# Integrar com IA

> Faça a integração com o Claude Code, o Cursor ou o Codex: a documentação em Markdown para agentes e um prompt pronto para começar.

Página: https://docs.diligensai.com.br/guias/integrar-com-ia

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](https://docs.diligensai.com.br/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](https://docs.diligensai.com.br/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](https://docs.diligensai.com.br/guias/quickstart.md).

Prompt:

```text
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](https://app.diligensai.com.br/billing). 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](https://app.diligensai.com.br/settings/api-keys), 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](https://app.diligensai.com.br/api-docs) e revisar o catálogo de ações gerado.