# Contrato.Cloud developer documentation

Public KYC documentation only. No private API keys or customer data are required to read these resources.

Revision: ab4c5635b7f0f446ba6cfcf3607f9fb94636e233074478aed2ea1a9c23f83ead

MCP: https://contrato.cloud/api/mcp

## pt-BR

- [Context bundle](https://contrato.cloud/downloads/ai/pt-BR/context.md)
- [API KYC: da identificação ao resultado](https://contrato.cloud/pt-BR/desenvolvedores/kyc/visao-geral): Entenda a arquitetura da integração KYC, a jornada hospedada, os eventos e as responsabilidades do seu sistema.
- [Integre sua primeira jornada de KYC](https://contrato.cloud/pt-BR/desenvolvedores/kyc/inicio-rapido): Crie uma transação no seu servidor, encaminhe a jornada hospedada e consulte o resultado com exemplos da API KYC.
- [Integre KYC com seu agente de IA](https://contrato.cloud/pt-BR/desenvolvedores/integrar-com-ia): Prepare sua integração KYC com prompts, contexto público, oito linguagens e documentação por MCP.
- [Autenticação e proteção das chaves de API](https://contrato.cloud/pt-BR/desenvolvedores/kyc/autenticacao): Use X-API-Key no backend, mantenha Tenant e ambiente isolados e prepare a rotação de credenciais da integração KYC.
- [Ambientes e configuração da integração KYC](https://contrato.cloud/pt-BR/desenvolvedores/kyc/ambientes): Separe credenciais, URLs, callbacks e dados por ambiente, sem confundir exemplos locais com serviços operacionais.
- [Crie uma transação de verificação de identidade](https://contrato.cloud/pt-BR/desenvolvedores/kyc/criar-transacao): Conheça os campos de criação, os identificadores de correlação e o retorno 201 da API KYC.
- [Encaminhe a pessoa para a jornada hospedada](https://contrato.cloud/pt-BR/desenvolvedores/kyc/jornada-hospedada): Utilize os links retornados pela API KYC, preserve a privacidade e acompanhe a jornada pelo seu backend.
- [Interprete resultados, decisões e status do KYC](https://contrato.cloud/pt-BR/desenvolvedores/kyc/resultados-e-status): Diferencie etapa operacional de decisão e trate pendências, aprovação, rejeição, expiração e revisão manual.
- [Idempotência: repita a criação sem duplicar a transação](https://contrato.cloud/pt-BR/desenvolvedores/kyc/idempotencia): Use Idempotency-Key para repetir o mesmo POST e trate conflitos de payload sem criar transações duplicadas.
- [Receba webhooks e acompanhe os eventos de KYC](https://contrato.cloud/pt-BR/desenvolvedores/kyc/webhooks-e-eventos): Configure o callback, valide a assinatura, deduplique pelo event_id e consulte o estado atual da transação.
- [Valide a assinatura HMAC dos webhooks](https://contrato.cloud/pt-BR/desenvolvedores/kyc/validar-assinatura-hmac): Valide timestamp e HMAC SHA-256 sobre os bytes originais, com exemplos em TypeScript e Python e comparação segura.
- [Reentrega, duplicidades e reconciliação de eventos](https://contrato.cloud/pt-BR/desenvolvedores/kyc/reentrega-e-reconciliacao): Projete um consumidor tolerante a falhas com event_id, persistência durável e consulta do estado atual por GET.
- [Documentos, assets e evidências com acesso autorizado](https://contrato.cloud/pt-BR/desenvolvedores/kyc/documentos-e-evidencias): Consulte os quatro endpoints de arquivos do KYC e entenda o escopo document_download, a autorização por IP e os cuidados com dados pessoais.
- [Erros e diagnóstico da integração KYC](https://contrato.cloud/pt-BR/desenvolvedores/kyc/erros-e-diagnostico): Identifique falhas de validação, autenticação, permissão, transação e idempotência sem expor dados pessoais nos logs.
- [Limites do contrato e boas práticas de integração](https://contrato.cloud/pt-BR/desenvolvedores/kyc/limites-e-boas-praticas): Aplique limites documentados de campos, timeouts, concorrência controlada e minimização de dados na integração KYC.
- [Checklist para colocar sua integração KYC em produção](https://contrato.cloud/pt-BR/desenvolvedores/kyc/entrada-em-producao): Revise acesso, segurança de webhook, cenários de decisão, recuperação e proteção de dados antes de liberar a integração.
- [Histórico e evolução do contrato público KYC](https://contrato.cloud/pt-BR/desenvolvedores/kyc/historico-de-versoes): Acompanhe a versão do contrato público e saiba revisar exemplos, consumidores e mudanças antes de atualizar sua integração.
- [Exemplos de API e downloads para integração KYC](https://contrato.cloud/pt-BR/desenvolvedores/kyc/exemplos-e-downloads): Baixe OpenAPI e Postman e consulte exemplos de criação em Node.js, TypeScript e Python sem credenciais reais.
- [Explore o simulador local de KYC](https://contrato.cloud/pt-BR/desenvolvedores/kyc/guia-do-simulador): Aprenda a interpretar cenários sintéticos de KYC no navegador, sem credenciais, uploads ou chamadas à API real.

## en

- [Context bundle](https://contrato.cloud/downloads/ai/en/context.md)
- [KYC API: from identity checks to results](https://contrato.cloud/en/developers/kyc/overview): Understand KYC integration architecture, the hosted journey, events and your application’s responsibilities.
- [Integrate your first KYC journey](https://contrato.cloud/en/developers/kyc/quickstart): Create a transaction on your server, hand over the hosted journey and read its result using KYC API examples.
- [Integrate KYC with your AI agent](https://contrato.cloud/en/developers/integrate-with-ai): Prepare your KYC integration with prompts, public context, eight languages and MCP documentation.
- [Authentication and API key protection](https://contrato.cloud/en/developers/kyc/authentication): Use X-API-Key on your backend, isolate Tenant and environment access and prepare KYC credential rotation.
- [KYC environments and integration configuration](https://contrato.cloud/en/developers/kyc/environments): Separate credentials, URLs, callbacks and data by environment without confusing local examples with operational services.
- [Create an identity verification transaction](https://contrato.cloud/en/developers/kyc/create-transaction): Understand creation fields, correlation identifiers and the KYC API’s 201 response.
- [Hand the person over to the hosted journey](https://contrato.cloud/en/developers/kyc/hosted-journey): Use the KYC API’s returned links, protect privacy and track the journey through your backend.
- [Interpret KYC results, decisions and status](https://contrato.cloud/en/developers/kyc/results-and-status): Distinguish operational stages from decisions and handle pending, approved, rejected, expired and manual-review cases.
- [Idempotency: retry creation without duplicating a transaction](https://contrato.cloud/en/developers/kyc/idempotency): Use Idempotency-Key to repeat the same POST and handle payload conflicts without duplicate transactions.
- [Receive webhooks and track KYC events](https://contrato.cloud/en/developers/kyc/webhooks-and-events): Configure callbacks, verify signatures, deduplicate by event_id and read current transaction state.
- [Verify webhook HMAC signatures](https://contrato.cloud/en/developers/kyc/verify-hmac-signature): Verify timestamp and HMAC SHA-256 over original bytes using TypeScript and Python examples with safe comparison.
- [Event redelivery, duplicates and reconciliation](https://contrato.cloud/en/developers/kyc/redelivery-and-reconciliation): Design a fault-tolerant consumer with event_id, durable persistence and current-state reconciliation through GET.
- [Authorized documents, assets and evidence downloads](https://contrato.cloud/en/developers/kyc/documents-and-evidence): Explore the four KYC file endpoints, document_download scope, IP authorization and personal-data safeguards.
- [KYC integration errors and troubleshooting](https://contrato.cloud/en/developers/kyc/errors-and-troubleshooting): Identify validation, authentication, permission, transaction and idempotency failures without exposing personal data in logs.
- [Contract bounds and integration best practices](https://contrato.cloud/en/developers/kyc/limits-and-best-practices): Apply documented field bounds, timeouts, controlled concurrency and data minimization in your KYC integration.
- [Go-live checklist for your KYC integration](https://contrato.cloud/en/developers/kyc/go-live): Review access, webhook security, decision scenarios, recovery and data protection before launching your integration.
- [KYC public contract history and evolution](https://contrato.cloud/en/developers/kyc/changelog): Track the public contract version and review examples, consumers and changes before updating your integration.
- [KYC API examples and integration downloads](https://contrato.cloud/en/developers/kyc/examples-and-downloads): Download OpenAPI and Postman resources and explore Node.js, TypeScript and Python creation examples without real credentials.
- [Explore the local KYC simulator](https://contrato.cloud/en/developers/kyc/simulator-guide): Learn to interpret synthetic KYC scenarios in your browser without credentials, uploads or real API calls.

## es

- [Context bundle](https://contrato.cloud/downloads/ai/es/context.md)
- [API KYC: de la identificación al resultado](https://contrato.cloud/es/desarrolladores/kyc/vision-general): Comprenda la integración KYC, el recorrido alojado, los eventos y las responsabilidades de su sistema.
- [Integre su primer recorrido KYC](https://contrato.cloud/es/desarrolladores/kyc/inicio-rapido): Cree una transacción desde su servidor, derive al recorrido alojado y consulte el resultado con ejemplos de la API KYC.
- [Integre KYC con su agente de IA](https://contrato.cloud/es/desarrolladores/integrar-con-ia): Prepare su integración KYC con prompts, contexto público, ocho lenguajes y documentación por MCP.
- [Autenticación y protección de las claves de API](https://contrato.cloud/es/desarrolladores/kyc/autenticacion): Utilice X-API-Key desde el backend, aísle el Tenant y el entorno y prepare la rotación de credenciales KYC.
- [Entornos y configuración de la integración KYC](https://contrato.cloud/es/desarrolladores/kyc/entornos): Separe credenciales, URLs, callbacks y datos por entorno sin confundir ejemplos locales con servicios operativos.
- [Cree una transacción de verificación de identidad](https://contrato.cloud/es/desarrolladores/kyc/crear-transaccion): Conozca los campos de creación, los identificadores de correlación y la respuesta 201 de la API KYC.
- [Derive a la persona al recorrido alojado](https://contrato.cloud/es/desarrolladores/kyc/recorrido-alojado): Utilice los enlaces devueltos por la API KYC, proteja la privacidad y acompañe el recorrido desde su backend.
- [Interprete resultados, decisiones y estados KYC](https://contrato.cloud/es/desarrolladores/kyc/resultados-y-estados): Distinga la etapa operativa de la decisión y trate pendientes, aprobación, rechazo, vencimiento y revisión manual.
- [Idempotencia: repita la creación sin duplicar la transacción](https://contrato.cloud/es/desarrolladores/kyc/idempotencia): Utilice Idempotency-Key para repetir el mismo POST y trate los conflictos sin duplicar transacciones.
- [Reciba webhooks y acompañe los eventos KYC](https://contrato.cloud/es/desarrolladores/kyc/webhooks-y-eventos): Configure el callback, valide la firma, deduplique por event_id y consulte el estado actual de la transacción.
- [Valide la firma HMAC de los webhooks](https://contrato.cloud/es/desarrolladores/kyc/validar-firma-hmac): Valide timestamp y HMAC SHA-256 sobre los bytes originales con ejemplos TypeScript y Python y comparación segura.
- [Reentrega, duplicados y conciliación de eventos](https://contrato.cloud/es/desarrolladores/kyc/reentrega-y-conciliacion): Diseñe un consumidor tolerante a fallos con event_id, persistencia duradera y consulta del estado actual mediante GET.
- [Descarga autorizada de documentos, assets y evidencias](https://contrato.cloud/es/desarrolladores/kyc/documentos-y-evidencias): Consulte los cuatro endpoints de archivos KYC, el permiso document_download, la autorización por IP y la protección de datos.
- [Errores y diagnóstico de la integración KYC](https://contrato.cloud/es/desarrolladores/kyc/errores-y-diagnostico): Identifique fallos de validación, autenticación, permisos, transacción e idempotencia sin exponer datos personales.
- [Límites del contrato y buenas prácticas de integración](https://contrato.cloud/es/desarrolladores/kyc/limites-y-buenas-practicas): Aplique límites documentados de campos, timeouts, concurrencia controlada y minimización de datos en su integración KYC.
- [Lista para llevar su integración KYC a producción](https://contrato.cloud/es/desarrolladores/kyc/paso-a-produccion): Revise acceso, seguridad de webhooks, decisiones, recuperación y protección de datos antes de liberar su integración.
- [Historial y evolución del contrato público KYC](https://contrato.cloud/es/desarrolladores/kyc/historial-de-versiones): Acompañe la versión del contrato público y revise ejemplos, consumidores y cambios antes de actualizar su integración.
- [Ejemplos de API y descargas para integrar KYC](https://contrato.cloud/es/desarrolladores/kyc/ejemplos-y-descargas): Descargue OpenAPI y Postman y consulte ejemplos de creación en Node.js, TypeScript y Python sin credenciales reales.
- [Explore el simulador local de KYC](https://contrato.cloud/es/desarrolladores/kyc/guia-del-simulador): Aprenda a interpretar escenarios KYC sintéticos en el navegador, sin credenciales, cargas ni llamadas a la API real.

## API

- [OpenAPI](https://contrato.cloud/downloads/kyc/openapi.json)