> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engineapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração com IA

> A engineAPI é AI-Ready. Qualquer agente de IA integra em minutos, não dias. Claude, ChatGPT, Gemini, Copilot, Cursor.

<Info>
  **Seus devs (ou os agentes de IA deles) integram em minutos, não dias.**

  A engineAPI foi projetada para ser consumida tanto por humanos quanto por agentes de IA. Qualquer LLM (Claude, ChatGPT, Gemini, Copilot, Cursor, Windsurf) consegue gerar código de integração correto apontando para nosso contexto machine-readable.
</Info>

## Por que isso importa

Hoje, a maioria dos times de engenharia usa IA no dia a dia para escrever código. Quando a API é **AI-Ready**, o custo de integração cai drasticamente:

| Abordagem                         | Tempo estimado | Risco de erro                |
| --------------------------------- | -------------- | ---------------------------- |
| Ler docs + escrever código manual | 2 a 5 dias     | Alto (interpretação humana)  |
| Copiar exemplos da doc            | 1 a 2 dias     | Médio (depende de contexto)  |
| **Apontar IA para `llms.txt`**    | **Minutos**    | **Baixo, contexto completo** |

## Recursos disponíveis para IAs

A engineAPI fornece 3 recursos machine-readable que IAs usam automaticamente: o
**llms.txt** (contexto completo para LLMs: endpoints, SDK, auth e erros), o
**OpenAPI Spec** (92 endpoints com schemas tipados e exemplos) e o **SDK
TypeScript** (tipos exportados para auto-complete em qualquer IDE).

| Recurso          | URL                                  | Atualização       |
| ---------------- | ------------------------------------ | ----------------- |
| **llms.txt**     | `docs.engineapi.com.br/llms.txt`     | Automática via CI |
| **OpenAPI Spec** | `api.engineapi.com.br/api-docs-json` | Automática via CI |
| **SDK Types**    | `npm install @engineapi/sdk`         | A cada release    |

## Como usar com agentes de IA

### Claude, ChatGPT, Gemini (conversacional)

Cole este bloco na conversa com qualquer agente de IA:

```
Preciso integrar com a engineAPI, uma API fiscal brasileira.

Contexto completo da API: https://docs.engineapi.com.br/llms.txt

Use o SDK @engineapi/sdk (npm). Crie uma integração para emitir NFe
com tratamento de erros e retry. A API key está em process.env.ENGINE_API_KEY.
```

O agente vai gerar código funcional de primeira porque o `llms.txt` contém todos os endpoints, parâmetros e formatos de resposta.

### Cursor / Windsurf / Copilot (IDE)

<Steps>
  <Step title="Adicione o contexto">
    No Cursor: abra o chat e adicione `https://docs.engineapi.com.br/llms.txt` como referência.
    No Copilot: cole o conteúdo do llms.txt como comentário no topo do arquivo.
  </Step>

  <Step title="Peça a integração">
    ```
    Integre com a engineAPI para emitir NFe.
    Use @engineapi/sdk. API key em process.env.ENGINE_API_KEY.
    ```
  </Step>

  <Step title="Revise e execute">
    O agente gera o código completo com imports, client setup, chamada e error handling.
  </Step>
</Steps>

### Agentes autônomos (Forge, Devin, Sweep)

Para agentes que operam em repositórios, adicione ao seu `CONTEXT.md` ou `README.md`:

```markdown theme={null}
## Fiscal API Integration

engineAPI: Motor Fiscal SaaS
- SDK: npm install @engineapi/sdk
- llms.txt: https://docs.engineapi.com.br/llms.txt
- OpenAPI: https://api.engineapi.com.br/api-docs-json
- Auth: header x-api-key
```

O agente encontra essas referências automaticamente e integra sem intervenção humana.

### OpenAPI Import (Postman, Insomnia, Hoppscotch)

Para ferramentas de API testing:

```
https://api.engineapi.com.br/api-docs-json
```

Importe e todos os 92 endpoints aparecem organizados por módulo, com parâmetros e responses tipados.

## Bloco de contexto rápido

Se você está usando IA **agora mesmo**, copie e cole este bloco completo:

```
engineAPI: Motor Fiscal SaaS B2B2B
npm install @engineapi/sdk

import { EngineApiClient } from '@engineapi/sdk';
const client = new EngineApiClient({
  baseUrl: 'https://api.engineapi.com.br',
  apiKey: process.env.ENGINE_API_KEY,
});

Módulos:
- client.nfe      (emitir, listar, cancelar, cartaCorrecao, downloadPdf, downloadXml)
  Auth: header x-api-key: ek_live_UUID (funciona com o config acima)

- client.companies (criar, listar, buscar, consultarCnpj, uploadCertificado)
  Aceita apiKey OU token JWT. uploadCertificado() já envia multipart/form-data
  (campo file + password), path real é /companies.

Não existe client.dfe (DFe é fluxo interno do dashboard, fora do contrato público).

Erros: EngineApiError (isValidationError, isUnauthorized, isRateLimited, isServerError)
OpenAPI: https://api.engineapi.com.br/api-docs-json
Docs: https://docs.engineapi.com.br
```

## O que é llms.txt

O [llms.txt](https://llmstxt.org) é um padrão emergente: como o `robots.txt` para crawlers, mas para modelos de linguagem. Quando uma IA acessa sua documentação, ela procura por esse arquivo para entender rapidamente o que a API faz e como usar.

<AccordionGroup>
  <Accordion title="Qual a diferença entre llms.txt e OpenAPI?">
    O **OpenAPI** é um spec técnico completo (schemas, validações, responses). O **llms.txt** é um resumo em linguagem natural otimizado para LLMs, contém o que a IA precisa para gerar código correto sem ler centenas de páginas.

    São complementares: a IA lê o llms.txt primeiro para entender a estrutura, depois consulta o OpenAPI spec para detalhes de parâmetros.
  </Accordion>

  <Accordion title="O llms.txt é atualizado automaticamente?">
    Sim. O pipeline de CI da engineAPI gera o `llms.txt` automaticamente a partir do OpenAPI spec em cada deploy. Se um endpoint muda no código, o CI **bloqueia o merge** até que a documentação seja atualizada.
  </Accordion>

  <Accordion title="Funciona com qualquer IA?">
    Sim. O llms.txt é texto puro, funciona com Claude, ChatGPT, Gemini, Copilot, Cursor, Windsurf, Devin, e qualquer agente que leia texto.
  </Accordion>
</AccordionGroup>

## Próximos passos

* [SDK TypeScript](/sdks/typescript): documentação completa do SDK oficial com tipos.
* [Quickstart](/quickstart): da conta criada à primeira nota em 5 minutos.