# Perguntas frequentes sobre a API DFe.

## Quais documentos fiscais a API DFe suporta?
A API DFe cobre **NF-e** (modelo 55), **NFC-e** (modelo 65) e **NFS-e**, além de recursos complementares:

- Emissão individual ou em lote;
- Cancelamento, inutilização de numeração e Carta de Correção (CC-e);
- Download de XML e DANFE/DANFCE/DANFSE (PDF);
- Consultas por chave, lote, série + número, id e idExternal;
- Distribuição DFe (notas destinadas ao seu CNPJ);
- Listas fiscais (NCM, CFOP, CEST, CSTs), IBPT e cálculo de impostos (em beta).

## O que é tpAmb e qual ambiente devo usar?
O ambiente é definido pelo campo **tpAmb** em cada requisição:

| tpAmb | Ambiente |
|---|---|
| 1 | Produção (validade fiscal) |
| 2 | Homologação (testes, sem validade fiscal) |

Comece em homologação (`tpAmb: 2`). Quando o fluxo estiver validado, passe a emitir com `tpAmb: 1`.

## Qual é a URL base da API?
A URL base é `https://api-dfe.dadosjah.com.br/v1/`. Como temos apenas uma versão no momento, usaremos a v1. Exemplo: para emitir uma NFC-e, faça `POST https://api-dfe.dadosjah.com.br/v1/nfce`.

**Homologação e produção usam a mesma URL** — o que define o ambiente é o campo `tpAmb` de cada requisição (`1` = produção, `2` = homologação). Não há URL separada para testes.

## Posso emitir para vários CNPJs com uma única conta?
Sim. Com a sua conta **Sistema** (SYSTEM) você cadastra quantos clientes/usuários quiser — não há limite de CNPJs. Cada cliente recebe uma credencial própria (`email` e `password`, definidos por você no cadastro) e gera o **próprio token** na rota `POST /v1/auth/user/login`. Todas as requisições do cliente devem usar esse token, que é o que identifica o emitente.

