API de Belfort

Qué hay aquí

95 operaciones y 151 códigos de error, todos derivados del contrato publicado (2026-07-30). La referencia sale del OpenAPI; las guías están escritas a mano, pero describen mecanismos que tienen un test que los vigila.

• Primeros pasos — de cero a una verificación aprobada.
• Autenticación — tipos de key, scopes y qué no debe salir de tu servidor.
• Errores — el catálogo completo, con el porqué de cada código.
• Webhooks — cómo verificar la firma sin escribirla tú.

Las dos formas de integrar

Belfort se integra de dos maneras, y la elección es sobre quién pone la interfaz de captura, no sobre qué tan potente es cada una.

• Canal embebido — Belfort pone la interfaz dentro de un iframe en tu producto. Tú no tocas biometría ni almacenas una sola imagen. Es lo que quieres salvo que tengas una razón concreta para lo otro.
• Canal API-direct — tu aplicación captura y sube la media. Más control, y también más superficie tuya que auditar.

El vault de personas es transversal a los dos: es donde vive la identidad una vez verificada, con su PII cifrada y cada acceso en bitácora.

Lo que conviene saber antes

Cuatro reglas que aplican a toda la API y que ahorran la mayoría de las sorpresas:

• Los identificadores son opacos y con prefijo (vrf_, per_, case_). Un UUID crudo se rechaza con INVALID_ID. No los parsees: son cadenas.
• Las listas van por cursor, nunca por offset. Mandar ?offset= es un error explícito, no un parámetro ignorado.
• Toda escritura que cueste dinero o cree algo lleva Idempotency-Key, y en varias es obligatoria.
• Los errores son problem+json. Programa contra code.

Para máquinas

El documento OpenAPI 3.1 es el mismo del que sale esta documentación: mételo en openapi-generator, Speakeasy o Stainless y tienes un cliente. Hay una colección Postman lista para importar y un llms.txt para agentes.