API de ModoKYC

API REST para verificación de identidad. Autentica cada solicitud con el encabezado x-api-key (crea tus claves en el portal, en Claves API).

Tu saldo son créditos prepago (números enteros). Cada producto cobra un número fijo de créditos por sesión.

1. Consulta tus productos

curl https://kyc.modotu.com/api/v1/products -H "x-api-key: mk_live_..."
{ "data": [
  { "code": "kyc-full", "name": "...", "description": "...", "kind": "user", "credits": 2, "type": "session" },
  { "code": "aml-screening", "name": "...", "description": "...", "kind": "user", "credits": 2, "type": "check", "check_type": "aml" }
] }

type dice cómo se usa el producto: session abre una sesión de verificación con enlace y check es una consulta directa por API (ver Consultas), con check_type aml, col_cedula o face_match.

2. Crea una sesión de verificación

Los créditos del producto se reservan de tu saldo y se cobran cuando la sesión tiene decisión (Approved, Declined o In Review). Las sesiones abandonadas o vencidas se devuelven.

curl -X POST https://kyc.modotu.com/api/v1/sessions \
  -H "x-api-key: mk_live_..." -H "content-type: application/json" \
  -d '{"product":"kyc-full","reference":"user-42","callback":"https://yourapp.com/done","language":"es"}'

Respuesta 201: redirige a tu usuario a url, o ábrela en un iframe (allow="camera; microphone; fullscreen").

{
  "id": "clx...",
  "product": "kyc-full",
  "reference": "user-42",
  "status": "Not Started",
  "url": "https://verify...",
  "credits": 2,
  "billing_state": "held"
}

Campos opcionales: metadata (objeto que te devolvemos igual), contact_details, expected_details. Si repites una reference mientras su sesión no ha terminado, recibes la misma sesión.

Enviar el enlace por correo: con notify: true (opcional, por defecto false) ModoKYC le envía el enlace a contact_details.email por correo, en español, a nombre de tu empresa. Sin ese correo la respuesta es 422 notify requires contact_details.email; un valor que no sea booleano también es 422. El celular (contact_details.phone) se acepta, pero todavía no se envía nada por SMS ni WhatsApp. Si el envío falla, la sesión se crea igual y el correo se reintenta automáticamente.

curl -X POST https://kyc.modotu.com/api/v1/sessions \
  -H "x-api-key: mk_live_..." -H "content-type: application/json" \
  -d '{"product":"kyc-full","reference":"cred-77","notify":true,"contact_details":{"email":"juan@correo.com"}}'

Toda sesión trae notification: null si no pediste el envío, o el resultado del último correo. La dirección siempre va enmascarada; ModoKYC nunca devuelve el correo completo.

"notification": {
  "channel": "email",
  "status": "sent",
  "recipient": "j•••@correo.com",
  "sent_at": "...",
  "delivery_status": null,
  "resends": 0
}

status es pending, sent, failed (el proveedor lo rechazó o la dirección está suprimida por rebote o queja; se reintenta) o skipped (el correo no está configurado en ModoKYC: no se envió ni se reintentará). delivery_status es lo que reportó el servidor de correo: delivered, bounced, complained, rejected, delayed o null.

Reenviar el enlace: POST /api/v1/sessions/{id}/resend lo envía de nuevo al mismo correo y responde 200 con la sesión. Funciona mientras la sesión se puede completar (Not Started, In Progress, Resubmitted o Awaiting User), como máximo una vez cada 10 minutos y cinco veces por sesión. Respuestas: 404 not_found, 409 session_not_pending (la sesión terminó o venció: crea una nueva), 409 no_contact_email (la sesión no se creó con notify: true), 409 resend_too_soon, 409 resend_limit y 503 email_not_configured.

Si repites una reference con notify: true mientras su sesión sigue abierta, recibes la misma sesión y: si ya se envió el enlace a ese mismo correo, no se envía otro; si es un correo distinto, el enlace se envía de inmediato al nuevo correo y cuenta como un reenvío (sin esperar los 10 minutos), y desde ahí notification y los reenvíos usan el nuevo correo; si ya se usaron los cinco reenvíos, la respuesta es 409 resend_limit y no se envía nada; si la sesión se creó sin notify, se envía su primer correo.

