{ "openapi": "3.0.3", "info": { "title": "LideraNota API", "version": "0.10.0", "description": "API da LideraNota para emissão de NFS-e no padrão nacional. A emissão é assíncrona: o seu sistema envia um lote de notas, recebe na hora o resultado da recepção de cada nota e acompanha o desfecho pelo webhook ou pela consulta da nota. Toda requisição leva o token de acesso no cabeçalho Authorization: Bearer. Os endereços de homologação e de produção estão em servers." }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Token de acesso entregue pela LideraNota, vinculado a um emitente, enviado no cabeçalho Authorization: Bearer . Guarde-o como senha; em caso de perda ou suspeita de vazamento, peça um novo token à LideraNota." } }, "schemas": { "WebhookEvento": { "type": "object", "description": "Evento de nota enviado ao webhook do seu sistema. O conteúdo é congelado na criação do evento: nota mostra o estado naquele instante, inclusive quando o evento é reenviado; o estado atual é o da consulta da nota.", "required": [ "eventoId", "tipo", "ocorridoEm", "nota" ], "properties": { "eventoId": { "type": "string", "format": "uuid", "description": "Identificador único do evento: o mesmo evento pode chegar mais de uma vez; grave os eventoId recebidos e ignore o repetido, respondendo 2xx." }, "tipo": { "type": "string", "enum": [ "autorizada", "rejeitada", "cancelada", "cancelamento_rejeitado", "substituida", "analise_fiscal_registrada", "analise_fiscal_rejeitada", "analise_fiscal_indeferida" ], "description": "Tipo do evento. autorizada: NFS-e autorizada pela Sefin Nacional. rejeitada: Nota rejeitada pela Sefin Nacional ou pela validação antes do envio; nota.erro traz o código e o motivo. cancelada: Cancelamento registrado, pelo cancelamento direto (nota.cancelamento.status registrado) ou pelo deferimento da análise fiscal (nota.analiseFiscal.resultado.decisao deferido). cancelamento_rejeitado: Cancelamento recusado pela Sefin Nacional: a nota volta a autorizada e nota.cancelamento traz o erro; um novo pedido pode ser feito. substituida: A substituta da nota foi autorizada. Evento da nota original (status substituida, com nota.substituidaPor); chega junto do evento autorizada da substituta, com o mesmo ocorridoEm. analise_fiscal_registrada: Pedido de análise fiscal registrado na Sefin Nacional; a nota continua autorizada e ainda não há decisão do município. analise_fiscal_rejeitada: A Sefin Nacional recusou o pedido de análise fiscal; nota.analiseFiscal traz o erro e a nota continua autorizada. analise_fiscal_indeferida: O município indeferiu o cancelamento; a nota continua autorizada e nota.analiseFiscal.resultado traz a decisão e o motivo. Novos tipos podem surgir: responda 2xx a tipo que o seu sistema não conheça e registre o evento." }, "ocorridoEm": { "type": "string", "format": "date-time", "description": "Instante do evento (ISO 8601, UTC). Eventos podem chegar fora de ordem: descarte o evento cujo ocorridoEm é anterior ao do último estado aplicado à nota." }, "nota": { "type": "object", "required": [ "id", "idOperacao", "loteId", "status", "ambiente" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identificador da nota." }, "idOperacao": { "type": "string", "description": "Identificador da operação enviado pelo seu sistema." }, "loteId": { "type": "string", "format": "uuid", "description": "Identificador do lote que recebeu a nota." }, "status": { "type": "string", "enum": [ "recebida", "pronta", "enviada", "autorizada", "rejeitada", "pendente_intervencao", "cancelamento_solicitado", "cancelada", "substituida" ], "description": "Status da nota. recebida, pronta e enviada: em processamento. autorizada e rejeitada: desfecho (rejeitada traz erro com código e motivo). pendente_intervencao: a emissão não foi concluída e aguarda a análise da LideraNota; não é rejeição da nota. Não reenvie a nota com outro idOperacao (a DPS pode ter sido registrada na Sefin) e continue consultando: o status ainda pode mudar. cancelamento_solicitado e cancelada: cancelamento (cancelada: cancelamento direto ou deferimento da análise fiscal). substituida: a nota foi substituída por outra nota autorizada (substituidaPor); na Sefin ela fica cancelada por substituição." }, "ambiente": { "type": "string", "enum": [ "homologacao", "producao" ], "description": "Ambiente da NFS-e Nacional em que a nota é emitida: homologacao (produção restrita, sem validade jurídica) ou producao." }, "serie": { "type": "string", "description": "Série da DPS; presente depois que a DPS é montada." }, "numeroDps": { "type": "integer", "description": "Número da DPS na série; presente depois que a DPS é montada." }, "idDps": { "type": "string", "description": "Identificador da DPS; presente depois que a DPS é montada." }, "numeroNfse": { "type": "string", "description": "Número da NFS-e; presente quando autorizada." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da NFS-e (50 dígitos); presente quando autorizada." }, "autorizadaEm": { "type": "string", "format": "date-time", "description": "Instante da autorização da NFS-e (ISO 8601)." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitada: código e motivo da rejeição.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } }, "links": { "type": "object", "description": "Links absolutos dos documentos da nota. Presente somente quando a nota tem XML autorizado (autorizada, cancelamento_solicitado, cancelada e substituida).", "properties": { "xml": { "type": "string", "format": "uri", "description": "GET do XML autorizado da nota (application/xml), com o mesmo token de API." }, "danfse": { "type": "string", "format": "uri", "description": "GET do DANFSe da nota (application/pdf), gerado a partir do XML autorizado, com o mesmo token de API." } } }, "cancelamento": { "type": "object", "description": "Presente somente quando a nota tem algum pedido de cancelamento: o último pedido (evento 101101).", "required": [ "status", "motivo", "cMotivo", "solicitadoEm" ], "properties": { "status": { "type": "string", "enum": [ "solicitado", "registrado", "rejeitado" ], "description": "Situação do pedido: solicitado (aguardando a Sefin Nacional), registrado ou rejeitado." }, "motivo": { "type": "string", "description": "Motivo gravado, sem espaços nas pontas." }, "cMotivo": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Classificação do motivo enviada à Sefin no pedido: 1 erro na emissão, 2 serviço não prestado, 9 outros. É a informada pelo sistema consumidor ou 9 quando não informada; sempre presente." }, "solicitadoEm": { "type": "string", "format": "date-time", "description": "Instante do pedido (ISO 8601)." }, "registradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando o status é registrado." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitado: código e motivo da rejeição da Sefin.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } } } }, "analiseFiscal": { "type": "object", "description": "Presente somente quando a nota tem algum pedido de análise fiscal para cancelamento: o último pedido (evento 101103) e, quando houver, a decisão do município.", "required": [ "status", "motivo", "cMotivo", "solicitadoEm" ], "properties": { "status": { "type": "string", "enum": [ "solicitado", "registrado", "rejeitado" ], "description": "Situação do pedido: solicitado (aguardando a Sefin Nacional), registrado ou rejeitado." }, "motivo": { "type": "string", "description": "Motivo gravado, sem espaços nas pontas." }, "cMotivo": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Classificação do motivo enviada à Sefin no pedido (informada pelo sistema consumidor): 1 erro na emissão, 2 serviço não prestado, 9 outros; 9 quando não informada; sempre presente. Não é a decisão do município, que fica em resultado.codigoMotivo." }, "solicitadoEm": { "type": "string", "format": "date-time", "description": "Instante do pedido (ISO 8601)." }, "registradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando o status é registrado: registro do pedido na Sefin." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitado: código e motivo da rejeição da Sefin.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } }, "resultado": { "type": "object", "description": "Presente somente quando o município decidiu: 105104 (deferido, a nota fica cancelada) ou 105105 (indeferido, a nota continua autorizada).", "required": [ "evento", "decisao", "codigoMotivo", "motivo", "decididoEm" ], "properties": { "evento": { "type": "string", "enum": [ "105104", "105105" ], "description": "Evento do município: 105104 (deferimento) ou 105105 (indeferimento)." }, "decisao": { "type": "string", "enum": [ "deferido", "indeferido" ], "description": "Decisão do município." }, "codigoMotivo": { "type": "string", "enum": [ "1", "2" ], "description": "Código do motivo do município: no indeferimento, 2 = indeferido sem análise de mérito." }, "motivo": { "type": "string", "description": "Justificativa do município." }, "processoAdministrativo": { "type": "string", "description": "Número do processo administrativo, se informado." }, "decididoEm": { "type": "string", "format": "date-time", "description": "Instante da decisão do município (ISO 8601)." } } }, "acompanhamentoEncerradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando a consulta automática do resultado terminou sem decisão do município (fim da janela de acompanhamento). Não é decisão: o município ainda pode decidir; para retomar o acompanhamento, fale com a LideraNota." } } }, "valoresIbsCbs": { "type": "object", "description": "Valores de IBS/CBS calculados pela Sefin, copiados do XML da NFS-e autorizada (a LideraNota não soma, não arredonda e não zera). Presente somente quando a nota tem XML autorizado e esse XML traz o grupo IBSCBS; ausente nas notas sem o grupo (envio desligado ou autorizadas antes da versão). Reais e percentuais como números JSON (0.9 = 0,90%).", "required": [ "valorLiquido", "valorTotalNfse", "baseCalculo", "ibs", "cbs" ], "properties": { "valorLiquido": { "type": "number", "description": "vLiq: Valor Líquido da NFS-e, em reais." }, "valorTotalNfse": { "type": "number", "description": "vTotNF: Valor Líquido da NFS-e + IBS/CBS, em reais. É o valor a cobrar (guia de integração)." }, "baseCalculo": { "type": "number", "description": "Base de cálculo do IBS/CBS, em reais." }, "ibs": { "type": "object", "description": "IBS: valor total e as esferas estadual e municipal.", "required": [ "valorTotal", "estadual", "municipal" ], "properties": { "valorTotal": { "type": "number", "description": "Valor total do IBS, em reais." }, "estadual": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "IBS estadual: alíquota, alíquota efetiva e valor apurado." }, "municipal": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "IBS municipal: alíquota, alíquota efetiva e valor apurado." } } }, "cbs": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "CBS: alíquota, alíquota efetiva e valor apurado." } } }, "substitui": { "type": "object", "description": "Presente somente na nota substituta, em qualquer status: a nota original que ela substitui e o motivo informado no pedido.", "required": [ "notaId", "chaveAcesso", "cMotivo" ], "properties": { "notaId": { "type": "string", "format": "uuid", "description": "Identificador da nota original." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da nota original (chSubstda da DPS)." }, "cMotivo": { "type": "string", "enum": [ "01", "02", "03", "04", "05", "99" ], "description": "Motivo da substituição informado no pedido." }, "xMotivo": { "type": "string", "description": "Descrição do motivo informada no pedido, quando houver." } } }, "substituidaPor": { "type": "object", "description": "Presente somente quando o status é substituida: a nota substituta autorizada.", "required": [ "notaId", "chaveAcesso" ], "properties": { "notaId": { "type": "string", "format": "uuid", "description": "Identificador da nota substituta." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da nota substituta." } } } }, "description": "A nota no instante do evento, no mesmo formato da consulta da nota. Os links de documentos são baixados com o token de acesso, nunca com o token de webhook." } } } } }, "paths": { "/lotes": { "post": { "operationId": "enviarLote", "summary": "Enviar lote de 1 a 500 notas", "tags": [ "Lotes" ], "description": "Recebe de 1 a 500 notas e responde 202 na hora, com o resultado da recepção de cada nota, na ordem enviada. A emissão acontece depois, em segundo plano; o desfecho chega pelo webhook ou pela consulta da nota. Uma nota recusada na recepção não impede as demais. Reenviar um idOperacao já recebido devolve a nota existente (existente = true), sem emitir outra. O corpo aceita até 5 MB.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Lote de notas a emitir.", "required": [ "notas" ], "additionalProperties": false, "properties": { "notas": { "type": "array", "description": "Notas do lote, de 1 a 500; cada nota é validada separadamente.", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "idOperacao": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Identificador da operação no sistema do cliente (por exemplo, o código da fatura): 1 a 64 caracteres. É a chave de idempotência: reenviar o mesmo idOperacao devolve a nota já recebida, sem emitir outra." }, "competencia": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Data de competência do serviço, no formato AAAA-MM-DD." }, "tomador": { "description": "Tomador do serviço, somente nacional. Ausente, a nota sai sem tomador identificado (exige ISSQN não retido). Com o envio do IBS/CBS ligado, obrigatório, com endereco, nos serviços cujo indicador de operação exige o tomador (E0234).", "type": "object", "properties": { "documento": { "type": "string", "pattern": "^(\\d{11}|[0-9A-Z]{12}\\d{2})$", "description": "CPF (11 dígitos) ou CNPJ (14 caracteres: 12 dígitos ou letras maiúsculas e 2 dígitos verificadores numéricos; CNPJ alfanumérico aceito), sem pontuação, com dígito verificador válido." }, "nome": { "type": "string", "maxLength": 300, "description": "Nome ou razão social: até 300 caracteres, não vazio." }, "email": { "description": "E-mail (opcional): endereço válido com até 80 caracteres.", "type": "string", "maxLength": 80, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "telefone": { "description": "Telefone com DDD (opcional): 10 ou 11 dígitos, sem pontuação.", "type": "string", "pattern": "^\\d{10,11}$" }, "endereco": { "description": "Endereço nacional do tomador. Obrigatório quando o tomador é CNPJ ou a nota tem valores.issRetido = true; opcional para tomador CPF sem retenção.", "type": "object", "properties": { "cep": { "type": "string", "pattern": "^\\d{8}$", "description": "CEP com 8 dígitos, sem pontuação." }, "logradouro": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[\\u0020-\\u00FF]*$", "description": "Logradouro: 1 a 255 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos." }, "numero": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[\\u0020-\\u00FF]*$", "description": "Número do endereço: 1 a 60 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos." }, "complemento": { "description": "Complemento do endereço (opcional): 1 a 156 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos.", "type": "string", "minLength": 1, "maxLength": 156, "pattern": "^[\\u0020-\\u00FF]*$" }, "bairro": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[\\u0020-\\u00FF]*$", "description": "Bairro: 1 a 60 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos." }, "codigoMunicipio": { "type": "string", "pattern": "^\\d{7}$", "description": "Código IBGE do município, com 7 dígitos." } }, "required": [ "cep", "logradouro", "numero", "bairro", "codigoMunicipio" ], "additionalProperties": false } }, "required": [ "documento", "nome" ], "additionalProperties": false }, "servico": { "type": "object", "properties": { "codigoTributacaoNacional": { "type": "string", "pattern": "^\\d{6}$", "description": "Código de tributação nacional (cTribNac): 6 dígitos, com o zero à esquerda (010701, não 10701), existente na lista nacional de serviços." }, "codigoTributacaoMunicipal": { "description": "Código de tributação municipal (cTribMun): 3 dígitos, diferente de 000. Exigido conforme o cadastro do serviço do emitente.", "type": "string", "pattern": "^\\d{3}$" }, "codigoNbs": { "description": "Código NBS (cNBS): 9 dígitos, sem pontos (1.1501.10.00 vira 115011000), existente na tabela NBS. Opcional; com o envio do IBS/CBS ligado, obrigatório quando o serviço não tem cNBS cadastrado (E0322). Informado na nota, prevalece sobre o cadastrado.", "type": "string", "pattern": "^\\d{9}$" }, "descricao": { "type": "string", "maxLength": 2000, "description": "Discriminação do serviço: até 2000 caracteres, não vazia; quebra de linha permitida." }, "codigoMunicipioPrestacao": { "description": "Código IBGE do município de prestação, com 7 dígitos (opcional). Sem o campo, vale o município de prestação padrão cadastrado para o emitente.", "type": "string", "pattern": "^\\d{7}$" } }, "required": [ "codigoTributacaoNacional", "descricao" ], "additionalProperties": false, "description": "Serviço prestado." }, "valores": { "type": "object", "properties": { "valorServico": { "description": "Valor do serviço em reais, como número JSON (não texto), mínimo 0.01 e no máximo 2 casas decimais (ex.: 150.25).", "type": "number", "minimum": 0.01 }, "issRetido": { "description": "ISSQN retido pelo tomador. Obrigatório para prestador do Simples Nacional (ME/EPP e MEI); opcional para não optante (opSimpNac = 1), que pode usar valores.tpRetISSQN (os dois juntos devem concordar: true somente com 2, false somente com 1; ambos ausentes = não retido). Proibido para MEI (E0583). true exige tomador com endereco e, para prestador com regApTribSN = 1, valores.aliquotaSimples.", "type": "boolean" }, "aliquotaSimples": { "description": "Alíquota do Simples Nacional em percentual. Obrigatória somente quando valores.issRetido = true e regApTribSN = 1 no cadastro. Recusada sem retenção e para regApTribSN 2 ou 3. Proibida para MEI (E0600), inclusive zero, e para não optante (E0617).", "type": "number", "minimum": 1.8, "maximum": 5 }, "tribISSQN": { "description": "Somente não optante (opSimpNac = 1). Tributação do ISSQN: 1 = operação tributável (padrão quando omitido), 2 = imunidade (exige tpImunidade), 4 = não incidência. Imunidade e não incidência proíbem retenção (E0580) e suspensão (E0585) e exigem regEspTrib = 0 no cadastro (E0172).", "type": "number", "enum": [ 1, 2, 4 ] }, "tpImunidade": { "description": "Somente não optante. Tipo de imunidade (1 a 5): obrigatório e permitido somente com tribISSQN = 2 (E0592).", "type": "number", "enum": [ 1, 2, 3, 4, 5 ] }, "exigSusp": { "description": "Somente não optante. Exigibilidade do ISSQN suspensa (tpSusp e nProcesso juntos): permitida somente com operação tributável (tribISSQN = 1; E0585).", "type": "object", "properties": { "tpSusp": { "type": "number", "enum": [ 1, 2 ], "description": "1 = decisão judicial; 2 = processo administrativo." }, "nProcesso": { "type": "string", "pattern": "^[0-9]{30}$", "description": "Número do processo judicial ou administrativo da suspensão: exatamente 30 dígitos (0 a 9), padrão TSNumProcExigSuspensa do XSD. Nenhum ajuste é feito no valor (sem remoção de espaços ou pontuação e sem completar com zeros à esquerda); valor fora do padrão recusa a nota na recepção." } }, "required": [ "tpSusp", "nProcesso" ], "additionalProperties": false }, "tpRetISSQN": { "description": "Somente não optante. Retenção do ISSQN: 1 = não retido, 2 = retido pelo tomador (exige tomador com endereco, E0237), 3 = retido pelo intermediário (exige intermediario com endereco e tomador com endereco; omita issRetido). Retenção 2 ou 3 é recusada com regime especial no cadastro (E0588).", "type": "number", "enum": [ 1, 2, 3 ] }, "totTrib": { "description": "Somente não optante. Total aproximado dos tributos: exatamente um entre vTotTrib (valores) e pTotTrib (percentuais), com os três membros. Ausente, usa os percentuais do cadastro do prestador; sem nenhum dos dois, a nota é recusada (E0713). A nota com o grupo válido prevalece integralmente sobre o cadastro.", "type": "object", "properties": { "vTotTrib": { "description": "Total aproximado dos tributos em valor (reais, texto com até 2 casas): vTotTribFed, vTotTribEst e vTotTribMun, cada um de 0 até o valor do serviço.", "type": "object", "properties": { "vTotTribFed": { "type": "string", "description": "Valor aproximado dos tributos federais, em reais, como texto sem sinal, vírgula, expoente nem espaços, com até 15 dígitos inteiros e no máximo 2 casas decimais (ex.: \"12.34\"), de 0 até o valor do serviço." }, "vTotTribEst": { "type": "string", "description": "Valor aproximado dos tributos estaduais, em reais, como texto sem sinal, vírgula, expoente nem espaços, com até 15 dígitos inteiros e no máximo 2 casas decimais (ex.: \"12.34\"), de 0 até o valor do serviço." }, "vTotTribMun": { "type": "string", "description": "Valor aproximado dos tributos municipais, em reais, como texto sem sinal, vírgula, expoente nem espaços, com até 15 dígitos inteiros e no máximo 2 casas decimais (ex.: \"12.34\"), de 0 até o valor do serviço." } }, "required": [ "vTotTribFed", "vTotTribEst", "vTotTribMun" ], "additionalProperties": false }, "pTotTrib": { "description": "Total aproximado dos tributos em percentual (texto de 0 a 100 com até 2 casas): pTotTribFed, pTotTribEst e pTotTribMun.", "type": "object", "properties": { "pTotTribFed": { "type": "string", "description": "Percentual aproximado dos tributos federais, em percentual, como texto de 0 a 100 sem sinal, vírgula, expoente nem espaços, com no máximo 2 casas decimais (ex.: \"13.45\")." }, "pTotTribEst": { "type": "string", "description": "Percentual aproximado dos tributos estaduais, em percentual, como texto de 0 a 100 sem sinal, vírgula, expoente nem espaços, com no máximo 2 casas decimais (ex.: \"13.45\")." }, "pTotTribMun": { "type": "string", "description": "Percentual aproximado dos tributos municipais, em percentual, como texto de 0 a 100 sem sinal, vírgula, expoente nem espaços, com no máximo 2 casas decimais (ex.: \"13.45\")." } }, "required": [ "pTotTribFed", "pTotTribEst", "pTotTribMun" ], "additionalProperties": false } }, "additionalProperties": false }, "tribFed": { "description": "Tributos federais da nota: PIS/COFINS (piscofins) e retenções vRetCP, vRetIRRF e vRetCSLL, todos calculados e informados pelo seu sistema; a LideraNota confere formato e coerência e nunca calcula, completa ou arredonda os valores. Valores em reais e alíquotas em percentual, como texto com no máximo 2 casas. Aceito para não optante e ME/EPP; proibido para MEI (E0676). Ausente, a DPS sai sem o grupo. Independente de totTrib (nenhum alimenta o outro).", "type": "object", "properties": { "piscofins": { "description": "PIS/COFINS da nota (TCTribOutrosPisCofins): CST obrigatório; base, alíquotas, valores e tpRetPisCofins opcionais.", "type": "object", "properties": { "CST": { "type": "string", "enum": [ "00", "01", "02", "03", "04", "05", "06", "07", "08", "09", "49", "50", "51", "52", "53", "54", "55", "56", "60", "61", "62", "63", "64", "65", "66", "67", "70", "71", "72", "73", "74", "75", "98", "99" ], "description": "CST do PIS/COFINS como texto de dois dígitos (TSTipoCST): 00 a 09, 49, 50 a 56, 60 a 67, 70 a 75, 98 ou 99. Obrigatório no grupo; o enquadramento é do consumidor." }, "vBCPisCofins": { "description": "Base de cálculo do PIS/COFINS em reais, texto com até 15 dígitos inteiros e 2 casas (ex.: \"1000.00\"). Obrigatória quando pAliqPis ou pAliqCofins é informada; não precisa ser igual ao valor do serviço, mas não pode ser maior que ele (E0677).", "type": "string" }, "pAliqPis": { "description": "Alíquota do PIS em percentual, texto de 0 a 99.99 com até 2 casas (\"0.65\" = 0,65%, não 0,0065). Quando informada, exige vBCPisCofins e vPis e confere vPis (E0694).", "type": "string" }, "pAliqCofins": { "description": "Alíquota da COFINS em percentual, texto de 0 a 99.99 com até 2 casas (\"3.00\" = 3%). Quando informada, exige vBCPisCofins e vCofins e confere vCofins (E0696).", "type": "string" }, "vPis": { "description": "Valor do PIS em reais, calculado pelo consumidor (texto com até 2 casas). Com pAliqPis, deve ficar a no máximo R$ 0,01 de vBCPisCofins × pAliqPis ÷ 100 arredondado para centavos pela regra half-even; nunca é recalculado nem corrigido.", "type": "string" }, "vCofins": { "description": "Valor da COFINS em reais, calculado pelo consumidor (texto com até 2 casas). Com pAliqCofins, deve ficar a no máximo R$ 0,01 de vBCPisCofins × pAliqCofins ÷ 100 arredondado para centavos pela regra half-even; nunca é recalculado nem corrigido.", "type": "string" }, "tpRetPisCofins": { "description": "Tipo de retenção do PIS/COFINS/CSLL (inteiro 0 a 9, tabela TSTipoRetPISCofins), sem valor padrão: ausente não significa não retido. 0 proíbe vRetCSLL (E0720); 1, 3, 4, 5, 6, 7, 8 e 9 exigem vRetCSLL (E0724).", "type": "number", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ] } }, "required": [ "CST" ], "additionalProperties": false }, "vRetCP": { "description": "Contribuição previdenciária retida em reais (texto com até 2 casas): maior que zero e menor que o valor do serviço (E0699).", "type": "string" }, "vRetIRRF": { "description": "IRRF retido em reais (texto com até 2 casas): maior que zero e menor que o valor do serviço (E0700).", "type": "string" }, "vRetCSLL": { "description": "Valor das contribuições retidas em reais (texto com até 2 casas), como informado pelo consumidor: maior que zero e menor que o valor do serviço (E0701); proibido com tpRetPisCofins 0 (E0720) e obrigatório com 1, 3 a 9 (E0724). Nunca derivado nem somado pela LideraNota.", "type": "string" } }, "additionalProperties": false } }, "required": [ "valorServico" ], "additionalProperties": false, "description": "Valores e tributação da nota." }, "informacoesComplementares": { "description": "Informações complementares da nota (opcional): 1 a 2000 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos.", "type": "string", "minLength": 1, "maxLength": 2000, "pattern": "^[\\u0020-\\u00FF]*$" }, "ibsCbs": { "type": "object", "properties": { "codigoIndicadorOperacao": { "description": "Indicador da operação (cIndOp, 6 dígitos, tabela oficial ANEXO_C). Sobrepõe o cadastrado para o serviço.", "type": "string", "pattern": "^\\d{6}$" }, "codigoSituacaoTributaria": { "description": "CST do IBS/CBS (3 dígitos). Informado junto com codigoClassificacaoTributaria ou nenhum dos dois; o par sobrepõe o cadastrado para o serviço.", "type": "string", "pattern": "^\\d{3}$" }, "codigoClassificacaoTributaria": { "description": "Classificação tributária do IBS/CBS (cClassTrib, 6 dígitos). Informado junto com codigoSituacaoTributaria ou nenhum dos dois; o par deve constar da tabela oficial, valer para a NFS-e e estar vigente.", "type": "string", "pattern": "^\\d{6}$" } }, "additionalProperties": false, "description": "Classificação IBS/CBS da nota (opcional). Só tem efeito quando o envio do grupo IBSCBS está ligado para o prestador; com ele desligado, é aceito e ignorado. Cada campo informado sobrepõe o cadastrado para o serviço (servico.codigoTributacaoNacional); com os três campos, a nota dispensa o cadastro. Objeto vazio equivale a grupo ausente." }, "intermediario": { "description": "Somente não optante (opSimpNac = 1). Intermediário do serviço (infDPS.interm), somente nacional, com as mesmas regras de identificação e endereço do tomador; o emitente continua sendo o prestador. Obrigatório, com endereco, quando valores.tpRetISSQN = 3. Intermediário com CNPJ exige endereco com qualquer retenção (E1388); com CPF, o endereço é opcional fora da retenção 3. A raiz do CNPJ do intermediário (8 primeiros caracteres) não pode ser a do prestador (E0262).", "type": "object", "properties": { "documento": { "type": "string", "pattern": "^(\\d{11}|[0-9A-Z]{12}\\d{2})$", "description": "CPF (11 dígitos) ou CNPJ (14 caracteres: 12 dígitos ou letras maiúsculas e 2 dígitos verificadores numéricos; CNPJ alfanumérico aceito), sem pontuação, com dígito verificador válido." }, "nome": { "type": "string", "maxLength": 300, "description": "Nome ou razão social: até 300 caracteres, não vazio." }, "email": { "description": "E-mail (opcional): endereço válido com até 80 caracteres.", "type": "string", "maxLength": 80, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "telefone": { "description": "Telefone com DDD (opcional): 10 ou 11 dígitos, sem pontuação.", "type": "string", "pattern": "^\\d{10,11}$" }, "endereco": { "description": "Endereço nacional do tomador. Obrigatório quando o tomador é CNPJ ou a nota tem valores.issRetido = true; opcional para tomador CPF sem retenção.", "type": "object", "properties": { "cep": { "type": "string", "pattern": "^\\d{8}$", "description": "CEP com 8 dígitos, sem pontuação." }, "logradouro": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[\\u0020-\\u00FF]*$", "description": "Logradouro: 1 a 255 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos." }, "numero": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[\\u0020-\\u00FF]*$", "description": "Número do endereço: 1 a 60 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos." }, "complemento": { "description": "Complemento do endereço (opcional): 1 a 156 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos.", "type": "string", "minLength": 1, "maxLength": 156, "pattern": "^[\\u0020-\\u00FF]*$" }, "bairro": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[\\u0020-\\u00FF]*$", "description": "Bairro: 1 a 60 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos." }, "codigoMunicipio": { "type": "string", "pattern": "^\\d{7}$", "description": "Código IBGE do município, com 7 dígitos." } }, "required": [ "cep", "logradouro", "numero", "bairro", "codigoMunicipio" ], "additionalProperties": false } }, "required": [ "documento", "nome" ], "additionalProperties": false } }, "required": [ "idOperacao", "competencia", "servico", "valores" ], "additionalProperties": false } } } }, "example": { "notas": [ { "idOperacao": "FAT-1001", "competencia": "2026-11-10", "tomador": { "documento": "11222333000181", "nome": "Cliente Exemplo Ltda", "email": "financeiro@cliente.example", "endereco": { "cep": "30130000", "logradouro": "Rua Exemplo", "numero": "100", "bairro": "Centro", "codigoMunicipio": "3106200" } }, "servico": { "codigoTributacaoNacional": "010701", "descricao": "Desenvolvimento de sistema sob encomenda" }, "valores": { "valorServico": 1500, "issRetido": false } } ] } } }, "description": "Lote de notas a emitir." }, "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Lote aceito. Cada nota traz seu resultado individual de recepção.", "content": { "application/json": { "schema": { "description": "Lote aceito. Cada nota traz seu resultado individual de recepção.", "type": "object", "required": [ "loteId", "notas" ], "properties": { "loteId": { "type": "string", "format": "uuid", "description": "Identificador do lote, usado na consulta do lote." }, "notas": { "type": "array", "description": "Resultado de cada nota, na ordem em que foi enviada.", "items": { "type": "object", "required": [ "aceita" ], "properties": { "idOperacao": { "type": "string", "description": "idOperacao enviado na nota; ausente quando não veio como texto." }, "aceita": { "type": "boolean", "description": "true se a nota foi recebida para emissão; false se foi recusada na recepção (veja erros)." }, "id": { "type": "string", "format": "uuid", "description": "Identificador da nota; presente se aceita." }, "status": { "type": "string", "enum": [ "recebida", "pronta", "enviada", "autorizada", "rejeitada", "pendente_intervencao", "cancelamento_solicitado", "cancelada", "substituida" ], "description": "Status da nota no momento da resposta; presente se aceita." }, "existente": { "type": "boolean", "description": "true se o idOperacao já tinha sido recebido: a resposta traz a nota existente e nenhuma nota nova é criada." }, "erros": { "type": "array", "description": "Recusas da nota; presente se recusada.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "example": { "loteId": "7c1e9a4b-2f3d-4e8a-b5c6-1d2e3f4a5b6c", "notas": [ { "idOperacao": "FAT-1001", "aceita": true, "id": "3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10", "status": "recebida", "existente": false } ] } } } }, "400": { "description": "Lote com formato inválido (VALIDACAO_CAMPO, com o detalhe em campos) ou acima do limite de notas (LOTE_ACIMA_DO_LIMITE, nenhuma nota recebida). Notas inválidas num lote válido não geram 400: voltam recusadas no 202.", "content": { "application/json": { "schema": { "type": "object", "description": "Lote com formato inválido (VALIDACAO_CAMPO, com o detalhe em campos) ou acima do limite de notas (LOTE_ACIMA_DO_LIMITE, nenhuma nota recebida). Notas inválidas num lote válido não geram 400: voltam recusadas no 202.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "401": { "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "content": { "application/json": { "schema": { "type": "object", "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "429": { "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "content": { "application/json": { "schema": { "type": "object", "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "503": { "description": "Tabelas oficiais da NFS-e Nacional não carregadas (TABELAS_OFICIAIS_INDISPONIVEIS): nenhuma nota do lote foi recebida; repita o envio depois do Retry-After.", "content": { "application/json": { "schema": { "type": "object", "description": "Tabelas oficiais da NFS-e Nacional não carregadas (TABELAS_OFICIAIS_INDISPONIVEIS): nenhuma nota do lote foi recebida; repita o envio depois do Retry-After.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } } } } }, "/lotes/{loteId}": { "get": { "operationId": "consultarLote", "summary": "Consultar lote", "tags": [ "Lotes" ], "description": "Devolve o lote com a contagem de notas por status e as notas gravadas por ele. O desfecho de cada nota também chega pelo webhook.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "in": "path", "name": "loteId", "required": true, "description": "Identificador do lote, devolvido no envio." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lote com contagem por status e notas", "content": { "application/json": { "schema": { "description": "Lote com contagem por status e notas", "type": "object", "required": [ "loteId", "recebidoEm", "totalNotas", "contagemPorStatus", "notas" ], "properties": { "loteId": { "type": "string", "format": "uuid", "description": "Identificador do lote." }, "recebidoEm": { "type": "string", "format": "date-time", "description": "Instante da recepção do lote (ISO 8601)." }, "totalNotas": { "type": "integer", "description": "Quantidade de itens da requisição do lote, inclusive notas recusadas na recepção e reenvios de idOperacao já recebido. Pode ser maior que a quantidade de notas: reenvios continuam ligados ao lote original (consulte-os por GET /notas?idOperacao=)." }, "contagemPorStatus": { "type": "object", "description": "Quantidade de notas do lote por status; só aparecem os status presentes.", "additionalProperties": { "type": "integer", "description": "Quantidade de notas no status." } }, "notas": { "type": "array", "description": "Notas gravadas por este lote, em ordem de idOperacao.", "items": { "type": "object", "required": [ "id", "idOperacao", "loteId", "status", "ambiente" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identificador da nota." }, "idOperacao": { "type": "string", "description": "Identificador da operação enviado pelo seu sistema." }, "loteId": { "type": "string", "format": "uuid", "description": "Identificador do lote que recebeu a nota." }, "status": { "type": "string", "enum": [ "recebida", "pronta", "enviada", "autorizada", "rejeitada", "pendente_intervencao", "cancelamento_solicitado", "cancelada", "substituida" ], "description": "Status da nota. recebida, pronta e enviada: em processamento. autorizada e rejeitada: desfecho (rejeitada traz erro com código e motivo). pendente_intervencao: a emissão não foi concluída e aguarda a análise da LideraNota; não é rejeição da nota. Não reenvie a nota com outro idOperacao (a DPS pode ter sido registrada na Sefin) e continue consultando: o status ainda pode mudar. cancelamento_solicitado e cancelada: cancelamento (cancelada: cancelamento direto ou deferimento da análise fiscal). substituida: a nota foi substituída por outra nota autorizada (substituidaPor); na Sefin ela fica cancelada por substituição." }, "ambiente": { "type": "string", "enum": [ "homologacao", "producao" ], "description": "Ambiente da NFS-e Nacional em que a nota é emitida: homologacao (produção restrita, sem validade jurídica) ou producao." }, "serie": { "type": "string", "description": "Série da DPS; presente depois que a DPS é montada." }, "numeroDps": { "type": "integer", "description": "Número da DPS na série; presente depois que a DPS é montada." }, "idDps": { "type": "string", "description": "Identificador da DPS; presente depois que a DPS é montada." }, "numeroNfse": { "type": "string", "description": "Número da NFS-e; presente quando autorizada." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da NFS-e (50 dígitos); presente quando autorizada." }, "autorizadaEm": { "type": "string", "format": "date-time", "description": "Instante da autorização da NFS-e (ISO 8601)." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitada: código e motivo da rejeição.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } }, "links": { "type": "object", "description": "Links absolutos dos documentos da nota. Presente somente quando a nota tem XML autorizado (autorizada, cancelamento_solicitado, cancelada e substituida).", "properties": { "xml": { "type": "string", "format": "uri", "description": "GET do XML autorizado da nota (application/xml), com o mesmo token de API." }, "danfse": { "type": "string", "format": "uri", "description": "GET do DANFSe da nota (application/pdf), gerado a partir do XML autorizado, com o mesmo token de API." } } }, "cancelamento": { "type": "object", "description": "Presente somente quando a nota tem algum pedido de cancelamento: o último pedido (evento 101101).", "required": [ "status", "motivo", "cMotivo", "solicitadoEm" ], "properties": { "status": { "type": "string", "enum": [ "solicitado", "registrado", "rejeitado" ], "description": "Situação do pedido: solicitado (aguardando a Sefin Nacional), registrado ou rejeitado." }, "motivo": { "type": "string", "description": "Motivo gravado, sem espaços nas pontas." }, "cMotivo": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Classificação do motivo enviada à Sefin no pedido: 1 erro na emissão, 2 serviço não prestado, 9 outros. É a informada pelo sistema consumidor ou 9 quando não informada; sempre presente." }, "solicitadoEm": { "type": "string", "format": "date-time", "description": "Instante do pedido (ISO 8601)." }, "registradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando o status é registrado." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitado: código e motivo da rejeição da Sefin.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } } } }, "analiseFiscal": { "type": "object", "description": "Presente somente quando a nota tem algum pedido de análise fiscal para cancelamento: o último pedido (evento 101103) e, quando houver, a decisão do município.", "required": [ "status", "motivo", "cMotivo", "solicitadoEm" ], "properties": { "status": { "type": "string", "enum": [ "solicitado", "registrado", "rejeitado" ], "description": "Situação do pedido: solicitado (aguardando a Sefin Nacional), registrado ou rejeitado." }, "motivo": { "type": "string", "description": "Motivo gravado, sem espaços nas pontas." }, "cMotivo": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Classificação do motivo enviada à Sefin no pedido (informada pelo sistema consumidor): 1 erro na emissão, 2 serviço não prestado, 9 outros; 9 quando não informada; sempre presente. Não é a decisão do município, que fica em resultado.codigoMotivo." }, "solicitadoEm": { "type": "string", "format": "date-time", "description": "Instante do pedido (ISO 8601)." }, "registradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando o status é registrado: registro do pedido na Sefin." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitado: código e motivo da rejeição da Sefin.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } }, "resultado": { "type": "object", "description": "Presente somente quando o município decidiu: 105104 (deferido, a nota fica cancelada) ou 105105 (indeferido, a nota continua autorizada).", "required": [ "evento", "decisao", "codigoMotivo", "motivo", "decididoEm" ], "properties": { "evento": { "type": "string", "enum": [ "105104", "105105" ], "description": "Evento do município: 105104 (deferimento) ou 105105 (indeferimento)." }, "decisao": { "type": "string", "enum": [ "deferido", "indeferido" ], "description": "Decisão do município." }, "codigoMotivo": { "type": "string", "enum": [ "1", "2" ], "description": "Código do motivo do município: no indeferimento, 2 = indeferido sem análise de mérito." }, "motivo": { "type": "string", "description": "Justificativa do município." }, "processoAdministrativo": { "type": "string", "description": "Número do processo administrativo, se informado." }, "decididoEm": { "type": "string", "format": "date-time", "description": "Instante da decisão do município (ISO 8601)." } } }, "acompanhamentoEncerradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando a consulta automática do resultado terminou sem decisão do município (fim da janela de acompanhamento). Não é decisão: o município ainda pode decidir; para retomar o acompanhamento, fale com a LideraNota." } } }, "valoresIbsCbs": { "type": "object", "description": "Valores de IBS/CBS calculados pela Sefin, copiados do XML da NFS-e autorizada (a LideraNota não soma, não arredonda e não zera). Presente somente quando a nota tem XML autorizado e esse XML traz o grupo IBSCBS; ausente nas notas sem o grupo (envio desligado ou autorizadas antes da versão). Reais e percentuais como números JSON (0.9 = 0,90%).", "required": [ "valorLiquido", "valorTotalNfse", "baseCalculo", "ibs", "cbs" ], "properties": { "valorLiquido": { "type": "number", "description": "vLiq: Valor Líquido da NFS-e, em reais." }, "valorTotalNfse": { "type": "number", "description": "vTotNF: Valor Líquido da NFS-e + IBS/CBS, em reais. É o valor a cobrar (guia de integração)." }, "baseCalculo": { "type": "number", "description": "Base de cálculo do IBS/CBS, em reais." }, "ibs": { "type": "object", "description": "IBS: valor total e as esferas estadual e municipal.", "required": [ "valorTotal", "estadual", "municipal" ], "properties": { "valorTotal": { "type": "number", "description": "Valor total do IBS, em reais." }, "estadual": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "IBS estadual: alíquota, alíquota efetiva e valor apurado." }, "municipal": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "IBS municipal: alíquota, alíquota efetiva e valor apurado." } } }, "cbs": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "CBS: alíquota, alíquota efetiva e valor apurado." } } }, "substitui": { "type": "object", "description": "Presente somente na nota substituta, em qualquer status: a nota original que ela substitui e o motivo informado no pedido.", "required": [ "notaId", "chaveAcesso", "cMotivo" ], "properties": { "notaId": { "type": "string", "format": "uuid", "description": "Identificador da nota original." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da nota original (chSubstda da DPS)." }, "cMotivo": { "type": "string", "enum": [ "01", "02", "03", "04", "05", "99" ], "description": "Motivo da substituição informado no pedido." }, "xMotivo": { "type": "string", "description": "Descrição do motivo informada no pedido, quando houver." } } }, "substituidaPor": { "type": "object", "description": "Presente somente quando o status é substituida: a nota substituta autorizada.", "required": [ "notaId", "chaveAcesso" ], "properties": { "notaId": { "type": "string", "format": "uuid", "description": "Identificador da nota substituta." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da nota substituta." } } } } } } } } } } }, "400": { "description": "Identificador do lote fora do formato UUID (VALIDACAO_CAMPO).", "content": { "application/json": { "schema": { "type": "object", "description": "Identificador do lote fora do formato UUID (VALIDACAO_CAMPO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "401": { "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "content": { "application/json": { "schema": { "type": "object", "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "404": { "description": "Lote não encontrado para o token informado (LOTE_NAO_ENCONTRADO).", "content": { "application/json": { "schema": { "type": "object", "description": "Lote não encontrado para o token informado (LOTE_NAO_ENCONTRADO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "429": { "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "content": { "application/json": { "schema": { "type": "object", "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } } } } }, "/notas": { "get": { "operationId": "buscarNotaPorIdOperacao", "summary": "Buscar nota pelo idOperacao", "tags": [ "Notas" ], "description": "Devolve a nota pelo idOperacao enviado pelo seu sistema; útil quando o seu sistema não guardou o identificador da nota devolvido no envio do lote.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\t\\n\\r\\u0020-\\uD7FF\\uE000-\\uFFFD\\u{10000}-\\u{10FFFF}]*$" }, "in": "query", "name": "idOperacao", "required": true, "description": "Identificador da operação enviado pelo seu sistema na nota (1 a 64 caracteres)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Estado atual da nota.", "content": { "application/json": { "schema": { "description": "Estado atual da nota.", "type": "object", "required": [ "id", "idOperacao", "loteId", "status", "ambiente" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identificador da nota." }, "idOperacao": { "type": "string", "description": "Identificador da operação enviado pelo seu sistema." }, "loteId": { "type": "string", "format": "uuid", "description": "Identificador do lote que recebeu a nota." }, "status": { "type": "string", "enum": [ "recebida", "pronta", "enviada", "autorizada", "rejeitada", "pendente_intervencao", "cancelamento_solicitado", "cancelada", "substituida" ], "description": "Status da nota. recebida, pronta e enviada: em processamento. autorizada e rejeitada: desfecho (rejeitada traz erro com código e motivo). pendente_intervencao: a emissão não foi concluída e aguarda a análise da LideraNota; não é rejeição da nota. Não reenvie a nota com outro idOperacao (a DPS pode ter sido registrada na Sefin) e continue consultando: o status ainda pode mudar. cancelamento_solicitado e cancelada: cancelamento (cancelada: cancelamento direto ou deferimento da análise fiscal). substituida: a nota foi substituída por outra nota autorizada (substituidaPor); na Sefin ela fica cancelada por substituição." }, "ambiente": { "type": "string", "enum": [ "homologacao", "producao" ], "description": "Ambiente da NFS-e Nacional em que a nota é emitida: homologacao (produção restrita, sem validade jurídica) ou producao." }, "serie": { "type": "string", "description": "Série da DPS; presente depois que a DPS é montada." }, "numeroDps": { "type": "integer", "description": "Número da DPS na série; presente depois que a DPS é montada." }, "idDps": { "type": "string", "description": "Identificador da DPS; presente depois que a DPS é montada." }, "numeroNfse": { "type": "string", "description": "Número da NFS-e; presente quando autorizada." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da NFS-e (50 dígitos); presente quando autorizada." }, "autorizadaEm": { "type": "string", "format": "date-time", "description": "Instante da autorização da NFS-e (ISO 8601)." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitada: código e motivo da rejeição.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } }, "links": { "type": "object", "description": "Links absolutos dos documentos da nota. Presente somente quando a nota tem XML autorizado (autorizada, cancelamento_solicitado, cancelada e substituida).", "properties": { "xml": { "type": "string", "format": "uri", "description": "GET do XML autorizado da nota (application/xml), com o mesmo token de API." }, "danfse": { "type": "string", "format": "uri", "description": "GET do DANFSe da nota (application/pdf), gerado a partir do XML autorizado, com o mesmo token de API." } } }, "cancelamento": { "type": "object", "description": "Presente somente quando a nota tem algum pedido de cancelamento: o último pedido (evento 101101).", "required": [ "status", "motivo", "cMotivo", "solicitadoEm" ], "properties": { "status": { "type": "string", "enum": [ "solicitado", "registrado", "rejeitado" ], "description": "Situação do pedido: solicitado (aguardando a Sefin Nacional), registrado ou rejeitado." }, "motivo": { "type": "string", "description": "Motivo gravado, sem espaços nas pontas." }, "cMotivo": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Classificação do motivo enviada à Sefin no pedido: 1 erro na emissão, 2 serviço não prestado, 9 outros. É a informada pelo sistema consumidor ou 9 quando não informada; sempre presente." }, "solicitadoEm": { "type": "string", "format": "date-time", "description": "Instante do pedido (ISO 8601)." }, "registradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando o status é registrado." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitado: código e motivo da rejeição da Sefin.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } } } }, "analiseFiscal": { "type": "object", "description": "Presente somente quando a nota tem algum pedido de análise fiscal para cancelamento: o último pedido (evento 101103) e, quando houver, a decisão do município.", "required": [ "status", "motivo", "cMotivo", "solicitadoEm" ], "properties": { "status": { "type": "string", "enum": [ "solicitado", "registrado", "rejeitado" ], "description": "Situação do pedido: solicitado (aguardando a Sefin Nacional), registrado ou rejeitado." }, "motivo": { "type": "string", "description": "Motivo gravado, sem espaços nas pontas." }, "cMotivo": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Classificação do motivo enviada à Sefin no pedido (informada pelo sistema consumidor): 1 erro na emissão, 2 serviço não prestado, 9 outros; 9 quando não informada; sempre presente. Não é a decisão do município, que fica em resultado.codigoMotivo." }, "solicitadoEm": { "type": "string", "format": "date-time", "description": "Instante do pedido (ISO 8601)." }, "registradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando o status é registrado: registro do pedido na Sefin." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitado: código e motivo da rejeição da Sefin.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } }, "resultado": { "type": "object", "description": "Presente somente quando o município decidiu: 105104 (deferido, a nota fica cancelada) ou 105105 (indeferido, a nota continua autorizada).", "required": [ "evento", "decisao", "codigoMotivo", "motivo", "decididoEm" ], "properties": { "evento": { "type": "string", "enum": [ "105104", "105105" ], "description": "Evento do município: 105104 (deferimento) ou 105105 (indeferimento)." }, "decisao": { "type": "string", "enum": [ "deferido", "indeferido" ], "description": "Decisão do município." }, "codigoMotivo": { "type": "string", "enum": [ "1", "2" ], "description": "Código do motivo do município: no indeferimento, 2 = indeferido sem análise de mérito." }, "motivo": { "type": "string", "description": "Justificativa do município." }, "processoAdministrativo": { "type": "string", "description": "Número do processo administrativo, se informado." }, "decididoEm": { "type": "string", "format": "date-time", "description": "Instante da decisão do município (ISO 8601)." } } }, "acompanhamentoEncerradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando a consulta automática do resultado terminou sem decisão do município (fim da janela de acompanhamento). Não é decisão: o município ainda pode decidir; para retomar o acompanhamento, fale com a LideraNota." } } }, "valoresIbsCbs": { "type": "object", "description": "Valores de IBS/CBS calculados pela Sefin, copiados do XML da NFS-e autorizada (a LideraNota não soma, não arredonda e não zera). Presente somente quando a nota tem XML autorizado e esse XML traz o grupo IBSCBS; ausente nas notas sem o grupo (envio desligado ou autorizadas antes da versão). Reais e percentuais como números JSON (0.9 = 0,90%).", "required": [ "valorLiquido", "valorTotalNfse", "baseCalculo", "ibs", "cbs" ], "properties": { "valorLiquido": { "type": "number", "description": "vLiq: Valor Líquido da NFS-e, em reais." }, "valorTotalNfse": { "type": "number", "description": "vTotNF: Valor Líquido da NFS-e + IBS/CBS, em reais. É o valor a cobrar (guia de integração)." }, "baseCalculo": { "type": "number", "description": "Base de cálculo do IBS/CBS, em reais." }, "ibs": { "type": "object", "description": "IBS: valor total e as esferas estadual e municipal.", "required": [ "valorTotal", "estadual", "municipal" ], "properties": { "valorTotal": { "type": "number", "description": "Valor total do IBS, em reais." }, "estadual": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "IBS estadual: alíquota, alíquota efetiva e valor apurado." }, "municipal": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "IBS municipal: alíquota, alíquota efetiva e valor apurado." } } }, "cbs": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "CBS: alíquota, alíquota efetiva e valor apurado." } } }, "substitui": { "type": "object", "description": "Presente somente na nota substituta, em qualquer status: a nota original que ela substitui e o motivo informado no pedido.", "required": [ "notaId", "chaveAcesso", "cMotivo" ], "properties": { "notaId": { "type": "string", "format": "uuid", "description": "Identificador da nota original." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da nota original (chSubstda da DPS)." }, "cMotivo": { "type": "string", "enum": [ "01", "02", "03", "04", "05", "99" ], "description": "Motivo da substituição informado no pedido." }, "xMotivo": { "type": "string", "description": "Descrição do motivo informada no pedido, quando houver." } } }, "substituidaPor": { "type": "object", "description": "Presente somente quando o status é substituida: a nota substituta autorizada.", "required": [ "notaId", "chaveAcesso" ], "properties": { "notaId": { "type": "string", "format": "uuid", "description": "Identificador da nota substituta." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da nota substituta." } } } } } } } }, "400": { "description": "Parâmetro fora do formato (VALIDACAO_CAMPO, com o detalhe em campos).", "content": { "application/json": { "schema": { "type": "object", "description": "Parâmetro fora do formato (VALIDACAO_CAMPO, com o detalhe em campos).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "401": { "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "content": { "application/json": { "schema": { "type": "object", "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "404": { "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "content": { "application/json": { "schema": { "type": "object", "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "429": { "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "content": { "application/json": { "schema": { "type": "object", "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } } } } }, "/notas/{notaId}": { "get": { "operationId": "consultarNota", "summary": "Consultar nota", "tags": [ "Notas" ], "description": "Devolve o estado atual da nota: status, dados da NFS-e quando autorizada, links dos documentos e os pedidos de cancelamento, análise fiscal e substituição.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "in": "path", "name": "notaId", "required": true, "description": "Identificador da nota, devolvido no envio do lote e na consulta." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Estado atual da nota.", "content": { "application/json": { "schema": { "description": "Estado atual da nota.", "type": "object", "required": [ "id", "idOperacao", "loteId", "status", "ambiente" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identificador da nota." }, "idOperacao": { "type": "string", "description": "Identificador da operação enviado pelo seu sistema." }, "loteId": { "type": "string", "format": "uuid", "description": "Identificador do lote que recebeu a nota." }, "status": { "type": "string", "enum": [ "recebida", "pronta", "enviada", "autorizada", "rejeitada", "pendente_intervencao", "cancelamento_solicitado", "cancelada", "substituida" ], "description": "Status da nota. recebida, pronta e enviada: em processamento. autorizada e rejeitada: desfecho (rejeitada traz erro com código e motivo). pendente_intervencao: a emissão não foi concluída e aguarda a análise da LideraNota; não é rejeição da nota. Não reenvie a nota com outro idOperacao (a DPS pode ter sido registrada na Sefin) e continue consultando: o status ainda pode mudar. cancelamento_solicitado e cancelada: cancelamento (cancelada: cancelamento direto ou deferimento da análise fiscal). substituida: a nota foi substituída por outra nota autorizada (substituidaPor); na Sefin ela fica cancelada por substituição." }, "ambiente": { "type": "string", "enum": [ "homologacao", "producao" ], "description": "Ambiente da NFS-e Nacional em que a nota é emitida: homologacao (produção restrita, sem validade jurídica) ou producao." }, "serie": { "type": "string", "description": "Série da DPS; presente depois que a DPS é montada." }, "numeroDps": { "type": "integer", "description": "Número da DPS na série; presente depois que a DPS é montada." }, "idDps": { "type": "string", "description": "Identificador da DPS; presente depois que a DPS é montada." }, "numeroNfse": { "type": "string", "description": "Número da NFS-e; presente quando autorizada." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da NFS-e (50 dígitos); presente quando autorizada." }, "autorizadaEm": { "type": "string", "format": "date-time", "description": "Instante da autorização da NFS-e (ISO 8601)." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitada: código e motivo da rejeição.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } }, "links": { "type": "object", "description": "Links absolutos dos documentos da nota. Presente somente quando a nota tem XML autorizado (autorizada, cancelamento_solicitado, cancelada e substituida).", "properties": { "xml": { "type": "string", "format": "uri", "description": "GET do XML autorizado da nota (application/xml), com o mesmo token de API." }, "danfse": { "type": "string", "format": "uri", "description": "GET do DANFSe da nota (application/pdf), gerado a partir do XML autorizado, com o mesmo token de API." } } }, "cancelamento": { "type": "object", "description": "Presente somente quando a nota tem algum pedido de cancelamento: o último pedido (evento 101101).", "required": [ "status", "motivo", "cMotivo", "solicitadoEm" ], "properties": { "status": { "type": "string", "enum": [ "solicitado", "registrado", "rejeitado" ], "description": "Situação do pedido: solicitado (aguardando a Sefin Nacional), registrado ou rejeitado." }, "motivo": { "type": "string", "description": "Motivo gravado, sem espaços nas pontas." }, "cMotivo": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Classificação do motivo enviada à Sefin no pedido: 1 erro na emissão, 2 serviço não prestado, 9 outros. É a informada pelo sistema consumidor ou 9 quando não informada; sempre presente." }, "solicitadoEm": { "type": "string", "format": "date-time", "description": "Instante do pedido (ISO 8601)." }, "registradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando o status é registrado." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitado: código e motivo da rejeição da Sefin.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } } } }, "analiseFiscal": { "type": "object", "description": "Presente somente quando a nota tem algum pedido de análise fiscal para cancelamento: o último pedido (evento 101103) e, quando houver, a decisão do município.", "required": [ "status", "motivo", "cMotivo", "solicitadoEm" ], "properties": { "status": { "type": "string", "enum": [ "solicitado", "registrado", "rejeitado" ], "description": "Situação do pedido: solicitado (aguardando a Sefin Nacional), registrado ou rejeitado." }, "motivo": { "type": "string", "description": "Motivo gravado, sem espaços nas pontas." }, "cMotivo": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Classificação do motivo enviada à Sefin no pedido (informada pelo sistema consumidor): 1 erro na emissão, 2 serviço não prestado, 9 outros; 9 quando não informada; sempre presente. Não é a decisão do município, que fica em resultado.codigoMotivo." }, "solicitadoEm": { "type": "string", "format": "date-time", "description": "Instante do pedido (ISO 8601)." }, "registradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando o status é registrado: registro do pedido na Sefin." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitado: código e motivo da rejeição da Sefin.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } }, "resultado": { "type": "object", "description": "Presente somente quando o município decidiu: 105104 (deferido, a nota fica cancelada) ou 105105 (indeferido, a nota continua autorizada).", "required": [ "evento", "decisao", "codigoMotivo", "motivo", "decididoEm" ], "properties": { "evento": { "type": "string", "enum": [ "105104", "105105" ], "description": "Evento do município: 105104 (deferimento) ou 105105 (indeferimento)." }, "decisao": { "type": "string", "enum": [ "deferido", "indeferido" ], "description": "Decisão do município." }, "codigoMotivo": { "type": "string", "enum": [ "1", "2" ], "description": "Código do motivo do município: no indeferimento, 2 = indeferido sem análise de mérito." }, "motivo": { "type": "string", "description": "Justificativa do município." }, "processoAdministrativo": { "type": "string", "description": "Número do processo administrativo, se informado." }, "decididoEm": { "type": "string", "format": "date-time", "description": "Instante da decisão do município (ISO 8601)." } } }, "acompanhamentoEncerradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando a consulta automática do resultado terminou sem decisão do município (fim da janela de acompanhamento). Não é decisão: o município ainda pode decidir; para retomar o acompanhamento, fale com a LideraNota." } } }, "valoresIbsCbs": { "type": "object", "description": "Valores de IBS/CBS calculados pela Sefin, copiados do XML da NFS-e autorizada (a LideraNota não soma, não arredonda e não zera). Presente somente quando a nota tem XML autorizado e esse XML traz o grupo IBSCBS; ausente nas notas sem o grupo (envio desligado ou autorizadas antes da versão). Reais e percentuais como números JSON (0.9 = 0,90%).", "required": [ "valorLiquido", "valorTotalNfse", "baseCalculo", "ibs", "cbs" ], "properties": { "valorLiquido": { "type": "number", "description": "vLiq: Valor Líquido da NFS-e, em reais." }, "valorTotalNfse": { "type": "number", "description": "vTotNF: Valor Líquido da NFS-e + IBS/CBS, em reais. É o valor a cobrar (guia de integração)." }, "baseCalculo": { "type": "number", "description": "Base de cálculo do IBS/CBS, em reais." }, "ibs": { "type": "object", "description": "IBS: valor total e as esferas estadual e municipal.", "required": [ "valorTotal", "estadual", "municipal" ], "properties": { "valorTotal": { "type": "number", "description": "Valor total do IBS, em reais." }, "estadual": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "IBS estadual: alíquota, alíquota efetiva e valor apurado." }, "municipal": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "IBS municipal: alíquota, alíquota efetiva e valor apurado." } } }, "cbs": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "CBS: alíquota, alíquota efetiva e valor apurado." } } }, "substitui": { "type": "object", "description": "Presente somente na nota substituta, em qualquer status: a nota original que ela substitui e o motivo informado no pedido.", "required": [ "notaId", "chaveAcesso", "cMotivo" ], "properties": { "notaId": { "type": "string", "format": "uuid", "description": "Identificador da nota original." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da nota original (chSubstda da DPS)." }, "cMotivo": { "type": "string", "enum": [ "01", "02", "03", "04", "05", "99" ], "description": "Motivo da substituição informado no pedido." }, "xMotivo": { "type": "string", "description": "Descrição do motivo informada no pedido, quando houver." } } }, "substituidaPor": { "type": "object", "description": "Presente somente quando o status é substituida: a nota substituta autorizada.", "required": [ "notaId", "chaveAcesso" ], "properties": { "notaId": { "type": "string", "format": "uuid", "description": "Identificador da nota substituta." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da nota substituta." } } } } } } } }, "400": { "description": "Parâmetro fora do formato (VALIDACAO_CAMPO, com o detalhe em campos).", "content": { "application/json": { "schema": { "type": "object", "description": "Parâmetro fora do formato (VALIDACAO_CAMPO, com o detalhe em campos).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "401": { "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "content": { "application/json": { "schema": { "type": "object", "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "404": { "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "content": { "application/json": { "schema": { "type": "object", "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "429": { "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "content": { "application/json": { "schema": { "type": "object", "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } } } } }, "/notas/{notaId}/xml": { "get": { "operationId": "baixarXml", "summary": "Baixar o XML autorizado da nota", "tags": [ "Documentos fiscais" ], "description": "Devolve o XML autorizado da NFS-e, exatamente como recebido da Sefin Nacional (application/xml). Só existe para nota com XML autorizado. Tem limite de requisições próprio, separado das demais rotas.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "in": "path", "name": "notaId", "required": true, "description": "Identificador da nota, devolvido no envio do lote e na consulta." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "XML autorizado da NFS-e, exatamente como recebido da Sefin Nacional.", "content": { "application/xml": { "schema": { "type": "string" } } } }, "400": { "description": "Identificador da nota fora do formato UUID (VALIDACAO_CAMPO).", "content": { "application/json": { "schema": { "type": "object", "description": "Identificador da nota fora do formato UUID (VALIDACAO_CAMPO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "401": { "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "content": { "application/json": { "schema": { "type": "object", "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "404": { "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "content": { "application/json": { "schema": { "type": "object", "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "409": { "description": "Nota ainda não autorizada: o XML só existe para nota autorizada (NOTA_NAO_AUTORIZADA).", "content": { "application/json": { "schema": { "type": "object", "description": "Nota ainda não autorizada: o XML só existe para nota autorizada (NOTA_NAO_AUTORIZADA).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "429": { "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "content": { "application/json": { "schema": { "type": "object", "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } } } } }, "/notas/{notaId}/danfse": { "get": { "operationId": "baixarDanfse", "summary": "Baixar o DANFSe (PDF) da nota", "tags": [ "Documentos fiscais" ], "description": "Devolve o DANFSe em PDF, gerado na hora a partir do XML autorizado da NFS-e. Só existe para nota com XML autorizado. Tem limite de requisições próprio, compartilhado com o download do XML.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "in": "path", "name": "notaId", "required": true, "description": "Identificador da nota, devolvido no envio do lote e na consulta." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "DANFSe em PDF, gerado sob demanda a partir do XML autorizado da NFS-e.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Identificador da nota fora do formato UUID (VALIDACAO_CAMPO).", "content": { "application/json": { "schema": { "type": "object", "description": "Identificador da nota fora do formato UUID (VALIDACAO_CAMPO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "401": { "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "content": { "application/json": { "schema": { "type": "object", "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "404": { "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "content": { "application/json": { "schema": { "type": "object", "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "409": { "description": "Nota ainda não autorizada: o DANFSe só existe para nota autorizada (NOTA_NAO_AUTORIZADA).", "content": { "application/json": { "schema": { "type": "object", "description": "Nota ainda não autorizada: o DANFSe só existe para nota autorizada (NOTA_NAO_AUTORIZADA).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "429": { "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "content": { "application/json": { "schema": { "type": "object", "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "503": { "description": "Geração de DANFSe temporariamente ocupada (DANFSE_INDISPONIVEL_TEMPORARIAMENTE); repita depois dos segundos indicados no cabeçalho Retry-After.", "content": { "application/json": { "schema": { "type": "object", "description": "Geração de DANFSe temporariamente ocupada (DANFSE_INDISPONIVEL_TEMPORARIAMENTE); repita depois dos segundos indicados no cabeçalho Retry-After.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } } } } }, "/notas/{notaId}/cancelamento": { "post": { "operationId": "solicitarCancelamento", "summary": "Cancelar nota autorizada", "tags": [ "Cancelamento" ], "description": "Pede o cancelamento da nota (evento 101101), processado de forma assíncrona. O resultado (cancelada ou cancelamento_rejeitado) chega por webhook e aparece em GET /notas/{notaId}. Repetir o pedido de uma nota já em cancelamento ou cancelada devolve o pedido existente, sem novo evento. A classificação opcional cMotivo (1, 2 ou 9; padrão 9) vai ao evento e volta no pedido; no pedido repetido vale o código do pedido existente.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Pedido de cancelamento.", "required": [ "motivo" ], "additionalProperties": false, "properties": { "motivo": { "type": "string", "description": "Motivo do cancelamento: 15 a 255 caracteres depois de remover os espaços das pontas, só caracteres de U+0020 a U+00FF (sem quebra de linha, travessão, aspas curvas ou emoji)." }, "cMotivo": { "type": "string", "description": "Classificação do motivo: 1 erro na emissão, 2 serviço não prestado, 9 outros. Sem o campo, vale 9." } } }, "example": { "motivo": "Serviço cobrado em duplicidade na fatura", "cMotivo": "1" } } }, "description": "Pedido de cancelamento." }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "in": "path", "name": "notaId", "required": true, "description": "Identificador da nota, devolvido no envio do lote e na consulta." } ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Pedido de cancelamento aceito (ou o pedido existente, quando repetido).", "content": { "application/json": { "schema": { "type": "object", "description": "Pedido de cancelamento aceito (ou o pedido existente, quando repetido).", "required": [ "status", "motivo", "cMotivo", "solicitadoEm" ], "properties": { "status": { "type": "string", "enum": [ "solicitado", "registrado", "rejeitado" ], "description": "Situação do pedido: solicitado (aguardando a Sefin Nacional), registrado ou rejeitado." }, "motivo": { "type": "string", "description": "Motivo gravado, sem espaços nas pontas." }, "cMotivo": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Classificação do motivo enviada à Sefin no pedido: 1 erro na emissão, 2 serviço não prestado, 9 outros. É a informada pelo sistema consumidor ou 9 quando não informada; sempre presente." }, "solicitadoEm": { "type": "string", "format": "date-time", "description": "Instante do pedido (ISO 8601)." }, "registradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando o status é registrado." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitado: código e motivo da rejeição da Sefin.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } } } }, "example": { "status": "solicitado", "motivo": "Serviço cobrado em duplicidade na fatura", "cMotivo": "1", "solicitadoEm": "2026-11-10T14:03:12.345Z" } } } }, "400": { "description": "Pedido fora do formato: notaId, corpo, motivo longo ou com caractere não permitido, ou cMotivo inválido (VALIDACAO_CAMPO).", "content": { "application/json": { "schema": { "type": "object", "description": "Pedido fora do formato: notaId, corpo, motivo longo ou com caractere não permitido, ou cMotivo inválido (VALIDACAO_CAMPO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "401": { "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "content": { "application/json": { "schema": { "type": "object", "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "404": { "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "content": { "application/json": { "schema": { "type": "object", "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "409": { "description": "A nota não admite cancelamento no estado atual: não autorizada (NOTA_NAO_AUTORIZADA), substituída, com substituição em andamento ou com análise fiscal pendente, indeferida ou deferida (NOTA_EM_ESTADO_INCOMPATIVEL).", "content": { "application/json": { "schema": { "type": "object", "description": "A nota não admite cancelamento no estado atual: não autorizada (NOTA_NAO_AUTORIZADA), substituída, com substituição em andamento ou com análise fiscal pendente, indeferida ou deferida (NOTA_EM_ESTADO_INCOMPATIVEL).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "422": { "description": "Motivo com menos de 15 caracteres depois de remover os espaços das pontas (MOTIVO_CANCELAMENTO_CURTO).", "content": { "application/json": { "schema": { "type": "object", "description": "Motivo com menos de 15 caracteres depois de remover os espaços das pontas (MOTIVO_CANCELAMENTO_CURTO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "429": { "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "content": { "application/json": { "schema": { "type": "object", "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } } } } }, "/notas/{notaId}/analise-fiscal": { "post": { "operationId": "solicitarAnaliseFiscal", "summary": "Pedir análise fiscal para cancelamento de nota autorizada", "tags": [ "Análise fiscal" ], "description": "Pede ao município a análise fiscal para cancelamento da nota (evento 101103), processada de forma assíncrona: use quando o cancelamento direto não é mais aceito (por exemplo, cancelamento_rejeitado com E0822, fora do prazo). A nota continua autorizada durante a análise. O registro do pedido na Sefin chega pelo webhook analise_fiscal_registrada (ou analise_fiscal_rejeitada); a decisão do município, que pode levar dias, chega como cancelada (deferido) ou analise_fiscal_indeferida (indeferido) e aparece em analiseFiscal de GET /notas/{notaId}. Repetir o pedido de uma nota com pedido ativo devolve o pedido existente, sem novo evento. O motivo segue as mesmas regras do cancelamento. A classificação opcional cMotivo (1, 2 ou 9; padrão 9) vai ao evento e volta no pedido; no pedido repetido vale o código do pedido existente.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Pedido de análise fiscal para cancelamento.", "required": [ "motivo" ], "additionalProperties": false, "properties": { "motivo": { "type": "string", "description": "Motivo do pedido de cancelamento dirigido ao município: 15 a 255 caracteres depois de remover os espaços das pontas, só caracteres de U+0020 a U+00FF (sem quebra de linha, travessão, aspas curvas ou emoji)." }, "cMotivo": { "type": "string", "description": "Classificação do motivo: 1 erro na emissão, 2 serviço não prestado, 9 outros. Sem o campo, vale 9." } } }, "example": { "motivo": "Serviço não prestado conforme o contrato", "cMotivo": "2" } } }, "description": "Pedido de análise fiscal para cancelamento." }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "in": "path", "name": "notaId", "required": true, "description": "Identificador da nota, devolvido no envio do lote e na consulta." } ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Pedido de análise fiscal aceito (ou o pedido existente, quando repetido).", "content": { "application/json": { "schema": { "type": "object", "description": "Pedido de análise fiscal aceito (ou o pedido existente, quando repetido).", "required": [ "status", "motivo", "cMotivo", "solicitadoEm" ], "properties": { "status": { "type": "string", "enum": [ "solicitado", "registrado", "rejeitado" ], "description": "Situação do pedido: solicitado (aguardando a Sefin Nacional), registrado ou rejeitado." }, "motivo": { "type": "string", "description": "Motivo gravado, sem espaços nas pontas." }, "cMotivo": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Classificação do motivo enviada à Sefin no pedido (informada pelo sistema consumidor): 1 erro na emissão, 2 serviço não prestado, 9 outros; 9 quando não informada; sempre presente. Não é a decisão do município, que fica em resultado.codigoMotivo." }, "solicitadoEm": { "type": "string", "format": "date-time", "description": "Instante do pedido (ISO 8601)." }, "registradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando o status é registrado: registro do pedido na Sefin." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitado: código e motivo da rejeição da Sefin.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } }, "resultado": { "type": "object", "description": "Presente somente quando o município decidiu: 105104 (deferido, a nota fica cancelada) ou 105105 (indeferido, a nota continua autorizada).", "required": [ "evento", "decisao", "codigoMotivo", "motivo", "decididoEm" ], "properties": { "evento": { "type": "string", "enum": [ "105104", "105105" ], "description": "Evento do município: 105104 (deferimento) ou 105105 (indeferimento)." }, "decisao": { "type": "string", "enum": [ "deferido", "indeferido" ], "description": "Decisão do município." }, "codigoMotivo": { "type": "string", "enum": [ "1", "2" ], "description": "Código do motivo do município: no indeferimento, 2 = indeferido sem análise de mérito." }, "motivo": { "type": "string", "description": "Justificativa do município." }, "processoAdministrativo": { "type": "string", "description": "Número do processo administrativo, se informado." }, "decididoEm": { "type": "string", "format": "date-time", "description": "Instante da decisão do município (ISO 8601)." } } }, "acompanhamentoEncerradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando a consulta automática do resultado terminou sem decisão do município (fim da janela de acompanhamento). Não é decisão: o município ainda pode decidir; para retomar o acompanhamento, fale com a LideraNota." } } }, "example": { "status": "solicitado", "motivo": "Serviço não prestado conforme o contrato", "cMotivo": "2", "solicitadoEm": "2026-11-10T14:03:12.345Z" } } } }, "400": { "description": "Pedido fora do formato: notaId, corpo, motivo longo ou com caractere não permitido, ou cMotivo inválido (VALIDACAO_CAMPO).", "content": { "application/json": { "schema": { "type": "object", "description": "Pedido fora do formato: notaId, corpo, motivo longo ou com caractere não permitido, ou cMotivo inválido (VALIDACAO_CAMPO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "401": { "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "content": { "application/json": { "schema": { "type": "object", "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "404": { "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "content": { "application/json": { "schema": { "type": "object", "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "409": { "description": "A nota não admite análise fiscal no estado atual: não autorizada (NOTA_NAO_AUTORIZADA), já cancelada, substituída, com cancelamento ou substituição em andamento (NOTA_EM_ESTADO_INCOMPATIVEL).", "content": { "application/json": { "schema": { "type": "object", "description": "A nota não admite análise fiscal no estado atual: não autorizada (NOTA_NAO_AUTORIZADA), já cancelada, substituída, com cancelamento ou substituição em andamento (NOTA_EM_ESTADO_INCOMPATIVEL).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "422": { "description": "Motivo com menos de 15 caracteres depois de remover os espaços das pontas (MOTIVO_CANCELAMENTO_CURTO).", "content": { "application/json": { "schema": { "type": "object", "description": "Motivo com menos de 15 caracteres depois de remover os espaços das pontas (MOTIVO_CANCELAMENTO_CURTO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "429": { "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "content": { "application/json": { "schema": { "type": "object", "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } } } } }, "/notas/{notaId}/substituicao": { "post": { "operationId": "substituirNota", "summary": "Substituir nota autorizada", "tags": [ "Substituição" ], "description": "Pede a substituição da nota autorizada {notaId} por uma nota corrigida, processada de forma assíncrona como uma nota nova (DPS com novo número da série e o grupo subst). A resposta 202 traz a nota substituta (status recebida, com substitui). Autorizada a substituta, a original passa a substituida e chegam os webhooks autorizada (substituta) e substituida (original). Rejeitada a substituta, chega só o webhook rejeitada da substituta e a original continua autorizada. Repetir o pedido com o mesmo nota.idOperacao para a mesma original devolve a substituta existente.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Pedido de substituição: a nota corrigida e o motivo.", "required": [ "nota", "cMotivo" ], "additionalProperties": false, "properties": { "nota": { "type": "object", "properties": { "idOperacao": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Identificador da operação no sistema do cliente (por exemplo, o código da fatura): 1 a 64 caracteres. É a chave de idempotência: reenviar o mesmo idOperacao devolve a nota já recebida, sem emitir outra." }, "competencia": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Data de competência do serviço, no formato AAAA-MM-DD." }, "tomador": { "description": "Tomador do serviço, somente nacional. Ausente, a nota sai sem tomador identificado (exige ISSQN não retido). Com o envio do IBS/CBS ligado, obrigatório, com endereco, nos serviços cujo indicador de operação exige o tomador (E0234).", "type": "object", "properties": { "documento": { "type": "string", "pattern": "^(\\d{11}|[0-9A-Z]{12}\\d{2})$", "description": "CPF (11 dígitos) ou CNPJ (14 caracteres: 12 dígitos ou letras maiúsculas e 2 dígitos verificadores numéricos; CNPJ alfanumérico aceito), sem pontuação, com dígito verificador válido." }, "nome": { "type": "string", "maxLength": 300, "description": "Nome ou razão social: até 300 caracteres, não vazio." }, "email": { "description": "E-mail (opcional): endereço válido com até 80 caracteres.", "type": "string", "maxLength": 80, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "telefone": { "description": "Telefone com DDD (opcional): 10 ou 11 dígitos, sem pontuação.", "type": "string", "pattern": "^\\d{10,11}$" }, "endereco": { "description": "Endereço nacional do tomador. Obrigatório quando o tomador é CNPJ ou a nota tem valores.issRetido = true; opcional para tomador CPF sem retenção.", "type": "object", "properties": { "cep": { "type": "string", "pattern": "^\\d{8}$", "description": "CEP com 8 dígitos, sem pontuação." }, "logradouro": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[\\u0020-\\u00FF]*$", "description": "Logradouro: 1 a 255 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos." }, "numero": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[\\u0020-\\u00FF]*$", "description": "Número do endereço: 1 a 60 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos." }, "complemento": { "description": "Complemento do endereço (opcional): 1 a 156 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos.", "type": "string", "minLength": 1, "maxLength": 156, "pattern": "^[\\u0020-\\u00FF]*$" }, "bairro": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[\\u0020-\\u00FF]*$", "description": "Bairro: 1 a 60 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos." }, "codigoMunicipio": { "type": "string", "pattern": "^\\d{7}$", "description": "Código IBGE do município, com 7 dígitos." } }, "required": [ "cep", "logradouro", "numero", "bairro", "codigoMunicipio" ], "additionalProperties": false } }, "required": [ "documento", "nome" ], "additionalProperties": false }, "servico": { "type": "object", "properties": { "codigoTributacaoNacional": { "type": "string", "pattern": "^\\d{6}$", "description": "Código de tributação nacional (cTribNac): 6 dígitos, com o zero à esquerda (010701, não 10701), existente na lista nacional de serviços." }, "codigoTributacaoMunicipal": { "description": "Código de tributação municipal (cTribMun): 3 dígitos, diferente de 000. Exigido conforme o cadastro do serviço do emitente.", "type": "string", "pattern": "^\\d{3}$" }, "codigoNbs": { "description": "Código NBS (cNBS): 9 dígitos, sem pontos (1.1501.10.00 vira 115011000), existente na tabela NBS. Opcional; com o envio do IBS/CBS ligado, obrigatório quando o serviço não tem cNBS cadastrado (E0322). Informado na nota, prevalece sobre o cadastrado.", "type": "string", "pattern": "^\\d{9}$" }, "descricao": { "type": "string", "maxLength": 2000, "description": "Discriminação do serviço: até 2000 caracteres, não vazia; quebra de linha permitida." }, "codigoMunicipioPrestacao": { "description": "Código IBGE do município de prestação, com 7 dígitos (opcional). Sem o campo, vale o município de prestação padrão cadastrado para o emitente.", "type": "string", "pattern": "^\\d{7}$" } }, "required": [ "codigoTributacaoNacional", "descricao" ], "additionalProperties": false, "description": "Serviço prestado." }, "valores": { "type": "object", "properties": { "valorServico": { "description": "Valor do serviço em reais, como número JSON (não texto), mínimo 0.01 e no máximo 2 casas decimais (ex.: 150.25).", "type": "number", "minimum": 0.01 }, "issRetido": { "description": "ISSQN retido pelo tomador. Obrigatório para prestador do Simples Nacional (ME/EPP e MEI); opcional para não optante (opSimpNac = 1), que pode usar valores.tpRetISSQN (os dois juntos devem concordar: true somente com 2, false somente com 1; ambos ausentes = não retido). Proibido para MEI (E0583). true exige tomador com endereco e, para prestador com regApTribSN = 1, valores.aliquotaSimples.", "type": "boolean" }, "aliquotaSimples": { "description": "Alíquota do Simples Nacional em percentual. Obrigatória somente quando valores.issRetido = true e regApTribSN = 1 no cadastro. Recusada sem retenção e para regApTribSN 2 ou 3. Proibida para MEI (E0600), inclusive zero, e para não optante (E0617).", "type": "number", "minimum": 1.8, "maximum": 5 }, "tribISSQN": { "description": "Somente não optante (opSimpNac = 1). Tributação do ISSQN: 1 = operação tributável (padrão quando omitido), 2 = imunidade (exige tpImunidade), 4 = não incidência. Imunidade e não incidência proíbem retenção (E0580) e suspensão (E0585) e exigem regEspTrib = 0 no cadastro (E0172).", "type": "number", "enum": [ 1, 2, 4 ] }, "tpImunidade": { "description": "Somente não optante. Tipo de imunidade (1 a 5): obrigatório e permitido somente com tribISSQN = 2 (E0592).", "type": "number", "enum": [ 1, 2, 3, 4, 5 ] }, "exigSusp": { "description": "Somente não optante. Exigibilidade do ISSQN suspensa (tpSusp e nProcesso juntos): permitida somente com operação tributável (tribISSQN = 1; E0585).", "type": "object", "properties": { "tpSusp": { "type": "number", "enum": [ 1, 2 ], "description": "1 = decisão judicial; 2 = processo administrativo." }, "nProcesso": { "type": "string", "pattern": "^[0-9]{30}$", "description": "Número do processo judicial ou administrativo da suspensão: exatamente 30 dígitos (0 a 9), padrão TSNumProcExigSuspensa do XSD. Nenhum ajuste é feito no valor (sem remoção de espaços ou pontuação e sem completar com zeros à esquerda); valor fora do padrão recusa a nota na recepção." } }, "required": [ "tpSusp", "nProcesso" ], "additionalProperties": false }, "tpRetISSQN": { "description": "Somente não optante. Retenção do ISSQN: 1 = não retido, 2 = retido pelo tomador (exige tomador com endereco, E0237), 3 = retido pelo intermediário (exige intermediario com endereco e tomador com endereco; omita issRetido). Retenção 2 ou 3 é recusada com regime especial no cadastro (E0588).", "type": "number", "enum": [ 1, 2, 3 ] }, "totTrib": { "description": "Somente não optante. Total aproximado dos tributos: exatamente um entre vTotTrib (valores) e pTotTrib (percentuais), com os três membros. Ausente, usa os percentuais do cadastro do prestador; sem nenhum dos dois, a nota é recusada (E0713). A nota com o grupo válido prevalece integralmente sobre o cadastro.", "type": "object", "properties": { "vTotTrib": { "description": "Total aproximado dos tributos em valor (reais, texto com até 2 casas): vTotTribFed, vTotTribEst e vTotTribMun, cada um de 0 até o valor do serviço.", "type": "object", "properties": { "vTotTribFed": { "type": "string", "description": "Valor aproximado dos tributos federais, em reais, como texto sem sinal, vírgula, expoente nem espaços, com até 15 dígitos inteiros e no máximo 2 casas decimais (ex.: \"12.34\"), de 0 até o valor do serviço." }, "vTotTribEst": { "type": "string", "description": "Valor aproximado dos tributos estaduais, em reais, como texto sem sinal, vírgula, expoente nem espaços, com até 15 dígitos inteiros e no máximo 2 casas decimais (ex.: \"12.34\"), de 0 até o valor do serviço." }, "vTotTribMun": { "type": "string", "description": "Valor aproximado dos tributos municipais, em reais, como texto sem sinal, vírgula, expoente nem espaços, com até 15 dígitos inteiros e no máximo 2 casas decimais (ex.: \"12.34\"), de 0 até o valor do serviço." } }, "required": [ "vTotTribFed", "vTotTribEst", "vTotTribMun" ], "additionalProperties": false }, "pTotTrib": { "description": "Total aproximado dos tributos em percentual (texto de 0 a 100 com até 2 casas): pTotTribFed, pTotTribEst e pTotTribMun.", "type": "object", "properties": { "pTotTribFed": { "type": "string", "description": "Percentual aproximado dos tributos federais, em percentual, como texto de 0 a 100 sem sinal, vírgula, expoente nem espaços, com no máximo 2 casas decimais (ex.: \"13.45\")." }, "pTotTribEst": { "type": "string", "description": "Percentual aproximado dos tributos estaduais, em percentual, como texto de 0 a 100 sem sinal, vírgula, expoente nem espaços, com no máximo 2 casas decimais (ex.: \"13.45\")." }, "pTotTribMun": { "type": "string", "description": "Percentual aproximado dos tributos municipais, em percentual, como texto de 0 a 100 sem sinal, vírgula, expoente nem espaços, com no máximo 2 casas decimais (ex.: \"13.45\")." } }, "required": [ "pTotTribFed", "pTotTribEst", "pTotTribMun" ], "additionalProperties": false } }, "additionalProperties": false }, "tribFed": { "description": "Tributos federais da nota: PIS/COFINS (piscofins) e retenções vRetCP, vRetIRRF e vRetCSLL, todos calculados e informados pelo seu sistema; a LideraNota confere formato e coerência e nunca calcula, completa ou arredonda os valores. Valores em reais e alíquotas em percentual, como texto com no máximo 2 casas. Aceito para não optante e ME/EPP; proibido para MEI (E0676). Ausente, a DPS sai sem o grupo. Independente de totTrib (nenhum alimenta o outro).", "type": "object", "properties": { "piscofins": { "description": "PIS/COFINS da nota (TCTribOutrosPisCofins): CST obrigatório; base, alíquotas, valores e tpRetPisCofins opcionais.", "type": "object", "properties": { "CST": { "type": "string", "enum": [ "00", "01", "02", "03", "04", "05", "06", "07", "08", "09", "49", "50", "51", "52", "53", "54", "55", "56", "60", "61", "62", "63", "64", "65", "66", "67", "70", "71", "72", "73", "74", "75", "98", "99" ], "description": "CST do PIS/COFINS como texto de dois dígitos (TSTipoCST): 00 a 09, 49, 50 a 56, 60 a 67, 70 a 75, 98 ou 99. Obrigatório no grupo; o enquadramento é do consumidor." }, "vBCPisCofins": { "description": "Base de cálculo do PIS/COFINS em reais, texto com até 15 dígitos inteiros e 2 casas (ex.: \"1000.00\"). Obrigatória quando pAliqPis ou pAliqCofins é informada; não precisa ser igual ao valor do serviço, mas não pode ser maior que ele (E0677).", "type": "string" }, "pAliqPis": { "description": "Alíquota do PIS em percentual, texto de 0 a 99.99 com até 2 casas (\"0.65\" = 0,65%, não 0,0065). Quando informada, exige vBCPisCofins e vPis e confere vPis (E0694).", "type": "string" }, "pAliqCofins": { "description": "Alíquota da COFINS em percentual, texto de 0 a 99.99 com até 2 casas (\"3.00\" = 3%). Quando informada, exige vBCPisCofins e vCofins e confere vCofins (E0696).", "type": "string" }, "vPis": { "description": "Valor do PIS em reais, calculado pelo consumidor (texto com até 2 casas). Com pAliqPis, deve ficar a no máximo R$ 0,01 de vBCPisCofins × pAliqPis ÷ 100 arredondado para centavos pela regra half-even; nunca é recalculado nem corrigido.", "type": "string" }, "vCofins": { "description": "Valor da COFINS em reais, calculado pelo consumidor (texto com até 2 casas). Com pAliqCofins, deve ficar a no máximo R$ 0,01 de vBCPisCofins × pAliqCofins ÷ 100 arredondado para centavos pela regra half-even; nunca é recalculado nem corrigido.", "type": "string" }, "tpRetPisCofins": { "description": "Tipo de retenção do PIS/COFINS/CSLL (inteiro 0 a 9, tabela TSTipoRetPISCofins), sem valor padrão: ausente não significa não retido. 0 proíbe vRetCSLL (E0720); 1, 3, 4, 5, 6, 7, 8 e 9 exigem vRetCSLL (E0724).", "type": "number", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ] } }, "required": [ "CST" ], "additionalProperties": false }, "vRetCP": { "description": "Contribuição previdenciária retida em reais (texto com até 2 casas): maior que zero e menor que o valor do serviço (E0699).", "type": "string" }, "vRetIRRF": { "description": "IRRF retido em reais (texto com até 2 casas): maior que zero e menor que o valor do serviço (E0700).", "type": "string" }, "vRetCSLL": { "description": "Valor das contribuições retidas em reais (texto com até 2 casas), como informado pelo consumidor: maior que zero e menor que o valor do serviço (E0701); proibido com tpRetPisCofins 0 (E0720) e obrigatório com 1, 3 a 9 (E0724). Nunca derivado nem somado pela LideraNota.", "type": "string" } }, "additionalProperties": false } }, "required": [ "valorServico" ], "additionalProperties": false, "description": "Valores e tributação da nota." }, "informacoesComplementares": { "description": "Informações complementares da nota (opcional): 1 a 2000 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos.", "type": "string", "minLength": 1, "maxLength": 2000, "pattern": "^[\\u0020-\\u00FF]*$" }, "ibsCbs": { "type": "object", "properties": { "codigoIndicadorOperacao": { "description": "Indicador da operação (cIndOp, 6 dígitos, tabela oficial ANEXO_C). Sobrepõe o cadastrado para o serviço.", "type": "string", "pattern": "^\\d{6}$" }, "codigoSituacaoTributaria": { "description": "CST do IBS/CBS (3 dígitos). Informado junto com codigoClassificacaoTributaria ou nenhum dos dois; o par sobrepõe o cadastrado para o serviço.", "type": "string", "pattern": "^\\d{3}$" }, "codigoClassificacaoTributaria": { "description": "Classificação tributária do IBS/CBS (cClassTrib, 6 dígitos). Informado junto com codigoSituacaoTributaria ou nenhum dos dois; o par deve constar da tabela oficial, valer para a NFS-e e estar vigente.", "type": "string", "pattern": "^\\d{6}$" } }, "additionalProperties": false, "description": "Classificação IBS/CBS da nota (opcional). Só tem efeito quando o envio do grupo IBSCBS está ligado para o prestador; com ele desligado, é aceito e ignorado. Cada campo informado sobrepõe o cadastrado para o serviço (servico.codigoTributacaoNacional); com os três campos, a nota dispensa o cadastro. Objeto vazio equivale a grupo ausente." }, "intermediario": { "description": "Somente não optante (opSimpNac = 1). Intermediário do serviço (infDPS.interm), somente nacional, com as mesmas regras de identificação e endereço do tomador; o emitente continua sendo o prestador. Obrigatório, com endereco, quando valores.tpRetISSQN = 3. Intermediário com CNPJ exige endereco com qualquer retenção (E1388); com CPF, o endereço é opcional fora da retenção 3. A raiz do CNPJ do intermediário (8 primeiros caracteres) não pode ser a do prestador (E0262).", "type": "object", "properties": { "documento": { "type": "string", "pattern": "^(\\d{11}|[0-9A-Z]{12}\\d{2})$", "description": "CPF (11 dígitos) ou CNPJ (14 caracteres: 12 dígitos ou letras maiúsculas e 2 dígitos verificadores numéricos; CNPJ alfanumérico aceito), sem pontuação, com dígito verificador válido." }, "nome": { "type": "string", "maxLength": 300, "description": "Nome ou razão social: até 300 caracteres, não vazio." }, "email": { "description": "E-mail (opcional): endereço válido com até 80 caracteres.", "type": "string", "maxLength": 80, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "telefone": { "description": "Telefone com DDD (opcional): 10 ou 11 dígitos, sem pontuação.", "type": "string", "pattern": "^\\d{10,11}$" }, "endereco": { "description": "Endereço nacional do tomador. Obrigatório quando o tomador é CNPJ ou a nota tem valores.issRetido = true; opcional para tomador CPF sem retenção.", "type": "object", "properties": { "cep": { "type": "string", "pattern": "^\\d{8}$", "description": "CEP com 8 dígitos, sem pontuação." }, "logradouro": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[\\u0020-\\u00FF]*$", "description": "Logradouro: 1 a 255 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos." }, "numero": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[\\u0020-\\u00FF]*$", "description": "Número do endereço: 1 a 60 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos." }, "complemento": { "description": "Complemento do endereço (opcional): 1 a 156 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos.", "type": "string", "minLength": 1, "maxLength": 156, "pattern": "^[\\u0020-\\u00FF]*$" }, "bairro": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[\\u0020-\\u00FF]*$", "description": "Bairro: 1 a 60 caracteres de U+0020 a U+00FF (faixa Latin-1, sem tabulação nem quebra de linha); os espaços das pontas são removidos." }, "codigoMunicipio": { "type": "string", "pattern": "^\\d{7}$", "description": "Código IBGE do município, com 7 dígitos." } }, "required": [ "cep", "logradouro", "numero", "bairro", "codigoMunicipio" ], "additionalProperties": false } }, "required": [ "documento", "nome" ], "additionalProperties": false } }, "required": [ "idOperacao", "competencia", "servico", "valores" ], "additionalProperties": false, "description": "A nota corrigida completa, no mesmo formato de uma nota do lote, com um idOperacao novo. Não é um patch: todos os campos são reenviados." }, "cMotivo": { "type": "string", "enum": [ "01", "02", "03", "04", "05", "99" ], "description": "Motivo da substituição: 01 desenquadramento do Simples Nacional, 02 enquadramento no Simples Nacional, 03 inclusão retroativa de imunidade/isenção, 04 exclusão retroativa de imunidade/isenção, 05 rejeição pelo tomador ou intermediário, 99 outros." }, "xMotivo": { "type": "string", "description": "Descrição do motivo: 15 a 255 caracteres depois de remover os espaços das pontas, só caracteres de U+0020 a U+00FF. Obrigatória com cMotivo 99 (E0078)." } } }, "example": { "nota": { "idOperacao": "FAT-1001-S1", "competencia": "2026-11-10", "tomador": { "documento": "11222333000181", "nome": "Cliente Exemplo Ltda", "email": "financeiro@cliente.example", "endereco": { "cep": "30130000", "logradouro": "Rua Exemplo", "numero": "100", "bairro": "Centro", "codigoMunicipio": "3106200" } }, "servico": { "codigoTributacaoNacional": "010701", "descricao": "Desenvolvimento de sistema sob encomenda" }, "valores": { "valorServico": 1450, "issRetido": false } }, "cMotivo": "99", "xMotivo": "Correção do valor do serviço informado na nota" } } }, "description": "Pedido de substituição: a nota corrigida e o motivo." }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" }, "in": "path", "name": "notaId", "required": true, "description": "Identificador da nota original (a que será substituída)." } ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Pedido aceito: a nota substituta, com status recebida e substitui (ou a substituta existente, quando repetido).", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "idOperacao", "loteId", "status", "ambiente" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identificador da nota." }, "idOperacao": { "type": "string", "description": "Identificador da operação enviado pelo seu sistema." }, "loteId": { "type": "string", "format": "uuid", "description": "Identificador do lote que recebeu a nota." }, "status": { "type": "string", "enum": [ "recebida", "pronta", "enviada", "autorizada", "rejeitada", "pendente_intervencao", "cancelamento_solicitado", "cancelada", "substituida" ], "description": "Status da nota. recebida, pronta e enviada: em processamento. autorizada e rejeitada: desfecho (rejeitada traz erro com código e motivo). pendente_intervencao: a emissão não foi concluída e aguarda a análise da LideraNota; não é rejeição da nota. Não reenvie a nota com outro idOperacao (a DPS pode ter sido registrada na Sefin) e continue consultando: o status ainda pode mudar. cancelamento_solicitado e cancelada: cancelamento (cancelada: cancelamento direto ou deferimento da análise fiscal). substituida: a nota foi substituída por outra nota autorizada (substituidaPor); na Sefin ela fica cancelada por substituição." }, "ambiente": { "type": "string", "enum": [ "homologacao", "producao" ], "description": "Ambiente da NFS-e Nacional em que a nota é emitida: homologacao (produção restrita, sem validade jurídica) ou producao." }, "serie": { "type": "string", "description": "Série da DPS; presente depois que a DPS é montada." }, "numeroDps": { "type": "integer", "description": "Número da DPS na série; presente depois que a DPS é montada." }, "idDps": { "type": "string", "description": "Identificador da DPS; presente depois que a DPS é montada." }, "numeroNfse": { "type": "string", "description": "Número da NFS-e; presente quando autorizada." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da NFS-e (50 dígitos); presente quando autorizada." }, "autorizadaEm": { "type": "string", "format": "date-time", "description": "Instante da autorização da NFS-e (ISO 8601)." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitada: código e motivo da rejeição.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } }, "links": { "type": "object", "description": "Links absolutos dos documentos da nota. Presente somente quando a nota tem XML autorizado (autorizada, cancelamento_solicitado, cancelada e substituida).", "properties": { "xml": { "type": "string", "format": "uri", "description": "GET do XML autorizado da nota (application/xml), com o mesmo token de API." }, "danfse": { "type": "string", "format": "uri", "description": "GET do DANFSe da nota (application/pdf), gerado a partir do XML autorizado, com o mesmo token de API." } } }, "cancelamento": { "type": "object", "description": "Presente somente quando a nota tem algum pedido de cancelamento: o último pedido (evento 101101).", "required": [ "status", "motivo", "cMotivo", "solicitadoEm" ], "properties": { "status": { "type": "string", "enum": [ "solicitado", "registrado", "rejeitado" ], "description": "Situação do pedido: solicitado (aguardando a Sefin Nacional), registrado ou rejeitado." }, "motivo": { "type": "string", "description": "Motivo gravado, sem espaços nas pontas." }, "cMotivo": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Classificação do motivo enviada à Sefin no pedido: 1 erro na emissão, 2 serviço não prestado, 9 outros. É a informada pelo sistema consumidor ou 9 quando não informada; sempre presente." }, "solicitadoEm": { "type": "string", "format": "date-time", "description": "Instante do pedido (ISO 8601)." }, "registradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando o status é registrado." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitado: código e motivo da rejeição da Sefin.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } } } }, "analiseFiscal": { "type": "object", "description": "Presente somente quando a nota tem algum pedido de análise fiscal para cancelamento: o último pedido (evento 101103) e, quando houver, a decisão do município.", "required": [ "status", "motivo", "cMotivo", "solicitadoEm" ], "properties": { "status": { "type": "string", "enum": [ "solicitado", "registrado", "rejeitado" ], "description": "Situação do pedido: solicitado (aguardando a Sefin Nacional), registrado ou rejeitado." }, "motivo": { "type": "string", "description": "Motivo gravado, sem espaços nas pontas." }, "cMotivo": { "type": "string", "enum": [ "1", "2", "9" ], "description": "Classificação do motivo enviada à Sefin no pedido (informada pelo sistema consumidor): 1 erro na emissão, 2 serviço não prestado, 9 outros; 9 quando não informada; sempre presente. Não é a decisão do município, que fica em resultado.codigoMotivo." }, "solicitadoEm": { "type": "string", "format": "date-time", "description": "Instante do pedido (ISO 8601)." }, "registradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando o status é registrado: registro do pedido na Sefin." }, "erro": { "type": "object", "description": "Presente somente quando o status é rejeitado: código e motivo da rejeição da Sefin.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "E0315", "description": "Código da rejeição: o da Sefin Nacional (por exemplo, E0315) ou o da validação local." }, "mensagem": { "type": "string", "description": "Motivo da rejeição, em português." } } }, "resultado": { "type": "object", "description": "Presente somente quando o município decidiu: 105104 (deferido, a nota fica cancelada) ou 105105 (indeferido, a nota continua autorizada).", "required": [ "evento", "decisao", "codigoMotivo", "motivo", "decididoEm" ], "properties": { "evento": { "type": "string", "enum": [ "105104", "105105" ], "description": "Evento do município: 105104 (deferimento) ou 105105 (indeferimento)." }, "decisao": { "type": "string", "enum": [ "deferido", "indeferido" ], "description": "Decisão do município." }, "codigoMotivo": { "type": "string", "enum": [ "1", "2" ], "description": "Código do motivo do município: no indeferimento, 2 = indeferido sem análise de mérito." }, "motivo": { "type": "string", "description": "Justificativa do município." }, "processoAdministrativo": { "type": "string", "description": "Número do processo administrativo, se informado." }, "decididoEm": { "type": "string", "format": "date-time", "description": "Instante da decisão do município (ISO 8601)." } } }, "acompanhamentoEncerradoEm": { "type": "string", "format": "date-time", "description": "Presente somente quando a consulta automática do resultado terminou sem decisão do município (fim da janela de acompanhamento). Não é decisão: o município ainda pode decidir; para retomar o acompanhamento, fale com a LideraNota." } } }, "valoresIbsCbs": { "type": "object", "description": "Valores de IBS/CBS calculados pela Sefin, copiados do XML da NFS-e autorizada (a LideraNota não soma, não arredonda e não zera). Presente somente quando a nota tem XML autorizado e esse XML traz o grupo IBSCBS; ausente nas notas sem o grupo (envio desligado ou autorizadas antes da versão). Reais e percentuais como números JSON (0.9 = 0,90%).", "required": [ "valorLiquido", "valorTotalNfse", "baseCalculo", "ibs", "cbs" ], "properties": { "valorLiquido": { "type": "number", "description": "vLiq: Valor Líquido da NFS-e, em reais." }, "valorTotalNfse": { "type": "number", "description": "vTotNF: Valor Líquido da NFS-e + IBS/CBS, em reais. É o valor a cobrar (guia de integração)." }, "baseCalculo": { "type": "number", "description": "Base de cálculo do IBS/CBS, em reais." }, "ibs": { "type": "object", "description": "IBS: valor total e as esferas estadual e municipal.", "required": [ "valorTotal", "estadual", "municipal" ], "properties": { "valorTotal": { "type": "number", "description": "Valor total do IBS, em reais." }, "estadual": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "IBS estadual: alíquota, alíquota efetiva e valor apurado." }, "municipal": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "IBS municipal: alíquota, alíquota efetiva e valor apurado." } } }, "cbs": { "type": "object", "required": [ "aliquota", "aliquotaEfetiva", "valor" ], "properties": { "aliquota": { "type": "number", "description": "Alíquota em percentual (0.9 = 0,90%)." }, "aliquotaEfetiva": { "type": "number", "description": "Alíquota efetiva em percentual (0.9 = 0,90%)." }, "valor": { "type": "number", "description": "Valor em reais." } }, "description": "CBS: alíquota, alíquota efetiva e valor apurado." } } }, "substitui": { "type": "object", "description": "Presente somente na nota substituta, em qualquer status: a nota original que ela substitui e o motivo informado no pedido.", "required": [ "notaId", "chaveAcesso", "cMotivo" ], "properties": { "notaId": { "type": "string", "format": "uuid", "description": "Identificador da nota original." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da nota original (chSubstda da DPS)." }, "cMotivo": { "type": "string", "enum": [ "01", "02", "03", "04", "05", "99" ], "description": "Motivo da substituição informado no pedido." }, "xMotivo": { "type": "string", "description": "Descrição do motivo informada no pedido, quando houver." } } }, "substituidaPor": { "type": "object", "description": "Presente somente quando o status é substituida: a nota substituta autorizada.", "required": [ "notaId", "chaveAcesso" ], "properties": { "notaId": { "type": "string", "format": "uuid", "description": "Identificador da nota substituta." }, "chaveAcesso": { "type": "string", "description": "Chave de acesso da nota substituta." } } } }, "description": "Pedido aceito: a nota substituta, com status recebida e substitui (ou a substituta existente, quando repetido)." }, "example": { "id": "b2d4f6a8-1c3e-4a5b-8c7d-9e0f1a2b3c4d", "idOperacao": "FAT-1001-S1", "loteId": "9d8c7b6a-5f4e-4d3c-a2b1-0f9e8d7c6b5a", "status": "recebida", "ambiente": "homologacao", "substitui": { "notaId": "3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10", "chaveAcesso": "31062002211222333000181000000000012326110000001234", "cMotivo": "99", "xMotivo": "Correção do valor do serviço informado na nota" } } } } }, "400": { "description": "Pedido fora do formato: notaId, envelope, nota corrigida, cMotivo ou xMotivo (VALIDACAO_CAMPO, com o detalhe em campos).", "content": { "application/json": { "schema": { "type": "object", "description": "Pedido fora do formato: notaId, envelope, nota corrigida, cMotivo ou xMotivo (VALIDACAO_CAMPO, com o detalhe em campos).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "401": { "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "content": { "application/json": { "schema": { "type": "object", "description": "Token de acesso ausente, inválido ou revogado (TOKEN_INVALIDO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "404": { "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "content": { "application/json": { "schema": { "type": "object", "description": "Nota não encontrada para o token informado (NOTA_NAO_ENCONTRADA).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "409": { "description": "A nota original não admite substituição no estado atual (NOTA_NAO_AUTORIZADA ou NOTA_EM_ESTADO_INCOMPATIVEL), ou o idOperacao da nota corrigida já é usado por outra nota (ID_OPERACAO_EM_USO).", "content": { "application/json": { "schema": { "type": "object", "description": "A nota original não admite substituição no estado atual (NOTA_NAO_AUTORIZADA ou NOTA_EM_ESTADO_INCOMPATIVEL), ou o idOperacao da nota corrigida já é usado por outra nota (ID_OPERACAO_EM_USO).", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "422": { "description": "SUBSTITUICAO_NAO_PERMITIDA: a nota substituta altera campo que a Sefin não permite alterar na substituição (E0060 ou E0061); um item de campos por campo alterado.", "content": { "application/json": { "schema": { "type": "object", "description": "SUBSTITUICAO_NAO_PERMITIDA: a nota substituta altera campo que a Sefin não permite alterar na substituição (E0060 ou E0061); um item de campos por campo alterado.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "429": { "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "content": { "application/json": { "schema": { "type": "object", "description": "Limite de requisições por minuto excedido para o token (LIMITE_REQUISICOES_EXCEDIDO); repita depois dos segundos indicados no cabeçalho Retry-After.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } }, "503": { "description": "Tabelas oficiais da NFS-e Nacional não carregadas (TABELAS_OFICIAIS_INDISPONIVEIS): nada foi gravado; repita o pedido depois do Retry-After.", "content": { "application/json": { "schema": { "type": "object", "description": "Tabelas oficiais da NFS-e Nacional não carregadas (TABELAS_OFICIAIS_INDISPONIVEIS): nada foi gravado; repita o pedido depois do Retry-After.", "required": [ "codigo", "mensagem" ], "properties": { "codigo": { "type": "string", "example": "LOTE_ACIMA_DO_LIMITE", "description": "Código estável do erro, em maiúsculas; use o código, e não a mensagem, na lógica do seu sistema." }, "mensagem": { "type": "string", "description": "Mensagem em português que explica o erro." }, "campos": { "type": "array", "description": "Recusas por campo, quando o erro aponta campos da requisição.", "items": { "type": "object", "description": "Recusa de um campo da requisição.", "required": [ "campo", "mensagem" ], "properties": { "codigo": { "type": "string", "description": "Código estável da recusa fiscal, quando aplicável (por exemplo, o código da regra da NFS-e Nacional)." }, "campo": { "type": "string", "example": "servico.codigoTributacaoMunicipal", "description": "Caminho do campo recusado, com os nomes separados por ponto." }, "mensagem": { "type": "string", "description": "Motivo da recusa do campo, em português." } } } } } } } } } } } } }, "servers": [ { "url": "https://hml.nfse.lideraweb.com/v1", "description": "Homologação (produção restrita da NFS-e Nacional, notas sem validade jurídica)" }, { "url": "https://nfse.lideraweb.com/v1", "description": "Produção" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Lotes", "description": "Envio de notas em lote e consulta do lote. A recepção é imediata; a emissão acontece depois, em segundo plano." }, { "name": "Notas", "description": "Consulta da nota pelo identificador da nota ou pelo idOperacao do seu sistema." }, { "name": "Documentos fiscais", "description": "Download do XML autorizado e do DANFSe (PDF) da nota." }, { "name": "Cancelamento", "description": "Pedido de cancelamento de nota autorizada (evento 101101)." }, { "name": "Substituição", "description": "Substituição de nota autorizada por uma nota corrigida." }, { "name": "Análise fiscal", "description": "Pedido de análise fiscal para cancelamento, decidido pelo município (evento 101103)." }, { "name": "Webhook", "description": "Evento que a LideraNota envia ao endereço de webhook do seu sistema a cada desfecho de nota." } ], "x-webhooks": { "notaAtualizada": { "post": { "operationId": "receberEventoNota", "tags": [ "Webhook" ], "summary": "Receber evento de nota", "description": "Requisição que a LideraNota envia, por HTTPS, ao endereço de webhook do seu sistema a cada desfecho de nota. Confira o cabeçalho X-Lwnfse-Token antes de processar. Responda 2xx logo depois de gravar o evento e deixe o processamento para depois: qualquer status de 200 a 299 conta como entregue e o corpo da resposta é descartado. Qualquer outra resposta, tempo de resposta acima de 10 segundos ou erro de rede ou TLS gera nova tentativa, com intervalos de 1, 2, 4, 8, 16 e 32 minutos e depois a cada hora, por cerca de um dia. Redirecionamento (3xx) nunca é seguido e conta como falha. A situação pendente_intervencao não gera evento: consulte a nota.", "parameters": [ { "name": "X-Lwnfse-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Token de webhook do emitente, entregue pela LideraNota. Compare com o valor guardado no seu sistema em tempo constante; ausente ou diferente, responda 401 sem processar o evento. Não registre o valor em log." }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "description": "Sempre application/json, com o corpo em UTF-8." } ], "requestBody": { "required": true, "description": "Evento da nota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvento" } } } }, "responses": { "401": { "description": "Token ausente ou diferente: o evento não é processado e a LideraNota tenta de novo." }, "2XX": { "description": "Evento recebido (inclusive evento repetido ou de tipo desconhecido): a entrega termina." } } } } } }