Guía de inicio

Esta guía va de cero a una verificación completa. Todos los curl son reales y todas las respuestas son el shape exacto que devuelve la API.

1. Crear la cuenta

El alta se hace en el dashboard: app.kyc.ar. Al registrarte creás tu organización y quedás como owner.

La cuenta nace en estado pendiente de aprobación y la habilita una persona de nuestro lado. Es un requisito del producto: verificamos identidad de terceros y no abrimos la API a cuentas anónimas.

2. Crear un proyecto y publicar un flujo

Un proyecto agrupa una configuración de verificación: qué pasos corre, en qué orden y con qué parámetros. Cada vez que publicás la configuración se congela una versión (cfg_00000003), y cada sesión queda atada a la versión vigente al momento de crearse: cambiar el flujo mañana no altera las sesiones de hoy.

Un proyecto tiene dos punteros independientes: la versión activa en test y la activa en live. Si el proyecto no tiene configuración publicada en el modo de tu clave, crear una sesión falla con 422.

Todo esto se hace desde el dashboard. El detalle de los pasos y sus parámetros está en Configuración de flujos.

3. Obtener una API key

En el dashboard, sección de claves de API, generás una clave por modo:

• sk_test_… — modo prueba. No consume tokens.
• sk_live_… — modo producción. Descuenta tokens del saldo.

Guardala en el entorno de tu backend:

export KYCAR_API_KEY="sk_test_..."
export KYCAR_API="https://api.kyc.ar"

4. Crear una sesión de verificación

curl -sS -X POST "$KYCAR_API/v1/verification-sessions" \
  -H "Authorization: Bearer $KYCAR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: alta-4821" \
  -d '{
    "project_id": "prj_01J9Z2K3M4N5P6Q7R8S9T0V1W2",
    "external_ref": "cliente-4821",
    "expires_in_hours": 48
  }'

Respuesta 201:

{
  "id": "vs_01K2M4P6R8T0V2X4Z6B8D0F2H4",
  "object": "verification_session",
  "status": "pending",
  "mode": "test",
  "project_id": "prj_01J9Z2K3M4N5P6Q7R8S9T0V1W2",
  "config_version": "cfg_00000003",
  "url": "https://verify.kyc.ar/s/lt_9pQ2vLxK7sYdN1bTfR4mHc8jWgE3aZuQ5nS0oXpVtB",
  "qr": {
    "svg": "https://api.kyc.ar/v1/qr/lt_9pQ2vLxK7sYdN1bTfR4mHc8jWgE3aZuQ5nS0oXpVtB.svg",
    "png": "https://api.kyc.ar/v1/qr/lt_9pQ2vLxK7sYdN1bTfR4mHc8jWgE3aZuQ5nS0oXpVtB.png"
  },
  "expires_at": "2026-08-21T14:03:11.000Z",
  "created_at": "2026-08-19T14:03:11.482Z",
  "external_ref": "cliente-4821"
}

5. Entregarle el link o el QR a la persona

Dos caminos, según dónde esté tu usuario:

• Link: mandale url por email, WhatsApp o mostralo como botón. Abre el flujo en el navegador del celular, sin instalar nada.
• QR: si la persona está frente a una pantalla de escritorio, mostrale qr.svg (o qr.png). Son endpoints públicos que no requieren tu API key, así que podés embeberlos directo:

<img src="https://api.kyc.ar/v1/qr/lt_9pQ2....svg" alt="Escaneá para verificar tu identidad" />

El link vale hasta expires_at y es de un solo uso: una vez abierto y canjeado, el QR de ese token responde 410.

6. Recibir el resultado

Hay dos formas, y conviene usar las dos.

Webhook (recomendado)

Registrá un endpoint receptor y suscribilo a los eventos que te importan:

curl -sS -X POST "$KYCAR_API/v1/webhook-endpoints" \
  -H "Authorization: Bearer $KYCAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.tu-empresa.com/hooks/kycar",
    "events": ["verification_session.approved", "verification_session.rejected"],
    "description": "Backend de onboarding"
  }'

Respuesta 201 — el secret viene completo una sola vez:

{
  "id": "whep_01K2M4P6R8T0V2X4Z6B8D0F2H4",
  "object": "webhook_endpoint",
  "url": "https://api.tu-empresa.com/hooks/kycar",
  "events": ["verification_session.approved", "verification_session.rejected"],
  "status": "active",
  "description": "Backend de onboarding",
  "secret": "whsec_kR7mQ2vLxK9sYdN1bTfR4mHc8jWgE3aZ",
  "created_at": "2026-08-19T14:10:02.117Z",
  "updated_at": "2026-08-19T14:10:02.117Z"
}

Cuando la sesión se resuelve, recibís un POST con el evento firmado:

{
  "id": "evt_7QK3M9ZP2X8V4T0R6B1D5F3H7J",
  "object": "event",
  "api_version": "v1",
  "type": "verification_session.approved",
  "created_at": "2026-08-19T14:22:47.903Z",
  "data": {
    "object": {
      "id": "vs_01K2M4P6R8T0V2X4Z6B8D0F2H4",
      "object": "verification_session",
      "status": "approved",
      "mode": "test",
      "project_id": "prj_01J9Z2K3M4N5P6Q7R8S9T0V1W2",
      "config_version": "cfg_00000003",
      "created_at": "2026-08-19T14:03:11.482Z",
      "external_ref": "cliente-4821",
      "result": {
        "outcome": "approved",
        "reason_codes": [],
        "steps": [
          { "id": "consent", "type": "consent", "verdict": "approved" },
          { "id": "documento", "type": "document_ar", "verdict": "approved" },
          { "id": "selfie", "type": "face_liveness", "verdict": "approved" }
        ]
      },
      "completed_at": "2026-08-19T14:22:46.551Z"
    }
  }
}

Los datos del documento (nombre, número, CUIL) no viajan por defecto: son opt-in por proyecto. Ver Eventos y payload.

Consulta directa

Sirve como red de seguridad (reconciliación, reintentos de tu lado) y para resolver el estado en cualquier momento:

curl -sS "$KYCAR_API/v1/verification-sessions/vs_01K2M4P6R8T0V2X4Z6B8D0F2H4" \
  -H "Authorization: Bearer $KYCAR_API_KEY"

{
  "id": "vs_01K2M4P6R8T0V2X4Z6B8D0F2H4",
  "object": "verification_session",
  "status": "approved",
  "mode": "test",
  "project_id": "prj_01J9Z2K3M4N5P6Q7R8S9T0V1W2",
  "config_version": "cfg_00000003",
  "created_at": "2026-08-19T14:03:11.482Z",
  "external_ref": "cliente-4821",
  "result": {
    "outcome": "approved",
    "reason_codes": [],
    "steps": [
      { "id": "consent", "type": "consent", "verdict": "approved" },
      { "id": "documento", "type": "document_ar", "verdict": "approved" },
      { "id": "selfie", "type": "face_liveness", "verdict": "approved" }
    ]
  },
  "completed_at": "2026-08-19T14:22:46.551Z"
}

No hagas polling agresivo: la API pública tiene throttling y una verificación tarda lo que tarde la persona. El webhook es el camino correcto; la consulta, el respaldo.

7. Pasar a producción

1. Publicá la configuración del proyecto en modo live desde el dashboard.
2. Generá una clave sk_live_… (requiere la cuenta activa).
3. Cargá saldo de tokens: en live cada sesión descuenta al crearse.
4. Registrá el endpoint de webhook de producción y probalo con POST /v1/webhook-endpoints/{id}/test.

Los endpoints de webhook son por cuenta, no por modo: el mismo endpoint recibe eventos de sesiones test y live. Distinguilos por data.object.mode.