curl -X POST https://kyc.modotu.com/api/v1/sessions/{id}/resend -H "x-api-key: mk_live_..."

Integra la verificación en tu app

La url de una sesión es una página alojada que maneja la cámara, la captura del documento y la prueba de vida. Todos los productos de identidad se usan igual (por ejemplo prueba-de-vida para frenar registros automáticos, o kyc-full para validar también el documento de identidad).

Redirección: envía callback al crear la sesión y redirige al usuario a url. Cuando termina, el navegador vuelve a tu callback con ?verificationSessionId=...&status=.... Toma esos parámetros solo como una pista.

Iframe: el usuario se queda en tu página.

<iframe src="{session.url}" style="width:100%;height:700px;border:0"
  allow="camera; microphone; fullscreen; autoplay; encrypted-media"></iframe>

Decide en tu servidor: nunca confíes en el navegador. Antes de dejar continuar al usuario, consulta la sesión con tu clave API (o espera el webhook) y exige que status sea Approved.

// Your backend, when the user submits the form
const res = await fetch("https://kyc.modotu.com/api/v1/sessions/" + sessionId, { headers: { "x-api-key": API_KEY } });
const session = await res.json();
if (session.status !== "Approved") return reject("Identity not verified");

Toda verificación terminada consume créditos, incluso las rechazadas. Limita cuántas sesiones puede abrir un mismo visitante o dirección IP antes de llamar a esta API.

3. Consulta los resultados

curl https://kyc.modotu.com/api/v1/sessions/{id} -H "x-api-key: mk_live_..."
curl "https://kyc.modotu.com/api/v1/sessions?limit=20&reference=user-42" -H "x-api-key: mk_live_..."
curl https://kyc.modotu.com/api/v1/balance -H "x-api-key: mk_live_..."

GET /api/v1/balance devuelve los créditos disponibles, ya descontados los reservados por sesiones abiertas:

{ "credits": 98 }

Documentos para firma

Un documento para firma (sobre) es un PDF o un archivo de Word (.docx) y de 1 a 10 firmantes. Cada firmante recibe su propio enlace de firma sobre el mismo PDF. El flujo es:

  1. Creas el sobre con POST /api/v1/envelopes. Se envía en el mismo paso y la respuesta trae el signing_url de cada firmante.
  2. Compartes cada enlace con su firmante (ModoKYC todavía no envía correos).
  3. Sigues el avance con los webhooks envelope.* o consultando GET /api/v1/envelopes/{id}.
  4. Cuando un firmante firma, descargas su copia firmada y su evidencia.
  5. Cuando todos firmaron, descargas el documento final con el anexo probatorio.

Niveles: otp (el firmante confirma su correo con un código) y biometric (además valida su documento de identidad y una selfie). Cada firmante cobra los créditos de su nivel (consúltalos en GET /api/v1/products: firma-otp y firma-biometrica). Al crear el sobre necesitas créditos para todos los firmantes; si ordered es true, cada firmante recibe su enlace solo cuando el anterior firmó, y sus créditos se reservan en ese momento.

curl -X POST https://kyc.modotu.com/api/v1/envelopes \
  -H "x-api-key: mk_live_..." -H "content-type: application/json" \
  -H "Idempotency-Key: contrato-77-v1" \
  -d '{
    "title": "Contrato de crédito 77",
    "reference": "credito-77",
    "metadata": { "loan_id": 77 },
    "ordered": false,
    "notify": true,
    "document": { "file_name": "contrato.pdf", "content_base64": "JVBERi0xLjcK..." },
    "signers": [
      { "name": "Ana Pérez", "email": "ana@example.com", "phone": "+573001112233", "level": "otp" },
      { "name": "Luis Gómez", "email": "luis@example.com", "level": "biometric", "document_number": "1020304050", "signature_anchor": "Firma del deudor" }
    ]
  }'

El archivo va en base64 dentro de content_base64. Límites: PDF o Word (.docx) de máximo 10 MB, 100 páginas y sin contraseña; la solicitud completa puede pesar máximo 15 MB. Un Word se convierte a PDF en el servidor; el PDF resultante es el documento que se firma. El encabezado Idempotency-Key es obligatorio (ver Idempotencia).

