{ "openapi": "3.1.0", "info": { "title": "TexFiscal: emissão de NFS-e por API", "version": "2.0.0", "summary": "Emissão, consulta e cancelamento de NFS-e pelo contrato REST v2 de mercado.", "description": "Emissão de Nota Fiscal de Serviço eletrônica pelo seu sistema.\n\nCOMPATIBILIDADE: os caminhos, os campos e os literais de `status` são os do\ncontrato REST v2 de NFS-e que a maioria dos ERPs já integra. Quem já emite por\nAPI migra trocando a URL base e o token, sem mexer no código do cliente.\n\nDUAS REGRAS QUE MUDAM COMO SE ESCREVE O CLIENTE:\n\n1. A `ref` é a chave de idempotência. Repetir o POST com a mesma `ref` NÃO emite\n de novo: devolve a nota que já existe. Gere a `ref` a partir da sua transação,\n nunca de um relógio ou de um aleatório.\n2. Nota em `processando_autorizacao` NUNCA se reenvia. Só a consulta resolve.\n Reenviar duplica documento fiscal, e documento fiscal duplicado se resolve com\n o contador, não com código.\n\nO que este serviço nunca faz: responder 502, 503 ou 504 em rota de API (falha de\ndependência sai como 422 com corpo próprio, porque a Cloudflare troca o corpo de\n5xx pela página dela e o seu fetch cairia no catch sem a mensagem); guardar o seu\ntoken em claro; entregar PDF ou XML por link público.", "contact": { "name": "SeuSaude Tecnologia", "url": "https://texfiscal.com.br" }, "x-logo": { "url": "/marca/texfiscal-logo-reversa-2026-09.svg", "altText": "TexFiscal", "backgroundColor": "#0c1322", "href": "https://texfiscal.com.br" } }, "tags": [ { "name": "NFS-e", "description": "Emitir, consultar, cancelar e baixar o documento." }, { "name": "NF-e e NFC-e", "description": "Nota fiscal de mercadoria (modelos 55 e 65) direto na SEFAZ: emitir, consultar, cancelar, carta de correção, inutilização e XML de distribuição." }, { "name": "Cobertura", "description": "Municípios atendidos, com a data de verificação de cada um." }, { "name": "Conta", "description": "Uso do mês, que é a base da fatura." }, { "name": "Webhook", "description": "O aviso que o serviço manda ao seu sistema quando a nota muda de desfecho, e o cadastro dele por API (/v2/hooks)." }, { "name": "Servico", "x-displayName": "Serviço", "description": "Saúde do ambiente." } ], "servers": [ { "url": "https://homologacao-nfse.texfiscal.com.br", "description": "Homologação. Vai ao ambiente de teste da prefeitura: a nota NÃO tem valor fiscal. Integre aqui primeiro." }, { "url": "https://nfse.texfiscal.com.br", "description": "Produção. Nota com efeito fiscal." } ], "security": [ { "basicAuth": [] } ], "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "HTTP Basic com o token como usuário e senha VAZIA: Authorization: Basic base64(\"SEU_TOKEN:\"). Cada ambiente tem o seu token; o token de um apresentado no outro recebe 401. Os tokens são gerados e revogados pelo cliente no painel (https://painel.texfiscal.com.br)." } }, "schemas": { "UsoMensal": { "type": "object", "description": "Medição do mês. Serve para o cliente conferir a fatura sem deduzir nada.", "required": [ "mes", "ambiente", "por_status", "total", "cobravel" ], "properties": { "mes": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "examples": [ "2026-09" ] }, "ambiente": { "type": "string", "enum": [ "homologacao", "producao" ] }, "por_status": { "type": "object", "description": "Chave é o literal público de status. Ausente quando não houve nota naquele estado.", "additionalProperties": { "type": "object", "required": [ "quantidade", "valor" ], "properties": { "quantidade": { "type": "integer", "examples": [ 9 ] }, "valor": { "type": "number", "description": "Soma de valor_servicos das notas naquele estado.", "examples": [ 5470 ] } } } }, "total": { "type": "integer", "description": "Todas as notas do mês, em QUALQUER estado, inclusive as que falharam. NÃO é o valor da fatura.", "examples": [ 22 ] }, "cobravel": { "type": "integer", "description": "O que a fatura conta: nota que recebeu número da prefeitura, em produção. Em homologação é sempre 0. Este é o número que bate com a cobrança.", "examples": [ 9 ] } } }, "Erro": { "type": "object", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável do erro. Trate por ele, nunca pelo texto." }, "mensagem": { "type": "string" }, "erros": { "type": "array", "description": "Presente quando a recusa é de validação de campo.", "items": { "type": "object", "properties": { "codigo": { "type": "string", "description": "Campo que reprovou, ex.: servico.discriminacao." }, "mensagem": { "type": "string" }, "correcao": { "type": "string", "description": "O que fazer para passar." } } } } } }, "Endereco": { "type": "object", "required": [ "logradouro", "numero", "bairro", "codigo_municipio", "uf", "cep" ], "properties": { "logradouro": { "type": "string", "maxLength": 125 }, "numero": { "type": "string", "maxLength": 10 }, "complemento": { "type": "string", "maxLength": 60 }, "bairro": { "type": "string", "maxLength": 60 }, "codigo_municipio": { "type": "string", "pattern": "^[0-9]{7}$", "description": "Código IBGE de 7 dígitos.", "examples": [ "2910800" ] }, "uf": { "type": "string", "pattern": "^[A-Z]{2}$" }, "cep": { "type": "string", "pattern": "^[0-9]{8}$", "description": "Oito dígitos, sem máscara na saída. Máscara na entrada é aceita e normalizada." } } }, "NotaFiscal": { "type": "object", "properties": { "ref": { "type": "string" }, "status": { "type": "string", "enum": [ "autorizado", "processando_autorizacao", "erro_autorizacao", "cancelado", "processando_cancelamento", "denegado" ] }, "numero": { "type": [ "string", "null" ], "description": "Número da NFS-e na prefeitura." }, "numero_rps": { "type": [ "string", "null" ] }, "serie_rps": { "type": [ "string", "null" ] }, "codigo_verificacao": { "type": [ "string", "null" ] }, "data_emissao": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": [ "string", "null" ], "description": "Endereço do DANFSe. Exige o token: não é link público." }, "caminho_danfse": { "type": [ "string", "null" ] }, "caminho_xml_nota_fiscal": { "type": [ "string", "null" ] }, "mensagem": { "type": [ "string", "null" ] }, "erros": { "type": [ "array", "null" ], "items": { "type": "object" } } } }, "PedidoDfe": { "type": "object", "required": [ "items", "formas_pagamento" ], "properties": { "natureza_operacao": { "type": "string", "maxLength": 60, "examples": [ "Venda de mercadoria" ] }, "cnpj_emitente": { "type": "string", "description": "Opcional. Se vier, tem de ser o CNPJ do emissor do token (senão 422 emitente_divergente)." }, "numero": { "type": "integer", "minimum": 1, "maximum": 999999999, "description": "Opcional. Sem ele o serviço numera a série. Número já usado por outra ref responde 409 numero_em_uso." }, "serie": { "type": "integer", "minimum": 0, "maximum": 889, "default": 1 }, "tipo_documento": { "type": "integer", "enum": [ 0, 1 ], "default": 1, "description": "0 entrada, 1 saída. NFC-e só saída." }, "finalidade_emissao": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "default": 1, "description": "1 normal, 2 complementar, 3 ajuste, 4 devolução (exige notas_referenciadas)." }, "local_destino": { "type": "integer", "enum": [ 1, 2, 3 ], "default": 1, "description": "NF-e: recalculado pela UF do destinatário quando divergir." }, "consumidor_final": { "type": "integer", "enum": [ 0, 1 ], "default": 1 }, "presenca_comprador": { "type": "integer", "default": 1, "description": "NFC-e aceita só 1 (presencial) e 4 (entrega a domicílio)." }, "modalidade_frete": { "type": "integer", "enum": [ 0, 1, 2, 3, 4, 9 ], "default": 9 }, "cnpj_destinatario": { "type": "string", "description": "NF-e exige CNPJ ou CPF. NFC-e aceita e não exige." }, "cpf_destinatario": { "type": "string" }, "nome_destinatario": { "type": "string", "maxLength": 60 }, "indicador_inscricao_estadual_destinatario": { "type": "integer", "enum": [ 1, 2, 9 ], "default": 9, "description": "1 contribuinte (exige inscricao_estadual_destinatario), 2 isento, 9 não contribuinte. NFC-e é sempre 9." }, "inscricao_estadual_destinatario": { "type": "string" }, "email_destinatario": { "type": "string" }, "logradouro_destinatario": { "type": "string", "maxLength": 60 }, "numero_destinatario": { "type": "string", "maxLength": 60 }, "complemento_destinatario": { "type": "string", "maxLength": 60 }, "bairro_destinatario": { "type": "string", "maxLength": 60 }, "municipio_destinatario": { "type": "string", "description": "Nome do município. Com uf_destinatario, o código IBGE é resolvido pela tabela oficial; se não resolver, mande codigo_municipio_destinatario." }, "codigo_municipio_destinatario": { "type": "string", "pattern": "^[0-9]{7}$" }, "uf_destinatario": { "type": "string", "pattern": "^[A-Z]{2}$" }, "cep_destinatario": { "type": "string" }, "telefone_destinatario": { "type": "string" }, "notas_referenciadas": { "type": "array", "items": { "type": "object", "properties": { "chave_nfe": { "type": "string", "pattern": "^[0-9]{44}$" } } } }, "cnpjs_autorizados_xml": { "type": "array", "items": { "type": "string" }, "description": "Quem pode baixar o XML na SEFAZ (contador). Na Bahia a NF-e exige o grupo: sem ele o serviço informa o CNPJ da própria SEFAZ-BA." }, "informacoes_adicionais_contribuinte": { "type": "string", "maxLength": 5000 }, "valor_troco": { "type": "number" }, "items": { "type": "array", "minItems": 1, "maxItems": 990, "items": { "type": "object", "required": [ "descricao", "codigo_ncm", "cfop", "quantidade_comercial", "valor_unitario_comercial", "icms_situacao_tributaria" ], "properties": { "codigo_produto": { "type": "string", "maxLength": 60 }, "descricao": { "type": "string", "maxLength": 120 }, "codigo_ncm": { "type": "string", "pattern": "^[0-9]{8}$" }, "cest": { "type": "string", "pattern": "^[0-9]{7}$" }, "cfop": { "type": "string", "pattern": "^[0-9]{4}$", "description": "NFC-e só aceita 5101, 5102, 5103, 5104, 5115, 5405, 5656, 5667, 5910 e 5933, e o CSOSN tem de combinar (102/103/300/400/900 com 5101 a 5115 e 5910; 500 com 5405, 5656, 5667 e 5910). Fora disso a recusa vem ANTES de numerar." }, "unidade_comercial": { "type": "string", "maxLength": 6, "default": "UN" }, "quantidade_comercial": { "type": "number", "exclusiveMinimum": 0 }, "valor_unitario_comercial": { "type": "number", "exclusiveMinimum": 0 }, "valor_bruto": { "type": "number", "description": "Quantidade x valor unitário (tolerância de R$ 0,01). Desconto vai em valor_desconto, nunca aqui." }, "valor_desconto": { "type": "number", "default": 0 }, "codigo_ean": { "type": "string", "description": "GTIN de 8, 12, 13 ou 14 dígitos com dígito válido, ou \"SEM GTIN\". GTIN inválido vira \"SEM GTIN\"." }, "inclui_no_total": { "type": "integer", "enum": [ 0, 1 ], "default": 1 }, "icms_origem": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8" ], "default": "0" }, "icms_situacao_tributaria": { "type": "string", "description": "CSOSN no Simples (101, 102, 103, 300, 400, 500, 900) ou CST no regime normal (00, 40, 41, 50, 60, 90)." }, "pis_situacao_tributaria": { "type": "string", "default": "49" }, "cofins_situacao_tributaria": { "type": "string", "default": "49" }, "valor_total_tributos": { "type": "number", "description": "Tributos aproximados do item (Lei 12.741). Opcional." } } } }, "formas_pagamento": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "forma_pagamento", "valor_pagamento" ], "properties": { "forma_pagamento": { "type": "string", "description": "Código tPag: 01 dinheiro, 02 cheque, 03 crédito, 04 débito, 05 crediário, 15 boleto, 17 Pix dinâmico, 20 Pix estático, 90 sem pagamento (não vale em NFC-e), 99 outros." }, "valor_pagamento": { "type": "number" }, "tipo_integracao": { "type": "string", "enum": [ "1", "2" ], "default": "2", "description": "Só para cartão e Pix dinâmico (03, 04, 17): 1 maquininha integrada ao sistema, 2 não integrada." }, "cnpj_credenciadora": { "type": "string", "description": "Só com tipo_integracao 1." }, "bandeira_operadora": { "type": "string" }, "numero_autorizacao": { "type": "string", "maxLength": 20 } } } } } }, "NotaDfe": { "type": "object", "properties": { "ref": { "type": "string" }, "status": { "type": "string", "enum": [ "autorizado", "processando_autorizacao", "erro_autorizacao", "cancelado", "processando_cancelamento", "denegado" ] }, "modelo": { "type": "string", "enum": [ "55", "65" ] }, "serie": { "type": "string" }, "numero": { "type": "string" }, "status_sefaz": { "type": [ "string", "null" ], "description": "cStat da SEFAZ (100 autorizado, 204 duplicidade, 539 número em uso com chave diferente...)." }, "mensagem_sefaz": { "type": [ "string", "null" ] }, "chave_nfe": { "type": [ "string", "null" ], "description": "Prefixo NFe + 44 dígitos, como no contrato de mercado." }, "protocolo": { "type": [ "string", "null" ] }, "data_emissao": { "type": [ "string", "null" ], "format": "date-time" }, "data_autorizacao": { "type": [ "string", "null" ], "format": "date-time" }, "caminho_xml_nota_fiscal": { "type": [ "string", "null" ], "description": "nfeProc (NFe + protNFe): o XML de distribuição que o emitente guarda por 5 anos." }, "qrcode_url": { "type": [ "string", "null" ], "description": "NFC-e: conteúdo EXATO do QR Code do DANFCE. Imprima este texto no QR, sem alterar." }, "url_consulta_nf": { "type": [ "string", "null" ], "description": "NFC-e: endereço de consulta pela chave (urlChave), impresso no DANFCE." }, "protocolo_cancelamento": { "type": [ "string", "null" ] }, "caminho_xml_cancelamento": { "type": [ "string", "null" ] }, "mensagem": { "type": [ "string", "null" ] }, "erros": { "type": [ "array", "null" ], "items": { "type": "object" } } } }, "PedidoEmissao": { "type": "object", "required": [ "tomador", "servico" ], "properties": { "data_emissao": { "type": "string", "format": "date-time", "description": "ISO 8601. Formato brasileiro é recusado. Omita para usar agora.", "examples": [ "2026-09-02T10:00:00" ] }, "optante_simples_nacional": { "type": "boolean", "description": "Omita para usar o do cadastro do emissor." }, "regime_especial_tributacao": { "type": "integer", "minimum": 1, "maximum": 6, "description": "UM dígito, conforme o XSD ABRASF. Omita para usar o do cadastro." }, "prestador": { "type": "object", "properties": { "cnpj": { "type": "string", "description": "Se enviado, precisa ser o CNPJ do emissor do token. Serve de conferência: enviar outro é recusado, para não emitir em nome errado sem perceber." } } }, "tomador": { "type": "object", "required": [ "razao_social", "endereco" ], "properties": { "cpf": { "type": "string", "description": "CPF do tomador, só dígitos. Informe cpf OU cnpj." }, "cnpj": { "type": "string" }, "razao_social": { "type": "string", "maxLength": 150 }, "email": { "type": "string", "format": "email", "maxLength": 80 }, "telefone": { "type": "string", "maxLength": 20 }, "endereco": { "$ref": "#/components/schemas/Endereco" } } }, "servico": { "type": "object", "required": [ "valor_servicos", "item_lista_servico", "discriminacao" ], "properties": { "valor_servicos": { "type": "number", "description": "Ponto decimal e no máximo duas casas. \"1.500,00\" é recusado.", "examples": [ 150 ] }, "aliquota": { "type": "number", "description": "PERCENTUAL, não fração: 2.00 significa dois por cento. Valor abaixo de 1 é recusado como fração mal convertida.", "examples": [ 2 ] }, "iss_retido": { "type": "boolean" }, "item_lista_servico": { "type": "string", "description": "Item da lista da LC 116.", "examples": [ "4.10" ] }, "codigo_tributario_municipio": { "type": "string" }, "codigo_cnae": { "type": "string", "pattern": "^[0-9]{7}$", "description": "Sete dígitos, sem ponto nem hífen. Omita para usar o do cadastro do emissor." }, "ibs_cbs": { "type": "object", "description": "Reforma Tributária: IBS e CBS.\n\nOPCIONAL até 31/12/2026 e EXIGIDO a partir de 01/01/2027 para empresas do\nSimples Nacional (01/10/2026 para quem está fora do Simples). Enquanto for\nopcional, omitir o objeto inteiro é válido e a nota sai como sempre saiu.\n\nÉ TUDO OU NADA: os três códigos juntos, ou nenhum. Um grupo pela metade é\nrecusado no schema do provedor e o RPS já estaria consumido, então a recusa\nacontece aqui, antes de reservar número.\n\nOs códigos podem ficar no cadastro do seu emissor, e aí você não precisa\nmandar em cada nota. O que vier no payload SEMPRE vence o cadastro: um mesmo\nCNPJ pode emitir em atividades com classificação diferente.\n\nQuais códigos usar e enquadramento tributário, e isso é conversa com o seu\ncontador: não escolhemos por você, e não há default.", "required": [ "cst", "classificacao_tributaria", "indicador_operacao" ], "properties": { "cst": { "type": "string", "pattern": "^[0-9]{3}$", "description": "Código de Situação Tributária do IBS e da CBS, 3 dígitos. Anexo VI." }, "classificacao_tributaria": { "type": "string", "pattern": "^[0-9]{6}$", "description": "Código de Classificação Tributária, 6 dígitos. Anexo VI." }, "indicador_operacao": { "type": "string", "pattern": "^[0-9]{6}$", "description": "Código indicador da operação de fornecimento, 6 dígitos. Anexo VIII." }, "indicador_destinatario": { "type": "string", "enum": [ "0", "1" ], "default": "0", "description": "0 quando o destinatário é o próprio tomador da nota; 1 quando não é." }, "uso_consumo_pessoal": { "type": "string", "enum": [ "0", "1" ], "default": "0", "description": "Operação de uso ou consumo pessoal (art. 57). 0 = não, 1 = sim." } } }, "discriminacao": { "type": "string", "minLength": 10, "maxLength": 2000, "description": "Descrição do serviço. MÍNIMO DE 10 CARACTERES: é regra do provedor, não do XSD, e o texto curto é recusado pela prefeitura consumindo RPS. A conta é feita sobre o texto com espaços colapsados: completar o mínimo com espaço ou quebra de linha não passa." } } } } } } }, "paths": { "/health": { "get": { "summary": "Saúde do serviço", "operationId": "saude", "tags": [ "Servico" ], "description": "Única rota sem token. Diz o mínimo de propósito: vigia não precisa de credencial, e o que não se responde não vaza.", "security": [], "responses": { "200": { "description": "No ar", "content": { "application/json": { "schema": { "type": "object", "properties": { "servico": { "type": "string" }, "status": { "type": "string" } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } } } } }, "/v2/nfse": { "post": { "summary": "Emitir NFS-e", "operationId": "emitirNfse", "tags": [ "NFS-e" ], "description": "A `ref` vai na QUERY, não no corpo, e é a chave de idempotência.\n\nToda recusa de validação acontece ANTES de reservar número de RPS. Número\nreservado é número consumido: validar depois deixaria buraco na numeração, e\nburaco na numeração o fisco cobra explicação.", "parameters": [ { "name": "ref", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9._-]{1,64}$" }, "description": "Sua chave da transação. Não pode começar com ponto nem terminar em sufixo de arquivo reservado (.env, .log, .key e afins).", "example": "venda-2026-000123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PedidoEmissao" } } } }, "responses": { "200": { "description": "Autorizada na hora", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaFiscal" } } } }, "202": { "description": "Em processamento. Consulte depois ou espere o webhook. NÃO reenvie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaFiscal" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "402": { "description": "assinatura_suspensa | franquia_excedida | cnpjs_excedidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "assinatura_suspensa": { "value": { "codigo": "assinatura_suspensa", "mensagem": "A assinatura da conta está suspensa, cancelada, ou o período de teste terminou. Emitir em produção fica bloqueado; consultar, XML e PDF das notas já emitidas continuam liberados. Homologação continua liberada." } }, "franquia_excedida": { "value": { "codigo": "franquia_excedida", "mensagem": "A conta atingiu a franquia de notas do mês no plano contratado e o plano não vende nota excedente. Trocar de plano no painel libera na hora. Só acontece em produção." } }, "cnpjs_excedidos": { "value": { "codigo": "cnpjs_excedidos", "mensagem": "A conta tem mais emissores ativos do que o plano inclui e o plano não vende CNPJ adicional. Trocar de plano ou desativar um emissor libera. Só acontece em produção." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "409": { "description": "ref_encerrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "ref_encerrada": { "value": { "codigo": "ref_encerrada", "mensagem": "Esta referência já tem uma nota CANCELADA e não pode ser reutilizada. A nota cancelada continua existindo como documento fiscal: emita a substituta com uma referência NOVA (por exemplo, sufixo -R2)." } } } } } }, "413": { "description": "corpo_excede_limite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "corpo_excede_limite": { "value": { "codigo": "corpo_excede_limite", "mensagem": "Corpo acima de 512 KB." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida | json_invalido | requisicao_invalida | emissor_nao_configurado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } }, "json_invalido": { "value": { "codigo": "json_invalido", "mensagem": "O corpo não é um objeto JSON válido." } }, "requisicao_invalida": { "value": { "codigo": "requisicao_invalida", "mensagem": "O payload foi recusado na validação. O array erros[] traz campo, mensagem e correção. Nada foi transmitido à prefeitura e nenhum RPS foi consumido." } }, "emissor_nao_configurado": { "value": { "codigo": "emissor_nao_configurado", "mensagem": "O emissor do token está sem certificado, sem inscrição municipal, com o certificado vencido ou com o cadastro incompleto. Emissor SUSPENSO não cai aqui: cai em emissor_bloqueado (403)." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } }, "get": { "summary": "Listar NFS-e por período", "operationId": "listarNfse", "tags": [ "NFS-e" ], "description": "Listagem paginada (50 por página) das notas do emissor no ambiente do token, da mais recente para a mais antiga, para conciliar sem consultar ref por ref. Nunca leva payload, XML nem PDF, e não pergunta à prefeitura: nota pendente aparece como está no serviço.", "parameters": [ { "name": "de", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Dia inicial de criação da nota (inclusive), AAAA-MM-DD." }, { "name": "ate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Dia final de criação da nota (inclusive), AAAA-MM-DD." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "autorizado", "processando_autorizacao", "erro_autorizacao", "cancelado", "processando_cancelamento", "denegado" ] }, "description": "Literal público, o mesmo que o GET por ref devolve. processando_autorizacao cobre recebida e processando." }, { "name": "pagina", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "50 por página, da mais recente para a mais antiga." } ], "responses": { "200": { "description": "Página da listagem", "content": { "application/json": { "schema": { "type": "object", "properties": { "documento": { "type": "string", "enum": [ "nfse", "nfe", "nfce" ] }, "ambiente": { "type": "string", "enum": [ "homologacao", "producao" ] }, "pagina": { "type": "integer" }, "paginas": { "type": "integer" }, "total": { "type": "integer" }, "por_pagina": { "type": "integer" }, "notas": { "type": "array", "items": { "type": "object", "description": "Resumo para conciliação, sem payload, XML nem PDF. O documento inteiro está em GET /v2/nfse/{ref}.", "properties": { "ref": { "type": "string" }, "status": { "type": "string", "enum": [ "autorizado", "processando_autorizacao", "erro_autorizacao", "cancelado", "processando_cancelamento", "denegado" ] }, "status_texfiscal": { "type": "string" }, "numero": { "type": [ "string", "null" ] }, "codigo_verificacao": { "type": [ "string", "null" ] }, "serie_rps": { "type": [ "string", "null" ] }, "numero_rps": { "type": [ "integer", "null" ] }, "valor": { "type": [ "number", "null" ] }, "tomador": { "type": [ "string", "null" ] }, "mensagem": { "type": [ "string", "null" ] }, "data_emissao": { "type": [ "string", "null" ] }, "processado_em": { "type": [ "string", "null" ] }, "cancelada_em": { "type": [ "string", "null" ] }, "criado_em": { "type": "string" }, "atualizado_em": { "type": [ "string", "null" ] } } } } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | periodo_invalido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "periodo_invalido": { "value": { "codigo": "periodo_invalido", "mensagem": "Parâmetro de listagem fora do formato: de e ate em AAAA-MM-DD (de não maior que ate), status entre os literais públicos, pagina inteira a partir de 1." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfse/validar": { "post": { "summary": "Validar o payload da NFS-e sem emitir", "operationId": "validarNfse", "tags": [ "NFS-e" ], "description": "Roda a mesma validação da emissão (cadastro do emissor e regras do payload) e PARA antes de reservar RPS, assinar ou falar com a prefeitura. 200 quando passa; 422 requisicao_invalida com os mesmos `erros[]` da emissão quando não passa. Não exige certificado, então serve para homologar a integração antes de o A1 chegar. A prefeitura ainda pode recusar por regra própria dela.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PedidoEmissao" } } } }, "responses": { "200": { "description": "Passou na validação local; nada foi numerado nem transmitido", "content": { "application/json": { "schema": { "type": "object", "properties": { "valido": { "type": "boolean", "enum": [ true ] }, "documento": { "type": "string", "enum": [ "nfse", "nfe", "nfce" ] }, "ambiente": { "type": "string" }, "mensagem": { "type": "string" } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | json_invalido | requisicao_invalida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "json_invalido": { "value": { "codigo": "json_invalido", "mensagem": "O corpo não é um objeto JSON válido." } }, "requisicao_invalida": { "value": { "codigo": "requisicao_invalida", "mensagem": "O payload foi recusado na validação. O array erros[] traz campo, mensagem e correção. Nada foi transmitido à prefeitura e nenhum RPS foi consumido." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfse/{ref}": { "get": { "summary": "Consultar NFS-e", "operationId": "consultarNfse", "tags": [ "NFS-e" ], "description": "Se a nota estiver em processamento, a consulta PERGUNTA à prefeitura antes de responder: é por isso que consultar resolve e reenviar não.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "responses": { "200": { "description": "Estado atual", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaFiscal" } } } }, "202": { "description": "Sem veredito ainda: a prefeitura não respondeu ou ainda está processando. Consulte de novo ou espere o webhook. NUNCA reenvie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaFiscal" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } }, "delete": { "summary": "Cancelar NFS-e", "operationId": "cancelarNfse", "tags": [ "NFS-e" ], "description": "Só nota autorizada cancela. 202 com processando_cancelamento quando a prefeitura não foi conclusiva: repita o DELETE ou consulte, o serviço confere e resolve.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "justificativa" ], "properties": { "justificativa": { "type": "string", "minLength": 15, "description": "Por que a nota está sendo cancelada. ATENÇÃO: este texto NÃO vai à prefeitura. O padrão ABRASF não tem campo livre para justificativa; ela fica no registro do serviço como prova de auditoria e volta na resposta. Quem declara o motivo ao fisco é o campo `motivo` abaixo.", "examples": [ "Valor do serviço lancado errado na venda 4471." ] }, "motivo": { "type": "integer", "enum": [ 1, 2, 3 ], "default": 1, "description": "Declaração AO FISCO (tsCodigoCancelamentoNfse do ABRASF): 1 erro na emissão, 2 serviço não prestado, 3 erro de assinatura. Opcional; omitido vale 1. Informe o valor correto: 1 e 2 dizem coisas diferentes ao município.", "examples": [ 2 ] } } } } } }, "responses": { "200": { "description": "Cancelada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaFiscal" } } } }, "202": { "description": "Cancelamento em processamento" }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "413": { "description": "corpo_excede_limite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "corpo_excede_limite": { "value": { "codigo": "corpo_excede_limite", "mensagem": "Corpo acima de 512 KB." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida | json_invalido | estado_invalido | justificativa_invalida | motivo_invalido | cancelamento_recusado | emissor_nao_configurado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } }, "json_invalido": { "value": { "codigo": "json_invalido", "mensagem": "O corpo não é um objeto JSON válido." } }, "estado_invalido": { "value": { "codigo": "estado_invalido", "mensagem": "A operação não cabe no estado atual da nota (cancelar nota que não está autorizada, por exemplo)." } }, "justificativa_invalida": { "value": { "codigo": "justificativa_invalida", "mensagem": "A justificativa de cancelamento tem menos de 15 caracteres." } }, "motivo_invalido": { "value": { "codigo": "motivo_invalido", "mensagem": "O campo motivo do cancelamento aceita 1 (erro na emissão), 2 (serviço não prestado) ou 3 (erro de assinatura)." } }, "cancelamento_recusado": { "value": { "codigo": "cancelamento_recusado", "mensagem": "A prefeitura recusou o cancelamento." } }, "emissor_nao_configurado": { "value": { "codigo": "emissor_nao_configurado", "mensagem": "O emissor do token está sem certificado, sem inscrição municipal, com o certificado vencido ou com o cadastro incompleto. Emissor SUSPENSO não cai aqui: cai em emissor_bloqueado (403)." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfse/{ref}/xml": { "get": { "summary": "XML da NFS-e autorizada", "operationId": "baixarXml", "tags": [ "NFS-e" ], "description": "Como a prefeitura devolveu. Exige token, e responde no-store: documento fiscal com CPF do tomador nunca entra em cache.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "responses": { "200": { "description": "XML", "content": { "application/xml": { "schema": { "type": "string" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "nao_encontrado | xml_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } }, "xml_indisponivel": { "value": { "codigo": "xml_indisponivel", "mensagem": "Não há XML autorizado guardado para essa ref." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfse/{ref}/pdf": { "get": { "summary": "DANFSe em PDF", "operationId": "baixarDanfse", "tags": [ "NFS-e" ], "description": "Gerado do XML autorizado. Exige token, então NÃO entregue este endereço ao seu usuário final: ele receberia 401 em JSON. Para mostrar o PDF a quem recebeu a nota, peça um endereço assinado em /v2/nfse/{ref}/pdf/link, que abre sem token e expira.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "responses": { "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "nao_encontrado | danfse_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } }, "danfse_indisponivel": { "value": { "codigo": "danfse_indisponivel", "mensagem": "Não há nota autorizada para essa ref. Situação permanente enquanto a nota não autorizar." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | danfse_falhou | ref_invalida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "danfse_falhou": { "value": { "codigo": "danfse_falhou", "mensagem": "A nota está autorizada mas o DANFSe não pode ser gerado agora. O XML autorizado continua em /xml. Tente o PDF de novo em instantes." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfse/{ref}/pdf/link": { "get": { "summary": "Endereço assinado do PDF da NFS-e, para o cliente final", "operationId": "linkPdfNfse", "tags": [ "NFS-e" ], "description": "Devolve um endereço de curta validade que abre o PDF SEM token, para você entregar ao navegador de quem recebeu a nota (botão de e-mail, tela do cliente, WhatsApp). É a alternativa oficial ao proxy autenticado que cada integrador vinha escrevendo. O endereço vale para UM documento, expira, e não dá acesso a mais nada da conta: quem o tiver antes da expiração abre esse PDF, então entregue apenas ao destinatário da nota. A validade padrão é de 900 segundos e o teto é de 604800 (sete dias). Depois de expirar, o endereço responde uma página dizendo que o link venceu, e não JSON, porque quem lê é uma pessoa. O PDF em si não pode ser exibido dentro de um iframe (frame-ancestors none neste host): abra em aba nova ou ofereça como download.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." }, { "name": "validade", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60, "maximum": 604800, "default": 900 }, "description": "Validade do endereço, em segundos. Fora da faixa, o valor é ajustado ao limite mais próximo, sem erro.", "example": 3600 } ], "responses": { "200": { "description": "Endereço assinado", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Endereço a entregar ao navegador. Abre sem token." }, "expira_em": { "type": "string", "format": "date-time" }, "validade_segundos": { "type": "integer" }, "aviso": { "type": "string" } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida | link_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } }, "link_indisponivel": { "value": { "codigo": "link_indisponivel", "mensagem": "O endereço assinado não pode ser montado agora. O PDF autenticado em /pdf continua funcionando." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfe/{ref}/pdf/link": { "get": { "summary": "Endereço assinado do PDF da NF-e, para o cliente final", "operationId": "linkPdfNfe", "tags": [ "NF-e e NFC-e" ], "description": "Devolve um endereço de curta validade que abre o PDF SEM token, para você entregar ao navegador de quem recebeu a nota (botão de e-mail, tela do cliente, WhatsApp). É a alternativa oficial ao proxy autenticado que cada integrador vinha escrevendo. O endereço vale para UM documento, expira, e não dá acesso a mais nada da conta: quem o tiver antes da expiração abre esse PDF, então entregue apenas ao destinatário da nota. A validade padrão é de 900 segundos e o teto é de 604800 (sete dias). Depois de expirar, o endereço responde uma página dizendo que o link venceu, e não JSON, porque quem lê é uma pessoa. O PDF em si não pode ser exibido dentro de um iframe (frame-ancestors none neste host): abra em aba nova ou ofereça como download.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." }, { "name": "validade", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60, "maximum": 604800, "default": 900 }, "description": "Validade do endereço, em segundos. Fora da faixa, o valor é ajustado ao limite mais próximo, sem erro.", "example": 3600 } ], "responses": { "200": { "description": "Endereço assinado", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Endereço a entregar ao navegador. Abre sem token." }, "expira_em": { "type": "string", "format": "date-time" }, "validade_segundos": { "type": "integer" }, "aviso": { "type": "string" } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida | link_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } }, "link_indisponivel": { "value": { "codigo": "link_indisponivel", "mensagem": "O endereço assinado não pode ser montado agora. O PDF autenticado em /pdf continua funcionando." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfce/{ref}/pdf/link": { "get": { "summary": "Endereço assinado do PDF da NFC-e, para o cliente final", "operationId": "linkPdfNfce", "tags": [ "NF-e e NFC-e" ], "description": "Devolve um endereço de curta validade que abre o PDF SEM token, para você entregar ao navegador de quem recebeu a nota (botão de e-mail, tela do cliente, WhatsApp). É a alternativa oficial ao proxy autenticado que cada integrador vinha escrevendo. O endereço vale para UM documento, expira, e não dá acesso a mais nada da conta: quem o tiver antes da expiração abre esse PDF, então entregue apenas ao destinatário da nota. A validade padrão é de 900 segundos e o teto é de 604800 (sete dias). Depois de expirar, o endereço responde uma página dizendo que o link venceu, e não JSON, porque quem lê é uma pessoa. O PDF em si não pode ser exibido dentro de um iframe (frame-ancestors none neste host): abra em aba nova ou ofereça como download.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." }, { "name": "validade", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60, "maximum": 604800, "default": 900 }, "description": "Validade do endereço, em segundos. Fora da faixa, o valor é ajustado ao limite mais próximo, sem erro.", "example": 3600 } ], "responses": { "200": { "description": "Endereço assinado", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Endereço a entregar ao navegador. Abre sem token." }, "expira_em": { "type": "string", "format": "date-time" }, "validade_segundos": { "type": "integer" }, "aviso": { "type": "string" } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida | link_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } }, "link_indisponivel": { "value": { "codigo": "link_indisponivel", "mensagem": "O endereço assinado não pode ser montado agora. O PDF autenticado em /pdf continua funcionando." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/emissor": { "get": { "summary": "De quem é este token, e o que ele assume por você", "operationId": "consultarEmissor", "tags": [ "Conta" ], "description": "Diz em nome de QUAL CNPJ a nota sairia com este token, e quais valores o\nTexFiscal assume quando o seu payload não manda o campo.\n\nConsulte esta rota ANTES de emitir em sistema multi-inquilino. O caso que ela\nexiste para evitar é concreto: um sistema com vários clientes e UM token no\nambiente emite a nota do inquilino B com o CNPJ do inquilino A. A nota sai\nAUTORIZADA, em nome de quem não prestou o serviço, e o erro só aparece na\napuração do contador.\n\nO bloco `padroes` traz o que vem do CADASTRO do emissor. Seu payload sempre\nvence: mande o campo e o cadastro é ignorado; omita e o cadastro entra.\nAssim um cliente com o cadastro completo emite mandando só tomador, valor e\ndiscriminação.", "responses": { "200": { "description": "Dados do emissor do token", "content": { "application/json": { "schema": { "type": "object", "properties": { "cnpj": { "type": "string", "description": "CNPJ em nome de quem a nota sai. Compare com o do seu inquilino ANTES de emitir." }, "nome": { "type": "string" }, "inscricao_municipal": { "type": "string" }, "inscricao_estadual": { "type": "string" }, "codigo_municipio": { "type": "string", "description": "Código IBGE de sete dígitos." }, "municipio_nome": { "type": "string" }, "uf": { "type": "string" }, "ambiente": { "type": "string", "enum": [ "producao", "homologacao" ], "description": "Vem do HOST apresentado, não do token." }, "situacao": { "type": "string", "description": "Situação do contrato do emissor." }, "serie_rps": { "type": "string", "description": "Série usada na numeração. O número é reservado pelo TexFiscal e devolvido em numero_rps." }, "endereco": { "type": "object", "properties": { "logradouro": { "type": "string" }, "numero": { "type": "string" }, "complemento": { "type": "string" }, "bairro": { "type": "string" }, "cep": { "type": "string" } } }, "padroes": { "type": "object", "description": "O que o cadastro preenche quando o payload omite. O payload sempre vence.", "properties": { "item_lista_servico": { "type": "string" }, "codigo_tributario_municipio": { "type": "string" }, "codigo_cnae": { "type": "string" }, "codigo_nbs": { "type": "string" }, "aliquota": { "type": "number", "nullable": true, "description": "Percentual, nunca fração: 2.00 é dois por cento." }, "optante_simples_nacional": { "type": "boolean" }, "regime_especial_tributacao": { "type": "integer" }, "discriminacao": { "type": "string" } } } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/uso": { "get": { "summary": "Uso do mês", "operationId": "consultarUso", "tags": [ "Conta" ], "description": "Quantidade e valor por status no mês, no ambiente do token. O campo `total` soma TODOS os status, inclusive os que falharam, então ele não é o valor da fatura: quem responde por isso é `cobravel`, que aplica o mesmo critério do fechamento (nota que recebeu número da prefeitura, em produção). Em homologação `cobravel` é sempre 0, porque nada ali é cobrado.", "parameters": [ { "name": "mes", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$" }, "example": "2026-09" } ], "responses": { "200": { "description": "Uso do mês", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsoMensal" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | mes_invalido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "mes_invalido": { "value": { "codigo": "mes_invalido", "mensagem": "O parâmetro mês não está em AAAA-MM." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/hooks": { "get": { "summary": "Webhook cadastrado para o emissor no ambiente do token", "operationId": "listarHooks", "tags": [ "Webhook" ], "description": "Lista o webhook do emissor no ambiente do token (há no máximo um por ambiente), ativo ou desligado. O segredo nunca volta aqui: ele só aparece na resposta do POST.", "responses": { "200": { "description": "Lista com zero ou um webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "ambiente": { "type": "string" }, "hooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "ambiente": { "type": "string", "enum": [ "homologacao", "producao" ] }, "ativo": { "type": "boolean" }, "criado_em": { "type": [ "string", "null" ] }, "atualizado_em": { "type": [ "string", "null" ] } } } } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } }, "post": { "summary": "Cadastrar ou substituir o webhook", "operationId": "definirHook", "tags": [ "Webhook" ], "description": "Cadastra a URL que recebe os eventos do emissor neste ambiente. Só https, sem usuário embutido e sem endereço interno.\nA resposta 201 traz o `segredo` UMA vez: guarde-o, ele vai em X-Webhook-Token em cada aviso e assina o corpo em X-TexFiscal-Assinatura.\nJá existe um ativo: 409 webhook_ja_cadastrado. Repita com `substituir: true` para trocar a URL, sabendo que o segredo é rotacionado e o seu receptor precisa adotar o novo.\nÉ o mesmo cadastro do painel (Webhooks) e do console: quem integra pela API não precisa de acesso ao painel.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://erp.exemplo.com.br/api/webhook-texfiscal" }, "substituir": { "type": "boolean", "default": false, "description": "true para trocar um webhook ativo; rotaciona o segredo." } } } } } }, "responses": { "201": { "description": "Webhook cadastrado; o segredo só aparece aqui", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "ambiente": { "type": "string", "enum": [ "homologacao", "producao" ] }, "ativo": { "type": "boolean" }, "criado_em": { "type": [ "string", "null" ] }, "atualizado_em": { "type": [ "string", "null" ] } } }, { "type": "object", "properties": { "segredo": { "type": "string" }, "mensagem": { "type": "string" } } } ] } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "409": { "description": "webhook_ja_cadastrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "webhook_ja_cadastrado": { "value": { "codigo": "webhook_ja_cadastrado", "mensagem": "Já existe um webhook ativo para este emissor neste ambiente. Repita com \"substituir\": true para trocar a URL: isso ROTACIONA o segredo e o seu receptor precisa adotar o novo." } } } } } }, "422": { "description": "servico_indisponivel | json_invalido | webhook_url_invalida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "json_invalido": { "value": { "codigo": "json_invalido", "mensagem": "O corpo não é um objeto JSON válido." } }, "webhook_url_invalida": { "value": { "codigo": "webhook_url_invalida", "mensagem": "A URL do webhook precisa ser https, sem usuário embutido, e não pode apontar para endereço local ou privado." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/hooks/{id}": { "delete": { "summary": "Desligar o webhook", "operationId": "desativarHook", "tags": [ "Webhook" ], "description": "Desliga o webhook do emissor. As entregas pendentes dele são encerradas sem envio; as notas continuam consultáveis por GET. Cadastrar de novo gera outro segredo.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "O id devolvido pelo GET ou pelo POST." } ], "responses": { "200": { "description": "Desligado", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "ativo": { "type": "boolean" }, "mensagem": { "type": "string" } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/municipios": { "get": { "summary": "Municípios atendidos, com a data em que cada um foi verificado", "operationId": "listarMunicipios", "tags": [ "Cobertura" ], "description": "Cobertura MEDIDA, não afirmada: cada município da lista teve o webservice da\nprefeitura consultado e o padrão conferido, e a resposta traz a data dessa\nverificação. Consulte antes de prometer emissão ao seu cliente.\n\nMunicípio ausente da lista não é necessariamente município impossível: é\nmunicípio que não verificamos ou que usa um provedor para o qual ainda não há\ndriver. Pergunte.", "security": [], "parameters": [ { "name": "uf", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "description": "Filtra por UF." }, { "name": "codigo_ibge", "in": "query", "schema": { "type": "string", "pattern": "^[0-9]{7}$" }, "description": "Pergunta por um município específico." } ], "responses": { "200": { "description": "Lista verificada", "content": { "application/json": { "schema": { "type": "object", "properties": { "verificado_em": { "type": "string", "format": "date" }, "total": { "type": "integer" }, "municipios": { "type": "array", "items": { "type": "object", "properties": { "codigo_ibge": { "type": "string" }, "nome": { "type": "string" }, "uf": { "type": "string" }, "provedor": { "type": "string" }, "padrao": { "type": "string" }, "driver": { "type": "string" }, "verificado_em": { "type": "string", "format": "date" } } } } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "cobertura_indisponivel | servico_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "cobertura_indisponivel": { "value": { "codigo": "cobertura_indisponivel", "mensagem": "A lista de cidades atendidas não pode ser lida agora." } }, "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } } } } }, "/v2/nfce": { "post": { "summary": "Emitir NFC-e", "operationId": "emitirNfce", "tags": [ "NF-e e NFC-e" ], "description": "Modelo 65, transmitida de forma síncrona à SEFAZ da UF do emissor. A `ref` vai na\nQUERY e é a chave de idempotência: repetir com a mesma ref devolve a nota que existe.\n\nToda recusa de validação (CFOP, CSOSN, GTIN, pagamento menor que o total, valor bruto\ndiferente de quantidade x unitário) acontece ANTES de numerar. A nota recusada pela SEFAZ\nvolta 422 com `status_sefaz` e `mensagem_sefaz`, e pode ser reenviada com a MESMA ref\n(mesmo número, mesma chave) depois de corrigida; número DENEGADO não volta.\n\nSem desfecho (SEFAZ fora do ar, timeout) a resposta é 202: NUNCA reenvie, consulte.\nA NFC-e exige CSC cadastrado no emissor (produção) e só aceita CFOP de venda a consumidor.", "parameters": [ { "name": "ref", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9._-]{1,64}$" }, "description": "Sua chave da transação. Uma ref por documento; nota cancelada não reaproveita a ref.", "example": "venda-2026-000123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PedidoDfe" } } } }, "responses": { "200": { "description": "Autorizada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "202": { "description": "Sem desfecho: a SEFAZ não concluiu. Consulte GET /v2/nfce/{ref}. NÃO reenvie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "402": { "description": "assinatura_suspensa | franquia_excedida | cnpjs_excedidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "assinatura_suspensa": { "value": { "codigo": "assinatura_suspensa", "mensagem": "A assinatura da conta está suspensa, cancelada, ou o período de teste terminou. Emitir em produção fica bloqueado; consultar, XML e PDF das notas já emitidas continuam liberados. Homologação continua liberada." } }, "franquia_excedida": { "value": { "codigo": "franquia_excedida", "mensagem": "A conta atingiu a franquia de notas do mês no plano contratado e o plano não vende nota excedente. Trocar de plano no painel libera na hora. Só acontece em produção." } }, "cnpjs_excedidos": { "value": { "codigo": "cnpjs_excedidos", "mensagem": "A conta tem mais emissores ativos do que o plano inclui e o plano não vende CNPJ adicional. Trocar de plano ou desativar um emissor libera. Só acontece em produção." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "409": { "description": "ref_encerrada | numero_em_uso | numero_denegado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "ref_encerrada": { "value": { "codigo": "ref_encerrada", "mensagem": "Esta referência já tem uma nota CANCELADA e não pode ser reutilizada. A nota cancelada continua existindo como documento fiscal: emita a substituta com uma referência NOVA (por exemplo, sufixo -R2)." } }, "numero_em_uso": { "value": { "codigo": "numero_em_uso", "mensagem": "A série e o número informados já pertencem a outra ref deste emissor (autorizada, pendente ou cancelada). O corpo traz `ref_existente`, `status_existente` e `documento` (a mesma representação do GET por ref): se o status for autorizado, ADOTE esse documento em vez de emitir de novo. É o que acontece quando a resposta da primeira tentativa se perdeu na rede." } }, "numero_denegado": { "value": { "codigo": "numero_denegado", "mensagem": "A SEFAZ DENEGOU o uso deste número: ele foi consumido e não volta. Emita com outro número. A nota denegada fica com status `denegado` e o XML em /xml." } } } } } }, "413": { "description": "corpo_excede_limite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "corpo_excede_limite": { "value": { "codigo": "corpo_excede_limite", "mensagem": "Corpo acima de 512 KB." } } } } } }, "422": { "description": "servico_indisponivel | dfe_nao_habilitado | uf_nao_atendida | ref_invalida | json_invalido | requisicao_invalida | emitente_divergente | emissor_nao_configurado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "dfe_nao_habilitado": { "value": { "codigo": "dfe_nao_habilitado", "mensagem": "O emissor do token não está habilitado para NF-e e NFC-e (só NFS-e). Fale com o suporte para ligar." } }, "uf_nao_atendida": { "value": { "codigo": "uf_nao_atendida", "mensagem": "A emissão desse modelo ainda não atende a UF do emissor. Hoje: Bahia (NF-e na SEFAZ-BA, NFC-e na SVRS)." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } }, "json_invalido": { "value": { "codigo": "json_invalido", "mensagem": "O corpo não é um objeto JSON válido." } }, "requisicao_invalida": { "value": { "codigo": "requisicao_invalida", "mensagem": "O payload foi recusado na validação. O array erros[] traz campo, mensagem e correção. Nada foi transmitido à prefeitura e nenhum RPS foi consumido." } }, "emitente_divergente": { "value": { "codigo": "emitente_divergente", "mensagem": "O cnpj_emitente do payload não é o CNPJ do emissor dono do token. O token de um CNPJ nunca emite por outro." } }, "emissor_nao_configurado": { "value": { "codigo": "emissor_nao_configurado", "mensagem": "O emissor do token está sem certificado, sem inscrição municipal, com o certificado vencido ou com o cadastro incompleto. Emissor SUSPENSO não cai aqui: cai em emissor_bloqueado (403)." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } }, "get": { "summary": "Listar NFC-e por período", "operationId": "listarNfce", "tags": [ "NF-e e NFC-e" ], "description": "Listagem paginada (50 por página) das NFC-e do emissor no ambiente do token, da mais recente para a mais antiga, para conciliar sem consultar ref por ref. Nunca leva payload nem XML, e não pergunta à SEFAZ: nota pendente aparece como está no serviço.", "parameters": [ { "name": "de", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Dia inicial de criação da nota (inclusive), AAAA-MM-DD." }, { "name": "ate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Dia final de criação da nota (inclusive), AAAA-MM-DD." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "autorizado", "processando_autorizacao", "erro_autorizacao", "cancelado", "processando_cancelamento", "denegado" ] }, "description": "Literal público, o mesmo que o GET por ref devolve. processando_autorizacao cobre recebida e processando." }, { "name": "pagina", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "50 por página, da mais recente para a mais antiga." } ], "responses": { "200": { "description": "Página da listagem", "content": { "application/json": { "schema": { "type": "object", "properties": { "documento": { "type": "string", "enum": [ "nfse", "nfe", "nfce" ] }, "ambiente": { "type": "string", "enum": [ "homologacao", "producao" ] }, "pagina": { "type": "integer" }, "paginas": { "type": "integer" }, "total": { "type": "integer" }, "por_pagina": { "type": "integer" }, "notas": { "type": "array", "items": { "type": "object", "description": "Resumo para conciliação, sem payload nem XML. O documento inteiro está em GET /v2/nfce/{ref}.", "properties": { "ref": { "type": "string" }, "status": { "type": "string", "enum": [ "autorizado", "processando_autorizacao", "erro_autorizacao", "cancelado", "processando_cancelamento", "denegado" ] }, "status_texfiscal": { "type": "string" }, "serie": { "type": "integer" }, "numero": { "type": "integer" }, "chave_nfe": { "type": [ "string", "null" ], "description": "Com o prefixo NFe, como no XML." }, "status_sefaz": { "type": [ "string", "null" ] }, "mensagem_sefaz": { "type": [ "string", "null" ] }, "protocolo": { "type": [ "string", "null" ] }, "valor": { "type": [ "number", "null" ] }, "destinatario": { "type": [ "string", "null" ] }, "data_emissao": { "type": [ "string", "null" ] }, "autorizada_em": { "type": [ "string", "null" ] }, "cancelada_em": { "type": [ "string", "null" ] }, "criado_em": { "type": "string" }, "atualizado_em": { "type": [ "string", "null" ] } } } } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | periodo_invalido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "periodo_invalido": { "value": { "codigo": "periodo_invalido", "mensagem": "Parâmetro de listagem fora do formato: de e ate em AAAA-MM-DD (de não maior que ate), status entre os literais públicos, pagina inteira a partir de 1." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfce/validar": { "post": { "summary": "Validar o payload da NFC-e sem emitir", "operationId": "validarNfce", "tags": [ "NF-e e NFC-e" ], "description": "Roda a mesma validação da emissão (habilitação, UF, cadastro do emissor, CFOP, CSOSN, GTIN, pagamentos, totais) e PARA antes de numerar, assinar e transmitir. 200 quando passa; 422 requisicao_invalida com os mesmos `erros[]` da emissão quando não passa. Não consome número da série nem toca a SEFAZ, que ainda pode recusar por regra própria dela.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PedidoDfe" } } } }, "responses": { "200": { "description": "Passou na validação local; nada foi numerado nem transmitido", "content": { "application/json": { "schema": { "type": "object", "properties": { "valido": { "type": "boolean", "enum": [ true ] }, "documento": { "type": "string", "enum": [ "nfse", "nfe", "nfce" ] }, "ambiente": { "type": "string" }, "mensagem": { "type": "string" } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | json_invalido | requisicao_invalida | dfe_nao_habilitado | uf_nao_atendida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "json_invalido": { "value": { "codigo": "json_invalido", "mensagem": "O corpo não é um objeto JSON válido." } }, "requisicao_invalida": { "value": { "codigo": "requisicao_invalida", "mensagem": "O payload foi recusado na validação. O array erros[] traz campo, mensagem e correção. Nada foi transmitido à prefeitura e nenhum RPS foi consumido." } }, "dfe_nao_habilitado": { "value": { "codigo": "dfe_nao_habilitado", "mensagem": "O emissor do token não está habilitado para NF-e e NFC-e (só NFS-e). Fale com o suporte para ligar." } }, "uf_nao_atendida": { "value": { "codigo": "uf_nao_atendida", "mensagem": "A emissão desse modelo ainda não atende a UF do emissor. Hoje: Bahia (NF-e na SEFAZ-BA, NFC-e na SVRS)." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfce/{ref}/pdf": { "get": { "summary": "DANFCE em PDF", "operationId": "baixarNfcePdf", "tags": [ "NF-e e NFC-e" ], "description": "Cupom de bobina de 80mm, com a altura ajustada ao número de itens e o QR Code da consulta desenhado. É a representação impressa; o documento fiscal continua sendo o XML.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9._-]{1,64}$" }, "description": "A sua chave da transação, a mesma usada na emissão.", "example": "venda-2026-000123" } ], "responses": { "200": { "description": "PDF do documento", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "danfe_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "danfe_indisponivel": { "value": { "codigo": "danfe_indisponivel", "mensagem": "Não há NF-e ou NFC-e autorizada para essa ref neste emissor e ambiente. Situação permanente enquanto a nota não autorizar." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | danfe_falhou | ref_invalida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "danfe_falhou": { "value": { "codigo": "danfe_falhou", "mensagem": "A nota está autorizada, mas o DANFE não pode ser gerado agora. O XML autorizado continua em /xml. Tente o PDF de novo em instantes." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfce/{ref}": { "get": { "summary": "Consultar NFC-e", "operationId": "consultarNfce", "tags": [ "NF-e e NFC-e" ], "description": "Nota pendente: a consulta pergunta a SEFAZ pela chave (no máximo uma vez a cada 15 s). Nota recusada volta 422 com o motivo da SEFAZ.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "responses": { "200": { "description": "Estado atual", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "202": { "description": "Ainda sem desfecho na SEFAZ. Consulte de novo em instantes. NUNCA reenvie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "422": { "description": "Nota recusada pela SEFAZ (status erro_autorizacao) ou ref inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } }, "delete": { "summary": "Cancelar NFC-e", "operationId": "cancelarNfce", "tags": [ "NF-e e NFC-e" ], "description": "Só nota autorizada cancela. O prazo é da SEFAZ (24 h para NF-e; NFC-e na Bahia, 30 minutos sem circulação da mercadoria): fora dele a resposta é 422 cancelamento_recusado com o cStat. A justificativa (15 a 255 caracteres) VAI à SEFAZ no evento 110111.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "justificativa" ], "properties": { "justificativa": { "type": "string", "minLength": 15, "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Cancelada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "202": { "description": "Cancelamento sem desfecho: consulte ou repita o DELETE." }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida | estado_invalido | justificativa_invalida | cancelamento_recusado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } }, "estado_invalido": { "value": { "codigo": "estado_invalido", "mensagem": "A operação não cabe no estado atual da nota (cancelar nota que não está autorizada, por exemplo)." } }, "justificativa_invalida": { "value": { "codigo": "justificativa_invalida", "mensagem": "A justificativa de cancelamento tem menos de 15 caracteres." } }, "cancelamento_recusado": { "value": { "codigo": "cancelamento_recusado", "mensagem": "A prefeitura recusou o cancelamento." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfce/por-numero/{serie}/{numero}": { "get": { "summary": "Consultar NFC-e por série e número", "operationId": "consultarPorNumeroNfce", "tags": [ "NF-e e NFC-e" ], "description": "Recuperação: devolve a nota deste emissor com a série e o número informados, no ambiente do token,\ncom a mesma representação do GET por ref. Use quando a resposta do POST se perdeu (timeout, rede)\ne o seu sistema não gravou a ref: antes de reenviar o mesmo número, pergunte se ele já existe.\nNota de outro emissor responde 404, igual a número inexistente.", "parameters": [ { "name": "serie", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 999 }, "example": 1 }, { "name": "numero", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 999999999 }, "example": 2012 } ], "responses": { "200": { "description": "Estado atual", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "202": { "description": "Ainda sem desfecho na SEFAZ.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "422": { "description": "Nota recusada pela SEFAZ, ou série e número fora do formato (numero_invalido)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfce/chave/{chave}": { "get": { "summary": "Consultar NFC-e pela chave de acesso", "operationId": "consultarPorChaveNfce", "tags": [ "NF-e e NFC-e" ], "description": "Recuperação pela chave de acesso de 44 posições (a do DANFE e do Id do XML), com ou sem o prefixo NFe e aceitando o CNPJ alfanumérico, escopada ao emissor do token e ao ambiente. Chave de outro emissor responde 404, igual a chave inexistente; chave com dígito verificador errado responde 422 chave_invalida.", "parameters": [ { "name": "chave", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(NFe)?[0-9A-Za-z]{44}$" }, "example": "29260905509541000163650010000020121144422536" } ], "responses": { "200": { "description": "Estado atual", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "202": { "description": "Ainda sem desfecho na SEFAZ.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "422": { "description": "Nota recusada pela SEFAZ, ou chave inválida (chave_invalida)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfce/{ref}.xml": { "get": { "summary": "XML de distribuição (nfeProc) da NFC-e", "operationId": "xmlNfce", "tags": [ "NF-e e NFC-e" ], "description": "NFe assinada + protNFe, exatamente como a SEFAZ autorizou. É o arquivo que o emitente guarda por 5 anos e manda ao contador. Também aceito como /{ref}/xml.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "responses": { "200": { "description": "XML", "content": { "application/xml": { "schema": { "type": "string" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "xml_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "xml_indisponivel": { "value": { "codigo": "xml_indisponivel", "mensagem": "Não há XML autorizado guardado para essa ref." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfce/{ref}/cancelamento.xml": { "get": { "summary": "XML do evento de cancelamento da NFC-e", "operationId": "xmlCancelamentoNfce", "tags": [ "NF-e e NFC-e" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "responses": { "200": { "description": "procEventoNFe", "content": { "application/xml": { "schema": { "type": "string" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "xml_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "xml_indisponivel": { "value": { "codigo": "xml_indisponivel", "mensagem": "Não há XML autorizado guardado para essa ref." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfce/inutilizacoes": { "get": { "summary": "Inutilizações registradas da NFC-e", "operationId": "inutilizacoesNfce", "tags": [ "NF-e e NFC-e" ], "description": "Cada pedido de inutilização do emissor neste ambiente (homologado ou recusado), mais recente primeiro. Desde 22/09/2026 o procInutNFe é guardado e entra no ZIP do mês do painel.", "responses": { "200": { "description": "Lista", "content": { "application/json": { "schema": { "type": "object", "properties": { "inutilizacoes": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "status_sefaz": { "type": "string" }, "mensagem_sefaz": { "type": "string" }, "protocolo": { "type": "string", "nullable": true }, "modelo": { "type": "string" }, "serie": { "type": "string" }, "numero_inicial": { "type": "string" }, "numero_final": { "type": "string" }, "justificativa": { "type": "string" }, "inutilizacao_id": { "type": "integer" }, "registrada_em": { "type": "string" } } } } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfce/inutilizacao": { "post": { "summary": "Inutilizar faixa de numeração da NFC-e", "operationId": "inutilizarNfce", "tags": [ "NF-e e NFC-e" ], "description": "Declara à SEFAZ que os números de numero_inicial a numero_final da série não serão usados. Faixa com número já usado é recusada antes de ir à SEFAZ.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "serie", "numero_inicial", "numero_final", "justificativa" ], "properties": { "cnpj": { "type": "string", "description": "Opcional; se vier tem de ser o do emissor." }, "serie": { "type": "integer" }, "numero_inicial": { "type": "integer" }, "numero_final": { "type": "integer" }, "justificativa": { "type": "string", "minLength": 15, "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Homologada (cStat 102)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "status_sefaz": { "type": "string" }, "mensagem_sefaz": { "type": "string" }, "protocolo": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | json_invalido | requisicao_invalida | emitente_divergente | numero_usado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "json_invalido": { "value": { "codigo": "json_invalido", "mensagem": "O corpo não é um objeto JSON válido." } }, "requisicao_invalida": { "value": { "codigo": "requisicao_invalida", "mensagem": "O payload foi recusado na validação. O array erros[] traz campo, mensagem e correção. Nada foi transmitido à prefeitura e nenhum RPS foi consumido." } }, "emitente_divergente": { "value": { "codigo": "emitente_divergente", "mensagem": "O cnpj_emitente do payload não é o CNPJ do emissor dono do token. O token de um CNPJ nunca emite por outro." } }, "numero_usado": { "value": { "codigo": "numero_usado", "mensagem": "A faixa a inutilizar contém número de nota autorizada, pendente ou cancelada." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfe": { "post": { "summary": "Emitir NF-e", "operationId": "emitirNfe", "tags": [ "NF-e e NFC-e" ], "description": "Modelo 55, transmitida de forma síncrona à SEFAZ da UF do emissor. A `ref` vai na\nQUERY e é a chave de idempotência: repetir com a mesma ref devolve a nota que existe.\n\nToda recusa de validação (CFOP, CSOSN, GTIN, pagamento menor que o total, valor bruto\ndiferente de quantidade x unitário) acontece ANTES de numerar. A nota recusada pela SEFAZ\nvolta 422 com `status_sefaz` e `mensagem_sefaz`, e pode ser reenviada com a MESMA ref\n(mesmo número, mesma chave) depois de corrigida; número DENEGADO não volta.\n\nSem desfecho (SEFAZ fora do ar, timeout) a resposta é 202: NUNCA reenvie, consulte.\nA NF-e exige destinatário identificado com endereço completo.", "parameters": [ { "name": "ref", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9._-]{1,64}$" }, "description": "Sua chave da transação. Uma ref por documento; nota cancelada não reaproveita a ref.", "example": "venda-2026-000123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PedidoDfe" } } } }, "responses": { "200": { "description": "Autorizada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "202": { "description": "Sem desfecho: a SEFAZ não concluiu. Consulte GET /v2/nfe/{ref}. NÃO reenvie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "402": { "description": "assinatura_suspensa | franquia_excedida | cnpjs_excedidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "assinatura_suspensa": { "value": { "codigo": "assinatura_suspensa", "mensagem": "A assinatura da conta está suspensa, cancelada, ou o período de teste terminou. Emitir em produção fica bloqueado; consultar, XML e PDF das notas já emitidas continuam liberados. Homologação continua liberada." } }, "franquia_excedida": { "value": { "codigo": "franquia_excedida", "mensagem": "A conta atingiu a franquia de notas do mês no plano contratado e o plano não vende nota excedente. Trocar de plano no painel libera na hora. Só acontece em produção." } }, "cnpjs_excedidos": { "value": { "codigo": "cnpjs_excedidos", "mensagem": "A conta tem mais emissores ativos do que o plano inclui e o plano não vende CNPJ adicional. Trocar de plano ou desativar um emissor libera. Só acontece em produção." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "409": { "description": "ref_encerrada | numero_em_uso | numero_denegado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "ref_encerrada": { "value": { "codigo": "ref_encerrada", "mensagem": "Esta referência já tem uma nota CANCELADA e não pode ser reutilizada. A nota cancelada continua existindo como documento fiscal: emita a substituta com uma referência NOVA (por exemplo, sufixo -R2)." } }, "numero_em_uso": { "value": { "codigo": "numero_em_uso", "mensagem": "A série e o número informados já pertencem a outra ref deste emissor (autorizada, pendente ou cancelada). O corpo traz `ref_existente`, `status_existente` e `documento` (a mesma representação do GET por ref): se o status for autorizado, ADOTE esse documento em vez de emitir de novo. É o que acontece quando a resposta da primeira tentativa se perdeu na rede." } }, "numero_denegado": { "value": { "codigo": "numero_denegado", "mensagem": "A SEFAZ DENEGOU o uso deste número: ele foi consumido e não volta. Emita com outro número. A nota denegada fica com status `denegado` e o XML em /xml." } } } } } }, "413": { "description": "corpo_excede_limite", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "corpo_excede_limite": { "value": { "codigo": "corpo_excede_limite", "mensagem": "Corpo acima de 512 KB." } } } } } }, "422": { "description": "servico_indisponivel | dfe_nao_habilitado | uf_nao_atendida | ref_invalida | json_invalido | requisicao_invalida | emitente_divergente | emissor_nao_configurado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "dfe_nao_habilitado": { "value": { "codigo": "dfe_nao_habilitado", "mensagem": "O emissor do token não está habilitado para NF-e e NFC-e (só NFS-e). Fale com o suporte para ligar." } }, "uf_nao_atendida": { "value": { "codigo": "uf_nao_atendida", "mensagem": "A emissão desse modelo ainda não atende a UF do emissor. Hoje: Bahia (NF-e na SEFAZ-BA, NFC-e na SVRS)." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } }, "json_invalido": { "value": { "codigo": "json_invalido", "mensagem": "O corpo não é um objeto JSON válido." } }, "requisicao_invalida": { "value": { "codigo": "requisicao_invalida", "mensagem": "O payload foi recusado na validação. O array erros[] traz campo, mensagem e correção. Nada foi transmitido à prefeitura e nenhum RPS foi consumido." } }, "emitente_divergente": { "value": { "codigo": "emitente_divergente", "mensagem": "O cnpj_emitente do payload não é o CNPJ do emissor dono do token. O token de um CNPJ nunca emite por outro." } }, "emissor_nao_configurado": { "value": { "codigo": "emissor_nao_configurado", "mensagem": "O emissor do token está sem certificado, sem inscrição municipal, com o certificado vencido ou com o cadastro incompleto. Emissor SUSPENSO não cai aqui: cai em emissor_bloqueado (403)." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } }, "get": { "summary": "Listar NF-e por período", "operationId": "listarNfe", "tags": [ "NF-e e NFC-e" ], "description": "Listagem paginada (50 por página) das NF-e do emissor no ambiente do token, da mais recente para a mais antiga, para conciliar sem consultar ref por ref. Nunca leva payload nem XML, e não pergunta à SEFAZ: nota pendente aparece como está no serviço.", "parameters": [ { "name": "de", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Dia inicial de criação da nota (inclusive), AAAA-MM-DD." }, { "name": "ate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Dia final de criação da nota (inclusive), AAAA-MM-DD." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "autorizado", "processando_autorizacao", "erro_autorizacao", "cancelado", "processando_cancelamento", "denegado" ] }, "description": "Literal público, o mesmo que o GET por ref devolve. processando_autorizacao cobre recebida e processando." }, { "name": "pagina", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "50 por página, da mais recente para a mais antiga." } ], "responses": { "200": { "description": "Página da listagem", "content": { "application/json": { "schema": { "type": "object", "properties": { "documento": { "type": "string", "enum": [ "nfse", "nfe", "nfce" ] }, "ambiente": { "type": "string", "enum": [ "homologacao", "producao" ] }, "pagina": { "type": "integer" }, "paginas": { "type": "integer" }, "total": { "type": "integer" }, "por_pagina": { "type": "integer" }, "notas": { "type": "array", "items": { "type": "object", "description": "Resumo para conciliação, sem payload nem XML. O documento inteiro está em GET /v2/nfe/{ref}.", "properties": { "ref": { "type": "string" }, "status": { "type": "string", "enum": [ "autorizado", "processando_autorizacao", "erro_autorizacao", "cancelado", "processando_cancelamento", "denegado" ] }, "status_texfiscal": { "type": "string" }, "serie": { "type": "integer" }, "numero": { "type": "integer" }, "chave_nfe": { "type": [ "string", "null" ], "description": "Com o prefixo NFe, como no XML." }, "status_sefaz": { "type": [ "string", "null" ] }, "mensagem_sefaz": { "type": [ "string", "null" ] }, "protocolo": { "type": [ "string", "null" ] }, "valor": { "type": [ "number", "null" ] }, "destinatario": { "type": [ "string", "null" ] }, "data_emissao": { "type": [ "string", "null" ] }, "autorizada_em": { "type": [ "string", "null" ] }, "cancelada_em": { "type": [ "string", "null" ] }, "criado_em": { "type": "string" }, "atualizado_em": { "type": [ "string", "null" ] } } } } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | periodo_invalido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "periodo_invalido": { "value": { "codigo": "periodo_invalido", "mensagem": "Parâmetro de listagem fora do formato: de e ate em AAAA-MM-DD (de não maior que ate), status entre os literais públicos, pagina inteira a partir de 1." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfe/validar": { "post": { "summary": "Validar o payload da NF-e sem emitir", "operationId": "validarNfe", "tags": [ "NF-e e NFC-e" ], "description": "Roda a mesma validação da emissão (habilitação, UF, cadastro do emissor, CFOP, CSOSN, GTIN, pagamentos, totais) e PARA antes de numerar, assinar e transmitir. 200 quando passa; 422 requisicao_invalida com os mesmos `erros[]` da emissão quando não passa. Não consome número da série nem toca a SEFAZ, que ainda pode recusar por regra própria dela.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PedidoDfe" } } } }, "responses": { "200": { "description": "Passou na validação local; nada foi numerado nem transmitido", "content": { "application/json": { "schema": { "type": "object", "properties": { "valido": { "type": "boolean", "enum": [ true ] }, "documento": { "type": "string", "enum": [ "nfse", "nfe", "nfce" ] }, "ambiente": { "type": "string" }, "mensagem": { "type": "string" } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | json_invalido | requisicao_invalida | dfe_nao_habilitado | uf_nao_atendida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "json_invalido": { "value": { "codigo": "json_invalido", "mensagem": "O corpo não é um objeto JSON válido." } }, "requisicao_invalida": { "value": { "codigo": "requisicao_invalida", "mensagem": "O payload foi recusado na validação. O array erros[] traz campo, mensagem e correção. Nada foi transmitido à prefeitura e nenhum RPS foi consumido." } }, "dfe_nao_habilitado": { "value": { "codigo": "dfe_nao_habilitado", "mensagem": "O emissor do token não está habilitado para NF-e e NFC-e (só NFS-e). Fale com o suporte para ligar." } }, "uf_nao_atendida": { "value": { "codigo": "uf_nao_atendida", "mensagem": "A emissão desse modelo ainda não atende a UF do emissor. Hoje: Bahia (NF-e na SEFAZ-BA, NFC-e na SVRS)." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfe/{ref}/pdf": { "get": { "summary": "DANFE em PDF", "operationId": "baixarNfePdf", "tags": [ "NF-e e NFC-e" ], "description": "Folha A4 em retrato. É a representação impressa; o documento fiscal continua sendo o XML. Não é um layout homologado pela SEFAZ: cumpre a função (identificar a nota e permitir a consulta pela chave) com os campos obrigatórios presentes.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9._-]{1,64}$" }, "description": "A sua chave da transação, a mesma usada na emissão.", "example": "venda-2026-000123" } ], "responses": { "200": { "description": "PDF do documento", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "danfe_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "danfe_indisponivel": { "value": { "codigo": "danfe_indisponivel", "mensagem": "Não há NF-e ou NFC-e autorizada para essa ref neste emissor e ambiente. Situação permanente enquanto a nota não autorizar." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | danfe_falhou | ref_invalida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "danfe_falhou": { "value": { "codigo": "danfe_falhou", "mensagem": "A nota está autorizada, mas o DANFE não pode ser gerado agora. O XML autorizado continua em /xml. Tente o PDF de novo em instantes." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfe/{ref}": { "get": { "summary": "Consultar NF-e", "operationId": "consultarNfe", "tags": [ "NF-e e NFC-e" ], "description": "Nota pendente: a consulta pergunta a SEFAZ pela chave (no máximo uma vez a cada 15 s). Nota recusada volta 422 com o motivo da SEFAZ.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "responses": { "200": { "description": "Estado atual", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "202": { "description": "Ainda sem desfecho na SEFAZ. Consulte de novo em instantes. NUNCA reenvie.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "422": { "description": "Nota recusada pela SEFAZ (status erro_autorizacao) ou ref inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } }, "delete": { "summary": "Cancelar NF-e", "operationId": "cancelarNfe", "tags": [ "NF-e e NFC-e" ], "description": "Só nota autorizada cancela. O prazo é da SEFAZ (24 h para NF-e; NFC-e na Bahia, 30 minutos sem circulação da mercadoria): fora dele a resposta é 422 cancelamento_recusado com o cStat. A justificativa (15 a 255 caracteres) VAI à SEFAZ no evento 110111.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "justificativa" ], "properties": { "justificativa": { "type": "string", "minLength": 15, "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Cancelada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "202": { "description": "Cancelamento sem desfecho: consulte ou repita o DELETE." }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida | estado_invalido | justificativa_invalida | cancelamento_recusado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } }, "estado_invalido": { "value": { "codigo": "estado_invalido", "mensagem": "A operação não cabe no estado atual da nota (cancelar nota que não está autorizada, por exemplo)." } }, "justificativa_invalida": { "value": { "codigo": "justificativa_invalida", "mensagem": "A justificativa de cancelamento tem menos de 15 caracteres." } }, "cancelamento_recusado": { "value": { "codigo": "cancelamento_recusado", "mensagem": "A prefeitura recusou o cancelamento." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfe/por-numero/{serie}/{numero}": { "get": { "summary": "Consultar NF-e por série e número", "operationId": "consultarPorNumeroNfe", "tags": [ "NF-e e NFC-e" ], "description": "Recuperação: devolve a nota deste emissor com a série e o número informados, no ambiente do token,\ncom a mesma representação do GET por ref. Use quando a resposta do POST se perdeu (timeout, rede)\ne o seu sistema não gravou a ref: antes de reenviar o mesmo número, pergunte se ele já existe.\nNota de outro emissor responde 404, igual a número inexistente.", "parameters": [ { "name": "serie", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 999 }, "example": 1 }, { "name": "numero", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 999999999 }, "example": 2012 } ], "responses": { "200": { "description": "Estado atual", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "202": { "description": "Ainda sem desfecho na SEFAZ.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "422": { "description": "Nota recusada pela SEFAZ, ou série e número fora do formato (numero_invalido)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfe/chave/{chave}": { "get": { "summary": "Consultar NF-e pela chave de acesso", "operationId": "consultarPorChaveNfe", "tags": [ "NF-e e NFC-e" ], "description": "Recuperação pela chave de acesso de 44 posições (a do DANFE e do Id do XML), com ou sem o prefixo NFe e aceitando o CNPJ alfanumérico, escopada ao emissor do token e ao ambiente. Chave de outro emissor responde 404, igual a chave inexistente; chave com dígito verificador errado responde 422 chave_invalida.", "parameters": [ { "name": "chave", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(NFe)?[0-9A-Za-z]{44}$" }, "example": "29260905509541000163650010000020121144422536" } ], "responses": { "200": { "description": "Estado atual", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "202": { "description": "Ainda sem desfecho na SEFAZ.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "422": { "description": "Nota recusada pela SEFAZ, ou chave inválida (chave_invalida)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaDfe" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfe/{ref}.xml": { "get": { "summary": "XML de distribuição (nfeProc) da NF-e", "operationId": "xmlNfe", "tags": [ "NF-e e NFC-e" ], "description": "NFe assinada + protNFe, exatamente como a SEFAZ autorizou. É o arquivo que o emitente guarda por 5 anos e manda ao contador. Também aceito como /{ref}/xml.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "responses": { "200": { "description": "XML", "content": { "application/xml": { "schema": { "type": "string" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "xml_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "xml_indisponivel": { "value": { "codigo": "xml_indisponivel", "mensagem": "Não há XML autorizado guardado para essa ref." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfe/{ref}/cancelamento.xml": { "get": { "summary": "XML do evento de cancelamento da NF-e", "operationId": "xmlCancelamentoNfe", "tags": [ "NF-e e NFC-e" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "responses": { "200": { "description": "procEventoNFe", "content": { "application/xml": { "schema": { "type": "string" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "xml_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "xml_indisponivel": { "value": { "codigo": "xml_indisponivel", "mensagem": "Não há XML autorizado guardado para essa ref." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfe/inutilizacoes": { "get": { "summary": "Inutilizações registradas da NF-e", "operationId": "inutilizacoesNfe", "tags": [ "NF-e e NFC-e" ], "description": "Cada pedido de inutilização do emissor neste ambiente (homologado ou recusado), mais recente primeiro. Desde 22/09/2026 o procInutNFe é guardado e entra no ZIP do mês do painel.", "responses": { "200": { "description": "Lista", "content": { "application/json": { "schema": { "type": "object", "properties": { "inutilizacoes": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "status_sefaz": { "type": "string" }, "mensagem_sefaz": { "type": "string" }, "protocolo": { "type": "string", "nullable": true }, "modelo": { "type": "string" }, "serie": { "type": "string" }, "numero_inicial": { "type": "string" }, "numero_final": { "type": "string" }, "justificativa": { "type": "string" }, "inutilizacao_id": { "type": "integer" }, "registrada_em": { "type": "string" } } } } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfe/inutilizacao": { "post": { "summary": "Inutilizar faixa de numeração da NF-e", "operationId": "inutilizarNfe", "tags": [ "NF-e e NFC-e" ], "description": "Declara à SEFAZ que os números de numero_inicial a numero_final da série não serão usados. Faixa com número já usado é recusada antes de ir à SEFAZ.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "serie", "numero_inicial", "numero_final", "justificativa" ], "properties": { "cnpj": { "type": "string", "description": "Opcional; se vier tem de ser o do emissor." }, "serie": { "type": "integer" }, "numero_inicial": { "type": "integer" }, "numero_final": { "type": "integer" }, "justificativa": { "type": "string", "minLength": 15, "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Homologada (cStat 102)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "status_sefaz": { "type": "string" }, "mensagem_sefaz": { "type": "string" }, "protocolo": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | json_invalido | requisicao_invalida | emitente_divergente | numero_usado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "json_invalido": { "value": { "codigo": "json_invalido", "mensagem": "O corpo não é um objeto JSON válido." } }, "requisicao_invalida": { "value": { "codigo": "requisicao_invalida", "mensagem": "O payload foi recusado na validação. O array erros[] traz campo, mensagem e correção. Nada foi transmitido à prefeitura e nenhum RPS foi consumido." } }, "emitente_divergente": { "value": { "codigo": "emitente_divergente", "mensagem": "O cnpj_emitente do payload não é o CNPJ do emissor dono do token. O token de um CNPJ nunca emite por outro." } }, "numero_usado": { "value": { "codigo": "numero_usado", "mensagem": "A faixa a inutilizar contém número de nota autorizada, pendente ou cancelada." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfe/{ref}/carta_correcao.xml": { "get": { "summary": "XML (procEventoNFe) de uma carta de correção da NF-e", "operationId": "xmlCartaCorrecaoNfe", "tags": [ "NF-e e NFC-e" ], "description": "A CC-e é documento fiscal de guarda (5 anos). Sem `sequencia` devolve a última registrada. Existe desde 22/09/2026; antes só o texto da correção ficava guardado.", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." }, { "name": "sequencia", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20 } } ], "responses": { "200": { "description": "procEventoNFe", "content": { "application/xml": { "schema": { "type": "string" } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "xml_indisponivel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "xml_indisponivel": { "value": { "codigo": "xml_indisponivel", "mensagem": "Não há XML autorizado guardado para essa ref." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } }, "/v2/nfe/{ref}/carta_correcao": { "get": { "summary": "Cartas de correção registradas da NF-e", "operationId": "cartasCorrecaoNfe", "tags": [ "NF-e e NFC-e" ], "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "responses": { "200": { "description": "Lista por sequência, com o caminho do XML de cada uma", "content": { "application/json": { "schema": { "type": "object", "properties": { "ref": { "type": "string" }, "chave_nfe": { "type": "string" }, "cartas_correcao": { "type": "array", "items": { "type": "object", "properties": { "numero_carta_correcao": { "type": "integer" }, "protocolo": { "type": "string", "nullable": true }, "correcao": { "type": "string" }, "registrada_em": { "type": "string" }, "caminho_xml_carta_correcao": { "type": "string" } } } } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } }, "post": { "summary": "Carta de correção da NF-e", "operationId": "cartaCorrecaoNfe", "tags": [ "NF-e e NFC-e" ], "description": "Evento 110110. Só NF-e autorizada; NFC-e não tem carta de correção. Não corrige valor, quantidade, imposto, remetente, destinatário nem data (regra do Convênio S/N).", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 }, "description": "A mesma ref usada na emissão." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "correcao" ], "properties": { "correcao": { "type": "string", "minLength": 15, "maxLength": 1000 }, "sequencia": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1 } } } } } }, "responses": { "200": { "description": "Registrada (cStat 135/136)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "status_sefaz": { "type": "string" }, "mensagem_sefaz": { "type": "string" }, "protocolo": { "type": [ "string", "null" ] }, "numero_carta_correcao": { "type": "integer" } } } } } }, "401": { "description": "nao_autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_autorizado": { "value": { "codigo": "nao_autorizado", "mensagem": "Token ausente, inválido, ou de um ambiente diferente do endereço chamado." } } } } } }, "403": { "description": "emissor_bloqueado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "emissor_bloqueado": { "value": { "codigo": "emissor_bloqueado", "mensagem": "O contrato do emissor está suspenso, encerrado ou ainda não foi ligado. Emitir e cancelar ficam barrados; CONSULTAR continua liberado, inclusive o XML e o PDF das notas já emitidas." } } } } } }, "404": { "description": "nao_encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "nao_encontrado": { "value": { "codigo": "nao_encontrado", "mensagem": "Não existe nota com essa ref neste emissor e ambiente." } } } } } }, "405": { "description": "metodo_nao_permitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "metodo_nao_permitido": { "value": { "codigo": "metodo_nao_permitido", "mensagem": "Método errado na rota. O cabeçalho Allow diz quais valem." } } } } } }, "422": { "description": "servico_indisponivel | ref_invalida | estado_invalido | correcao_invalida | sequencia_invalida | carta_correcao_recusada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "servico_indisponivel": { "value": { "codigo": "servico_indisponivel", "mensagem": "O serviço não respondeu a tempo ou está fora do ar. O DESFECHO DESTA CHAMADA É DESCONHECIDO: consulte GET /v2/nfse/{a mesma ref} antes de qualquer reenvio, e nunca reenvie com ref nova." } }, "ref_invalida": { "value": { "codigo": "ref_invalida", "mensagem": "A ref não passou na regra: até 64 caracteres entre letras, números, ponto, hífen e sublinhado, sem começar com ponto e sem sufixo de arquivo reservado." } }, "estado_invalido": { "value": { "codigo": "estado_invalido", "mensagem": "A operação não cabe no estado atual da nota (cancelar nota que não está autorizada, por exemplo)." } }, "correcao_invalida": { "value": { "codigo": "correcao_invalida", "mensagem": "O texto da carta de correção precisa de 15 a 1000 caracteres." } }, "sequencia_invalida": { "value": { "codigo": "sequencia_invalida", "mensagem": "A sequência da carta de correção vai de 1 a 20." } }, "carta_correcao_recusada": { "value": { "codigo": "carta_correcao_recusada", "mensagem": "A SEFAZ recusou a carta de correção. status_sefaz e mensagem_sefaz trazem o motivo. Logo depois da autorização a SEFAZ-BA pode responder 494 (chave inexistente) por alguns minutos: repita em instantes." } } } } } }, "429": { "description": "limite_de_requisicoes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "limite_de_requisicoes": { "value": { "codigo": "limite_de_requisicoes", "mensagem": "Acima de 10 requisições por segundo por token (rajada de 40); sem token, 3 por segundo por IP. O cabeçalho Retry-After diz quanto esperar." } } } } } }, "500": { "description": "falha_interna", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "examples": { "falha_interna": { "value": { "codigo": "falha_interna", "mensagem": "Falha não prevista. O incidente foi registrado." } } } } } } } } } }, "webhooks": { "nfse": { "post": { "operationId": "receberEventoNfse", "tags": [ "Webhook" ], "summary": "Evento de mudança de desfecho de uma nota", "description": "Enviado por nós para a URL que você cadastrar, uma por ambiente (no painel ou por POST /v2/hooks).\nVale para NFS-e (nfse_*), NF-e (nfe_*) e NFC-e (nfce_*): o prefixo do evento diz o recurso.\n\nConfira o X-TexFiscal-Assinatura antes de confiar no conteúdo: é o\nHMAC-SHA256 do CORPO CRU com o segredo do seu webhook. Compare com\nhash_equals ou equivalente, nunca com == .\n\nTrês regras do receptor, e a segunda já custou caro em outros\nintegradores:\n1. Responda 2xx rápido. Nosso timeout na tentativa imediata é 5 s.\n2. DESCARTE evento fora de ordem. Uma entrega reagendada pode chegar\n DEPOIS de um evento mais novo da mesma ref: por exemplo, uma\n nfse_autorizada que falhou chegando depois da nfse_cancelada.\n Guarde o ocorrido_em do último evento aplicado por ref e ignore o\n que for mais antigo, senão você marca como autorizada uma nota\n que foi cancelada.\n3. Trate entrega REPETIDA. Reenviamos até 16 vezes enquanto você não\n responder 2xx, e uma entrega pode chegar duas vezes se a sua\n resposta se perder. Deduplique pelo evento_id.", "parameters": [ { "name": "X-TexFiscal-Evento", "in": "header", "required": true, "schema": { "type": "string" }, "description": "O mesmo valor do campo evento." }, { "name": "X-TexFiscal-Tentativa", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Número da tentativa, comecando em 1." }, { "name": "X-TexFiscal-Assinatura", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 do corpo cru, em hexadecimal, com o segredo do seu webhook." }, { "name": "X-Webhook-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "O próprio segredo do webhook, em claro, para o receptor escrito para a Focus continuar funcionando sem mudança. Prefira conferir a assinatura: ela prova o corpo, o token só prova a origem." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/NotaFiscal" }, { "type": "object", "required": [ "evento", "ref", "evento_id", "ocorrido_em" ], "properties": { "evento": { "type": "string", "enum": [ "nfse_autorizada", "nfse_erro", "nfse_cancelada", "nfse_cancelamento_nao_efetivado", "nfe_autorizada", "nfe_erro", "nfe_cancelada", "nfe_denegada", "nfce_autorizada", "nfce_erro", "nfce_cancelada", "nfce_denegada", "teste" ], "description": "nfse_cancelamento_nao_efetivado significa que o cancelamento NÃO valeu na prefeitura e a nota voltou a estar autorizada: é o único que pede ação sua. nfe_denegada e nfce_denegada: a SEFAZ denegou o uso e o número foi consumido (estado final, XML em /xml). teste: disparado pelo botão do painel, corpo sem nota." }, "ref": { "type": "string" }, "evento_id": { "type": "integer", "description": "Único e estável. Use como chave de deduplicação." }, "ocorrido_em": { "type": "string", "format": "date-time", "description": "Quando o evento foi gerado, não quando foi entregue. Use para descartar evento fora de ordem." } } } ] } } } }, "responses": { "200": { "description": "Recebido. Qualquer 2xx serve; nada é reenviado depois disto." }, "500": { "description": "Falha sua. Reenviamos com espera crescente, até 16 vezes." } } } } } }