# Referência da API emitza (versão 0.10.2-rc.1)

API da emitza para emitir NF-e e NFS-e e calcular impostos, incluindo o IBS/CBS da Reforma Tributária.

**Autenticação.** Envie `Authorization: Bearer <chave>`. Chaves `fsk_test_` funcionam só em `api-sandbox.emitza.com.br` e emitem só em homologação, sem valor fiscal; chaves `fsk_live_` funcionam só em `api.emitza.com.br`. Comece pelo sandbox e confira a chave com `GET /v1/me`.

**Emissão assíncrona.** `POST /v1/nfe` e `POST /v1/nfse` respondem 202 na hora, com a nota na fila. O resultado chega pelo webhook (`nfe.authorized`, `nfse.rejected`...) ou consultando `GET /v1/nfe/{id}`.

**Idempotência.** O `externalId` do pedido é a chave: repetir o mesmo pedido devolve a mesma nota (200), nunca uma segunda. Uma nota rejeitada é corrigida reenviando o pedido corrigido com o mesmo `externalId`.

**Valores.** Decimais vão em texto com ponto (`"1500.00"`), para não perder precisão.

**Erros.** Sempre `{ "error": { "code", "message", "details" } }`. Em `validation_failed` (422), `details` lista `{ path, message }` com o caminho do campo, ex.: `items[2].ncm`. Campos desconhecidos são recusados.

## Endereços

- `https://api-sandbox.emitza.com.br`: Sandbox: chave fsk_test_, só homologação (sem valor fiscal).
- `https://api.emitza.com.br`: Produção: chave fsk_live_.

## Sistema

Saúde do serviço, conferência da chave e esta especificação.

### Saúde do serviço

`GET /health` (sem chave)

Sem autenticação. Versão publicada e conexão com o banco.

**Respostas**

- `200`: No ar.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `status` | texto | sim | um de: `ok`, `degraded` |
  | `db` | texto | sim | um de: `ok`, `unreachable` |
  | `version` | texto | sim | até 60 caracteres |
  | `commit` | texto |  | até 60 caracteres |
  | `sefaz` | texto |  | um de: `simulada` |

- `429`: Limite de requisições; espere o tempo de Retry-After.

### Esta especificação (OpenAPI 3.1)

`GET /v1/openapi.json` (sem chave)

Sem autenticação. Use para gerar um cliente ou para dar à IA o contrato da API.

**Respostas**

- `200`: Documento OpenAPI 3.1.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Quem sou eu

`GET /v1/me`

Confere a chave: cliente, plano e modo (live ou test). Bom primeiro teste da integração.

**Respostas**

- `200`: Cliente da chave.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `clientId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `name` | texto | sim | até 100000 caracteres |
  | `plan` | texto ou null | sim | até 60 caracteres |
  | `keyPrefix` | texto | sim | até 60 caracteres |
  | `mode` | texto | sim | live: chave fsk_live_ (produção). test: chave fsk_test_ (sandbox, só homologação). um de: `live`, `test` |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `429`: Limite de requisições; espere o tempo de Retry-After.

## Empresas

Empresas emitentes: cadastro, certificado A1, séries e configuração da NFS-e.

### Cadastrar empresa emitente

`POST /v1/companies`

Cadastra a empresa que vai emitir. Depois envie o certificado A1 (PUT /v1/companies/{id}/certificate). Com chave de teste (fsk_test_) a empresa fica só em homologação.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `cnpj` | texto | sim | CNPJ, com ou sem pontuação (aceita o CNPJ alfanumérico). 14 a 18 caracteres |
| `ie` | texto | sim | Inscrição estadual (dígitos, com ou sem pontuação) ou "ISENTO". 2 a 20 caracteres |
| `im` | texto ou null |  | Inscrição municipal (necessária para NFS-e em alguns municípios). até 15 caracteres |
| `crt` | inteiro | sim | Regime tributário (CRT): 1 Simples Nacional, 2 Simples com excesso de sublimite, 3 regime normal (Presumido ou Real), 4 MEI. um de: `1`, `2`, `3`, `4` |
| `legalName` | texto | sim | 2 a 60 caracteres |
| `tradeName` | texto ou null |  | até 60 caracteres |
| `email` | texto ou null |  | email; até 254 caracteres |
| `address` | objeto | sim | Endereço da empresa. cityCode é o código IBGE do município (7 dígitos). |
| `address.street` | texto | sim | 2 a 60 caracteres |
| `address.number` | texto | sim | até 60 caracteres |
| `address.complement` | texto ou null |  | até 60 caracteres |
| `address.district` | texto | sim | 2 a 60 caracteres |
| `address.cityName` | texto | sim | 2 a 60 caracteres |
| `address.cityCode` | texto | sim | padrão `^[0-9]{7}$` |
| `address.uf` | texto | sim | um de: `RO`, `AC`, `AM`, `RR`, `PA`, `AP`, `TO`, `MA`, `PI`, `CE`, `RN`, `PB`, `PE`, `AL`, `SE`, `BA`, `MG`, `ES`, `RJ`, `SP`, `PR`, `SC`, `RS`, `MS`, `MT`, `GO`, `DF` |
| `address.zip` | texto | sim | padrão `^[0-9]{8}$` |
| `address.phone` | texto ou null |  | padrão `^[0-9]{6,14}$` |
| `environment` | texto |  | homologation: testes, sem valor fiscal. production: notas com valor fiscal. um de: `homologation`, `production` |
| `nfeSeries` | lista de objeto |  | Séries da NF-e já usadas pela empresa, com o próximo número (para continuar a numeração de outro sistema). |
| `nfeSeries[].number` | inteiro | sim | Série da NF-e (0 a 889). 0 a 889 |
| `nfeSeries[].next` | inteiro | sim | Próximo número a usar nesta série. 1 a 999999999 |

Exemplo:

```json
{
  "cnpj": "11222333000181",
  "ie": "110042490114",
  "crt": 1,
  "legalName": "Calçados Exemplo Indústria Ltda",
  "tradeName": "Exemplo",
  "email": "fiscal@exemplo.com.br",
  "address": {
    "street": "Rua das Indústrias",
    "number": "100",
    "district": "Distrito Industrial",
    "cityName": "Franca",
    "cityCode": "3516200",
    "uf": "SP",
    "zip": "14406000",
    "phone": "1637001000"
  }
}
```

**Respostas**

- `201`: Empresa cadastrada.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `cnpj` | texto | sim | até 14 caracteres |
  | `ie` | texto | sim | até 20 caracteres |
  | `im` | texto ou null | sim | até 15 caracteres |
  | `crt` | inteiro | sim | um de: `1`, `2`, `3`, `4` |
  | `legalName` | texto | sim | até 100000 caracteres |
  | `tradeName` | texto ou null | sim | até 100000 caracteres |
  | `email` | texto ou null | sim | até 100000 caracteres |
  | `address` | objeto | sim | Endereço, como cadastrado. |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `sandbox` | booleano | sim | true: empresa criada com chave de teste (fsk_test_); só emite em homologação. |
  | `nfe` | objeto | sim | Séries e próximos números da NF-e, separados por ambiente. |
  | `nfe.homologation` | objeto | sim |  |
  | `nfe.production` | objeto | sim |  |
  | `nfse` | objeto | sim | Configuração e séries da DPS (NFS-e nacional). |
  | `nfse.settings` | objeto | sim | Configuração da NFS-e (PUT /v1/companies/{id}/nfse-settings); campos não configurados vêm null. |
  | `nfse.homologation` | objeto | sim |  |
  | `nfse.production` | objeto | sim |  |
  | `certificate` | objeto ou null | sim |  |
  | `certificate.cnpj` | texto ou null | sim | até 14 caracteres |
  | `certificate.subjectName` | texto ou null | sim | até 100000 caracteres |
  | `certificate.issuer` | texto ou null | sim | até 100000 caracteres |
  | `certificate.serialNumber` | texto ou null | sim | até 100000 caracteres |
  | `certificate.notBefore` | texto | sim | date-time |
  | `certificate.notAfter` | texto | sim | date-time |
  | `certificate.uploadedAt` | texto | sim | date-time |
  | `certificate.status` | texto | sim | um de: `valid`, `expiring`, `expired` |
  | `certificate.daysLeft` | inteiro | sim |  |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `409`: CNPJ já cadastrado por este cliente.
- `422`: Dados inválidos; em sandbox, sandbox_homologation_only ao pedir produção; UF ainda não atendida.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Listar empresas

`GET /v1/companies`

**Respostas**

- `200`: Empresas do cliente.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `data` | lista de qualquer | sim |  |
  | `data[].id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `data[].cnpj` | texto | sim | até 14 caracteres |
  | `data[].ie` | texto | sim | até 20 caracteres |
  | `data[].im` | texto ou null | sim | até 15 caracteres |
  | `data[].crt` | inteiro | sim | um de: `1`, `2`, `3`, `4` |
  | `data[].legalName` | texto | sim | até 100000 caracteres |
  | `data[].tradeName` | texto ou null | sim | até 100000 caracteres |
  | `data[].email` | texto ou null | sim | até 100000 caracteres |
  | `data[].address` | objeto | sim | Endereço, como cadastrado. |
  | `data[].environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `data[].sandbox` | booleano | sim | true: empresa criada com chave de teste (fsk_test_); só emite em homologação. |
  | `data[].nfe` | objeto | sim | Séries e próximos números da NF-e, separados por ambiente. |
  | `data[].nfse` | objeto | sim | Configuração e séries da DPS (NFS-e nacional). |
  | `data[].certificate` | objeto ou null | sim |  |
  | `data[].createdAt` | texto | sim | date-time |
  | `data[].updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Consultar empresa

`GET /v1/companies/{id}`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da empresa. |

**Respostas**

- `200`: Empresa.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `cnpj` | texto | sim | até 14 caracteres |
  | `ie` | texto | sim | até 20 caracteres |
  | `im` | texto ou null | sim | até 15 caracteres |
  | `crt` | inteiro | sim | um de: `1`, `2`, `3`, `4` |
  | `legalName` | texto | sim | até 100000 caracteres |
  | `tradeName` | texto ou null | sim | até 100000 caracteres |
  | `email` | texto ou null | sim | até 100000 caracteres |
  | `address` | objeto | sim | Endereço, como cadastrado. |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `sandbox` | booleano | sim | true: empresa criada com chave de teste (fsk_test_); só emite em homologação. |
  | `nfe` | objeto | sim | Séries e próximos números da NF-e, separados por ambiente. |
  | `nfe.homologation` | objeto | sim |  |
  | `nfe.production` | objeto | sim |  |
  | `nfse` | objeto | sim | Configuração e séries da DPS (NFS-e nacional). |
  | `nfse.settings` | objeto | sim | Configuração da NFS-e (PUT /v1/companies/{id}/nfse-settings); campos não configurados vêm null. |
  | `nfse.homologation` | objeto | sim |  |
  | `nfse.production` | objeto | sim |  |
  | `certificate` | objeto ou null | sim |  |
  | `certificate.cnpj` | texto ou null | sim | até 14 caracteres |
  | `certificate.subjectName` | texto ou null | sim | até 100000 caracteres |
  | `certificate.issuer` | texto ou null | sim | até 100000 caracteres |
  | `certificate.serialNumber` | texto ou null | sim | até 100000 caracteres |
  | `certificate.notBefore` | texto | sim | date-time |
  | `certificate.notAfter` | texto | sim | date-time |
  | `certificate.uploadedAt` | texto | sim | date-time |
  | `certificate.status` | texto | sim | um de: `valid`, `expiring`, `expired` |
  | `certificate.daysLeft` | inteiro | sim |  |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada (ou de outro cliente).
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Alterar empresa

`PATCH /v1/companies/{id}`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da empresa. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `ie` | texto |  | Inscrição estadual (dígitos, com ou sem pontuação) ou "ISENTO". 2 a 20 caracteres |
| `im` | texto ou null |  | até 15 caracteres |
| `crt` | inteiro |  | Regime tributário (CRT): 1 Simples Nacional, 2 Simples com excesso de sublimite, 3 regime normal (Presumido ou Real), 4 MEI. um de: `1`, `2`, `3`, `4` |
| `legalName` | texto |  | 2 a 60 caracteres |
| `tradeName` | texto ou null |  | até 60 caracteres |
| `email` | texto ou null |  | email; até 254 caracteres |
| `address` | objeto |  | Endereço da empresa. cityCode é o código IBGE do município (7 dígitos). |
| `address.street` | texto | sim | 2 a 60 caracteres |
| `address.number` | texto | sim | até 60 caracteres |
| `address.complement` | texto ou null |  | até 60 caracteres |
| `address.district` | texto | sim | 2 a 60 caracteres |
| `address.cityName` | texto | sim | 2 a 60 caracteres |
| `address.cityCode` | texto | sim | padrão `^[0-9]{7}$` |
| `address.uf` | texto | sim | um de: `RO`, `AC`, `AM`, `RR`, `PA`, `AP`, `TO`, `MA`, `PI`, `CE`, `RN`, `PB`, `PE`, `AL`, `SE`, `BA`, `MG`, `ES`, `RJ`, `SP`, `PR`, `SC`, `RS`, `MS`, `MT`, `GO`, `DF` |
| `address.zip` | texto | sim | padrão `^[0-9]{8}$` |
| `address.phone` | texto ou null |  | padrão `^[0-9]{6,14}$` |
| `environment` | texto |  | homologation: testes, sem valor fiscal. production: notas com valor fiscal. um de: `homologation`, `production` |

**Respostas**

- `200`: Empresa alterada.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `cnpj` | texto | sim | até 14 caracteres |
  | `ie` | texto | sim | até 20 caracteres |
  | `im` | texto ou null | sim | até 15 caracteres |
  | `crt` | inteiro | sim | um de: `1`, `2`, `3`, `4` |
  | `legalName` | texto | sim | até 100000 caracteres |
  | `tradeName` | texto ou null | sim | até 100000 caracteres |
  | `email` | texto ou null | sim | até 100000 caracteres |
  | `address` | objeto | sim | Endereço, como cadastrado. |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `sandbox` | booleano | sim | true: empresa criada com chave de teste (fsk_test_); só emite em homologação. |
  | `nfe` | objeto | sim | Séries e próximos números da NF-e, separados por ambiente. |
  | `nfe.homologation` | objeto | sim |  |
  | `nfe.production` | objeto | sim |  |
  | `nfse` | objeto | sim | Configuração e séries da DPS (NFS-e nacional). |
  | `nfse.settings` | objeto | sim | Configuração da NFS-e (PUT /v1/companies/{id}/nfse-settings); campos não configurados vêm null. |
  | `nfse.homologation` | objeto | sim |  |
  | `nfse.production` | objeto | sim |  |
  | `certificate` | objeto ou null | sim |  |
  | `certificate.cnpj` | texto ou null | sim | até 14 caracteres |
  | `certificate.subjectName` | texto ou null | sim | até 100000 caracteres |
  | `certificate.issuer` | texto ou null | sim | até 100000 caracteres |
  | `certificate.serialNumber` | texto ou null | sim | até 100000 caracteres |
  | `certificate.notBefore` | texto | sim | date-time |
  | `certificate.notAfter` | texto | sim | date-time |
  | `certificate.uploadedAt` | texto | sim | date-time |
  | `certificate.status` | texto | sim | um de: `valid`, `expiring`, `expired` |
  | `certificate.daysLeft` | inteiro | sim |  |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada (ou de outro cliente).
- `422`: Dados inválidos; certificate_required ao pedir produção sem certificado; em sandbox, sandbox_homologation_only.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Cadastrar série da NF-e

`POST /v1/companies/{id}/nfe-series`

Inclui uma série com o próximo número. Útil para continuar a numeração de outro emissor.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da empresa. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `number` | inteiro | sim | Série (0 a 889; 890 em diante são reservadas ao Fisco). 0 a 889 |
| `next` | inteiro | sim | Próximo número a usar. 1 a 999999999 |
| `environment` | texto |  | Ambiente da série (padrão: o atual da empresa). um de: `homologation`, `production` |

**Respostas**