notify (opcional, por defecto true): si el envío de correos está configurado, ModoKYC le manda a cada firmante su invitación para firmar por correo, al enviar el sobre y cuando le llega el turno en un sobre con ordered. Usa false si tú entregas los enlaces. Cualquier valor que no sea booleano responde 422 invalid_request.

document_number (opcional, solo nivel biometric): el número del documento que esperas que muestre ese firmante. Se ignoran espacios, puntos y guiones; deben quedar de 4 a 20 letras o dígitos. Si el documento que presenta la persona tiene otro número, la verificación de identidad se rechaza y la persona no puede firmar: el firmante queda declined con error "El número de documento no coincide con el esperado". Con nivel otp responde 422 invalid_request, porque ese nivel no lee ningún documento. Sin este campo no se compara nada.

signature_anchor (opcional, cualquier nivel): un texto del documento, de 1 a 64 caracteres, como "Firma del deudor". La firma de esa persona se estampa justo encima de la primera aparición de ese texto, en su copia firmada. Si el texto no está en el documento (por ejemplo un PDF escaneado sin texto), no se puede crear la sesión de firma: el firmante queda failed con error "El texto de anclaje de la firma no aparece en el documento". Sin este campo la firma aparece solo en la hoja de evidencia que se agrega al final. En el documento final de ModoKYC cada firma ubicada así se reproduce en el mismo lugar de la página (ver "Documento final con anexo probatorio").

Respuesta 201:

{
  "id": "clx...",
  "title": "Contrato de crédito 77",
  "reference": "credito-77",
  "metadata": { "loan_id": 77 },
  "status": "sent",
  "ordered": false,
  "pages": 3,
  "sha256": "hash del PDF que se firma",
  "uploaded_sha256": "hash del archivo que subiste",
  "source_format": "pdf",
  "credits": 4,
  "created_at": "...", "sent_at": "...", "completed_at": null,
  "cancelled_at": null, "cancel_reason": null,
  "final_document_sha256": null,
  "has_final_document": false,
  "verification_url": "https://kyc.modotu.com/verificar/clx...",
  "environment": "live",
  "signers": [
    {
      "id": "cly...",
      "name": "Ana Pérez", "email": "ana@example.com", "phone": "+573001112233",
      "level": "otp", "position": 1, "status": "sent",
      "signing_url": "https://verify...",
      "credits": 1,
      "signed_at": null, "signed_document_sha256": null,
      "has_signed_document": false, "has_evidence": false,
      "last_notification": { "kind": "invitation", "channel": "email", "status": "sent", "sent_at": "..." },
      "error": null
    }
  ]
}

credits del sobre es la suma de los créditos de sus firmantes. source_format es pdf o docx. error explica por qué un firmante no recibió su enlace o por qué falta un archivo.

last_notification es el último mensaje que ModoKYC le envió a ese firmante: kind (invitation o reminder), channel (email o whatsapp), status (pending, sent o failed) y sent_at. Nunca incluye la dirección de destino. Vale null si no se envió nada, por ejemplo cuando el correo no está configurado o el sobre se creó con notify: false.

final_document_sha256 es la huella SHA-256 del documento final y vale null hasta que se genera; has_final_document dice si ya está guardado. verification_url es la página pública de verificación del sobre: existe desde que lo creas y puedes compartirla.

environment vale live o test. Es test cuando alguna sesión de firma corrió en el modo de prueba del proveedor de verificación (o, antes de que llegue el primer resultado, cuando ModoKYC usa una clave de prueba). En modo de prueba el proveedor simula todos los resultados de identidad sin importar lo que capture la persona: el tipo y número de documento, los nombres, los puntajes y las aprobaciones son datos de muestra que no corresponden a los firmantes. Un sobre test no tiene validez: el anexo probatorio, la página de verificación y el portal lo marcan como "Documento de prueba, sin validez". Los webhooks envelope.* llevan el mismo campo.

