> ## 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.

# Referência da API

> Referência completa dos endpoints da engineAPI: autenticação, rate limits, idempotência e módulos disponíveis.

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](/guides/ai-integration)).

<Steps>
  <Step title="Obtenha seu token">
    ```bash theme={null}
    curl -X POST https://api.engineapi.com.br/v1/auth/login \
      -H "Content-Type: application/json" \
      -d '{ "email": "dev@minhaempresa.com", "password": "suaSenha" }'
    ```
  </Step>

  <Step title="Copie o access_token da resposta">
    ```json theme={null}
    { "data": { "access_token": "eyJhbGciOiJIUzI1NiIs...", "user": { "...": "..." } } }
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## Módulos

<CardGroup cols={2}>
  <Card title="NFe" icon="file-invoice" href="/guides/emitir-nfe#inutilizao">
    Emissão, cancelamento, carta de correção, inutilização, consulta, download XML/PDF, lote/fila
  </Card>

  <Card title="NFCe" icon="receipt" href="/guides/nfce#inutilizao">
    Emissão, cancelamento, inutilização, consulta, download HTML/XML
  </Card>

  <Card title="NFSe" icon="briefcase">
    Emissão, cancelamento, consulta na SEFIN, download XML/PDF
  </Card>

  <Card title="MDFe / CTe" icon="truck">
    Implementados no motor, **fora da superfície pública documentada** hoje
  </Card>

  <Card title="Empresas" icon="building">
    CRUD de emissores, upload de certificado, consulta de CNPJ
  </Card>

  <Card title="Webhooks" icon="bell">
    Configuração (URL + eventos), secret HMAC, logs de entrega, DLQ
  </Card>

  <Card title="Admin" icon="shield">
    **Acesso restrito (SUPERADMIN)**: provisionamento de parceiros, planos
  </Card>
</CardGroup>

***

## Rate Limits

Os limites são por **partner** (todas as suas chaves compartilham o mesmo orçamento) e a
tabela completa por plano vive em [Rate Limits](/guides/rate-limits), fonte única, não
duplicada aqui.

***

## 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:

```bash theme={null}
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 '{ ... }'
```

<Info>
  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}`).
</Info>

***

## 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](/guides/sandbox) para o estado real da promoção pra produção.

***

## Próximos passos

Os endpoints completos (navegáveis por operação, gerados direto do contrato real) estão
no grupo **Endpoints** desta mesma aba, no menu lateral.

<CardGroup cols={2}>
  <Card title="Catálogo de campos: NFe" icon="file-invoice" href="/api-reference/campos-nfe">
    Todo campo do payload de emissão, navegável por grupo, gerado do schema real
  </Card>

  <Card title="Catálogo de campos: NFCe" icon="cash-register" href="/api-reference/campos-nfce">
    Todo campo do payload de emissão, navegável por grupo, gerado do schema real
  </Card>

  <Card title="Catálogo de campos: NFSe" icon="building-columns" href="/api-reference/campos-nfse">
    Todo campo do payload de emissão, navegável por grupo, gerado do schema real
  </Card>

  <Card title="SDKs" icon="box" href="/sdks/typescript">
    Integre com TypeScript, Python ou PHP em minutos
  </Card>

  <Card title="Autenticação" icon="lock" href="/authentication">
    JWT e API Keys explicados em detalhes
  </Card>
</CardGroup>