# Conceitos

Conceitos de documentos fiscais na API DFe: NF-e, NFC-e, NFS-e e operações disponíveis.

## Requisições Sincrona e Assincrona

Ao emitir notas ou enviar eventos, o campo **async** deve ser enviado com o valor *true* ou *false*, onde:
 - **true (emissão assíncrona)**: 
O sistema retorna um idBatch (ID do lote) instantaneamente, e o processamento ocorre em segundo plano. O usuário deve consultar o status depois.

 - **false (emissão síncrona)**: 
O sistema aguarda a resposta da SEFAZ e retorna imediatamente os dados da nota autorizada, incluindo o XML e o PDF.
É importante ajustar o timeout da sua aplicação para que não ocorra erro antes de ser retornado a resposta da requisição. O padrão geralmente é 5000ms, mas 60000ms é um bom tempo também.

> **Importante:** Na emissão síncrona só é possível enviar uma nota por vez, já na assíncrona o limite é 50.

## Emissão em lote

Mesmo enviando um lote com 50 notas, elas não são enviadas como um único lote para a sefaz, internamente são enviadas de forma separada, uma a uma, desta forma caso uma das notas dê problema, não atrapalha as demais do lote.

## Cadastros de Emitente e AutXML

Na emissão das notas é enviado tanto o grupo do emitente (*emit*) quanto o grupo de autorização de xml (*autxml*), mas para evitar de enviar estes grupos em todas as requisições, é possível fazer um pré-cadastro destas informações e na emissão das notas suprimir estes dois grupos, desta forma é enviado os dados já pré-cadastrados. Caso estes dados estejam pré-cadastrados e seja enviado na requisição, será considerado os dados na requisição.

Utilize a rota /emit para cadastrar o emitente e /autxml para cadastrar o grupo de autorização do xml.

## Campos Críticos de Documentos Fiscais Eletrônicos (DF-e)

Vários campos são recorrentes e cruciais em diferentes documentos fiscais (NF-e, NFC-e, Eventos).
Abaixo listamos os principais:

### tpAmb (Tipo de Ambiente):

**Descrição**: Indica o ambiente da operação fiscal.

**Orientação**: Fundamental em todas as operações fiscais. Use 1 para Produção (validade legal) e 2 para Homologação/Teste (sem validade fiscal).

### chDfe (Chave de Acesso do DF-e):

**Descrição**: Identificador único de 44 dígitos do Documento Fiscal Eletrônico (NF-e, NFC-e, CT-e, etc.) perante a SEFAZ.

**Orientação**: A "identidade" da nota. Retornada em sucesso de emissão/autorização e principal identificador para consultas, cancelamentos, etc.

**Observação**: É possível gerar a chave de acesso a partir da rota /util/nfe/chDfe enviando os campos que compõe a chave.

### cStat e xMotivo (Status da SEFAZ):

**Descrição**: cStat é o código numérico da resposta da SEFAZ. 
xMotivo é a descrição textual.

**Orientação**: Sempre verifique para entender o resultado. cStat: 100 geralmente indica sucesso ("Autorizado o uso da NF-e"). Outros códigos (ex: 203, 218) indicam rejeições ou denegações, com xMotivo detalhando a causa.

### nProt (Número do Protocolo):

**Descrição**: O protocolo de autorização da SEFAZ.

**Orientação**: Preenchido apenas se o documento fiscal for AUTORIZADO. É a prova legal da validade. Para cancelamentos e outros eventos, indica o sucesso da operação do evento.

### Campos de Conteúdo (xml, pdf) e Links (xmlLink, pdfLink):

**Descrição**: xml e pdf podem conter o conteúdo direto (XML completo ou PDF em Base64). 
xmlLink e pdfLink são URLs assinadas para download dos arquivos, sendo que é possível baixar estes arquivos dentro de até 36hs.

**Orientação**: O conteúdo direto pode ser grande e lento. Recomendamos fortemente o uso de xmlLink e pdfLink para baixar os documentos. Estes links geralmente têm um curto tempo de expiração (ex: 36 horas) por segurança.

### Justificativas (xJust, xCorrecao):

**Orientação**: Campos de justificativa (xJust para cancelamento/inutilização, xCorrecao para CC-e) são obrigatórios e devem ter no mínimo 15 caracteres, descrevendo claramente o motivo.