- `201`: Série incluída.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `cnpj` | texto | sim | até 14 caracteres |
  | `ie` | texto | sim | até 20 caracteres |
  | `im` | texto ou null | sim | até 15 caracteres |
  | `crt` | inteiro | sim | um de: `1`, `2`, `3`, `4` |
  | `legalName` | texto | sim | até 100000 caracteres |
  | `tradeName` | texto ou null | sim | até 100000 caracteres |
  | `email` | texto ou null | sim | até 100000 caracteres |
  | `address` | objeto | sim | Endereço, como cadastrado. |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `sandbox` | booleano | sim | true: empresa criada com chave de teste (fsk_test_); só emite em homologação. |
  | `nfe` | objeto | sim | Séries e próximos números da NF-e, separados por ambiente. |
  | `nfe.homologation` | objeto | sim |  |
  | `nfe.production` | objeto | sim |  |
  | `nfse` | objeto | sim | Configuração e séries da DPS (NFS-e nacional). |
  | `nfse.settings` | objeto | sim | Configuração da NFS-e (PUT /v1/companies/{id}/nfse-settings); campos não configurados vêm null. |
  | `nfse.homologation` | objeto | sim |  |
  | `nfse.production` | objeto | sim |  |
  | `certificate` | objeto ou null | sim |  |
  | `certificate.cnpj` | texto ou null | sim | até 14 caracteres |
  | `certificate.subjectName` | texto ou null | sim | até 100000 caracteres |
  | `certificate.issuer` | texto ou null | sim | até 100000 caracteres |
  | `certificate.serialNumber` | texto ou null | sim | até 100000 caracteres |
  | `certificate.notBefore` | texto | sim | date-time |
  | `certificate.notAfter` | texto | sim | date-time |
  | `certificate.uploadedAt` | texto | sim | date-time |
  | `certificate.status` | texto | sim | um de: `valid`, `expiring`, `expired` |
  | `certificate.daysLeft` | inteiro | sim |  |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada (ou de outro cliente).
- `409`: Série já cadastrada.
- `422`: Dados inválidos (validation_failed), com a lista de campos em details.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Cadastrar série da DPS (NFS-e)

`POST /v1/companies/{id}/nfse-series`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da empresa. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `number` | inteiro | sim | Série da DPS (1 a 49999). 1 a 49999 |
| `next` | inteiro | sim | 1 a 999999999999999 |
| `environment` | texto |  | homologation: testes, sem valor fiscal. production: notas com valor fiscal. um de: `homologation`, `production` |

**Respostas**

- `201`: Série incluída.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `cnpj` | texto | sim | até 14 caracteres |
  | `ie` | texto | sim | até 20 caracteres |
  | `im` | texto ou null | sim | até 15 caracteres |
  | `crt` | inteiro | sim | um de: `1`, `2`, `3`, `4` |
  | `legalName` | texto | sim | até 100000 caracteres |
  | `tradeName` | texto ou null | sim | até 100000 caracteres |
  | `email` | texto ou null | sim | até 100000 caracteres |
  | `address` | objeto | sim | Endereço, como cadastrado. |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `sandbox` | booleano | sim | true: empresa criada com chave de teste (fsk_test_); só emite em homologação. |
  | `nfe` | objeto | sim | Séries e próximos números da NF-e, separados por ambiente. |
  | `nfe.homologation` | objeto | sim |  |
  | `nfe.production` | objeto | sim |  |
  | `nfse` | objeto | sim | Configuração e séries da DPS (NFS-e nacional). |
  | `nfse.settings` | objeto | sim | Configuração da NFS-e (PUT /v1/companies/{id}/nfse-settings); campos não configurados vêm null. |
  | `nfse.homologation` | objeto | sim |  |
  | `nfse.production` | objeto | sim |  |
  | `certificate` | objeto ou null | sim |  |
  | `certificate.cnpj` | texto ou null | sim | até 14 caracteres |
  | `certificate.subjectName` | texto ou null | sim | até 100000 caracteres |
  | `certificate.issuer` | texto ou null | sim | até 100000 caracteres |
  | `certificate.serialNumber` | texto ou null | sim | até 100000 caracteres |
  | `certificate.notBefore` | texto | sim | date-time |
  | `certificate.notAfter` | texto | sim | date-time |
  | `certificate.uploadedAt` | texto | sim | date-time |
  | `certificate.status` | texto | sim | um de: `valid`, `expiring`, `expired` |
  | `certificate.daysLeft` | inteiro | sim |  |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada (ou de outro cliente).
- `409`: Série já cadastrada.
- `422`: Dados inválidos (validation_failed), com a lista de campos em details.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Configurar a NFS-e da empresa

`PUT /v1/companies/{id}/nfse-settings`

Regime de apuração do Simples, regime especial municipal, atividade do Simples (cAtvSN) e total aproximado dos tributos padrão.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da empresa. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `simplesTaxRegime` | inteiro |  | ME/EPP do Simples: regime de apuração (regApTribSN): 1 tributos federais e municipal pelo Simples, 2 federais pelo Simples e ISS pela NFS-e, 3 federais e municipal pela NFS-e. um de: `1`, `2`, `3` |
| `ibsCbsSimplesRegime` | inteiro |  | ME/EPP do Simples: apuração do IBS/CBS (regApIBSCBSSN, NT 009). um de: `1`, `2`, `3` |
| `specialRegime` | inteiro |  | Regime especial de tributação municipal (regEspTrib); 0 nenhum. um de: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `9` |
| `simplesActivity` | texto ou null |  | Atividade do Simples padrão da empresa (cAtvSN). um de: `07`, `08`, `09`, `10`, `11`, `12`, `13`, `14`, `90` |
| `approximateTaxes` | objeto ou null |  | Total aproximado dos tributos padrão das notas. |
| `approximateTaxes.simplesRate` | texto |  | Decimal em texto, com ponto e até 2 casas (máximo 99.99). |
| `approximateTaxes.rates` | objeto |  |  |
| `approximateTaxes.rates.federal` | texto | sim | Decimal em texto, com ponto e até 2 casas (máximo 100). |
| `approximateTaxes.rates.state` | texto | sim | Decimal em texto, com ponto e até 2 casas (máximo 100). |
| `approximateTaxes.rates.municipal` | texto | sim | Decimal em texto, com ponto e até 2 casas (máximo 100). |
| `approximateTaxes.amounts` | objeto |  |  |
| `approximateTaxes.amounts.federal` | texto | sim | Decimal em texto, com ponto e até 2 casas. |
| `approximateTaxes.amounts.state` | texto | sim | Decimal em texto, com ponto e até 2 casas. |
| `approximateTaxes.amounts.municipal` | texto | sim | Decimal em texto, com ponto e até 2 casas. |

**Respostas**

- `200`: Configuração salva.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `cnpj` | texto | sim | até 14 caracteres |
  | `ie` | texto | sim | até 20 caracteres |
  | `im` | texto ou null | sim | até 15 caracteres |
  | `crt` | inteiro | sim | um de: `1`, `2`, `3`, `4` |
  | `legalName` | texto | sim | até 100000 caracteres |
  | `tradeName` | texto ou null | sim | até 100000 caracteres |
  | `email` | texto ou null | sim | até 100000 caracteres |
  | `address` | objeto | sim | Endereço, como cadastrado. |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `sandbox` | booleano | sim | true: empresa criada com chave de teste (fsk_test_); só emite em homologação. |
  | `nfe` | objeto | sim | Séries e próximos números da NF-e, separados por ambiente. |
  | `nfe.homologation` | objeto | sim |  |
  | `nfe.production` | objeto | sim |  |
  | `nfse` | objeto | sim | Configuração e séries da DPS (NFS-e nacional). |
  | `nfse.settings` | objeto | sim | Configuração da NFS-e (PUT /v1/companies/{id}/nfse-settings); campos não configurados vêm null. |
  | `nfse.homologation` | objeto | sim |  |
  | `nfse.production` | objeto | sim |  |
  | `certificate` | objeto ou null | sim |  |
  | `certificate.cnpj` | texto ou null | sim | até 14 caracteres |
  | `certificate.subjectName` | texto ou null | sim | até 100000 caracteres |
  | `certificate.issuer` | texto ou null | sim | até 100000 caracteres |
  | `certificate.serialNumber` | texto ou null | sim | até 100000 caracteres |
  | `certificate.notBefore` | texto | sim | date-time |
  | `certificate.notAfter` | texto | sim | date-time |
  | `certificate.uploadedAt` | texto | sim | date-time |
  | `certificate.status` | texto | sim | um de: `valid`, `expiring`, `expired` |
  | `certificate.daysLeft` | inteiro | sim |  |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada (ou de outro cliente).
- `422`: Dados inválidos (validation_failed), com a lista de campos em details.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Enviar certificado digital A1

`PUT /v1/companies/{id}/certificate`

Envia o .pfx (e-CNPJ A1) em base64 com a senha. O certificado é conferido (CNPJ da empresa, validade, cadeia ICP-Brasil) e guardado cifrado. Substitui o anterior.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da empresa. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `pfxBase64` | texto | sim | Arquivo .pfx (certificado A1 e-CNPJ) em base64. padrão `^[A-Za-z0-9+/=\s]+$`; 100 a 700000 caracteres |
| `password` | texto | sim | Senha do .pfx. Não é guardada em texto: o certificado é cifrado no cofre. até 128 caracteres |

**Respostas**

- `200`: Certificado aceito.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `cnpj` | texto | sim | até 14 caracteres |
  | `ie` | texto | sim | até 20 caracteres |
  | `im` | texto ou null | sim | até 15 caracteres |
  | `crt` | inteiro | sim | um de: `1`, `2`, `3`, `4` |
  | `legalName` | texto | sim | até 100000 caracteres |
  | `tradeName` | texto ou null | sim | até 100000 caracteres |
  | `email` | texto ou null | sim | até 100000 caracteres |
  | `address` | objeto | sim | Endereço, como cadastrado. |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `sandbox` | booleano | sim | true: empresa criada com chave de teste (fsk_test_); só emite em homologação. |
  | `nfe` | objeto | sim | Séries e próximos números da NF-e, separados por ambiente. |
  | `nfe.homologation` | objeto | sim |  |
  | `nfe.production` | objeto | sim |  |
  | `nfse` | objeto | sim | Configuração e séries da DPS (NFS-e nacional). |
  | `nfse.settings` | objeto | sim | Configuração da NFS-e (PUT /v1/companies/{id}/nfse-settings); campos não configurados vêm null. |
  | `nfse.homologation` | objeto | sim |  |
  | `nfse.production` | objeto | sim |  |
  | `certificate` | objeto ou null | sim |  |
  | `certificate.cnpj` | texto ou null | sim | até 14 caracteres |
  | `certificate.subjectName` | texto ou null | sim | até 100000 caracteres |
  | `certificate.issuer` | texto ou null | sim | até 100000 caracteres |
  | `certificate.serialNumber` | texto ou null | sim | até 100000 caracteres |
  | `certificate.notBefore` | texto | sim | date-time |
  | `certificate.notAfter` | texto | sim | date-time |
  | `certificate.uploadedAt` | texto | sim | date-time |
  | `certificate.status` | texto | sim | um de: `valid`, `expiring`, `expired` |
  | `certificate.daysLeft` | inteiro | sim |  |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada (ou de outro cliente).
- `422`: certificate_*: senha errada, certificado vencido, de outro CNPJ ou fora da ICP-Brasil.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Situação da empresa

`GET /v1/companies/{id}/status`

Ambiente atual e situação do certificado.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da empresa. |

**Respostas**

- `200`: Situação.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `certificate` | objeto | sim |  |
  | `certificate.status` | texto | sim | expiring: vence em até 30 dias. um de: `missing`, `valid`, `expiring`, `expired` |
  | `certificate.daysLeft` | inteiro ou null | sim |  |
  | `certificate.notAfter` | texto ou null | sim | date-time |
  | `sefaz` | qualquer ou null | sim | Reservado (situação da SEFAZ). |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada (ou de outro cliente).
- `429`: Limite de requisições; espere o tempo de Retry-After.

## Classes de imposto

Regras de impostos por tipo de produto, para o item da nota só informar a classe.

### Criar classe de imposto

`POST /v1/companies/{id}/tax-classes`

Uma classe guarda as regras de CFOP, ICMS, IPI, PIS e COFINS de um tipo de produto, escolhidas por operação, destino e tipo de destinatário. O item da nota só informa taxClass.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da empresa. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `code` | texto | sim | Código da classe, usado em items[].taxClass. padrão `^[A-Za-z0-9_.-]+$`; até 30 caracteres |
| `name` | texto | sim | até 120 caracteres |
| `ibsCbs` | objeto ou null |  | Classificação do IBS/CBS fixa para a classe. Ausente: o motor decide; null: sem o grupo. |
| `ibsCbs.cst` | texto | sim | padrão `^[0-9]{3}$` |
| `ibsCbs.classTrib` | texto | sim | padrão `^[0-9]{6}$` |
| `rules` | lista de qualquer | sim |  |
| `rules[].when` | objeto |  | Quando a regra vale. Ausente: vale sempre. Vence a primeira regra que casar. |
| `rules[].when.operations` | lista de texto |  | um de: `sale`, `return`, `bonus`, `transfer` |
| `rules[].when.destination` | texto |  | internal dentro do estado, interstate para outro estado. um de: `internal`, `interstate` |
| `rules[].when.recipient` | texto |  | Tipo de destinatário (pelo ieIndicator 1, 2 ou 9). um de: `contributor`, `exempt`, `nonContributor` |
| `rules[].cfop` | texto | sim | padrão `^[0-9]{4}$` |
| `rules[].icms` | objeto | sim | ICMS do item. Informe cst (regime normal) ou csosn (Simples), um dos dois. |
| `rules[].icms.cst` | texto |  | CST do ICMS (regime normal). um de: `00`, `20`, `40`, `41`, `50`, `51`, `90` |
| `rules[].icms.csosn` | texto |  | CSOSN (Simples Nacional). um de: `101`, `102`, `103`, `300`, `400`, `900` |
| `rules[].icms.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `rules[].icms.baseReduction` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `rules[].icms.deferral` | texto |  | Decimal em texto, com ponto e até 2 casas (máximo 100). |
| `rules[].icms.creditRate` | texto |  | Alíquota do crédito do Simples (CSOSN 101 e 900). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `rules[].icms.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `rules[].ipi` | objeto ou null |  |  |
| `rules[].ipi.cst` | texto | sim | um de: `00`, `01`, `02`, `03`, `04`, `05`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `99` |
| `rules[].ipi.enquadramento` | texto |  | Código de enquadramento legal do IPI (padrão 999). padrão `^[0-9]{3}$` |
| `rules[].ipi.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `rules[].ipi.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `rules[].pis` | objeto | sim |  |
| `rules[].pis.cst` | texto | sim | um de: `01`, `02`, `04`, `05`, `06`, `07`, `08`, `09`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `56`, `60`, `61`, `62`, `63`, `64`, `65`, `66`, `67`, `70`, `71`, `72`, `73`, `74`, `75`, `98`, `99` |
| `rules[].pis.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `rules[].pis.base` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `rules[].pis.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `rules[].cofins` | objeto | sim |  |
| `rules[].cofins.cst` | texto | sim | um de: `01`, `02`, `04`, `05`, `06`, `07`, `08`, `09`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `56`, `60`, `61`, `62`, `63`, `64`, `65`, `66`, `67`, `70`, `71`, `72`, `73`, `74`, `75`, `98`, `99` |
| `rules[].cofins.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `rules[].cofins.base` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `rules[].cofins.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |

**Respostas**

- `201`: Classe criada.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `code` | texto | sim | até 30 caracteres |
  | `name` | texto | sim | até 100000 caracteres |
  | `ibsCbs` | objeto ou null |  | Classificação do IBS/CBS fixa da classe; null: sem o grupo. Ausente: o motor decide. |
  | `rules` | lista de objeto | sim |  |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa ou classe não encontrada.
- `409`: Já existe uma classe com este código.
- `422`: Dados inválidos (validation_failed), com a lista de campos em details.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Listar classes de imposto

`GET /v1/companies/{id}/tax-classes`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da empresa. |

**Respostas**

