# API de NFS-e — Ext Contabilidade

> Emissão de NFS-e para empresas da Ext Contabilidade. REST, JSON, valores em
centavos. A emissão é assíncrona: `202` e depois polling, com um envelope de
erro único em toda falha.

Versão 1.0.0 · OpenAPI 3.1.0

- Documento OpenAPI (a fonte deste arquivo): https://api.extcontabilidade.com.br/v1/openapi.json
- Detalhe completo, campo a campo: https://api.extcontabilidade.com.br/llms-full.txt
- Referência para humanos: https://extcontabilidade.com.br/devs
- Suporte: suporte@extcontabilidade.com.br

## Autenticação

Header `Authorization: Bearer <chave>`, no formato `ext_sk`.
Chave de API da empresa (`ext_sk_...`).

## Início rápido

1. `POST /v1/nfse` com `amount_in_cents` e `description`. Mande também
   `reference` — o id da fatura no seu sistema —, que é por onde você
   reencontra a nota se o `id` se perder.
   Emitindo fora da atividade **principal** da empresa, mande `cnae` (7
   dígitos) — e `service_code` (6) junto, se aquele CNAE tiver mais de uma
   linha. Omitidos, a nota sai na principal.
2. Guarde o `id` do `202`. Ele significa ACEITA, não autorizada.
3. Consulte o header `Location` no intervalo do `Retry-After` até o `status`
   virar um desfecho.
4. Em `issued`, baixe `GET /v1/nfse/{id}/pdf` e `GET /v1/nfse/{id}/xml`.

Os dois tropeços mais comuns da primeira integração: `amount_in_cents` é em
CENTAVOS (`R$ 1.250,50` = `125050`), e `failed` e `indeterminate` pedem ações
opostas.

## Rotas

- `GET /v1/nfse` — Buscar NFS-e por referência
- `POST /v1/nfse` — Emitir NFS-e
- `POST /v1/nfse/{id}/cancel` — Cancelar NFS-e
- `GET /v1/nfse/{id}` — Consultar NFS-e
- `GET /v1/nfse/{id}/pdf` — Baixar o PDF da nota
- `GET /v1/nfse/{id}/xml` — Baixar o XML autorizado
- `GET /v1/activities` — Listar as atividades em que a empresa pode emitir

## Estados da nota

Valores de `status`: `queued`, `processing`, `issued`, `failed`, `indeterminate`, `canceled`.

Situação da nota:

- `queued` — aceita, ainda não enviada. Continue consultando.
- `processing` — envio em curso. Estado **transitório**: não pare o polling nele.
- `issued` — autorizada. `access_key` e `links` existem; é o único estado em que PDF e XML baixam.
- `failed` — recusada, e **nenhum documento existe**. Corrigir o que `error` aponta e reemitir é seguro.
- `indeterminate` — a emissão começou sem desfecho confirmado: **pode existir NFS-e autorizada** sem registro aqui. **Nunca reemita** — daria nota em duplicidade. Acione o suporte.
- `canceled` — cancelada. Nota em cancelamento ainda aparece `issued`.

Desfechos: `issued`, `failed`, `indeterminate` e `canceled`. Valor desconhecido, trate como `indeterminate`.

## Envelope de erro

Toda falha sai neste envelope: `error.type`, `error.code`, `error.message`, `error.param` (opcional), `error.retryable`, `error.livemode` (opcional), `error.provider_code` (opcional), `error.request_id`, `error.errors` (opcional).

Trate pelo `error.code`, nunca pelo status HTTP; `error.retryable` diz se
repetir a MESMA requisição pode dar outro resultado.

### Códigos

- `unauthorized` (401)
- `feature_not_enabled` (403)
- `insufficient_scope` (403)
- `company.issuer_not_enabled` (422)
- `company.issuer_not_configured` (422)
- `company.issuer_not_approved` (422)
- `company.certificate_missing` (422)
- `nfse.cnae_missing_ctribnac` (422)
- `nfse.cnae_missing_nbs` (422)
- `nfse.municipality_not_covered` (422)
- `nfse.cnae_not_allowed` (422)
- `nfse.cnae_without_default` (422)
- `nfse.service_code_unknown` (422)
- `nfse.service_code_not_allowed` (422)
- `nfse.nbs_invalid` (422)
- `nfse.municipal_registration_missing` (422)
- `nfse.customer_document_invalid` (400)
- `nfse.customer_required` (422)
- `nfse.customer_name_required` (422)
- `nfse.export_incomplete` (422)
- `nfse.country_unsupported` (422)
- `nfse.currency_unsupported` (422)
- `nfse.foreign_amount_invalid` (422)
- `nfse.customer_type_conflict` (422)
- `nfse.cancel_window_closed` (422)
- `nfse.not_cancelable` (409)
- `nfse.already_canceled` (409)
- `nfse.cancel_in_progress` (409)
- `nfse.not_issued` (409)
- `nfse.reference_in_use` (409)
- `duplicate_suspected` (409)
- `idempotency_key_in_use` (409)
- `idempotency_key_reuse` (409)
- `invalid_request` (400)
- `invalid_id` (400)
- `not_found` (404)
- `route_not_found` (404)
- `malformed_json` (400)
- `payload_too_large` (413)
- `unsupported_media_type` (415)
- `rate_limit_exceeded` (429)
- `internal_error` (500)
- `service_unavailable` (503)