Estados del sobre (status):

  • sent: enviado, faltan firmas.
  • completed: todos firmaron.
  • declined: un firmante rechazó la firma o no se le pudo enviar, y nadie más puede firmar.
  • expired: un enlace venció o se abandonó, y nadie más puede firmar.
  • cancelled: lo anulaste; cancelled_at y cancel_reason dicen cuándo y por qué.

Estados del firmante:

  • pending: espera su turno (sobres con ordered).
  • sent: su enlace está listo.
  • in_progress: está firmando.
  • signed: firmó.
  • declined: rechazó la firma.
  • expired: su enlace venció o lo abandonó.
  • failed: no se le pudo enviar el enlace; mira error. No se cobró.
  • cancelled: el sobre se anuló antes de que firmara; su enlace ya no funciona y no se cobró.

Consulta y descargas:

curl https://kyc.modotu.com/api/v1/envelopes/{id} -H "x-api-key: mk_live_..."
curl "https://kyc.modotu.com/api/v1/envelopes?limit=20&reference=credito-77" -H "x-api-key: mk_live_..."
curl -o contrato.pdf https://kyc.modotu.com/api/v1/envelopes/{id}/document -H "x-api-key: mk_live_..."
curl -o firmado.pdf https://kyc.modotu.com/api/v1/envelopes/{id}/signers/{signerId}/signed-document -H "x-api-key: mk_live_..."
curl -o evidencia.pdf https://kyc.modotu.com/api/v1/envelopes/{id}/signers/{signerId}/evidence -H "x-api-key: mk_live_..."

La lista se pagina igual que las sesiones: limit (1 a 100, por defecto 20) y cursor con el next_cursor de la página anterior. Las descargas responden el PDF (application/pdf) como adjunto. document es el PDF que firma cada persona; la copia firmada y la evidencia responden 404 not_ready hasta que el firmante firma y el archivo se guarda (mira has_signed_document y has_evidence). Cada firmante firma su propia copia del mismo PDF.

Anular un sobre pendiente

Un sobre sent se puede anular, con un motivo opcional de hasta 500 caracteres. El cuerpo es opcional; no requiere Idempotency-Key porque repetir la anulación es seguro.

curl -X POST https://kyc.modotu.com/api/v1/envelopes/{id}/cancel \
  -H "x-api-key: mk_live_..." -H "content-type: application/json" \
  -d '{ "reason": "El cliente desistió del crédito" }'

Cada firmante que no ha firmado queda cancelled: su enlace deja de funcionar y se devuelven sus créditos reservados. Quien ya firmó conserva su firma y su cobro. El sobre anulado nunca se completa ni tiene documento final, aunque llegue una firma tardía. Se envía una sola vez el webhook envelope.cancelled. Si no se pudo cerrar la sesión de firma en el proveedor, el firmante muestra en error "No se pudo cerrar la sesión de firma con el proveedor de verificación": vuelve a llamar este endpoint para reintentarlo.

  • 200: el sobre anulado, también si ya estaba anulado (no cambia nada más ni envía otro webhook).
  • 404 not_found: el sobre no existe o no es de tu cuenta.
  • 409 envelope_not_cancellable: el sobre ya no está pendiente (completed, declined o expired); el mensaje dice su estado.
  • 422 invalid_request: el motivo no es texto, pasa de 500 caracteres o tiene caracteres de control.

Documento final con anexo probatorio

Cuando todos firmaron, ModoKYC genera un único PDF: el documento que firmó cada persona seguido de las páginas del "Anexo probatorio de firma electrónica", en español. Si un firmante tiene la firma ubicada en una página (con signature_anchor), la imagen de su firma se dibuja en esa página, dentro del recuadro que registró el proveedor, sin deformarla; el anexo lo aclara. El documento enviado a firmar y su SHA-256 no cambian. Sin firmas ubicadas el documento final es igual que antes.

curl -o final.pdf https://kyc.modotu.com/api/v1/envelopes/{id}/final-document -H "x-api-key: mk_live_..."
  • 200: el PDF como adjunto (Cache-Control: no-store). Su SHA-256 es final_document_sha256.
  • 404 not_ready: todavía no firmaron todos.
  • 404 not_found: el sobre no existe o no es de tu cuenta.
  • 503 final_document_unavailable: no se pudo generar todavía (por ejemplo, faltan fotos o la imagen de una firma del proveedor). Reintenta después de los segundos de Retry-After (hoy 30): cada descarga vuelve a intentarlo.