- `200`: Classes.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `data` | lista de qualquer | sim |  |
  | `data[].code` | texto | sim | até 30 caracteres |
  | `data[].name` | texto | sim | até 100000 caracteres |
  | `data[].ibsCbs` | objeto ou null |  | Classificação do IBS/CBS fixa da classe; null: sem o grupo. Ausente: o motor decide. |
  | `data[].rules` | lista de objeto | sim |  |
  | `data[].createdAt` | texto | sim | date-time |
  | `data[].updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa ou classe não encontrada.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Consultar classe de imposto

`GET /v1/companies/{id}/tax-classes/{code}`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da empresa. |
| `code` | caminho | sim | Código da classe. |

**Respostas**

- `200`: Classe.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `code` | texto | sim | até 30 caracteres |
  | `name` | texto | sim | até 100000 caracteres |
  | `ibsCbs` | objeto ou null |  | Classificação do IBS/CBS fixa da classe; null: sem o grupo. Ausente: o motor decide. |
  | `rules` | lista de objeto | sim |  |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa ou classe não encontrada.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Substituir classe de imposto

`PUT /v1/companies/{id}/tax-classes/{code}`

Troca a classe inteira (o code do corpo é ignorado; vale o da URL).

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da empresa. |
| `code` | caminho | sim | Código da classe. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `code` | texto | sim | Código da classe, usado em items[].taxClass. padrão `^[A-Za-z0-9_.-]+$`; até 30 caracteres |
| `name` | texto | sim | até 120 caracteres |
| `ibsCbs` | objeto ou null |  | Classificação do IBS/CBS fixa para a classe. Ausente: o motor decide; null: sem o grupo. |
| `ibsCbs.cst` | texto | sim | padrão `^[0-9]{3}$` |
| `ibsCbs.classTrib` | texto | sim | padrão `^[0-9]{6}$` |
| `rules` | lista de qualquer | sim |  |
| `rules[].when` | objeto |  | Quando a regra vale. Ausente: vale sempre. Vence a primeira regra que casar. |
| `rules[].when.operations` | lista de texto |  | um de: `sale`, `return`, `bonus`, `transfer` |
| `rules[].when.destination` | texto |  | internal dentro do estado, interstate para outro estado. um de: `internal`, `interstate` |
| `rules[].when.recipient` | texto |  | Tipo de destinatário (pelo ieIndicator 1, 2 ou 9). um de: `contributor`, `exempt`, `nonContributor` |
| `rules[].cfop` | texto | sim | padrão `^[0-9]{4}$` |
| `rules[].icms` | objeto | sim | ICMS do item. Informe cst (regime normal) ou csosn (Simples), um dos dois. |
| `rules[].icms.cst` | texto |  | CST do ICMS (regime normal). um de: `00`, `20`, `40`, `41`, `50`, `51`, `90` |
| `rules[].icms.csosn` | texto |  | CSOSN (Simples Nacional). um de: `101`, `102`, `103`, `300`, `400`, `900` |
| `rules[].icms.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `rules[].icms.baseReduction` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `rules[].icms.deferral` | texto |  | Decimal em texto, com ponto e até 2 casas (máximo 100). |
| `rules[].icms.creditRate` | texto |  | Alíquota do crédito do Simples (CSOSN 101 e 900). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `rules[].icms.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `rules[].ipi` | objeto ou null |  |  |
| `rules[].ipi.cst` | texto | sim | um de: `00`, `01`, `02`, `03`, `04`, `05`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `99` |
| `rules[].ipi.enquadramento` | texto |  | Código de enquadramento legal do IPI (padrão 999). padrão `^[0-9]{3}$` |
| `rules[].ipi.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `rules[].ipi.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `rules[].pis` | objeto | sim |  |
| `rules[].pis.cst` | texto | sim | um de: `01`, `02`, `04`, `05`, `06`, `07`, `08`, `09`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `56`, `60`, `61`, `62`, `63`, `64`, `65`, `66`, `67`, `70`, `71`, `72`, `73`, `74`, `75`, `98`, `99` |
| `rules[].pis.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `rules[].pis.base` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `rules[].pis.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `rules[].cofins` | objeto | sim |  |
| `rules[].cofins.cst` | texto | sim | um de: `01`, `02`, `04`, `05`, `06`, `07`, `08`, `09`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `56`, `60`, `61`, `62`, `63`, `64`, `65`, `66`, `67`, `70`, `71`, `72`, `73`, `74`, `75`, `98`, `99` |
| `rules[].cofins.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `rules[].cofins.base` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `rules[].cofins.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |

**Respostas**

- `200`: Classe substituída.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `code` | texto | sim | até 30 caracteres |
  | `name` | texto | sim | até 100000 caracteres |
  | `ibsCbs` | objeto ou null |  | Classificação do IBS/CBS fixa da classe; null: sem o grupo. Ausente: o motor decide. |
  | `rules` | lista de objeto | sim |  |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa ou classe não encontrada.
- `422`: Dados inválidos (validation_failed), com a lista de campos em details.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Apagar classe de imposto

`DELETE /v1/companies/{id}/tax-classes/{code}`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da empresa. |
| `code` | caminho | sim | Código da classe. |

**Respostas**

- `204`: Apagada.
- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa ou classe não encontrada.
- `429`: Limite de requisições; espere o tempo de Retry-After.

## NF-e

Nota fiscal eletrônica (modelo 55): emissão assíncrona, consulta, XML, DANFE, eventos e inutilização.

### Exportar o mês (zip para o contador)

`GET /v1/nfe/export`

Zip com os XMLs do mês (notas, eventos e inutilizações), um resumo.csv e, com danfe=1, os DANFEs. Sai em streaming.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `companyId` | query | sim | id da empresa. padrão `^[0-9a-f]{24}$`; 24 caracteres |
| `month` | query | sim | Mês AAAA-MM. padrão `^\d{4}-(0[1-9]\|1[0-2])$`; 7 caracteres |
| `environment` | query |  | Padrão: o ambiente atual da empresa. um de: `production`, `homologation` |
| `danfe` | query |  | 1 inclui os DANFEs em PDF. um de: `0`, `1` |

**Respostas**

- `200`: Arquivo zip. (application/zip)
- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada.
- `422`: Parâmetros inválidos; too_many_danfes quando o mês tem notas demais para incluir os DANFEs.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Inutilizar faixa de números

`POST /v1/nfe/disable-range`

Inutiliza números pulados ou de notas que não foram autorizadas (veja GET /v1/nfe/gaps). Assíncrono: o resultado chega pelo webhook nfe.disabled ou em GET /v1/nfe/disablements/{id}.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `companyId` | texto | sim | id da empresa emitente (devolvido em POST /v1/companies). padrão `^[0-9a-f]{24}$`; 24 caracteres |
| `series` | inteiro | sim | 0 a 889 |
| `from` | inteiro | sim | 1 a 999999999 |
| `to` | inteiro | sim | 1 a 999999999 |
| `justification` | texto | sim | 15 a 255 caracteres |

**Respostas**

- `200`: O mesmo pedido já existia.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `series` | inteiro | sim |  |
  | `from` | inteiro | sim |  |
  | `to` | inteiro | sim |  |
  | `justification` | texto | sim | até 100000 caracteres |
  | `status` | texto | sim | um de: `queued`, `sending`, `unknown`, `disabled`, `rejected`, `failed` |
  | `protocol` | texto ou null | sim | até 20 caracteres |
  | `disabledAt` | texto ou null | sim | date-time |
  | `rejection` | objeto ou null | sim |  |
  | `rejection.cStat` | texto | sim | até 10 caracteres |
  | `rejection.reason` | texto | sim | até 100000 caracteres |
  | `rejection.at` | texto | sim | date-time |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `202`: Pedido aceito e na fila.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `series` | inteiro | sim |  |
  | `from` | inteiro | sim |  |
  | `to` | inteiro | sim |  |
  | `justification` | texto | sim | até 100000 caracteres |
  | `status` | texto | sim | um de: `queued`, `sending`, `unknown`, `disabled`, `rejected`, `failed` |
  | `protocol` | texto ou null | sim | até 20 caracteres |
  | `disabledAt` | texto ou null | sim | date-time |
  | `rejection` | objeto ou null | sim |  |
  | `rejection.cStat` | texto | sim | até 10 caracteres |
  | `rejection.reason` | texto | sim | até 100000 caracteres |
  | `rejection.at` | texto | sim | date-time |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `400`: companyId inválido.
- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada.
- `409`: Faixa sobreposta a outra inutilização ou com notas em uso.
- `422`: series_missing, range_invalid, range_too_large, range_not_reserved, certificate_unavailable.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Números pulados da série

`GET /v1/nfe/gaps`

Faixas que não viraram nota autorizada nem foram inutilizadas. O Fisco exige inutilizar esses números.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `companyId` | query | sim | id da empresa. padrão `^[0-9a-f]{24}$`; 24 caracteres |
| `series` | query | sim | Série. 0 a 889 |

**Respostas**

- `200`: Faixas.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `series` | inteiro | sim |  |
  | `next` | inteiro | sim | Próximo número da série. |
  | `gaps` | lista de objeto | sim | Faixas sem nota autorizada nem inutilizada. Inutilize com POST /v1/nfe/disable-range. |
  | `gaps[].from` | inteiro | sim |  |
  | `gaps[].to` | inteiro | sim |  |
  | `gaps[].reason` | texto | sim | unused: número pulado; rejected ou failed: nota que não foi autorizada; disabling: inutilização em andamento. até 30 caracteres |
  | `gaps[].documentIds` | lista de texto | sim | Notas da faixa que não foram autorizadas. padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `truncated` | booleano | sim | true: a busca parou em 100 mil números. |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada.
- `422`: series_missing ou parâmetros inválidos.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Consultar inutilização

`GET /v1/nfe/disablements/{id}`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da inutilização. |

**Respostas**

- `200`: Inutilização.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `series` | inteiro | sim |  |
  | `from` | inteiro | sim |  |
  | `to` | inteiro | sim |  |
  | `justification` | texto | sim | até 100000 caracteres |
  | `status` | texto | sim | um de: `queued`, `sending`, `unknown`, `disabled`, `rejected`, `failed` |
  | `protocol` | texto ou null | sim | até 20 caracteres |
  | `disabledAt` | texto ou null | sim | date-time |
  | `rejection` | objeto ou null | sim |  |
  | `rejection.cStat` | texto | sim | até 10 caracteres |
  | `rejection.reason` | texto | sim | até 100000 caracteres |
  | `rejection.at` | texto | sim | date-time |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Inutilização não encontrada.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### XML da inutilização

`GET /v1/nfe/disablements/{id}/xml`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da inutilização. |

**Respostas**

- `200`: procInutNFe. (application/xml)
- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Inutilização não encontrada.
- `409`: Inutilização ainda não registrada.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Reenviar inutilização com falha

`POST /v1/nfe/disablements/{id}/retry`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da inutilização. |

**Respostas**

- `202`: De volta à fila.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `series` | inteiro | sim |  |
  | `from` | inteiro | sim |  |
  | `to` | inteiro | sim |  |
  | `justification` | texto | sim | até 100000 caracteres |
  | `status` | texto | sim | um de: `queued`, `sending`, `unknown`, `disabled`, `rejected`, `failed` |
  | `protocol` | texto ou null | sim | até 20 caracteres |
  | `disabledAt` | texto ou null | sim | date-time |
  | `rejection` | objeto ou null | sim |  |
  | `rejection.cStat` | texto | sim | até 10 caracteres |
  | `rejection.reason` | texto | sim | até 100000 caracteres |
  | `rejection.at` | texto | sim | date-time |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Inutilização não encontrada.
- `409`: Só inutilizações com falha podem ser reenviadas.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Emitir NF-e

`POST /v1/nfe`

Calcula os impostos (IBS/CBS incluídos), monta, assina e envia a NF-e (modelo 55) em segundo plano. Responde 202 na hora; o resultado chega pelo webhook (nfe.authorized, nfe.rejected...) ou em GET /v1/nfe/{id}. O externalId é a chave de idempotência: repetir o pedido devolve a mesma nota com 200; reenviar uma nota rejeitada com o mesmo externalId e o pedido corrigido tenta de novo com o mesmo número.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `externalId` | texto | sim | Seu identificador do pedido. Também é a chave de idempotência: repetir o mesmo externalId devolve a mesma nota (200), nunca uma segunda. até 100 caracteres |
| `companyId` | texto | sim | id da empresa emitente (devolvido em POST /v1/companies). padrão `^[0-9a-f]{24}$`; 24 caracteres |
| `operation` | texto | sim | sale venda, return devolução, bonus bonificação, transfer transferência. um de: `sale`, `return`, `bonus`, `transfer` |
| `direction` | texto |  | Só em devolução: out nota de saída (padrão), in nota de entrada. um de: `out`, `in` |
| `series` | inteiro |  | Série (padrão: a série padrão da empresa no ambiente). 0 a 889 |
| `natureOfOperation` | texto | sim | Natureza da operação impressa na nota (ex.: "Venda de mercadoria"). até 60 caracteres |
| `presence` | texto |  | Indicador de presença do comprador (indPres): 0 não se aplica, 1 presencial, 2 internet, 3 teleatendimento, 4 entrega a domicílio, 5 presencial fora do estabelecimento, 9 outros. um de: `0`, `1`, `2`, `3`, `4`, `5`, `9` |
| `finalConsumer` | booleano |  | Venda a consumidor final (indFinal). |
| `recipient` | objeto | sim | Destinatário. Informe cnpj ou cpf (um dos dois). |
| `recipient.cnpj` | texto |  | CNPJ, com ou sem pontuação (aceita o CNPJ alfanumérico). 14 a 18 caracteres |
| `recipient.cpf` | texto |  | CPF, 11 dígitos. padrão `^[0-9]{11}$` |
| `recipient.name` | texto | sim | 2 a 60 caracteres |
| `recipient.ieIndicator` | texto | sim | Indicador da IE do destinatário: 1 contribuinte do ICMS (informe ie), 2 isento, 9 não contribuinte. um de: `1`, `2`, `9` |
| `recipient.ie` | texto ou null |  | Inscrição estadual (dígitos, com ou sem pontuação) ou "ISENTO". 2 a 20 caracteres |
| `recipient.email` | texto ou null |  | Recebe o XML e o DANFE, se a empresa enviar. email; até 254 caracteres |
| `recipient.address` | objeto | sim |  |
| `recipient.address.street` | texto | sim | 2 a 60 caracteres |
| `recipient.address.number` | texto | sim | até 60 caracteres |
| `recipient.address.complement` | texto ou null |  | até 60 caracteres |
| `recipient.address.district` | texto | sim | 2 a 60 caracteres |
| `recipient.address.cityName` | texto | sim | 2 a 60 caracteres |
| `recipient.address.cityCode` | texto | sim | padrão `^[0-9]{7}$` |
| `recipient.address.uf` | texto | sim | um de: `RO`, `AC`, `AM`, `RR`, `PA`, `AP`, `TO`, `MA`, `PI`, `CE`, `RN`, `PB`, `PE`, `AL`, `SE`, `BA`, `MG`, `ES`, `RJ`, `SP`, `PR`, `SC`, `RS`, `MS`, `MT`, `GO`, `DF` |
| `recipient.address.zip` | texto ou null |  | padrão `^[0-9]{8}$` |
| `recipient.address.phone` | texto ou null |  | padrão `^[0-9]{6,14}$` |
| `items` | lista de qualquer | sim |  |
| `items[].code` | texto | sim | Código do produto no seu sistema. até 60 caracteres |
| `items[].description` | texto | sim | até 120 caracteres |
| `items[].ncm` | texto | sim | NCM do produto (8 dígitos). padrão `^[0-9]{8}$` |
| `items[].cest` | texto ou null |  | padrão `^[0-9]{7}$` |
| `items[].gtin` | texto ou null |  | Código de barras (GTIN) ou "SEM GTIN". padrão `^(SEM GTIN\|\d{8}\|\d{12,14})$`; até 14 caracteres |
| `items[].origin` | texto | sim | Origem da mercadoria: 0 nacional; 1 a 8 importada ou com conteúdo importado (tabela do ICMS). um de: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` |
| `items[].cfop` | texto |  | CFOP. Obrigatório sem taxClass; com taxClass, vem da classe. padrão `^[0-9]{4}$` |
| `items[].taxClass` | texto |  | Código de uma classe de imposto da empresa (POST /v1/companies/{id}/tax-classes): CFOP, ICMS, IPI, PIS e COFINS saem dela. padrão `^[A-Za-z0-9_.-]+$`; até 30 caracteres |
| `items[].unit` | texto | sim | Unidade comercial (ex.: UN, KG, PAR). até 6 caracteres |
| `items[].quantity` | texto | sim | Decimal em texto, com ponto e até 4 casas (mínimo 0.0001). |
| `items[].unitPrice` | texto | sim | Preço unitário bruto. padrão `^[0-9]{1,15}(\.[0-9]{1,10})?$` |
| `items[].netUnitPrice` | texto |  | Preço unitário líquido, quando a empresa calcula pelo líquido. padrão `^[0-9]{1,15}(\.[0-9]{1,10})?$` |
| `items[].discount` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].freight` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].insurance` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].otherExpenses` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].approxTaxes` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].purchaseOrder` | texto ou null |  | até 15 caracteres |
| `items[].purchaseOrderItem` | texto ou null |  | padrão `^[0-9]{1,6}$` |
| `items[].additionalInfo` | texto ou null |  | até 500 caracteres |
| `items[].reference` | objeto |  | Só em devolução: a NF-e original e o número do item nela. |
| `items[].reference.accessKey` | texto | sim | Chave de acesso de 44 caracteres. padrão `^[0-9]{6}[0-9A-Z]{12}[0-9]{26}$`; 44 caracteres |
| `items[].reference.item` | inteiro |  | 1 a 990 |
| `items[].returnedIpi` | objeto |  | Só em devolução: IPI devolvido. |
| `items[].returnedIpi.value` | texto | sim | Decimal em texto, com ponto e até 2 casas. |
| `items[].returnedIpi.percent` | texto |  | Decimal em texto, com ponto e até 2 casas (mínimo 0.01, máximo 100). |
| `items[].taxes` | objeto |  | Impostos do item. Sem taxClass, informe icms, pis e cofins. Com taxClass, o que vier aqui prevalece sobre a classe. |
| `items[].taxes.icms` | objeto |  | ICMS do item. Informe cst (regime normal) ou csosn (Simples), um dos dois. |
| `items[].taxes.icms.cst` | texto |  | CST do ICMS (regime normal). um de: `00`, `20`, `40`, `41`, `50`, `51`, `90` |
| `items[].taxes.icms.csosn` | texto |  | CSOSN (Simples Nacional). um de: `101`, `102`, `103`, `300`, `400`, `900` |
| `items[].taxes.icms.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.icms.baseReduction` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.icms.deferral` | texto |  | Decimal em texto, com ponto e até 2 casas (máximo 100). |
| `items[].taxes.icms.creditRate` | texto |  | Alíquota do crédito do Simples (CSOSN 101 e 900). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.icms.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.ipi` | objeto ou null |  |  |
| `items[].taxes.ipi.cst` | texto | sim | um de: `00`, `01`, `02`, `03`, `04`, `05`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `99` |
| `items[].taxes.ipi.enquadramento` | texto |  | Código de enquadramento legal do IPI (padrão 999). padrão `^[0-9]{3}$` |
| `items[].taxes.ipi.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.ipi.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.pis` | objeto |  |  |
| `items[].taxes.pis.cst` | texto | sim | um de: `01`, `02`, `04`, `05`, `06`, `07`, `08`, `09`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `56`, `60`, `61`, `62`, `63`, `64`, `65`, `66`, `67`, `70`, `71`, `72`, `73`, `74`, `75`, `98`, `99` |
| `items[].taxes.pis.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.pis.base` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.pis.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.cofins` | objeto |  |  |
| `items[].taxes.cofins.cst` | texto | sim | um de: `01`, `02`, `04`, `05`, `06`, `07`, `08`, `09`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `56`, `60`, `61`, `62`, `63`, `64`, `65`, `66`, `67`, `70`, `71`, `72`, `73`, `74`, `75`, `98`, `99` |
| `items[].taxes.cofins.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.cofins.base` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.cofins.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.ibsCbs` | objeto ou null |  | Ausente: o motor decide o IBS/CBS. null: nota sem o grupo do IBS/CBS. |
| `items[].taxes.ibsCbs.cst` | texto | sim | CST do IBS/CBS (tabela da Reforma Tributária; veja GET /v1/tax/classifications). padrão `^[0-9]{3}$` |
| `items[].taxes.ibsCbs.classTrib` | texto | sim | cClassTrib: classificação tributária do IBS/CBS (veja GET /v1/tax/classifications). padrão `^[0-9]{6}$` |
| `items[].taxes.ibsCbs.ibsUfRate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.ibsCbs.ibsMunRate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.ibsCbs.cbsRate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.ibsCbs.donation` | booleano |  |  |
| `items[].taxes.ibsCbs.ibsValue` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.ibsCbs.cbsValue` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `charges` | objeto |  |  |
| `charges.freight` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `charges.insurance` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `charges.otherExpenses` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `charges.discount` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `transport` | objeto | sim |  |
| `transport.mode` | texto | sim | Modalidade do frete: 0 por conta do emitente, 1 do destinatário, 2 de terceiros, 3 próprio do emitente, 4 próprio do destinatário, 9 sem frete. um de: `0`, `1`, `2`, `3`, `4`, `9` |
| `transport.carrier` | objeto ou null |  |  |
| `transport.carrier.cnpj` | texto |  | CNPJ, com ou sem pontuação (aceita o CNPJ alfanumérico). 14 a 18 caracteres |
| `transport.carrier.cpf` | texto |  | CPF, 11 dígitos. padrão `^[0-9]{11}$` |
| `transport.carrier.name` | texto | sim | 2 a 60 caracteres |
| `transport.carrier.ie` | texto ou null |  | Inscrição estadual (dígitos, com ou sem pontuação) ou "ISENTO". 2 a 20 caracteres |
| `transport.carrier.address` | texto ou null |  | até 60 caracteres |
| `transport.carrier.city` | texto ou null |  | até 60 caracteres |
| `transport.carrier.uf` | texto ou null |  | um de: `RO`, `AC`, `AM`, `RR`, `PA`, `AP`, `TO`, `MA`, `PI`, `CE`, `RN`, `PB`, `PE`, `AL`, `SE`, `BA`, `MG`, `ES`, `RJ`, `SP`, `PR`, `SC`, `RS`, `MS`, `MT`, `GO`, `DF` |
| `transport.volumes` | lista de objeto |  |  |
| `transport.volumes[].quantity` | inteiro |  | 0 a 999999999999999 |
| `transport.volumes[].species` | texto |  | até 60 caracteres |
| `transport.volumes[].brand` | texto |  | até 60 caracteres |
| `transport.volumes[].numbering` | texto |  | até 60 caracteres |
| `transport.volumes[].netWeight` | texto |  | Decimal em texto, com ponto e até 3 casas. |
| `transport.volumes[].grossWeight` | texto |  | Decimal em texto, com ponto e até 3 casas. |
| `payments` | lista de objeto | sim |  |
| `payments[].method` | texto | sim | Meio de pagamento (tPag): 01 dinheiro, 03 cartão de crédito, 04 cartão de débito, 15 boleto, 17 PIX, 90 sem pagamento, 99 outros. padrão `^[0-9]{2}$` |
| `payments[].amount` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `payments[].description` | texto |  | Descrição do meio quando method é 99. até 60 caracteres |
| `payments[].term` | texto |  | cash à vista, installments a prazo. um de: `cash`, `installments` |
| `billing` | objeto ou null |  | Fatura e duplicatas (vendas a prazo). |
| `billing.number` | texto |  | até 60 caracteres |
| `billing.installments` | lista de objeto | sim |  |
| `billing.installments[].dueDate` | texto | sim | date; padrão `^\d{4}-(0[1-9]\|1[0-2])-(0[1-9]\|[12]\d\|3[01])$`; 10 caracteres |
| `billing.installments[].amount` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `purchaseOrder` | texto ou null |  | até 60 caracteres |
| `additionalInfo` | texto ou null |  | Informações complementares de interesse do contribuinte. até 4000 caracteres |
| `fiscalInfo` | texto ou null |  | Informações de interesse do Fisco. até 2000 caracteres |
| `expectedTotal` | texto |  | Total que você espera. Se o calculado for diferente, a nota é recusada antes de ir à SEFAZ. padrão `^[0-9]{1,15}(\.[0-9]{1,2})?$` |

