# Emitex API (documentação completa) > API REST de emissão, consulta e gestão de NF-e, NFC-e e NFS-e. Este arquivo reúne a referência completa em texto, para leitura por modelos de linguagem. Contrato máquina-legível: https://emitex.api.br/openapi.yaml. Índice resumido: https://emitex.api.br/llms.txt. # API Reference — EMITEX v1 Base URL: `https://emitex.api.br` · Prefixo: `/api/v1` · Formato: JSON. Para integração por máquina e por agentes de IA: contrato OpenAPI 3.1 em `https://emitex.api.br/openapi.yaml`, índice em `https://emitex.api.br/llms.txt` e esta referência inteira em texto em `https://emitex.api.br/llms-full.txt` (descoberta pelo catálogo RFC 9727 em `/.well-known/api-catalog`). Acesso assistido, sob consulta; canal de solicitação em avaliação. Disponibilidade conforme documento e cenário. Produção e liberação comercial sob consulta; implementação não comprova cobertura de UFs ou municípios. Exemplos iniciais pressupõem empresa em homologação, certificado e configuração fiscal compatíveis. O ambiente é da empresa/documento, sem garantia de credencial exclusiva por ambiente. Consulte `expires_in` ao obter o token. CT-e, CT-e OS, MDF-e, NFCom, DC-e e consultas CEP/CNPJ são futuros. Retenção e condições sob confirmação; imutabilidade, cifragem do storage, backup, preços, suporte e SLA sob consulta. Matriz de evidências: [verdade do produto](site-verdade-do-produto.md). ## Autenticação OAuth2 **client_credentials** (Laravel Passport). Obtenha um token e envie em `Authorization: Bearer `. ```http POST /oauth/token Content-Type: application/x-www-form-urlencoded grant_type=client_credentials &client_id=... &client_secret=... &scope=empresas:gerenciar nfe:emitir nfe:consultar nfe:cancelar ``` ### Scopes | Scope | Permite | |---|---| | `empresas:gerenciar` | Cadastrar/consultar empresas e enviar certificado | | `nfe:emitir` | Emitir e reenviar NF-e, NFC-e e NFS-e | | `nfe:consultar` | Consultar NF-e/NFC-e/NFS-e e baixar arquivos disponíveis; validar XML offline | | `nfe:cancelar` | Cancelar NF-e/NFC-e/NFS-e e solicitar inutilização NF-e/NFC-e | | `distribuicao-nfe:consultar` | Consultar DF-es distribuídos, baixar XMLs e sincronizar a distribuição | | `distribuicao-nfe:manifestar` | Enviar manifestação do destinatário (1 crédito por evento registrado) | | `sefaz:status` | Consultar a disponibilidade da SEFAZ | ## Erros Nas operações fiscais síncronas, `FiscalException` carrega `cStat`/`motivo` quando disponíveis. O envelope JSON de erros depende do tratamento de exceções da aplicação, não incluído nesta cópia; a confirmar no ambiente executor. O exemplo abaixo é ilustrativo. Na emissão assíncrona aceita (`202`), rejeição é estado da nota, consultado pelo id; não é `402`. A consulta NF-e/NFC-e usa `cStat`, o webhook fiscal usa `recurso.cstat`, e a consulta NFS-e usa `codigo`/`motivo`. O webhook NFS-e inclui `motivo`, mas não `codigo`. ```json { "error": "fiscal_error", "message": "Rejeição SEFAZ 539: ...", "cStat": "539", "motivo": "..." } ``` HTTP: `401` autenticação; `402` crédito insuficiente; `422` validação/erro fiscal síncrono; `429` limite de requisições; `502` falha de comunicação fiscal. Respeite o intervalo de `Retry-After` antes de tentar novamente após `429`. A chave usada para agrupar o limite (credencial/IP) fica a confirmar no middleware do ambiente executor. Nomes do envelope (`validation_error`, `unauthenticated`, `fiscal_error`) a confirmar no tratamento de exceções do ambiente executor. ## Empresas ### `POST /api/v1/empresas` — cadastrar (scope `empresas:gerenciar`) ```json { "razao_social": "EMPRESA LTDA", "cnpj": "11222333000181", "ie": "119295340110", "crt": 1, "logradouro": "RUA X", "numero": "100", "bairro": "CENTRO", "cep": "01001000", "codigo_municipio": 3550308, "municipio": "SAO PAULO", "uf": "SP", "ambiente": "homologacao" } ``` `crt`: 1 Simples · 2 Simples (excesso) · 3 Normal · 4 MEI. `ambiente`: `homologacao` (padrão) ou `producao`. Resposta `201` com a empresa criada (certificado nunca é retornado). Aceita também, opcionalmente, a configuração do envio mensal ao contador (`contador_envio_xml`, `contador_email`, `contador_dia_envio`) — ver o `PATCH` abaixo. ### `PATCH /api/v1/empresas/{empresa}` — atualizar (scope `empresas:gerenciar`) Atualização parcial: só os campos enviados mudam. **CNPJ não é editável** — é a identidade do emitente, referenciada por toda nota já emitida e pelo caminho dos XMLs no storage. ```json { "contador_envio_xml": true, "contador_email": "contador@escritorio.com.br", "contador_dia_envio": 5 } ``` | Campo | Descrição | |---|---| | `contador_envio_xml` | Liga o envio mensal do pacote de XMLs ao contador. | | `contador_email` | Destinatário do pacote. Obrigatório para ligar o envio — e não pode ser apagado enquanto o envio estiver ligado. | | `contador_dia_envio` | Dia do mês (1–31) em que o pacote sai, referente ao **mês anterior**. Dia inexistente no mês (30/31) é recolhido no último dia. | Demais campos aceitos: `razao_social`, `nome_fantasia`, `ie`, `im`, `crt`, endereço completo, `fone`, `ambiente`, `serie_nfe`, `fiscal_numeracao`, `email_destinatario_auto`, `percentual_tributos_sn`. `percentual_tributos_sn` (opcional, também no `POST`): percentual aproximado dos tributos pela alíquota do Simples Nacional (0–99,99, até 2 casas), enviado no `pTotTribSN` da DPS da NFS-e Nacional. **Obrigatório para ME/EPP do Simples (`crt` 1 ou 2) emitirem NFS-e Nacional** — sem ele a nota fica com status de erro e o motivo indica o campo faltante (crédito estornado). Resposta `200` com a empresa atualizada. ### `POST /api/v1/empresas/{empresa}/certificado` — enviar A1 (scope `empresas:gerenciar`) `multipart/form-data` com `arquivo` (.pfx) **ou** JSON com `certificado_base64`, mais `senha`. O certificado e a senha usam casts `encrypted` no modelo `Empresa` e campos ocultos na serialização. A API de cadastro retorna metadados do certificado. ```json { "message": "Certificado armazenado com segurança.", "certificado_cn": "...", "certificado_validade": "2027-01-01T00:00:00Z" } ``` ### `POST /api/v1/empresas/{empresa}/csc` — CSC da NFC-e (scope `empresas:gerenciar`) Configura o **CSC** (Código de Segurança do Contribuinte) e o **idCSC** da empresa, exigidos para emitir NFC-e (compõem o QR Code). O CSC é **por ambiente** (a SEFAZ emite CSCs distintos para homologação e produção); `ambiente` é opcional e assume o ambiente atual da empresa. O CSC é cifrado em repouso e **nunca** retornado. `serie_nfce` é opcional. ```json { "csc": "CODIGO-CSC-DA-SEFAZ-UF", "csc_id": "000001", "serie_nfce": 1, "ambiente": "homologacao" } ``` `ambiente`: `homologacao` | `producao` (padrão: ambiente atual da empresa). Resposta `200`: `{ "message": "CSC da NFC-e armazenado com segurança.", "ambiente": "homologação", "csc_id": "000001", "serie_nfce": 1 }` ## NF-e ### `POST /api/v1/empresas/{empresa}/nfe` — emitir (scope `nfe:emitir`) Assíncrono: responde **`202`** com o id para consulta. Defaults aplicados (CFOP 5102, impostos por regime, à vista). Em homologação o destinatário é forçado para o nome-padrão da SEFAZ. ```json { "natureza_operacao": "VENDA", "destinatario": { "cnpj": "99999999000191", "indicador_ie": 9 }, "itens": [ { "descricao": "PRODUTO", "ncm": "61091000", "cfop": "5102", "quantidade": 2, "valor_unitario": 10.50, "unidade": "UN" } ], "pagamento": { "forma": "01", "valor": 21.00 }, "request_id": "opcional-idempotencia" } ``` #### Reforma Tributária — IBS/CBS/IS (v2, NT 2025.002) **Aditivo e opcional.** Todos os campos abaixo são por item e `nullable`. Se o item não os enviar, a nota é montada exatamente como na v1 (layout PL_009, sem os grupos novos). Quando **ao menos um item** traz `cClassTrib`, a nota inteira é montada no layout **PL_010** e os grupos `` (gIBSUF/gIBSMun/gCBS), `` e os totalizadores ``/`` passam a ser emitidos. Os mesmos campos valem para a NFC-e (modelo 65). | Campo (por item) | Descrição | |---|---| | `cClassTrib` | Código de Classificação Tributária do IBS/CBS (âncora — habilita os grupos da Reforma) | | `cst_ibs` / `cst_cbs` | CST do IBS / CBS (usa-se `cst_cbs`, com fallback para `cst_ibs`) | | `cBenef` | Código de Benefício Fiscal da UF. Emitido em `prod/cBenef` (nível do produto, não do grupo IBSCBS) | | `cCredPres` | Código de Classificação do Crédito Presumido — habilita o grupo `` | | `cred_pres_base_calc` | Base de cálculo do crédito presumido (`vBCCredPres`). Se ausente, usa `ibs_base_calc`/`cbs_base_calc` | | `cred_pres_ibs_aliquota` | Percentual do crédito presumido de IBS (`gIBSCredPres/pCredPres`) | | `cred_pres_ibs_valor` | Valor do crédito presumido de IBS (`gIBSCredPres/vCredPres`) | | `cred_pres_ibs_valor_cond_sus` | Valor do crédito presumido de IBS em condição suspensiva (usado quando não há `cred_pres_ibs_valor`) | | `cred_pres_cbs_aliquota` | Percentual do crédito presumido de CBS (`gCBSCredPres/pCredPres`) | | `cred_pres_cbs_valor` | Valor do crédito presumido de CBS (`gCBSCredPres/vCredPres`) | | `cred_pres_cbs_valor_cond_sus` | Valor do crédito presumido de CBS em condição suspensiva (usado quando não há `cred_pres_cbs_valor`) | | `ibs_base_calc` | Base de cálculo do IBS/CBS (`vBC` do grupo `gIBSCBS`) | | `ibs_uf_aliquota` / `ibs_uf_valor` | Alíquota e valor do IBS de competência da UF | | `ibs_mun_aliquota` / `ibs_mun_valor` | Alíquota e valor do IBS de competência do Município | | `cbs_base_calc` | Base de cálculo da CBS (fallback de `ibs_base_calc` se ausente) | | `cbs_aliquota` / `cbs_valor` | Alíquota e valor da CBS | | `is_base_calc` | Base de cálculo do Imposto Seletivo (``) | | `is_aliquota` / `is_valor` | Alíquota e valor do Imposto Seletivo | Exemplo de item com Reforma: ```json { "descricao": "PRODUTO", "ncm": "61091000", "cfop": "5102", "quantidade": 2, "valor_unitario": 10.50, "unidade": "UN", "cClassTrib": "000001", "cst_cbs": "000", "ibs_base_calc": 21.00, "ibs_uf_aliquota": 0.10, "ibs_uf_valor": 2.10, "ibs_mun_aliquota": 0.05, "ibs_mun_valor": 1.05, "cbs_base_calc": 21.00, "cbs_aliquota": 0.90, "cbs_valor": 18.90, "is_base_calc": 21.00, "is_aliquota": 0.00, "is_valor": 0.00 } ``` Exemplo com benefício fiscal e crédito presumido: ```json { "descricao": "PRODUTO", "ncm": "61091000", "cfop": "5102", "quantidade": 1, "valor_unitario": 100.00, "unidade": "UN", "cClassTrib": "000001", "cst_cbs": "000", "cBenef": "SP830001", "cCredPres": "01", "cred_pres_base_calc": 100.00, "cred_pres_cbs_aliquota": 0.90, "cred_pres_cbs_valor": 0.90, "cred_pres_ibs_aliquota": 0.10, "cred_pres_ibs_valor": 0.10 } ``` > **Homologação obrigatória.** Os grupos IBS/CBS/IS exigem homologação na SEFAZ (ambiente de produção restrita) antes de uso em produção. > > **`cBenef`** é emitido no nível do produto (`prod/cBenef`, via `Make::tagprod`) — não faz parte do grupo IBSCBS. > > **`cCredPres`** é emitido no grupo `` via `Make::taggCredPresOper` (o Make anexa o grupo ao node `` do item em `monta()`). Requer que o item também traga `cClassTrib` (âncora do IBSCBS). O Make exige `vBCCredPres`; os subgrupos `gIBSCredPres`/`gCBSCredPres` só saem quando informados o percentual e o valor (ou o valor em condição suspensiva). > > **Ainda não mapeado (TODO):** redução de alíquota (`gRedAliq` / `pRedAliq`+`pAliqEfet` dentro de `gIBSUF`/`gIBSMun`/`gCBS`), tributação regular (`gTribRegular`), diferimento (`gDif`), monofásico (`gIBSCBSMono`), transferência/estorno de crédito e crédito presumido da ZFM (`gCredPresIBSZFM`). Os métodos existem na sped-nfe v5.2.5 mas não têm campos no contrato da API. #### Documentos referenciados, informações adicionais e devolução **Aditivo e opcional.** Payload sem estes campos gera o mesmo XML de antes. | Campo | Tipo | XML | Regra | |---|---|---|---| | `documentos_referenciados` | array (1–500) | `ide/NFref` | **Obrigatório** com `finalidade` 2 (complementar). Na devolução (4), só no formato antigo, sem `itens.*.referencia` | | `documentos_referenciados.*.chave` | string, 44 dígitos | `NFref/refNFe` | Chave de NF-e (55) **ou** NFC-e (65) | | `itens.*.referencia.chave` | string, 44 dígitos | `det/DFeReferenciado/chaveAcesso` | Só com `finalidade` 4. Nota de origem do item | | `itens.*.referencia.n_item` | int 1–990 | `det/DFeReferenciado/nItem` | Número do item na nota de origem. Obrigatório quando há `referencia` | | `informacoes_complementares` | string (máx. 5000) | `infAdic/infCpl` | Opcional | | `informacoes_fisco` | string (máx. 2000) | `infAdic/infAdFisco` | Opcional | **Devolução item a item (NT 2025.002 v1.52, VC02-14 — SEFAZ exige a partir de 16/11/2026).** Com `finalidade` 4 e `referencia` nos itens: - **todo** item leva `referencia.chave` + `referencia.n_item` (Rejeição 1048 sem o nItem); - `documentos_referenciados` é **proibido** (Rejeição 1010) — a nota sai sem `NFref`; - a mesma chave + item não pode repetir (1072) e todas as chaves são do mesmo emitente (1193); - o XML sai no leiaute PL_010 (o grupo não existe no PL_009) e o `infCpl` ganha "Ref. NF-e de origem: {chaves}." porque o DANFE só imprime o `NFref`. Devolução **sem** `referencia` em nenhum item segue o formato antigo (`documentos_referenciados` obrigatório) enquanto a SEFAZ aceitar. `referencia` fora da devolução é recusada. **Referência a NFC-e (NT 2026.002):** NF-e de saída (`tipo` 1) que não seja complementar nem devolução não pode ter chave de NFC-e em `documentos_referenciados` (Rejeição 679); CFOP 5929/6929 com NFC-e referenciada é recusado (Rejeição 375). `finalidade` (finNFe): `1` normal · `2` complementar · `3` ajuste · `4` devolução · `5` nota de crédito · `6` nota de débito (ver abaixo; desligadas por padrão). Com `finalidade` **3 ou 4** o `pagamento` enviado é **ignorado** e o `detPag` sai com `tPag=90` (sem pagamento) e `vPag=0`, como exige a SEFAZ. #### Nota de débito e de crédito (finalidade 5 e 6, Ajuste SINIEF 49/2025) NF-e de **nota de crédito** (`finalidade` 5, `ide/tpNFCredito`) e de **nota de débito** (`finalidade` 6, `ide/tpNFDebito`). Facultativas desde 03/08/2026 e obrigatórias a partir de 01/01/2027 (Ajuste SINIEF 27/2026). **Desligadas por padrão**: sem `FISCAL_NF_DEBITO_CREDITO=ligado` a API responde 422 para `finalidade` 5/6. Fonte: NT 2025.002-RTC v1.53 (regras B25, B25.1, B25.2, B25-80/100/110/120, UB14, VC) e XSD PL_010g v1.03. | Campo | Regra | |---|---| | `tipo_nota_credito` | `01` multa e juros · `02` crédito presumido IBS ZFM (só a partir de 2029, 1145) · `03` retorno por recusa total/não localização · `04` redução de valores · `05` transferência de crédito na sucessão · `06` retorno por recusa parcial. Obrigatório com `finalidade` 5 (1164), proibido nas demais (1163) | | `tipo_nota_debito` | `01` transferência de créditos para cooperativas · `02` anulação de crédito por saídas imunes/isentas · `03` débitos de notas não processadas · `04` multa e juros · `05` transferência de crédito na sucessão · `06` pagamento antecipado · `07` perda em estoque · `08` desenquadramento do SN. Obrigatório com `finalidade` 6 (1009), proibido nas demais (1139) | | `tipo` | Padrão `0` (entrada) no crédito e `1` (saída) no débito; outro valor é recusado (1161, 1162, 1152) | | `documentos_referenciados` | Crédito `01`, `03` e `04`: exatamente 1 chave de NF-e 55 (254/255/1003; NFC-e só no `03`); `03`/`04`: emitente e UF iguais aos da nota (269/678). Crédito `02`: proibido (1027). Débito: nunca NFC-e (679) | | `itens.*.referencia` | `DFeReferenciado` por item: **obrigatório** em débito `03`/`04` e crédito `06` (1038); débito `03` sem `n_item` (VC03-10); nos demais créditos proibido (1042); não combinar com `documentos_referenciados` (1010) | | `itens.*.estorno_credito` | Objeto `{v_ibs_est_cred, v_cbs_est_cred}` (gEstornoCred, UB116). **Obrigatório no débito 07** (rejeição 1173; 0 é aceito); nos demais tipos IBS ou CBS > 0 (1174). Exige cClassTrib. | | `itens.*.cClassTrib` | Obrigatório (nota somente de IBS/CBS). Débito `01` 800002, `02` 811001, `03` 811002, `05` 800001, `07` 410030, `08` 811003; crédito `02` 810001, `05` 800001 (1200/1201/1202) | No XML, nota só de IBS/CBS sai **sem** ICMS, PIS e COFINS (B25-80, 1001); crédito `03`/`04`/`06` e débito `07` mantêm o grupo ICMS (exceção da NT). O XML usa o XSD derivado (PL_010_V1.30 + tpNFCredito `06`). `pagamento` segue o fluxo normal (a NT não traz regra de pagamento para finNFe 5/6). Não implementados: ver `docs/fiscal/nts-2026-pendencias.md`. Exemplo — devolução integral de uma NFC-e (NF-e de entrada, `tipo` 0): ```json { "natureza_operacao": "DEVOLUCAO DE VENDA", "tipo": 0, "finalidade": 4, "destinatario": { "cpf": "12345678909", "nome": "CLIENTE", "indicador_ie": 9 }, "documentos_referenciados": [ { "chave": "35260911222333000181650010000000061000000061" } ], "informacoes_complementares": "Devolução integral da NFC-e nº 6, série 1.", "itens": [ { "descricao": "PRODUTO", "ncm": "61091000", "cfop": "1202", "quantidade": 2, "valor_unitario": 10.50, "unidade": "UN" } ], "request_id": "devolucao-venda-123" } ``` Exemplo — devolução item a item (formato exigido a partir de 16/11/2026): ```json { "natureza_operacao": "DEVOLUCAO DE COMPRA", "tipo": 1, "finalidade": 4, "destinatario": { "cnpj": "11222333000181", "nome": "FORNECEDOR LTDA", "indicador_ie": 1, "ie": "110042490114" }, "itens": [ { "descricao": "PRODUTO", "ncm": "61091000", "cfop": "5202", "quantidade": 2, "valor_unitario": 50.00, "referencia": { "chave": "35260911222333000181550010000000071000000071", "n_item": 3 } } ] } ``` #### Impostos destacados por item — devolução de compra ao fornecedor **Aditivo e opcional (só NF-e 55).** Uso típico: NF-e de **saída** (`tipo` 1), `finalidade` 4, `NFref` com a chave da nota de entrada e destinatário PJ contribuinte (`indicador_ie` 1 + `ie`), levando os impostos destacados na nota original **proporcionais à quantidade devolvida** — o EMITEX não recalcula nada, só destaca o que o ERP mandar. Payload sem estes campos gera o mesmo XML de antes (coberto por teste de XML de referência). | Campo | Tipo | XML | Regra | |---|---|---|---| | `itens.*.cest` | string, 7 dígitos | `prod/CEST` | Opcional | | `itens.*.icms_modalidade_bc` | int `0–3` (padrão 3) | `modBC` | Só sai junto com o ICMS próprio | | `itens.*.icms_reducao_bc` | número 0–100 | `pRedBC` | CST 20/70 (sai `0` se omitido nesses CSTs) e CSOSN 900 | | `itens.*.icms_base_calc` / `icms_aliquota` / `icms_valor` | número | `vBC` / `pICMS` / `vICMS` | CST 00, 10, 20, 70 e CSOSN 900. Somam em `ICMSTot/vBC` e `vICMS` | | `itens.*.icms_st_modalidade_bc` | int `0–6` (padrão 4) | `modBCST` | Só sai junto com o ST | | `itens.*.icms_st_mva` | número | `pMVAST` | Opcional | | `itens.*.icms_st_base_calc` / `icms_st_aliquota` / `icms_st_valor` | número | `vBCST` / `pICMSST` / `vICMSST` | CST 10, 30, 70 e CSOSN 201, 202, 203, 900. Somam em `vBCST`/`vST` e o **vST entra no vNF** | | (mesmos, no CST 60) | número | `vBCSTRet` / `pST` / `vICMSSTRet` | ST **retido anteriormente**: informativo, **não** soma em vBCST/vST nem no vNF | | `itens.*.icms_sn_credito_aliquota` / `icms_sn_credito_valor` | número | `pCredSN` / `vCredICMSSN` | CSOSN 101, 201 e 900 | | `itens.*.ipi_devolvido_percentual` | número >0 a 100 | `impostoDevol/pDevol` | **Obrigatório** com `ipi_devolvido_valor` | | `itens.*.ipi_devolvido_valor` | número | `impostoDevol/IPI/vIPIDevol` | Só sai se > 0. Não gera grupo ``; soma em `ICMSTot/vIPIDevol` e no vNF | | `itens.*.frete` / `seguro` / `outras` | número | `prod/vFrete` / `vSeg` / `vOutro` | Só saem se > 0. Somam nos totais e no vNF | Campos de ICMS informados em CST/CSOSN que não os comportam (ex.: CST 41, CSOSN 102) são ignorados — o grupo sai só com `orig` + CST/CSOSN, como antes. **Totais:** `vNF = vProd − vDesc + vST + vFrete + vSeg + vOutro + vIPIDevol` (`vII` e `vIPI` seguem 0). A soma das `duplicatas` (quando houver) é conferida contra esse mesmo vNF. Devolução continua sem cobrança e com `tPag=90`/`vPag=0`. Exemplo — devolução parcial (2 de 10 unidades) de uma compra com ICMS, ST e IPI: ```json { "natureza_operacao": "DEVOLUCAO DE COMPRA", "tipo": 1, "finalidade": 4, "consumidor_final": 0, "destinatario": { "cnpj": "11222333000181", "nome": "FORNECEDOR LTDA", "indicador_ie": 1, "ie": "110042490114", "endereco": { "logradouro": "RUA A", "numero": "1", "bairro": "CENTRO", "codigo_municipio": 3550308, "municipio": "SAO PAULO", "uf": "SP", "cep": "01001000" } }, "documentos_referenciados": [ { "chave": "35260911222333000181550010000000071000000071" } ], "informacoes_complementares": "Devolucao parcial da NF-e 7, serie 1.", "itens": [ { "descricao": "PRODUTO", "ncm": "61091000", "cest": "2806300", "cfop": "5411", "quantidade": 2, "valor_unitario": 50.00, "cst": "10", "icms_base_calc": 100.00, "icms_aliquota": 12, "icms_valor": 12.00, "icms_st_mva": 40, "icms_st_base_calc": 140.00, "icms_st_aliquota": 18, "icms_st_valor": 13.20, "ipi_devolvido_percentual": 20, "ipi_devolvido_valor": 5.00, "frete": 3.00 } ] } ``` vNF = 100,00 + 13,20 + 3,00 + 5,00 = **121,20**. #### Presença, transporte, cobrança (fatura/duplicatas) e venda a prazo **Aditivo e opcional.** Payload sem estes campos gera o mesmo XML de antes (`modFrete=9`, sem ``, `indPag=0`). | Campo | Tipo | XML | Regra | |---|---|---|---| | `presenca` | int `0,1,2,3,5,9` | `ide/indPres` | 1 presencial · 2 internet · 3 teleatendimento · 5 presencial fora do estabelecimento · 9 outros. O **4** (entrega a domicílio) é exclusivo da NFC-e e é recusado na NF-e (422); para entrega use 2 ou 9 com o transporte | | `itens.*.desconto` | número ≥ 0 | `prod/vDesc` + `ICMSTot/vDesc` | Desconto destacado do item (NF-e e NFC-e). vNF = vProd − vDesc; não pode passar do valor do item. Sem o campo o XML não muda | | `pagamento.indicador` | int `0,1` | `detPag/indPag` | 0 à vista · 1 a prazo. Sem o campo: `1` se houver `duplicatas`, senão `0` | | `fatura.numero` | string (máx. 60) | `cobr/fat/nFat` | Opcional | | `fatura.valor_original` / `valor_desconto` / `valor_liquido` | número | `fat/vOrig` / `vDesc` / `vLiq` | `valor_liquido` = `valor_original` − `valor_desconto` | | `duplicatas` | array (1–120) | `cobr/dup` | Soma dos `valor` = total da nota (vNF líquido dos descontos) | | `duplicatas.*.numero` | string, 3 dígitos | `dup/nDup` | `001`, `002`, … | | `duplicatas.*.vencimento` | `AAAA-MM-DD` | `dup/dVenc` | Não anterior à data de emissão (Brasília) e em ordem crescente | | `duplicatas.*.valor` | número > 0 | `dup/vDup` | — | | `transporte.modalidade` | int `0,1,2,3,4,9` | `transp/modFrete` | Obrigatório quando `transporte` vem. Tem precedência sobre o campo legado `frete` | | `transporte.transportadora` | objeto | `transp/transporta` | `cnpj` (14 posições, aceita CNPJ alfanumérico) **ou** `cpf` (11), `nome`, `ie`, `endereco`, `municipio`, `uf`. Proibido com `modalidade` 9 | | `transporte.volumes[]` | array (até 5000) | `transp/vol` | `quantidade` (inteiro), `especie`, `marca`, `numeracao`, `peso_liquido`, `peso_bruto` (kg, 3 casas; bruto ≥ líquido) | Não há valor de frete neste contrato — o total da nota não muda. O pagamento continua **uma única forma** (`detPag`) com o valor total; o parcelamento vai nas duplicatas. Com `finalidade` 3 ou 4, `fatura`/`duplicatas` são ignoradas. O `NfeMaker` reaplica as regras das duplicatas (soma e datas) e recusa com `422` se não baterem. Exemplo — venda interestadual a prazo, entregue por transportadora: ```json { "natureza_operacao": "VENDA DE MERCADORIA", "destino": 2, "consumidor_final": 0, "presenca": 4, "destinatario": { "cnpj": "99999999000191", "nome": "CLIENTE LTDA", "indicador_ie": 1, "ie": "123456789", "endereco": { "logradouro": "RUA A", "numero": "10", "bairro": "CENTRO", "codigo_municipio": 4106902, "municipio": "CURITIBA", "uf": "PR", "cep": "80010000" } }, "itens": [ { "descricao": "PRODUTO", "ncm": "61091000", "cfop": "6102", "quantidade": 3, "valor_unitario": 100.00, "unidade": "UN" } ], "pagamento": { "forma": "15", "valor": 300.00, "indicador": 1 }, "fatura": { "numero": "1234", "valor_original": 300.00, "valor_desconto": 0, "valor_liquido": 300.00 }, "duplicatas": [ { "numero": "001", "vencimento": "2026-10-23", "valor": 150.00 }, { "numero": "002", "vencimento": "2026-11-23", "valor": 150.00 } ], "transporte": { "modalidade": 0, "transportadora": { "cnpj": "11222333000181", "nome": "TRANSPORTES LTDA", "ie": "110042490114", "endereco": "RUA DAS CARGAS 10", "municipio": "SAO PAULO", "uf": "SP" }, "volumes": [ { "quantidade": 2, "especie": "CAIXA", "peso_liquido": 10.5, "peso_bruto": 11.25 } ] }, "informacoes_complementares": "Pedido 1234.", "request_id": "venda-1234" } ``` Resposta `202`: ```json { "id": 10, "status": "pendente", "numero": 10, "serie": 1, "ambiente": "homologação", "consultar_em": "https://emitex.api.br/api/v1/nfe/10" } ``` `request_id` torna a emissão idempotente (mesma chave → mesma nota, não reemite). ### `GET /api/v1/nfe/{nota}` — status (scope `nfe:consultar`) ```json { "id": 10, "status": "autorizada", "numero": 10, "serie": 1, "modelo": 55, "ambiente": "homologação", "chave": "3526...", "protocolo": "135...", "cStat": "100", "motivo": "Autorizado o uso da NF-e", "autorizada_em": "2026-06-12T18:30:00-03:00", "links": { "xml": ".../nfe/10/xml", "pdf": ".../nfe/10/pdf" } } ``` Status: `pendente` · `processando` · `autorizada` · `rejeitada` · `denegada` · `cancelada` · `erro`. ### `GET /api/v1/nfe/{nota}/xml` — XML autorizado (scope `nfe:consultar`) ### `GET /api/v1/nfe/{nota}/xml-cancelamento` — XML do evento de cancelamento (scope `nfe:consultar`) `procEventoNFe` devolvido pela SEFAZ no cancelamento. Documento fiscal por si só: comprova que a nota foi cancelada, e o contador precisa dele junto com o XML da nota. `404` quando a nota não está cancelada ou quando o evento não foi guardado (notas canceladas antes de o emissor passar a persistir o arquivo). Mesma rota existe para NFC-e: `GET /api/v1/nfce/{nota}/xml-cancelamento`. ### `GET /api/v1/nfe/{nota}/pdf` — DANFE (scope `nfe:consultar`) Disponíveis apenas após autorização. `404` caso contrário. ### `POST /api/v1/nfe/{nota}/cancelar` — cancelar (scope `nfe:cancelar`) ```json { "justificativa": "texto entre 15 e 255 caracteres" } ``` ## NFC-e (modelo 65) Nota Fiscal de Consumidor eletrônica (venda no varejo/PDV). Mesmos scopes da NF-e (`nfe:emitir`/`nfe:consultar`/`nfe:cancelar`). Requisitos: certificado A1 cadastrado **e CSC configurado** (`POST /empresas/{empresa}/csc`). O QR Code (`infNFeSupl`) é gerado automaticamente na assinatura. Diferenças do payload: **destinatário é opcional** (consumidor não identificado — só vai ao XML se houver CPF/CNPJ); **pagamento é obrigatório** (aceita forma única ou várias formas, com troco). `tpImp` é sempre cupom; `indFinal=1` (consumidor final). ### `POST /api/v1/empresas/{empresa}/nfce` — emitir (scope `nfe:emitir`) Responde **`202`** com o id para consulta (processamento síncrono à SEFAZ dentro do job). ```json { "natureza_operacao": "VENDA AO CONSUMIDOR", "destinatario": { "cpf": "12345678909" }, "itens": [ { "descricao": "PRODUTO", "ncm": "61091000", "cfop": "5102", "quantidade": 2, "valor_unitario": 10.50, "unidade": "UN" } ], "pagamento": { "formas": [ { "forma": "01", "valor": 21.00 } ], "troco": 0.00 }, "request_id": "opcional-idempotencia" } ``` Pagamento também aceita o formato simples: `"pagamento": { "forma": "01", "valor": 21.00 }`. Os itens aceitam os mesmos campos opcionais da **Reforma Tributária (IBS/CBS/IS)** descritos na seção da NF-e acima. Resposta `202`: ```json { "id": 11, "status": "pendente", "numero": 11, "serie": 1, "modelo": 65, "ambiente": "homologação", "consultar_em": "https://emitex.api.br/api/v1/nfce/11" } ``` ### `GET /api/v1/nfce/{nota}` — status (scope `nfe:consultar`) Mesmo formato da NF-e (com `modelo: 65` e links `xml`/`pdf`). O PDF é o **DANFE NFC-e em cupom** (com QR Code). ### `GET /api/v1/nfce/{nota}/xml` — XML autorizado (scope `nfe:consultar`) ### `GET /api/v1/nfce/{nota}/pdf` — DANFE NFC-e/cupom (scope `nfe:consultar`) Disponíveis apenas após autorização. `404` caso contrário. ### `POST /api/v1/nfce/{nota}/cancelar` — cancelar (scope `nfe:cancelar`) ```json { "justificativa": "texto entre 15 e 255 caracteres" } ``` Atenção: a NFC-e tem **prazo de cancelamento curto** (definido por UF); fora do prazo a SEFAZ rejeita. ## Listar notas ### `GET /api/v1/empresas/{empresa}/nfe` · `/nfce` · `/nfse` — listar (scope `nfe:consultar`) Lista paginada das notas da empresa, da mais recente para a mais antiga (`id` decrescente). `/nfe` devolve só modelo 55, `/nfce` só modelo 65 e `/nfse` as NFS-e. Cada item tem o mesmo formato da consulta individual (`GET /nfe/{nota}`, `/nfce/{nota}`, `/nfse/{nota}`). Todos os filtros são opcionais e se combinam (E); chave vazia é ignorada. Throttle 240/min. | Parâmetro | Regra | |---|---| | `status` | `pendente`, `processando`, `autorizada`, `rejeitada`, `denegada`, `cancelada` ou `erro` | | `de`, `ate` | datas `Y-m-d`, inclusivas, em America/Sao_Paulo, sobre a data de criação da nota (`ate` não pode ser anterior a `de`) | | `busca` | texto até 60 caracteres: parte da chave ou número exato (na NFS-e também parte do número da NFS-e) | | `numero`, `serie` | inteiros, valor exato | | `chave` | 44 dígitos, valor exato | | `request_id` | até 64 caracteres, valor exato (idempotency key da emissão) | | `ambiente` | `homologacao` ou `producao` | | `per_page` | 1 a 100 (padrão 20) | | `page` | número da página (padrão 1) | A resposta é o envelope padrão de paginação (`current_page`, `data`, `per_page`, `total`, `last_page`, `next_page_url`, `links` etc.); os filtros são preservados nas URLs de página. Filtro inválido responde `422`; empresa de outra conta, `403`. ```bash curl -G "https://emitex.api.br/api/v1/empresas/1/nfe" \ -H "Authorization: Bearer $TOKEN" \ --data-urlencode "status=autorizada" \ --data-urlencode "de=2026-11-01" --data-urlencode "ate=2026-11-15" \ --data-urlencode "per_page=50" ``` ## Inutilização de numeração (NF-e e NFC-e) ### `POST /api/v1/empresas/{empresa}/nfe/inutilizacoes` · `POST /api/v1/empresas/{empresa}/nfce/inutilizacoes` — inutilizar (scope `nfe:cancelar`) ```json { "serie": 1, "numero_inicial": 48, "numero_final": 48, "justificativa": "NFC-E REJEITADA E NUMERO SEM USO" } ``` - Ambiente = o atual da empresa. Faixa de até 1.000 números, sem nota pendente/processando/autorizada/cancelada/denegada e sem sobrepor inutilização anterior (422). - `201` com a inutilização (`id`, `protocolo`, `cstat` 102, `recebido_em`, `links.xml`). Rejeição da SEFAZ = 422 `fiscal_error` com `cStat`/`motivo`; falha de comunicação = 502. Debita 1 crédito (402 sem saldo). - Notas rejeitadas/erro da faixa ficam com `inutilizacao_id` e não podem mais ser reenviadas. ### `GET /api/v1/empresas/{empresa}/inutilizacoes` — listar (scope `nfe:consultar`) Filtros: `competencia` (`AAAA-MM`, mês do protocolo em Brasília), `modelo` (55/65), `ambiente` (1/2). Resposta `{ "data": [...] }`. Cada item traz `emitida_em`, `prazo` (dia 10 do mês seguinte ao da emissão da nota rejeitada) e `fora_do_prazo`; nulos quando não há nota ligada. ### `GET /api/v1/empresas/{empresa}/inutilizacoes/{inutilizacao}/xml` — XML (scope `nfe:consultar`) `procInutNFe` (ou o `retInutNFe` da SEFAZ nas inutilizações importadas). ## NFS-e (Padrão Nacional) Emissão de Nota Fiscal de **Serviço** pelo Padrão Nacional (DPS → Sefin Nacional/ADN). Para prestadores de serviço (usa Inscrição Municipal, sem IE). Mesmos scopes da NF-e (`nfe:emitir`/`nfe:consultar`). Requisito: a empresa precisa estar **aderida ao Ambiente Nacional** e o certificado A1 cadastrado (autenticação mTLS). Empresa ME/EPP do Simples (`crt` 1 ou 2) precisa ter `percentual_tributos_sn` configurado (ver `PATCH /empresas/{empresa}`). Em homologação usa a **produção restrita** do ADN. ### `POST /api/v1/empresas/{empresa}/nfse` — emitir (scope `nfe:emitir`) ```json { "descricao": "DESENVOLVIMENTO DE SOFTWARE", "valor": 1500.00, "codigo_servico": "010701", "aliquota": 2.00, "competencia": "2026-06-12", "iss_retido": false, "tomador": { "cnpj": "99999999000191", "nome": "CLIENTE LTDA" }, "request_id": "opcional-idempotencia" } ``` `codigo_servico`: código de tributação nacional do serviço. No provedor Nacional aceita 6 dígitos (`cTribNac`, ex. `010701`) ou 9 dígitos, com ou sem pontos (ex. `010701001` ou `01.07.01.001`): os 6 primeiros vão em `cTribNac` e os 3 últimos em `cTribMun` (desdobro municipal; obrigatório em municípios que só parametrizam o desdobro, como São Paulo 3550308, senão o Sefin rejeita com E0312). Outros formatos seguem como antes. `iss_retido`: booleano — `true` = ISS retido pelo tomador, `false`/omitido = não retido. Resposta `202` (assíncrono). ### `GET /api/v1/nfse/{nota}` — status (scope `nfe:consultar`) ### `GET /api/v1/nfse/{nota}/xml` — XML da NFS-e (scope `nfe:consultar`) ### `GET /api/v1/nfse/{nota}/pdf` — PDF existente da NFS-e (scope `nfe:consultar`) O enum de notas contém `pendente`, `processando`, `autorizada`, `rejeitada`, `denegada`, `cancelada` e `erro`; os estados efetivamente usados dependem do documento/provedor. Resposta do status (`GET /nfse/{nota}`): ```json { "id": 29, "tipo": "nfse", "status": "autorizada", "numero": 1001, "serie": 13, "ambiente": "homologação", "chave": "...", "nfse_numero": "39", "codigo_verificacao": "WBNQMZFB", "codigo": "100", "motivo": "NFS-e aceita.", "autorizada_em": "2026-07-04T...", "links": { "xml": ".../nfse/29/xml", "pdf": null } } ``` `codigo_verificacao`: código de verificação da nota — presente na **Prefeitura de São Paulo** (Paulistana); `null` no **Padrão Nacional**, onde a nota se valida pela **chave de acesso** (50 dígitos). `nfse_numero` no **Padrão Nacional**: número oficial da NFS-e (`infNFSe/nNFSe` do XML devolvido pelo Sefin); `chave` traz a chave de acesso, separada. `links.pdf`: URL quando `pdf_path` está preenchido; caso contrário, `null`. A rota `/pdf` serve o arquivo somente para nota autorizada com `pdf_path` existente; sem essas condições, responde `404`. Não há geração de DANFSe implementada. ### `POST /api/v1/nfse/{nota}/consultar` — consultar no autorizador (scope `nfe:consultar`) Consulta a NFS-e diretamente no autorizador e atualiza número/código/status. Disponível para NFS-e da **Prefeitura de São Paulo**. ### `POST /api/v1/nfse/{nota}/cancelar` — cancelar (scope `nfe:cancelar`) Cancela uma NFS-e autorizada. O comportamento depende do **provedor** da nota: - **Prefeitura de São Paulo**: exige a nota com número e código de verificação. Sem corpo. - **Padrão Nacional (ADN/Sefin Nacional)**: registra o evento de cancelamento **e101101** no ADN. Exige corpo: ```json { "motivo_codigo": 1, "motivo": "Cancelamento por erro na emissão da nota" } ``` | Campo | Tipo | Regra | |---|---|---| | `motivo_codigo` | int | Obrigatório. `1` = erro na emissão, `2` = serviço não prestado, `9` = outros | | `motivo` | string | Obrigatório. Justificativa, 15–255 caracteres | Só cancela nota **autorizada** e com **chave de acesso** preenchida. Em sucesso, a nota passa a `cancelada`; o XML do evento é arquivado. Rejeição no cancelamento gera `FiscalException` com `cStat`/`motivo` quando disponíveis (`422`). Na consulta da NFS-e, os campos são `codigo`/`motivo`. ## Créditos (billing) NF-e, NFC-e e NFS-e debitam **1 crédito no enfileiramento**. O observer aciona estorno em **erro, rejeição ou denegação**; o reenvio debita novamente. Sem saldo, a emissão retorna **`402`**, separado da rejeição fiscal. A carteira é da conta quando a empresa está vinculada; no cadastro legado, da empresa. O header **`x-quota-saldo`** aparece nas respostas de emissão inicial e de saldo/movimentação de créditos, não em todas as respostas. Na emissão inicial de NFC-e, o controller lê o saldo da empresa, enquanto o débito pode ocorrer na conta; a correspondência desse header com a carteira fica a confirmar. **Ressalva da NFC-e — a confirmar:** `NfceEmissor::enfileirar` registra o recurso como `nfce`, mas `NotaStatusObserver` procura `nfe` ao estornar `NotaFiscal`. `CreditoService::estornar` filtra pelo tipo; portanto, o estorno do débito inicial de NFC-e não está sustentado por esse caminho. O reenvio registra `nfe`. Esta revisão apenas documenta a divergência. ### Reenvio `POST /api/v1/nfe/{nota}/reenviar`, `POST /api/v1/nfce/{nota}/reenviar` e `POST /api/v1/nfse/{nota}/reenviar`, com scope `nfe:emitir`, recebem o payload corrigido. São aceitas notas `rejeitada` ou `erro`, respeitadas as restrições do emissor (incluindo numeração inutilizada para NF-e/NFC-e). Reutilizam número/série, debitam novamente e retornam `202` com status `pendente`. ### Downloads e condições Os controllers de downloads não implementam débito por repetição nem regra de primeiro download gratuito. NF-e/NFC-e têm geração de PDF; NFS-e apenas serve PDF já disponível. Preços, compra mínima, validade/acúmulo de créditos, mensalidade, fidelidade, suporte, downloads e política comercial de estorno ficam **sob consulta**; o comportamento técnico acima não define uma oferta comercial. Crédito não é lançado pela API: o saldo é creditado pelo admin/comercial da EMITEX (o antigo `POST /api/v1/empresas/{empresa}/creditos` foi removido e responde `405`). ### `GET /api/v1/empresas/{empresa}/creditos` — saldo + extrato (scope `empresas:gerenciar`) Retorna `saldo` e o ledger paginado (`movimentos`: tipo, origem, quantidade, saldo_apos, recurso). `402` ao emitir sem saldo: ```json { "error": "creditos_insuficientes", "message": "Créditos insuficientes para emitir.", "saldo": 0 } ``` ## Webhooks A empresa recebe uma notificação **POST** sempre que uma nota (NF-e ou NFS-e) muda para status final (`autorizada`, `rejeitada`, `denegada`, `cancelada`, `erro`). O job `EnviarWebhook` configura até **cinco tentativas no total**, incluindo a inicial, com backoff progressivo e registro de entrega. Não são cinco retentativas adicionais; a execução depende da fila e não constitui SLA. NFC-e usa o tipo/evento `nfe` porque compartilha o modelo `NotaFiscal`. ### `POST /api/v1/empresas/{empresa}/webhook` — configurar (scope `empresas:gerenciar`) ```json { "url": "https://seu-sistema/webhooks/emitex", "regenerar_secret": false } ``` Resposta inclui o `secret` **uma única vez** (na criação/regeneração) — guarde-o para validar a assinatura. ### Evento entregue ```http POST {sua url} X-Emitex-Event: nfse.autorizada X-Emitex-Delivery: 42 X-Emitex-Signature: sha256= Content-Type: application/json { "evento": "nfse.autorizada", "ocorrido_em": "2026-06-13T...", "recurso": { "tipo": "nfse", "id": 29, "status": "autorizada", "numero": 1, "serie": 1, "ambiente": "homologação", "chave": "...", "motivo": "...", "nfse_numero": "39", "codigo_verificacao": "WBNQMZFB" } } ``` Para NFS-e o `recurso` inclui `nfse_numero` e `codigo_verificacao` (este `null` no Padrão Nacional), para o consumidor montar o link de visualização sem uma consulta extra. NF-e/NFC-e não trazem esses campos; incluem `recurso.cstat` (minúsculo), `protocolo` e `autorizada_em`. A consulta NF-e/NFC-e usa `cStat` (maiúsculo), sem uniformização desses nomes. **Validação:** calcule `HMAC-SHA256(corpo_bruto, secret)` e compare com o header `X-Emitex-Signature` (`sha256=`). Responda `2xx` para confirmar; falha de transporte ou resposta fora de `2xx` provoca falha do job, sujeita ao limite total de cinco tentativas. ### `GET /api/v1/empresas/{empresa}/webhook/entregas` — auditoria (scope `empresas:gerenciar`) Lista paginada das entregas (evento, http_status, sucesso, tentativas, erro). ## Validador de XML ### `POST /api/v1/documentos/validar` — validar XML fiscal (scope `nfe:consultar`) Validação **offline** (não consulta SEFAZ/prefeitura) de estrutura, schema XSD e assinatura digital. **Não é por empresa** (sem `tenant`) e não implementa débito de crédito. Condições comerciais de uso sob consulta. Throttle 120/min. **Request** ```json { "tipo": "nfe", "xml": "..." } ``` `tipo`: `nfe` | `nfce` | `nfeproc` (NF-e processada) | `dps` | `nfse` | `evento`. `xml`: string, até ~5 MB. **Response `200`** (sempre 200 quando a requisição é válida — o resultado vai no corpo): ```json { "tipo": "nfe", "bem_formado": true, "schema": { "valido": true, "erros": [] }, "assinatura": { "presente": true, "valida": true, "erro": null }, "valido": true } ``` - `valido` = `bem_formado` **E** `schema.valido` **E** (`assinatura` ausente **OU** `assinatura.valida`). - XML malformado → `bem_formado=false` e os erros do parser em `schema.erros`. - Documento sem `` (ex.: DPS) → `assinatura.presente=false` (não reprova). ## Distribuição de DF-e (recebimento) Recebe as NF-e emitidas **contra** o CNPJ da empresa (Ambiente Nacional / NFeDistribuicaoDFe) e permite a **manifestação do destinatário**. A empresa precisa de `dist_ativa = true` e certificado A1. Recebimento/consulta/download não implementam débito de crédito; cada manifestação registrada com cStat 135/136 tenta debitar 1 crédito. Duplicidade reconhecida (573) não gera novo débito. Condições comerciais sob consulta. ### `GET /api/v1/empresas/{empresa}/distribuicoes` — listar (scope `distribuicao-nfe:consultar`) Paginado (20/pág). Filtros: `status` (`recebida`|`completa`|`erro`), `manifestacao_status` (`pendente`|`enviada`|`registrada`|`rejeitada`), `ambiente` (1|2), `chave` (44). Throttle 240/min. Cada item traz `nsu`, `chave`, `schema` (`resNFe`/`procNFe`/`resEvento`/`procEventoNFe`), `emitente` (cnpj/nome), `valor`, `status`, `manifestacao` e link de XML. ### `GET /api/v1/empresas/{empresa}/distribuicoes/{distribuicao}` — detalhe (scope `distribuicao-nfe:consultar`) ### `GET /api/v1/empresas/{empresa}/distribuicoes/{distribuicao}/xml` — baixar XML (scope `distribuicao-nfe:consultar`) `404` se o XML ainda não estiver disponível. ### `POST /api/v1/empresas/{empresa}/distribuicoes/sincronizar` — forçar sincronização (scope `distribuicao-nfe:consultar`) Enfileira o polling (`202`). Throttle 12/min. Respeita o intervalo mínimo entre sincronizações (proteção contra cStat 656). ### `POST /api/v1/empresas/{empresa}/distribuicoes/{distribuicao}/manifestar` — manifestar (scope `distribuicao-nfe:manifestar`) ```json { "tipo": "ciencia", "justificativa": null } ``` `tipo`: `ciencia` | `confirmacao` | `desconhecimento` | `nao_realizada`. `justificativa` (15–255) **obrigatória** para `nao_realizada`. Responde `202` (processamento assíncrono) com `x-quota-saldo`. Tenta debitar 1 crédito quando o evento é **registrado** (135/136); rejeição não debita, duplicidade reconhecida (573) não gera novo débito. A pré-checagem exige saldo, mas falha no débito após registro é apenas logada pelo serviço. Condições comerciais sob consulta. Throttle 60/min. ## Throttles configurados nas rotas | Grupo | Limite | |---|---| | Empresas | 120/min | | Emissão | 60/min | | Consulta/artefatos | 240/min | | Listagem de notas | 240/min | | Cancelamento | 60/min | | Validador de XML | 120/min | | Distribuição (consulta) | 240/min | | Distribuição (sincronizar) | 12/min | | Manifestação | 60/min | ## Histórico | Data | Descrição | |---|---| | 2026-06-12 | v1 inicial: auth client_credentials, empresas + certificado, emissão/consulta/cancelamento de NF-e, XML/DANFE | | 2026-06-13 | NFS-e Padrão Nacional: cancelamento via evento e101101 no endpoint `/nfse/{nota}/cancelar` (corpo `motivo_codigo` + `motivo`); rota agora roteia por provedor (São Paulo / Nacional) | | 2026-07-09 | NFS-e: `GET /nfse/{nota}` passa a retornar `codigo_verificacao` e `links.pdf`; webhook de NFS-e inclui `nfse_numero` + `codigo_verificacao`; nova rota `GET /nfse/{nota}/pdf` (DANFSe quando existir, senão 404). Mudança **aditiva** | | 2026-11-14 | NFS-e Padrão Nacional: `nfse_numero` passa a ser o `nNFSe` oficial (antes vinha o `idDps`); sem campo novo, contrato inalterado | | 2026-11-14 | NFS-e Padrão Nacional: `iss_retido` documentado como booleano (`true` = retido pelo tomador), como a validação sempre exigiu; corrige `tpRetISSQN` invertido na DPS | | 2026-11-14 | NFS-e Padrão Nacional: `codigo_servico` com 9 dígitos (com ou sem pontos) gera `cTribNac` (6 primeiros) + `cTribMun` (3 últimos) na DPS; 6 dígitos seguem como antes. Mudança **aditiva** | | 2026-11-14 | Empresas: campo opcional `percentual_tributos_sn` no `POST`/`PATCH` e na resposta da empresa. NFS-e Padrão Nacional de ME/EPP do Simples passa a exigir o campo (vai em `pTotTribSN`; antes `indTotTrib=0`, rejeitado com E0712). Mudança **aditiva** no contrato | | 2026-06-13 | NFC-e (modelo 65): `POST /empresas/{id}/csc`, emissão/consulta/XML/cupom/cancelamento em `/nfce`, QR Code automático | | 2026-06-15 | Validador de XML standalone: `POST /documentos/validar` (bem-formado + XSD por tipo + assinatura), offline, sem crédito | | 2026-06-15 | Distribuição de DF-e: `GET/POST /empresas/{id}/distribuicoes*` (listar/detalhe/xml/sincronizar/manifestar), scopes `distribuicao-nfe:consultar`/`:manifestar`; manifestação debita 1 crédito |