El anexo contiene:

  • Datos del documento: título, identificador, páginas, huellas SHA-256 del documento enviado a firmar y del archivo subido, y sus fechas.
  • Por firmante: nombre, correo, nivel, fecha de firma, IP y su ubicación aproximada, dispositivo, consentimiento, código de un solo uso (con el destino enmascarado) y la huella de su copia firmada.
  • En la firma biométrica: tipo de documento, número enmascarado, resultados de documento, prueba de vida y comparación facial, y tres fotos.
  • La línea de tiempo de cada cambio de estado, y un código QR con la página de verificación.

El documento final todavía no lleva un sello digital propio: su integridad se comprueba con su SHA-256 en la página de verificación.

Página pública de verificación

verification_url (/verificar/{id}) abre sin iniciar sesión y no se indexa en buscadores. Muestra el estado, las páginas, las fechas de creación y de cierre, la huella del documento enviado a firmar y, cuando existe, la del documento final, y cada firmante solo con sus iniciales, su nivel y su fecha de firma. No muestra el título, nombres, correos, teléfonos, IP, fotos ni archivos. Quien tenga un PDF puede elegirlo en esa página y comprobar si coincide: la huella se calcula en su navegador y el archivo no se sube.

Consultas por API

Una consulta es una llamada directa de tu servidor, sin enlace ni intervención de la persona: screening AML, validación de una cédula colombiana contra el registro oficial o comparación de dos fotos de rostro. La respuesta llega en la misma solicitud (puede tardar hasta 20 segundos). Las tres rutas exigen x-api-key y el encabezado Idempotency-Key (ver Idempotencia).

Qué se cobra y cuándo: los créditos del producto se reservan antes de consultar y se cobran cuando el proveedor responde, también si la respuesta es "sin coincidencias", "no coincide" o "no encontrado", porque esa respuesta también se paga. Si el proveedor falla, rechaza la solicitud, no responde en 20 segundos o no da una respuesta concluyente, los créditos se devuelven, la consulta queda failed y recibes 502 upstream_error: no se cobra nada y puedes reintentar con la misma Idempotency-Key.

Si el proveedor nunca respondió: si una consulta sigue en pending con los créditos reservados más de 2 minutos (por ejemplo porque se cayó el servidor durante la llamada), ModoKYC devuelve los créditos y la marca failed, con result.failure_reason = "The provider did not answer; the check was not charged". El proveedor no permite recuperar después el resultado de una consulta suelta, así que no se cobra nada. Esto ocurre al consultar o listar tus consultas y en una tarea periódica. Mientras una consulta sigue pending, reintentar con la misma Idempotency-Key responde 409 idempotency_in_progress; cuando queda failed, el siguiente reintento con esa llave vuelve a ejecutar la consulta.

Reintentos y el proveedor: la llave de idempotencia que ModoKYC envía al proveedor se deriva de tu cuenta y de tu Idempotency-Key (un hash de ambas; nunca se envía el identificador de tu cuenta). Si reintentas con la misma llave después de un corte, el proveedor recibe la misma llave y no ejecuta ni cobra la consulta dos veces.

Fechas: date_of_birth y date_of_issue deben ser fechas reales en formato AAAA-MM-DD, no anteriores al 1900-01-01 ni posteriores a hoy (fecha UTC). Si envías ambas, la fecha de expedición no puede ser anterior a la de nacimiento. Si no se cumple, recibes 422 invalid_request y no se cobra nada.

Screening AML

Busca a una persona o empresa en listas de sanciones, PEP y listas de vigilancia. Solo full_name es obligatorio (mínimo 2 caracteres); entity_type es person (por defecto) o company, date_of_birth va como AAAA-MM-DD y nationality es el código de país de 2 letras.

curl -X POST https://kyc.modotu.com/api/v1/checks/aml \
  -H "x-api-key: mk_live_..." -H "content-type: application/json" -H "Idempotency-Key: aml-user-42-1" \
  -d '{"full_name":"Ana Pérez","date_of_birth":"1990-01-15","nationality":"CO","document_number":"1020304050","reference":"user-42"}'