Exemplo:

```json
{
  "externalId": "pedido-1234",
  "companyId": "6710a1b2c3d4e5f601234567",
  "operation": "sale",
  "natureOfOperation": "Venda de produção do estabelecimento",
  "recipient": {
    "cnpj": "11444777000161",
    "name": "Loja Exemplo Comércio de Calçados Ltda",
    "ieIndicator": "1",
    "ie": "123456785004",
    "email": "fiscal@lojaexemplo.com.br",
    "address": {
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "cityName": "São Paulo",
      "cityCode": "3550308",
      "uf": "SP",
      "zip": "01310100"
    }
  },
  "items": [
    {
      "code": "BOT-COURO-38",
      "description": "Bota de couro cano médio nº 38",
      "ncm": "64039190",
      "origin": "0",
      "cfop": "5101",
      "unit": "PAR",
      "quantity": "10",
      "unitPrice": "129.90",
      "taxes": {
        "icms": {
          "csosn": "101",
          "creditRate": "1.25"
        },
        "pis": {
          "cst": "49"
        },
        "cofins": {
          "cst": "49"
        }
      }
    }
  ],
  "transport": {
    "mode": "0"
  },
  "payments": [
    {
      "method": "15"
    }
  ],
  "billing": {
    "installments": [
      {
        "dueDate": "2026-11-30"
      }
    ]
  }
}
```

**Respostas**

- `200`: Pedido repetido: a nota que já existe.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `externalId` | texto | sim | até 100 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `status` | texto | sim | queued/sending/pending: em andamento. unknown: resposta perdida, em conferência com a SEFAZ. authorized, rejected, denied, failed: resultado. cancelled e disabled: depois de um evento. um de: `queued`, `sending`, `pending`, `unknown`, `authorized`, `rejected`, `denied`, `failed`, `cancelled`, `disabled` |
  | `series` | inteiro | sim |  |
  | `number` | inteiro ou null | sim |  |
  | `accessKey` | texto ou null | sim | Chave de acesso (44 caracteres na NF-e; 50 na NFS-e). até 50 caracteres |
  | `protocol` | texto ou null | sim | até 20 caracteres |
  | `authorizedAt` | texto ou null | sim | date-time |
  | `rejection` | objeto ou null | sim | Última rejeição da SEFAZ (status rejected). Corrija e reenvie com o mesmo externalId. |
  | `rejection.cStat` | texto | sim | até 10 caracteres |
  | `rejection.reason` | texto | sim | até 100000 caracteres |
  | `rejection.at` | texto | sim | date-time |
  | `denial` | objeto ou null | sim |  |
  | `denial.cStat` | texto ou null | sim | até 10 caracteres |
  | `denial.reason` | texto ou null | sim | até 100000 caracteres |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `totals` | objeto ou null | sim | Totais calculados (produtos, impostos, total da nota), em texto decimal. |
  | `warnings` | lista de texto | sim | Avisos do cálculo; não impedem a emissão. até 100000 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `202`: Aceita e na fila. Header Location com o endereço da nota.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `externalId` | texto | sim | até 100 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `status` | texto | sim | queued/sending/pending: em andamento. unknown: resposta perdida, em conferência com a SEFAZ. authorized, rejected, denied, failed: resultado. cancelled e disabled: depois de um evento. um de: `queued`, `sending`, `pending`, `unknown`, `authorized`, `rejected`, `denied`, `failed`, `cancelled`, `disabled` |
  | `series` | inteiro | sim |  |
  | `number` | inteiro ou null | sim |  |
  | `accessKey` | texto ou null | sim | Chave de acesso (44 caracteres na NF-e; 50 na NFS-e). até 50 caracteres |
  | `protocol` | texto ou null | sim | até 20 caracteres |
  | `authorizedAt` | texto ou null | sim | date-time |
  | `rejection` | objeto ou null | sim | Última rejeição da SEFAZ (status rejected). Corrija e reenvie com o mesmo externalId. |
  | `rejection.cStat` | texto | sim | até 10 caracteres |
  | `rejection.reason` | texto | sim | até 100000 caracteres |
  | `rejection.at` | texto | sim | date-time |
  | `denial` | objeto ou null | sim |  |
  | `denial.cStat` | texto ou null | sim | até 10 caracteres |
  | `denial.reason` | texto ou null | sim | até 100000 caracteres |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `totals` | objeto ou null | sim | Totais calculados (produtos, impostos, total da nota), em texto decimal. |
  | `warnings` | lista de texto | sim | Avisos do cálculo; não impedem a emissão. até 100000 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada.
- `409`: externalId já usado com outro conteúdo, ou nota em situação que não aceita reenvio.
- `422`: Dados inválidos; series_missing, certificate_unavailable, model_invalid, sandbox_homologation_only, total diferente de expectedTotal.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Buscar NF-e pelo externalId

`GET /v1/nfe`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `externalId` | query | sim | O seu identificador do pedido. até 100 caracteres |

**Respostas**

- `200`: NF-e.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `externalId` | texto | sim | até 100 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `status` | texto | sim | queued/sending/pending: em andamento. unknown: resposta perdida, em conferência com a SEFAZ. authorized, rejected, denied, failed: resultado. cancelled e disabled: depois de um evento. um de: `queued`, `sending`, `pending`, `unknown`, `authorized`, `rejected`, `denied`, `failed`, `cancelled`, `disabled` |
  | `series` | inteiro | sim |  |
  | `number` | inteiro ou null | sim |  |
  | `accessKey` | texto ou null | sim | Chave de acesso (44 caracteres na NF-e; 50 na NFS-e). até 50 caracteres |
  | `protocol` | texto ou null | sim | até 20 caracteres |
  | `authorizedAt` | texto ou null | sim | date-time |
  | `rejection` | objeto ou null | sim | Última rejeição da SEFAZ (status rejected). Corrija e reenvie com o mesmo externalId. |
  | `rejection.cStat` | texto | sim | até 10 caracteres |
  | `rejection.reason` | texto | sim | até 100000 caracteres |
  | `rejection.at` | texto | sim | date-time |
  | `denial` | objeto ou null | sim |  |
  | `denial.cStat` | texto ou null | sim | até 10 caracteres |
  | `denial.reason` | texto ou null | sim | até 100000 caracteres |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `totals` | objeto ou null | sim | Totais calculados (produtos, impostos, total da nota), em texto decimal. |
  | `warnings` | lista de texto | sim | Avisos do cálculo; não impedem a emissão. até 100000 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NF-e não encontrada.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Consultar NF-e

`GET /v1/nfe/{id}`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NF-e. |

**Respostas**

- `200`: NF-e.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `externalId` | texto | sim | até 100 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `status` | texto | sim | queued/sending/pending: em andamento. unknown: resposta perdida, em conferência com a SEFAZ. authorized, rejected, denied, failed: resultado. cancelled e disabled: depois de um evento. um de: `queued`, `sending`, `pending`, `unknown`, `authorized`, `rejected`, `denied`, `failed`, `cancelled`, `disabled` |
  | `series` | inteiro | sim |  |
  | `number` | inteiro ou null | sim |  |
  | `accessKey` | texto ou null | sim | Chave de acesso (44 caracteres na NF-e; 50 na NFS-e). até 50 caracteres |
  | `protocol` | texto ou null | sim | até 20 caracteres |
  | `authorizedAt` | texto ou null | sim | date-time |
  | `rejection` | objeto ou null | sim | Última rejeição da SEFAZ (status rejected). Corrija e reenvie com o mesmo externalId. |
  | `rejection.cStat` | texto | sim | até 10 caracteres |
  | `rejection.reason` | texto | sim | até 100000 caracteres |
  | `rejection.at` | texto | sim | date-time |
  | `denial` | objeto ou null | sim |  |
  | `denial.cStat` | texto ou null | sim | até 10 caracteres |
  | `denial.reason` | texto ou null | sim | até 100000 caracteres |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `totals` | objeto ou null | sim | Totais calculados (produtos, impostos, total da nota), em texto decimal. |
  | `warnings` | lista de texto | sim | Avisos do cálculo; não impedem a emissão. até 100000 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NF-e não encontrada.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### XML autorizado (procNFe)

`GET /v1/nfe/{id}/xml`

Disponível para nota autorizada, denegada ou cancelada. É o arquivo que o emitente deve guardar por 5 anos.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NF-e. |

**Respostas**

- `200`: XML. (application/xml)
- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NF-e não encontrada.
- `409`: XML ainda não disponível para a situação atual.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### DANFE em PDF

`GET /v1/nfe/{id}/danfe`

Montado do XML autorizado. Nota cancelada sai com marca d'água.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NF-e. |
| `download` | query |  | 1 para baixar (attachment) em vez de abrir no navegador. um de: `1` |

**Respostas**

- `200`: PDF. (application/pdf)
- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NF-e não encontrada.
- `409`: Nota sem DANFE (não autorizada).
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Cancelar NF-e

`POST /v1/nfe/{id}/cancel`

Pede o cancelamento (evento 110111) de uma nota autorizada, dentro do prazo da SEFAZ. Assíncrono: resultado pelo webhook nfe.cancelled ou nfe.event_rejected.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NF-e. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `justification` | texto | sim | Motivo do cancelamento (15 a 255 caracteres). 15 a 255 caracteres |

**Respostas**

