Defina el proceso que se verificará
Cree la transacción mediante POST /v1/face-auth/transactions. Los campos obligatorios son country_code y subject; dentro de subject, indique identity con type, number y country. Consulte los países y locales admitidos en la referencia; los idiomas del sitio no equivalen a los valores de la API.
# Server-side only. Configure KYC_API_BASE_URL with your authorized base (https://api.example.invalid is illustrative), and KYC_API_KEY privately. Never expose credentials in browser code.
set -eu
: "${KYC_API_BASE_URL:?Set authorized base}" "${KYC_API_KEY:?Set API key}"
: "${KYC_IDEMPOTENCY_KEY:?Persist the key for this creation intent}"
curl --fail-with-body --max-time 15 --request POST \
"${KYC_API_BASE_URL%/}/v1/face-auth/transactions" \
--header "X-API-Key: ${KYC_API_KEY}" \
--header "Idempotency-Key: ${KYC_IDEMPOTENCY_KEY}" \
--header 'Content-Type: application/json' \
--data-binary '{"country_code":"BR","external_id":"docs-example-0001","locale":"pt-BR","subject":{"identity":{"country":"BR","number":"00000000000","type":"CPF"}}}'
# Persist transaction_id and business correlation; use the returned links.webview_url. Read status, decision and decision_reason together. Reuse the SAME idempotency key AND original payload only for the same creation intent; never silently bypass a 409 conflict.
Correlacione sin duplicar datos
Utilice external_id para relacionar el proceso en su sistema. subject.tenant_subject_id identifica a la persona en su base. Estos identificadores tienen funciones distintas y no sustituyen el transaction_id devuelto por la API.
source describe el sistema, la integración y el canal de origen. metadata admite contexto de negocio, con un límite de 8 KB; evite datos sensibles e información innecesaria. Puede configurar el vencimiento mediante expires_in_minutes, dentro de los límites del contrato; si se omite, se aplica el valor del Tenant.
Trate la respuesta
La respuesta documentada es 201, incluso si la creación se recupera por idempotencia. Guarde el identificador antes de derivar a la persona. Si pierde la respuesta después del envío, repita la creación con la misma clave y el mismo payload; no genere automáticamente otra clave.
callback_url, si se proporciona, define el webhook de la transacción; de lo contrario se utiliza la configuración del Tenant. Consulte idempotencia y webhooks antes de producción.