result: status (approved, in_review o declined), total_hits y hasta 20 hits, cada uno con name, match_score (0 a 100), categories (por ejemplo PEP o Sanctions) y country.

Cédula colombiana

Valida la cédula contra el registro oficial. Obligatorios: document_number (solo dígitos, de 6 a 10, el rango válido para la cédula colombiana) y date_of_issue (fecha de expedición, AAAA-MM-DD). Opcionales: first_name y last_name para compararlos.

curl -X POST https://kyc.modotu.com/api/v1/checks/colombia-cedula \
  -H "x-api-key: mk_live_..." -H "content-type: application/json" -H "Idempotency-Key: cedula-user-42-1" \
  -d '{"document_number":"1020304050","date_of_issue":"2010-05-20","first_name":"Ana","last_name":"Pérez"}'

result: status, match_type (full_match, partial_match o no_match), outcome (por ejemplo match, no_match o document_not_found), fields con el resultado de cada campo comparado y document_number_last4. ModoKYC no guarda el número completo ni los datos del registro.

Comparación facial

Compara dos fotos de rostro: user_image (por ejemplo una selfie) y ref_image (por ejemplo la foto del documento), en base64, JPEG o PNG, máximo 5 MB cada una; la solicitud completa puede pesar hasta 15 MB. Cada imagen debe estar completa y terminar en su marca de fin (FFD9 en JPEG, el bloque IEND en PNG) sin ningún byte después; si no, recibes 422 invalid_request y no se cobra nada. Las imágenes no se guardan: se usan solo durante la consulta.

curl -X POST https://kyc.modotu.com/api/v1/checks/face-match \
  -H "x-api-key: mk_live_..." -H "content-type: application/json" -H "Idempotency-Key: face-user-42-1" \
  -d '{"user_image":"<base64>","ref_image":"<base64>","reference":"user-42"}'

result: status (approved o declined) y score (0 a 100, o null si no se encontró un rostro que comparar).

Respuesta y consulta posterior

Respuesta 201 (la misma forma devuelven GET /api/v1/checks/{id} y la lista):

{
  "id": "clz...",
  "type": "aml",
  "reference": "user-42",
  "metadata": null,
  "status": "completed",
  "result": { "status": "approved", "total_hits": 0, "hits": [] },
  "credits": 2,
  "billing_state": "captured",
  "environment": "live",
  "created_at": "2026-06-11T10:21:07.013Z"
}
curl https://kyc.modotu.com/api/v1/checks/{id} -H "x-api-key: mk_live_..."
curl "https://kyc.modotu.com/api/v1/checks?type=aml&reference=user-42&limit=20" -H "x-api-key: mk_live_..."

type en la lista es aml, col_cedula o face_match; la paginación usa cursor con el next_cursor de la página anterior. reference y metadata son tuyos y nunca se envían al proveedor.

Modo de prueba: cuando environment es test, la consulta se hizo en el modo de prueba del proveedor y todos los resultados son simulados (por ejemplo AML siempre sin coincidencias, la cédula siempre coincide y la comparación facial siempre aprueba), sin importar los datos o las fotos que envíes. No envíes datos ni fotos reales en modo de prueba.

Idempotencia: reintentos seguros

Envía el encabezado Idempotency-Key para poder repetir una solicitud sin crear nada dos veces, por ejemplo si se cortó la conexión antes de recibir la respuesta. Es obligatorio en POST /api/v1/envelopes y opcional en POST /api/v1/sessions. Usa un valor único por operación (de 1 a 255 caracteres ASCII visibles, sin espacios), por ejemplo un UUID o contrato-77-v1. También es obligatorio en las tres consultas (POST /api/v1/checks/...).

  • La llave vale para tu cuenta durante 24 horas.
  • Misma llave y misma solicitud: recibes la respuesta guardada (mismo estado y mismo cuerpo) con el encabezado Idempotent-Replayed: true, y no se crea ni se cobra nada más. El orden de los campos del JSON no importa.
  • Misma llave con otra solicitud (otro cuerpo u otra ruta): 422 idempotency_key_reused.
  • Misma llave mientras la primera solicitud sigue en curso: 409 idempotency_in_progress. Espera y reintenta.
  • Se guardan las respuestas 2xx y 4xx (por ejemplo un 422 o un 402): para corregirlas usa una llave nueva. Un 5xx no se guarda: reintenta con la misma llave.

