Convenciones — Docs de kyc.ar

Reglas que valen para todos los endpoints de la API pública /v1.

URL base

https://api.kyc.ar

Toda la API es HTTPS. Los cuerpos son JSON (Content-Type: application/json), salvo dos excepciones explícitas: el QR devuelve imágenes y el export de uso devuelve CSV.

Autenticación

Authorization: Bearer sk_live_… o sk_test_… en cada request. Ver Autenticación.

La cuenta nunca viaja en el path, el query ni el body: se resuelve del lookup de la clave. Un id de otro tenant devuelve 404, no 403: la API no confirma la existencia de recursos ajenos.

Identificadores

Los ids públicos llevan prefijo, al estilo de Stripe. El sufijo es un ULID (ordenable por tiempo de creación) salvo el de evento, que es un hash.

Campo	Tipo	Ejemplo	Descripción
`prj_`	Proyecto	prj_01J9Z2K3M4N5P6Q7R8S9T0V1W2	Agrupa una configuración de verificación.
`cfg_`	Versión de config	cfg_00000003	Versión congelada del flujo. El sufijo es el número de versión, no un ULID.
`vs_`	Sesión	vs_01K2M4P6R8T0V2X4Z6B8D0F2H4	Sesión de verificación.
`whep_`	Webhook endpoint	whep_01K2M4P6R8T0V2X4Z6B8D0F2H4	Destino registrado para recibir eventos.
`evt_`	Evento	evt_7QK3M9ZP2X8V4T0R6B1D5F3H7J	Evento de webhook. Determinístico: el mismo evento lógico repite id en cada reintento y endpoint.
`key_`	API key	key_01K2M4P6R8T0V2X4Z6B8D0F2H4	Id público de una clave. El secreto es otra cosa y no se puede recuperar.

Fechas

Todos los timestamps son ISO 8601 en UTC con sufijo Z (2026-08-19T14:03:11.482Z). Las fechas del documento (nacimiento, vencimiento) son YYYY-MM-DD sin hora.

Paginación

Los listados devuelven páginas con cursor opaco:

{
  "data": [ /* … */ ],
  "has_more": true,
  "next_cursor": "eyJwayI6IlNFU1NJT04jdF8wMUsyIiwic2siOiJTIzIwMjYtMDgifQ"
}

Campo	Tipo	Requerido	Descripción
`limit`	integer	no	Entre 1 y 100. Por defecto 25.
`cursor`	string	no	El next_cursor de la página anterior, tal cual. Es opaco: no lo construyas ni lo interpretes.

next_cursor sólo aparece cuando has_more es true. Un cursor malformado devuelve 422.

Idempotencia

POST /v1/verification-sessions acepta el header Idempotency-Key (1 a 255 caracteres). Reintentar con la misma clave devuelve la respuesta original en vez de crear una segunda sesión.

-H "Idempotency-Key: alta-4821"

La clave se registra por cuenta + modo + API key, así que:

la misma Idempotency-Key en test y en live produce dos sesiones distintas (es el caso habitual cuando la clave es tu número de trámite y corrés el mismo caso en sandbox y en producción);
dos API keys de la misma cuenta tampoco colisionan entre sí.

Campo	Tipo	Descripción
`Misma clave, mismo payload`	201	Devuelve la respuesta guardada del primer request. No se crea otra sesión ni se debita otra vez.
`Misma clave, payload distinto`	409	`conflict`: “Idempotency-Key reutilizada con un payload distinto al original”. Es una salvaguarda: nunca se sirve la respuesta de otro request.
`Misma clave, request en curso`	409	`conflict`: hay otro request en vuelo con esa clave. Reintentá en unos segundos.

Los demás endpoints no usan Idempotency-Key: GET y DELETE son idempotentes por definición, PUT reemplaza los campos que mandes y el cancel es idempotente en el sentido útil (la segunda llamada devuelve 409 porque la sesión ya es terminal).

Errores

Todos los errores de aplicación son application/problem+json (RFC 7807), con un campo code estable:

{
  "type": "https://docs.kyc.ar/errores#validation_failed",
  "title": "validation_failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "project_id: el proyecto no existe"
}

Programá contra code, no contra detail ni contra el status: detail es para humanos y puede cambiar de redacción. La lista completa está en Errores.

La única excepción son los 403 de autorización, que emite el gateway como {"message":"Forbidden"}.

Límites de tasa

20 requests por segundo sostenidos, ráfagas de hasta 40, a nivel del stage de la API. Las operaciones que generan tráfico saliente (prueba y re-entrega de webhook) tienen además un cupo de 10 por minuto por cuenta.

CORS

La API pública sólo habilita CORS para el dashboard de kyc.ar y para desarrollo local. Es server-to-server por diseño: llamarla desde el navegador de tus usuarios expondría tu clave secreta.