Nesta página
Prepare a integração KYC com seu agente
Escolha a linguagem e copie as instruções abaixo para o seu agente de desenvolvimento. O contexto reúne os guias públicos, exemplos completos e a referência do contrato. Use dados sintéticos durante a preparação; a base de exemplo .invalid não é um ambiente de execução.
Prompt e contexto da integração
Instruções para o seu agente
Implemente uma integração backend de KYC da Contrato.Cloud em TypeScript / Node.js, usando somente a documentação pública indicada abaixo.
1. Leia o contexto e o OpenAPI antes de escrever código. Cite as páginas utilizadas; se um campo ou comportamento não estiver documentado, peça esclarecimento. Não invente API de assinaturas SIGN, rotas Admin ou Portal privado.
2. Use https://api.example.invalid como base sintética. Antes de qualquer execução real, solicite a base autorizada do ambiente e carregue a X-API-Key somente de variáveis de ambiente no backend. Nunca coloque chaves no frontend, prompt, URL, logs ou repositório.
3. Crie transações com POST /v1/face-auth/transactions e Idempotency-Key estável por operação lógica. Persista transaction_id e external_id. Encaminhe a pessoa pela links.webview_url retornada; não construa a URL da jornada.
4. Consulte GET /v1/face-auth/transactions/{transaction_id}. Trate status, decision e decision_reason em conjunto. pending e etapas intermediárias continuam pendentes; manual_review_pending aguarda revisão; approved exige decision=approved; rejected exige tratamento da recusa; expired encerra ou reinicia conforme política. Expiração não implica decision=rejected.
5. No receptor de webhooks, preserve os bytes do corpo bruto. Valide X-Face-Auth-Timestamp e X-Face-Auth-Signature (sha256=<hex>) com HMAC SHA-256 de timestamp + '.' + raw_body, comparação em tempo constante e janela temporal. Só depois interprete JSON e valide o envelope.
6. Deduplicate event_id em armazenamento durável, confira o identificador do header com o corpo e torne efeitos de negócio idempotentes. Reconcilie eventos fora de ordem e entregas perdidas consultando a transação atual; não rebaixe uma decisão nova por um evento antigo.
7. Entregue configuração, tratamento de erros, testes com fixtures sintéticas e instruções de execução. Cubra aprovação, rejeição, pending, expiração, revisão manual, duplicidade, corpo alterado, Unicode e timestamp vencido. Não execute chamadas reais nem processe dados pessoais sem autorização explícita.
8. cURL exemplifica somente HTTP. Se cURL for a preferência, use uma linguagem de backend suportada para o receptor/HMAC e explique a escolha. O MCP abaixo só consulta documentação pública: não cria transações, não assina e não cobra.
Context: https://contrato.cloud/downloads/ai/pt-BR/context.md
OpenAPI: https://contrato.cloud/downloads/kyc/openapi.json
Index: https://contrato.cloud/llms.txt
MCP (Streamable HTTP): https://contrato.cloud/api/mcp
MCP prompt: integrate_kyc (locale=pt-BR, language=typescript)
MCP tools: search_docs, read_doc, get_example
Revisão do conteúdo: ab4c5635b7f0f446ba6cfcf3607f9fb94636e233074478aed2ea1a9c23f83ead
Conectar a documentação por MCP
Adicione esta URL como servidor MCP remoto no seu agente, usando Streamable HTTP. A documentação é pública e não exige chave ou OAuth.
https://contrato.cloud/api/mcpListe ferramentas, recursos e prompts. Use search_docs para encontrar guias, read_doc para ler Markdown e get_example para obter uma variante. Selecione o prompt integrate_kyc com seu idioma e linguagem.
Configuração de exemplo para clientes que aceitam mcpServers/url
{
"mcpServers": {
"contrato-docs": {
"url": "https://contrato.cloud/api/mcp"
}
}
}Este MCP consulta documentação pública KYC. Execução de transações e credenciais pertencem ao seu backend.
Valide antes de executar
Revise o código produzido, configure a base autorizada no seu backend e teste idempotência, HMAC, reconciliação, expiração e revisão manual. Consulte o checklist de produção. A documentação de IA e o MCP não recebem chaves KYC nem dados dos seus clientes.