4. Webhooks

Configura tu URL en el portal, en Webhooks. Cada cambio de estado de una verificación envía un POST con un evento session.updated:

{ "id": "evt uuid", "type": "session.updated", "created_at": "...", "data": { ...session } }

Los documentos para firma envían estos eventos, con el sobre completo en data:

  • envelope.signer.updated: cambió el estado de un firmante; signer_id dice cuál.
  • envelope.completed: todos firmaron.
  • envelope.declined: el sobre quedó rechazado.
  • envelope.expired: el sobre quedó vencido.
  • envelope.cancelled: anulaste el sobre (una sola vez, aunque repitas la anulación).
{ "id": "evt uuid", "type": "envelope.signer.updated", "created_at": "...", "signer_id": "cly...", "data": { ...envelope } }

Las sesiones de firma de un sobre ya no envían session.updated: los eventos envelope.* los reemplazan. No se envían eventos al crear el sobre (la respuesta 201 ya trae su estado), ni cuando un aviso repetido no cambia nada.

Verifica la firma antes de confiar en el evento:

const expected = crypto.createHmac("sha256", WEBHOOK_SECRET)
  .update(`${req.headers["x-modokyc-timestamp"]}.${rawBody}`)
  .digest("hex");
// compare with req.headers["x-modokyc-signature"] using a constant-time comparison,
// and reject timestamps older than 5 minutes.

Los eventos pueden llegar más de una vez o en desorden: usa data.id + data.status como llave, o vuelve a consultar la sesión o el sobre.

Errores

Los errores responden { "error": { "code", "message", "details?" } }. El texto de message está en inglés.

Tu integración debe decidir solo con el estado HTTP, error.code y los nombres de los campos en details. El texto de message y de los mensajes dentro de details es informativo y puede cambiar entre versiones: no lo compares ni lo interpretes.

  • 400 idempotency_key_required / idempotency_key_invalid: falta el encabezado Idempotency-Key o no tiene de 1 a 255 caracteres ASCII visibles.
  • 400 invalid_json: el cuerpo no es JSON.
  • 401 unauthorized: falta la clave API o no es válida.
  • 402 insufficient_balance: no tienes créditos suficientes, por ejemplo Insufficient credits: 1 available, 2 required. Compra más créditos.
  • 403 tenant_suspended: la cuenta está suspendida.
  • 404 product_not_found / not_found: el producto, la sesión, el sobre o el firmante no existen.
  • 404 not_ready: la copia firmada, la evidencia o el documento final todavía no existen.
  • 409 idempotency_in_progress: la primera solicitud con esa Idempotency-Key sigue en curso.
  • 409 envelope_not_cancellable: el sobre que intentas anular ya no está pendiente.
  • 409 session_not_pending / no_contact_email / resend_too_soon / resend_limit: no se puede reenviar el enlace de esa sesión (ver Crea una sesión de verificación).
  • 413 payload_too_large: la solicitud pesa más de 15 MB.
  • 422 invalid_request: revisa message y details (por ejemplo un PDF dañado, un base64 inválido o un correo repetido).
  • 422 idempotency_key_reused: esa Idempotency-Key ya se usó con otra solicitud.
  • 502 upstream_error: el proveedor de verificación rechazó o no atendió la solicitud (en una consulta, también si no respondió en 20 segundos o no dio una respuesta concluyente); no se cobró nada.
  • 503 final_document_unavailable: el documento final no se pudo generar todavía; reintenta después de Retry-After (hoy 30 segundos).
  • 503 email_not_configured: el envío de correos no está configurado en ModoKYC; comparte el enlace tú.
  • 503 service_busy: el servicio está ocupado y no se creó nada ni se reservaron créditos. Reintenta después de los segundos que indica el encabezado Retry-After (hoy 2) y espera cada vez más entre intentos.