Integração com agentes de IA

Esta documentação foi escrita para ser lida por máquina também. Aponte seu assistente de programação para os endereços abaixo e ele tem tudo de que precisa.

O que dar ao agente

Endereço	O que é
`https://docbank.lumecoding.com/openapi.json`	O contrato completo, em OpenAPI 3.1. É este o arquivo a passar, e não as páginas legíveis por gente.
`https://docbank.lumecoding.com/llms.txt`	Resumo em texto puro: o que a API faz, URLs base, autenticação e as regras que um agente não adivinha.
`https://docbank.lumecoding.com/openapi.yaml`	O mesmo contrato em YAML, se a ferramenta preferir.

Os endereços são estáveis e versionados. O esquema publicado ali não quebra em silêncio: uma mudança incompatível vira v2, com a v1 no ar e rotulada.

O prompt

Copie, troque o que estiver entre colchetes e cole no seu agente.

prompt

Construa uma integração com a API bancária Lume.

Especificação OpenAPI: https://docbank.lumecoding.com/openapi.json
Resumo para agentes: https://docbank.lumecoding.com/llms.txt
URL base do sandbox: https://sandbox.api.lumecoding.com
Linguagem: [TypeScript / Go / Python / …]

Comece pedindo uma chave de sandbox em POST /v1/sandbox/keys — não precisa de
cadastro nem de aprovação, e a resposta traz a chave, uma conta de testes com
saldo fictício e o segredo TOTP dessa conta.

Autenticação: envie a chave no cabeçalho X-API-Key em todas as chamadas.

O cliente precisa saber:
  1. Consultar saldo e extrato.
  2. Consultar o titular de uma chave PIX antes de transferir, e exibir o nome
     devolvido para conferência.
  3. Transferir por PIX.
  4. Acompanhar o desfecho da transferência pelo status da transação.

Regras obrigatórias — não são opcionais e não podem ser simplificadas:

  - Envie o cabeçalho Idempotency-Key em TODA chamada que move dinheiro. A chave
    tem de ser derivada do pedido que originou o pagamento, e NÃO gerada dentro
    da função de envio: repetir a mesma operação precisa produzir a mesma chave,
    senão a repetição vira uma segunda transferência.
  - Todos os valores são inteiros em centavos. Nunca use ponto flutuante para
    dinheiro em nenhuma parte do código.
  - Trate o status HELD_FOR_REVIEW da transferência como um desfecho normal, e
    não como erro: a transação foi retida para o titular decidir em
    POST /v1/transactions/{id}/review.
  - Decida o tratamento de erro pelo campo "code" da resposta, nunca comparando
    o texto de "message".
  - Repita apenas 429, 500 e 503, com espera crescente e sempre com a MESMA
    chave de idempotência.
  - Transferências a partir de R$ 1.000,00 — o valor exato já conta —,
    e também a que leva a soma dos PIX do dia a esse valor, exigem um token de
    step-up no cabeçalho X-Step-Up, obtido em POST /v1/auth/step-up (rota de
    sessão: login e MFA com as credentials da chave de sandbox) com um código
    TOTP calculado a partir do segredo da conta.

Escreva testes que cubram: repetição com a mesma chave de idempotência, saldo
insuficiente, limite excedido e transferência retida para revisão.

O que dizer ao agente antes de rodar o código

O que conferir no resultado

O agente escreve rápido; a conferência é sua. Uma lista curta que pega quase tudo que importa:

O Idempotency-Key aparece em toda chamada de transferência, e vem de fora da função de envio?
Existe algum float, double ou number guardando dinheiro fora de centavos inteiros?
O tratamento de erro olha code, e não message?
O laço de repetição espera Retry-After, ou repete imediatamente?
A chave de API está em variável de ambiente, e não no código — nem no histórico do Git?

Ferramentas que leem o spec sozinhas

Assistentes que aceitam uma URL de OpenAPI podem consumir /openapi.json diretamente, sem intermediário. Para editores com acesso a arquivos, baixar o spec para o repositório e apontar o agente para ele funciona igualmente bem — e mantém a integração reproduzível quando a rede não coopera.