- `200`: O mesmo pedido já existia.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `nfeId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `type` | texto | sim | cancel cancelamento (110111), correction carta de correção (110110). um de: `cancel`, `correction` |
  | `sequence` | inteiro | sim |  |
  | `text` | texto | sim | até 100000 caracteres |
  | `status` | texto | sim | um de: `queued`, `sending`, `unknown`, `registered`, `rejected`, `failed` |
  | `protocol` | texto ou null | sim | até 20 caracteres |
  | `registeredAt` | texto ou null | sim | date-time |
  | `rejection` | objeto ou null | sim |  |
  | `rejection.cStat` | texto | sim | até 10 caracteres |
  | `rejection.reason` | texto | sim | até 100000 caracteres |
  | `rejection.at` | texto | sim | date-time |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `202`: Pedido aceito.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `nfeId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `type` | texto | sim | cancel cancelamento (110111), correction carta de correção (110110). um de: `cancel`, `correction` |
  | `sequence` | inteiro | sim |  |
  | `text` | texto | sim | até 100000 caracteres |
  | `status` | texto | sim | um de: `queued`, `sending`, `unknown`, `registered`, `rejected`, `failed` |
  | `protocol` | texto ou null | sim | até 20 caracteres |
  | `registeredAt` | texto ou null | sim | date-time |
  | `rejection` | objeto ou null | sim |  |
  | `rejection.cStat` | texto | sim | até 10 caracteres |
  | `rejection.reason` | texto | sim | até 100000 caracteres |
  | `rejection.at` | texto | sim | date-time |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NF-e não encontrada.
- `409`: Nota não autorizada ou cancelamento já em andamento.
- `422`: certificate_unavailable.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Carta de correção

`POST /v1/nfe/{id}/correction`

Registra uma carta de correção (evento 110110). Não corrige valores, impostos, dados do emitente ou do destinatário que mudem quem é ele, nem a data. Até 20 por nota.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NF-e. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `text` | texto | sim | Texto da correção. Cada carta substitui a anterior, então repita as correções anteriores que ainda valem. 15 a 1000 caracteres |

**Respostas**

- `200`: O mesmo pedido já existia.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `nfeId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `type` | texto | sim | cancel cancelamento (110111), correction carta de correção (110110). um de: `cancel`, `correction` |
  | `sequence` | inteiro | sim |  |
  | `text` | texto | sim | até 100000 caracteres |
  | `status` | texto | sim | um de: `queued`, `sending`, `unknown`, `registered`, `rejected`, `failed` |
  | `protocol` | texto ou null | sim | até 20 caracteres |
  | `registeredAt` | texto ou null | sim | date-time |
  | `rejection` | objeto ou null | sim |  |
  | `rejection.cStat` | texto | sim | até 10 caracteres |
  | `rejection.reason` | texto | sim | até 100000 caracteres |
  | `rejection.at` | texto | sim | date-time |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `202`: Pedido aceito.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `nfeId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `type` | texto | sim | cancel cancelamento (110111), correction carta de correção (110110). um de: `cancel`, `correction` |
  | `sequence` | inteiro | sim |  |
  | `text` | texto | sim | até 100000 caracteres |
  | `status` | texto | sim | um de: `queued`, `sending`, `unknown`, `registered`, `rejected`, `failed` |
  | `protocol` | texto ou null | sim | até 20 caracteres |
  | `registeredAt` | texto ou null | sim | date-time |
  | `rejection` | objeto ou null | sim |  |
  | `rejection.cStat` | texto | sim | até 10 caracteres |
  | `rejection.reason` | texto | sim | até 100000 caracteres |
  | `rejection.at` | texto | sim | date-time |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NF-e não encontrada.
- `409`: Nota não autorizada ou outra carta em andamento.
- `422`: correction_limit ou certificate_unavailable.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Eventos da NF-e

`GET /v1/nfe/{id}/events`

Cancelamentos e cartas de correção da nota.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NF-e. |

**Respostas**

- `200`: Eventos.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `data` | lista de qualquer | sim |  |
  | `data[].id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `data[].nfeId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `data[].type` | texto | sim | cancel cancelamento (110111), correction carta de correção (110110). um de: `cancel`, `correction` |
  | `data[].sequence` | inteiro | sim |  |
  | `data[].text` | texto | sim | até 100000 caracteres |
  | `data[].status` | texto | sim | um de: `queued`, `sending`, `unknown`, `registered`, `rejected`, `failed` |
  | `data[].protocol` | texto ou null | sim | até 20 caracteres |
  | `data[].registeredAt` | texto ou null | sim | date-time |
  | `data[].rejection` | objeto ou null | sim |  |
  | `data[].failure` | objeto ou null | sim |  |
  | `data[].attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `data[].createdAt` | texto | sim | date-time |
  | `data[].updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NF-e não encontrada.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### XML do evento

`GET /v1/nfe/{id}/events/{eventId}/xml`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NF-e. |
| `eventId` | caminho | sim | id do evento. |

**Respostas**

- `200`: procEventoNFe. (application/xml)
- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NF-e ou evento não encontrado.
- `409`: Evento ainda não registrado.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Tentar de novo

`POST /v1/nfe/{id}/retry`

Para nota com falha (failed) ou parada pedindo atenção, depois de corrigir a causa (ex.: certificado novo). Rejeitada não usa esta rota: reenvie o pedido corrigido em POST /v1/nfe.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NF-e. |

**Respostas**

- `202`: De volta à fila.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `externalId` | texto | sim | até 100 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `status` | texto | sim | queued/sending/pending: em andamento. unknown: resposta perdida, em conferência com a SEFAZ. authorized, rejected, denied, failed: resultado. cancelled e disabled: depois de um evento. um de: `queued`, `sending`, `pending`, `unknown`, `authorized`, `rejected`, `denied`, `failed`, `cancelled`, `disabled` |
  | `series` | inteiro | sim |  |
  | `number` | inteiro ou null | sim |  |
  | `accessKey` | texto ou null | sim | Chave de acesso (44 caracteres na NF-e; 50 na NFS-e). até 50 caracteres |
  | `protocol` | texto ou null | sim | até 20 caracteres |
  | `authorizedAt` | texto ou null | sim | date-time |
  | `rejection` | objeto ou null | sim | Última rejeição da SEFAZ (status rejected). Corrija e reenvie com o mesmo externalId. |
  | `rejection.cStat` | texto | sim | até 10 caracteres |
  | `rejection.reason` | texto | sim | até 100000 caracteres |
  | `rejection.at` | texto | sim | date-time |
  | `denial` | objeto ou null | sim |  |
  | `denial.cStat` | texto ou null | sim | até 10 caracteres |
  | `denial.reason` | texto ou null | sim | até 100000 caracteres |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `totals` | objeto ou null | sim | Totais calculados (produtos, impostos, total da nota), em texto decimal. |
  | `warnings` | lista de texto | sim | Avisos do cálculo; não impedem a emissão. até 100000 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NF-e não encontrada.
- `409`: A nota não pode ser reenviada na situação atual.
- `429`: Limite de requisições; espere o tempo de Retry-After.

## NFS-e

NFS-e no padrão nacional (Sefin): emissão assíncrona, consulta, XML, DANFSe e cancelamento.

### Município no Sistema Nacional da NFS-e

`GET /v1/nfse/municipalities/{cityCode}`

Diz se o município é conveniado e se aceita os emissores nacionais (a NFS-e pela API do Sefin). Consulta o ADN com o certificado da empresa; resultado guardado por 24 h.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `cityCode` | caminho | sim | Código IBGE do município (7 dígitos). |
| `companyId` | query | sim | Empresa cujo certificado é usado na consulta. padrão `^[0-9a-f]{24}$`; 24 caracteres |

**Respostas**

- `200`: Situação do município.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `cityCode` | texto | sim | até 7 caracteres |
  | `name` | texto ou null | sim | até 100000 caracteres |
  | `uf` | texto ou null | sim | até 2 caracteres |
  | `agreement` | booleano ou null | sim | Município conveniado ao Sistema Nacional da NFS-e. |
  | `nationalIssuer` | booleano ou null | sim | Aceita os emissores nacionais (API do Sefin). false: a NFS-e sai pelo sistema da prefeitura. |
  | `checkedAt` | texto ou null | sim | date-time |
  | `source` | texto | sim | adn (consultado agora), cache (até 24 h), indisponível ou sem certificado para consultar. até 60 caracteres |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada.
- `422`: Código IBGE ou companyId inválido.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Emitir NFS-e (padrão nacional)

`POST /v1/nfse`

