Clientes

Crea el cliente antes de construir un cobro, pago o cuenta bancaria emitida. Las capacidades, cuentas y transferencias están asociadas a ese cliente. Utiliza externalId como mapeo estable al registro correspondiente en tu sistema.

Environment variables

export API_BASE='https://platform.swipelux.com'
export SWIPELUX_API_KEY='replace-with-your-api-key'

Clientes individuales

Un individuo solo requiere type. Incluye los campos de perfil que ya conozcas y añade más solo cuando la capacidad o tarea actual los necesite. Crea el cliente con POST /v3/customers:

Create individual customer

curl --request POST \
  "${API_BASE}/v3/customers" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-user-123" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "type": "individual",
  "externalId": "user_123",
  "individual": {
    "firstName": "Amina",
    "lastName": "Diallo",
    "residenceCountry": "FR"
  }
}
JSON

Guarda el data.id devuelto como CUSTOMER_ID. Consulta Onboarding de individuos para el contexto de la política.

Clientes empresa

Una empresa requiere business.legalName. Crea la empresa con la misma operación:

Create business customer

curl --request POST \
  "${API_BASE}/v3/customers" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-company-456" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "type": "business",
  "externalId": "company_456",
  "business": {
    "legalName": "Acme Payments SAS"
  }
}
JSON

Guarda el data.id devuelto como CUSTOMER_ID. Consulta Onboarding de empresas para el contexto de política y documentos. Añade directores, propietarios y otros participantes de la empresa cuando sean conocidos o solicitados. Este ejemplo crea un director con POST /v3/customers/{customerId}/related-parties:

Add related party

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/related-parties" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: related-party-director-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "partyType": "person",
  "roles": ["director"],
  "title": "Chief executive officer",
  "person": {
    "firstName": "Amina",
    "lastName": "Diallo",
    "residenceCountry": "FR"
  }
}
JSON

Guarda el data.id devuelto como RELATED_PARTY_ID. Si necesitas exportar un cliente, usa POST /v3/customers/{customerId}/export y sigue el esquema de la solicitud. El formato json_basic_data devuelve el recurso de cliente público v3 actual como un adjunto JSON; cada llamada recalcula los datos actuales y excluye los documentos y sus metadatos. Para un formato de token de portabilidad, envía el ID de cliente del proyecto KYC receptor como forClientId, no el customerId de Swipelux. Usa el data.token devuelto antes de data.expiresAt. Reutilizar la misma Idempotency-Key y el mismo cuerpo reproduce ese resultado de token; usa una clave nueva para emitir otro token.

Lee la disponibilidad desde las capacidades

Un cliente no tiene un estado de verificación o disponibilidad en la API. Lee el cliente con GET /v3/customers/{customerId} para obtener los datos actuales del perfil, luego utiliza las capacidades y sus openTaskIds para decidir qué puede hacer el cliente a continuación.

Get customer

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}"

Encuentra clientes con documentos pendientes

Para saber qué clientes de una página aún deben documentos obligatorios, pasa include=documentRequirements a GET /v3/customers. Puedes combinarlo con los resúmenes de capacidades como include=capabilities,documentRequirements. Las claves de API necesitan accounts:read para la expansión documentRequirements. Cada resumen de cliente incluye entonces un objeto documentRequirements:

Document requirement summary

{
  "documentRequirements": {
    "required": true,
    "count": 2
  }
}

count es el número de requisitos de documentos obligatorios en action_required en tareas que también están en action_required. Abarca todos los ámbitos de tarea, incluidas las tareas de toda la cuenta, y no depende de la disponibilidad de las capacidades.
required es true cuando count es mayor que 0.
Un conjunto de alternativas cuenta una sola vez, y solo cuando todas las alternativas requieren un documento.

El resumen es conservador. Excluye los documentos opcionales, los documentos obligatorios de forma condicional y las alternativas que mezclan vías con documento y sin documento. También excluye los requisitos que el cliente puede completar mediante la verificación alojada. Por lo tanto, required: false no demuestra que no se aplique ninguna tarea de documentos. Úsalo para priorizar clientes y luego lee sus tareas para obtener la lista definitiva de lo que debes recopilar. Sin la expansión, la respuesta omite documentRequirements. A continuación, pasa a Capacidades y tareas para descubrir y activar el resultado de producto que necesites.

Comienza

Incorpora clientes

Crea flujos de dinero

Lanzamiento

Clientes individuales

Clientes empresa

Lee la disponibilidad desde las capacidades

Encuentra clientes con documentos pendientes

​Clientes individuales

​Clientes empresa

​Añade partes relacionadas de la empresa

​Lee la disponibilidad desde las capacidades

​Encuentra clientes con documentos pendientes

Clientes individuales

Clientes empresa

Añade partes relacionadas de la empresa

Lee la disponibilidad desde las capacidades

Encuentra clientes con documentos pendientes