### Numeração de Eventos (nSeqEvento):

**Orientação**: Para eventos como Carta de Correção, o nSeqEvento deve ser incrementado para cada evento subsequente relacionado à mesma chave de acesso da nota. (1ª CC-e será 1, 2ª será 2, etc.).

### Códigos de UF e Município (cUF, cMun, cMunFG):

**Orientação**: Todos os códigos de Unidade Federativa (UF) e Município devem ser os códigos IBGE válidos. Garanta que cMunFG (Município do Fato Gerador) corresponda à UF do emitente.

**Observação**: É possível utilizar rotas para retornar o código da UF a partir da uf enviada ou retornar a uf a partir do código da uf.

**Dica**: Consulte uma tabela atualizada de códigos IBGE para evitar erros de validação da SEFAZ.

### Inscrição Estadual (IE) e Inscrição Municipal (IM):

**Orientação**: Devem ser válidas e corresponder ao estado/município do emitente. IE é obrigatória para contribuintes de ICMS; IM é obrigatória para prestadores de serviço com Inscrição Municipal.

**Observação**: Valores inválidos podem levar a rejeições do documento fiscal, portanto se atente aos zeros a esquerda e o tamanho padrão da numeração conforme cidade/estado.

### Datas e Horas (dhEmi, dhSaiEnt, dhEvento, etc.):

**Orientação**: Todas as datas e horas devem ser enviadas no formato ISO 8601 completo, incluindo o fuso horário (ex: YYYY-MM-DDTHH:mm:ss-03:00).

**Observação**: Atrasos na dhEmi podem resultar em rejeição (cStat: 228).

### Código de Regime Tributário (CRT):

**Orientação**: Campo obrigatório em documentos fiscais, deve corresponder ao regime tributário da empresa: `1` = Simples Nacional, `2` = Simples Nacional (excesso de sublimite), `3` = Regime Normal, `4` = MEI. Valor incorreto causará rejeição. A API aceita `CRT: 4` (veja o [FAQ](#/api/api-dfe/faq)).

## Tipos e Valores Específicos de Campos

Alguns campos possuem um conjunto restrito de valores predefinidos que devem ser utilizados.

### tpDanfe:

- **Descrição**: Define o tipo de impressão do Documento Auxiliar da Nota Fiscal Eletrônica (DANFE).

- **Valores Aceitos**: 
**NFe**: ['Retrato', 'Paisagem', 'Simplificado']

**NFCe**: ['Cupom', 'NFCeA4']

### situationDfe:

- **Descrição**: Indica o status atual do Documento Fiscal Eletrônico na Sefaz.

- **Valores Aceitos**: 
['EmAberto', 'Emitido', 'Rejeitado', 'Cancelado']

### notification:

- **Descrição**: Define o tipo de notificação a ser recebida.

- **Valores Aceitos- **: ['TODOS']

- **Observação**: O serviço de envio de notificações da API ainda não está finalizado, por isso, há somente uma opção, que é o envio de email após emissão da nota fiscal. Este campo pode ser removido ou adicionado novos valores futuramente.

### CST de ICMS (CST no grupo ICMS):

- **Valores Aceitos**: 
['cst00', 'cst02', 'cst10', 'cst15', 'cst20', 'cst30', 'cst40', 'cst41', 'cst50', 'cst51', 'cst53', 'cst60', 'cst61', 'cst70', 'cst90', 'cstPart10', 'cstPart90', 'cstRep41', 'cstRep60', 'csosn101', 'csosn102', 'csosn103', 'csosn201', 'csosn202', 'csosn203', 'csosn300', 'csosn400', 'csosn500', 'csosn900']

- **Observação**: Este campo utiliza um formato alfanumérico específico para identificar a Classificação da Situação Tributária do ICMS.

### Outros CSTs (PIS, COFINS, IPI, CST IBS/CBS, cClassTrib):

Para os Códigos de Situação Tributária de PIS, COFINS, IPI e outros, o valor deve ser enviado como uma string numérica de duas, três ou seis casas decimais conforme tipos.

- **Exemplos**: ['00', '02', '10', '67', '000', '000001', ...]

- **Observação**: Mesmo que o número seja um único dígito, ele deve ser preenchido com zeros à esquerda para garantir a quantidade de casas decimais conforme esperado pelo tipo (ex: 02 em vez de 2, 001 ao invés de 1, etc).