Monta e assina a DPS e envia ao Sistema Nacional da NFS-e (Sefin) em segundo plano. Responde 202 na hora; o resultado chega pelo webhook (nfse.authorized, nfse.rejected...) ou em GET /v1/nfse/{id}. MEI e Simples Nacional emitem pelo padrão nacional em todos os municípios a partir de 01/11/2026 (antes, só onde a prefeitura já aceita); os demais regimes, só onde o município aceita o emissor nacional (veja GET /v1/nfse/municipalities/{cityCode}). O externalId é a chave de idempotência.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `externalId` | texto | sim | Seu identificador do pedido. Também é a chave de idempotência: repetir o mesmo externalId devolve a mesma nota (200), nunca uma segunda. até 100 caracteres |
| `companyId` | texto | sim | id da empresa emitente (devolvido em POST /v1/companies). padrão `^[0-9a-f]{24}$`; 24 caracteres |
| `series` | inteiro |  | Série da DPS (padrão: a série padrão da empresa no ambiente). 1 a 49999 |
| `competenceDate` | texto |  | Data de competência (padrão: hoje). date; padrão `^\d{4}-(0[1-9]\|1[0-2])-(0[1-9]\|[12]\d\|3[01])$`; 10 caracteres |
| `service` | objeto | sim |  |
| `service.nationalCode` | texto | sim | Código de tributação nacional (cTribNac, lista da LC 116), com ou sem pontos: "01.07.01" ou "010701". padrão `^[0-9.\s-]{6,10}$`; 6 a 10 caracteres |
| `service.municipalCode` | texto ou null |  | Código de tributação municipal, quando o município exige. padrão `^[0-9]{3}$` |
| `service.nbs` | texto ou null |  | Código NBS (9 dígitos). Obrigatório quando a nota leva o grupo do IBS/CBS. padrão `^[0-9.\s-]{9,13}$`; 9 a 13 caracteres |
| `service.description` | texto | sim | Discriminação do serviço. até 2000 caracteres |
| `service.internalCode` | texto ou null |  | padrão `^[A-Za-z0-9]+$`; até 20 caracteres |
| `service.simplesActivity` | texto ou null |  | Atividade do Simples Nacional (cAtvSN), só para ME/EPP; MEI e não optante não informam. Ex.: 10 para 16.01, 12 e 13 para 7.02 e 7.05. um de: `07`, `08`, `09`, `10`, `11`, `12`, `13`, `14`, `90` |
| `service.location` | objeto ou null |  | Local da prestação. Padrão: o município da empresa. |
| `service.location.cityCode` | texto |  | padrão `^[0-9]{7}$` |
| `service.location.country` | texto |  | padrão `^[A-Z]{2}$`; 2 caracteres |
| `recipient` | objeto ou null |  | Tomador do serviço. Informe exatamente um: cnpj, cpf, nif (estrangeiro) ou noNifReason. |
| `recipient.cnpj` | texto |  | CNPJ, com ou sem pontuação (aceita o CNPJ alfanumérico). 14 a 18 caracteres |
| `recipient.cpf` | texto |  | CPF, 11 dígitos. padrão `^[0-9]{11}$` |
| `recipient.nif` | texto |  | até 40 caracteres |
| `recipient.noNifReason` | inteiro |  | um de: `0`, `1`, `2` |
| `recipient.im` | texto ou null |  | até 15 caracteres |
| `recipient.name` | texto | sim | até 150 caracteres |
| `recipient.email` | texto ou null |  | email; até 254 caracteres |
| `recipient.phone` | texto ou null |  | padrão `^[0-9]{6,20}$` |
| `recipient.address` | objeto ou null |  | No Brasil: cityCode (IBGE) e zip. No exterior: country, cityName, state e postalCode. |
| `recipient.address.street` | texto | sim | até 255 caracteres |
| `recipient.address.number` | texto | sim | até 60 caracteres |
| `recipient.address.complement` | texto ou null |  | até 156 caracteres |
| `recipient.address.district` | texto | sim | até 60 caracteres |
| `recipient.address.cityCode` | texto |  | padrão `^[0-9]{7}$` |
| `recipient.address.zip` | texto |  | padrão `^[0-9]{8}$` |
| `recipient.address.country` | texto |  | padrão `^[A-Z]{2}$`; 2 caracteres |
| `recipient.address.cityName` | texto |  | até 60 caracteres |
| `recipient.address.state` | texto |  | até 60 caracteres |
| `recipient.address.postalCode` | texto |  | até 11 caracteres |
| `amount` | texto | sim | Valor do serviço. padrão `^[0-9]{1,15}(\.[0-9]{1,2})?$` |
| `discounts` | objeto ou null |  |  |
| `discounts.unconditional` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `discounts.conditional` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `iss` | objeto ou null |  | ISSQN. |
| `iss.taxation` | texto |  | taxable tributável (padrão), immune imunidade, export exportação de serviço, not_levied não incidência. um de: `taxable`, `immune`, `export`, `not_levied` |
| `iss.withheld` | booleano |  | ISS retido pelo tomador. |
| `iss.rate` | texto ou null |  | Alíquota do ISS em %. Ausente: a do município no Sistema Nacional. padrão `^[0-9]{1,15}(\.[0-9]{1,2})?$` |
| `iss.immunityType` | inteiro |  | um de: `1`, `2`, `3`, `4`, `5` |
| `iss.resultCountry` | texto |  | padrão `^[A-Z]{2}$`; 2 caracteres |
| `federal` | objeto ou null |  |  |
| `federal.pisCofins` | objeto |  |  |
| `federal.pisCofins.cst` | texto | sim | um de: `00`, `01`, `02`, `03`, `04`, `05`, `06`, `07`, `08`, `09` |
| `federal.pisCofins.base` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `federal.pisCofins.pisRate` | texto |  | Decimal em texto, com ponto e até 2 casas (máximo 99.99). |
| `federal.pisCofins.cofinsRate` | texto |  | Decimal em texto, com ponto e até 2 casas (máximo 99.99). |
| `federal.pisCofins.withholding` | inteiro |  | um de: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9` |
| `federal.inss` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `federal.irrf` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `federal.csll` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `approximateTaxes` | objeto ou null |  | Total aproximado dos tributos (Lei 12.741/2012). Informe só um: simplesRate, rates ou amounts. |
| `approximateTaxes.simplesRate` | texto |  | Decimal em texto, com ponto e até 2 casas (máximo 99.99). |
| `approximateTaxes.rates` | objeto |  |  |
| `approximateTaxes.rates.federal` | texto | sim | Decimal em texto, com ponto e até 2 casas (máximo 100). |
| `approximateTaxes.rates.state` | texto | sim | Decimal em texto, com ponto e até 2 casas (máximo 100). |
| `approximateTaxes.rates.municipal` | texto | sim | Decimal em texto, com ponto e até 2 casas (máximo 100). |
| `approximateTaxes.amounts` | objeto |  |  |
| `approximateTaxes.amounts.federal` | texto | sim | Decimal em texto, com ponto e até 2 casas. |
| `approximateTaxes.amounts.state` | texto | sim | Decimal em texto, com ponto e até 2 casas. |
| `approximateTaxes.amounts.municipal` | texto | sim | Decimal em texto, com ponto e até 2 casas. |
| `ibsCbs` | objeto ou null |  | Grupo do IBS/CBS da NFS-e. |
| `ibsCbs.cst` | texto | sim | padrão `^[0-9]{3}$` |
| `ibsCbs.classTrib` | texto | sim | padrão `^[0-9]{6}$` |
| `ibsCbs.operationIndicator` | texto | sim | Indicador da operação (cIndOp, Anexo VII da NT). padrão `^[0-9]{6}$` |
| `ibsCbs.finalConsumer` | booleano |  |  |
| `orderNumber` | texto ou null |  | Número do pedido, impresso no DANFSe. até 60 caracteres |
| `reference` | texto ou null |  | até 255 caracteres |
| `additionalInfo` | texto ou null |  | até 2000 caracteres |

Exemplo:

```json
{
  "externalId": "os-2026-1001",
  "companyId": "6710a1b2c3d4e5f601234567",
  "service": {
    "nationalCode": "01.07.01",
    "description": "Suporte técnico em informática - outubro/2026",
    "simplesActivity": "07"
  },
  "recipient": {
    "cnpj": "11444777000161",
    "name": "Cliente Exemplo Ltda",
    "email": "fiscal@cliente.com.br",
    "address": {
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "cityCode": "3550308",
      "zip": "01310100"
    }
  },
  "amount": "1500.00",
  "approximateTaxes": {
    "simplesRate": "6.00"
  }
}
```

**Respostas**

- `200`: Pedido repetido: a NFS-e que já existe.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `externalId` | texto | sim | até 100 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `status` | texto | sim | queued/sending: em andamento. unknown: resposta perdida, em conferência com o Sefin. authorized, rejected, failed: resultado. cancelled: cancelada. um de: `queued`, `sending`, `unknown`, `authorized`, `rejected`, `failed`, `cancelled` |
  | `dps` | objeto | sim | Declaração de Prestação de Serviço enviada (série, número e Id). |
  | `dps.series` | inteiro | sim |  |
  | `dps.number` | inteiro ou null | sim |  |
  | `dps.id` | texto ou null | sim | até 45 caracteres |
  | `number` | texto ou null | sim | Número da NFS-e, dado pelo Sistema Nacional. até 20 caracteres |
  | `accessKey` | texto ou null | sim | Chave de acesso (44 caracteres na NF-e; 50 na NFS-e). até 50 caracteres |
  | `authorizedAt` | texto ou null | sim | date-time |
  | `values` | objeto ou null | sim | Valores da NFS-e gerada (base, ISSQN, líquido...), lidos do XML. |
  | `incidence` | objeto ou null | sim | Município de incidência do ISSQN (código e nome). |
  | `rejection` | objeto ou null | sim |  |
  | `rejection.errors` | lista de objeto | sim |  |
  | `rejection.at` | texto | sim | date-time |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `cancellation` | objeto ou null | sim |  |
  | `cancellation.eventId` | texto | sim | até 24 caracteres |
  | `cancellation.reason` | texto | sim | até 2 caracteres |
  | `cancellation.at` | texto | sim | date-time |
  | `summary` | objeto ou null | sim | Resumo do pedido calculado antes do envio. |
  | `warnings` | lista de objeto | sim | Avisos do cálculo; não impedem a emissão. |
  | `warnings[].code` | texto | sim | até 60 caracteres |
  | `warnings[].message` | texto | sim | até 100000 caracteres |
  | `alerts` | lista de objeto | sim | Alertas devolvidos pelo Sefin junto com a NFS-e. |
  | `alerts[].code` | texto ou null | sim | até 20 caracteres |
  | `alerts[].message` | texto ou null | sim | até 100000 caracteres |
  | `alerts[].complement` | texto ou null | sim | até 100000 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `202`: Aceita e na fila.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `externalId` | texto | sim | até 100 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `status` | texto | sim | queued/sending: em andamento. unknown: resposta perdida, em conferência com o Sefin. authorized, rejected, failed: resultado. cancelled: cancelada. um de: `queued`, `sending`, `unknown`, `authorized`, `rejected`, `failed`, `cancelled` |
  | `dps` | objeto | sim | Declaração de Prestação de Serviço enviada (série, número e Id). |
  | `dps.series` | inteiro | sim |  |
  | `dps.number` | inteiro ou null | sim |  |
  | `dps.id` | texto ou null | sim | até 45 caracteres |
  | `number` | texto ou null | sim | Número da NFS-e, dado pelo Sistema Nacional. até 20 caracteres |
  | `accessKey` | texto ou null | sim | Chave de acesso (44 caracteres na NF-e; 50 na NFS-e). até 50 caracteres |
  | `authorizedAt` | texto ou null | sim | date-time |
  | `values` | objeto ou null | sim | Valores da NFS-e gerada (base, ISSQN, líquido...), lidos do XML. |
  | `incidence` | objeto ou null | sim | Município de incidência do ISSQN (código e nome). |
  | `rejection` | objeto ou null | sim |  |
  | `rejection.errors` | lista de objeto | sim |  |
  | `rejection.at` | texto | sim | date-time |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `cancellation` | objeto ou null | sim |  |
  | `cancellation.eventId` | texto | sim | até 24 caracteres |
  | `cancellation.reason` | texto | sim | até 2 caracteres |
  | `cancellation.at` | texto | sim | date-time |
  | `summary` | objeto ou null | sim | Resumo do pedido calculado antes do envio. |
  | `warnings` | lista de objeto | sim | Avisos do cálculo; não impedem a emissão. |
  | `warnings[].code` | texto | sim | até 60 caracteres |
  | `warnings[].message` | texto | sim | até 100000 caracteres |
  | `alerts` | lista de objeto | sim | Alertas devolvidos pelo Sefin junto com a NFS-e. |
  | `alerts[].code` | texto ou null | sim | até 20 caracteres |
  | `alerts[].message` | texto ou null | sim | até 100000 caracteres |
  | `alerts[].complement` | texto ou null | sim | até 100000 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada.
- `409`: externalId já usado com outro conteúdo, ou documento em situação que não aceita reenvio.
- `422`: Dados inválidos; nfse_series_missing, certificate_unavailable, model_invalid, municipality_not_supported, sandbox_homologation_only.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Buscar NFS-e pelo externalId

`GET /v1/nfse`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `externalId` | query | sim | O seu identificador do pedido. até 100 caracteres |

**Respostas**

- `200`: NFS-e.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `externalId` | texto | sim | até 100 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `status` | texto | sim | queued/sending: em andamento. unknown: resposta perdida, em conferência com o Sefin. authorized, rejected, failed: resultado. cancelled: cancelada. um de: `queued`, `sending`, `unknown`, `authorized`, `rejected`, `failed`, `cancelled` |
  | `dps` | objeto | sim | Declaração de Prestação de Serviço enviada (série, número e Id). |
  | `dps.series` | inteiro | sim |  |
  | `dps.number` | inteiro ou null | sim |  |
  | `dps.id` | texto ou null | sim | até 45 caracteres |
  | `number` | texto ou null | sim | Número da NFS-e, dado pelo Sistema Nacional. até 20 caracteres |
  | `accessKey` | texto ou null | sim | Chave de acesso (44 caracteres na NF-e; 50 na NFS-e). até 50 caracteres |
  | `authorizedAt` | texto ou null | sim | date-time |
  | `values` | objeto ou null | sim | Valores da NFS-e gerada (base, ISSQN, líquido...), lidos do XML. |
  | `incidence` | objeto ou null | sim | Município de incidência do ISSQN (código e nome). |
  | `rejection` | objeto ou null | sim |  |
  | `rejection.errors` | lista de objeto | sim |  |
  | `rejection.at` | texto | sim | date-time |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `cancellation` | objeto ou null | sim |  |
  | `cancellation.eventId` | texto | sim | até 24 caracteres |
  | `cancellation.reason` | texto | sim | até 2 caracteres |
  | `cancellation.at` | texto | sim | date-time |
  | `summary` | objeto ou null | sim | Resumo do pedido calculado antes do envio. |
  | `warnings` | lista de objeto | sim | Avisos do cálculo; não impedem a emissão. |
  | `warnings[].code` | texto | sim | até 60 caracteres |
  | `warnings[].message` | texto | sim | até 100000 caracteres |
  | `alerts` | lista de objeto | sim | Alertas devolvidos pelo Sefin junto com a NFS-e. |
  | `alerts[].code` | texto ou null | sim | até 20 caracteres |
  | `alerts[].message` | texto ou null | sim | até 100000 caracteres |
  | `alerts[].complement` | texto ou null | sim | até 100000 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NFS-e não encontrada.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Consultar NFS-e

`GET /v1/nfse/{id}`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NFS-e. |

**Respostas**

- `200`: NFS-e.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `externalId` | texto | sim | até 100 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `status` | texto | sim | queued/sending: em andamento. unknown: resposta perdida, em conferência com o Sefin. authorized, rejected, failed: resultado. cancelled: cancelada. um de: `queued`, `sending`, `unknown`, `authorized`, `rejected`, `failed`, `cancelled` |
  | `dps` | objeto | sim | Declaração de Prestação de Serviço enviada (série, número e Id). |
  | `dps.series` | inteiro | sim |  |
  | `dps.number` | inteiro ou null | sim |  |
  | `dps.id` | texto ou null | sim | até 45 caracteres |
  | `number` | texto ou null | sim | Número da NFS-e, dado pelo Sistema Nacional. até 20 caracteres |
  | `accessKey` | texto ou null | sim | Chave de acesso (44 caracteres na NF-e; 50 na NFS-e). até 50 caracteres |
  | `authorizedAt` | texto ou null | sim | date-time |
  | `values` | objeto ou null | sim | Valores da NFS-e gerada (base, ISSQN, líquido...), lidos do XML. |
  | `incidence` | objeto ou null | sim | Município de incidência do ISSQN (código e nome). |
  | `rejection` | objeto ou null | sim |  |
  | `rejection.errors` | lista de objeto | sim |  |
  | `rejection.at` | texto | sim | date-time |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `cancellation` | objeto ou null | sim |  |
  | `cancellation.eventId` | texto | sim | até 24 caracteres |
  | `cancellation.reason` | texto | sim | até 2 caracteres |
  | `cancellation.at` | texto | sim | date-time |
  | `summary` | objeto ou null | sim | Resumo do pedido calculado antes do envio. |
  | `warnings` | lista de objeto | sim | Avisos do cálculo; não impedem a emissão. |
  | `warnings[].code` | texto | sim | até 60 caracteres |
  | `warnings[].message` | texto | sim | até 100000 caracteres |
  | `alerts` | lista de objeto | sim | Alertas devolvidos pelo Sefin junto com a NFS-e. |
  | `alerts[].code` | texto ou null | sim | até 20 caracteres |
  | `alerts[].message` | texto ou null | sim | até 100000 caracteres |
  | `alerts[].complement` | texto ou null | sim | até 100000 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NFS-e não encontrada.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### XML da NFS-e

`GET /v1/nfse/{id}/xml`

XML gerado pelo Sistema Nacional, com a DPS assinada dentro.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NFS-e. |

**Respostas**

- `200`: XML. (application/xml)
- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NFS-e não encontrada.
- `409`: XML ainda não disponível.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### DANFSe em PDF

`GET /v1/nfse/{id}/danfse`

Documento auxiliar da NFS-e (NT 008), com QR Code. Cancelada sai com marca d'água.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NFS-e. |
| `download` | query |  | 1 para baixar em vez de abrir. um de: `1` |

**Respostas**

- `200`: PDF. (application/pdf)
- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NFS-e não encontrada.
- `409`: NFS-e não autorizada.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Cancelar NFS-e

`POST /v1/nfse/{id}/cancel`

Registra o evento de cancelamento (101101). Assíncrono: resultado pelo webhook nfse.cancelled ou nfse.event_rejected.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NFS-e. |

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `reason` | texto | sim | Motivo: 1 erro na emissão, 2 serviço não prestado, 9 outros. um de: `1`, `2`, `9` |
| `justification` | texto | sim | Justificativa (15 a 255 caracteres). 15 a 255 caracteres |

**Respostas**

- `200`: O mesmo pedido já existia.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `type` | texto | sim | um de: `cancel` |
  | `status` | texto | sim | um de: `queued`, `sending`, `unknown`, `registered`, `rejected` |
  | `reason` | texto | sim | até 2 caracteres |
  | `justification` | texto | sim | até 100000 caracteres |
  | `errors` | lista de objeto | sim |  |
  | `errors[].code` | texto ou null | sim | até 20 caracteres |
  | `errors[].message` | texto ou null | sim | até 100000 caracteres |
  | `errors[].complement` | texto ou null | sim | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `registeredAt` | texto ou null | sim | date-time |
  | `createdAt` | texto | sim | date-time |

- `202`: Pedido aceito.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `type` | texto | sim | um de: `cancel` |
  | `status` | texto | sim | um de: `queued`, `sending`, `unknown`, `registered`, `rejected` |
  | `reason` | texto | sim | até 2 caracteres |
  | `justification` | texto | sim | até 100000 caracteres |
  | `errors` | lista de objeto | sim |  |
  | `errors[].code` | texto ou null | sim | até 20 caracteres |
  | `errors[].message` | texto ou null | sim | até 100000 caracteres |
  | `errors[].complement` | texto ou null | sim | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `registeredAt` | texto ou null | sim | date-time |
  | `createdAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NFS-e não encontrada.
- `409`: NFS-e não autorizada ou cancelamento já pedido.
- `422`: Dados inválidos (validation_failed), com a lista de campos em details.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Eventos da NFS-e

`GET /v1/nfse/{id}/events`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NFS-e. |

**Respostas**

