# Introdução à API DFe

A API DFe é o serviço de documentos fiscais eletrônicos da Dados Jah. Ela cobre emissão, consulta e gestão de **NF-e**, **NFC-e** e **NFS-e**, além de uma série de recursos fiscais complementares.

## Documentos suportados

| Documento | Descrição |
|---|---|
| **NF-e** | Nota Fiscal Eletrônica (modelo 55) — venda de mercadorias (operação entre empresas e consumidor final) |
| **NFC-e** | Nota Fiscal de Consumidor Eletrônica (modelo 65, mais conhecido por cupom eletrônico) — venda no varejo, com CPF/CNPJ opcional |
| **NFS-e** | Nota Fiscal de Serviço Eletrônica — prestação de serviços, com suporte a diversos municípios/provedores |

## Recursos gerais

A API vai muito além da simples emissão. Os principais recursos são:

- **Emissão** de NF-e, NFC-e e NFS-e, inclusive com envio em lote (várias notas em uma única chamada);
- **Cancelamento** de notas e **inutilização** de numeração;
- **Carta de Correção (CC-e)** e **outros eventos**;
- **Download de XML** e de **DANFE/DANFCE/DANFSE** (PDF);
- **Consultas** por chave, lote, série + número, id e idExternal;
- **Distribuição DFe** — consulta de notas destinadas ao seu CNPJ (ultNSU, NSU ou chave);
- **Consulta SEFAZ** — cadastro de contribuinte (CCC) e status do serviço;
- **Listas fiscais** — NCM, CFOP, CEST e CSTs de ICMS, IPI, PIS e COFINS;
- **Cálculo de impostos (em beta)** — tributos de saída e de entrada;
- **IBPT** — alíquotas por UF + NCM e cálculo de tributos;
- **Multi-emitente** — gerenciamento de múltiplos CNPJs;
- **Configuração de DANFE/DANFCE/DANFSE** - configure como quer imprimir o PDF da nota;
- **Reenvio de email**;
- **Histórico de requisições**;
- **Utilitários** - Monte ou desmonte a chave de acesso, retorne o código ou sigla do estado;
- **Outros** - Outos recursos já existentes hoje ou que serão desenvolvidos;

Para o detalhamento das requisições, consulte seção correspondente.

## Modelo de cobrança

Assim como os demais serviços da Dados Jah, a API DFe usa o modelo **pay-per-use**: créditos pré-pagos, sem mensalidade. Você paga apenas pelas operações que executar — emissão, cancelamento, consulta, impressão, etc. Os valores estão na [tabela de preços](https://dadosjah.com.br/produto/precos.html).

> **Importante:** Só será cobrado as requisições que forem enviadas para a Sefaz ou retornarem como sucesso em Produção. 
> Requisições em homologação não são cobradas.
> *Exemplo 1*: Caso tente emitir uma nota fiscal e retorne como rejeição, será cobrado, pois foi enviado para a Sefaz.
> *Exemplo 2*: Caso tente emitir uma nota fiscal e falhe na validação do schema xml ou dê algum erro interno na API, não será cobrado. 

## Armazenamento do xml

Os arquivos XML retornados pela Sefaz são armazenados na AWS S3 com a *classe Standard (acesso rápido)*, temos redundância salvando em uma base de dados em outro servidor.

Os arquivos emitidos em homologação não são salvos em nosso servidor e portanto não é retornado na requisição o **xmllink** e **pdflink**, apenas o **xml** e **pdf** em *base64*;

> **Aviso:** Por enquanto não há cobranças por armazenamento ou exclusão de arquivos após determinado período.
> Em breve implementaremos este recurso.


## Referência completa

> **Dica:** a referência oficial com todos os endpoints, parâmetros, payloads e exemplos está na documentação do Postman da [API DFe](https://documenter.getpostman.com/view/53424652/2sBXikoBN8). Use-a como fonte canônica durante a integração.
