{ "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` e a chave de idempotencia. 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 relogio ou de um aleatorio.\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\ndependencia 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.seusaude.com" } }, "tags": [ { "name": "NFS-e", "description": "Emitir, consultar, cancelar e baixar o documento." }, { "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": "Servico", "x-displayName": "Serviço", "description": "Saúde do ambiente." } ], "servers": [ { "url": "https://homologacao-nfse.seusaude.com", "description": "Homologação. Vai ao ambiente de teste da prefeitura: a nota NÃO tem valor fiscal. Integre aqui primeiro." }, { "url": "https://nfse.seusaude.com", "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." } }, "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 e de validação de campo.", "items": { "type": "object", "properties": { "codigo": { "type": "string", "description": "Campo que reprovou, ex.: serviço.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 mascara na saída. Mascara na entrada e aceita e normalizada." } } }, "NotaFiscal": { "type": "object", "properties": { "ref": { "type": "string" }, "status": { "type": "string", "enum": [ "autorizado", "processando_autorizacao", "erro_autorizacao", "cancelado", "processando_cancelamento" ] }, "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 e 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" } } } }, "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 conferencia: enviar outro e 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\" e recusado.", "examples": [ 150 ] }, "aliquota": { "type": "number", "description": "PERCENTUAL, não fracao: 2.00 significa dois por cento. Valor abaixo de 1 e recusado como fracao 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 e válido e a nota sai como sempre saiu.\n\nE TUDO OU NADA: os três códigos juntos, ou nenhum. Um grupo pela metade e\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 ai 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 classificacao diferente.\n\nQuais códigos usar e enquadramento tributario, e isso e 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 Classificacao 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 destinatario e o próprio tomador da nota; 1 quando não e." }, "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: e regra do provedor, não do XSD, e o texto curto e recusado pela prefeitura consumindo RPS. A conta e feita sobre o texto com espacos colapsados: completar o mínimo com espaco 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 proposito: 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 cabecalho 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 E 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 requisicoes por segundo por IP." } } } } } } } } }, "/v2/nfse": { "post": { "summary": "Emitir NFS-e", "operationId": "emitirNfse", "tags": [ "NFS-e" ], "description": "A `ref` vai na QUERY, não no corpo, e e a chave de idempotencia.\n\nToda recusa de validação acontece ANTES de reservar número de RPS. Número\nreservado e número consumido: validar depois deixaria buraco na numeracao, e\nburaco na numeracao o fisco cobra explicacao.", "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." } } } } } }, "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 cabecalho 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 E 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 e 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 a 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 requisicoes por segundo por IP." } } } } } }, "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 a prefeitura antes de responder: e 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 cabecalho 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 E 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 requisicoes por segundo por IP." } } } } } }, "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 a 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 e 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 cabecalho 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 E 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 e 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 requisicoes por segundo por IP." } } } } } }, "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 cabecalho 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 E 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 requisicoes por segundo por IP." } } } } } }, "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: não existe link público de documento fiscal aqui. Se você hoje entrega ao seu usuário o link do PDF do integrador, troque por um proxy autenticado no seu servidor.", "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 cabecalho 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 E 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 requisicoes por segundo por IP." } } } } } }, "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 cabecalho 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 E 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 requisicoes por segundo por IP." } } } } } }, "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 e necessariamente município impossível: e\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 cabecalho 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 E 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 requisicoes por segundo por IP." } } } } } } } } } }, "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.\n\nConfira o X-TexFiscal-Assinatura antes de confiar no conteúdo: e 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 e 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." } ], "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" ], "description": "nfse_cancelamento_nao_efetivado significa que o cancelamento NÃO valeu na prefeitura e a nota voltou a estar autorizada: e o único que pede acao sua." }, "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 e reenviado depois disto." }, "500": { "description": "Falha sua. Reenviamos com espera crescente, até 16 vezes." } } } } } }