# API NOTAS PRO > API REST brasileira para emissão de NFS-e pelo **padrão nacional** (Sefin Nacional / Ambiente de Dados Nacional): uma integração para todos os municípios conveniados ao Sistema Nacional. Emissão enfileirada (202 com identificador, ou 201 com `?wait=`), cancelamento por evento, XML assinado da DPS e da NFS-e, webhooks assinados. A documentação e o produto estão em prévia local. Idioma: português do Brasil. Resolva os links que começam com / na mesma origem deste arquivo. O contrato canônico é /openapi.json; os exemplos dos guias são sintéticos. O catálogo da prévia inclui Free R$ 0/50 notas, Dev R$ 99/500, SaaS Pro R$ 249/2 mil e Enterprise R$ 749/10 mil, por ciclo mensal, com nota adicional a R$ 0,25 em todos os planos. A franquia é por organização, não por emitente. Há dois tipos de chave e a diferença importa: a **Project Key** (`pk_test_…` no sandbox, `pk_live_…` em produção) emite e consulta notas de um único emitente (escopos nfse:emitir, nfse:ler, nfse:cancelar, documentos:ler); o **Org Token** (`ot_test_…`, `ot_live_…`) cria projetos e chaves, cadastra emitentes, envia certificados e administra webhooks, e **não emite**. Ambos vão no header Authorization: Bearer. A chave determina o emitente e o ambiente; o sandbox dispensa certificado. POST /v1/nfse aceita Idempotency-Key e devolve 202 por padrão; a `referencia` é única por emitente, e repetida devolve a nota só à chave com o escopo de leitura do modelo (à que só emite, 409 REFERENCE_IN_USE, sem os dados da nota); `?wait=` (até 30) segura a requisição até o desfecho. Cada documento autorizado em produção, de qualquer modelo, consome uma nota da franquia; recusado, denegado, homologação e sandbox não consomem. Sem saldo, a emissão responde 402 QUOTA_EXCEEDED antes de gastar número. Emitir na Produção Restrita e em produção exige um certificado digital **A1 do próprio emitente** (o sandbox dispensa): a Sefin recusa DPS assinada por titular diferente da inscrição do prestador (E0718). No envio do certificado e depois todo dia, a API pergunta à AC emissora, pela LCR e pelo OCSP, se o A1 foi revogado: revogado no envio é 422 CERTIFICATE_REVOKED; revogado depois para a emissão do emitente com 409 CERTIFICATE_REVOKED antes de gastar número, e sai o webhook certificate.revoked. A AC fora do ar não recusa nada (`revogacao.situacao` indisponivel no certificado). Rejeição de regra vem com o código oficial do Anexo I em erros[], um item por campo. ## Integração - [Início rápido](/docs/inicio-rapido.md): do Org Token de sandbox à nota emitida e cancelada, sem certificado — criar o projeto, cadastrar o emitente, gerar a Project Key, emitir, consultar, baixar XML e DANFSe, mandar por e-mail ao tomador, cancelar. Cada requisição do guia é executada pela suíte de testes da API. - [Coleção Postman](/docs/api-notas-pro.postman_collection.json): os mesmos passos do início rápido, gerados a partir dele, com dados fictícios. - [Início rápido da NF-e](/docs/inicio-rapido-nfe.md): NF-e modelo 55 pela SEFAZ da UF do emitente, no sandbox contra a SEFAZ simulada e sem certificado — emitente com inscrição estadual e série, Project Key com os escopos nfe:emitir, nfe:ler, nfe:cancelar, nfe:corrigir e nfe:inutilizar, emissão em POST /v1/nfe, XML (nfeProc), DANFE em PDF, o envio por e-mail ao destinatário, carta de correção, cancelamento e uma exportação, com o destinatário no exterior (idEstrangeiro, município 9999999, país do BACEN e o grupo exportacao); os tributos de cada item são os que o sistema calculou: ICMS por CST ou CSOSN, com a substituição tributária (icms.st), o IPI (ipi), o DIFAL da venda interestadual a consumidor final (difal), PIS, COFINS e IBS/CBS. A recusa traz o `cStat` oficial em erros[]. Cada requisição do guia é executada pela suíte de testes da API. - [Coleção Postman da NF-e](/docs/api-notas-pro-nfe.postman_collection.json): os mesmos passos do início rápido da NF-e, gerados a partir dele, com dados fictícios. - [Início rápido da NFC-e](/docs/inicio-rapido-nfce.md): NFC-e modelo 65, a venda ao consumidor, no sandbox contra a SEFAZ simulada e sem certificado — emitente com série da NFC-e, CSC guardado em PUT /v1/org/emitentes/{project}/csc/{ambiente} (Org Token com certificados:escrever), Project Key com nfce:emitir, nfce:ler, nfce:cancelar e nfce:inutilizar, emissão em POST /v1/nfce com QR Code versão 2, DANFCe de 80 mm em PDF ou HTML, o envio por e-mail ao consumidor, cancelamento, a recusa com o `cStat` oficial e a contingência off-line: sem retorno da SEFAZ, a nota sai em status contingency, com QR Code e cupom, e a API a transmite depois; se a SEFAZ a recusar, ela fica em contingency_rejected e se corrige, com a mesma chave, em POST /v1/nfce/{id}/retransmissao. Cada requisição do guia é executada pela suíte de testes da API. - [Coleção Postman da NFC-e](/docs/api-notas-pro-nfce.postman_collection.json): os mesmos passos do início rápido da NFC-e, gerados a partir dele, com dados fictícios. - [Início rápido do CT-e](/docs/inicio-rapido-cte.md): CT-e modelo 57, modal rodoviário, no sandbox contra a SEFAZ simulada e sem certificado — emitente com inscrição estadual, RNTRC e série do CT-e, Project Key com cte:emitir, cte:ler, cte:cancelar e cte:corrigir, emissão em POST /v1/cte com o tomador do frete, as partes, o ICMS e as NF-e da carga, XML (cteProc), DACTE em PDF, o envio por e-mail ao tomador, carta de correção por campos, o cancelamento vedado depois dela (cStat 523), outro CT-e cancelado, o CT-e Simplificado em POST /v1/cte/simplificado, o pagamento antecipado (antecipação e fornecimento) e a recusa do CFOP com o `cStat` oficial. Cada requisição do guia é executada pela suíte de testes da API. - [Coleção Postman do CT-e](/docs/api-notas-pro-cte.postman_collection.json): os mesmos passos do início rápido do CT-e, gerados a partir dele, com dados fictícios. - [Início rápido do MDF-e](/docs/inicio-rapido-mdfe.md): MDF-e modelo 58, o manifesto da viagem, no sandbox contra a SEFAZ simulada e sem certificado — emitente com inscrição estadual, RNTRC e série do MDF-e, Project Key com mdfe:emitir, mdfe:ler, mdfe:cancelar, mdfe:encerrar e mdfe:condutores, emissão em POST /v1/mdfe com o veículo, os condutores, a ANTT, o seguro e o CT-e da descarga, XML (mdfeProc), DAMDFE em PDF, inclusão de condutor, a placa recusada com o cStat 611 enquanto o manifesto está aberto, o encerramento e outro manifesto cancelado, a balsa do aquaviário, o CT-e Simplificado em prestação parcial e o encerramento pelo dono do caminhão (POST /v1/mdfe/terceiros/{chave}/encerramento, com a conta dele). Cada requisição do guia é executada pela suíte de testes da API. - [Coleção Postman do MDF-e](/docs/api-notas-pro-mdfe.postman_collection.json): os mesmos passos do início rápido do MDF-e, gerados a partir dele, com dados fictícios. - [Exportação para o contador](/docs/exportacao-contador.md): os XML de um período num ZIP, por POST /v1/exportacoes (Project Key com documentos:ler; Idempotency-Key como na emissão), com o período pela data de emissão em dias de Brasília (de e ate, até 31 dias) e, se quiser, os modelos; o emitente e o ambiente são os da chave. A resposta é 202 e a fila gera o arquivo: GET /v1/exportacoes/{id} mostra a situação (queued, processing, ready, failed, expired) e GET /v1/exportacoes/{id}/arquivo baixa o ZIP por 7 dias (depois, 410 EXPORT_EXPIRED), com o nfeProc, cteProc, mdfeProc ou a NFS-e de cada nota autorizada, cancelada, substituída, denegada ou encerrada, os eventos dela e as inutilizações do período, em pastas por modelo, e um resumo.csv (UTF-8 com BOM, separador ;, valor com vírgula) com modelo, série, número, chave, data de emissão, competência, situação, destinatário, valor total e, por último, o total do documento, só no CT-e com IBS/CBS (o vTotDFe, que a partir de 2027 soma o IBS e a CBS ao valor da prestação). Sem cálculo de imposto. Webhook exportacao.completed. No painel, em Notas fiscais › Exportar para o contador. No SDK, notas.exportacoes.pedir, consultar, listar e baixar. Cada requisição do guia é executada pela suíte de testes da API. - [Coleção Postman da exportação para o contador](/docs/api-notas-pro-exportacao.postman_collection.json): os mesmos passos do guia da exportação, gerados a partir dele, com dados fictícios. - [NF-e recebidas e manifestação](/docs/nfe-recebidas.md): as NF-e que fornecedores emitem contra o CNPJ do emitente, lidas da distribuição de DF-e do Ambiente Nacional (NT 2014.002), no sandbox contra o AN simulado, sem certificado e com notas de fornecedores fictícios — Project Key com nfe:recebidas (ler e ligar a leitura em POST /v1/nfe/recebidas/sincronizacao, que segue a espera de uma hora do AN depois do 137 e do 656; o NSU que faltou na sequência é consultado pontualmente pelo consNSU, até 10 por hora, e o 137 dele é desconsiderado) e nfe:manifestar, a lista em GET /v1/nfe/recebidas com filtros e cursor, a nota pela chave, o resumo (resNFe) e o XML completo (nfeProc) depois da ciência, e a manifestação do destinatário (NT 2020.001) em POST /v1/nfe/recebidas/{chave}/manifestacao: ciencia, confirmacao, desconhecimento e nao_realizada (com a justificativa de 15 a 255 caracteres). Cada conclusivo vai até duas vezes (Ajuste SINIEF 43/2023), a terceira volta 409 MANIFESTATION_LIMIT_REACHED; prazos gerais só como informação, e a recusa do AN (596, 655) volta com o cStat em erros[]. Webhooks nfe.received (a nota chegou) e nfe.received_cancelled (o fornecedor cancelou a que já tinha chegado). No painel, em NF-e recebidas, com a leitura ligada no ambiente da barra de cima (Sandbox alcança o sandbox e a homologação, Produção a produção, como as chaves) e o XML de cada evento registrado (o mesmo procEventoNFe de GET /v1/nfe/recebidas/{chave}/eventos/{tpEvento}/{sequencia}/xml). Cada requisição do guia é executada pela suíte de testes da API. - [Coleção Postman das NF-e recebidas](/docs/api-notas-pro-nfe-recebidas.postman_collection.json): os mesmos passos do guia das NF-e recebidas, gerados a partir dele, com dados fictícios. - [CT-e recebidos e desacordo](/docs/cte-recebidos.md): os CT-e que transportadoras emitem com o CNPJ do emitente como tomador, remetente, destinatário, expedidor ou recebedor, lidos da distribuição de DF-e do Ambiente Nacional do CT-e (NT 2015.002), no sandbox contra o AN simulado, sem certificado e com CT-e de transportadoras fictícias — Project Key com cte:recebidos (ler e ligar a leitura em POST /v1/cte/recebidos/sincronizacao, que segue a espera de uma hora do AN depois do 137 e do 656; o NSU que faltou na sequência é consultado pontualmente pelo consNSU, até 10 por hora, e o 137 dele é desconsiderado) e cte:desacordo, a lista em GET /v1/cte/recebidos com filtros (papel, situacao, desacordo) e cursor, o CT-e pela chave com o tomador que ele declara e os papéis do emitente, o XML (cteProc), e a prestação do serviço em desacordo (610110) em POST /v1/cte/recebidos/{chave}/desacordo, com a observacao de 15 a 255 caracteres, e o cancelamento dela (610111) em POST /v1/cte/recebidos/{chave}/desacordo/cancelamento. Só o tomador registra: nos outros papéis, 422 com o cStat 755 antes de assinar; o prazo de 150 dias só como informação, e a recusa do autorizador (787) volta com o cStat em erros[]. No CT-e de transportador autônomo (NFF ou PAA) ou de MEI, a apropriação do crédito presumido do IBS e da CBS (evento 211110, NT 2026.004) em POST /v1/cte/recebidos/{chave}/credito-presumido, com o escopo cte:credito-presumido: baseCalculo, codigo (cCredPres; no CT-e, o 02), ibs e cbs (percentual e valor) e declaracaoPagamento; vai à SVRS, a única que o autoriza, e a API recusa antes de assinar o que as regras 01 a 16 da NT recusariam (755, 1060, 1061 a 1071). Webhook cte.received. No painel, em CT-e recebidos, com a leitura ligada no ambiente da barra de cima (Sandbox alcança o sandbox e a homologação, Produção a produção, como as chaves) e o XML de cada evento registrado (o mesmo procEventoCTe de GET /v1/cte/recebidos/{chave}/eventos/{tpEvento}/{sequencia}/xml). Cada requisição do guia é executada pela suíte de testes da API. - [Coleção Postman dos CT-e recebidos](/docs/api-notas-pro-cte-recebidos.postman_collection.json): os mesmos passos do guia dos CT-e recebidos, gerados a partir dele, com dados fictícios. - [Entrega do CT-e](/docs/cte-entrega.md): os eventos de entrega do transportador emitente do CT-e (modelo 57), com a Project Key com cte:entrega, no sandbox contra a SEFAZ simulada — o comprovante de entrega (110180, MOC CT-e 4.00 §6.8) em POST /v1/cte/{id}/comprovante-entrega, com entregueEm, recebedor (documento e nome), localizacao (latitude e longitude, opcional), nfes (as chaves das NF-e entregues) e a imagem capturada: em imagem, Base64 padrão de até 512 KiB, de que a API tira o hash (SHA-1 em Base64 da chave do CT-e seguida do Base64 da imagem) sem guardá-la, ou o hash pronto em hash com hashGeradoEm; o insucesso na entrega (110190, NT 2023.002 v1.01) em POST /v1/cte/{id}/insucesso-entrega, com tentativaEm, tentativa (opcional), motivo (recebedor-nao-encontrado, recusa-do-recebedor, endereco-inexistente ou outros, este com a justificativa de 15 a 256 caracteres), localizacao, a imagem opcional e nfes; e o cancelamento de cada um (110181 e 110191) em .../cancelamento, com a sequencia do evento a cancelar. Cada tipo na sua sequência (1 a 999); Idempotency-Key devolve o registrado sem ir à SEFAZ. A API recusa antes de assinar, com o cStat em erros[] e origem local: 869 (complementar), 872, 873, 918 e 919 (datas antes da emissão ou depois de agora), 870 e 920 (um vigente por CT-e, salvo o globalizado), 865, 871, 921 e 922 (as NF-e pelo tipo de serviço), 860 e 923 (chave), 861, 863, 864, 924 e 925 (NF-e repetida, já em outro evento ou fora do CT-e), 926 (outros sem justificativa), 866 (sequência sem evento) e 218 (CT-e cancelado); o cancelamento do CT-e com comprovante vigente é 862. Os eventos aparecem em GET /v1/cte/{id}/eventos (com comprovante, insucesso ou cancela) e o procEventoCTe em GET /v1/cte/{id}/eventos/{tipo}/{sequencia}/xml. Webhooks cte.delivered, cte.delivery_cancelled, cte.delivery_failed e cte.delivery_failure_cancelled, com o evento em data.entrega. No painel, a seção Entrega do detalhe do CT-e, para os papéis de gestão. Cada requisição do guia é executada pela suíte de testes da API. - [Coleção Postman da entrega do CT-e](/docs/api-notas-pro-cte-entrega.postman_collection.json): os mesmos passos do guia da entrega do CT-e, gerados a partir dele, com dados fictícios e as datas no instante do pedido ({{$isoTimestamp}}). - [Relatório de ISS por competência](/docs/relatorio-iss.md): GET /v1/nfse/relatorios/iss?competencia=AAAA-MM (Project Key com nfse:ler; o emitente e o ambiente são os da chave) devolve o que as NFS-e do emitente somam no mês, por município de incidência (cLocIncid) e, dentro dele, por grupo — o regime do prestador na nota (opSimpNac 1 não optante, 2 MEI, 3 ME/EPP, 4 optante pendente; a ME/EPP com regApTribSN 2 ou 3 fica à parte, com o ISS das notas) e o tipo de retenção (tpRetISSQN 1, 2 tomador, 3 intermediário) —, com o rótulo de cada valor de ISS ("ISS destacado nas notas", "ISS retido pelo tomador, conforme a nota" e os outros); ME/EPP sem retenção e MEI não somam ISS, e não há total de ISS do mês. Agrupa valores das notas; não calcula imposto nem confirma recolhimento. Canceladas e substituídas ficam em foraDosTotais; alertas CANCELAMENTO_PENDENTE (análise fiscal sem desfecho, ou substituta de fora sem o cancelamento da original), SUBSTITUTA_EM_OUTRA_COMPETENCIA (a substituta conta na competência gravada nela: decisão do sistema), MEI_COM_RETENCAO e NOTA_SEM_DADOS. Entram as NFS-e emitidas fora da API que a distribuição de DF-e trouxe; a de tomador não. posicaoEm é o instante da leitura. formato=csv devolve o mesmo relatório para o Excel (UTF-8 com BOM, separador ;, valor com vírgula). No painel, em Relatório de ISS. A revisão dos rótulos é do Conselheiro Contábil. Cada requisição do guia é executada pela suíte de testes da API. - [Coleção Postman do relatório de ISS](/docs/api-notas-pro-relatorio-iss.postman_collection.json): os mesmos passos do guia do relatório de ISS, gerados a partir dele, com dados fictícios. - [Emissão pelo painel](/docs/emissao-pelo-painel.md): sem chave de API, na página Notas fiscais do painel, pelo emitente e pelo ambiente da barra de cima — uma nota pelo formulário (os padrões do cadastro do emitente, a conferência antes de enviar e o resultado com o link para o detalhe), ou em JSON a um clique, com o mesmo pedido de POST /v1/nfse e o que o formulário não mostra (a exportação de serviço, os tributos federais retidos, a substituição) indo junto ao voltar aos campos, ou Partir de outra nota, que carrega o pedido de uma NFS-e anterior; ou até 100 por planilha CSV ([modelo](/docs/modelo-nfse.csv): UTF-8 com ou sem BOM, separador ; ou ,, valor em reais com vírgula decimal, data DD/MM/AAAA, colunas com o nome do campo no contrato, como tomador.inscricao, servico.descricao e valores.servico). A planilha é conferida linha a linha, com a linha e a coluna de cada erro, contra o contrato e as regras da emissão, sem gastar número; com erro em qualquer linha nada é emitido, a não ser que se escolha emitir só as válidas; acima de 100 linhas é recusada inteira. O caminho é o mesmo de POST /v1/nfse e POST /v1/nfse/lote: as mesmas validações, a mesma numeração, a mesma fila e a mesma cobrança (em produção, cada nota usa uma do saldo). Emitem o dono, o administrador e o desenvolvedor; o leitor e o financeiro não; o membro restrito a emitentes só nos dele. Cada envio leva uma Idempotency-Key, e o duplo clique devolve a mesma nota. A NF-e e a NFC-e também saem pelo painel (Emitir NF-e e Emitir NFC-e), com o mesmo pedido e o mesmo serviço de POST /v1/nfe e POST /v1/nfce: um formulário guiado (identificação, destinatário ou consumidor, itens com o ICMS, o PIS, a COFINS, o IBS/CBS e, na NF-e, o IPI e o DIFAL, transporte, pagamento e informações complementares) que não sugere CFOP, CST, alíquota, cClassTrib nem valor de imposto e só faz conta aritmética (quantidade × valor unitário do item e as somas), o JSON do pedido a um clique para o que o formulário não mostra, e Partir de outra nota, que carrega o pedido de uma NF-e ou NFC-e anterior do mesmo emitente e do ambiente da barra (sem a referência) para corrigir e emitir de novo; o erro da API aparece no campo que ela aponta em erros[].campo, e a recusa da SEFAZ com o cStat. A NF-e e a NFC-e também saem por planilha (NF-e por planilha e NFC-e por planilha; modelos [/docs/modelo-nfe.csv](/docs/modelo-nfe.csv) e [/docs/modelo-nfce.csv](/docs/modelo-nfce.csv)): CSV no formato da planilha da NFS-e, uma linha por item, as linhas de uma nota juntas pela referencia, colunas com o nome do campo no pedido (item. e pagamento. na frente), sem valor fiscal padrão em nenhuma coluna, até 100 notas, 1.000 linhas e 1 MB; POST /api/org/{org}/projects/{project}/{nfe,nfce}/planilha/conferencia?environment= mostra cada nota montada e os erros com a linha e a coluna, pelo contrato e pelas regras da emissão, sem gastar número, e a nota que o arquivo já emitiu com a situação dela; POST …/planilha emite só as prontas, uma a uma, pelo serviço de POST /v1/nfe e /v1/nfce e com a mesma cobrança, cada uma com a Idempotency-Key tirada do que o arquivo diz dela (o mesmo arquivo de novo não emite duas vezes e emite só as que faltam), e responde o relatório com emitidasAgora e interrupcao (o 402 sem saldo no meio para o envio; sem nenhuma nota emitida, a resposta é o próprio erro); a referência que já é de outra nota volta como REFERENCE_IN_USE na coluna referencia; POST …/planilha/relatorio devolve o relatório em CSV, uma linha por nota, com o cStat da recusa e a fórmula neutralizada. O CT-e e o MDF-e também saem pelo painel (Emitir CT-e e Emitir MDF-e), com o mesmo pedido e o mesmo serviço de POST /v1/cte, POST /v1/cte/simplificado e POST /v1/mdfe: um formulário guiado do modal rodoviário (no CT-e, a prestação, o tomador e as partes, os valores com os componentes, o ICMS com os campos que o CST pede, a carga, as NF-e e as observações; no MDF-e, o carregamento e o percurso, as descargas com os documentos, o veículo e os condutores, o seguro, o produto predominante, a ANTT com o pagamento do frete e os totais) que não sugere CFOP, CST, alíquota nem valor e só faz conta aritmética (a soma dos componentes do CT-e, que só se mostra, e o valor do contrato do frete do MDF-e, que é a soma dos componentes pela regra F58 até a pessoa digitar outro); o CT-e Simplificado, os outros modais e os grupos raros vão pelo JSON, e a gaveta lista os grupos do pedido que o formulário não mostra; Partir de outra nota carrega o pedido de um CT-e ou MDF-e anterior sem a referência (o Simplificado abre o Simplificado; o complementar não serve de partida). No detalhe da nota, Emitir de novo abre a gaveta do modelo (NFS-e, NF-e, NFC-e, CT-e ou MDF-e) pelo emitente da nota e com o pedido dela, sem a referência e com a Idempotency-Key da gaveta, nunca a da nota de origem; aparece para quem emite, na nota do ambiente da barra, e não no CT-e complementar; na NFS-e, o pedido vem inteiro, com a competência de hoje: os campos com o que cabe neles e o resto (a exportação, os tributos federais retidos, a substituição) no JSON, que a gaveta lista. O pedido de uma nota anterior vem de GET /api/org/{org}/projects/{project}/{modelo}/{id}/pedido?environment=, de quem pode emitir. O que vem depois deles sai também pelo painel, pelo mesmo caminho da rota da API: no detalhe da nota, cancelar, carta de correção, vincular o pagamento à NF-e e à NFC-e (110300) e desfazer a vinculação (110001), emitir o CT-e complementar (com o CST e a alíquota do original) e o substituto do CT-e e do Simplificado (a partir do pedido do original, campo a campo ou em JSON), corrigir e retransmitir a NFC-e em contingência recusada, e os eventos do MDF-e; na página do emitente, a inutilização de faixa da NF-e e da NFC-e (lista do ambiente da barra, com o XML); na página de notas, o encerramento do MDF-e de outro emitente pelo dono do caminhão (NT 2024.001); no CT-e recebido, a apropriação do crédito presumido pelo tomador (211110). Agem o dono, o administrador e o desenvolvedor, no ambiente da barra de cima; o erro da API aparece no campo; cada ação fica registrada com a pessoa. Continuam só pela API: o complementar de vários CT-e e a importação de XML. - CT-e (modelo 57, modal rodoviário), no [contrato OpenAPI](/openapi.json), grupo CT-e: POST /v1/cte emite o conhecimento de transporte com o trajeto (municipioInicio, municipioFim), o tomador (uma das partes ou outro), remetente, destinatário, valores em centavos, ICMS por CST, a carga e os documentos (NF-e, DC-e ou outros). O emitente precisa de inscrição estadual, RNTRC e da série em modelos.cte. GET /v1/cte/{id}/dacte devolve o DACTE em PDF ou HTML; cancelamento em até 168 horas e carta de correção por campos (grupo, campo, valor). Com contingencia: { justificativa }, o CT-e sai em contingência off-line (tpEmis 2, NT 2026.004, com dhCont e xJust): vale na hora, em status contingency, com DACTE e o sign no QR Code, e a API o transmite até a SEFAZ autorizar (webhook cte.contingency, depois cte.issued; depois de 168 horas a SEFAZ autoriza fora de prazo, 150); os eventos esperam a autorização. Em produção, a off-line e valores.liquido (vTPrestLiq) só valem a partir de 14/12/2026, quando a NT 2026.004 entra em produção; antes, 215. valores.total não leva o IBS e a CBS: com tributos.ibsCbs, o total do documento (vTotDFe) é o valores.total em 2026 e soma o IBS e a CBS a partir de 2027. O CT-e que ficou esperando a SEFAZ passa para a contingência com POST /v1/cte/{id}/contingencia e a justificativa, com nova chave (e outro número, se já tinha sido enviado; a tentativa original é cancelada se a SEFAZ a autorizou). Sem pedido, se a SEFAZ de origem não responde e a SVC da UF está ativada por ela (status 113), a API gera o CT-e de novo para a SVC — SVC-RS, tpEmis 7, para quem autoriza na SVSP, em MT, MS e SP; SVC-SP, tpEmis 8, para as demais — e o autoriza lá: ele sai issued, com contingencia.tipo svc-rs ou svc-sp, o QR Code da SVC e sem dhCont e xJust (a regra G008 os reserva à off-line); se a origem pode ter recebido o original, o da SVC sai com outro número, e a API cancela a tentativa na origem quando ela volta, se foi autorizada (contingencia.tentativa). O cancelamento do CT-e da SVC vai à SVC; a carta de correção, à origem. O CT-e gerado para a SVC não passa para a off-line (409 CTE_IN_SVC). Pagamento antecipado (NT 2026.002): pagamentoAntecipado { tipo: antecipacao } no CT-e do pagamento feito antes da prestação, { tipo: fornecimento, chaves } no da prestação já paga; o ICMS do CT-e de antecipação vai com cst previsto (o ICMS do fornecimento futuro, NT 2026.004), exigido a partir de 01/02/2027 em homologação e de 01/03/2027 em produção. POST /v1/cte/simplificado emite o CT-e Simplificado (NT 2024.002, tpCTe 5): o tomador, o ICMS e a carga uma vez, e as prestacoes (de 1 a 990) com o trajeto, os valores, o ibsCbs e as NF-e ou os CT-e anteriores de cada uma; o total é a soma, a resposta traz tipo simplificado, e a consulta, o XML (cteSimpProc), o cancelamento e a carta de correção são os do CT-e. Sem DACTE nem e-mail (o leiaute do DACTE do Simplificado não está no Manual do DACTE nem na NT; 400 NOT_SUPPORTED_YET). Em produção, até 14/12/2026, as prestações terminam num só município (370) e sem ibsCbs na prestação (215). Escopos cte:emitir, cte:ler, cte:cancelar e cte:corrigir. No sandbox, contra a SEFAZ simulada. - MDF-e (modelo 58, modal rodoviário), no [contrato OpenAPI](/openapi.json), grupo MDF-e: POST /v1/mdfe emite o manifesto da viagem com o tipo de emitente, os municípios de carregamento e de descarga (com os CT-e ou NF-e de cada um), o veículo e os condutores, a ANTT (CIOT, vale-pedágio, contratantes e pagamento do frete), seguro, produto predominante e totais. O emitente precisa de inscrição estadual, RNTRC e da série em modelos.mdfe. POST /v1/mdfe/{id}/encerramento encerra a viagem (status closed) e libera a placa — enquanto o manifesto está aberto, outro para a mesma placa é recusado com o cStat 611; cancelamento em até 24 horas e inclusão de condutor em POST /v1/mdfe/{id}/condutores. GET /v1/mdfe/{id}/damdfe devolve o DAMDFE em PDF ou HTML. POST /v1/mdfe/{id}/documentos inclui no MDF-e de carga própria emitido com carregamentoPosterior (sem documentos, um município só) as NF-e coletadas no caminho, com o município de descarga de cada uma (evento 110115; 708 no manifesto comum, 711 na NF-e repetida, e sem inclusão ele não se encerra, 715). POST /v1/mdfe/{id}/pagamento registra o pagamento da operação do TAC agregado (evento 110116), com as viagens e o mesmo pagamento de antt.pagamentos, um por MDF-e, também no encerrado (723 quando o proprietário do veículo não é TAC agregado). Com contingencia: true, o MDF-e sai em contingência off-line (tpEmis 2, decisão do contribuinte): vale na hora, em status contingency, com DAMDFE marcado "EMISSÃO EM CONTINGÊNCIA" e o sign no QR Code, prende a placa como manifesto aberto, e a API o transmite até a SVRS autorizar, em até 168 horas (webhook mdfe.contingency, depois mdfe.issued); os eventos esperam a autorização. O MDF-e que ficou esperando a SVRS passa para a contingência com POST /v1/mdfe/{id}/contingencia, com nova chave (e outro número, se já tinha sido enviado; a tentativa original é cancelada se a SVRS a autorizou). POST /v1/mdfe/terceiros/{chave}/encerramento encerra como transportador terceiro (NT 2024.001, evento 110112 com indEncPorTerceiro) o MDF-e que outro emitente emitiu: o emitente da chave é o proprietário ou possuidor do veículo de tração, com o certificado dele, e o pedido leva o protocolo de autorização do MDF-e e o município (524 para o próprio emitente e para quem não é o proprietário; GET no mesmo endereço consulta e /xml traz o procEventoMDFe); o emitente que depois pede o próprio encerramento recebe o do terceiro, adotado pela consulta. Na prestação parcial do CT-e Simplificado (NT 2024.002), descarregamento[].cte[].prestacaoParcial.nfe leva as NF-e que a viagem entrega (525 a 527, e 524 no CT-e da API que não é Simplificado). Escopos mdfe:emitir, mdfe:ler, mdfe:cancelar, mdfe:encerrar, mdfe:condutores, mdfe:documentos e mdfe:pagamento. No sandbox, contra a SEFAZ simulada. - Depois de um restore do banco da API, a nota autorizada que ela perdeu volta: a NFS-e sozinha, pela distribuição de DF-e; a NF-e, a NFC-e, o CT-e e o MDF-e por POST /v1/nfe/importacao, /v1/nfce/importacao, /v1/cte/importacao e /v1/mdfe/importacao (escopo de emissão do modelo), com o `nfeProc`, o `cteProc` ou o `mdfeProc` que o integrador recebeu e, se souber, o `id` e a `referencia` de antes. A API confere a assinatura e o certificado do emitente, o `digVal` do protocolo e consulta o autorizador; a nota volta como ele a tem hoje (autorizada, cancelada, denegada ou encerrada), com os eventos que ele tem (a carta de correção da NF-e e do CT-e; no MDF-e, o encerramento, a inclusão de condutor, a de DF-e e o pagamento da operação), sem transmitir, sem consumir crédito e sem webhook. A mesma chave de novo devolve a nota com 200. As quatro importações cabem juntas 30 por minuto pela organização, no ambiente da chave; acima, 429 RATE_LIMIT_EXCEEDED com Retry-After até o minuto seguinte, sem o corpo ser lido: devolva em série e, no 429, espere e repita a mesma. O documento emitido em contingência que o autorizador ainda não tem também volta, com o XML assinado: a NFC-e off-line, a NF-e em EPEC ou gerada para a SVC, o CT-e off-line ou da SVC e o MDF-e off-line. Sem protocolo, a prova é a assinatura com o certificado A1 do emitente que assinava na API na emissão (e, na NFC-e, o QR Code com o CSC); ele volta como estava, em contingência ou, o da SVC, à espera da autorização, e segue para a transmissão. - E-mail ao destinatário, no [contrato OpenAPI](/openapi.json): a NFS-e, a NF-e, a NFC-e e o CT-e autorizados vão por e-mail a quem os recebe, com o PDF (DANFSe, DANFE, DANFCe, DACTE) e o XML anexos, uma mensagem por endereço, do remetente da plataforma com resposta para o e-mail do emitente; o cancelamento sai numa segunda mensagem aos mesmos endereços, com o XML do evento. O MDF-e fica de fora. Na emissão, o grupo `email` pede o envio: `email.destinatarios` (até 5), ou `{}` para o e-mail do tomador, destinatário ou consumidor informado na nota; `{ "enviar": false }` não manda. Sem o grupo, vale o padrão do emitente em GET e PUT /v1/org/emitentes/{project}/email (Org Token com projetos:ler e projetos:escrever; desligado por padrão, até 4 cópias). GET /v1/{modelo}/{id}/emails (escopo de leitura do modelo) lista os envios com o endereço mascarado, o status (pending, delivered, failed, simulated), as tentativas e o último erro; POST /v1/{modelo}/{id}/emails (escopo de emissão) manda de novo a quem já recebeu e, com `destinatarios` novos, pede também documentos:ler, porque entrega o PDF e o XML (sem ele, 403 INSUFFICIENT_SCOPE); POST /v1/{modelo}/{id}/emails/{email}/reenvio devolve à fila o envio que falhou. Seis tentativas com espera crescente, como nos webhooks; sem evento de webhook próprio. Limites: 5 endereços distintos por nota, 10 envios manuais por nota e 1.000 mensagens por organização em 24 horas (produção e testes à parte; acima, EMAIL_DAILY_LIMIT). Fora de produção, só sai para o e-mail confirmado de um membro da organização; os outros ficam `simulated`. O endereço completo é apagado 90 dias depois do envio. - NT 2023.002 v1.02 e NT 2026.010 na NF-e e na NFC-e: a autorização é sempre síncrona, e o recibo (SEFAZ_PROCESSING) só vale até o fim da autorização assíncrona (01/02/2027 em homologação, 05/04/2027 em produção); a inutilização de emitente do AC, da BA e de SP responde 422 NUMBERING_VOID_DISCONTINUED (cStat 998) desde 11/11/2026, sem ir à SEFAZ; a NF-e emitida a partir de 01/12/2026 sai no DANFE da Reforma Tributária, com o quadro Total do IBS/CBS/IS e as bases, alíquotas e valores do IBS UF, IBS Município, CBS e IS de cada item. O DANFCe não muda. - [SDK em Python](/docs/sdk-python.md): o cliente Python da API (pacote `api-notas-pro`, módulo `api_notas_pro`), só com a biblioteca padrão e Python 3.9 ou mais novo; ainda não está no PyPI e se instala a partir do repositório (`sdks/python`) ou do arquivo `.whl` entregue. `ClienteNotas(chave, base_url)` com notas.nfse, nfe, nfce, cte, mdfe, nfe_recebidas, cte_recebidos, exportacoes, lote, catalogo e distribuicao, nos nomes do SDK TypeScript em snake_case (emitir, consultar, listar, cancelar, xml, danfe, evento_xml…). Nas emissões, a Idempotency-Key é a passada em idempotency_key ou uma gerada pelo SDK, a mesma em todas as tentativas, como no SDK TypeScript; repete sozinho só o que a API marca como repetível (o 429 e os 5xx sem o campo retryable), esperando o Retry-After (2 s sem ele), e só em leitura ou com a chave. ErroDaApi traz status, code, message, erros, request_id, retryable, retry_after e a idempotency_key; ErroDeRede, a falta de resposta. XML em texto, PDF e ZIP em bytes. Tipos em TypedDict gerados do contrato (api_notas_pro.tipos, com py.typed). ler_evento e verificar_assinatura conferem o webhook como o SDK TypeScript, com os mesmos vetores de teste. Cada exemplo do guia é executado pela suíte do SDK. - [Catálogo de erros](/docs/erros.md): formato application/problem+json, o que fazer por status HTTP, cada `code` da API pública e se vale repetir, e os códigos oficiais do Anexo I conferidos antes de transmitir. - [Vindo do Notaas](/docs/migracao-notaas.md): rotas, campos, respostas, webhooks e erros do Notaas lado a lado com os desta API. - [Webhooks](/docs/webhooks.md): eventos nfse.issued, nfse.error, nfse.cancelled, nfse.substituted, lote.completed, certificate.expiring, certificate.expired, certificate.revoked (a AC revogou o A1 do emitente, achado pela conferência diária da LCR e do OCSP), nfe.issued, nfe.error, nfe.denied, nfe.cancelled, nfe.corrected, nfe.contingency (NF-e emitida com EPEC), nfe.received (NF-e de fornecedor que chegou pela distribuição do Ambiente Nacional), nfe.received_cancelled (o fornecedor cancelou a NF-e recebida), nfce.issued, nfce.error, nfce.denied, nfce.cancelled, nfce.contingency, nfce.contingency_rejected, cte.issued, cte.error, cte.cancelled, cte.corrected, cte.contingency, cte.delivered, cte.delivery_cancelled, cte.delivery_failed e cte.delivery_failure_cancelled (os eventos de entrega, com o evento em data.entrega), cte.received (CT-e de transportadora que chegou pela distribuição do Ambiente Nacional do CT-e), mdfe.issued, mdfe.error, mdfe.cancelled, mdfe.closed e mdfe.contingency, e o aviso da nota parada depois das seis tentativas (nfse.stalled, nfe.stalled, nfce.stalled, cte.stalled e mdfe.stalled) e o fim da exportação para o contador (exportacao.completed); assinatura HMAC com instante no cabeçalho x-webhook-signature; seis tentativas ao longo de oito horas; entrega de teste e histórico. - [Planos e limites](/docs/creditos.md): planos da prévia, franquia por organização, o que é cobrado (documento autorizado em produção), o 402 sem saldo, limites por minuto e repetição sem duplicar. - [Contrato OpenAPI](/openapi.json): parâmetros, tipos, escopos, limites e respostas vigentes. ## Evolução - [Changelog](/docs/changelog.md): histórico dos recursos implementados na prévia local. ## Optional - [Documentação para pessoas](/docs): início rápido e regras da API. - [Referência interativa](/reference): documentação gerada do OpenAPI. - [Changelog para pessoas](/changelog): histórico navegável. - [Planos](/#planos): preços e franquias da prévia, carregados do mesmo catálogo usado pelo painel.