Integrar com IA · Diligens Docs

Assistentes de programação, como o Claude Code, o Cursor, o Codex e o GitHub Copilot, conseguem fazer boa parte da integração sozinhos, desde que leiam a documentação correta. Esta página reúne o que a Diligens oferece para esses agentes e um prompt pronto para começar.

Documentação para agentes de IA

llms-full.txt: todas as páginas desta documentação em Markdown, em um único arquivo. É o melhor ponto de partida para um agente, porque ele lê tudo de uma vez.
llms.txt: o resumo do produto e o índice das páginas, no formato do llmstxt.org.
Markdown de cada página: acrescente .md ao endereço de qualquer página (por exemplo, /referencia/pedidos.md). O botão Copiar página, no topo de cada página, copia esse Markdown e também abre a página no ChatGPT ou no Claude.

Todas as páginas também são servidas em HTML completo, sem depender de JavaScript, para os agentes que leem a página diretamente.

Prompt para começar

Abra o assistente na raiz do seu projeto e cole o prompt abaixo. Ele indica ao agente onde está a documentação e a ordem da integração, a mesma do Quickstart.

Prompt

Integre a Diligens (assistente de IA com a marca da empresa, dentro do sistema) neste projeto.

1. Antes de escrever código, leia a documentação completa em https://docs.diligensai.com.br/llms-full.txt. Siga a documentação: não invente rotas, campos nem códigos de erro.
2. Analise o projeto: a linguagem e o framework do backend, como a sessão do usuário autenticado é obtida, onde ficam as páginas autenticadas do frontend e onde os pedidos, os produtos e as contas a receber e a pagar são criados e alterados.
3. Backend: leia a API key da variável de ambiente DILIGENS_API_KEY. Ela nunca vai para o navegador nem para o repositório.
4. Backend: crie uma rota, acessível apenas ao usuário autenticado, que chame POST /chat/token com o external_id do usuário da sessão (nunca de um parâmetro enviado pelo navegador) e devolva { token, expires_at }.
5. Frontend: inclua o script do SDK (https://cdn.diligensai.com.br/v1/diligens.js) nas páginas autenticadas e chame Diligens.init com um getToken que busque a rota do passo 4.
6. Backend: envie os pedidos com PUT /orders, em lotes de até 300, o catálogo de produtos com PUT /products, em lotes de até 500, e as contas com PUT /financial-entries, em lotes de até 200. Crie um comando que envie o histórico completo uma única vez, com as páginas em sequência, e envie cada alteração no ponto em que o pedido, o produto ou a conta é criado ou alterado, com o updated_at da última alteração. Produto excluído vai com status "archived".
7. Backend: quando um usuário for excluído do sistema, chame DELETE /external-users/:external_id.
8. Trate os erros pelo campo code e, no status 429, aguarde os segundos do header Retry-After antes de repetir a chamada. O PUT /orders, o PUT /products e o PUT /financial-entries respondem 202 com batch_id e gravam em segundo plano: registre o batch_id no log, não reenvie um lote que recebeu 202 e reenvie o que recebeu 500 ou 503.
9. Ao terminar, liste os arquivos criados ou alterados, as variáveis de ambiente necessárias e o que eu preciso fazer no painel da Diligens.

Revise o código antes de publicar

O agente pode errar. Confira, principalmente, se o external_id do POST /chat/token vem da sessão do seu backend e se a API key não aparece no frontend nem no repositório.

O que continua com você

Algumas etapas são feitas no painel da Diligens e não podem ser delegadas ao agente:

Fazer a primeira recarga de créditos, em Cobrança. A API inteira funciona depois da primeira recarga paga: antes dela, a API key não é gerada.
Gerar a API key, em Configurações › Chaves de API, e guardá-la na variável de ambiente DILIGENS_API_KEY do servidor.
Para que a IA consulte dados e execute ações no seu sistema, enviar a documentação da sua API em Integrações e revisar o catálogo de ações gerado.