Belfort Docs

Primeros pasos

Una verificación completa, de principio a fin, en el entorno de prueba. Sin costo, sin datos reales y con resultados deterministas: el mismo dato de entrada produce siempre el mismo veredicto, así que puedes escribir tests contra esto.

Lo que necesitas

Una API key de prueba, que sacas del panel en Desarrolladores → API keys. Empieza por belfort_test_sk_. Las de prueba y las de producción viven en mundos separados: una key de prueba no puede leer ni escribir nada real, y eso no es una convención sino una barrera.

export BELFORT_API="https://api.belfort.ai"
export BELFORT_KEY="belfort_test_sk_..."

1. Crea la sesión

Una sesión de verificación es el contenedor de todo lo que sigue. La Idempotency-Key es obligatoria: si tu petición se corta por timeout y reintentas, recibes la MISMA sesión, no una segunda.

curl -sS "$BELFORT_API/v1/verification-sessions" \
  -H "Authorization: Bearer $BELFORT_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"checks": ["document", "liveness", "face_match"]}'

Guarda el id que devuelve — es un vrf_…, opaco. No intentes derivar nada de él.

2. Registra el consentimiento

Antes de tratar datos biométricos hace falta el consentimiento informado de la persona titular. No es un trámite de la API: es lo que la LFPDPPP exige y lo que tendrás que exhibir si alguien pregunta. Sin él, el paso 4 rechaza.

curl -sS "$BELFORT_API/v1/verification-sessions/$SESSION/consent" \
  -H "Authorization: Bearer $BELFORT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accepted": true, "purpose": "identity_verification"}'

3. Sube la media

Una llamada por pieza: anverso del documento, reverso y el video de prueba de vida.

curl -sS "$BELFORT_API/v1/verification-sessions/$SESSION/media" \
  -H "Authorization: Bearer $BELFORT_KEY" \
  -F "kind=document_front" \
  -F "file=@ine-frente.jpg"

4. Envía a evaluar

Cierra la captura y dispara el pipeline. La respuesta ya trae un veredicto provisional; el definitivo llega por webhook.

curl -sS -X POST "$BELFORT_API/v1/verification-sessions/$SESSION/submit" \
  -H "Authorization: Bearer $BELFORT_KEY"

En el entorno de prueba el resultado es determinista, así que puedes forzar cada rama — aprobada, rechazada, revisión manual— sin depender de qué imagen subiste.

5. Recoge el resultado

Lo normal es esperar el webhook. Belfort te avisa cuando hay veredicto en vez de que tú preguntes cada segundo. El paquete de evidencia queda disponible para reconciliar:

curl -sS "$BELFORT_API/v1/verification-sessions/$SESSION/evidence" \
  -H "Authorization: Bearer $BELFORT_KEY"

Si necesitas consultar en bucle, respeta el Retry-After que viene en la respuesta en vez de fijar un intervalo tuyo: es la única cifra que sabe cuánto falta de verdad.

Qué sigue