Guia: Integração com IA
A engineAPI é AI-Ready. Qualquer agente de IA integra em minutos, não dias. Claude, ChatGPT, Gemini, Copilot, Cursor.
AI-Ready API
Seus devs (ou os agentes de IA deles) integram em minutos, não dias.
A engineAPI é a primeira API fiscal do Brasil 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.
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:
| 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 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)
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.
Peça a integração
Integre com a engineAPI para emitir NFe.
Use @engineapi/sdk. API key em process.env.ENGINE_API_KEY.
Revise e execute
O agente gera o código completo com imports, client setup, chamada e error handling.
Agentes autônomos (Forge, Devin, Sweep)
Para agentes que operam em repositórios, adicione ao seu CONTEXT.md ou README.md:
## 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, uploadCertificado)
QUEBRADO nesta versão do pacote: chama /issuers/* em vez de /companies e o
upload de certificado manda JSON em vez de multipart/form-data. Não use
client.companies.*. Use fetch/curl direto contra /v1/companies, exatamente
como documentado em https://docs.engineapi.com.br/guides/first-emission e
https://docs.engineapi.com.br/guides/certificates.
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 é 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.