Remitente

El Remitente es el participante que inicia y paga una transacción. Todo remitente debe pasar por una verificación KYC (Know Your Customer), y sus límites de transacción se determinan según su nivel de cumplimiento.

Configuración Inicial de Cumplimiento

Al inicio de tu integración, el equipo de cumplimiento de Inyo trabaja con tu organización para definir un marco de cumplimiento personalizado, adaptado a tu producto y al perfil de tus clientes. Este marco determina:

• Niveles de cumplimiento — niveles que definen cuánto puede enviar un cliente dentro de períodos establecidos (24h, 30d, 180d)
• Reglas de validación — los datos y documentos requeridos para cada nivel (p. ej., nombre, SSN, comprobante de ingresos)
• Controles de riesgo — umbrales que activan la debida diligencia reforzada

Esta configuración es única por tenant e impacta directamente en cómo se verifican los participantes y qué operaciones pueden realizar.

Crear un Remitente (v2 — Recomendado)

Endpoint: POST /organizations/{tenant}/v2/people
Autenticación: Nivel de tenant (x-api-key)

⚠️ El endpoint v1 POST /organizations/{tenant}/people está obsoleto. Usa v2 — acepta el mismo payload y agrega validación y verificación de documentos integradas con la solución KYC.

El endpoint v2 acepta la misma estructura de solicitud que v1 (vea las tablas de campos abajo), más un campo adicional por documento — documents[].stateCode (estado/provincia emisor, máx. 32 caracteres) — y aplica un pipeline más estricto y seguro:

• Validación de documentos basada en reglas — por país + tipo de documento, reglas configuradas por tenant pueden exigir campos adicionales (p. ej., stateCode para licencias de conducir de EE. UU.) y aplicar regex de formato. Las violaciones devuelven 422 VALIDATION_ERROR con errores por campo bajo errors["documents.{i}.{field}"], y nada se persiste.
• Verificación sincrónica de número KYC — donde la regla lo exige, el número de documento se verifica contra el servicio KYC Inyo360 durante la solicitud. Un rechazo de KYC devuelve 422 con el detalle; si el servicio KYC no está disponible, la solicitud falla de forma segura con 502 KYC_UPSTREAM_ERROR (reintente).
• Veredictos de verificación registrados — los documentos verificados llevan kyc_verdict/kyc_verified_at en los registros de documentos de la persona.
• Misma idempotencia que v1: si existe una persona con el mismo externalId, se devuelve la persona existente con 200; una persona nueva devuelve 201.

Técnicamente, ningún campo es requerido para crear una persona — pero para usarla como remitente, debe alcanzar al menos el Nivel de Cumplimiento 1, que normalmente requiere nombre, apellido, dirección y número de teléfono.

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/v2/people \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "birthDate": "1990-01-15",
  "phoneNumber": "+15551234567",
  "gender": "Male",
  "externalId": "your-internal-id-001",
  "address": {
    "countryCode": "US",
    "stateCode": "CA",
    "city": "San Francisco",
    "line1": "123 Market St",
    "zipcode": "94105"
  },
  "documents": [
    {
      "type": "drivers_license",
      "document": "D12345678",
      "countryCode": "US",
      "stateCode": "CA",
      "expireDate": "2030-06-30"
    }
  ],
  "occupation": "Software Engineer"
}'

Campos de la Solicitud

Tipos de Documento Aceptados

En los endpoints v2, documents[].type usa valores en minúsculas, siguiendo el mismo estándar que la solución KYC:

Observa el plural drivers_license — v2 corrige el singular DRIVER_LICENSE de v1 para alinearse con el estándar KYC. Para una migración sin fricciones, v2 también acepta los valores heredados en mayúsculas de v1 y el singular driver_license (todos comparados sin distinción de mayúsculas y normalizados), pero las nuevas integraciones deben enviar los valores en minúsculas.

Estos son números de documento declarados — para enviar imágenes de documentos para verificación, use los endpoints de carga de documentos.

ⓘ El obsoleto v1 PATCH /people/{personId} acepta un conjunto más limitado para documents[].type (PASSPORT, DRIVER_LICENSE, DNI, CC, CPF, ID, SSN, ITIN) y restringe documents[].countryCode a US, BR, CO, PE, KE. El v2 PATCH /v2/people/{personId} no tiene esa restricción — sus reglas de documentos son idénticas a las de creación v2.

Respuesta de Ejemplo