- Rotas do cliente: grupo **"Usuários"** da [collection do Postman](https://documenter.getpostman.com/view/53424652/2sBXikoBN8#dda9717d-105e-44c5-9cf2-2e32c1c23123).
- Rotas do sistema: grupo **"Sistema"** da [collection do Postman](https://documenter.getpostman.com/view/53424652/2sBXikoBN8#7f79e5dd-5065-4133-9bc4-a22eeb6d0f03) — o token de sistema serve apenas para cadastrar e editar seus clientes.

## Para emitir notas (ex.: POST /nfce), uso o token de sistema?
Não. Use o token obtido em `POST /v1/auth/user/login` — ou seja, crie um usuário/credencial para **cada emitente**. Dessa forma cada CNPJ tem autenticação e histórico separados.

## Como faço login e gero o token de acesso?
Envie um JSON com `email` e `password` em uma das rotas de autenticação:

- `POST /v1/auth/system/login` — credenciais do **sistema** (usadas nas rotas do grupo Sistema);
- `POST /v1/auth/user/login` — credenciais do **usuário** (usadas nas rotas de emissão e demais operações).

```json
{
  "email": "seu-email",
  "password": "sua-senha"
}
```

A resposta traz o `accessToken`, que deve ser enviado no cabeçalho `Authorization: Bearer SEU_TOKEN` em todas as chamadas. Veja o guia completo em [Autenticação](#/api/comecando/autenticacao).

## As credenciais do painel são as mesmas da API?
Sim. O mesmo `email` e `password` usados para entrar no painel podem ser usados como credenciais da API. Se preferir, é possível trocar as credenciais usadas **apenas na emissão de DFe** — pelo painel ou via API.

## Como cadastro um novo cliente/emitente?
Na rota `POST /v1/user` (token de sistema) você envia:

- `name` — nome/razão social do cliente;
- `cnpj` — CNPJ ou CPF do cliente (com ou sem pontuação);
- `email` — será o login do cliente;
- `password` — senha criada por você para o cliente autenticar;
- `idExternal` — opcional; código do cliente no seu sistema/CRM, para conciliação;
- `nfceCSC`, `nfceIdCSC`, `nfceVersaoQRCode` — opcionais; necessários apenas para NFC-e com QR Code versão 2 (veja a pergunta sobre CSC);
- `timezone` — fuso horário do cliente (ex.: `-03:00`), para que data/hora de emissão e saída fiquem corretas;
- `notification` — ativa/desativa o envio de e-mail após a emissão;
- `vTotTribCalculate` — se `true`, a API calcula o valor aproximado dos tributos (tag `vTotTrib`) automaticamente.

Veja o exemplo completo em [Criar Usuário na collection](https://documenter.getpostman.com/view/53424652/2sBXikoBN8#122aa5a4-9bff-4355-aec7-123618be3d1d) e a edição em [Modificar Dados Usuários](https://documenter.getpostman.com/view/53424652/2sBXikoBN8#315a66b9-5fda-4e0e-8e15-7aaf84427ad5).

## Para que serve a rota /emit?
`POST /v1/emit` faz o **pré-cadastro do grupo `emit`** (CNPJ/CPF, razão social, nome fantasia, endereço, IE, CRT, IM). Assim você não precisa enviar o grupo `emit` em cada payload de emissão — a API usa os dados pré-cadastrados. Caso você envie o grupo `emit` no payload, a API considera o que você enviou (prevalece sobre o cadastro).

O mesmo vale para o grupo `autXML` na rota `POST /v1/autxml` (autorização para download de XML).

## Como funciona o CSC da NFC-e?
Para emitir NFC-e com QR Code **versão 2** (`nfceVersaoQRCode: "2"`), você deve informar `nfceCSC` e `nfceIdCSC` — enviados **uma única vez** no cadastro/edição do usuário (`POST`/`PATCH /v1/user`). Para a **versão 3** (`nfceVersaoQRCode: "3"`) não é necessário.

## Como envio o certificado digital A1 (POST /certificate)?
Faça um `POST /v1/certificate` enviando:

- `file` — o certificado em **base64**;
- `password` — a senha do certificado;
- `extension` — a extensão do certificado, geralmente `.pfx`.

Veja o exemplo em [Enviar Certificado na collection](https://documenter.getpostman.com/view/53424652/2sBXikoBN8#c8bd7d65-eb7c-4d28-b86c-8c76dedc5581).

## Posso usar certificado digital A3?
Não. A API trabalha apenas com certificado **A1**, pois ele é enviado como arquivo (`.pfx` em base64) e utilizado pelo nosso servidor nas assinaturas. O modelo A3 depende de mídia física (token ou cartão), o que não é compatível com a emissão via API.

## O certificado A1 fica armazenado? Preciso reenviá-lo a cada emissão?
Não precisa reenviar. O certificado e a senha são armazenados no nosso servidor e utilizados automaticamente nas próximas emissões. Ao cadastrar, confira se a senha está correta e se o certificado está dentro da validade.

## Preciso de um certificado digital para emitir notas?
Sim, é necessário o certificado digital para emitir NFe/NFCe e credenciamento com a Sefaz do estado (fique atento quanto a autorização para emitir em homologação/produção).

Já a NFSe, depende do provedor, alguns pedem apenas um usuário e senha.

## Qual a diferença entre emissão síncrona e assíncrona?
O campo `async` do payload define:

- `false` (síncrona): a API aguarda a resposta da Sefaz e retorna a nota autorizada com XML e PDF. Permite **1 nota por requisição**. Ajuste o timeout da sua aplicação (60 segundos é um bom valor);
- `true` (assíncrona): a API retorna um `idBatch` imediatamente e processa em segundo plano. Permite até **50 notas** por lote. Consulte o resultado depois.

## Como consulto o resultado de uma emissão assíncrona (idBatch)?
Use as rotas de consulta. Exemplo para NFC-e (as mesmas rotas existem para NF-e e NFS-e):

| Consulta | Rota |
|---|---|
| Por lote | `GET /v1/nfce?idBatch=...` |
| Por chave e ambiente | `GET /v1/nfce?chDfe=...&tpAmb=...` |
| Por ambiente, série e número | `GET /v1/nfce?nNF=...&tpAmb=...&serie=...` |
| Por idDfe | `GET /v1/nfce?idDfe=...` |
| Por idExternal | `GET /v1/nfce?idExternal=...` |
| Direto na Sefaz | `GET /v1/nfce/sefaz?chDfe=...&tpAmb=...` |

Na collection: [por lote](https://documenter.getpostman.com/view/53424652/2sBXikoBN8#3fb3f62a-8f50-432d-b64a-65e306ca9fcc), [por chave e ambiente](https://documenter.getpostman.com/view/53424652/2sBXikoBN8#b08f5847-d76b-4c00-8fb1-48363f273684), [por ambiente, série e número](https://documenter.getpostman.com/view/53424652/2sBXikoBN8#3d6382af-af87-4713-bfe0-fb9dacdb13cb), [por idDfe](https://documenter.getpostman.com/view/53424652/2sBXikoBN8#998710f9-c454-4bf1-82fd-13d9a9d82485), [por idExternal](https://documenter.getpostman.com/view/53424652/2sBXikoBN8#33e195f2-a067-44fb-8e2a-79014aab2212) e [consulta na Sefaz](https://documenter.getpostman.com/view/53424652/2sBXikoBN8#d06e49b8-7fab-40e8-8e96-dfd6ebd53476).

## Se uma nota de um lote for rejeitada, as demais são afetadas?
Não. Mesmo em lotes de até 50 notas, elas são enviadas à Sefaz **uma a uma**. Se uma falhar, as demais do lote continuam normalmente.

## Quem controla a série e o número (nNF) das notas?
O **seu sistema**. A API Dados Jah é apenas a ponte entre o seu sistema e a Sefaz — a sequência de série e numeração fica sob sua responsabilidade.

## Existe um payload mínimo/exemplo para a primeira NFC-e em homologação?
Sim. Na [collection do Postman](https://documenter.getpostman.com/view/53424652/2sBXikoBN8) cada rota tem exemplos de requisição. A estrutura principal do payload de emissão é:

- `async` — define síncrono/assíncrono;
- `NFCe` — array com uma ou mais notas, cada uma com:
  - `idExternal` — opcional, para conciliação;
  - `infNF` — com os blocos `ide` (identificação), `emit` (pode ser omitido se pré-cadastrado), `dest`, `det` (itens e impostos), `total`, `transp`, `infAdic`, `pag` e `infRespTec`.

## Como emito nota complementar, de ajuste ou de devolução?
O campo `finNFe` (bloco `ide`) define a finalidade da nota:

| finNFe | Finalidade |
|---|---|
| 1 | Normal |
| 2 | Complementar |
| 3 | Ajuste |
| 4 | Devolução |

Envie o valor correspondente no payload da emissão, junto com os demais campos exigidos para cada finalidade.

## Como obtenho o XML e o DANFE das notas?
As respostas de emissão e consulta trazem o conteúdo e os links:

- `xml` e `pdf` — conteúdo em base64 (pode ser grande e lento) no pdf, o xml é retornado em texto;
- `xmlLink` e `pdfLink` — URLs assinadas para download, válidas por até **36 horas**.

> **Dica:** prefira `xmlLink` e `pdfLink` para baixar os arquivos, mas lembre-se que há um prazo para expirar estes downloads.

> **Atenção:** em homologação os arquivos não são armazenados no servidor, então a API retorna apenas `xml` e `pdf` em base64, sem os links.

Há também rotas dedicadas para obter XML e DANFE/DANFCE/DANFSE por chave, idDfe, idExternal, etc. — consulte a [collection](https://documenter.getpostman.com/view/53424652/2sBXikoBN8).

## A rota /nfce/danfe/xml aceita o XML completo de uma NFC-e já autorizada, incluindo protocolo, para gerar novamente o DANFCE?
Isto, este endpoint foi feito para você enviar um xml, seja ele autorizado pelo DadosJah ou não (é possível enviar xml autorizados em homologação ou até mesmo uma nota em produção sem autorização de uso) e transformar num DANFCe. 

> **Informação:** ao utilizar esta rota, não é emitido uma nova nota, é apenas gerado o PDF.

## Os XMLs ficam armazenados? Por quanto tempo?
Sim. Os XMLs emitidos em **produção** são armazenados na AWS S3 (classe Standard) com redundância em outro servidor. Os links de download (`xmlLink` e `pdfLink`) ficam disponíveis por até **36 horas**, mas os arquivos continuam acessíveis pelas rotas de consulta da API. Por enquanto não há cobrança pelo armazenamento.

Em **homologação** os arquivos não são armazenados — a API retorna apenas o conteúdo em base64.

## Ao emitir em Produção, o XML fica disponível para recuperar posteriormente pela rota /xml?
Sim, em Produção o XML é armazenado em nossa conta AWS S3 e fica disponível para download a qualquer momento, além de ficar armazenado como texto em uma base de dados em outro servidor como redundância.

Em **homologação** os arquivos não são armazenados e portanto não é possível utilizar esta rota para recuperar o xml.
Ao utilizar esta rota, será retornado "XML EM HOMOLOGAÇÃO NÃO É SALVO".

## Como recebo as notas emitidas contra o meu CNPJ?
Use as rotas de **Distribuição DFe**, que consultam as notas destinadas ao seu CNPJ:

- `POST /v1/nfe/distribution/last-nsu` — últimas notas a partir de um ultNSU;
- `POST /v1/nfe/distribution/nsu` — consulta por NSU específico;
- `POST /v1/nfe/distribute-dfe-by-key` — consulta por chave;
- `POST /v1/nfe/distribution` — consulta geral.

Consulte os parâmetros de cada rota na [collection do Postman](https://documenter.getpostman.com/view/53424652/2sBXikoBN8).

## Como cancelar ou inutilizar uma nota?
- Cancelamento: `POST /v1/nfe/cancel` (NFC-e: `POST /v1/nfce/cancel`);
- Inutilização de numeração: `POST /v1/nfe/disenable` (NFC-e: `POST /v1/nfce/disenable`);
- Carta de Correção e outros eventos: `POST /v1/nfe/events`.

> **Importante:** as justificativas (`xJust` para cancelamento/inutilização, `xCorrecao` para CC-e) são obrigatórias e precisam de no mínimo **15 caracteres**.

## O que são cStat, xMotivo e nProt?
São campos retornados pela Sefaz em cada operação:

- `cStat` — código numérico do resultado (ex.: `100` = autorizado);
- `xMotivo` — descrição textual do resultado;
- `nProt` — protocolo de autorização; só vem preenchido quando a nota foi **autorizada** (é a prova legal de validade).

Se a nota for rejeitada, leia o `xMotivo` para entender a causa e corrija o payload.

## A API envia e-mail ao destinatário da nota?
Sim. Ao emitir uma nota em **Produção** (`tpAmb: 1`), a API envia um e-mail transacional ao destinatário com as informações da nota e os arquivos XML e PDF em anexo. Em **homologação** (`tpAmb: 2`) nenhum e-mail real é enviado, para evitar spam durante os testes.

Também é possível reenviar o e-mail depois, usando `POST /v1/nfe/resend-email` (o mesmo vale para NFC-e e NFS-e).

> **Importante:** Só é enviado e-mail caso o tomador da NFS-e ou o destinatário da NF-e/NFC-e tenha um e-mail cadastrado e esteja marcado como `true` em `notification` no cadastro do usuário da API.

## A API envia notificações (webhooks) quando uma nota é emitida?
Ainda não. O serviço de webhooks está planejado, mas por enquanto a única notificação disponível é o **e-mail** enviado após a emissão (campo `notification` no cadastro do usuário). Hoje, para acompanhar o status das operações, use as rotas de consulta (polling) — veja a pergunta sobre emissão assíncrona.

## Posso consultar o histórico das minhas requisições?
Sim. A rota `GET /v1/request` retorna o histórico de requisições da API, útil para auditoria e conciliação.

## Onde obtenho as listas fiscais (NCM, CFOP, CEST, CST)?
A API disponibiliza rotas de consulta para as listas fiscais:

- `GET /v1/lists/ncm` — NCM;
- `GET /v1/lists/cfop` — CFOP;
- `GET /v1/lists/cest` — CEST;
- `GET /v1/lists/icms` — tributação de ICMS (CST/CSOSN);
- `GET /v1/lists/ipi`, `GET /v1/lists/pis` e `GET /v1/lists/cofins` — CSTs de IPI, PIS e COFINS.

## Como gero ou desmonto a chave de acesso?
Use as rotas utilitárias:

- `POST /v1/util/nfe/chDfe`, `POST /v1/util/nfce/chDfe` e `POST /v1/util/nfse/chDfe` — geram a chave de acesso a partir dos campos que a compõem;
- `POST /v1/util/nfe/chDfe-info` (e equivalentes) — retornam as informações de uma chave;
- `POST /v1/util/cUF` e `POST /v1/util/UF` — convertem entre código e sigla de UF.

## Como verifico se o serviço da Sefaz está disponível?
Use a rota de status do serviço, informando a UF e o ambiente:

- `GET /v1/nfe/service-status?UF=...&tpAmb=...`
- `GET /v1/nfce/service-status?UF=...&tpAmb=...`

## Como verifico se a API está no ar?
Use a rota `GET /v1/health/api` ou acompanhe a [página de status](https://status.dadosjah.com.br/status/dadosjah).

## Como identifico um prestador MEI ou optante pelo Simples Nacional na NFS-e?
Use o campo `opSimpNac` do bloco Prestador. **O domínio depende do provedor da cidade:**

| Provedor | Valores aceitos |
|---|---|
| ABRASF | `1` = Sim, `2` = Não |
| Padrão Nacional (DPS) | `1` = Não Optante, `2` = MEI, `3` = ME/EPP |

> **Atenção:** a numeração tem significados **opostos** entre os padrões — `1` é `Sim` no ABRASF e `Não Optante` no Padrão Nacional; `2` é `Não` no ABRASF e `MEI` no Padrão Nacional. Confirme sempre no manual do provedor da cidade.

Envie o valor conforme o manual do provedor da cidade. O valor é repassado para o XML exatamente como enviado — valores fora do domínio causam erro de validação de schema.

## Os nomes dos campos do payload são iguais aos do XML?
Não necessariamente. Alguns campos têm o mesmo nome no payload e no XML, outros mudam. Exemplos:

| Payload | XML (leiaute oficial) |
|---|---|
| `RegimeApuracaoSN` | `regApTribSN` |
| `Regime` | `regEspTrib` |

Use os exemplos da [collection do Postman](https://documenter.getpostman.com/view/53424652/2sBXikoBN8) como referência dos campos do payload.

Campos **opcionais** podem ser omitidos sem problema. Já campos **obrigatórios** ausentes podem gerar erro de schema XML ou receber um valor padrão definido pelo provedor — por isso, envie explicitamente os campos exigidos no manual da cidade.

## Quais valores o campo Regime (regEspTrib) aceita?
O campo `Regime` do payload corresponde ao `regEspTrib` do XML. Valores aceitos:

| Valor | Descrição |
|---|---|
| `0` | Nenhum |
| `1` | Cooperativa |
| `2` | Estimativa |
| `3` | Microempresa municipal |
| `4` | Notário ou registrador |
| `5` | ISS de autônomos |
| `6` | Sociedade de profissionais |
| `9` | Outros |

## Como devo enviar campos opcionais que não se aplicam ao meu caso?
A melhor opção é **omitir** o campo. Você também pode enviar `""` (vazio). Campos opcionais sem valor ou com valor zero não são gerados no XML.

Isso vale para campos **opcionais** — campos que identificam o regime (como `opSimpNac`) devem ser enviados conforme o manual do provedor, quando exigidos.

## A API aplica automaticamente as regras do leiaute para MEI na NFS-e?
Parcialmente. A biblioteca **ACBr** (open source) utilizada internamente já aplica algumas regras de negócio conforme o provedor, mas o ideal é **enviar os campos de forma explícita**, omitindo ou preenchendo conforme o manual do provedor da cidade.

## A API aceita CRT = 4 (MEI) na NF-e?
Sim. A API aceita `CRT: 4`. A API valida apenas o **schema do XML**; as validações de negócio (como as regras da NT 2024.001) ficam com a Sefaz, que retorna a rejeição caso algo esteja em desacordo — a API não faz essa validação previamente para não barrar notas que seriam aceitas.

## Qual versão do leiaute nacional da NFS-e a API atende?
A API utiliza internamente a biblioteca **ACBr** (open source) e acompanha as atualizações dela. A API está alinhada à **NT 007**, com itens das NT 008 e 009 ainda dependentes da evolução da biblioteca. Na medida em que for atualizado no ACBr, será na API também.

## Quais valores o campo tipoXML aceita?
Os valores aceitos são `RPS` e `NFSE`:

- `RPS` — ao enviar RPS/DPS;
- `NFSE` — ao enviar uma NFS-e.

## Consigo emitir NFSe no padrão nacional mesmo que a cidade do prestador use provedor próprio?
Sim é possível. Basta enviar o parâmetro `layoutNFSe` da rota com o valor 2.

Nas rotas da NFSe (veja os exemplos da [collection do Postman](https://documenter.getpostman.com/view/53424652/2sBXikoBN8#c4051c1a-ee3c-4388-8846-412cc9b9589b)) o parâmetro layoutNFSe define se vai utilizar o provedor configurado da cidade ou se vai forçar o uso do padrão nacional.
O layoutNFSe tem 3 valores possíveis, sendo o `0` valor padrão e `2` o valor recomendado para emissão no Padrão Nacional, já que é a última versão disponível.
- `0` Usar o Provedor configurado na cidade;
- `1` Forçar o Padrão Nacional versão 1.00, independente do provedor configurado para a cidade;
- `2` Forçar o Padrão Nacional versão 1.01, independente do provedor configurado para a cidade;