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

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

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/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": "SSN",
      "document": "123456789",
      "countryCode": "US"
    }
  ],
  "occupation": "Software Engineer"
}'

Campos de la Solicitud

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

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

Solo se actualizan los campos incluidos en el cuerpo de la solicitud; los campos omitidos permanecen sin cambios.

curl --request PATCH \
  --url https://{FQDN}/organizations/$TENANT/people/$PERSON_ID \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "occupation": "Consultant",
  "documents": [
    {
      "type": "SSN",
      "document": "987654321",
      "countryCode": "US"
    }
  ]
}'

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
• Carga de Documentos — Envía documentos de identidad y de origen de fondos
• Datos de Prueba — Escenarios de prueba en sandbox para flujos de cumplimiento

Todos los Endpoints

Documentación Interactiva de la API