{
  "id": "48066496-9445-41b7-acbe-85e069a77cb7",
  "firstName": "John",
  "lastName": "Doe",
  "mainAddressId": "9c2ea7e5-51a2-4ea1-83cf-8948754486f8",
  "phoneNumber": "+15551234567",
  "email": "[email protected]",
  "gender": "Male",
  "birthDate": "1990-01-15",
  "externalId": "your-internal-id-001",
  "updatedAt": "2025-01-15T12:00:00",
  "documents": [],
  "occupation": "Software Engineer",
  "documentId": null,
  "sourceOfFundsId": null,
  "employerName": null,
  "employerAddressId": null
}

Guarda el id devuelto — este es el senderId que se usa en todas las llamadas posteriores a la API.

Notas de comportamiento:

• Idempotente sobre externalId — si ya existe una persona con el mismo externalId en tu tenant, POST /people devuelve la persona existente en lugar de crear un duplicado.
• Los remitentes deben ser mayores de 18 años — birthDate se rechaza si la persona fuera menor de 18.
• Los documentos son de solo inserción (append-only) — actualizar los documentos de una persona inserta nuevos registros y retira los antiguos, preservando el rastro de auditoría de cumplimiento.

Actualizar un Remitente (v2 — Recomendado)

Endpoint: PATCH /organizations/{tenant}/v2/people/{personId}
Autenticación: Nivel de tenant

⚠️ El endpoint v1 PATCH /organizations/{tenant}/people/{personId} está obsoleto. La actualización v2 aplica la misma validación basada en reglas y verificación sincrónica de número KYC que la creación v2, y sus reglas de documentos son idénticas a las de creación (la actualización v1 aceptaba un conjunto más limitado de documentos).

Solo se actualizan los campos incluidos en el cuerpo de la solicitud; los campos omitidos permanecen sin cambios. Los documentos son aditivos — cada actualización agrega nuevos registros de documentos y el historial permanece visible.

curl --request PATCH \
  --url https://{FQDN}/organizations/$TENANT/v2/people/$PERSON_ID \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "occupation": "Consultant",
  "documents": [
    {
      "type": "drivers_license",
      "document": "D87654321",
      "countryCode": "US",
      "stateCode": "CA",
      "expireDate": "2031-01-31"
    }
  ]
}'

Verificación de Direcciones

Usa el endpoint de verificación de direcciones para pre-validar una dirección antes de crear o actualizar un remitente. Aplica las mismas reglas de validación específicas por país (incluidos los formatos de código postal por país) que los endpoints reales de guardado, por lo que si la verificación pasa aquí, la dirección será aceptada en POST /people.

curl --request GET \
  --url "https://{FQDN}/organizations/$TENANT/addresses/check?countryCode=US&stateCode=CA&city=San+Francisco&line1=123+Market+St&zipcode=94105" \
  --header "x-api-key: $API_KEY"

Parámetros de consulta: line1, city, stateCode y countryCode son requeridos; zipcode se valida contra las reglas de formato del país de destino.

Crear Remitentes Empresariales (KYB)

Para casos de uso B2B, puedes crear una empresa como remitente:

Endpoint: POST /organizations/{tenant}/companies
Autenticación: Nivel de tenant

Las empresas siguen un sistema de niveles de cumplimiento similar, pero con campos requeridos diferentes (registro mercantil, EIN, etc.). Contacta a tu gerente de cuenta de Inyo para la configuración KYB específica de tu tenant.

Niveles de Cumplimiento

Estos son personalizables por tenant. Ver Límites por Nivel de Confianza para más detalles.

Mejores Prácticas

• Onboarding progresivo — Recopila solo los campos del Nivel 1 al registrarse. Solicita más datos cuando el usuario necesite límites más altos.
• Pre-valida las direcciones — Usa el endpoint de verificación de direcciones antes de crear el remitente para evitar retenciones.
• Sincroniza el estado de cumplimiento — Después de actualizar el perfil, vuelve a verificar el nivel de cumplimiento para ver si se ha elevado.
• Maneja usuarios restringidos — Si un remitente está Restricted, consulta GET /participants/{id}/complianceLevels para entender por qué y qué acción se necesita.

Páginas Relacionadas

• Límites por Nivel de Confianza — Verifica y eleva los niveles de cumplimiento
• Verificación de Documentos — Sesiones de verificación KYC y verificación de documentos
• Datos de Prueba — Escenarios de prueba en sandbox para flujos de cumplimiento

Todos los Endpoints