- `200`: Eventos.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `data` | lista de qualquer | sim |  |
  | `data[].id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `data[].type` | texto | sim | um de: `cancel` |
  | `data[].status` | texto | sim | um de: `queued`, `sending`, `unknown`, `registered`, `rejected` |
  | `data[].reason` | texto | sim | até 2 caracteres |
  | `data[].justification` | texto | sim | até 100000 caracteres |
  | `data[].errors` | lista de objeto | sim |  |
  | `data[].attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `data[].registeredAt` | texto ou null | sim | date-time |
  | `data[].createdAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NFS-e não encontrada.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### XML do evento da NFS-e

`GET /v1/nfse/{id}/events/{eventId}/xml`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NFS-e. |
| `eventId` | caminho | sim | id do evento. |

**Respostas**

- `200`: XML do evento. (application/xml)
- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NFS-e não encontrada.
- `409`: Evento não registrado ou inexistente.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Tentar de novo

`POST /v1/nfse/{id}/retry`

Para NFS-e com falha ou parada pedindo atenção, depois de corrigir a causa. Rejeitada: reenvie o pedido corrigido em POST /v1/nfse com o mesmo externalId.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id da NFS-e. |

**Respostas**

- `202`: De volta à fila.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `externalId` | texto | sim | até 100 caracteres |
  | `companyId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `environment` | texto | sim | Ambiente: homologation (sem valor fiscal) ou production. um de: `homologation`, `production` |
  | `status` | texto | sim | queued/sending: em andamento. unknown: resposta perdida, em conferência com o Sefin. authorized, rejected, failed: resultado. cancelled: cancelada. um de: `queued`, `sending`, `unknown`, `authorized`, `rejected`, `failed`, `cancelled` |
  | `dps` | objeto | sim | Declaração de Prestação de Serviço enviada (série, número e Id). |
  | `dps.series` | inteiro | sim |  |
  | `dps.number` | inteiro ou null | sim |  |
  | `dps.id` | texto ou null | sim | até 45 caracteres |
  | `number` | texto ou null | sim | Número da NFS-e, dado pelo Sistema Nacional. até 20 caracteres |
  | `accessKey` | texto ou null | sim | Chave de acesso (44 caracteres na NF-e; 50 na NFS-e). até 50 caracteres |
  | `authorizedAt` | texto ou null | sim | date-time |
  | `values` | objeto ou null | sim | Valores da NFS-e gerada (base, ISSQN, líquido...), lidos do XML. |
  | `incidence` | objeto ou null | sim | Município de incidência do ISSQN (código e nome). |
  | `rejection` | objeto ou null | sim |  |
  | `rejection.errors` | lista de objeto | sim |  |
  | `rejection.at` | texto | sim | date-time |
  | `failure` | objeto ou null | sim |  |
  | `failure.code` | texto | sim | até 60 caracteres |
  | `failure.reason` | texto ou null |  | até 100000 caracteres |
  | `attention` | texto ou null | sim | Pede ação manual quando preenchido. Códigos: digest_mismatch, dps_mismatch, duplicate_unresolved, reconcile_exhausted, text_mismatch, certificate_missing, certificate_expired. até 60 caracteres |
  | `cancellation` | objeto ou null | sim |  |
  | `cancellation.eventId` | texto | sim | até 24 caracteres |
  | `cancellation.reason` | texto | sim | até 2 caracteres |
  | `cancellation.at` | texto | sim | date-time |
  | `summary` | objeto ou null | sim | Resumo do pedido calculado antes do envio. |
  | `warnings` | lista de objeto | sim | Avisos do cálculo; não impedem a emissão. |
  | `warnings[].code` | texto | sim | até 60 caracteres |
  | `warnings[].message` | texto | sim | até 100000 caracteres |
  | `alerts` | lista de objeto | sim | Alertas devolvidos pelo Sefin junto com a NFS-e. |
  | `alerts[].code` | texto ou null | sim | até 20 caracteres |
  | `alerts[].message` | texto ou null | sim | até 100000 caracteres |
  | `alerts[].complement` | texto ou null | sim | até 100000 caracteres |
  | `createdAt` | texto | sim | date-time |
  | `updatedAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: NFS-e não encontrada.
- `409`: A NFS-e não pode ser reenviada na situação atual.
- `429`: Limite de requisições; espere o tempo de Retry-After.

## Impostos

Cálculo sem emissão e tabelas da Reforma Tributária (IBS/CBS).

### Calcular impostos (sem emitir)

`POST /v1/tax/calculate`

Calcula ICMS, IPI, PIS, COFINS e IBS/CBS de um pedido como sairia na NF-e, sem criar documento nem reservar número. Serve para orçamento e carrinho. Use companyId (empresa cadastrada, com classes de imposto) ou issuer (só regime e UF).

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `companyId` | texto |  | id da empresa emitente (devolvido em POST /v1/companies). padrão `^[0-9a-f]{24}$`; 24 caracteres |
| `issuer` | objeto |  | Emitente sem cadastro (só regime e UF). Use companyId ou issuer, um dos dois. |
| `issuer.cnpj` | texto |  | CNPJ, com ou sem pontuação (aceita o CNPJ alfanumérico). 14 a 18 caracteres |
| `issuer.crt` | inteiro | sim | um de: `1`, `2`, `3`, `4` |
| `issuer.uf` | texto | sim | um de: `RO`, `AC`, `AM`, `RR`, `PA`, `AP`, `TO`, `MA`, `PI`, `CE`, `RN`, `PB`, `PE`, `AL`, `SE`, `BA`, `MG`, `ES`, `RJ`, `SP`, `PR`, `SC`, `RS`, `MS`, `MT`, `GO`, `DF` |
| `issuer.cityCode` | texto |  | padrão `^[0-9]{7}$` |
| `issueDate` | texto |  | Simula as regras de outra data (ex.: 2027-01-01). date; padrão `^\d{4}-(0[1-9]\|1[0-2])-(0[1-9]\|[12]\d\|3[01])$`; 10 caracteres |
| `operation` | texto | sim | sale venda, return devolução, bonus bonificação, transfer transferência. um de: `sale`, `return`, `bonus`, `transfer` |
| `direction` | texto |  | Só em devolução: out nota de saída (padrão), in nota de entrada. um de: `out`, `in` |
| `natureOfOperation` | texto |  | até 60 caracteres |
| `presence` | texto |  | Indicador de presença do comprador (indPres): 0 não se aplica, 1 presencial, 2 internet, 3 teleatendimento, 4 entrega a domicílio, 5 presencial fora do estabelecimento, 9 outros. um de: `0`, `1`, `2`, `3`, `4`, `5`, `9` |
| `finalConsumer` | booleano |  |  |
| `recipient` | objeto | sim |  |
| `recipient.cnpj` | texto |  | CNPJ, com ou sem pontuação (aceita o CNPJ alfanumérico). 14 a 18 caracteres |
| `recipient.cpf` | texto |  | CPF, 11 dígitos. padrão `^[0-9]{11}$` |
| `recipient.ieIndicator` | texto | sim | Indicador da IE do destinatário: 1 contribuinte do ICMS (informe ie), 2 isento, 9 não contribuinte. um de: `1`, `2`, `9` |
| `recipient.uf` | texto | sim | um de: `RO`, `AC`, `AM`, `RR`, `PA`, `AP`, `TO`, `MA`, `PI`, `CE`, `RN`, `PB`, `PE`, `AL`, `SE`, `BA`, `MG`, `ES`, `RJ`, `SP`, `PR`, `SC`, `RS`, `MS`, `MT`, `GO`, `DF` |
| `recipient.cityCode` | texto |  | padrão `^[0-9]{7}$` |
| `items` | lista de qualquer | sim |  |
| `items[].code` | texto | sim | Código do produto no seu sistema. até 60 caracteres |
| `items[].description` | texto | sim | até 120 caracteres |
| `items[].ncm` | texto | sim | NCM do produto (8 dígitos). padrão `^[0-9]{8}$` |
| `items[].cest` | texto ou null |  | padrão `^[0-9]{7}$` |
| `items[].gtin` | texto ou null |  | Código de barras (GTIN) ou "SEM GTIN". padrão `^(SEM GTIN\|\d{8}\|\d{12,14})$`; até 14 caracteres |
| `items[].origin` | texto | sim | Origem da mercadoria: 0 nacional; 1 a 8 importada ou com conteúdo importado (tabela do ICMS). um de: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` |
| `items[].cfop` | texto |  | CFOP. Obrigatório sem taxClass; com taxClass, vem da classe. padrão `^[0-9]{4}$` |
| `items[].taxClass` | texto |  | Código de uma classe de imposto da empresa (POST /v1/companies/{id}/tax-classes): CFOP, ICMS, IPI, PIS e COFINS saem dela. padrão `^[A-Za-z0-9_.-]+$`; até 30 caracteres |
| `items[].unit` | texto | sim | Unidade comercial (ex.: UN, KG, PAR). até 6 caracteres |
| `items[].quantity` | texto | sim | Decimal em texto, com ponto e até 4 casas (mínimo 0.0001). |
| `items[].unitPrice` | texto | sim | Preço unitário bruto. padrão `^[0-9]{1,15}(\.[0-9]{1,10})?$` |
| `items[].netUnitPrice` | texto |  | Preço unitário líquido, quando a empresa calcula pelo líquido. padrão `^[0-9]{1,15}(\.[0-9]{1,10})?$` |
| `items[].discount` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].freight` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].insurance` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].otherExpenses` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].approxTaxes` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].purchaseOrder` | texto ou null |  | até 15 caracteres |
| `items[].purchaseOrderItem` | texto ou null |  | padrão `^[0-9]{1,6}$` |
| `items[].additionalInfo` | texto ou null |  | até 500 caracteres |
| `items[].reference` | objeto |  | Só em devolução: a NF-e original e o número do item nela. |
| `items[].reference.accessKey` | texto | sim | Chave de acesso de 44 caracteres. padrão `^[0-9]{6}[0-9A-Z]{12}[0-9]{26}$`; 44 caracteres |
| `items[].reference.item` | inteiro |  | 1 a 990 |
| `items[].returnedIpi` | objeto |  | Só em devolução: IPI devolvido. |
| `items[].returnedIpi.value` | texto | sim | Decimal em texto, com ponto e até 2 casas. |
| `items[].returnedIpi.percent` | texto |  | Decimal em texto, com ponto e até 2 casas (mínimo 0.01, máximo 100). |
| `items[].taxes` | objeto |  | Impostos do item. Sem taxClass, informe icms, pis e cofins. Com taxClass, o que vier aqui prevalece sobre a classe. |
| `items[].taxes.icms` | objeto |  | ICMS do item. Informe cst (regime normal) ou csosn (Simples), um dos dois. |
| `items[].taxes.icms.cst` | texto |  | CST do ICMS (regime normal). um de: `00`, `20`, `40`, `41`, `50`, `51`, `90` |
| `items[].taxes.icms.csosn` | texto |  | CSOSN (Simples Nacional). um de: `101`, `102`, `103`, `300`, `400`, `900` |
| `items[].taxes.icms.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.icms.baseReduction` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.icms.deferral` | texto |  | Decimal em texto, com ponto e até 2 casas (máximo 100). |
| `items[].taxes.icms.creditRate` | texto |  | Alíquota do crédito do Simples (CSOSN 101 e 900). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.icms.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.ipi` | objeto ou null |  |  |
| `items[].taxes.ipi.cst` | texto | sim | um de: `00`, `01`, `02`, `03`, `04`, `05`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `99` |
| `items[].taxes.ipi.enquadramento` | texto |  | Código de enquadramento legal do IPI (padrão 999). padrão `^[0-9]{3}$` |
| `items[].taxes.ipi.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.ipi.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.pis` | objeto |  |  |
| `items[].taxes.pis.cst` | texto | sim | um de: `01`, `02`, `04`, `05`, `06`, `07`, `08`, `09`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `56`, `60`, `61`, `62`, `63`, `64`, `65`, `66`, `67`, `70`, `71`, `72`, `73`, `74`, `75`, `98`, `99` |
| `items[].taxes.pis.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.pis.base` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.pis.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.cofins` | objeto |  |  |
| `items[].taxes.cofins.cst` | texto | sim | um de: `01`, `02`, `04`, `05`, `06`, `07`, `08`, `09`, `49`, `50`, `51`, `52`, `53`, `54`, `55`, `56`, `60`, `61`, `62`, `63`, `64`, `65`, `66`, `67`, `70`, `71`, `72`, `73`, `74`, `75`, `98`, `99` |
| `items[].taxes.cofins.rate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.cofins.base` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.cofins.value` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.ibsCbs` | objeto ou null |  | Ausente: o motor decide o IBS/CBS. null: nota sem o grupo do IBS/CBS. |
| `items[].taxes.ibsCbs.cst` | texto | sim | CST do IBS/CBS (tabela da Reforma Tributária; veja GET /v1/tax/classifications). padrão `^[0-9]{3}$` |
| `items[].taxes.ibsCbs.classTrib` | texto | sim | cClassTrib: classificação tributária do IBS/CBS (veja GET /v1/tax/classifications). padrão `^[0-9]{6}$` |
| `items[].taxes.ibsCbs.ibsUfRate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.ibsCbs.ibsMunRate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.ibsCbs.cbsRate` | texto |  | Alíquota em percentual, texto com até 4 casas (ex.: "18.00"). padrão `^[0-9]{1,15}(\.[0-9]{1,4})?$` |
| `items[].taxes.ibsCbs.donation` | booleano |  |  |
| `items[].taxes.ibsCbs.ibsValue` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `items[].taxes.ibsCbs.cbsValue` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `charges` | objeto |  |  |
| `charges.freight` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `charges.insurance` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `charges.otherExpenses` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `charges.discount` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `payments` | lista de objeto |  |  |
| `payments[].method` | texto | sim | Meio de pagamento (tPag): 01 dinheiro, 03 cartão de crédito, 04 cartão de débito, 15 boleto, 17 PIX, 90 sem pagamento, 99 outros. padrão `^[0-9]{2}$` |
| `payments[].amount` | texto |  | Decimal em texto, com ponto e até 2 casas. |
| `payments[].description` | texto |  | Descrição do meio quando method é 99. até 60 caracteres |
| `payments[].term` | texto |  | cash à vista, installments a prazo. um de: `cash`, `installments` |
| `expectedTotal` | texto |  | Decimal em texto, com ponto e até 2 casas. |

Exemplo:

```json
{
  "issuer": {
    "crt": 3,
    "uf": "SP"
  },
  "operation": "sale",
  "recipient": {
    "cnpj": "11444777000161",
    "ieIndicator": "1",
    "uf": "MG"
  },
  "items": [
    {
      "code": "TEN-ESP-42",
      "description": "Tênis esportivo nº 42",
      "ncm": "64041100",
      "origin": "0",
      "cfop": "6101",
      "unit": "PAR",
      "quantity": "20",
      "unitPrice": "75.00",
      "taxes": {
        "icms": {
          "cst": "00",
          "rate": "12"
        },
        "ipi": {
          "cst": "50",
          "rate": "10"
        },
        "pis": {
          "cst": "01",
          "rate": "1.65"
        },
        "cofins": {
          "cst": "01",
          "rate": "7.6"
        }
      }
    }
  ]
}
```

**Respostas**

- `200`: Cálculo.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `operation` | texto | sim | até 20 caracteres |
  | `year` | inteiro | sim |  |
  | `items` | lista de objeto | sim | Itens na ordem do pedido. |
  | `totals` | objeto | sim | Totais como sairiam na NF-e, em texto decimal. |
  | `invoiceMessages` | texto ou null | sim | até 100000 caracteres |
  | `warnings` | lista de texto | sim | até 100000 caracteres |
  | `basis` | objeto | sim | Bases legais e alíquotas usadas no cálculo. |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Empresa não encontrada.
- `422`: Dados inválidos ou regras do ano ainda não publicadas.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Tabela de classificação do IBS/CBS

`GET /v1/tax/classifications`

CST e cClassTrib oficiais, com as reduções de cada classificação.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `cst` | query |  | Filtra por CST. padrão `^[0-9]{3}$` |
| `q` | query |  | Busca no nome ou no código. até 100 caracteres |

**Respostas**

- `200`: Classificações.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `source` | objeto | sim | Tabela oficial usada (versão e data). |
  | `data` | lista de objeto | sim |  |
  | `data[].cst` | texto | sim | até 3 caracteres |
  | `data[].classTrib` | texto | sim | até 6 caracteres |
  | `data[].description` | texto | sim | até 100000 caracteres |
  | `data[].taxed` | qualquer | sim | Tributação (texto da tabela oficial). |
  | `data[].ibsReduction` | qualquer | sim | Percentual de redução do IBS. |
  | `data[].cbsReduction` | qualquer | sim | Percentual de redução da CBS. |
  | `data[].supported` | booleano | sim | true: a emitza já emite com este CST. |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `422`: CST inválido.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Reduções possíveis para um NCM

`GET /v1/tax/ncm/{ncm}`

Itens dos anexos da LC 214/2025 que citam o NCM (redução do IBS/CBS) e o Imposto Seletivo. A redução só vale se o produto corresponder à descrição legal.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `ncm` | caminho | sim | NCM com 8 dígitos (pontuação aceita). |

**Respostas**

- `200`: Reduções.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `ncm` | texto | sim | até 8 caracteres |
  | `reductions` | lista de objeto | sim |  |
  | `reductions[].annex` | texto | sim | até 10 caracteres |
  | `reductions[].item` | texto ou inteiro | sim |  |
  | `reductions[].description` | texto | sim | até 100000 caracteres |
  | `reductions[].classTrib` | texto ou null | sim | até 6 caracteres |
  | `reductions[].publicBuyerClassTrib` | texto ou null | sim | até 6 caracteres |
  | `reductions[].reduction` | texto ou número ou null | sim |  |
  | `reductions[].legalBasis` | texto | sim | até 100000 caracteres |
  | `selectiveTax` | qualquer ou null | sim | Imposto Seletivo possível para o NCM, ou null. |
  | `note` | texto | sim | até 100000 caracteres |
  | `source` | objeto | sim | Fonte das listas de NCM. |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `422`: NCM inválido.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Regras do IBS/CBS de um ano

`GET /v1/tax/rules`

Alíquotas do ano e o que ainda falta ser publicado pelo governo.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `year` | query |  | Ano (padrão: o atual). 2026 a 2033 |
| `crt` | query |  | Regime (padrão: 3). um de: `1`, `2`, `3`, `4` |

**Respostas**

- `200`: Regras.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `year` | inteiro | sim |  |
  | `rates` | objeto ou null | sim | Alíquotas do IBS (UF e município) e da CBS no ano. |
  | `source` | qualquer ou null | sim | Base legal das alíquotas. |
  | `pending` | lista de objeto | sim | Regras ainda não publicadas. |
  | `available` | booleano | sim | true: tudo publicado; dá para emitir com as regras do ano. |
  | `knownYears` | lista de inteiro | sim |  |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `422`: Ano ou crt inválido.
- `429`: Limite de requisições; espere o tempo de Retry-After.

## Webhooks

Avisos de resultado enviados ao seu sistema.

### Cadastrar webhook

`POST /v1/webhooks`

Os eventos chegam por POST com JSON, assinados com HMAC-SHA256 no cabeçalho X-Fiscal-Signature (t=<unix>,v1=<hex de HMAC("<t>.<corpo>")>). Responda 2xx em até 10 s; sem isso, novas tentativas por cerca de 24 h. Até 5 webhooks ativos.

**Corpo (JSON)**

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `url` | texto | sim | URL HTTPS que recebe os eventos (POST com JSON assinado). uri; 8 a 500 caracteres |
| `events` | lista de texto |  | Eventos assinados; "*" (padrão) recebe todos. um de: `*`, `nfe.authorized`, `nfe.rejected`, `nfe.denied`, `nfe.failed`, `nfe.event_rejected`, `nfe.cancelled`, `nfe.correction_registered`, `nfe.disabled`, `nfse.authorized`, `nfse.rejected`, `nfse.failed`, `nfse.cancelled`, `nfse.event_rejected`, `certificate.expiring`, `certificate.expired`, `sefaz.contingency_started`, `sefaz.contingency_ended`, `webhook.test` |

Exemplo:

```json
{
  "url": "https://seu-sistema.com.br/webhooks/emitza",
  "events": [
    "nfe.authorized",
    "nfe.rejected",
    "nfse.authorized",
    "nfse.rejected"
  ]
}
```

**Respostas**

