API Reference
Referência completa dos endpoints da engineAPI: autenticação, rate limits, idempotência e módulos disponíveis.
API Reference
A engineAPI expõe endpoints REST organizados por módulo, todos sob o prefixo /v1.
Importe a especificação OpenAPI no Postman, Insomnia ou Hoppscotch para testar cada
endpoint com seu token.
Base URL: https://api.engineapi.com.br (todo path desta doc já inclui o /v1)
Testar os endpoints
Importe o OpenAPI direto na sua ferramenta de API testing:
https://api.engineapi.com.br/api-docs-json
Todos os endpoints aparecem organizados por módulo, com parâmetros e responses tipados (o mesmo caminho usado em Integração com IA).
Obtenha seu token
curl -X POST https://api.engineapi.com.br/v1/auth/login \
-H "Content-Type: application/json" \
-d '{ "email": "dev@minhaempresa.com", "password": "suaSenha" }'
Copie o access_token da resposta
{ "data": { "access_token": "eyJhbGciOiJIUzI1NiIs...", "user": { "...": "..." } } }
Use o token nas suas requisições
Envie o token no header Authorization: Bearer {token} (dashboard) ou use uma API
Key com x-api-key para integrações server-to-server.
Módulos
Rate Limits
Os limites são aplicados por partner (não por IP) e reiniciam a cada segundo:
| Plano | Requests/segundo |
|---|---|
| Dev | 5 |
| Starter | 20 |
| Growth | 60 |
| Scale | 200 |
| Enterprise | Dedicado |
Quando o limite é excedido, a API retorna 429 (envelope RFC 7807, ver
Erros e Rejeições) com o header (sempre 1, a janela é de 1 segundo):
Retry-After: 1
Idempotência
Para operações críticas (emissão de notas), use o header Idempotency-Key para garantir que a nota só seja emitida uma vez, mesmo que a requisição seja repetida por retry:
curl -X POST https://api.engineapi.com.br/v1/nfe \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-12345-nfe-1" \
-d '{ ... }'
Se a mesma Idempotency-Key for usada novamente em até 24 horas, a API retorna o
resultado original sem reprocessar, inclusive para rejeições (400 com
error.erros[]), que são replays determinísticos sem retransmitir à SEFAZ. Use um ID
único por nota (ex: pedido-{id}-nfe-{numero}).
Versionamento
A engineAPI segue Semantic Versioning para breaking changes:
| Tipo de mudança | Como é tratado |
|---|---|
| Novos campos opcionais | Retro-compatível |
| Novos endpoints | Retro-compatível |
| Remoção de campos | Aviso com 6 meses de antecedência |
| Breaking changes | Nova versão no path (ex: /v2/nfe) |
A versão atual é v1: todo endpoint desta API vive sob /v1, sem exceção.
Ambiente de Homologação
Todo emissor (Issuer) nasce em homologação (ambienteFiscal: 2). O endpoint da API é
sempre o mesmo:
https://api.engineapi.com.br
Veja o guia de Sandbox para o estado real da promoção pra produção.