Dar de alta un usuario

POST/v1/partner/usersusers:write

Da de alta un usuario final del partner. El usuario nace PARTNER_MANAGED y no accede a la app. Exige Idempotency-Key.

Propósito

Registra a una persona como usuario final de tu integración. Este usuario será el titular de una wallet y el destinatario de los cobros que generes con links de pago.

Flujo recomendado de integración

Crea el usuario → este endpoint
Crea su wallet de cobro → POST /wallets
Genera links de pago → POST /payment-links
Comparte el link con el pagador

Campos del request

Campo	Tipo	Requerido	Descripción
`email`	string	✅	Correo electrónico del usuario. Debe ser único en SLAN.
`firstName`	string	❌	Nombre(s) de pila. Aparece en recibos de pago.
`lastName`	string	❌	Apellido(s). Aparece en recibos de pago.
`externalRef`	string	❌	Tu identificador interno para este usuario. Único por partner. Recomendado para reconciliar sin guardar nuestro ULID.

Comportamiento especial

Idempotencia con externalRef: si envías un externalRef que ya existe para tu partner, te devolvemos el usuario existente en lugar de crear uno nuevo.
Correo duplicado: si el correo ya pertenece a un usuario de SLAN (con app, KYC, tarjetas), se rechaza con 409. No se vinculan cuentas por seguridad.

Errores comunes

Código	Error	Causa	Solución
`400`	`IDEMPOTENCY_KEY_REQUIRED`	Falta el header `Idempotency-Key`	Agrega un UUID v4 como header
`400`	`VALIDATION_ERROR`	Campo inválido (ej: email mal formado)	Revisa el array `errors[]`
`409`	`PARTNER_END_USER_EMAIL_TAKEN`	El correo ya existe en SLAN	Usa otro correo o contacta soporte
`500`	`INTERNAL_SERVER_ERROR`	Error inesperado	Reintenta. Si persiste, reporta el `requestId` a soporte

Cabeceras

Idempotency-Keyrequerida: Clave única de la intención, 8-128 caracteres (un UUID v4 sirve). Se genera UNA vez por intención del usuario y se reutiliza en cada reintento: mismo cuerpo ⇒ misma respuesta con `Idempotent-Replayed: true`, sin repetir el efecto. La respuesta se guarda 24 h.

Cuerpo de la petición

emailstringrequerido
Ejemplo: "ana.ramirez@example.com"
externalRefstringopcional
Ejemplo: "tripto-user-4821"
firstNamestringopcional
Ejemplo: "Ana"
lastNamestringopcional
Ejemplo: "Ramírez"

Respuesta 201

Nace PARTNER_MANAGED y activo; el ULID es el que se usa para pedirle la wallet

createdAtstring
Ejemplo: "2026-09-04T15:04:05.000Z"
emailstring
Ejemplo: "ana.ramirez@example.com"
externalRefstringpuede venir null
admite null
Ejemplo: "tripto-user-4821"
firstNamestringpuede venir null
admite null
Ejemplo: "Ana"
isActiveboolean
Ejemplo: true
lastNamestringpuede venir null
admite null
Ejemplo: "Ramírez"
publicIdstring
Ejemplo: "01JKX7PEND0000000000000036"
statusstring
Ejemplo: "PARTNER_MANAGED"

Errores

Estado	Códigos	Cuándo
`400`	`IDEMPOTENCY_KEY_REQUIRED`	Falta la cabecera `Idempotency-Key` o no mide entre 8 y 128 caracteres
`401`	sin code	Sin x-api-key válida
`403`	sin code	La llave no tiene el scope users:write
`409`	`IDEMPOTENCY_IN_FLIGHTPARTNER_END_USER_EMAIL_TAKEN`	El correo ya pertenece a una cuenta del core; no se vincula Hay una petición en curso con esa misma clave: espera y reintenta
`422`	`IDEMPOTENCY_PAYLOAD_MISMATCHIDEMPOTENCY_ROUTE_MISMATCH`	La clave ya se usó con OTRO cuerpo o en OTRA ruta: genera una nueva
`429`	`RATE_LIMITED`	Limite de uso: 60 por minuto por credencial. Respeta la cabecera `Retry-After`.
`500`	sin code	Error interno inesperado. Reintenta la petición. Si persiste, reporta el `requestId` de la respuesta al equipo de soporte.