- `201`: Webhook criado; o secret só aparece aqui.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `id` | texto | sim | até 24 caracteres |
  | `url` | texto | sim | até 500 caracteres |
  | `events` | lista de texto | sim | um de: `*`, `nfe.authorized`, `nfe.rejected`, `nfe.denied`, `nfe.failed`, `nfe.event_rejected`, `nfe.cancelled`, `nfe.correction_registered`, `nfe.disabled`, `nfse.authorized`, `nfse.rejected`, `nfse.failed`, `nfse.cancelled`, `nfse.event_rejected`, `certificate.expiring`, `certificate.expired`, `sefaz.contingency_started`, `sefaz.contingency_ended`, `webhook.test` |
  | `active` | booleano | sim |  |
  | `createdAt` | texto | sim | date-time |
  | `secret` | texto | sim | Segredo do HMAC. Aparece só nesta resposta: guarde para conferir a assinatura (cabeçalho X-Fiscal-Signature). até 200 caracteres |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `409`: URL repetida ou limite de 5 webhooks.
- `422`: URL recusada (precisa ser HTTPS e pública).
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Listar webhooks

`GET /v1/webhooks`

**Respostas**

- `200`: Webhooks ativos.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `data` | lista de qualquer | sim |  |
  | `data[].id` | texto | sim | até 24 caracteres |
  | `data[].url` | texto | sim | até 500 caracteres |
  | `data[].events` | lista de texto | sim | um de: `*`, `nfe.authorized`, `nfe.rejected`, `nfe.denied`, `nfe.failed`, `nfe.event_rejected`, `nfe.cancelled`, `nfe.correction_registered`, `nfe.disabled`, `nfse.authorized`, `nfse.rejected`, `nfse.failed`, `nfse.cancelled`, `nfse.event_rejected`, `certificate.expiring`, `certificate.expired`, `sefaz.contingency_started`, `sefaz.contingency_ended`, `webhook.test` |
  | `data[].active` | booleano | sim |  |
  | `data[].createdAt` | texto | sim | date-time |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Remover webhook

`DELETE /v1/webhooks/{id}`

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id do webhook. |

**Respostas**

- `204`: Removido.
- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Webhook não encontrado.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Enviar evento de teste

`POST /v1/webhooks/{id}/test`

Dispara um webhook.test para conferir a URL e a assinatura.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `id` | caminho | sim | id do webhook. |

**Respostas**

- `202`: Entrega na fila.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `deliveryId` | texto | sim | Identificador (24 caracteres hexadecimais). padrão `^[0-9a-f]{24}$`; 24 caracteres |
  | `status` | texto | sim | um de: `queued` |

- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `404`: Webhook não encontrado.
- `429`: Limite de requisições; espere o tempo de Retry-After.

## Cobertura

O que a emitza atende em cada município, por tipo de documento e regime.

### Cobertura por município

`GET /v1/coverage` (sem chave)

O que a emitza atende em cada município de SP: NF-e (todos, pela SEFAZ-SP) e NFS-e por regime, conforme a adesão do município ao emissor nacional, conferida todo mês no Sistema Nacional. Sem chave.

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `uf` | query |  | UF (por enquanto, só SP). um de: `SP` |

**Respostas**

- `200`: Municípios da UF.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `uf` | texto | sim | até 2 caracteres |
  | `updatedAt` | texto ou null | sim | Fim da última conferência completa (mensal). date-time |
  | `data` | lista de qualquer | sim |  |
  | `data[].cityCode` | texto | sim | até 7 caracteres |
  | `data[].name` | texto | sim | até 100000 caracteres |
  | `data[].uf` | texto | sim | até 2 caracteres |
  | `data[].nfe` | objeto | sim | NF-e: todos os municípios de SP, pela SEFAZ-SP. |
  | `data[].nfse` | objeto | sim | NFS-e por regime. |
  | `data[].checkedAt` | texto ou null | sim | Quando a adesão foi conferida no Sistema Nacional (ADN). date-time |

- `422`: UF não atendida.
- `429`: Limite de requisições; espere o tempo de Retry-After.

### Cobertura de um município

`GET /v1/coverage/{cityCode}` (sem chave)

**Parâmetros**

| Nome | Onde | Obrigatório | Descrição |
|---|---|---|---|
| `cityCode` | caminho | sim | Código IBGE do município (7 dígitos). |

**Respostas**

- `200`: Município.

  | Campo | Tipo | Obrigatório | Descrição |
  |---|---|---|---|
  | `cityCode` | texto | sim | até 7 caracteres |
  | `name` | texto | sim | até 100000 caracteres |
  | `uf` | texto | sim | até 2 caracteres |
  | `nfe` | objeto | sim | NF-e: todos os municípios de SP, pela SEFAZ-SP. |
  | `nfe.status` | texto | sim | um de: `available` |
  | `nfe.via` | texto | sim | um de: `SEFAZ-SP` |
  | `nfse` | objeto | sim | NFS-e por regime. |
  | `nfse.agreement` | booleano ou null | sim | Município conveniado ao Sistema Nacional da NFS-e. |
  | `nfse.nationalIssuer` | booleano ou null | sim | Aceita os emissores nacionais. null: ainda não conferido. |
  | `nfse.simplesMei` | objeto | sim | MEI e Simples Nacional. |
  | `nfse.otherRegimes` | objeto | sim | Lucro Presumido e Lucro Real. |
  | `checkedAt` | texto ou null | sim | Quando a adesão foi conferida no Sistema Nacional (ADN). date-time |

- `404`: Município fora de SP ou inexistente.
- `422`: Código IBGE inválido.
- `429`: Limite de requisições; espere o tempo de Retry-After.

## MCP

Servidor MCP para assistentes de IA emitirem notas com a sua chave.

### Servidor MCP (para IA)

`POST /mcp`

Model Context Protocol no transporte Streamable HTTP, sem sessão e com respostas em JSON. Configure no cliente de IA a URL https://api-sandbox.emitza.com.br/mcp (ou api.emitza.com.br/mcp) com o cabeçalho Authorization: Bearer <chave>. Tools: consultar_conta, listar_empresas, cadastrar_empresa, calcular_impostos, emitir_nfe, emitir_nfse, consultar_nota, cancelar_nota, baixar_documento.

**Respostas**

- `200`: Resposta JSON-RPC 2.0.
- `202`: Só notificações: nada a responder.
- `401`: Chave de API ausente, inválida ou do tipo errado para o endereço (fsk_test_ só em api-sandbox, fsk_live_ só em api).
- `403`: Origin não permitido (navegador de outro site).
- `429`: Limite de requisições; espere o tempo de Retry-After.

## Webhooks

Cada evento chega por POST com { id, event, createdAt, data }, assinado no cabeçalho X-Fiscal-Signature (t=<unix>,v1=<HMAC-SHA256 hex de "<t>.<corpo>">).

### nfe.authorized

NF-e autorizada pela SEFAZ. O XML e o DANFE já podem ser baixados.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.id` | texto | sim | id da NF-e. até 24 caracteres |
| `data.externalId` | texto | sim | até 100 caracteres |
| `data.companyId` | texto | sim | até 24 caracteres |
| `data.environment` | texto | sim | um de: `homologation`, `production` |
| `data.series` | inteiro | sim |  |
| `data.number` | inteiro ou null | sim |  |
| `data.accessKey` | texto ou null | sim | até 44 caracteres |
| `data.protocol` | texto | sim | até 20 caracteres |
| `data.authorizedAt` | texto | sim | date-time |

### nfe.rejected

NF-e rejeitada (cStat e motivo da SEFAZ). Corrija o pedido e reenvie com o mesmo externalId.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.id` | texto | sim | id da NF-e. até 24 caracteres |
| `data.externalId` | texto | sim | até 100 caracteres |
| `data.companyId` | texto | sim | até 24 caracteres |
| `data.environment` | texto | sim | um de: `homologation`, `production` |
| `data.series` | inteiro | sim |  |
| `data.number` | inteiro ou null | sim |  |
| `data.accessKey` | texto ou null | sim | até 44 caracteres |
| `data.cStat` | texto | sim | até 10 caracteres |
| `data.reason` | texto | sim | até 100000 caracteres |

### nfe.denied

Uso denegado: a SEFAZ registrou a nota, mas ela não vale (irregularidade do emitente ou destinatário). O número fica consumido.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.id` | texto | sim | id da NF-e. até 24 caracteres |
| `data.externalId` | texto | sim | até 100 caracteres |
| `data.companyId` | texto | sim | até 24 caracteres |
| `data.environment` | texto | sim | um de: `homologation`, `production` |
| `data.series` | inteiro | sim |  |
| `data.number` | inteiro ou null | sim |  |
| `data.accessKey` | texto ou null | sim | até 44 caracteres |
| `data.cStat` | texto ou null | sim | até 10 caracteres |
| `data.reason` | texto ou null | sim | até 100000 caracteres |

### nfe.failed

A emissão parou sem resposta da SEFAZ (ex.: certificado vencido). Corrija e chame POST /v1/nfe/{id}/retry.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.id` | texto | sim | id da NF-e. até 24 caracteres |
| `data.externalId` | texto | sim | até 100 caracteres |
| `data.companyId` | texto | sim | até 24 caracteres |
| `data.environment` | texto | sim | um de: `homologation`, `production` |
| `data.series` | inteiro | sim |  |
| `data.number` | inteiro ou null | sim |  |
| `data.accessKey` | texto ou null | sim | até 44 caracteres |
| `data.failure` | texto | sim | até 60 caracteres |
| `data.reason` | texto ou null | sim | até 100000 caracteres |

### nfe.cancelled

Cancelamento registrado na SEFAZ.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.id` | texto | sim | id da NF-e. até 24 caracteres |
| `data.externalId` | texto | sim | até 100 caracteres |
| `data.accessKey` | texto | sim | até 44 caracteres |
| `data.event` | objeto | sim |  |
| `data.event.id` | texto | sim | até 24 caracteres |
| `data.event.type` | texto | sim | um de: `cancel`, `correction` |
| `data.event.sequence` | inteiro | sim |  |
| `data.protocol` | texto | sim | até 20 caracteres |
| `data.cStat` | texto | sim | até 10 caracteres |

### nfe.correction_registered

Carta de correção registrada.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.id` | texto | sim | id da NF-e. até 24 caracteres |
| `data.externalId` | texto | sim | até 100 caracteres |
| `data.accessKey` | texto | sim | até 44 caracteres |
| `data.event` | objeto | sim |  |
| `data.event.id` | texto | sim | até 24 caracteres |
| `data.event.type` | texto | sim | um de: `cancel`, `correction` |
| `data.event.sequence` | inteiro | sim |  |
| `data.protocol` | texto | sim | até 20 caracteres |
| `data.text` | texto | sim | até 100000 caracteres |

### nfe.event_rejected

Cancelamento, carta de correção (com "event") ou inutilização (kind "disable") rejeitado ou com falha.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.id` | texto | sim | até 24 caracteres |
| `data.externalId` | texto |  | até 100 caracteres |
| `data.accessKey` | texto |  | até 44 caracteres |
| `data.event` | objeto |  |  |
| `data.event.id` | texto | sim | até 24 caracteres |
| `data.event.type` | texto | sim | um de: `cancel`, `correction` |
| `data.event.sequence` | inteiro | sim |  |
| `data.kind` | texto |  | um de: `disable` |
| `data.companyId` | texto |  | até 24 caracteres |
| `data.environment` | texto |  | um de: `homologation`, `production` |
| `data.series` | inteiro |  |  |
| `data.from` | inteiro |  |  |
| `data.to` | inteiro |  |  |
| `data.cStat` | texto |  | até 10 caracteres |
| `data.failure` | texto |  | até 60 caracteres |
| `data.reason` | texto ou null |  | até 100000 caracteres |

### nfe.disabled

Faixa de numeração inutilizada.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.id` | texto | sim | id da inutilização. até 24 caracteres |
| `data.companyId` | texto | sim | até 24 caracteres |
| `data.environment` | texto | sim | um de: `homologation`, `production` |
| `data.series` | inteiro | sim |  |
| `data.from` | inteiro | sim |  |
| `data.to` | inteiro | sim |  |
| `data.protocol` | texto ou null | sim | até 20 caracteres |
| `data.cStat` | texto | sim | até 10 caracteres |

### nfse.authorized

NFS-e gerada pelo Sistema Nacional. XML e DANFSe disponíveis.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.id` | texto | sim | id da NFS-e. até 24 caracteres |
| `data.externalId` | texto | sim | até 100 caracteres |
| `data.companyId` | texto | sim | até 24 caracteres |
| `data.environment` | texto | sim | um de: `homologation`, `production` |
| `data.dpsSeries` | inteiro | sim |  |
| `data.dpsNumber` | inteiro ou null | sim |  |
| `data.accessKey` | texto ou null | sim | até 50 caracteres |
| `data.number` | texto ou null | sim | até 20 caracteres |
| `data.authorizedAt` | texto | sim | date-time |
| `data.values` | objeto | sim | Valores da NFS-e gerada. |

### nfse.rejected

DPS rejeitada pelo Sefin (lista de erros com código). Corrija e reenvie com o mesmo externalId.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.id` | texto | sim | id da NFS-e. até 24 caracteres |
| `data.externalId` | texto | sim | até 100 caracteres |
| `data.companyId` | texto | sim | até 24 caracteres |
| `data.environment` | texto | sim | um de: `homologation`, `production` |
| `data.dpsSeries` | inteiro | sim |  |
| `data.dpsNumber` | inteiro ou null | sim |  |
| `data.accessKey` | texto ou null | sim | até 50 caracteres |
| `data.number` | texto ou null | sim | até 20 caracteres |
| `data.errors` | lista de objeto | sim |  |
| `data.errors[].code` | texto ou null | sim | até 20 caracteres |
| `data.errors[].message` | texto ou null | sim | até 100000 caracteres |
| `data.errors[].complement` | texto ou null | sim | até 100000 caracteres |

### nfse.failed

A emissão parou sem resposta do Sefin. Corrija e chame POST /v1/nfse/{id}/retry.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.id` | texto | sim | id da NFS-e. até 24 caracteres |
| `data.externalId` | texto | sim | até 100 caracteres |
| `data.companyId` | texto | sim | até 24 caracteres |
| `data.environment` | texto | sim | um de: `homologation`, `production` |
| `data.dpsSeries` | inteiro | sim |  |
| `data.dpsNumber` | inteiro ou null | sim |  |
| `data.accessKey` | texto ou null | sim | até 50 caracteres |
| `data.number` | texto ou null | sim | até 20 caracteres |
| `data.failure` | texto | sim | até 60 caracteres |
| `data.reason` | texto ou null | sim | até 100000 caracteres |

### nfse.cancelled

Cancelamento da NFS-e registrado.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.id` | texto | sim | id da NFS-e. até 24 caracteres |
| `data.externalId` | texto | sim | até 100 caracteres |
| `data.companyId` | texto | sim | até 24 caracteres |
| `data.accessKey` | texto | sim | até 50 caracteres |
| `data.eventId` | texto | sim | até 24 caracteres |
| `data.type` | texto | sim | um de: `cancel` |
| `data.cancelledAt` | texto | sim | date-time |

### nfse.event_rejected

Cancelamento da NFS-e rejeitado.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.id` | texto | sim | id da NFS-e. até 24 caracteres |
| `data.externalId` | texto | sim | até 100 caracteres |
| `data.companyId` | texto | sim | até 24 caracteres |
| `data.accessKey` | texto | sim | até 50 caracteres |
| `data.eventId` | texto | sim | até 24 caracteres |
| `data.type` | texto | sim | um de: `cancel` |
| `data.errors` | lista de objeto | sim |  |
| `data.errors[].code` | texto ou null | sim | até 20 caracteres |
| `data.errors[].message` | texto ou null | sim | até 100000 caracteres |
| `data.errors[].complement` | texto ou null | sim | até 100000 caracteres |

### certificate.expiring

O certificado da empresa vence em breve (avisos a 30, 15 e 7 dias).

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.companyId` | texto | sim | até 24 caracteres |
| `data.cnpj` | texto | sim | até 14 caracteres |
| `data.notAfter` | texto | sim | date-time |
| `data.daysLeft` | inteiro | sim |  |

### certificate.expired

O certificado da empresa venceu; as emissões param até o envio de um novo.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.companyId` | texto | sim | até 24 caracteres |
| `data.cnpj` | texto | sim | até 14 caracteres |
| `data.notAfter` | texto | sim | date-time |
| `data.daysLeft` | inteiro | sim |  |

### sefaz.contingency_started

Reservado: contingência da SEFAZ (ainda não enviado).

data: objeto livre.

### sefaz.contingency_ended

Reservado: fim da contingência (ainda não enviado).

data: objeto livre.

### webhook.test

Disparado por POST /v1/webhooks/{id}/test.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `data.message` | texto | sim | até 100000 caracteres |