{ "openapi": "3.0.0", "info": { "title": "API Nota Ligeira", "version": "1.0", "description": "API REST para emitir, consultar e cancelar **NFS-e do Padrão Nacional** (gov.br/nfse), acompanhar\neventos, receber notas de terceiros (DF-e) e ser avisado por **webhooks**. Esta página documenta só as\nrotas para integração por **token de API**; as telas do painel usam rotas próprias, fora deste documento.\n\n# Autenticação\nCrie um **token de API** no painel, no menu **Tokens de API** (só uma pessoa da equipe, logada, cria, edita,\nsubstitui ou revoga tokens — a API não gera token a partir de outro token), e envie-o em toda requisição:\n\n```http\nAuthorization: Bearer nfse_live_…\n```\n\nO token completo aparece **uma única vez**, na criação. No painel ele pode ser restrito a clientes e a IPs\nou redes (IPv4/IPv6/CIDR), ter validade (padrão 90 dias; a equipe é avisada 7 e 1 dia antes de vencer) e\nlimite próprio de requisições por minuto (até 600). Para trocar sem parar a integração, gere um\n**substituto**: o antigo continua valendo por 24 h a 7 dias e expira sozinho. A conta (tenant) vem sempre\ndo token — nunca do corpo. Cliente de outra conta responde `404`; cliente da conta fora da restrição do\ntoken responde `403`. Token vencido, revogado ou usado de IP fora da lista responde `401`\n(`tokens.expirado`, `tokens.ip_nao_autorizado`).\n\n# Escopos\nCada rota exige um escopo; sem ele a resposta é `403 insufficient_scope`. Um token recebe só escopos deste\ncatálogo (e nunca além das permissões de quem o criou):\n\n| Escopo | Permite |\n|---|---|\n| `nfse:write` | **Emitir e registrar eventos** — Emite NFS-e (uma a uma ou em lote), cancela, substitui e inutiliza. |\n| `nfe:write` | **Emitir NF-e e NFC-e** — Emite NF-e (modelo 55) e NFC-e (modelo 65), valida sem emitir, reenvia a rejeitada, cancela, registra a carta de correção e inutiliza numeração. Só em conta com a emissão de NF-e liberada. |\n| `nfse:read` | **Consultar notas** — Lista e consulta NFS-e emitidas, XML/DANFSe, situação e relatórios. |\n| `nfe:read` | **Consultar NF-e e NFC-e emitidas** — Lista e consulta as NF-e e NFC-e emitidas, os eventos, o XML e o DANFE, e as inutilizações. |\n| `dfe:read` | **Ler notas recebidas** — Lê as NFS-e e NF-e recebidas (distribuição DF-e), o XML, a configuração e a situação da busca. |\n| `dfe:write` | **Manifestar e configurar notas recebidas** — Registra a manifestação do destinatário nas NF-e recebidas (ciência, confirmação, desconhecimento, operação não realizada), liga/desliga a busca de NF-e do cliente e antecipa a busca. |\n| `webhooks:read` | **Ver webhooks** — Lista os webhooks e o histórico de entregas. |\n| `webhooks:write` | **Gerenciar webhooks** — Cria, altera, testa e remove webhooks. |\n| `empresas:read` | **Ver clientes e cadastros** — Lê clientes, tomadores, serviços e configurações fiscais (inclui tudo de cadastros:read e fiscal:read). |\n| `empresas:write` | **Alterar clientes e cadastros** — Cria e altera clientes, tomadores, serviços e configurações fiscais (inclui tudo de cadastros:write e fiscal:write). |\n| `cadastros:read` | **Ver tomadores e serviços** — Lê tomadores, serviços, regras serviço×tomador e produtos da NF-e; permite emitir pela forma por cadastros (com nfse:write ou nfe:write). |\n| `cadastros:write` | **Alterar tomadores e serviços** — Cria, altera, faz upsert e desativa tomadores, serviços, regras serviço×tomador e produtos da NF-e. |\n| `fiscal:read` | **Ver perfil fiscal** — Lê o perfil fiscal do cliente, as vigências de regime tributário, a situação do IBPT (nunca o token) e a configuração de NF-e/NFC-e (nunca o CSC). |\n| `fiscal:write` | **Alterar perfil fiscal** — Cria e altera vigências de regime tributário do cliente; cadastra, testa e remove o token do IBPT e liga/desliga o seu uso; altera a configuração de NF-e/NFC-e (IE, CRT, séries) e o CSC da NFC-e. |\n| `cert:read` | **Ver certificados** — Lê os dados (validade, titular) dos certificados digitais. |\n| `cert:write` | **Enviar certificados** — Envia e substitui certificados digitais A1 dos clientes. |\n| `cobrancas:read` | **Ver cobranças** — Lê as contas a receber (cobranças dos tomadores). |\n| `cobrancas:write` | **Gerenciar cobranças** — Gera, cancela e estorna cobranças dos tomadores. |\n| `audit:read` | **Ler auditoria** — Lê a trilha de auditoria da conta (ex.: para um SIEM). |\n\n# Cliente no caminho\nOperações sobre um cliente emitente usam o id no **caminho**: `/v1/clientes/{clienteId}/…`\n(ex.: `POST /v1/clientes/{clienteId}/nfse`). Obtenha o `clienteId` em `GET /v1/clientes`. Em\nlistagens, o filtro opcional por cliente vai na query.\n\n# Emissão por cadastros (motor de tributação)\nAlém da DPS completa, `POST /v1/clientes/{clienteId}/nfse` (e `…/batch`, `…/validar`) aceita a forma **por\ncadastros**: `servicoId` (ou `servicoCodigo`) + `tomadorId` (ou `tomadorCodigo`, ou `tomador` avulso) + `valor` +\n`competencia`. A plataforma resolve PIS/COFINS pelo regime do cliente **na competência**, retenções federais\n(IRRF, CSRF, INSS), ISS retido, alíquota do ISS e IBS/CBS do ano; blocos opcionais (`tributacao`, `servicos[0]`,\n`rtc`, `deducaoReducao`) prevalecem **campo a campo**. A resposta traz `origens` (de onde veio cada valor),\n`avisos` e `totais`; `…/validar` devolve a DPS resolvida (que pode ser reenviada completa). Serviço ou tomador\nde outro cliente/conta → `404` (`servico.nao_encontrado`, `tomador.nao_encontrado`); pendência (ex.: serviço\nsem alíquota de ISS e município sem parametrização) → `422 tributacao.pendente`. A forma completa continua igual.\nA forma por cadastros exige `nfse:write` **e** `cadastros:read` (ou `empresas:read`), porque a resposta traz dados do cadastro.\n\nIntegrações oficiais (F2b): com a calculadora oficial RFB/Serpro ligada para a conta, IBS/CBS (inclusive alíquotas\nreduzidas) vêm da calculadora e `versaoTabelasIbsCbs` traz a versão das tabelas usada (fora do ar → cálculo local e aviso\n`CALCULADORA_INDISPONIVEL`); a Lei 12.741 usa os tributos destacados (padrão) ou, para o cliente que cadastrou o PRÓPRIO token do IBPT e ligou `usarIbpt` (`…/ibpt`), a tabela IBPT vigente (`versaoIbpt`, \"Fonte: IBPT\" nas informações complementares); tomador\n`orgao_federal` com `natureza1234` no serviço retém pela tabela da IN RFB 1.234/2012 (sem a natureza → pendência\n`RETENCAO_ORGAO_NATUREZA`). As regras do par (`GET …/servicos/{servicoId}/regras`) e a lista unificada de regras e exigências por tomador (`GET …/regras-tomador`) são paginadas por cursor como as demais listas. A exigência de retenção que vale para todos os serviços de um tomador é gravada no cadastro dele (`exigeIrrfAliquota`, `exigeCsrf`, `exigeInssAliquota`).\n\n# Prioridade e origens\nNa forma por cadastros o motor decide **campo a campo**: para cada campo (alíquota do ISS, ISS retido, IRRF, CSRF, INSS,\nIBS/CBS…), vence o primeiro nível que o define, nesta ordem — a nota (ajuste ou bloco explícito) > a regra do par\nserviço×tomador > a exigência de retenção do tomador (todos os serviços) > o serviço > o tomador > o regime do cliente na competência > o município (ADN) e a lei. Pré-condições\nlegais vencem a ordem: prestador do Simples/MEI não sofre retenção federal e tomador pessoa física não retém tributos federais. Cada campo\nresolvido aparece em `origens` com a fonte, a base, a alíquota e o `fundamento`:\n\n| `fonte` | Significado |\n|---|---|\n| `nota` | Informado na própria nota (ajuste na tela ou bloco explícito da integração). Com `sobrescrito: true`, prevaleceu sobre o calculado (`anterior`). |\n| `regra_servico_tomador` | Regra fiscal do par serviço×tomador (`…/servicos/{servicoId}/regras/{tomadorId}`). |\n| `tomador_exigencia` | Exigência de retenção do tomador, valendo para todos os serviços (`exigeIrrfAliquota`, `exigeCsrf`, `exigeInssAliquota` no cadastro do tomador); `ref` é o id do tomador e `fundamento` traz o nome. |\n| `servico` | Padrão do cadastro do serviço. |\n| `tomador` | Cadastro do tomador (ex.: substituto tributário, veto de retenção). |\n| `cliente` | Cadastro do cliente emitente. Reservado: o motor não emite esta fonte hoje. |\n| `regime` | Regime tributário do cliente vigente na competência (perfil fiscal). |\n| `municipal_adn` | Parametrização do município de incidência no ADN (alíquota do ISS). |\n| `tabela_municipal` | Tabela municipal própria. Reservado: o motor não emite esta fonte hoje. |\n| `legislacao` | Regra legal padrão (LC 116, RIR/2018, Lei 10.833, LC 214…), com `fundamento`. `confirmar: true` = premissa ainda em revisão. |\n| `sugestao` | Sugestão não normativa (ex.: classificação IBS/CBS pelo Anexo VIII). Confirme e grave no cadastro. |\n| `calculado` | Resultado de conta do motor sobre os valores acima (`base` × `aliquota`). |\n| `dispensa` | Retenção calculada e dispensada por valor mínimo (até R$ 10,00); `anterior` traz o valor dispensado. |\n\n# Avisos e pendências do motor\n**Avisos** (`avisos`) não impedem a emissão: algo merece conferência. **Pendências** bloqueiam: a emissão responde\n`422 tributacao.pendente` com a lista em `pendencias`, e `…/validar` devolve as duas listas antes de emitir. Decida pelo\n`codigo` (estável), não pela `mensagem`; `campo` aponta o campo da DPS.\n\n| `codigo` | Tipo | Quando ocorre |\n|---|---|---|\n| `ADN_INDISPONIVEL` | aviso | Parametrização municipal (ADN) fora do ar no momento: a alíquota do ISS não pôde ser consultada. |\n| `AJUSTE_NAO_PERMITIDO` | **pendência** | Ajuste (`ajustes`) em campo que o motor sempre calcula e não aceita ajuste; retire o ajuste desse campo. |\n| `BASE_CALCULADA` | aviso | A base de PIS/COFINS é sempre calculada pelo motor; a base informada foi ignorada. |\n| `CALCULADORA_DIVERGENTE` | aviso | O resultado da calculadora oficial não corresponde à classificação ou base desta nota: usado o cálculo local. |\n| `CALCULADORA_INDISPONIVEL` | aviso | Calculadora oficial de IBS/CBS fora do ar ou sem resposta válida: usado o cálculo local (prévia). |\n| `CALCULADORA_SIMULADA` | aviso | A calculadora oficial marcou o cálculo como simulado (alíquotas ainda não definidas em lei). |\n| `CBS_NAO_PUBLICADA` | **pendência** | Alíquota de CBS do ano da competência ainda não publicada (LC 214/2025): o motor não reaproveita outro ano. |\n| `CPRB_FORA_DA_VIGENCIA` | aviso | Prestador optante pela CPRB em competência fora da vigência da retenção reduzida de INSS (3,5% até 31/12/2027): usada a alíquota do serviço. |\n| `CSRF_ALIQUOTA_DESTAQUE` | aviso | O leiaute tem um só vPIS/vCOFINS: os valores destacados seguem o regime e a retenção é indicada pelo tipo de retenção. |\n| `CSRF_DISPENSADA` | aviso | CSRF (PIS+COFINS+CSLL) calculada até R$ 10,00: dispensada nesta nota. A soma mensal é obrigação do tomador. |\n| `CSRF_SEM_GRUPO_PISCOFINS` | aviso | CSRF retida sem o grupo de PIS/COFINS: o total retido (vRetCSLL) vai sem o tipo de retenção. |\n| `DESCONTO_MAIOR_QUE_VALOR` | **pendência** | Desconto incondicionado igual ou maior que o valor do serviço (E1295): reduza o desconto. |\n| `DESCONTO_NEGATIVO` | **pendência** | Desconto incondicionado negativo. |\n| `DPS_INVALIDA` | **pendência** | A DPS resolvida não passou na validação do leiaute; `campo` aponta o caminho do erro. |\n| `EXIGENCIA_TOMADOR_CONFLITA_PF` | aviso | O tomador tem exigência de retenção federal cadastrada, mas não é pessoa jurídica: nada retido. |\n| `EXIGENCIA_TOMADOR_IGNORADA_EMITENTE` | aviso | O tomador exige retenção federal, mas o emitente é MEI ou pessoa física, cuja DPS não leva tributos federais (E0675/E0676): nada retido. |\n| `EXIGENCIA_TOMADOR_IGNORADA_SIMPLES` | aviso | O tomador exige IRRF ou CSRF, mas o prestador é do Simples/MEI na competência (IN SRF 765/2007; Lei 10.833/2003, art. 32, II): nada retido. |\n| `FEDERAIS_IGNORADOS` | aviso | Emitente pessoa física ou MEI não informa tributos federais na DPS (E0675/E0676): os valores informados foram ignorados. |\n| `FEDERAIS_IGNORADOS_EMITENTE` | aviso | Emitente MEI ou pessoa física (CPF) com retenções federais informadas na nota: foram ignoradas; a mensagem lista quais. |\n| `IBPT_SEM_ALIQUOTA` | aviso | Sem percentual IBPT para o NBS/subitem na UF do emitente: Lei 12.741 pelos tributos destacados. |\n| `IBPT_TEXTO_NAO_COUBE` | aviso | O texto da Lei 12.741 (Fonte: IBPT) passaria do limite das informações complementares: informe o valor aproximado dos tributos no documento ao consumidor. |\n| `IBPT_VENCIDA` | aviso | Tabela IBPT vencida: Lei 12.741 pelos tributos destacados até a próxima importação. |\n| `IBS_NAO_PUBLICADO` | **pendência** | Alíquota de IBS do ano da competência ainda não publicada (LC 214/2025): o motor não reaproveita outro ano. |\n| `IBSCBS_ANTES_2026` | aviso | IBS/CBS só a partir da competência 01/2026 (E0850): a classificação informada foi ignorada. |\n| `IBSCBS_APURADO_SEFIN` | aviso | Alíquota reduzida, monofásica ou suspensa depende do cClassTrib: o valor de IBS/CBS é apurado pela SEFIN. |\n| `IBSCBS_INCOMPLETO` | **pendência** | Classificação IBS/CBS incompleta: informe CST, cClassTrib e indicador de operação. |\n| `IBSCBS_SIMPLES` | aviso | Simples/MEI: IBS/CBS apurados no regime do Simples, sem prévia pela alíquota padrão. |\n| `IBSCBS_SUGESTAO` | aviso | Classificação IBS/CBS sugerida pelo Anexo VIII (não normativa): confirme e grave no cadastro do serviço. |\n| `INSS_MATERIAIS_MAIOR_QUE_BASE` | **pendência** | Materiais/equipamentos a excluir da base do INSS iguais ou maiores que o valor do serviço. |\n| `INSS_MATERIAIS_PISO` | aviso | Materiais/equipamentos do INSS sem valor discriminado limitados a 50% do valor (a base não pode ser menor que 50% do bruto — IN RFB 2.110/2022, art. 117, IV). |\n| `INSS_SIMPLES` | aviso | Prestador do Simples com INSS retido: a retenção só se aplica a serviços do Anexo IV (LC 123/2006, art. 18, § 5º-C) — confirme. |\n| `IRRF_DISPENSADO` | aviso | IRRF calculado até R$ 10,00: dispensado nesta nota. Somar pagamentos do mês ao mesmo prestador é obrigação do tomador. |\n| `ISS_ALIQUOTA_MAXIMA` | **pendência** | Alíquota de ISS acima de 5% (LC 116/2003, art. 8º, II). |\n| `ISS_ALIQUOTA_MINIMA` | **pendência** | Alíquota de ISS abaixo do mínimo de 2% (LC 116/2003, art. 8º-A), fora do Simples e dos subitens que a lei excetua. |\n| `ISS_ALIQUOTA_MINIMA_SN` | aviso | Prestador do Simples com alíquota de ISS abaixo de 2%: confira a faixa do Simples. |\n| `ISS_SEM_ALIQUOTA` | **pendência** | Serviço sem alíquota de ISS e município sem parametrização no ADN: informe a alíquota no cadastro do serviço. |\n| `ISS_SUBSTITUTO_OUTRO_MUNICIPIO` | aviso | O tomador é substituto tributário em outro município que não o de incidência: ISS não retido. |\n| `LOCAL_PRESTACAO_ASSUMIDO` | aviso | ISS devido no local da prestação sem o local informado: foi considerado o município do prestador. |\n| `MOTIVO_OBRIGATORIO` | **pendência** | Redução de uma retenção calculada pelo motor sem `motivo`; informe o motivo. |\n| `ORGAO_CODIGO_RECEITA` | aviso | Tomador órgão público federal: retenção pela IN RFB 1.234/2012; a mensagem traz o percentual e o código de receita. |\n| `ORGAO_DISPENSA` | aviso | Retenção da IN RFB 1.234/2012 abaixo de R$ 10,00: dispensada. |\n| `ORGAO_SIMPLES_DECLARACAO` | aviso | Prestador do Simples para órgão federal: sem retenção da IN RFB 1.234; entregue ao órgão a declaração do Anexo IV. |\n| `PIS_COFINS_SEM_CST` | **pendência** | PIS/COFINS sem CST: informe o CST (ou o regime do cliente na competência). |\n| `PIS_COFINS_SUGERE_CUMULATIVO` | aviso | Lucro Real com serviço de informática (1.01 a 1.08) no regime não cumulativo: costuma ser cumulativo (Lei 10.833/2003, art. 10, XXV). Defina o regime de PIS/COFINS do serviço. |\n| `PREMISSA_SEM_CONTADOR` | aviso | A nota usou uma interpretação fiscal ainda em revisão (premissa marcada \"a confirmar\", origem com `confirmar: true`): confira os valores. |\n| `REGIME_ESPECIAL_DEDUCAO_NOTA` | **pendência** | Dedução/redução informada na nota para prestador com regime especial de tributação (E0438): retire-a. |\n| `REGIME_ESPECIAL_IGNORADO` | aviso | Regime especial de tributação do ISS do perfil fiscal ignorado nesta nota (MEI, Simples com apuração pelo Simples, ou exigibilidade diferente de \"exigível\"): vai \"Nenhum\" (E0172/E0174/E0175). |\n| `REGIME_ESPECIAL_ISS` | aviso | Prestador com regime especial de tributação do ISS (regEspTrib ≠ 0): a NFS-e sai sem alíquota, base e valor de ISS e sem retenção (E0604, E1307, E0588); para profissional autônomo e sociedade de profissionais o ISS é fixo (DL 406/1968, art. 9º). |\n| `REGIME_ESPECIAL_SEM_ALIQUOTA` | **pendência** | Alíquota de ISS informada na nota para prestador com regime especial de tributação (E0604): retire a alíquota. |\n| `REGIME_ESPECIAL_SEM_BM` | aviso | Benefício municipal do serviço não é enviado com regime especial de tributação (E0535). |\n| `REGIME_ESPECIAL_SEM_DEDUCAO` | aviso | Dedução padrão do serviço não é enviada com regime especial de tributação (E0438). |\n| `REGIME_ESPECIAL_SEM_RETENCAO` | **pendência** | ISS retido informado na nota para prestador com regime especial de tributação (E0588). |\n| `REGIME_SEM_VIGENCIA` | aviso | Sem vigência de regime para a competência (ou competência anterior ao regime cadastrado): usado o regime atual do cadastro do cliente. |\n| `REGRA_CONFLITA_TOMADOR_PF` | aviso | A regra serviço×tomador pede retenção federal, mas o tomador não é pessoa jurídica: nada retido. |\n| `REGRA_IGNORADA_SIMPLES` | aviso | A regra serviço×tomador pede retenção federal, mas o prestador é do Simples/MEI na competência: nada retido. |\n| `RETENCAO_ORGAO_MANUAL` | **pendência** | Tomador estado, DF ou município: informe as retenções manualmente na nota. |\n| `RETENCAO_ORGAO_NATUREZA` | **pendência** | Tomador órgão público federal sem a natureza da IN RFB 1.234/2012 no serviço: informe a natureza (ex.: 6190). |\n| `RETENCAO_SUGERIDA_NAO_CONFIGURADA` | aviso | Tomador pessoa jurídica e subitem que costuma ter retenção de IRRF/CSRF, mas o serviço, a regra do par e a exigência do tomador não têm retenção configurada. O aviso traz a ação `aplicar_sugestao` (ajustes só desta nota, e `sugestao` com os parâmetros para gravar como regra ou exigência do tomador); o serviço nunca é alterado sozinho. |\n| `SIMPLES_SEM_PERCENTUAL_TOT_TRIB` | aviso | Prestador do Simples (ME/EPP) sem o percentual aproximado de tributos (Lei 12.741/2012; Decreto 8.264/2014, art. 2º) no perfil fiscal: informe-o (use a calculadora de alíquota efetiva). |\n| `VALOR_AUSENTE` | **pendência** | Nota sem valor e serviço sem valor padrão: informe `valor`. |\n| `VALOR_INFORMADO_DIFERE` | aviso | Um valor informado na nota prevaleceu sobre o que o motor calcularia; a mensagem traz os dois. |\n\n# Valores e arredondamento\nValores monetários e alíquotas trafegam como **texto decimal com ponto** (`\"1000.00\"`, `\"1.50\"` = 1,50%). Na DPS completa\no valor tem exatamente 2 casas; na forma por cadastros, `valor` aceita número, vírgula e até 2 casas (`100`, `\"100,5\"`).\n\nTodo arredondamento — tributos, retenções, totais, DANFSe — segue o **método bancário** (*half-even*, meio para o par),\nconforme a NT 007 SE/CGNFS-e (seção 2) do padrão nacional: o meio exato vai para o centavo par (10,005 → 10,00;\n10,015 → 10,02; 0,125 → 0,12) e os demais casos arredondam normalmente. Cada tributo é arredondado sobre a própria base;\npara conferir os totais do seu sistema com os da nota, use a mesma regra. O SEFIN aceita diferença de até R$ 0,01 em\nPIS/COFINS (NT 007).\n\n# Paginação das listagens\nNFS-e, clientes, webhooks e entregas, NFS-e recebidas, cadastros, NF-e e catálogos de referência usam `cursor` e `limit`.\n`limit` é um inteiro de 1 a 200 (padrão 50). Valores vazios, inválidos ou acima de 200 retornam `400 limit.invalido`.\nO corpo é um array; `X-Next-Cursor` indica a página seguinte e não vem na última. Repita os mesmos filtros e envie o cursor sem decodificá-lo.\nCursor inválido retorna `400 cursor.invalido`. O cursor não é um snapshot: mudanças em campos de ordenação/filtros podem alterar os resultados entre chamadas.\nNFS-e: emissão DESC + id DESC; clientes: razão social ASC + id ASC; webhooks/entregas: criação DESC + id DESC;\nNFS-e recebidas: recebimento DESC + id DESC; referências: código ASC (rejeições: código + documento). Cadastros e NF-e seguem a ordem descrita em cada operação.\nAs listas de DF-e retornam arrays; consulte a situação da busca nas rotas `…/dfe/situacao`. `limite` foi substituído por `limit`.\n```javascript\nlet cursor;\ndo {\n const params = new URLSearchParams({ limit: \"200\" });\n if (cursor) params.set(\"cursor\", cursor);\n const resposta = await fetch(baseUrl + \"/v1/nfse?\" + params, { headers: { Authorization: \"Bearer \" + token } });\n if (!resposta.ok) throw new Error(await resposta.text());\n const notas = await resposta.json(); // processe esta página\n cursor = resposta.headers.get(\"X-Next-Cursor\");\n} while (cursor);\n```\n\n# Cadastros (tomadores, serviços, regras e regime)\nO ERP pode manter os cadastros do cliente pela API — `…/tomadores`, `…/servicos`, `…/servicos/{servicoId}/regras/{tomadorId}`\n(regra fiscal do par serviço×tomador) e `…/regimes`/`…/perfil-fiscal` (regime tributário por competência). Escopos:\n`cadastros:read|write` (tomadores, serviços e regras) e `fiscal:read|write` (perfil fiscal e regimes); `empresas:read|write`\ncontinuam aceitos e valem por ambos.\n\n- **Upsert pela chave do ERP**, no corpo (nunca na URL): `PUT …/tomadores/upsert` pelo `documento` (ou pelo `codigo`, para\n tomador sem documento) e `PUT …/servicos/upsert` pelo `codigo`. `201` criado, `200` atualizado; reenviar o mesmo corpo não\n duplica, nem com requisições simultâneas.\n- **Listagens paginadas por cursor**: o corpo é um array (`limit` de 1 a 200, padrão 50) e a próxima página vem no cabeçalho\n `X-Next-Cursor` — repita a chamada com `cursor=` até o cabeçalho não vir. A ordem é estável (nome/descrição + id):\n inserções durante a leitura não duplicam nem pulam itens já percorridos. `atualizadoDesde` traz só o que mudou (sincronização\n incremental); `ativo=false` lista os desativados.\n- `POST` aceita `Idempotency-Key`; `PATCH` recusa campo desconhecido (`400`); `DELETE` desativa (o histórico fica).\n- Id de outro cliente ou de outra conta responde `404` (`tomador.nao_encontrado`, `servico.nao_encontrado`); documento ou\n código repetido, `409` (`tomador.documento_duplicado`, `tomador.codigo_duplicado`, `servico.codigo_duplicado`).\n\n# Idempotência\nEnvie `Idempotency-Key` (sugerimos UUID v4) nas rotas de escrita. Reenvio com a mesma chave e o mesmo\ncorpo devolve a mesma resposta; a mesma chave com corpo diferente responde `409` (na forma por cadastros vale o\ncorpo enviado: reenviar depois de mudar o cadastro devolve a nota já criada). No **lote**\n(`…/nfse/batch`, até 100 DPS) a chave passa a ser obrigatória no Sunset abaixo. A operação roda uma vez só:\npedidos simultâneos com a mesma chave esperam o primeiro e recebem a mesma resposta; se ele não concluir em 5 s,\n`409` `idempotency.em_andamento` com `Retry-After`. Respostas de erro não ficam guardadas (a chave pode ser repetida).\n\n# Plano e franquia\nCada nota autorizada **ou ainda em processamento** ocupa a franquia mensal do plano (mês no horário de Brasília); rejeitada\nlibera a vaga. A conferência é atômica: emissões simultâneas nunca passam da franquia. O **excedente é opcional** e\nvem desligado: só o Dono ou um administrador o liga, logado no painel, em **Plano e uso** — a API não o liga por token.\n\n- **Excedente desligado (padrão):** ao atingir a franquia, a emissão responde `402` `plano.limite`; o corpo traz `detalhes`\n (`franquia`, `notasMes`, `excedenteDisponivel`, `precoExcedenteNota` e `acoes`: `ativar_excedente` e/ou `trocar_plano`).\n No lote, os itens voltam com `code: plano.limite`.\n- **Excedente ligado:** a emissão continua acima da franquia e cada nota a mais é cobrada no fechamento pelo preço do plano.\n- **Plano pré-pago (créditos por nota):** não há franquia; cada nota debita o crédito da conta. Sem saldo, a emissão responde `402`\n `credito.saldo_insuficiente` com `detalhes` (`saldoCentavos`, `precoNotaCentavos`, `notasPossiveis`, `acoes: [adicionar_credito]`); no lote\n entram as notas que o saldo cobre. Nota rejeitada devolve o crédito. A recarga é feita no painel, em **Plano e uso**.\n- **Teste grátis encerrado:** `402` `plano.teste_expirado`. **Conta suspensa ou cancelada:** `402` ou `403` `tenant.inativo`.\n\n`…/validar` não emite e não conta na franquia. Trate o `402` como definitivo até a conta mudar o plano: reenviar não\nresolve.\n\n# Depreciações\nAs formas antigas continuam funcionando e respondem com os cabeçalhos:\n\n```http\nDeprecation: @1791158400\nSunset: Wed, 30 Jun 2027 23:59:59 GMT\nLink: ; rel=\"successor-version\", ; rel=\"deprecation\"\nX-Depreciacao: cliente-no-cabecalho\n```\n\nPodem deixar de funcionar a partir de **2027-06-30** (Sunset). Operações depreciadas aparecem\nriscadas nesta página:\n\n| Forma antiga | Use | `X-Depreciacao` |\n|---|---|---|\n| `/v1/empresas/…` | `/v1/clientes/…` (mesma rota) | `alias-empresas` |\n| Cabeçalho `X-Empresa-Id` | caminho `/v1/clientes/{id}/…` | `cabecalho-x-empresa-id` |\n| `POST /v1/nfse`, `/v1/nfse/batch`, `/v1/nfse/validar` com `X-Cliente-Id` | `POST /v1/clientes/{clienteId}/nfse…` | `cliente-no-cabecalho` |\n| Lote sem `Idempotency-Key` | envie a chave | `lote-sem-idempotency-key` |\n\n# NF-e recebidas\nPara cada cliente que ligar a busca (`PATCH /v1/clientes/{id}/nfe-recebidas/config` com `{ \"ativo\": true }`, que exige certificado A1\nvigente — `422 nfe.sem_certificado`), a plataforma busca na **Distribuição DF-e** do Ambiente Nacional as NF-e (modelo 55) em que o\ncliente é destinatário, e os eventos delas (cancelamento, carta de correção…). Escopos: `dfe:read` para ler e `dfe:write` para manifestar,\nconfigurar e antecipar a busca. A lista (`GET …/nfe-recebidas`) é paginada por cursor (`X-Next-Cursor`), como as demais.\n\n- **Liberação por conta:** a NF-e recebidas é liberada conta a conta pelo suporte. Enquanto a conta não tiver o recurso, todas as rotas\n de NF-e recebidas (inclusive as do portal) respondem `403 nfe.nao_liberada` e a busca automática fica parada. Peça a liberação ao suporte.\n- **Regra de 1 hora da SEFAZ:** depois de \"nenhum documento\" (cStat 137), de consumo indevido (656) ou de chegar ao último NSU, a SEFAZ\n exige 1 h antes da próxima consulta — consultar antes gera o 656 e **reinicia** a espera. Por isso `POST …/nfe-recebidas/sincronizar`\n só enfileira quando a consulta já é permitida; antes disso responde `409 nfe.consulta_bloqueada` com `Retry-After` (segundos) e\n `proximaConsultaEm`. A rotina automática consulta a cada 5 min respeitando a mesma regra; `GET …/situacao` mostra a próxima consulta.\n- **Sem retroativo:** a SEFAZ só gera NSU para quem consulta (e guarda os documentos por 90 dias): as notas aparecem a partir da primeira\n busca depois de ligar.\n- **XML completo:** a SEFAZ entrega primeiro o **resumo** (resNFe); o XML completo (procNFe) só depois da **Ciência da Operação**,\n da Confirmação ou da Operação não Realizada (Desconhecimento não libera). Antes disso `GET …/{chave}/xml` responde\n `409 nfe.xml_indisponivel`. Com a **ciência automática** ligada, cada resumo novo gera a Ciência sozinho.\n- **Manifestação** (`POST …/{chave}/manifestar`, com `Idempotency-Key`): `ciencia`, `confirmacao`, `desconhecimento` ou `nao_realizada`\n (esta exige `justificativa` de 15 a 255 caracteres). Prazos da NT 2020.001 v1.60: Ciência até **10 dias** da autorização; as\n conclusivas até **90 dias** (Ajuste SINIEF 14/26), no máximo **2 de cada tipo**; Ciência depois de uma conclusiva é recusada; NF-e\n cancelada ou denegada não aceita manifestação. A plataforma confere tudo antes do envio (`422 nfe.manifestacao_invalida`, com\n `motivo`) e responde `202` com o pedido `pendente`; o mesmo tipo ainda em andamento → `409 nfe.manifestacao_duplicada`. O resultado\n chega pelos webhooks `nfe.manifestation.registered`/`nfe.manifestation.rejected`; notas novas e canceladas, por `nfe.received`/`nfe.cancelled`.\n\n# NF-e e NFC-e\nEmissão de **NF-e (modelo 55)** e **NFC-e (modelo 65)** pelo cliente do caminho (`/v1/clientes/{id}/…`), leiaute 4.00. Escopos: `nfe:write`\npara emitir, validar, reenviar, cancelar, corrigir e inutilizar; `nfe:read` para consultar; `cadastros:read|write` para os produtos;\n`fiscal:read|write` para a configuração do emitente.\n\n- **Liberação por conta:** a emissão de NF-e/NFC-e é liberada conta a conta pelo suporte. Sem ela, **todas** as rotas abaixo (produtos,\n configuração, emissão, eventos e inutilização) respondem `403 nfe_emissao.nao_liberada`. `GET /v1/me` traz `tenant.nfeEmissao`.\n- **Configuração do emitente** (`PATCH …/nfe-config`): IE, CRT (1 Simples, 2 Simples com excesso de sublimite, 3 regime normal, 4 MEI), regime\n de PIS/COFINS, séries padrão da NF-e e da NFC-e, versão do QR Code e informações complementares padrão. O **CSC** da NFC-e (QR Code v2)\n vai em `PUT …/nfe-config/csc` `{ idCSC, csc }`: fica cifrado no cofre e nunca volta (só os 4 últimos caracteres). O QR Code v3 dispensa o CSC.\n- **Duas formas de emitir** (`POST …/nfe`, mesmo corpo em `…/nfe/validar`): **por cadastros** — `modelo`, `natOp`, o destinatário\n (`destinatarioId` da agenda de tomadores do cliente, ou `destinatario` avulso), `itens` com `produtoId`/`produtoCodigo` + `quantidade`\n (+ `valorUnitario`, `desconto`, `tributacao`), `frete`, `transporte`, `pagamentos`, `indPres`, `infAdic`, `externalRef`; ou **completa** —\n `{ modelo, documento }`, com a EntradaNFe (nomes das tags do leiaute; o emitente precisa ser o cliente). Nas duas, número, série, cNF,\n dhEmi, ambiente (tpAmb), IE/CRT e o responsável técnico vêm da plataforma.\n- **Tributação — caminho A:** os impostos vêm do **cadastro do produto** (perfil fiscal: CFOP interno/interestadual, ICMS por CST ou\n CSOSN, base e alíquota, redução, ST com MVA/alíquota/redução, FCP, crédito do Simples, cBenef, PIS/COFINS, IPI); a API calcula base,\n valores e totais e **valida** a coerência — não decide a tributação por você. `tributacao` no item sobrescreve o perfil campo a campo.\n CFOP: o interno (5xxx) quando o destinatário é da mesma UF, o interestadual (6xxx) quando não; `idDest` e `indFinal` saem do destinatário.\n- **CRT × CST/CSOSN:** CRT 1 e 4 usam o **CSOSN** (grupo ICMSSN: 101, 102, 103, 201, 202, 203, 300, 400, 500, 900); CRT 2 e 3, o **CST**\n (00, 10, 20, 30, 40, 41, 50, 60, 70, 90). CST no Simples ou CSOSN no regime normal → `nfe.crt_icms` (regras N12-20/N12a-10).\n- **Validação antes de gravar:** regras do Anexo I do MOC 7.0 e da NT 2025.002 (vProd = qCom × vUnCom ±0,01, totais, vNF, CFOP × destino,\n IE × indIEDest, pagamento ≥ total, NFC-e…). Problema → `422 nfe.validacao` com `problemas` (`codigo`, `regra`, `mensagem`, `caminho`).\n `…/validar` roda também o XSD e devolve o XML montado, sem gravar, numerar ou contar na franquia.\n- **Envio:** `X-Mode: sync` (padrão) espera a SEFAZ até o prazo e responde `201` com o resultado (`autorizada`, `rejeitada` ou `denegada`);\n `async` responde `202` (`processando`). Acompanhe por `GET …/nfe/{chave}` (ou pelo `id`) e pelos webhooks `nfe.emitida.authorized`,\n `.rejected`, `.denied`, `.cancelled` e `.corrected`. A **rejeição não consome o número**: corrija e reenvie em `POST …/nfe/{nfeId}/reenviar`\n (mesmo número); a denegação consome. Número abandonado → **inutilize** (`POST …/nfe-inutilizacoes`, até 10.000 números; webhook\n `nfe.inutilizacao.registered`).\n- **NFC-e:** consumidor final presencial (`indPres` 1 ou 4), operação interna, DANFE NFC-e em 80 mm com QR Code (v2 com o CSC, v3 sem);\n destinatário opcional até o limite da UF (padrão R$ 10.000,00; acima, identifique o consumidor); CFOP só os de venda a consumidor.\n- **Contingência** (`GET|PUT …/nfe-contingencia`): quando o autorizador da UF para (status 108/109 ou sem resposta em 2 verificações), os\n clientes entram sozinhos em contingência e saem quando ele volta (107). **NF-e:** SVC da UF (SVC-AN ou SVC-RS, tpEmis 6/7 — autorizada na\n hora pela SVC) ou, com a SVC fora (ou por preferência), **EPEC** (tpEmis 4: evento no Ambiente Nacional, DANFE com o protocolo do EPEC e a\n nota transmitida depois; vedado em PR e PB). **NFC-e:** off-line (tpEmis 9, QR Code de contingência, DANFE em 2 vias), transmitida depois —\n prazo: fim do 1º dia útil seguinte. A nota fica `contingencia_pendente` (webhook `nfe.emitida.contingency`, `GET …/{chave}/pdf` já\n disponível) até a transmissão (`POST …/{chave}/transmitir` ou a rotina a cada 2 min). Uma NFC-e que ficou **sem retorno** vira na hora uma\n NFC-e off-line com **outro número** (`substituidaPor` no detalhe); se a original também for autorizada, cancele-a com\n `POST …/{chave}/cancelar-por-substituicao` (110112, até 168 h); se não, o número dela é inutilizado sozinho. Entrada/saída manual com\n justificativa (vira o xJust); webhooks `nfe.contingencia.activated`/`deactivated`.\n- **Cancelamento** (`POST …/nfe/{chave}/cancelar`, justificativa de 15 a 255 caracteres): até **24 horas** depois da autorização (fora do\n prazo a SEFAZ recusa, salvo a UF aceitar o cancelamento extemporâneo). **Carta de Correção** (`…/carta-correcao`, 15 a 1.000 caracteres,\n até 20 por nota) só na NF-e (modelo 55) — na NFC-e responde `422 nfe.evento_invalido`; não corrige valores, impostos, destinatário nem datas.\n- **XML e DANFE:** `GET …/nfe/{chave}/xml` (nfeProc) e `…/pdf` devolvem uma URL pré-assinada de 300 s (`redirecionar=true` → 302);\n antes de existir, `409 nfe_emissao.arquivo_indisponivel`.\n- **Franquia:** cada NF-e/NFC-e autorizada (ou em processamento) conta na **mesma franquia** das NFS-e (`402 plano.limite`).\n- **Idempotência:** com `Idempotency-Key`, repetir a emissão devolve a mesma nota; a mesma chave com outro corpo → `409 idempotency.conflict`.\n\n# Webhooks\nCadastre uma URL `https` em `POST /v1/webhooks` escolhendo os eventos. Cada entrega é um `POST` JSON\nassinado com HMAC-SHA256 — formato, cabeçalhos e política de reenvio na seção **Webhooks** ao final\ndo menu. Deduplique pelo `id` do evento.\n\n# Ambientes\n- **Endereço principal da API:** `https://api.notaligeira.com.br` (tokens `nfse_live_…`).\n- **Compatibilidade:** `https://nfapi.digla.io` continua atendendo as mesmas rotas, sem redirecionar requisições.\n- **Homologação × produção** é configuração de cada **cliente emitente** (campo `ambiente`: `homolog`\n = Produção Restrita do SEFIN Nacional, sem valor fiscal; `prod` = produção). Teste a integração com um\n cliente em `homolog` antes de passá-lo para `prod`.\n- `POST /v1/clientes/{clienteId}/nfse/validar` valida a DPS e mostra o XML **sem emitir**.\n\n# Erros\nRespostas de erro seguem o formato **RFC 7807** (Problem Details: `type`, `title`, `status`, `detail`) com `code` próprio\n(ex.: `validation_error`, `tributacao.pendente`, `certificate.expired`, `sefin.E0084`). O `type` é\n`https://nf.digla.io/api/erros/`: uma página com quando o erro ocorre e como resolver (lista completa em\n[Códigos de erro](https://nf.digla.io/api/erros/)). Decida pelo `code`, não pelo texto. Limite de requisições\nexcedido responde `429` com `Retry-After`.\n\n# Suporte\nDúvidas de integração: o canal de suporte indicado no painel ([app.notaligeira.com.br](https://app.notaligeira.com.br)). O arquivo [openapi.json](./openapi.json) desta página pode ser\nimportado no Postman, Insomnia ou num gerador de clientes.", "contact": { "name": "Suporte Digla", "url": "https://app.notaligeira.com.br" }, "license": { "name": "Proprietária" } }, "servers": [ { "url": "https://api.notaligeira.com.br", "description": "Produção (a emissão em homologação ou produção depende do ambiente do cliente)" } ], "tags": [ { "name": "nfse", "description": "Emissão (inclusive lote), validação, consulta, listagem e DANFSe/XML", "x-displayName": "NFS-e" }, { "name": "eventos", "description": "Cancelamento, substituição e manifestação", "x-displayName": "Eventos" }, { "name": "dfe", "description": "Notas de terceiros recebidas por NSU e situação da busca", "x-displayName": "Notas recebidas (DF-e)" }, { "name": "nfe", "description": "Emissão de NF-e (modelo 55) e NFC-e (modelo 65) por cadastros ou pelo documento completo, validação, consulta, XML/DANFE, reenvio, cancelamento, carta de correção, inutilização e a configuração do emitente (IE, CRT, séries, CSC)", "x-displayName": "NF-e e NFC-e" }, { "name": "produtos", "description": "Cadastro de produtos da NF-e/NFC-e com o perfil fiscal (CFOP, ICMS por CST/CSOSN, ST, FCP, PIS/COFINS, IPI), upsert pelo código do ERP", "x-displayName": "Produtos" }, { "name": "nfe-recebidas", "description": "NF-e (modelo 55) em que o cliente é destinatário: lista, XML, manifestação do destinatário e busca na SEFAZ", "x-displayName": "NF-e recebidas" }, { "name": "webhooks", "description": "Configuração, histórico de entregas e reenvio", "x-displayName": "Webhooks" }, { "name": "clientes", "description": "Somente leitura — de onde vem o `clienteId` do caminho", "x-displayName": "Clientes emitentes" }, { "name": "tomadores", "description": "Agenda de tomadores do cliente: CRUD, upsert pelo documento/código e retenções do tomador", "x-displayName": "Tomadores" }, { "name": "servicos", "description": "Catálogo do cliente com os padrões fiscais, upsert pelo código e regras serviço×tomador", "x-displayName": "Serviços" }, { "name": "perfil-fiscal", "description": "Regime tributário do cliente por competência (vigências)", "x-displayName": "Perfil fiscal" }, { "name": "reference", "description": "NBS, serviços da LC 116, IBS/CBS, municípios, países e rejeições", "x-displayName": "Referências" }, { "name": "me", "description": "Conta e escopos do token em uso", "x-displayName": "Token atual" }, { "name": "health", "description": "Liveness e readiness da API", "x-displayName": "Saúde" }, { "name": "Cadastros" }, { "name": "empresas" }, { "name": "NfeCadastros" }, { "name": "NfeFiscal" }, { "name": "Tributacao" } ], "paths": { "/v1/me": { "get": { "description": "A lista `vinculos` é da PRÓPRIA pessoa (para o seletor \"Trocar de conta\"): a conta da sessão nunca recebe os vínculos da pessoa em outras contas por nenhuma rota de gestão — só a própria pessoa, aqui.", "operationId": "TenantsController_me", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Perfil: conta da sessão, pessoa, vínculo atual e os vínculos ativos da pessoa (seletor de contas)", "tags": [ "me" ] } }, "/v1/clientes": { "get": { "description": "`/v1/empresas` é apelido legado.\n\n**Escopo exigido:** `empresas:read`; sem ele, `403 insufficient_scope`.", "operationId": "EmpresasController_list[0]", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Próxima página; ausente na última.", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ClienteResponse" } } } } } }, "security": [ { "bearer": [] } ], "summary": "Lista os clientes emitentes do tenant", "tags": [ "clientes" ], "x-required-scopes": [ "empresas:read" ] } }, "/v1/empresas": { "get": { "description": "**DEPRECIADO** (Sunset 2027-06-30): alias legado — use `/v1/clientes`.\n\n`/v1/empresas` é apelido legado.\n\n**Escopo exigido:** `empresas:read`; sem ele, `403 insufficient_scope`.", "operationId": "EmpresasController_list[1]", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Próxima página; ausente na última.", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ClienteResponse" } } } } } }, "security": [ { "bearer": [] } ], "summary": "Lista os clientes emitentes do tenant", "tags": [ "clientes" ], "deprecated": true, "x-required-scopes": [ "empresas:read" ] } }, "/v1/clientes/{id}": { "get": { "operationId": "EmpresasController_get[0]", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClienteResponse" } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Detalhe de um cliente emitente", "tags": [ "clientes" ], "x-required-scopes": [ "empresas:read" ], "description": "**Escopo exigido:** `empresas:read`; sem ele, `403 insufficient_scope`." } }, "/v1/empresas/{id}": { "get": { "operationId": "EmpresasController_get[1]", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClienteResponse" } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Detalhe de um cliente emitente", "tags": [ "clientes" ], "deprecated": true, "description": "**DEPRECIADO** (Sunset 2027-06-30): alias legado — use `/v1/clientes/{id}`.\n\n**Escopo exigido:** `empresas:read`; sem ele, `403 insufficient_scope`.", "x-required-scopes": [ "empresas:read" ] } }, "/v1/nfse": { "post": { "deprecated": true, "description": "Igual a `POST /v1/clientes/{clienteId}/nfse`, com o cliente no cabeçalho `X-Cliente-Id`. Recebe uma DPS, valida, assina (XMLDSig), envia para o SEFIN Nacional via mTLS e persiste a NFS-e autorizada.\n\n**Escopo exigido:** `nfse:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfseController_emitir", "parameters": [ { "name": "X-Mode", "in": "header", "description": "Modo — `sync` aguarda autorização do SEFIN; `async` responde `201` imediatamente com `status: processando`.", "required": false, "schema": { "type": "string", "enum": [ "sync", "async" ], "default": "sync" } }, { "name": "X-Pedido-Id", "in": "header", "description": "Emissão a partir de um pedido de nota do cliente: quando a NFS-e é autorizada, o pedido vira `emitido` (rejeição não fecha o pedido).", "required": false, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Chave de idempotência (recomendado UUID v4). Reenvios retornam a mesma resposta.", "required": false, "schema": { "type": "string" } }, { "name": "X-Cliente-Id", "in": "header", "description": "DEPRECIADO (Sunset 2027-06-30): use `POST /v1/clientes/{clienteId}/nfse`. UUID do cliente emitente (do tenant atual).", "required": true, "deprecated": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Payload da DPS conforme layout nacional (ANEXO I + grupo IBSCBS da NT 004/2025).", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DpsEmissao" }, { "$ref": "#/components/schemas/EmissaoPorCadastros" } ] }, "examples": { "padrao": { "summary": "Emissão padrão com IBS/CBS", "value": { "externalRef": "PEDIDO-998877", "serie": "1", "competencia": "2026-05-23", "naturezaOperacao": "tributacaoNoMunicipio", "prestador": { "cnpj": "12345678000195", "im": "987654" }, "tomador": { "tipoDoc": "CNPJ", "documento": "11222333000181", "nome": "Empresa Tomadora LTDA", "email": "fin@tomadora.com", "endereco": { "cep": "01310100", "logradouro": "Av Paulista", "numero": "1000", "bairro": "Bela Vista", "municipioIbge": 3550308, "uf": "SP", "paisIso2": "BR" } }, "servicos": [ { "codigoNbs": "1.0101.00.00", "codigoServicoMunicipal": "0101", "descricao": "Consultoria em desenvolvimento de software", "quantidade": "1.00", "valorUnitario": "1500.00", "valorTotal": "1500.00", "issRetido": false, "aliquotaIss": "5.00" } ], "tributacao": { "iss": { "valor": "75.00", "exigibilidade": "exigivel" }, "ibsCbs": { "classificacao": "padrao", "baseCalculo": "1500.00", "aliquotaIbs": "9.25", "aliquotaCbs": "8.85", "valorIbs": "138.75", "valorCbs": "132.75", "imune": false, "is": { "incidencia": false } } }, "informacoesComplementares": "Pedido referência PEDIDO-998877" } }, "porCadastro": { "summary": "Por cadastros: serviço + tomador + valor (tributação resolvida)", "value": { "servicoId": "6f1d2c3b-4a59-4e7f-8a9b-0c1d2e3f4a5b", "tomadorId": "7a2e3d4c-5b6a-4f8e-9a0b-1c2d3e4f5a6b", "valor": "750.00", "competencia": "2026-10-01", "descricao": "Licença de uso {competencia}", "externalRef": "PEDIDO-998877", "tributacao": { "federal": { "retencaoIrrf": "0.00" } } } }, "substituicao": { "summary": "Substituição de NFS-e existente", "value": { "externalRef": "PEDIDO-998877", "serie": "1", "competencia": "2026-05-23", "naturezaOperacao": "tributacaoNoMunicipio", "prestador": { "cnpj": "12345678000195", "im": "987654" }, "tomador": { "tipoDoc": "CNPJ", "documento": "11222333000181", "nome": "Empresa Tomadora LTDA", "email": "fin@tomadora.com", "endereco": { "cep": "01310100", "logradouro": "Av Paulista", "numero": "1000", "bairro": "Bela Vista", "municipioIbge": 3550308, "uf": "SP", "paisIso2": "BR" } }, "servicos": [ { "codigoNbs": "1.0101.00.00", "codigoServicoMunicipal": "0101", "descricao": "Consultoria em desenvolvimento de software", "quantidade": "1.00", "valorUnitario": "1500.00", "valorTotal": "1500.00", "issRetido": false, "aliquotaIss": "5.00" } ], "tributacao": { "iss": { "valor": "75.00", "exigibilidade": "exigivel" }, "ibsCbs": { "classificacao": "padrao", "baseCalculo": "1500.00", "aliquotaIbs": "9.25", "aliquotaCbs": "8.85", "valorIbs": "138.75", "valorCbs": "132.75", "imune": false, "is": { "incidencia": false } } }, "informacoesComplementares": "Pedido referência PEDIDO-998877", "substituiChaveAcesso": "35503082212345678000195000000000000126101234567895" } } } } } }, "responses": { "201": { "description": "Modo `sync`: resultado final em `status` (`autorizada`, `rejeitada`) ou `processando` se passou do prazo. Modo `async` (`X-Mode: async`): aceita, com `status: processando`; acompanhe por webhook ou `GET /v1/nfse/{chave}`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfseEmitidaResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`, com `issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "402": { "description": "Plano: franquia de notas do mês atingida com o excedente desligado (`plano.limite`, com `detalhes`), saldo de crédito insuficiente no plano pré-pago (`credito.saldo_insuficiente`) ou teste grátis encerrado (`plano.teste_expirado`) ou conta suspensa (`tenant.inativo`). O Dono ou um administrador ativa o excedente ou troca de plano em Plano e uso, no painel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemLimitePlanoResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`), cliente fora da restrição do token ou conta suspensa (`tenant.inativo`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, serviço ou tomador não encontrado (inclusive de outra conta)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Mesma `Idempotency-Key` com corpo diferente, ou primeiro pedido com a chave ainda em andamento (`idempotency.em_andamento`, `Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Pendência do motor (`tributacao.pendente`, com `pendencias`), serviço/tomador inativo, regra do Anexo I violada ou DPS rejeitada pelo SEFIN (`sefin.E…`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemPendenciasResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "503": { "description": "SEFIN indisponível — a nota entrou em contingência", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Emitir NFS-e — forma legada (cliente no cabeçalho)", "tags": [ "nfse" ], "x-required-scopes": [ "nfse:write" ] }, "get": { "description": "Filtros opcionais por empresa, status e intervalo de data de emissão.\n\n**Escopo exigido:** `nfse:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfseController_list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "empresaId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "autorizada", "cancelada", "substituida", "rejeitada" ], "type": "string" } }, { "name": "dataDe", "required": false, "in": "query", "description": "ISO-8601, inclusiva", "schema": { "type": "string" } }, { "name": "dataAte", "required": false, "in": "query", "description": "ISO-8601, exclusiva", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "tomadorDoc", "required": false, "in": "query", "description": "CNPJ/CPF do tomador (sem máscara)", "schema": { "type": "string" } }, { "name": "valorMin", "required": false, "in": "query", "description": "Valor monetário mínimo (ex: \"100.00\")", "schema": { "type": "string" } }, { "name": "valorMax", "required": false, "in": "query", "description": "Valor monetário máximo (ex: \"5000.00\")", "schema": { "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Busca em chave de acesso e número (até 60 caracteres)", "schema": { "type": "string" } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "schema": { "type": "string" }, "description": "Próxima página; ausente na última." } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NfseResumoResponse" } } } } } }, "security": [ { "bearer": [] } ], "summary": "Listar NFS-e", "tags": [ "nfse" ], "x-required-scopes": [ "nfse:read" ] } }, "/v1/nfse/{chave}": { "get": { "description": "Chave de acesso de 50 dígitos. Inclui URL pré-assinada de XML e DANFSE.\n\n**Escopo exigido:** `nfse:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfseController_consultar", "parameters": [ { "name": "chave", "required": true, "in": "path", "schema": { "example": "35503082212345678000195000000000000126101234567895", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfseResumoResponse" } } } }, "400": { "description": "Chave inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Consultar NFS-e por chave", "tags": [ "nfse" ], "x-required-scopes": [ "nfse:read" ] } }, "/v1/nfse/{chave}/eventos": { "get": { "operationId": "NfseController_eventos", "parameters": [ { "name": "chave", "required": true, "in": "path", "description": "Chave de acesso (50 dígitos)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Eventos da nota, do mais recente ao mais antigo", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EventoNfseResponse" } } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`), cliente fora da restrição do token ou conta suspensa (`tenant.inativo`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "NFS-e não encontrada (`not_found`) — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Listar eventos da NFS-e", "tags": [ "nfse" ], "x-required-scopes": [ "nfse:read" ], "description": "**Escopo exigido:** `nfse:read`; sem ele, `403 insufficient_scope`." } }, "/v1/nfse/{chave}/cadeia": { "get": { "description": "Retorna a NFS-e atual, a anterior (se foi substituição) e as posteriores (se foi substituída).\n\n**Escopo exigido:** `nfse:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfseController_cadeia", "parameters": [ { "name": "chave", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CadeiaSubstituicoesResponse" } } } }, "400": { "description": "Chave de acesso inválida (`chave.invalid`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`), cliente fora da restrição do token ou conta suspensa (`tenant.inativo`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "NFS-e não encontrada (`not_found`) — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cadeia de substituições", "tags": [ "nfse" ], "x-required-scopes": [ "nfse:read" ] } }, "/v1/nfse/batch": { "post": { "deprecated": true, "description": "Igual a `POST /v1/clientes/{clienteId}/nfse/batch`, com o cliente no cabeçalho `X-Cliente-Id`.\n\n**Escopo exigido:** `nfse:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfseController_emitirBatch", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Chave do lote (UUID v4 recomendado). Reenviar o mesmo lote com a mesma chave devolve as mesmas DPS — nada é duplicado, mesmo em reenvio concorrente. Mesma chave com corpo diferente → 409. Ausente: aceito até 2027-06-30 com cabeçalhos `Deprecation`/`Sunset` (depois passa a ser obrigatória).", "required": false, "schema": { "type": "string" } }, { "name": "X-Cliente-Id", "in": "header", "description": "DEPRECIADO (Sunset 2027-06-30): use `POST /v1/clientes/{clienteId}/nfse/batch`.", "required": true, "deprecated": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Lote aceito: um resultado por DPS, na ordem do corpo. Itens recusados trazem `error` e `code` (ex.: `tributacao.pendente`). Com a franquia do mês já atingida e o excedente desligado, todos os itens voltam com `plano.limite`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoteEmitidoResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`, com `issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`), cliente fora da restrição do token ou conta suspensa (`tenant.inativo`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, serviço ou tomador não encontrado (inclusive de outra conta)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Mesma `Idempotency-Key` com corpo diferente ou ainda em andamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Emissão em lote (até 100 DPSs) — forma legada", "tags": [ "nfse" ], "x-required-scopes": [ "nfse:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dps": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/DpsEmissao" }, { "$ref": "#/components/schemas/EmissaoPorCadastros" } ] }, "minItems": 1, "maxItems": 100 } }, "required": [ "dps" ] } } } } } }, "/v1/nfse/{chave}/reemitir-danfse": { "post": { "description": "Enfileira regeneração do PDF da NFS-e (útil quando o layout/template muda).\n\n**Escopo exigido:** `nfse:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfseController_reemitirDanfse", "parameters": [ { "name": "chave", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Regeneração do PDF enfileirada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DanfseEnfileiradaResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`), cliente fora da restrição do token ou conta suspensa (`tenant.inativo`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "NFS-e não encontrada (`not_found`) — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Reemissão da DANFSE PDF", "tags": [ "nfse" ], "x-required-scopes": [ "nfse:write" ] } }, "/v1/clientes/{clienteId}/nfse": { "post": { "description": "Recebe uma DPS, valida, assina (XMLDSig), envia para o SEFIN Nacional via mTLS e persiste a NFS-e autorizada. Lucro Presumido/Real em município que só compartilha com o ADN (planilha oficial de adesão): sem confirmação a emissão responde 422 `nfse.confirmacao_municipio_nao_aderente` e nada é criado; reenvie com `confirmarMunicipioNaoAderente: true` no corpo (ou confirme em `POST /v1/clientes/{id}/emissor-nacional/confirmar`). O corpo aceita duas formas: a **DPS completa** (como sempre — passa intacta) ou **por cadastros** — `servicoId` (ou `servicoCodigo`) + `tomadorId` (ou `tomadorCodigo`, ou `tomador` avulso) + `valor` + `competencia`: o motor de tributação resolve PIS/COFINS pelo regime da competência, retenções (IRRF, CSRF, INSS, ISS retido), alíquota do ISS e IBS/CBS. Blocos opcionais (`tributacao`, `servicos[0]`, `rtc`, `deducaoReducao`) prevalecem campo a campo. A resposta da forma nova traz `origens` (de onde veio cada valor), `avisos` e `totais`. Serviço/tomador de outro cliente ou conta → 404 `servico.nao_encontrado`/`tomador.nao_encontrado`; pendência do motor → 422 `tributacao.pendente`.\n\n**Escopo exigido:** `nfse:write`; sem ele, `403 insufficient_scope`.", "operationId": "ClienteNfseController_emitir", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "description": "UUID do cliente emitente (do tenant do token)", "schema": { "type": "string" } }, { "name": "X-Mode", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "sync", "async" ], "default": "sync" } }, { "name": "X-Pedido-Id", "in": "header", "description": "Emissão a partir de um pedido de nota do cliente.", "required": false, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Chave de idempotência (UUID v4). Reenvios retornam a mesma resposta.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DpsEmissao" }, { "$ref": "#/components/schemas/EmissaoPorCadastros" } ] }, "examples": { "padrao": { "summary": "Emissão padrão com IBS/CBS", "value": { "externalRef": "PEDIDO-998877", "serie": "1", "competencia": "2026-05-23", "naturezaOperacao": "tributacaoNoMunicipio", "prestador": { "cnpj": "12345678000195", "im": "987654" }, "tomador": { "tipoDoc": "CNPJ", "documento": "11222333000181", "nome": "Empresa Tomadora LTDA", "email": "fin@tomadora.com", "endereco": { "cep": "01310100", "logradouro": "Av Paulista", "numero": "1000", "bairro": "Bela Vista", "municipioIbge": 3550308, "uf": "SP", "paisIso2": "BR" } }, "servicos": [ { "codigoNbs": "1.0101.00.00", "codigoServicoMunicipal": "0101", "descricao": "Consultoria em desenvolvimento de software", "quantidade": "1.00", "valorUnitario": "1500.00", "valorTotal": "1500.00", "issRetido": false, "aliquotaIss": "5.00" } ], "tributacao": { "iss": { "valor": "75.00", "exigibilidade": "exigivel" }, "ibsCbs": { "classificacao": "padrao", "baseCalculo": "1500.00", "aliquotaIbs": "9.25", "aliquotaCbs": "8.85", "valorIbs": "138.75", "valorCbs": "132.75", "imune": false, "is": { "incidencia": false } } }, "informacoesComplementares": "Pedido referência PEDIDO-998877" } }, "porCadastro": { "summary": "Por cadastros: serviço + tomador + valor (tributação resolvida)", "value": { "servicoId": "6f1d2c3b-4a59-4e7f-8a9b-0c1d2e3f4a5b", "tomadorId": "7a2e3d4c-5b6a-4f8e-9a0b-1c2d3e4f5a6b", "valor": "750.00", "competencia": "2026-10-01", "descricao": "Licença de uso {competencia}", "externalRef": "PEDIDO-998877", "tributacao": { "federal": { "retencaoIrrf": "0.00" } } } }, "substituicao": { "summary": "Substituição de NFS-e existente", "value": { "externalRef": "PEDIDO-998877", "serie": "1", "competencia": "2026-05-23", "naturezaOperacao": "tributacaoNoMunicipio", "prestador": { "cnpj": "12345678000195", "im": "987654" }, "tomador": { "tipoDoc": "CNPJ", "documento": "11222333000181", "nome": "Empresa Tomadora LTDA", "email": "fin@tomadora.com", "endereco": { "cep": "01310100", "logradouro": "Av Paulista", "numero": "1000", "bairro": "Bela Vista", "municipioIbge": 3550308, "uf": "SP", "paisIso2": "BR" } }, "servicos": [ { "codigoNbs": "1.0101.00.00", "codigoServicoMunicipal": "0101", "descricao": "Consultoria em desenvolvimento de software", "quantidade": "1.00", "valorUnitario": "1500.00", "valorTotal": "1500.00", "issRetido": false, "aliquotaIss": "5.00" } ], "tributacao": { "iss": { "valor": "75.00", "exigibilidade": "exigivel" }, "ibsCbs": { "classificacao": "padrao", "baseCalculo": "1500.00", "aliquotaIbs": "9.25", "aliquotaCbs": "8.85", "valorIbs": "138.75", "valorCbs": "132.75", "imune": false, "is": { "incidencia": false } } }, "informacoesComplementares": "Pedido referência PEDIDO-998877", "substituiChaveAcesso": "35503082212345678000195000000000000126101234567895" } } } } } }, "responses": { "201": { "description": "Modo `sync`: resultado final em `status` (`autorizada`, `rejeitada`) ou `processando` se passou do prazo. Modo `async` (`X-Mode: async`): aceita, com `status: processando`; acompanhe por webhook ou `GET /v1/nfse/{chave}`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfseEmitidaResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`, com `issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "402": { "description": "Plano: franquia de notas do mês atingida com o excedente desligado (`plano.limite`, com `detalhes`), saldo de crédito insuficiente no plano pré-pago (`credito.saldo_insuficiente`) ou teste grátis encerrado (`plano.teste_expirado`) ou conta suspensa (`tenant.inativo`). O Dono ou um administrador ativa o excedente ou troca de plano em Plano e uso, no painel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemLimitePlanoResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`), cliente fora da restrição do token ou conta suspensa (`tenant.inativo`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, serviço ou tomador não encontrado (inclusive de outra conta)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Mesma `Idempotency-Key` com corpo diferente, ou primeiro pedido com a chave ainda em andamento (`idempotency.em_andamento`, `Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Pendência do motor (`tributacao.pendente`, com `pendencias`), serviço/tomador inativo, regra do Anexo I violada ou DPS rejeitada pelo SEFIN (`sefin.E…`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemPendenciasResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "503": { "description": "SEFIN indisponível — a nota entrou em contingência", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Emitir NFS-e", "tags": [ "nfse" ], "x-required-scopes": [ "nfse:write" ] } }, "/v1/clientes/{clienteId}/nfse/batch": { "post": { "description": "Enfileira todas em modo assíncrono e retorna o id da DPS de cada item (ou o erro e o `code` do item). Cada item pode vir em qualquer das duas formas (DPS completa ou por cadastros); os cadastros do lote são carregados de uma vez (uma consulta por tabela). Para planilhas a partir dos cadastros (vários clientes, até 500 linhas) use `POST /v1/nfse/lote`.\n\n**Escopo exigido:** `nfse:write`; sem ele, `403 insufficient_scope`.", "operationId": "ClienteNfseController_emitirBatch", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "description": "UUID do cliente emitente (do tenant do token)", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Chave do lote (UUID v4 recomendado). Reenviar o mesmo lote com a mesma chave devolve as mesmas DPS — nada é duplicado, mesmo em reenvio concorrente. Mesma chave com corpo diferente → 409. Ausente: aceito até 2027-06-30 com cabeçalhos `Deprecation`/`Sunset` (depois passa a ser obrigatória).", "required": false, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Lote aceito: um resultado por DPS, na ordem do corpo. Itens recusados trazem `error` e `code` (ex.: `tributacao.pendente`). Com a franquia do mês já atingida e o excedente desligado, todos os itens voltam com `plano.limite`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoteEmitidoResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`, com `issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`), cliente fora da restrição do token ou conta suspensa (`tenant.inativo`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, serviço ou tomador não encontrado (inclusive de outra conta)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Mesma `Idempotency-Key` com corpo diferente ou ainda em andamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Emissão em lote (até 100 DPSs por chamada)", "tags": [ "nfse" ], "x-required-scopes": [ "nfse:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dps": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/DpsEmissao" }, { "$ref": "#/components/schemas/EmissaoPorCadastros" } ] }, "minItems": 1, "maxItems": 100 } }, "required": [ "dps" ] } } } } } }, "/v1/clientes/{id}/emissor-nacional/confirmar": { "post": { "description": "Lucro Presumido/Real em município sem Emissor Nacional (ou sem adesão, ou sem habilitação no CNC), segundo a consulta ao convênio no ADN (reserva: planilha oficial): a emissão pede confirmação, porque a Sefin pode recusar. Esta rota registra a confirmação do cliente (quem, quando, município, situação, fonte e retrato do convênio). Vale enquanto o município e a situação dele não mudarem. Cliente fora da regra: 409 `emissor_nacional.nao_aplicavel`.\n\n**Escopo exigido:** `empresas:write`; sem ele, `403 insufficient_scope`.", "operationId": "EmissorNacionalController_confirmar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmissorNacionalEstadoResponse" } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Cliente que não precisa da confirmação: MEI, Simples ou município do Emissor Nacional (`emissor_nacional.nao_aplicavel`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Confirma a emissão em município que só compartilha com o ADN", "tags": [ "empresas" ], "x-required-scopes": [ "empresas:write" ] }, "delete": { "operationId": "EmissorNacionalController_revogar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmissorNacionalEstadoResponse" } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Revoga a confirmação: a próxima emissão volta a pedi-la", "tags": [ "empresas" ], "x-required-scopes": [ "empresas:write" ], "description": "**Escopo exigido:** `empresas:write`; sem ele, `403 insufficient_scope`." } }, "/v1/clientes/{clienteId}/perfil-fiscal": { "get": { "description": "Regime vigente hoje, histórico de vigências por competência, município e pTotTribSN.\n\n**Escopo exigido:** `fiscal:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`.", "operationId": "TributacaoController_perfil", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerfilFiscalResponse" } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Perfil fiscal do cliente", "tags": [ "Tributacao", "perfil-fiscal" ], "x-required-scopes": [ "fiscal:read" ] } }, "/v1/clientes/{clienteId}/regimes": { "get": { "description": "Ordem cronológica; `vigenciaFim` null = vigente. Lista completa do cliente, sem paginação (sem `cursor`/`limit`/`X-Next-Cursor`).\n\n**Escopo exigido:** `fiscal:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`.", "operationId": "TributacaoController_listarRegimes", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RegimeResponse" } } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Listar vigências de regime tributário", "tags": [ "Tributacao", "perfil-fiscal" ], "x-required-scopes": [ "fiscal:read" ] }, "post": { "description": "\"Mudou de regime a partir de…\": `vigenciaInicio` (AAAA-MM) fecha na véspera a vigência que a contém; sem `vigenciaFim`, a nova termina na véspera da seguinte (se houver). Para cadastrar um regime anterior, informe início e fim. 409 `regime.vigencia_existente`, `regime.sobreposicao`, `regime.incompativel`, `regime.cumulativo`. Regime especial do ISS (`regimeEspecialIss`), profissionais habilitados (sociedade de profissionais, `regimeEspecialIss` \"6\") e `cprb` seguem as regras da Sefin: 400 `regime.especial_incompativel`, `regime.profissionais_obrigatorio`, `regime.profissionais_invalido`, `regime.cprb_incompativel`. A emissão usa o regime vigente na competência de cada nota.\n\n**Escopo exigido:** `fiscal:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "TributacaoController_criarRegime", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Recomendado (UUID v4).", "required": false, "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegimeCriadoResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`) ou combinação recusada: `regime.especial_incompativel`, `regime.profissionais_obrigatorio`, `regime.profissionais_invalido`, `regime.cprb_incompativel`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Vigência já existente (`regime.vigencia_existente`), sobreposta (`regime.sobreposicao`), regime incompatível com o documento (`regime.incompativel`) ou PIS/COFINS cumulativo fora do Lucro Real (`regime.cumulativo`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Nova vigência de regime tributário", "tags": [ "Tributacao", "perfil-fiscal" ], "x-required-scopes": [ "fiscal:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vigenciaInicio": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-01)?$" }, "vigenciaFim": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "nullable": true }, "regime": { "type": "string", "enum": [ "simples", "mei", "lucroPresumido", "lucroReal", "autonomo" ] }, "regimeApuracaoSn": { "type": "string", "enum": [ "1", "2", "3" ] }, "percentualTotTribSn": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "pisCofinsCumulativo": { "type": "boolean", "nullable": true }, "regimeEspecialIss": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "9" ] }, "profissionaisHabilitados": { "type": "integer", "minimum": 1, "maximum": 9999, "nullable": true }, "cprb": { "type": "boolean" }, "motivo": { "type": "string", "maxLength": 500, "nullable": true } }, "required": [ "vigenciaInicio", "regime" ], "additionalProperties": false } } } } } }, "/v1/clientes/{clienteId}/regimes/{id}": { "patch": { "description": "409 `regime.em_uso` se a mudança trocar o regime de referência de nota já autorizada (crie uma vigência nova a partir da próxima competência). Valem as mesmas validações do `POST` para regime especial, profissionais habilitados e CPRB.\n\n**Escopo exigido:** `fiscal:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "TributacaoController_atualizarRegime", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegimeResponse" } } } }, "400": { "description": "Campo desconhecido ou inválido (`validation_error`) ou combinação recusada: `regime.especial_incompativel`, `regime.profissionais_obrigatorio`, `regime.profissionais_invalido`, `regime.cprb_incompativel`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Vigência (`regime.nao_encontrado`) ou cliente não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "`regime.em_uso`, `regime.sobreposicao`, `regime.vigencia_existente` ou `regime.cumulativo`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Alterar vigência de regime", "tags": [ "Tributacao", "perfil-fiscal" ], "x-required-scopes": [ "fiscal:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vigenciaInicio": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])(-01)?$" }, "vigenciaFim": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "nullable": true }, "regime": { "type": "string", "enum": [ "simples", "mei", "lucroPresumido", "lucroReal", "autonomo" ] }, "regimeApuracaoSn": { "type": "string", "enum": [ "1", "2", "3" ] }, "percentualTotTribSn": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "pisCofinsCumulativo": { "type": "boolean", "nullable": true }, "regimeEspecialIss": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "9" ] }, "profissionaisHabilitados": { "type": "integer", "minimum": 1, "maximum": 9999, "nullable": true }, "cprb": { "type": "boolean" }, "motivo": { "type": "string", "maxLength": 500, "nullable": true } }, "additionalProperties": false } } } } } }, "/v1/clientes/{clienteId}/regras-tomador": { "get": { "description": "Reúne, em uma só lista, as regras serviço×tomador e as exigências de retenção dos tomadores (valem para todos os serviços; `tipo: \"exigencia\"`, `servicoId: null`). Ordem: nome do tomador, exigência antes das regras, serviço. Paginada por cursor (keyset): corpo array, próxima página em `X-Next-Cursor`. `retencoes` resume o que retém (`irrfAliquota`, `csrf`, `inssAliquota`, `issRetido`; alíquota \"0.00\" na regra = força não reter) e `outrosCampos` conta os demais ajustes da regra.\n\n**Escopo exigido:** `cadastros:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`.", "operationId": "TributacaoController_listarRegrasTomador", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Itens por página: 1 a 200 (padrão 50).", "schema": {} }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco da página seguinte (`X-Next-Cursor`).", "schema": {} }, { "name": "q", "required": false, "in": "query", "description": "Nome do tomador (contém)", "schema": {} }, { "name": "tipo", "required": false, "in": "query", "schema": { "enum": [ "regra", "exigencia" ], "type": "string" } }, { "name": "tributo", "required": false, "in": "query", "description": "Só quem trata deste tributo", "schema": { "enum": [ "irrf", "csrf", "inss", "iss" ], "type": "string" } }, { "name": "servicoId", "required": false, "in": "query", "description": "Só regras deste serviço (exigências de tomador valem para todos os serviços e não entram)", "schema": {} }, { "name": "tomadorId", "required": false, "in": "query", "description": "Só deste tomador", "schema": {} } ], "responses": { "200": { "description": "Página (array); a próxima página vem em `X-Next-Cursor`", "headers": { "X-Next-Cursor": { "description": "Cursor da próxima página (ausente na última).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RegraTomadorItemResponse" } } } } }, "400": { "description": "Filtro inválido (`query.invalida`, `cursor.invalido`, `limit.invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Listar todas as retenções exigidas por tomador do cliente", "tags": [ "Tributacao", "tomadores" ], "x-required-scopes": [ "cadastros:read" ] } }, "/v1/clientes/{clienteId}/servicos/{servicoId}/regras": { "get": { "description": "Overrides fiscais do serviço quando prestado a um tomador específico (ex.: tomador que exige IRRF 1,5%). Ordem do nome do tomador, paginada por cursor (keyset): corpo array, próxima página no cabeçalho `X-Next-Cursor`.\n\n**Escopo exigido:** `cadastros:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`.", "operationId": "TributacaoController_listarRegras", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "servicoId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Itens por página: 1 a 200 (padrão 50).", "schema": {} }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco da página seguinte (`X-Next-Cursor`).", "schema": {} }, { "name": "q", "required": false, "in": "query", "description": "Nome do tomador (contém)", "schema": {} } ], "responses": { "200": { "description": "Página (array); a próxima página vem em `X-Next-Cursor`", "headers": { "X-Next-Cursor": { "description": "Cursor da próxima página (ausente na última).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RegraParResponse" } } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Serviço (`servico.nao_encontrado`) ou cliente não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Listar regras serviço×tomador de um serviço", "tags": [ "Tributacao", "servicos" ], "x-required-scopes": [ "cadastros:read" ] } }, "/v1/clientes/{clienteId}/servicos/{servicoId}/regras/{tomadorId}": { "get": { "operationId": "TributacaoController_obterRegra", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "servicoId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "tomadorId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegraParResponse" } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Regra do par (`regra_st.nao_encontrada`) ou serviço (`servico.nao_encontrado`), tomador (`tomador.nao_encontrado`) ou cliente não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Consultar a regra do par serviço×tomador", "tags": [ "Tributacao", "servicos" ], "x-required-scopes": [ "cadastros:read" ], "description": "**Escopo exigido:** `cadastros:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`." }, "put": { "description": "201 criada / 200 atualizada. `campos` aceita só: `iss.aliquota`, `iss.exigibilidade`, `iss.retido`, `ret.irrf.aliquota` (null = não reter), `ret.csrf`, `ret.pis.aliquota`, `ret.cofins.aliquota`, `ret.csll.aliquota`, `ret.inss.aliquota` (null = não reter), `deducao.percentual` | `deducao.valor`, `ibscbs.cst`, `ibscbs.cClassTrib`, `ibscbs.cIndOp`. Vence o serviço e o tomador; perde para a nota.\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "TributacaoController_gravarRegra", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "servicoId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "tomadorId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "campos": { "type": "object", "properties": { "iss.aliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "iss.exigibilidade": { "type": "string", "enum": [ "exigivel", "naoIncidencia", "isencao", "exportacao", "imunidade", "suspensaoJudicial", "suspensaoAdministrativa" ] }, "iss.retido": { "type": "boolean" }, "ret.irrf.aliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "ret.csrf": { "type": "boolean" }, "ret.pis.aliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "ret.cofins.aliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "ret.csll.aliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "ret.inss.aliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "deducao.percentual": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "deducao.valor": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "ibscbs.cst": { "type": "string", "pattern": "^\\d{3}$" }, "ibscbs.cClassTrib": { "type": "string", "pattern": "^\\d{6}$" }, "ibscbs.cIndOp": { "type": "string", "pattern": "^\\d{6}$" } }, "additionalProperties": false }, "motivo": { "type": "string", "maxLength": 500, "nullable": true }, "ativo": { "type": "boolean" } }, "required": [ "campos" ], "additionalProperties": false }, "examples": { "irrf": { "value": { "campos": { "ret.irrf.aliquota": "1.50" }, "motivo": "Tomador exige IRRF no licenciamento" } } } } } }, "responses": { "200": { "description": "Regra atualizada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegraParResponse" } } } }, "201": { "description": "Regra criada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegraParResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`): chave de `campos` fora da lista aceita ou valor fora do formato", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Serviço (`servico.nao_encontrado`), tomador (`tomador.nao_encontrado`) ou cliente não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Gravar a regra do par serviço×tomador (upsert)", "tags": [ "Tributacao", "servicos" ], "x-required-scopes": [ "cadastros:write" ] }, "delete": { "operationId": "TributacaoController_removerRegra", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "servicoId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "tomadorId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Regra removida (sem corpo)" }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Regra do par, serviço, tomador ou cliente não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Remover a regra do par serviço×tomador", "tags": [ "Tributacao", "servicos" ], "x-required-scopes": [ "cadastros:write" ], "description": "**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`." } }, "/v1/clientes/{clienteId}/ibpt": { "get": { "description": "Padrão: tributos destacados. Com o token do PRÓPRIO cliente no IBPT e `usarIbpt` ligado, a nota usa os percentuais da tabela vigente. Nunca devolve o token — só `configuradoEm` e `tokenFinal` (últimos 4 caracteres). `status`: sem_token | pendente | ok | token_invalido | erro.\n\n**Escopo exigido:** `fiscal:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`.", "operationId": "IbptController_obter", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IbptEstadoResponse" } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Situação do IBPT do cliente (Lei 12.741)", "tags": [ "perfil-fiscal" ], "x-required-scopes": [ "fiscal:read" ] }, "patch": { "description": "Ligar exige token (409 `ibpt.sem_token`). Desligado = tributos destacados.\n\n**Escopo exigido:** `fiscal:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "IbptController_definirUso", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IbptEstadoResponse" } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Ligar sem token cadastrado (`ibpt.sem_token`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Ligar/desligar o uso do IBPT na Lei 12.741", "tags": [ "perfil-fiscal" ], "x-required-scopes": [ "fiscal:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "usarIbpt": { "type": "boolean" } }, "required": [ "usarIbpt" ], "additionalProperties": false } } } } } }, "/v1/clientes/{clienteId}/ibpt/token": { "put": { "description": "Token do cadastro do próprio cliente (CNPJ do cliente) no De Olho no Imposto; guardado cifrado no cofre. Fica `pendente` até o teste ou a próxima importação. 422 `ibpt.cnpj_uf_obrigatorios`.\n\n**Escopo exigido:** `fiscal:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "IbptController_definirToken", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IbptEstadoResponse" } } } }, "400": { "description": "Token em formato inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Cliente sem CNPJ ou sem UF (`ibpt.cnpj_uf_obrigatorios`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cadastrar ou trocar o token do IBPT do cliente", "tags": [ "perfil-fiscal" ], "x-required-scopes": [ "fiscal:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9._~+/=-]{8,200}$" } }, "required": [ "token" ], "additionalProperties": false } } } } }, "delete": { "description": "Desliga o uso do IBPT e apaga a tabela importada com o token; as notas voltam aos tributos destacados.\n\n**Escopo exigido:** `fiscal:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "IbptController_removerToken", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IbptEstadoResponse" } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente não encontrado ou sem token do IBPT cadastrado (`ibpt.sem_token`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Remover o token do IBPT do cliente", "tags": [ "perfil-fiscal" ], "x-required-scopes": [ "fiscal:write" ] } }, "/v1/clientes/{clienteId}/ibpt/testar": { "post": { "description": "Uma consulta mínima ao IBPT com o token e o CNPJ do cliente; responde só ok/erro (sem a tabela).\n\n**Escopo exigido:** `fiscal:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "IbptController_testar", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IbptTesteResponse" } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Cliente sem token do IBPT cadastrado (`ibpt.sem_token`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Testar o token do IBPT do cliente", "tags": [ "perfil-fiscal" ], "x-required-scopes": [ "fiscal:write" ] } }, "/v1/nfse/{chave}/cancelar": { "post": { "description": "Registra o evento de cancelamento (e101101). O prazo é o definido pelo município emissor da NFS-e (parametrização municipal; fora dele a SEFIN rejeita com E0822). Se a nota já tiver outro evento vinculado que impeça o cancelamento (ex.: bloqueio por ofício, análise fiscal), a SEFIN rejeita com E0840 e o pedido fica `rejected` com o evento informado.\n\n**Escopo exigido:** `nfse:write`; sem ele, `403 insufficient_scope`.", "operationId": "EventosController_cancelar", "parameters": [ { "name": "chave", "required": true, "in": "path", "description": "Chave de acesso (50 dígitos)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "motivo": { "type": "string", "minLength": 15, "maxLength": 255 }, "codigoMotivo": { "type": "string", "enum": [ "1", "2", "9" ], "default": "9", "description": "1 = erro na emissão, 2 = serviço não prestado, 9 = outros" } }, "required": [ "motivo" ] }, "examples": { "padrao": { "summary": "Cancelamento por erro de preenchimento", "value": { "motivo": "Erro no preenchimento do valor unitário do serviço" } } } } } }, "responses": { "201": { "description": "Evento enfileirado; o resultado chega pelos webhooks `nfse.cancelled` e `nfse.event.failed`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventoEnfileiradoResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`, com `issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`), cliente fora da restrição do token ou conta suspensa (`tenant.inativo`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "NFS-e não encontrada (`not_found`) — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "NFS-e já cancelada/substituída ou outro evento em andamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Rejeição local de regra (a rejeição da SEFIN, ex.: E0822, chega pelo webhook nfse.event.failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cancelar NFS-e", "tags": [ "eventos" ], "x-required-scopes": [ "nfse:write" ] } }, "/v1/nfse/{chave}/substituir": { "post": { "description": "Retorna instruções para enviar uma nova DPS com o grupo `substituicao` (chave, cMotivo e, com cMotivo 99, xMotivo de 15 a 255 caracteres — E0078). Prazo: definido pelo município emissor (E0050); sem prazo para cMotivo 01/02 (desenquadramento/enquadramento no Simples Nacional).\n\n**Escopo exigido:** `nfse:write`; sem ele, `403 insufficient_scope`.", "operationId": "EventosController_substituir", "parameters": [ { "name": "chave", "required": true, "in": "path", "description": "Chave de acesso da NFS-e a ser substituída", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Instruções para enviar a DPS substituta (`POST /v1/nfse` com `substituiChaveAcesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubstituicaoInstrucoesResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`, com `issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`), cliente fora da restrição do token ou conta suspensa (`tenant.inativo`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "NFS-e não encontrada (`not_found`) — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "NFS-e já cancelada/substituída", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Rejeição local de regra", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Iniciar substituição", "tags": [ "eventos" ], "x-required-scopes": [ "nfse:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "motivo": { "type": "string", "minLength": 15, "maxLength": 255 } }, "required": [ "motivo" ] } } } } } }, "/v1/webhooks": { "get": { "operationId": "WebhooksController_list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Próxima página; ausente na última.", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookResponse" } } } } }, "400": { "description": "Parâmetro inválido (`query.invalida`, `cursor.invalido`, `limit.invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Listar webhooks do tenant", "tags": [ "webhooks" ], "x-required-scopes": [ "webhooks:read" ], "description": "**Escopo exigido:** `webhooks:read`; sem ele, `403 insufficient_scope`." }, "post": { "description": "O segredo HMAC retornado é exibido APENAS uma vez. As entregas serão assinadas com header `X-Webhook-Signature: sha256=` calculado sobre `{timestamp}.{body}`.\n\nEventos disponíveis:\n- `nfse.authorized` — NFS-e autorizada pelo SEFIN\n- `nfse.rejected` — DPS rejeitada\n- `nfse.cancelled` — NFS-e cancelada\n- `nfse.replaced` — NFS-e substituída\n- `nfse.event.failed` — Falha ao registrar evento\n- `dfe.received` — Novo DF-e recebido (tomador)\n- `cert.expiring` — Certificado próximo do vencimento\n- `cert.expired` — Certificado expirou\n- `cobranca.gerada` — Cobrança (boleto/PIX) gerada para o tomador\n- `cobranca.paga` — Pagamento confirmado pelo Asaas\n- `cobranca.vencida` — Cobrança vencida sem pagamento\n- `cobranca.cancelada` — Cobrança cancelada (inclusive junto com a NFS-e)\n- `cobranca.estornada` — Pagamento estornado ou em chargeback\n- `webhook.test` — Disparo manual de teste\n\n**Escopo exigido:** `webhooks:write`; sem ele, `403 insufficient_scope`.", "operationId": "WebhooksController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "format": "uri" }, "eventos": { "type": "array", "items": { "type": "string", "enum": [ "nfse.authorized", "nfse.rejected", "nfse.cancelled", "nfse.replaced", "nfse.event.failed", "dfe.received", "nfe.received", "nfe.cancelled", "nfe.manifestation.registered", "nfe.manifestation.rejected", "nfe.emitida.authorized", "nfe.emitida.rejected", "nfe.emitida.denied", "nfe.emitida.cancelled", "nfe.emitida.corrected", "nfe.inutilizacao.registered", "nfe.emitida.contingency", "nfe.contingencia.activated", "nfe.contingencia.deactivated", "cert.expiring", "cert.expired", "cobranca.gerada", "cobranca.paga", "cobranca.vencida", "cobranca.cancelada", "cobranca.estornada", "pedido.criado", "pedido.atualizado", "webhook.test" ] }, "minItems": 1 }, "empresaId": { "type": "string", "format": "uuid" } }, "required": [ "nome", "url", "eventos" ] }, "examples": { "padrao": { "summary": "Webhook para eventos críticos", "value": { "nome": "ERP Produção", "url": "https://erp.cliente.com/integracoes/nfse", "eventos": [ "nfse.authorized", "nfse.rejected", "nfse.cancelled", "dfe.received" ] } } } } } }, "responses": { "201": { "description": "Webhook criado; o segredo HMAC (`secret`) só aparece nesta resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreatedResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`, com `issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Criar webhook", "tags": [ "webhooks" ], "x-required-scopes": [ "webhooks:write" ] } }, "/v1/webhooks/{id}": { "patch": { "operationId": "WebhooksController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`, com `issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Webhook não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Atualizar webhook", "tags": [ "webhooks" ], "x-required-scopes": [ "webhooks:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "format": "uri" }, "eventos": { "type": "array", "items": { "type": "string", "enum": [ "nfse.authorized", "nfse.rejected", "nfse.cancelled", "nfse.replaced", "nfse.event.failed", "dfe.received", "nfe.received", "nfe.cancelled", "nfe.manifestation.registered", "nfe.manifestation.rejected", "nfe.emitida.authorized", "nfe.emitida.rejected", "nfe.emitida.denied", "nfe.emitida.cancelled", "nfe.emitida.corrected", "nfe.inutilizacao.registered", "nfe.emitida.contingency", "nfe.contingencia.activated", "nfe.contingencia.deactivated", "cert.expiring", "cert.expired", "cobranca.gerada", "cobranca.paga", "cobranca.vencida", "cobranca.cancelada", "cobranca.estornada", "pedido.criado", "pedido.atualizado", "webhook.test" ] }, "minItems": 1 }, "ativo": { "type": "boolean" } } } } } }, "description": "**Escopo exigido:** `webhooks:write`; sem ele, `403 insufficient_scope`." }, "delete": { "operationId": "WebhooksController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "description": "Parâmetro inválido (`query.invalida`, `cursor.invalido`, `limit.invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Webhook não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Remover webhook", "tags": [ "webhooks" ], "x-required-scopes": [ "webhooks:write" ], "description": "**Escopo exigido:** `webhooks:write`; sem ele, `403 insufficient_scope`." } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "WebhooksController_test", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Entrega de teste enfileirada (`webhook.test`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntregaDeTesteResponse" } } } }, "400": { "description": "Parâmetro inválido (`query.invalida`, `cursor.invalido`, `limit.invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Webhook não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Disparar entrega de teste", "tags": [ "webhooks" ], "x-required-scopes": [ "webhooks:write" ], "description": "**Escopo exigido:** `webhooks:write`; sem ele, `403 insufficient_scope`." } }, "/v1/webhooks/{id}/entregas": { "get": { "operationId": "WebhooksController_entregas", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Próxima página; ausente na última.", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } }, "400": { "description": "Parâmetro inválido (`query.invalida`, `cursor.invalido`, `limit.invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Webhook não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Histórico de entregas — criação DESC, id DESC", "tags": [ "webhooks" ], "x-required-scopes": [ "webhooks:read" ], "description": "**Escopo exigido:** `webhooks:read`; sem ele, `403 insufficient_scope`." } }, "/v1/webhooks/entregas/{entregaId}/retry": { "post": { "operationId": "WebhooksController_retry", "parameters": [ { "name": "entregaId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Entrega reenfileirada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntregaReenfileiradaResponse" } } } }, "400": { "description": "Parâmetro inválido (`query.invalida`, `cursor.invalido`, `limit.invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Entrega não encontrada — inclusive de outra conta — ou que não está em estado falho (`dead`/`failed`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Reenviar entrega que falhou ou foi para DLQ (status=dead)", "tags": [ "webhooks" ], "x-required-scopes": [ "webhooks:write" ], "description": "**Escopo exigido:** `webhooks:write`; sem ele, `403 insufficient_scope`." } }, "/v1/clientes/{empresaId}/dfe": { "get": { "description": "NFS-e e eventos em que a empresa é parte, distribuídos pelo ADN por NSU.\n\n**Escopo exigido:** `dfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "DfeController_listar[0]", "parameters": [ { "name": "empresaId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "recebidas", "required": false, "in": "query", "description": "true = só NFS-e de terceiros (cliente como tomador)", "schema": { "type": "string" } }, { "name": "competencia", "required": false, "in": "query", "description": "AAAA-MM", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Próxima página; ausente na última.", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "security": [ { "bearer": [] } ], "summary": "Documentos fiscais recebidos (DF-e) da empresa", "tags": [ "dfe" ], "x-required-scopes": [ "dfe:read" ] } }, "/v1/empresas/{empresaId}/dfe": { "get": { "description": "**DEPRECIADO** (Sunset 2027-06-30): alias legado — use `/v1/clientes/{empresaId}/dfe`.\n\nNFS-e e eventos em que a empresa é parte, distribuídos pelo ADN por NSU.\n\n**Escopo exigido:** `dfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "DfeController_listar[1]", "parameters": [ { "name": "empresaId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "recebidas", "required": false, "in": "query", "description": "true = só NFS-e de terceiros (cliente como tomador)", "schema": { "type": "string" } }, { "name": "competencia", "required": false, "in": "query", "description": "AAAA-MM", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Próxima página; ausente na última.", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "security": [ { "bearer": [] } ], "summary": "Documentos fiscais recebidos (DF-e) da empresa", "tags": [ "dfe" ], "deprecated": true, "x-required-scopes": [ "dfe:read" ] } }, "/v1/clientes/{empresaId}/dfe/situacao": { "get": { "operationId": "DfeController_situacaoCliente[0]", "parameters": [ { "name": "empresaId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DfeSituacaoResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Situação da busca de notas recebidas do cliente (última tentativa, sucesso, erro)", "tags": [ "dfe" ], "x-required-scopes": [ "dfe:read" ], "description": "**Escopo exigido:** `dfe:read`; sem ele, `403 insufficient_scope`." } }, "/v1/empresas/{empresaId}/dfe/situacao": { "get": { "operationId": "DfeController_situacaoCliente[1]", "parameters": [ { "name": "empresaId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DfeSituacaoResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Situação da busca de notas recebidas do cliente (última tentativa, sucesso, erro)", "tags": [ "dfe" ], "deprecated": true, "description": "**DEPRECIADO** (Sunset 2027-06-30): alias legado — use `/v1/clientes/{empresaId}/dfe/situacao`.\n\n**Escopo exigido:** `dfe:read`; sem ele, `403 insufficient_scope`.", "x-required-scopes": [ "dfe:read" ] } }, "/v1/clientes/{empresaId}/dfe/sincronizar": { "post": { "operationId": "DfeController_sincronizar[0]", "parameters": [ { "name": "empresaId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sincronização enfileirada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DfeSincronizacaoResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Dispara a sincronização de DF-e com o ADN (além da rotina a cada 5 min)", "tags": [ "dfe" ], "x-required-scopes": [ "nfse:write" ], "description": "**Escopo exigido:** `nfse:write`; sem ele, `403 insufficient_scope`." } }, "/v1/empresas/{empresaId}/dfe/sincronizar": { "post": { "operationId": "DfeController_sincronizar[1]", "parameters": [ { "name": "empresaId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Sincronização enfileirada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DfeSincronizacaoResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Dispara a sincronização de DF-e com o ADN (além da rotina a cada 5 min)", "tags": [ "dfe" ], "deprecated": true, "description": "**DEPRECIADO** (Sunset 2027-06-30): alias legado — use `/v1/clientes/{empresaId}/dfe/sincronizar`.\n\n**Escopo exigido:** `nfse:write`; sem ele, `403 insufficient_scope`.", "x-required-scopes": [ "nfse:write" ] } }, "/v1/dfe/recebidas": { "get": { "description": "Visão \"Todos os clientes\" da tela Notas recebidas: mais recentes primeiro, com o cliente (tomador) de cada nota. Respeita a restrição por cliente do usuário/token. Para um cliente só, use `GET /v1/clientes/{id}/dfe?recebidas=true`.\n\n**Escopo exigido:** `dfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "DfeSituacaoController_recebidas", "parameters": [ { "name": "competencia", "required": false, "in": "query", "description": "AAAA-MM", "schema": {} }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Próxima página; ausente na última.", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "security": [ { "bearer": [] } ], "summary": "Notas recebidas (NFS-e de terceiros) de todos os clientes que a sessão vê", "tags": [ "dfe" ], "x-required-scopes": [ "dfe:read" ] } }, "/v1/dfe/situacao": { "get": { "operationId": "DfeSituacaoController_situacao", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DfeSituacaoResponse" } } } } } }, "security": [ { "bearer": [] } ], "summary": "Monitoramento: situação da busca de notas recebidas de todos os clientes", "tags": [ "dfe" ], "x-required-scopes": [ "dfe:read" ], "description": "**Escopo exigido:** `dfe:read`; sem ele, `403 insufficient_scope`." } }, "/v1/clientes/{id}/nfe-recebidas": { "get": { "description": "NF-e em que o cliente é destinatário, mais recentes primeiro (data de emissão), paginadas por cursor: o corpo é um array e a próxima página vem no cabeçalho `X-Next-Cursor`. A ordem é estável (emissão + id): inserções durante a leitura não duplicam nem pulam itens.\n\n**Escopo exigido:** `dfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfeRecebidasController_listar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Itens por página: 1 a 200 (padrão 50).", "schema": {} }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco da página seguinte (`X-Next-Cursor`).", "schema": {} }, { "name": "q", "required": false, "in": "query", "description": "Chave de acesso completa (44 dígitos) ou parte do nome do emitente (2–100 caracteres)", "schema": {} }, { "name": "manifestacao", "required": false, "in": "query", "schema": { "enum": [ "pendente", "ciencia", "confirmada", "desconhecida", "nao_realizada" ], "type": "string" } }, { "name": "situacao", "required": false, "in": "query", "schema": { "enum": [ "autorizada", "denegada", "cancelada" ], "type": "string" } }, { "name": "emitente", "required": false, "in": "query", "description": "CPF/CNPJ do emitente (com ou sem máscara)", "schema": {} }, { "name": "emissaoAte", "required": false, "in": "query", "description": "AAAA-MM-DD (inclusiva, horário de Brasília)", "schema": {} }, { "name": "emissaoDe", "required": false, "in": "query", "description": "AAAA-MM-DD (inclusiva, horário de Brasília)", "schema": {} } ], "responses": { "200": { "description": "Página de NF-e recebidas (array); próxima página no cabeçalho `X-Next-Cursor`.", "headers": { "X-Next-Cursor": { "description": "Cursor da próxima página (ausente na última).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NfeRecebidaItemResponse" } } } } }, "400": { "description": "Filtro inválido (`query.invalida`), cursor adulterado (`cursor.invalido`) ou `limit` fora de 1–200 (`limit.invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Recurso não liberado para a conta (`nfe.nao_liberada` — a NF-e recebidas é liberada conta a conta pelo suporte), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente não encontrado (inclusive de outra conta) ou NF-e não encontrada (`nfe.nao_encontrada`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Listar NF-e recebidas do cliente", "tags": [ "nfe-recebidas" ], "x-required-scopes": [ "dfe:read" ] } }, "/v1/clientes/{id}/nfe-recebidas/config": { "get": { "description": "Busca automática (padrão desligada), ciência automática e a situação do certificado A1.\n\n**Escopo exigido:** `dfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfeRecebidasController_config", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeRecebidasConfigResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Recurso não liberado para a conta (`nfe.nao_liberada` — a NF-e recebidas é liberada conta a conta pelo suporte), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente não encontrado (inclusive de outra conta) ou NF-e não encontrada (`nfe.nao_encontrada`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Configuração da busca de NF-e do cliente", "tags": [ "nfe-recebidas" ], "x-required-scopes": [ "dfe:read" ] }, "patch": { "description": "Ligar exige certificado A1 vigente do cliente (`422 nfe.sem_certificado`). A SEFAZ só gera NSU para quem consulta: as notas aparecem a partir da primeira busca, sem retroativo além de 90 dias. Com a ciência automática, cada resumo novo gera um pedido de Ciência da Operação (libera o XML completo).\n\n**Escopo exigido:** `dfe:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfeRecebidasController_alterarConfig", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Recomendado (UUID v4): reenvio com a mesma chave e o mesmo corpo devolve a mesma resposta; corpo diferente → 409.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "ativo": { "type": "boolean" }, "cienciaAutomatica": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeRecebidasConfigResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Recurso não liberado para a conta (`nfe.nao_liberada` — a NF-e recebidas é liberada conta a conta pelo suporte), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente não encontrado (inclusive de outra conta) ou NF-e não encontrada (`nfe.nao_encontrada`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Mesma `Idempotency-Key` com outro corpo ou ainda em andamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Ligar sem certificado A1 vigente (`nfe.sem_certificado`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Ligar/desligar a busca de NF-e e a ciência automática", "tags": [ "nfe-recebidas" ], "x-required-scopes": [ "dfe:write" ] } }, "/v1/clientes/{id}/nfe-recebidas/sincronizar": { "post": { "description": "Enfileira a busca na Distribuição DF-e SÓ se a SEFAZ já permitir uma nova consulta (`proximaConsultaEm` vazia ou passada). Depois de \"nenhum documento\" (137), de consumo indevido (656) ou de alcançar o último NSU, a SEFAZ exige 1 h de espera — consultar antes bloqueia o CNPJ por mais 1 h. Bloqueada: `409 nfe.consulta_bloqueada` com `Retry-After` (segundos). A rotina automática roda a cada 5 min respeitando a mesma regra.\n\n**Escopo exigido:** `dfe:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfeRecebidasController_sincronizar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Busca enfileirada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeBuscaEnfileiradaResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Recurso não liberado para a conta (`nfe.nao_liberada` — a NF-e recebidas é liberada conta a conta pelo suporte), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente não encontrado (inclusive de outra conta) ou NF-e não encontrada (`nfe.nao_encontrada`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "A SEFAZ ainda não permite nova consulta (`nfe.consulta_bloqueada`, com `proximaConsultaEm`): aguarde o `Retry-After` (s). Consultar antes geraria o 656 e mais 1 h de bloqueio.", "headers": { "Retry-After": { "description": "Segundos até a próxima consulta permitida.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Busca de NF-e desligada para o cliente (`nfe.busca_desligada`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Antecipar a busca de NF-e do cliente", "tags": [ "nfe-recebidas" ], "x-required-scopes": [ "dfe:write" ] } }, "/v1/clientes/{id}/nfe-recebidas/situacao": { "get": { "description": "Última busca, último cStat, próxima consulta permitida pela SEFAZ e o último erro.\n\n**Escopo exigido:** `dfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfeRecebidasController_situacao", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeSituacaoResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Recurso não liberado para a conta (`nfe.nao_liberada` — a NF-e recebidas é liberada conta a conta pelo suporte), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente não encontrado (inclusive de outra conta) ou NF-e não encontrada (`nfe.nao_encontrada`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Situação da busca de NF-e do cliente", "tags": [ "nfe-recebidas" ], "x-required-scopes": [ "dfe:read" ] } }, "/v1/clientes/{id}/nfe-recebidas/{chave}": { "get": { "description": "Dados da nota, documentos e eventos recebidos (por NSU), manifestações e o que pode ser manifestado agora.\n\n**Escopo exigido:** `dfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfeRecebidasController_detalhe", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "chave", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeRecebidaDetalheResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Recurso não liberado para a conta (`nfe.nao_liberada` — a NF-e recebidas é liberada conta a conta pelo suporte), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente não encontrado (inclusive de outra conta) ou NF-e não encontrada (`nfe.nao_encontrada`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Detalhe de uma NF-e recebida", "tags": [ "nfe-recebidas" ], "x-required-scopes": [ "dfe:read" ] } }, "/v1/clientes/{id}/nfe-recebidas/{chave}/xml": { "get": { "description": "`tipo=completo` (padrão) devolve o procNFe, disponível só depois da Ciência da Operação, da Confirmação ou da Operação não Realizada (`409 nfe.xml_indisponivel` antes disso); `tipo=resumo` devolve o resNFe. Com `redirecionar=true` responde `302` para a URL.\n\n**Escopo exigido:** `dfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfeRecebidasController_xml", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "chave", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "tipo", "required": false, "in": "query", "schema": { "enum": [ "completo", "resumo" ], "type": "string" } }, { "name": "redirecionar", "required": false, "in": "query", "schema": { "enum": [ "true", "false" ], "type": "string" } } ], "responses": { "200": { "description": "URL pré-assinada do XML (300 s)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeXmlUrlResponse" } } } }, "302": { "description": "Com `redirecionar=true`: redireciona para a URL pré-assinada (`Location`)" }, "400": { "description": "`tipo` diferente de `completo`/`resumo` (`query.invalida`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Recurso não liberado para a conta (`nfe.nao_liberada` — a NF-e recebidas é liberada conta a conta pelo suporte), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente não encontrado (inclusive de outra conta) ou NF-e não encontrada (`nfe.nao_encontrada`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "XML ainda não disponível (`nfe.xml_indisponivel`): o completo só vem depois da Ciência da Operação", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "XML da NF-e recebida (URL pré-assinada de 300 s)", "tags": [ "nfe-recebidas" ], "x-required-scopes": [ "dfe:read" ] } }, "/v1/clientes/{id}/nfe-recebidas/{chave}/manifestar": { "post": { "description": "Registra o pedido (`pendente`) e o envia à SEFAZ em segundo plano. Prazos (NT 2020.001 v1.60): Ciência até 10 dias da autorização; Confirmação, Desconhecimento e Operação não Realizada até 90 dias, no máximo 2 de cada tipo; Ciência não é aceita depois de uma conclusiva; Operação não Realizada exige `justificativa` de 15 a 255 caracteres. Ciência, Confirmação e Operação não Realizada liberam o XML completo. O resultado chega pelos webhooks `nfe.manifestation.registered`/`nfe.manifestation.rejected` e no detalhe da nota.\n\n**Escopo exigido:** `dfe:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfeRecebidasController_manifestar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "chave", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Recomendado (UUID v4): reenvio com a mesma chave e o mesmo corpo devolve a mesma resposta; corpo diferente → 409.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tipo" ], "additionalProperties": false, "properties": { "tipo": { "type": "string", "enum": [ "confirmacao", "ciencia", "desconhecimento", "nao_realizada" ] }, "justificativa": { "type": "string", "minLength": 15, "maxLength": 255, "description": "Obrigatória (e só aceita) em `nao_realizada`." } } } } } }, "responses": { "202": { "description": "Pedido gravado (`pendente`) e enfileirado; o resultado chega pelo webhook `nfe.manifestation.registered`/`rejected` e no detalhe", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeManifestacaoResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Recurso não liberado para a conta (`nfe.nao_liberada` — a NF-e recebidas é liberada conta a conta pelo suporte), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente não encontrado (inclusive de outra conta) ou NF-e não encontrada (`nfe.nao_encontrada`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Já existe pedido do mesmo tipo em andamento (`nfe.manifestacao_duplicada`, com `pedido`), mesma `Idempotency-Key` com outro corpo ou ainda em andamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Manifestação recusada antes do envio (`nfe.manifestacao_invalida`, com `motivo`): fora do prazo (10 dias ciência / 90 dias conclusiva), sequência > 2, ciência depois de conclusiva, justificativa ausente/inválida (15–255) em Operação não Realizada, justificativa em outro tipo, NF-e cancelada ou denegada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Manifestação do destinatário", "tags": [ "nfe-recebidas" ], "x-required-scopes": [ "dfe:write" ] } }, "/v1/clientes/{id}/nfe-produtos": { "get": { "description": "Em ordem de código, paginados por cursor (keyset): o corpo é um array e a próxima página vem no cabeçalho `X-Next-Cursor`.\n\n**Escopo exigido:** `cadastros:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeCadastrosController_listar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "ativo", "required": false, "in": "query", "description": "`true`/`false`; ausente = todos.", "schema": {} }, { "name": "q", "required": false, "in": "query", "description": "Descrição (contém), início do código ou início do NCM", "schema": {} }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Cursor da próxima página (ausente na última).", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NfeProdutoResponse" } } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Listar produtos do cliente", "tags": [ "NfeCadastros", "produtos" ], "x-required-scopes": [ "cadastros:read" ] }, "post": { "description": "Perfil fiscal do produto (caminho A): CFOP interno/interestadual, ICMS por CST (regime normal) ou CSOSN (Simples), base, alíquota, redução, ST (MVA, alíquota, redução), FCP, crédito do Simples, cBenef, PIS/COFINS, IPI. A emissão usa esse perfil e confere a coerência. Código duplicado → 409 `produto.codigo_duplicado`.\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeCadastrosController_criar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Recomendado (UUID v4): reenvio com a mesma chave e o mesmo corpo devolve a mesma resposta; corpo diferente → 409.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "codigo": { "type": "string", "minLength": 1, "maxLength": 60 }, "descricao": { "type": "string", "minLength": 1, "maxLength": 120 }, "ncm": { "type": "string" }, "unidade": { "type": "string", "minLength": 1, "maxLength": 6 }, "cfopInterno": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "pisCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "cofinsCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "cest": { "type": "string", "nullable": true }, "gtin": { "type": "string", "nullable": true }, "valorPadrao": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "ibscbsCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "ibscbsCclassTrib": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "fci": { "type": "string", "nullable": true }, "ativo": { "type": "boolean" }, "origem": { "type": "integer", "minimum": 0, "maximum": 8 }, "cfopInterestadual": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "icmsCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "icmsCsosn": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "icmsModBc": { "type": "integer", "minimum": 0, "maximum": 3, "nullable": true }, "icmsAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsReducaoBc": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsModBcSt": { "type": "integer", "minimum": 0, "maximum": 6, "nullable": true }, "icmsMvaOriginal": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsAliquotaSt": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsReducaoBcSt": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsAliquotaCreditoSn": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "fcpAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "fcpStAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "cbenef": { "type": "string", "pattern": "^[A-Z0-9]{8}$|^[A-Z0-9]{10}$", "nullable": true }, "pisAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "cofinsAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "ipiCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "ipiCenq": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "ipiAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true } }, "required": [ "codigo", "descricao", "ncm", "unidade", "cfopInterno", "pisCst", "cofinsCst" ], "additionalProperties": false }, "examples": { "simples": { "value": { "codigo": "CAM-001", "descricao": "Camiseta algodão", "ncm": "61091000", "unidade": "UN", "valorPadrao": "49.90", "origem": 0, "cfopInterno": "5102", "cfopInterestadual": "6102", "icmsCsosn": "102", "pisCst": "49", "cofinsCst": "49" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeProdutoResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`) ou perfil fiscal incoerente (`produto.fiscal_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Código já usado por outro produto do cliente (`produto.codigo_duplicado`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cadastrar produto", "tags": [ "NfeCadastros", "produtos" ], "x-required-scopes": [ "cadastros:write" ] } }, "/v1/clientes/{id}/nfe-produtos/upsert": { "put": { "description": "Upsert pelo `codigo` no corpo: 201 criado / 200 atualizado. Atômico e idempotente por natureza.\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeCadastrosController_upsert", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "codigo": { "type": "string", "minLength": 1, "maxLength": 60 }, "descricao": { "type": "string", "minLength": 1, "maxLength": 120 }, "ncm": { "type": "string" }, "unidade": { "type": "string", "minLength": 1, "maxLength": 6 }, "cfopInterno": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "pisCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "cofinsCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "cest": { "type": "string", "nullable": true }, "gtin": { "type": "string", "nullable": true }, "valorPadrao": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "ibscbsCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "ibscbsCclassTrib": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "fci": { "type": "string", "nullable": true }, "ativo": { "type": "boolean" }, "origem": { "type": "integer", "minimum": 0, "maximum": 8 }, "cfopInterestadual": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "icmsCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "icmsCsosn": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "icmsModBc": { "type": "integer", "minimum": 0, "maximum": 3, "nullable": true }, "icmsAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsReducaoBc": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsModBcSt": { "type": "integer", "minimum": 0, "maximum": 6, "nullable": true }, "icmsMvaOriginal": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsAliquotaSt": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsReducaoBcSt": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsAliquotaCreditoSn": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "fcpAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "fcpStAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "cbenef": { "type": "string", "pattern": "^[A-Z0-9]{8}$|^[A-Z0-9]{10}$", "nullable": true }, "pisAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "cofinsAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "ipiCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "ipiCenq": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "ipiAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true } }, "required": [ "codigo", "descricao", "ncm", "unidade", "cfopInterno", "pisCst", "cofinsCst" ], "additionalProperties": false }, "examples": { "simples": { "value": { "codigo": "CAM-001", "descricao": "Camiseta algodão", "ncm": "61091000", "unidade": "UN", "valorPadrao": "49.90", "origem": 0, "cfopInterno": "5102", "cfopInterestadual": "6102", "icmsCsosn": "102", "pisCst": "49", "cofinsCst": "49" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeProdutoResponse" } } } }, "201": { "description": "Criado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeProdutoResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`) ou perfil fiscal incoerente (`produto.fiscal_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Criar ou atualizar produto pelo código do ERP", "tags": [ "NfeCadastros", "produtos" ], "x-required-scopes": [ "cadastros:write" ] } }, "/v1/clientes/{id}/nfe-produtos/{produtoId}": { "get": { "operationId": "NfeCadastrosController_obter", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "produtoId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeProdutoResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`) ou perfil fiscal incoerente (`produto.fiscal_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Consultar produto", "tags": [ "NfeCadastros", "produtos" ], "x-required-scopes": [ "cadastros:read" ], "description": "**Escopo exigido:** `cadastros:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`." }, "patch": { "description": "Campo a campo; o código não muda; campo desconhecido → 400. O perfil resultante precisa ser coerente.\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeCadastrosController_alterar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "produtoId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "descricao": { "type": "string", "minLength": 1, "maxLength": 120 }, "ncm": { "type": "string" }, "cest": { "type": "string", "nullable": true }, "gtin": { "type": "string", "nullable": true }, "unidade": { "type": "string", "minLength": 1, "maxLength": 6 }, "valorPadrao": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "ibscbsCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "ibscbsCclassTrib": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "fci": { "type": "string", "nullable": true }, "ativo": { "type": "boolean" }, "origem": { "type": "integer", "minimum": 0, "maximum": 8 }, "cfopInterno": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "cfopInterestadual": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "icmsCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "icmsCsosn": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "icmsModBc": { "type": "integer", "minimum": 0, "maximum": 3, "nullable": true }, "icmsAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsReducaoBc": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsModBcSt": { "type": "integer", "minimum": 0, "maximum": 6, "nullable": true }, "icmsMvaOriginal": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsAliquotaSt": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsReducaoBcSt": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "icmsAliquotaCreditoSn": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "fcpAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "fcpStAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "cbenef": { "type": "string", "pattern": "^[A-Z0-9]{8}$|^[A-Z0-9]{10}$", "nullable": true }, "pisCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "pisAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "cofinsCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ] }, "cofinsAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "ipiCst": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "ipiCenq": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true }, "ipiAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeProdutoResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`) ou perfil fiscal incoerente (`produto.fiscal_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Alterar produto", "tags": [ "NfeCadastros", "produtos" ], "x-required-scopes": [ "cadastros:write" ] }, "delete": { "description": "Mantido para o histórico das notas (ativo = false); produto inativo não entra em emissão nova (422 `produto.inativo`).\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeCadastrosController_desativar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "produtoId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Produto desativado (sem corpo)." }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Desativar produto", "tags": [ "NfeCadastros", "produtos" ], "x-required-scopes": [ "cadastros:write" ] } }, "/v1/clientes/{id}/nfe-config": { "get": { "description": "IE, CRT, regime de PIS/COFINS, séries padrão, versão do QR Code, informações complementares padrão e o CSC (só o idCSC e os 4 últimos caracteres).\n\n**Escopo exigido:** `fiscal:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeCadastrosController_obterConfig", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeConfigResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta\n\nConfiguração ainda não feita (`nfe_emissao.sem_configuracao`) ou cliente de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Configuração de NF-e/NFC-e do cliente", "tags": [ "NfeCadastros", "nfe" ], "x-required-scopes": [ "fiscal:read" ] }, "patch": { "description": "Campo a campo. A primeira configuração exige `ie` e `crt` (422 `nfe_emissao.config_incompleta`). CRT 1/4 (Simples/MEI) usa CSOSN nos produtos; CRT 2/3, CST. Série 0–889 para CNPJ (920–969 para emitente CPF). QR Code v3 dispensa o CSC.\n\n**Escopo exigido:** `fiscal:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeCadastrosController_alterarConfig", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "ie": { "type": "string", "example": "123456785016" }, "crt": { "type": "integer", "enum": [ 1, 2, 3, 4 ] }, "regimePisCofins": { "type": "string", "enum": [ "simples", "cumulativo", "nao_cumulativo" ] }, "serieNfe": { "type": "integer" }, "serieNfce": { "type": "integer" }, "qrcodeVersao": { "type": "integer", "enum": [ 2, 3 ] }, "infAdicPadrao": { "type": "string", "nullable": true, "maxLength": 5000 }, "excluirIcmsBasePisCofins": { "type": "boolean" }, "tributosAproximados": { "type": "boolean" }, "ieSubstituto": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "SP": "110042490114" } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeConfigResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Primeira configuração sem IE e CRT, ou CSC antes da configuração (`nfe_emissao.config_incompleta`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Criar ou alterar a configuração de NF-e/NFC-e", "tags": [ "NfeCadastros", "nfe" ], "x-required-scopes": [ "fiscal:write" ] } }, "/v1/clientes/{id}/nfe-config/csc": { "put": { "description": "Código de Segurança do Contribuinte (QR Code v2), obtido no portal da SEFAZ da UF. Guardado cifrado no cofre; nunca volta na resposta, no log ou na auditoria — só o idCSC e os 4 últimos caracteres.\n\n**Escopo exigido:** `fiscal:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeCadastrosController_definirCsc", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "idCSC", "csc" ], "additionalProperties": false, "properties": { "idCSC": { "type": "string", "example": "1" }, "csc": { "type": "string", "minLength": 16, "maxLength": 36 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeConfigResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Primeira configuração sem IE e CRT, ou CSC antes da configuração (`nfe_emissao.config_incompleta`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cadastrar ou trocar o CSC da NFC-e", "tags": [ "NfeCadastros", "nfe" ], "x-required-scopes": [ "fiscal:write" ] }, "delete": { "description": "Sem CSC, a NFC-e só é emitida com QR Code v3. Sem CSC cadastrado → 404 `nfe_emissao.sem_csc`.\n\n**Escopo exigido:** `fiscal:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeCadastrosController_removerCsc", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "UUID do cliente", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeConfigResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Primeira configuração sem IE e CRT, ou CSC antes da configuração (`nfe_emissao.config_incompleta`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Remover o CSC da NFC-e", "tags": [ "NfeCadastros", "nfe" ], "x-required-scopes": [ "fiscal:write" ] } }, "/v1/clientes/{id}/nfe-regras-icms": { "get": { "description": "Em ordem de UF de destino e id, paginadas por cursor (keyset): o corpo é um array e a próxima página vem no cabeçalho `X-Next-Cursor`.\n\n**Escopo exigido:** `cadastros:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeFiscalController_listar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Início do NCM, CEST (7 dígitos) ou início do código do produto", "schema": {} }, { "name": "ufDestino", "required": false, "in": "query", "description": "UF de destino (2 letras)", "schema": {} }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Cursor da próxima página (ausente na última).", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NfeRegraIcmsResponse" } } } } }, "400": { "description": "Filtro inválido (`query.invalida`, `cursor.invalido`, `limit.invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Listar regras de ICMS por UF", "tags": [ "NfeFiscal", "produtos" ], "x-required-scopes": [ "cadastros:read" ] }, "post": { "description": "Casa por produto (`produtoId`), CEST ou prefixo de NCM (2 a 8 dígitos) na UF de destino, dentro da vigência. `sujeitoSt = false` marca o produto como fora da ST naquela UF; com `sujeitoSt = true` informe ao menos um percentual. Percentuais de 0 a 999,9999. Mesma combinação de UF, produto, CEST, NCM e início de vigência → 409 `regra_icms.duplicada`.\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeFiscalController_criar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ufDestino": { "type": "string" }, "produtoId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "nullable": true }, "cest": { "type": "string", "nullable": true }, "ncm": { "type": "string", "nullable": true }, "sujeitoSt": { "type": "boolean" }, "mvaOriginal": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "aliquotaInterna": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "fcpAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "reducaoBcSt": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "aliquotaInterestadual": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "difalBaseDupla": { "type": "boolean", "nullable": true }, "baseLegal": { "type": "string", "maxLength": 200, "nullable": true }, "vigenciaInicio": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "nullable": true }, "vigenciaFim": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "nullable": true } }, "required": [ "ufDestino" ], "additionalProperties": false }, "examples": { "st": { "value": { "ufDestino": "SP", "ncm": "2203", "sujeitoSt": true, "mvaOriginal": "40", "aliquotaInterna": "18", "fcpAliquota": "2", "baseLegal": "RICMS/SP art. 313-A", "vigenciaInicio": "2026-01-01" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeRegraIcmsResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`) ou regra incoerente (`regra_icms.invalida`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Regra duplicada (`regra_icms.duplicada`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "`produtoId` de outro cliente (`regra_icms.produto_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cadastrar regra de ICMS por UF", "tags": [ "NfeFiscal", "produtos" ], "x-required-scopes": [ "cadastros:write" ] } }, "/v1/clientes/{id}/nfe-regras-icms/referencia-uf": { "get": { "description": "Tabela embarcada na plataforma (alíquota modal interna, FCP, base dupla do DIFAL, vigência e fonte); serve de apoio ao cadastro das regras. Lista completa (27 UFs), sem paginação.\n\n**Escopo exigido:** `cadastros:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeFiscalController_referencia", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReferenciaUfResponse" } } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Referência de alíquota interna, FCP e DIFAL por UF", "tags": [ "NfeFiscal", "produtos" ], "x-required-scopes": [ "cadastros:read" ] } }, "/v1/clientes/{id}/nfe-regras-icms/importar": { "post": { "description": "CSV separado por `;` com cabeçalho `uf_destino;ncm;cest;codigo_produto;sujeito_st;mva_original;aliquota_interna;fcp;reducao_bc_st;aliquota_interestadual;base_legal;vigencia_inicio;vigencia_fim` e, opcionalmente, `difal_base_dupla` (vazio = referência do sistema; S/N, 1/0, true/false). Decimais com vírgula ou ponto; `sujeito_st` S/N, 1/0 ou true/false (vazio = S); datas AAAA-MM-DD ou DD/MM/AAAA. Tudo ou nada: com erro em alguma linha nada é gravado (422 `regra_icms.csv_invalido` com `erros`). `substituir: true` apaga antes as regras atuais do cliente (mesma transação). Linhas repetidas (mesma chave) entram em `ignoradas`.\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeFiscalController_importarRegras", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "csv" ], "additionalProperties": false, "properties": { "csv": { "type": "string", "example": "uf_destino;ncm;cest;codigo_produto;sujeito_st;mva_original;aliquota_interna;fcp;reducao_bc_st;aliquota_interestadual;base_legal;vigencia_inicio;vigencia_fim\nSP;2203;;;S;40;18;2;;;RICMS/SP;2026-01-01;" }, "substituir": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportacaoRegrasResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "CSV com erro de cabeçalho ou de linha (`regra_icms.csv_invalido`, com `erros`) ou grande demais (`regra_icms.csv_grande`); nada é gravado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemCsvResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Importar regras de ICMS por CSV", "tags": [ "NfeFiscal", "produtos" ], "x-required-scopes": [ "cadastros:write" ] } }, "/v1/clientes/{id}/nfe-regras-icms/{regraId}": { "patch": { "description": "Campo a campo; campo desconhecido → 400. A regra resultante precisa continuar válida.\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeFiscalController_alterar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "regraId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ufDestino": { "type": "string" }, "produtoId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "nullable": true }, "cest": { "type": "string", "nullable": true }, "ncm": { "type": "string", "nullable": true }, "sujeitoSt": { "type": "boolean" }, "mvaOriginal": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "aliquotaInterna": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "fcpAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "reducaoBcSt": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "aliquotaInterestadual": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "difalBaseDupla": { "type": "boolean", "nullable": true }, "baseLegal": { "type": "string", "maxLength": 200, "nullable": true }, "vigenciaInicio": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "nullable": true }, "vigenciaFim": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "nullable": true } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeRegraIcmsResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`) ou regra incoerente (`regra_icms.invalida`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Regra duplicada (`regra_icms.duplicada`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "`produtoId` de outro cliente (`regra_icms.produto_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Alterar regra de ICMS por UF", "tags": [ "NfeFiscal", "produtos" ], "x-required-scopes": [ "cadastros:write" ] }, "delete": { "operationId": "NfeFiscalController_remover", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "regraId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Regra excluída (sem corpo)." }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Excluir regra de ICMS por UF", "tags": [ "NfeFiscal", "produtos" ], "x-required-scopes": [ "cadastros:write" ], "description": "**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`." } }, "/v1/clientes/{id}/nfe-ibpt": { "get": { "description": "Versão, chave, fonte, vigência, quantidade de linhas e se está vencida. Sem tabela → 404 `nfe_ibpt.nao_importada`.\n\n**Escopo exigido:** `fiscal:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeFiscalController_obterIbpt", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IbptResumoResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta\n\nTabela ainda não importada (`nfe_ibpt.nao_importada`) ou cliente de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Resumo da tabela IBPT de produtos (NCM) do cliente", "tags": [ "NfeFiscal", "nfe" ], "x-required-scopes": [ "fiscal:read" ] }, "delete": { "description": "Apaga só as linhas de NCM. Sem tabela → 404 `nfe_ibpt.nao_importada`.\n\n**Escopo exigido:** `fiscal:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeFiscalController_removerIbpt", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Tabela apagada (sem corpo)." }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Apagar a tabela IBPT de produtos (NCM) do cliente", "tags": [ "NfeFiscal", "nfe" ], "x-required-scopes": [ "fiscal:write" ] } }, "/v1/clientes/{id}/nfe-ibpt/importar": { "post": { "description": "Alternativa manual à importação automática com o token do cliente. Formato oficial do IBPT: `codigo;ex;tipo;descricao;nacionalfederal;importadosfederal;estadual;municipal;vigenciainicio;vigenciafim;chave;versao;fonte` (decimais com ponto, datas DD/MM/AAAA). Entram só as linhas de NCM (tipo 0, sem exceção); as demais contam em `ignoradas`. A UF é a do cliente (`uf` opcional; se diferir → 422 `nfe_ibpt.uf_divergente`). Substitui as linhas de NCM do cliente numa transação; erro de formato → 422 `nfe_ibpt.csv_invalido` sem gravar nada. Corpo de até 5 MB.\n\n**Escopo exigido:** `fiscal:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "NfeFiscalController_importarIbpt", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "csv" ], "additionalProperties": false, "properties": { "csv": { "type": "string" }, "uf": { "type": "string", "example": "SP" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IbptImportadaResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "CSV inválido (`nfe_ibpt.csv_invalido`, com `erros`), UF diferente da do cliente (`nfe_ibpt.uf_divergente`) ou cliente sem UF (`nfe_ibpt.uf_ausente`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemCsvResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Importar a tabela IBPT de produtos (CSV oficial)", "tags": [ "NfeFiscal", "nfe" ], "x-required-scopes": [ "fiscal:write" ] } }, "/v1/clientes/{id}/nfe": { "post": { "description": "O corpo aceita duas formas. **Por cadastros**: `modelo`, `natOp`, o destinatário (`destinatarioId` da agenda de tomadores do cliente ou `destinatario` avulso), `itens` com `produtoId`/`produtoCodigo` + `quantidade` (+ `valorUnitario`, `desconto`, `tributacao` que sobrescreve o perfil do produto), `frete`, `transporte`, `pagamentos`, `indPres`, `infAdic`, `externalRef` — a API calcula idDest, indFinal, CFOP, ICMS (CST/CSOSN pelo CRT, ST, FCP, crédito do Simples), PIS/COFINS, IPI e os totais a partir do cadastro (caminho A: os impostos vêm do produto; nós calculamos e validamos). **Completa**: `{ modelo, documento }`, com a EntradaNFe (nomes das tags do leiaute 4.00); o emitente precisa ser o cliente do caminho. Nas duas, número, série, cNF, dhEmi, tpAmb, IE/CRT do emitente e o responsável técnico vêm do banco/plataforma. A forma **por cadastros** exige, além de `nfe:write`, o escopo `cadastros:read` (ou `empresas:read`), porque lê produtos e tomadores: sem ele, `403 insufficient_scope`. A API valida tudo antes de gravar (422 `nfe.validacao` com a lista de `problemas` e a regra do Anexo I de cada um), reserva o número e a franquia na mesma transação (NF-e e NFC-e contam na franquia junto com as NFS-e; 402 `plano.limite`) e enfileira o envio. A rejeição da SEFAZ não consome o número: corrija e use `POST …/nfe/{nfeId}/reenviar`.\n\n**Escopo exigido:** `nfe:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfeController_emitir", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "UUID do cliente emitente (da conta do token)", "schema": { "type": "string" } }, { "name": "X-Mode", "in": "header", "description": "`sync` (padrão) espera a autorização da SEFAZ até o prazo (como a NFS-e) e responde 201 com o resultado; `async` responde 202 \"processando\" na hora.", "required": false, "schema": { "type": "string", "enum": [ "sync", "async" ], "default": "sync" } }, { "name": "Idempotency-Key", "in": "header", "description": "Recomendado (UUID v4, até 120 caracteres): repetir o pedido com a mesma chave devolve a MESMA nota (nada é reservado de novo); a mesma chave com outro corpo → 409 `idempotency.conflict`.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "examples": { "porCadastros": { "summary": "NF-e por cadastros", "value": { "modelo": 55, "natOp": "Venda de mercadoria", "destinatarioId": "00000000-0000-4000-8000-000000000001", "itens": [ { "produtoCodigo": "CAM-001", "quantidade": "2", "valorUnitario": "10.50" } ], "pagamentos": [ { "tPag": "01", "valor": "21.00" } ], "externalRef": "PEDIDO-123" } }, "nfce": { "summary": "NFC-e sem destinatário", "value": { "modelo": 65, "natOp": "Venda ao consumidor", "itens": [ { "produtoCodigo": "CAM-001", "quantidade": "1" } ], "pagamentos": [ { "tPag": "17", "valor": "10.50" } ] } }, "completa": { "summary": "Forma completa (EntradaNFe)", "value": { "modelo": 55, "documento": { "ide": { "natOp": "VENDA" }, "emit": { "CNPJ": "11222333000181" }, "det": [], "transp": { "modFrete": "9" }, "pag": { "detPag": [] } } } } } } } }, "responses": { "201": { "description": "Nota criada e com resultado final da SEFAZ (`X-Mode: sync`): `autorizada`, `rejeitada` ou `denegada`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeDetalheResponse" } } } }, "202": { "description": "Aceita, em processamento (`X-Mode: async`, ou `sync` que passou do prazo) — acompanhe por `GET …/nfe/{id}` ou pelos webhooks `nfe.emitida.*`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeDetalheResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`, com `issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "402": { "description": "Franquia do plano atingida (`plano.limite`, NF-e e NFC-e contam junto com as NFS-e), teste encerrado ou conta suspensa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemLimitePlanoResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Mesma `Idempotency-Key` com outro corpo (`idempotency.conflict`) ou em andamento; reenvio fora de `rejeitada` (`nfe.status_invalido`), número já usado (`nfe.numero_ja_usado`) ou inutilizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Regras locais violadas (`nfe.validacao`, com `problemas` — Anexo I, NT e cadastro), produto inativo (`produto.inativo`), configuração ausente (`nfe_emissao.sem_configuracao`), NFC-e v2 sem CSC (`nfe_emissao.sem_csc`) ou cliente sem certificado A1 vigente (`nfe_emissao.sem_certificado`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemValidacaoNfeResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Emitir NF-e ou NFC-e", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:write" ] }, "get": { "description": "Mais recentes primeiro, paginadas por cursor: o corpo é um array e a próxima página vem no cabeçalho `X-Next-Cursor` (ordem estável: criação + id).\n\n**Escopo exigido:** `nfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfeController_listar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Chave de acesso (44), número da nota, CPF/CNPJ ou parte do nome do destinatário (2–100 caracteres)", "schema": {} }, { "name": "destinatario", "required": false, "in": "query", "description": "CPF/CNPJ do destinatário (com ou sem máscara)", "schema": {} }, { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "rascunho", "processando", "contingencia_pendente", "autorizada", "denegada", "rejeitada", "cancelada" ], "type": "string" } }, { "name": "modelo", "required": false, "in": "query", "schema": { "enum": [ "55", "65" ], "type": "string" } }, { "name": "ate", "required": false, "in": "query", "description": "AAAA-MM-DD (inclusiva, horário de Brasília)", "schema": {} }, { "name": "de", "required": false, "in": "query", "description": "AAAA-MM-DD (inclusiva, horário de Brasília) — data da emissão (criação)", "schema": {} }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Página (array); a próxima página vem no cabeçalho `X-Next-Cursor`", "headers": { "X-Next-Cursor": { "description": "Cursor da próxima página (ausente na última).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NfeItemResponse" } } } } }, "400": { "description": "Filtro inválido (`query.invalida`, `cursor.invalido`, `limit.invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Listar NF-e/NFC-e emitidas do cliente", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:read" ] } }, "/v1/clientes/{id}/nfe/validar": { "post": { "description": "Mesmo corpo da emissão. Resolve os cadastros, monta e roda as validações locais (Anexo I, NT 2025.002, XSD PL_010f) com número fictício: não grava, não numera, não assina, não envia e não conta na franquia. Devolve `{ valido, problemas, valorTotal, xml }`.\n\n**Escopo exigido:** `nfe:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfeController_validar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Resultado da validação: não grava, não numera, não assina, não envia e não conta na franquia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidacaoNfeResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Configuração de NF-e do cliente ausente (`nfe_emissao.sem_configuracao`) ou produto inativo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Validar NF-e/NFC-e sem emitir", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:write" ] } }, "/v1/clientes/{id}/nfe/{chave}": { "get": { "description": "Dados da nota, retorno da SEFAZ, eventos (cancelamento, CC-e), o corpo enviado e as ações disponíveis.\n\n**Escopo exigido:** `nfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfeController_detalhe", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "chave", "required": true, "in": "path", "description": "Chave de acesso (44) — ou o id da nota, enquanto ela não tem chave (ex.: rejeição local)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeDetalheResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Detalhe de uma NF-e/NFC-e emitida", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:read" ] } }, "/v1/clientes/{id}/nfe/{chave}/xml": { "get": { "description": "Só depois da autorização (ou denegação); antes → 409 `nfe_emissao.arquivo_indisponivel`. Com `redirecionar=true` responde 302.\n\n**Escopo exigido:** `nfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfeController_xml", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "chave", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "redirecionar", "required": false, "in": "query", "schema": { "enum": [ "true", "false" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeArquivoResponse" } } } }, "302": { "description": "Com `redirecionar=true`: redireciona para a URL" }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Arquivo ainda não disponível (`nfe_emissao.arquivo_indisponivel`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "XML (nfeProc) da NF-e/NFC-e — URL pré-assinada de 300 s", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:read" ] } }, "/v1/clientes/{id}/nfe/{chave}/pdf": { "get": { "description": "Gerado logo depois da autorização; antes → 409 `nfe_emissao.arquivo_indisponivel`.\n\n**Escopo exigido:** `nfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfeController_pdf", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "chave", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "redirecionar", "required": false, "in": "query", "schema": { "enum": [ "true", "false" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeArquivoResponse" } } } }, "302": { "description": "Com `redirecionar=true`: redireciona para a URL" }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Arquivo ainda não disponível (`nfe_emissao.arquivo_indisponivel`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "DANFE (A4 na NF-e, 80 mm na NFC-e) — URL pré-assinada de 300 s", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:read" ] } }, "/v1/clientes/{id}/nfe/{nfeId}/reenviar": { "post": { "description": "Só nota `rejeitada`. Corpo: o pedido corrigido (mesmas duas formas da emissão, mesmo modelo) ou `{}` para reenviar a mesma entrada. Mantém modelo, série e número (a rejeição não consome o número); reserva a franquia de novo. Recusa: 539 da SEFAZ (`nfe.numero_ja_usado` — o número já está autorizado com outra chave) e número inutilizado.\n\n**Escopo exigido:** `nfe:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfeController_reenviar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "nfeId", "required": true, "in": "path", "description": "Id da nota (a rejeitada pode não ter chave)", "schema": { "type": "string" } }, { "name": "X-Mode", "in": "header", "description": "`sync` (padrão) espera a autorização da SEFAZ até o prazo (como a NFS-e) e responde 201 com o resultado; `async` responde 202 \"processando\" na hora.", "required": false, "schema": { "type": "string", "enum": [ "sync", "async" ], "default": "sync" } }, { "name": "Idempotency-Key", "in": "header", "description": "Recomendado (UUID v4, até 120 caracteres): repetir o pedido com a mesma chave devolve a MESMA nota (nada é reservado de novo); a mesma chave com outro corpo → 409 `idempotency.conflict`.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Nota criada e com resultado final da SEFAZ (`X-Mode: sync`): `autorizada`, `rejeitada` ou `denegada`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeDetalheResponse" } } } }, "202": { "description": "Aceita, em processamento (`X-Mode: async`, ou `sync` que passou do prazo) — acompanhe por `GET …/nfe/{id}` ou pelos webhooks `nfe.emitida.*`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeDetalheResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`, com `issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "402": { "description": "Franquia do plano atingida (`plano.limite`, NF-e e NFC-e contam junto com as NFS-e), teste encerrado ou conta suspensa", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemLimitePlanoResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Mesma `Idempotency-Key` com outro corpo (`idempotency.conflict`) ou em andamento; reenvio fora de `rejeitada` (`nfe.status_invalido`), número já usado (`nfe.numero_ja_usado`) ou inutilizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Regras locais violadas (`nfe.validacao`, com `problemas` — Anexo I, NT e cadastro), produto inativo (`produto.inativo`), configuração ausente (`nfe_emissao.sem_configuracao`), NFC-e v2 sem CSC (`nfe_emissao.sem_csc`) ou cliente sem certificado A1 vigente (`nfe_emissao.sem_certificado`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemValidacaoNfeResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Reenviar NF-e/NFC-e rejeitada com o mesmo número", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:write" ] } }, "/v1/clientes/{id}/nfe/{chave}/cancelar": { "post": { "description": "Justificativa de 15 a 255 caracteres. Prazo da SEFAZ, contado da autorização: NF-e 24 horas; NFC-e 30 minutos, que a UF pode reduzir (Ajuste SINIEF 19/16, cláusula décima quinta). Fora dele a SEFAZ responde 501, salvo a UF aceitar o cancelamento extemporâneo, cStat 151/155). O resultado chega pelo webhook `nfe.emitida.cancelled` e no detalhe da nota.\n\n**Escopo exigido:** `nfe:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfeController_cancelar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "chave", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Recomendado (UUID v4, até 120 caracteres): repetir o pedido com a mesma chave devolve a MESMA nota (nada é reservado de novo); a mesma chave com outro corpo → 409 `idempotency.conflict`.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "justificativa" ], "additionalProperties": false, "properties": { "justificativa": { "type": "string", "minLength": 15, "maxLength": 255 } } } } } }, "responses": { "202": { "description": "Pedido registrado (`pendente`) e enfileirado; o resultado chega pelos webhooks e no detalhe da nota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventoNfeResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Pedido igual ainda em andamento (`nfe.evento_duplicado`) ou mesma `Idempotency-Key` com outro corpo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Evento não permitido (`nfe.evento_invalido`): nota não autorizada, CC-e na NFC-e, limite de 20 CC-e", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cancelar NF-e/NFC-e autorizada (evento 110111)", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:write" ] } }, "/v1/clientes/{id}/nfe/{chave}/carta-correcao": { "post": { "description": "Correção de 15 a 1.000 caracteres; até 20 por nota (cada nova substitui a anterior). Não corrige valores, impostos, dados cadastrais que mudem o remetente/destinatário nem a data de emissão/saída (Ajuste SINIEF 01/07). NFC-e → 422 `nfe.evento_invalido`. Resultado: webhook `nfe.emitida.corrected`.\n\n**Escopo exigido:** `nfe:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfeController_cartaCorrecao", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "chave", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Recomendado (UUID v4, até 120 caracteres): repetir o pedido com a mesma chave devolve a MESMA nota (nada é reservado de novo); a mesma chave com outro corpo → 409 `idempotency.conflict`.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "correcao" ], "additionalProperties": false, "properties": { "correcao": { "type": "string", "minLength": 15, "maxLength": 1000 } } } } } }, "responses": { "202": { "description": "Pedido registrado (`pendente`) e enfileirado; o resultado chega pelos webhooks e no detalhe da nota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventoNfeResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Pedido igual ainda em andamento (`nfe.evento_duplicado`) ou mesma `Idempotency-Key` com outro corpo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Evento não permitido (`nfe.evento_invalido`): nota não autorizada, CC-e na NFC-e, limite de 20 CC-e", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Carta de Correção Eletrônica — CC-e (evento 110110, só NF-e modelo 55)", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:write" ] } }, "/v1/clientes/{id}/nfe-inutilizacoes": { "post": { "description": "Até 10.000 números por pedido, sem nota emitida (não rejeitada) na faixa. A emissão pula números inutilizados. Resultado (cStat 102): webhook `nfe.inutilizacao.registered`.\n\n**Escopo exigido:** `nfe:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfeController_inutilizar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Recomendado (UUID v4, até 120 caracteres): repetir o pedido com a mesma chave devolve a MESMA nota (nada é reservado de novo); a mesma chave com outro corpo → 409 `idempotency.conflict`.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "modelo", "serie", "numeroInicial", "numeroFinal", "justificativa" ], "properties": { "modelo": { "type": "integer", "enum": [ 55, 65 ] }, "serie": { "type": "integer", "minimum": 0, "maximum": 969 }, "numeroInicial": { "type": "integer", "minimum": 1 }, "numeroFinal": { "type": "integer", "minimum": 1 }, "justificativa": { "type": "string", "minLength": 15, "maxLength": 255 } } } } } }, "responses": { "202": { "description": "Pedido registrado (`pendente`) e enfileirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InutilizacaoNfeResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Faixa com nota emitida (não rejeitada), sobreposta a outro pedido ou maior que 10.000 números (`nfe.inutilizacao_invalida`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Inutilizar faixa de numeração de NF-e/NFC-e", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:write" ] }, "get": { "description": "Mais recentes primeiro, por cursor (`X-Next-Cursor`).\n\n**Escopo exigido:** `nfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfeController_inutilizacoes", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "serie", "required": false, "in": "query", "schema": {} }, { "name": "modelo", "required": false, "in": "query", "schema": { "enum": [ "55", "65" ], "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Cursor da próxima página (ausente na última).", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InutilizacaoNfeResponse" } } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Listar inutilizações de numeração do cliente", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:read" ] } }, "/v1/clientes/{id}/nfe-contingencia": { "get": { "description": "Modo da NF-e (SVC-AN, SVC-RS ou EPEC) e da NFC-e (off-line), desde quando, justificativa (o xJust das notas), se a entrada foi automática (pelo status do serviço da SEFAZ) e a preferência; notas em contingência ainda não transmitidas (quantidade, vencidas e o próximo prazo) e o último status do autorizador da UF (e da SVC).\n\n**Escopo exigido:** `nfe:read`; sem ele, `403 insufficient_scope`.", "operationId": "NfeContingenciaController_obter", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "UUID do cliente emitente", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeContingenciaResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Situação da contingência do cliente", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:read" ] }, "put": { "description": "`{ modelo: 55, ativa: true, modo: \"SVC\" | \"SVC-AN\" | \"SVC-RS\" | \"EPEC\", justificativa }` coloca a NF-e em contingência: as próximas notas saem com tpEmis 6/7 (enviadas à SVC da UF) ou 4 (EPEC registrado no Ambiente Nacional e a nota transmitida depois). `{ modelo: 65, ativa: true, justificativa }` liga a NFC-e off-line (tpEmis 9, transmitida até o fim do 1º dia útil seguinte). `ativa: false` sai. A justificativa (15–256) vai no xJust de cada nota. A SVC precisa ser a da UF; EPEC é vedado em PR e PB (NT 2014.001). `{ modelo: 55, preferencia: \"SVC\" | \"EPEC\" }` só muda a escolha da entrada automática. A entrada automática (autorizador com 108/109 ou sem resposta) sai sozinha quando ele volta; a manual, só por aqui.\n\n**Escopo exigido:** `nfe:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfeContingenciaController_alterar", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Recomendado (UUID v4): repetir com a mesma chave e o mesmo corpo devolve a mesma resposta; corpo diferente → 409.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "modelo" ], "properties": { "modelo": { "type": "integer", "enum": [ 55, 65 ] }, "ativa": { "type": "boolean" }, "modo": { "type": "string", "enum": [ "SVC", "SVC-AN", "SVC-RS", "EPEC" ] }, "justificativa": { "type": "string", "minLength": 15, "maxLength": 256 }, "preferencia": { "type": "string", "enum": [ "SVC", "EPEC" ] } } }, "examples": { "svc": { "summary": "NF-e na SVC da UF", "value": { "modelo": 55, "ativa": true, "modo": "SVC", "justificativa": "SEFAZ autorizadora instável desde as 10h" } }, "offline": { "summary": "NFC-e off-line", "value": { "modelo": 65, "ativa": true, "justificativa": "Autorizador da NFC-e sem resposta" } }, "sair": { "summary": "Sair", "value": { "modelo": 55, "ativa": false } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeContingenciaResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Sem configuração (`nfe_emissao.sem_configuracao`), EPEC vedado na UF (`nfe_contingencia.epec_vedado`), SVC de outra UF (`nfe_contingencia.svc_invalida`) ou modo/justificativa ausentes (`nfe_contingencia.invalida`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Entrar ou sair da contingência (manual) e preferência da entrada automática", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:write" ] } }, "/v1/clientes/{id}/nfe/{chave}/transmitir": { "post": { "description": "NFC-e off-line ou NF-e com EPEC (`contingencia_pendente`): envia o MESMO XML (mesma chave) ao autorizador normal. A transmissão também acontece sozinha a cada 2 minutos quando o autorizador está em operação. Rejeição → a nota fica `rejeitada` com o `alerta` (corrigir e reenviar com o mesmo número); duplicidade (204) → o protocolo é consultado e gravado.\n\n**Escopo exigido:** `nfe:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfeContingenciaController_transmitir", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "chave", "required": true, "in": "path", "description": "Chave de acesso (44) ou id da nota em contingência", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Transmissão enfileirada: a nota volta a `processando` e o resultado chega pelos webhooks e no detalhe", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NfeDetalheResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "A nota não está em contingência pendente (`nfe.status_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Transmitir agora uma nota emitida em contingência", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:write" ] } }, "/v1/clientes/{id}/nfe/{chave}/cancelar-por-substituicao": { "post": { "description": "Quando uma NFC-e normal ficou sem retorno e a mesma venda foi emitida em contingência off-line, e depois as DUAS foram autorizadas: cancela a normal (`chave`) apontando a off-line (`chaveSubstituta`). Até 168 h da autorização; a substituta precisa estar autorizada, ser off-line (tpEmis 9), do mesmo emitente, com o mesmo valor, destinatário e itens e emitida em até 2 h da cancelada (NT 2018.004). Justificativa de 15 a 255 caracteres.\n\n**Escopo exigido:** `nfe:write`; sem ele, `403 insufficient_scope`.", "operationId": "NfeContingenciaController_cancelarPorSubstituicao", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "chave", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Recomendado (UUID v4): repetir com a mesma chave e o mesmo corpo devolve a mesma resposta; corpo diferente → 409.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "chaveSubstituta", "justificativa" ], "additionalProperties": false, "properties": { "chaveSubstituta": { "type": "string", "minLength": 44, "maxLength": 44 }, "justificativa": { "type": "string", "minLength": 15, "maxLength": 255 } } } } } }, "responses": { "202": { "description": "Pedido registrado (`pendente`) e enfileirado; o resultado chega pelo webhook `nfe.emitida.cancelled`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventoNfeResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Conta sem a emissão de NF-e/NFC-e liberada (`nfe_emissao.nao_liberada`), sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, nota (`nfe_emissao.nao_encontrada`), produto (`produto.nao_encontrado`) ou regra de ICMS (`regra_icms.nao_encontrada`) não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Pedido igual ainda em andamento (`nfe.evento_duplicado`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Par inválido (`nfe.substituicao_invalida`, com `problemas` e o cStat que a SEFAZ devolveria: 920/921 tipo de emissão, 911–913 substituta, 914 > 2 h, 915 valor, 917 destinatário, 918/919 itens, 501 prazo de 168 h)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemSubstituicaoResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cancelar NFC-e por substituição (evento 110112)", "tags": [ "nfe" ], "x-required-scopes": [ "nfe:write" ] } }, "/v1/clientes/{clienteId}/tomadores": { "get": { "description": "Agenda de tomadores em ordem de nome, paginada por cursor (keyset): o corpo é um array e a próxima página vem no cabeçalho `X-Next-Cursor`.\n\n**Escopo exigido:** `cadastros:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`.", "operationId": "CadastrosController_listarTomadores", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco da página seguinte (cabeçalho `X-Next-Cursor` da resposta anterior).", "schema": {} }, { "name": "limit", "required": false, "in": "query", "description": "Itens por página: 1 a 200 (padrão 50).", "schema": {} }, { "name": "ativo", "required": false, "in": "query", "description": "`true`/`false`; ausente = só ativos.", "schema": {} }, { "name": "atualizadoDesde", "required": false, "in": "query", "description": "Só os alterados desde este instante (ISO-8601) — sincronização incremental.", "schema": {} }, { "name": "comRetencao", "required": false, "in": "query", "description": "`true` = só tomadores com exigência de retenção, ISS retido ou regra serviço×tomador", "schema": {} }, { "name": "codigo", "required": false, "in": "query", "description": "Código do integrador (exato)", "schema": {} }, { "name": "documento", "required": false, "in": "query", "description": "CPF/CNPJ exato", "schema": {} }, { "name": "q", "required": false, "in": "query", "description": "Nome (contém) ou início do CPF/CNPJ", "schema": {} } ], "responses": { "200": { "description": "Página de tomadores (cada item traz `qtdRegras`: regras serviço×tomador do tomador); a próxima página vem em `X-Next-Cursor`", "headers": { "X-Next-Cursor": { "description": "Cursor da próxima página (ausente na última).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TomadorResponse" } } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Listar tomadores do cliente", "tags": [ "Cadastros", "tomadores" ], "x-required-scopes": [ "cadastros:read" ] }, "post": { "description": "CPF, CNPJ, exterior ou não informado — mesmas regras do tomador da DPS (todo tomador cadastrado é emitível). Retenções do tomador: `retemIss`, `retemIssMunicipioIbge`, `retencaoFederal`. Exigência de retenção para todos os serviços do tomador (só CNPJ; nulo/false = não exige): `exigeIrrfAliquota`, `exigeCsrf`, `exigeInssAliquota` — vence o padrão do serviço e perde para a regra serviço×tomador.\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "CadastrosController_criarTomador", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Recomendado (UUID v4): reenvio com a mesma chave e o mesmo corpo devolve a mesma resposta; corpo diferente → 409.", "required": false, "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TomadorResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`) ou exigência de retenção em tomador que não é CNPJ (`tomador.exigencia_so_cnpj`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Documento ou código já usado por outro tomador (`tomador.documento_duplicado`, `tomador.codigo_duplicado`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cadastrar tomador", "tags": [ "Cadastros", "tomadores" ], "x-required-scopes": [ "cadastros:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TomadorDps" }, { "type": "object", "properties": { "observacoes": { "type": "string", "maxLength": 1000 }, "ativo": { "type": "boolean" }, "codigo": { "type": "string", "minLength": 1, "maxLength": 60, "nullable": true }, "retemIss": { "type": "boolean" }, "retemIssMunicipioIbge": { "type": "integer", "minimum": 1100000, "maximum": 5399999, "nullable": true }, "retencaoFederal": { "type": "string", "enum": [ "nao_retem", "pj_comum", "pj_simples", "orgao_federal", "orgao_outros" ] }, "exigeIrrfAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "exigeCsrf": { "type": "boolean" }, "exigeInssAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true } } } ] } } } } } }, "/v1/clientes/{clienteId}/tomadores/upsert": { "put": { "description": "Upsert pelo `documento` (CPF/CNPJ) no CORPO — nunca na URL — ou, sem documento (exterior/não informado), pelo `codigo` do integrador. 201 criado / 200 atualizado; tipo e documento não mudam (409 `tomador.tipo_divergente`). Idempotente por natureza.\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "CadastrosController_upsertTomador", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TomadorDps" }, { "type": "object", "properties": { "observacoes": { "type": "string", "maxLength": 1000 }, "ativo": { "type": "boolean" }, "codigo": { "type": "string", "minLength": 1, "maxLength": 60, "nullable": true }, "retemIss": { "type": "boolean" }, "retemIssMunicipioIbge": { "type": "integer", "minimum": 1100000, "maximum": 5399999, "nullable": true }, "retencaoFederal": { "type": "string", "enum": [ "nao_retem", "pj_comum", "pj_simples", "orgao_federal", "orgao_outros" ] }, "exigeIrrfAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "exigeCsrf": { "type": "boolean" }, "exigeInssAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true } } } ] }, "examples": { "cnpj": { "value": { "tipoDoc": "CNPJ", "documento": "11222333000181", "nome": "Tomadora LTDA", "codigo": "CLI-42", "retencaoFederal": "pj_comum", "endereco": { "cep": "01310100", "logradouro": "Av Paulista", "numero": "1000", "bairro": "Bela Vista", "municipioIbge": 3550308, "uf": "SP", "paisIso2": "BR" } } } } } } }, "responses": { "200": { "description": "Atualizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TomadorResponse" } } } }, "201": { "description": "Criado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TomadorResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`), sem documento nem código (`tomador.chave_upsert`) ou exigência de retenção em tomador que não é CNPJ (`tomador.exigencia_so_cnpj`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Código já usado por outro tomador (`tomador.codigo_duplicado`) ou tipo de documento divergente (`tomador.tipo_divergente`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Criar ou atualizar tomador pelo documento (ou código)", "tags": [ "Cadastros", "tomadores" ], "x-required-scopes": [ "cadastros:write" ] } }, "/v1/clientes/{clienteId}/tomadores/{id}": { "get": { "operationId": "CadastrosController_obterTomador", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TomadorResponse" } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Tomador (`tomador.nao_encontrado`) ou cliente não encontrado — inclusive de outro cliente ou conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Consultar tomador", "tags": [ "Cadastros", "tomadores" ], "x-required-scopes": [ "cadastros:read" ], "description": "**Escopo exigido:** `cadastros:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`." }, "patch": { "description": "Tipo e documento não mudam; campo desconhecido → 400.\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "CadastrosController_atualizarTomador", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TomadorResponse" } } } }, "400": { "description": "Campo desconhecido ou inválido (`validation_error`) ou exigência de retenção em tomador que não é CNPJ (`tomador.exigencia_so_cnpj`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Tomador (`tomador.nao_encontrado`) ou cliente não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Código já usado por outro tomador (`tomador.codigo_duplicado`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Alterar tomador", "tags": [ "Cadastros", "tomadores" ], "x-required-scopes": [ "cadastros:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "minLength": 1, "maxLength": 200 }, "inscricaoMunicipal": { "type": "string", "maxLength": 20 }, "email": { "type": "string", "format": "email" }, "telefone": { "type": "string", "maxLength": 20 }, "endereco": { "type": "object", "properties": { "cep": { "type": "string", "minLength": 8, "maxLength": 8, "pattern": "^\\d{8}$" }, "logradouro": { "type": "string", "minLength": 1, "maxLength": 150 }, "numero": { "type": "string", "minLength": 1, "maxLength": 20 }, "complemento": { "type": "string", "maxLength": 80 }, "bairro": { "type": "string", "minLength": 1, "maxLength": 80 }, "municipioIbge": { "type": "integer", "minimum": 1100000, "maximum": 5399999 }, "uf": { "type": "string", "enum": [ "AC", "AL", "AP", "AM", "BA", "CE", "DF", "ES", "GO", "MA", "MT", "MS", "MG", "PA", "PB", "PR", "PE", "PI", "RJ", "RN", "RS", "RO", "RR", "SC", "SP", "SE", "TO" ] }, "paisIso2": { "type": "string", "minLength": 2, "maxLength": 2, "default": "BR" } }, "required": [ "cep", "logradouro", "numero", "bairro", "municipioIbge", "uf" ] }, "observacoes": { "type": "string", "maxLength": 1000 }, "ativo": { "type": "boolean" }, "inscricaoEstadual": { "type": "string", "maxLength": 20 }, "codigo": { "type": "string", "minLength": 1, "maxLength": 60, "nullable": true }, "retemIss": { "type": "boolean" }, "retemIssMunicipioIbge": { "type": "integer", "minimum": 1100000, "maximum": 5399999, "nullable": true }, "retencaoFederal": { "type": "string", "enum": [ "nao_retem", "pj_comum", "pj_simples", "orgao_federal", "orgao_outros" ] }, "exigeIrrfAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "exigeCsrf": { "type": "boolean" }, "exigeInssAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true } }, "additionalProperties": false } } } } }, "delete": { "description": "Mantido para histórico e agendamentos (ativo = false).\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "CadastrosController_desativarTomador", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Desativado (sem corpo)" }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Desativar tomador", "tags": [ "Cadastros", "tomadores" ], "x-required-scopes": [ "cadastros:write" ] } }, "/v1/clientes/{clienteId}/servicos": { "get": { "description": "Catálogo em ordem de descrição, paginado por cursor (`X-Next-Cursor`), com os padrões fiscais (ISS, IBS/CBS, retenções, dedução).\n\n**Escopo exigido:** `cadastros:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`.", "operationId": "CadastrosController_listarServicos", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco da página seguinte (cabeçalho `X-Next-Cursor` da resposta anterior).", "schema": {} }, { "name": "limit", "required": false, "in": "query", "description": "Itens por página: 1 a 200 (padrão 50).", "schema": {} }, { "name": "ativo", "required": false, "in": "query", "description": "`true`/`false`; ausente = só ativos.", "schema": {} }, { "name": "atualizadoDesde", "required": false, "in": "query", "description": "Só os alterados desde este instante (ISO-8601) — sincronização incremental.", "schema": {} }, { "name": "codigo", "required": false, "in": "query", "description": "Código do integrador (exato)", "schema": {} }, { "name": "q", "required": false, "in": "query", "description": "Descrição (contém), código do integrador ou cTribNac", "schema": {} } ], "responses": { "200": { "description": "Página de serviços (cada item traz `qtdRegras`: regras serviço×tomador do serviço); a próxima página vem em `X-Next-Cursor`", "headers": { "X-Next-Cursor": { "description": "Cursor da próxima página (ausente na última).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ServicoResponse" } } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Listar serviços do cliente", "tags": [ "Cadastros", "servicos" ], "x-required-scopes": [ "cadastros:read" ] }, "post": { "description": "cTribNac da LC 116 e NBS existentes nas tabelas oficiais; padrões fiscais opcionais (seção 5.2 do motor).\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "CadastrosController_criarServico", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Recomendado (UUID v4): reenvio com a mesma chave e o mesmo corpo devolve a mesma resposta; corpo diferente → 409.", "required": false, "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicoResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`) ou dados fiscais incoerentes (`servico.fiscal_invalido`: cTribNac/NBS inexistentes, materiais do INSS sem retenção de INSS, PIS/COFINS cumulativo fora do Lucro Real…)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Código já usado por outro serviço (`servico.codigo_duplicado`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cadastrar serviço", "tags": [ "Cadastros", "servicos" ], "x-required-scopes": [ "cadastros:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "descricao": { "type": "string", "minLength": 1, "maxLength": 2000 }, "codigoTribNacional": { "type": "string" }, "codigoTribMunicipal": { "type": "string", "pattern": "^\\d{1,3}$", "nullable": true }, "codigoNbs": { "type": "string" }, "aliquotaIss": { "type": "string", "pattern": "^\\d{1,2}(\\.\\d{1,2})?$", "nullable": true }, "valorPadrao": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "nullable": true }, "issRetido": { "type": "boolean" }, "ativo": { "type": "boolean" }, "codigo": { "type": "string", "minLength": 1, "maxLength": 60, "nullable": true }, "issRetencao": { "type": "string", "enum": [ "conforme_tomador", "sempre", "nunca" ] }, "exigibilidadeIss": { "type": "string", "enum": [ "exigivel", "naoIncidencia", "isencao", "exportacao", "imunidade", "suspensaoJudicial", "suspensaoAdministrativa" ], "nullable": true }, "issDetalhe": { "type": "object", "properties": { "tipoImunidade": { "type": "string", "enum": [ "1", "2", "3", "4", "5" ] }, "processoSuspensao": { "type": "string", "pattern": "^\\d{30}$" }, "beneficioMunicipal": { "type": "object", "properties": { "numero": { "type": "string", "pattern": "^\\d{14}$" }, "tipo": { "type": "string", "enum": [ "isencao", "aliquotaDiferenciada", "reducaoBaseCalculo" ] }, "reducaoValor": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "reducaoPercentual": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "numero" ], "additionalProperties": false }, "paisResultado": { "type": "string", "minLength": 2, "maxLength": 2 } }, "additionalProperties": false, "nullable": true }, "ibscbsCst": { "type": "string", "pattern": "^\\d{3}$", "nullable": true }, "ibscbsCClassTrib": { "type": "string", "pattern": "^\\d{6}$", "nullable": true }, "ibscbsIndOp": { "type": "string", "pattern": "^\\d{6}$", "nullable": true }, "retIrrfAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "retCsrf": { "type": "boolean" }, "retPisAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "retCofinsAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "retCsllAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "retInssAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "natureza1234": { "type": "string", "nullable": true }, "deducaoPercentual": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "deducaoValor": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "pisCofinsRegime": { "type": "string", "enum": [ "empresa", "cumulativo", "nao_cumulativo" ] }, "inssMateriaisPercentual": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "inssMateriaisValor": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true } }, "required": [ "descricao", "codigoTribNacional", "codigoNbs" ] } } } } } }, "/v1/clientes/{clienteId}/servicos/upsert": { "put": { "description": "Upsert pelo `codigo` (obrigatório) no corpo: 201 criado / 200 atualizado.\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "CadastrosController_upsertServico", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "descricao": { "type": "string", "minLength": 1, "maxLength": 2000 }, "codigoTribNacional": { "type": "string" }, "codigoTribMunicipal": { "type": "string", "pattern": "^\\d{1,3}$", "nullable": true }, "codigoNbs": { "type": "string" }, "aliquotaIss": { "type": "string", "pattern": "^\\d{1,2}(\\.\\d{1,2})?$", "nullable": true }, "valorPadrao": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "nullable": true }, "issRetido": { "type": "boolean" }, "ativo": { "type": "boolean" }, "codigo": { "type": "string", "minLength": 1, "maxLength": 60 }, "issRetencao": { "type": "string", "enum": [ "conforme_tomador", "sempre", "nunca" ] }, "exigibilidadeIss": { "type": "string", "enum": [ "exigivel", "naoIncidencia", "isencao", "exportacao", "imunidade", "suspensaoJudicial", "suspensaoAdministrativa" ], "nullable": true }, "issDetalhe": { "type": "object", "properties": { "tipoImunidade": { "type": "string", "enum": [ "1", "2", "3", "4", "5" ] }, "processoSuspensao": { "type": "string", "pattern": "^\\d{30}$" }, "beneficioMunicipal": { "type": "object", "properties": { "numero": { "type": "string", "pattern": "^\\d{14}$" }, "tipo": { "type": "string", "enum": [ "isencao", "aliquotaDiferenciada", "reducaoBaseCalculo" ] }, "reducaoValor": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "reducaoPercentual": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "numero" ], "additionalProperties": false }, "paisResultado": { "type": "string", "minLength": 2, "maxLength": 2 } }, "additionalProperties": false, "nullable": true }, "ibscbsCst": { "type": "string", "pattern": "^\\d{3}$", "nullable": true }, "ibscbsCClassTrib": { "type": "string", "pattern": "^\\d{6}$", "nullable": true }, "ibscbsIndOp": { "type": "string", "pattern": "^\\d{6}$", "nullable": true }, "retIrrfAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "retCsrf": { "type": "boolean" }, "retPisAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "retCofinsAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "retCsllAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "retInssAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "natureza1234": { "type": "string", "nullable": true }, "deducaoPercentual": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "deducaoValor": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "pisCofinsRegime": { "type": "string", "enum": [ "empresa", "cumulativo", "nao_cumulativo" ] }, "inssMateriaisPercentual": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "inssMateriaisValor": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true } }, "required": [ "descricao", "codigoTribNacional", "codigoNbs", "codigo" ] }, "examples": { "licenca": { "value": { "codigo": "LIC-01", "descricao": "Licença de uso {competencia}", "codigoTribNacional": "010501", "codigoNbs": "111032900", "aliquotaIss": "5.00", "issRetencao": "conforme_tomador" } } } } } }, "responses": { "200": { "description": "Atualizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicoResponse" } } } }, "201": { "description": "Criado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicoResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`) ou dados fiscais incoerentes (`servico.fiscal_invalido`: cTribNac/NBS inexistentes, materiais do INSS sem retenção de INSS, PIS/COFINS cumulativo fora do Lucro Real…)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Código já usado por outro serviço (`servico.codigo_duplicado`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Criar ou atualizar serviço pelo código do integrador", "tags": [ "Cadastros", "servicos" ], "x-required-scopes": [ "cadastros:write" ] } }, "/v1/clientes/{clienteId}/servicos/{id}": { "get": { "operationId": "CadastrosController_obterServico", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicoResponse" } } } }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Serviço (`servico.nao_encontrado`) ou cliente não encontrado — inclusive de outro cliente ou conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Consultar serviço", "tags": [ "Cadastros", "servicos" ], "x-required-scopes": [ "cadastros:read" ], "description": "**Escopo exigido:** `cadastros:read` (`empresas:read` também atende); sem ele, `403 insufficient_scope`." }, "patch": { "description": "Campo desconhecido → 400.\n\n**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`.", "operationId": "CadastrosController_atualizarServico", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicoResponse" } } } }, "400": { "description": "Campo desconhecido ou inválido (`validation_error`) ou dados fiscais incoerentes (`servico.fiscal_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Serviço (`servico.nao_encontrado`) ou cliente não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "409": { "description": "Código já usado por outro serviço (`servico.codigo_duplicado`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Alterar serviço", "tags": [ "Cadastros", "servicos" ], "x-required-scopes": [ "cadastros:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "descricao": { "type": "string", "minLength": 1, "maxLength": 2000 }, "codigoTribNacional": { "type": "string" }, "codigoTribMunicipal": { "type": "string", "pattern": "^\\d{1,3}$", "nullable": true }, "codigoNbs": { "type": "string" }, "aliquotaIss": { "type": "string", "pattern": "^\\d{1,2}(\\.\\d{1,2})?$", "nullable": true }, "valorPadrao": { "type": "string", "pattern": "^\\d{1,13}(\\.\\d{1,2})?$", "nullable": true }, "issRetido": { "type": "boolean" }, "ativo": { "type": "boolean" }, "codigo": { "type": "string", "minLength": 1, "maxLength": 60, "nullable": true }, "issRetencao": { "type": "string", "enum": [ "conforme_tomador", "sempre", "nunca" ] }, "exigibilidadeIss": { "type": "string", "enum": [ "exigivel", "naoIncidencia", "isencao", "exportacao", "imunidade", "suspensaoJudicial", "suspensaoAdministrativa" ], "nullable": true }, "issDetalhe": { "type": "object", "properties": { "tipoImunidade": { "type": "string", "enum": [ "1", "2", "3", "4", "5" ] }, "processoSuspensao": { "type": "string", "pattern": "^\\d{30}$" }, "beneficioMunicipal": { "type": "object", "properties": { "numero": { "type": "string", "pattern": "^\\d{14}$" }, "tipo": { "type": "string", "enum": [ "isencao", "aliquotaDiferenciada", "reducaoBaseCalculo" ] }, "reducaoValor": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "reducaoPercentual": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "numero" ], "additionalProperties": false }, "paisResultado": { "type": "string", "minLength": 2, "maxLength": 2 } }, "additionalProperties": false, "nullable": true }, "ibscbsCst": { "type": "string", "pattern": "^\\d{3}$", "nullable": true }, "ibscbsCClassTrib": { "type": "string", "pattern": "^\\d{6}$", "nullable": true }, "ibscbsIndOp": { "type": "string", "pattern": "^\\d{6}$", "nullable": true }, "retIrrfAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "retCsrf": { "type": "boolean" }, "retPisAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "retCofinsAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "retCsllAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "retInssAliquota": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "natureza1234": { "type": "string", "nullable": true }, "deducaoPercentual": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "deducaoValor": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "pisCofinsRegime": { "type": "string", "enum": [ "empresa", "cumulativo", "nao_cumulativo" ] }, "inssMateriaisPercentual": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "inssMateriaisValor": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true } }, "additionalProperties": false } } } } }, "delete": { "operationId": "CadastrosController_desativarServico", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Desativado (sem corpo)" }, "400": { "description": "Corpo, parâmetro ou filtro inválido (`validation_error`, `query.invalida`, `cursor.invalido`, `parametro.uuid_invalido`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente ou registro não encontrado — inclusive de outra conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Desativar serviço", "tags": [ "Cadastros", "servicos" ], "x-required-scopes": [ "cadastros:write" ], "description": "**Escopo exigido:** `cadastros:write` (`empresas:write` também atende); sem ele, `403 insufficient_scope`." } }, "/v1/clientes/{clienteId}/nfse/validar": { "post": { "description": "Mesmas regras da emissão (schema, coerência, cliente, XSD oficial). Não reserva número, não assina e não envia.\n\n**Escopo exigido:** `nfse:write`; sem ele, `403 insufficient_scope`.", "operationId": "FerramentasController_validarDoCliente", "parameters": [ { "name": "clienteId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resultado da validação (válida ou não). Não reserva número, não assina, não envia e não conta na franquia do plano.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidacaoDpsResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`, com `issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`), cliente fora da restrição do token ou conta suspensa (`tenant.inativo`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, serviço ou tomador não encontrado (inclusive de outra conta)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Valida uma DPS sem emitir (pré-visualização do XML)", "tags": [ "nfse" ], "x-required-scopes": [ "nfse:write" ] } }, "/v1/nfse/validar": { "post": { "deprecated": true, "description": "Igual a `POST /v1/clientes/{clienteId}/nfse/validar`, com o cliente no cabeçalho `X-Cliente-Id`.\n\n**Escopo exigido:** `nfse:write`; sem ele, `403 insufficient_scope`.", "operationId": "FerramentasController_validar", "parameters": [ { "name": "X-Cliente-Id", "in": "header", "description": "DEPRECIADO (Sunset 2027-06-30): use `POST /v1/clientes/{clienteId}/nfse/validar`.", "required": true, "deprecated": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resultado da validação (válida ou não). Não reserva número, não assina, não envia e não conta na franquia do plano.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidacaoDpsResponse" } } } }, "400": { "description": "Corpo inválido (`validation_error`, com `issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`), cliente fora da restrição do token ou conta suspensa (`tenant.inativo`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "404": { "description": "Cliente, serviço ou tomador não encontrado (inclusive de outra conta)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Valida uma DPS sem emitir — forma legada (cliente no cabeçalho)", "tags": [ "nfse" ], "x-required-scopes": [ "nfse:write" ] } }, "/v1/nfse-lote/zip": { "get": { "description": "Período em dias de Brasília (America/Sao_Paulo) pela data de emissão. Acima de 2.000 notas responde 422 `lote.limite_excedido` com `total` e `limite` (nada é cortado): divida o período.\n\n**Escopo exigido:** `nfse:read`; sem ele, `403 insufficient_scope`.", "operationId": "FerramentasController_zip", "parameters": [ { "name": "dataDe", "required": true, "in": "query", "description": "AAAA-MM-DD (inclusiva, 00:00 de Brasília)", "schema": { "type": "string" } }, { "name": "dataAte", "required": true, "in": "query", "description": "AAAA-MM-DD (exclusiva, 00:00 de Brasília)", "schema": { "type": "string" } }, { "name": "clienteId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "arquivos", "required": false, "in": "query", "schema": { "enum": [ "xml", "pdf", "ambos" ], "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "CSV: autorizada,cancelada,substituida", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Arquivo ZIP (`application/zip`) com `xml/` e `pdf/`; notas sem arquivo vão listadas em `LEIA-ME_arquivos_ausentes.txt`", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Período ausente ou inválido (`lote.periodo`) ou nenhuma nota no período (`lote.vazio`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "401": { "description": "Token ausente, vencido, revogado ou de IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "403": { "description": "Sem o escopo exigido (`insufficient_scope`) ou cliente fora da restrição do token (`cliente.sem_acesso`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "422": { "description": "Mais de 2.000 notas no período (`lote.limite_excedido`, com `total` e `limite`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } }, "429": { "description": "Limite de requisições do token excedido (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Download em lote (ZIP) de XML e/ou PDF das notas do período (máx. 2.000)", "tags": [ "nfse" ], "x-required-scopes": [ "nfse:read" ] } }, "/health": { "get": { "operationId": "HealthController_liveness", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaudeResponse" } } } } }, "summary": "Liveness — processo respondendo (não consulta dependências)", "tags": [ "health" ] } }, "/v1/health/ready": { "get": { "operationId": "HealthController_readiness", "parameters": [], "responses": { "200": { "description": "Postgres e Redis no ar (a SEFIN é informativa: `checks[].ok` falso nela não derruba a API)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProntidaoResponse" } } } }, "503": { "description": "Postgres ou Redis fora, ou processo desligando (`status: indisponivel`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProntidaoResponse" } } } } }, "summary": "Readiness — 200 com Postgres e Redis no ar; 503 caso contrário", "tags": [ "health" ] } }, "/v1/reference/municipios": { "get": { "description": "Dataset oficial (ANEXO A — gov.br/nfse) com 5.570 municípios brasileiros.", "operationId": "ReferenceController_municipios", "parameters": [ { "name": "uf", "required": false, "in": "query", "description": "Filtra por UF (ex: SP)", "schema": { "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Busca parcial por nome do município", "schema": { "type": "string" } }, { "name": "codigo", "required": false, "in": "query", "description": "Código IBGE exato (7 dígitos)", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Próxima página; ausente na última.", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "summary": "Listar municípios (IBGE)", "tags": [ "reference" ] } }, "/v1/reference/paises": { "get": { "description": "Dataset oficial — 250 entradas.", "operationId": "ReferenceController_paises", "parameters": [ { "name": "q", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "iso2", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Próxima página; ausente na última.", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "summary": "Listar países (ISO-2)", "tags": [ "reference" ] } }, "/v1/reference/nbs": { "get": { "description": "Dataset oficial NBS v2.0 (ANEXO B do gov.br/nfse). Total: 1.208 códigos.", "operationId": "ReferenceController_nbs", "parameters": [ { "name": "q", "required": false, "in": "query", "description": "Busca por código ou descrição", "schema": { "type": "string" } }, { "name": "codigo", "required": false, "in": "query", "description": "Código NBS exato", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Próxima página; ausente na última.", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "summary": "Listar NBS — Nomenclatura Brasileira de Serviços", "tags": [ "reference" ] } }, "/v1/reference/servicos-lc116": { "get": { "description": "Dataset oficial — 580 itens (ANEXO B / LISTA.SERV.NAC.).", "operationId": "ReferenceController_servicosLc", "parameters": [ { "name": "q", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "codigo", "required": false, "in": "query", "description": "Formato \"01.01.00\"", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Próxima página; ausente na última.", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "summary": "Lista de serviços da LC 116 (códigos tributação nacional)", "tags": [ "reference" ] } }, "/v1/reference/rejeicoes/{codigo}": { "get": { "description": "Mensagem e regra oficiais (Anexos I/II) e, para os códigos mais comuns, como resolver.", "operationId": "ReferenceController_rejeicao", "parameters": [ { "name": "codigo", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Explicação de um código de rejeição da SEFIN", "tags": [ "reference" ] } }, "/v1/reference/rejeicoes": { "get": { "operationId": "ReferenceController_rejeicoes", "parameters": [ { "name": "q", "required": false, "in": "query", "description": "Busca por código ou texto da mensagem", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Próxima página; ausente na última.", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "summary": "Catálogo oficial de códigos de rejeição (Anexos I e II)", "tags": [ "reference" ] } }, "/v1/reference/indicadores-operacao": { "get": { "operationId": "ReferenceController_indicadoresOperacao", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Cursor opaco recebido em X-Next-Cursor. Repita os mesmos filtros.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "headers": { "X-Next-Cursor": { "description": "Próxima página; ausente na última.", "schema": { "type": "string" } } }, "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "summary": "Indicadores de operação (cIndOp) do IBS/CBS — Anexo C vigente", "tags": [ "reference" ] } }, "/v1/reference/ibscbs/sugestao": { "get": { "description": "Correlação do Anexo VIII (item LC 116 × NBS × cIndOp × cClassTrib). O portal o declara em desenvolvimento, sem regras de negócio implementadas: use como sugestão e confirme com o contador. `indOpSugerido` é o cIndOp vigente (Anexo C) mais frequente para o serviço/NBS em operação onerosa com adquirente no país; `null` sem correlação (vale a regra residual do art. 11, X, da LC 214/2025: 100301). A emissão NÃO aplica a sugestão: o cIndOp enviado em `rtc.codigoIndicadorOperacao` é respeitado. `oficial` traz os cClassTrib do NBS pelos dados abertos da calculadora RFB/Serpro (D19), que prevalecem sobre o Anexo VIII.", "operationId": "ReferenceController_sugestaoIbsCbs", "parameters": [ { "name": "cTribNac", "required": true, "in": "query", "description": "Código de tributação nacional (ex.: 010501)", "schema": { "type": "string" } }, { "name": "nbs", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Sugestão de classificação IBS/CBS (cClassTrib/cIndOp) para um serviço", "tags": [ "reference" ] } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "API_TOKEN", "description": "Token de API (`nfse_live_…`), criado no painel, no menu **Tokens de API**, por uma pessoa da equipe." } }, "schemas": { "ProblemResponse": { "type": "object", "properties": { "type": { "type": "string", "example": "https://nf.digla.io/api/erros/validation_error" }, "title": { "type": "string", "example": "Erro de validação" }, "status": { "type": "number", "example": 422 }, "code": { "type": "string", "example": "validation_error" }, "detail": { "type": "string", "example": "Campo \"tomador.documento\" inválido" }, "instance": { "type": "string", "example": "/v1/nfse" }, "requestId": { "type": "string", "example": "1HYz7q5p2a4Tn3" } }, "required": [ "type", "title", "status", "code", "detail", "instance" ] }, "ContaDoTokenResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "plan": { "type": "string", "example": "escritorio" }, "tipo": { "type": "string", "example": "emitente" }, "exigirMfa": { "type": "boolean" }, "nfeRecebidas": { "type": "boolean", "description": "Conta com a NF-e recebida liberada." }, "nfeEmissao": { "type": "boolean", "description": "Conta com a emissão de NF-e/NFC-e liberada." } }, "required": [ "id", "slug", "name", "plan", "tipo", "exigirMfa", "nfeRecebidas", "nfeEmissao" ] }, "PrincipalResponse": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "token", "user" ] }, "id": { "type": "string", "format": "uuid" }, "scopes": { "example": [ "nfse:read", "cadastros:read" ], "type": "array", "items": { "type": "string" } }, "mfaEnabled": { "type": "boolean" }, "mfaObrigatorioPendente": { "type": "boolean" }, "mfaExigidoPelaConta": { "type": "boolean" }, "empresasIds": { "nullable": true, "description": "Clientes a que o token se restringe; nulo = todos.", "type": "array", "items": { "type": "string" } }, "tipoVinculo": { "type": "string", "nullable": true }, "contador": { "type": "boolean" }, "portalCliente": { "type": "boolean" } }, "required": [ "type", "id", "scopes", "mfaEnabled", "mfaObrigatorioPendente", "mfaExigidoPelaConta", "empresasIds", "tipoVinculo", "contador", "portalCliente" ] }, "MeResponse": { "type": "object", "properties": { "tenant": { "$ref": "#/components/schemas/ContaDoTokenResponse" }, "vinculo": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Vínculo da pessoa (nulo para token de API)." }, "vinculos": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "acessosContador": { "type": "integer" }, "principal": { "$ref": "#/components/schemas/PrincipalResponse" } }, "required": [ "tenant", "vinculo", "vinculos", "acessosContador", "principal" ] }, "EnderecoCadastroResponse": { "type": "object", "properties": { "cep": { "type": "string", "example": "01310100" }, "logradouro": { "type": "string", "example": "Av Paulista" }, "numero": { "type": "string", "example": "1000" }, "complemento": { "type": "string", "example": "Sala 10" }, "bairro": { "type": "string", "example": "Bela Vista" }, "municipioIbge": { "type": "number", "example": 3550308, "description": "Código IBGE do município (7 dígitos)." }, "uf": { "type": "string", "example": "SP" }, "paisIso2": { "type": "string", "example": "BR" } }, "required": [ "cep", "logradouro", "numero", "bairro", "municipioIbge", "uf", "paisIso2" ] }, "EmissorNacionalResumoResponse": { "type": "object", "properties": { "confirmado": { "type": "boolean" }, "confirmadoEm": { "type": "string", "nullable": true, "format": "date-time" }, "municipioIbge": { "type": "integer", "nullable": true, "example": 3550308, "description": "Município para o qual a confirmação foi dada." }, "situacao": { "type": "string", "nullable": true, "description": "Situação do município no convênio no momento da confirmação." }, "fonte": { "type": "string", "nullable": true, "enum": [ "adn", "planilha" ], "description": "Origem da consulta de adesão: ADN (consulta oficial) ou planilha oficial (reserva)." } }, "required": [ "confirmado", "confirmadoEm", "municipioIbge", "situacao", "fonte" ] }, "ClienteResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9c2a6f4b-1c7e-4d6e-9a44-a89f1a3e8c4d", "description": "O `clienteId` dos caminhos `/v1/clientes/{clienteId}/…`." }, "documento": { "type": "string", "example": "12345678000195", "description": "CNPJ (14) ou CPF (11), só dígitos." }, "tipoDocumento": { "type": "string", "enum": [ "CPF", "CNPJ" ] }, "inscricaoMunicipal": { "type": "string", "nullable": true, "example": "987654" }, "razaoSocial": { "type": "string", "example": "Empresa Exemplo LTDA" }, "nomeFantasia": { "type": "string", "nullable": true }, "regimeTributario": { "type": "string", "enum": [ "simples", "mei", "lucroPresumido", "lucroReal", "autonomo" ], "description": "Regime vigente hoje; o histórico por competência está em `…/regimes`." }, "regimeApuracaoSn": { "type": "string", "nullable": true, "enum": [ "1", "2", "3" ] }, "percentualTotTribSn": { "type": "string", "nullable": true, "example": "6.00" }, "municipioIbge": { "type": "number", "example": 3550308 }, "uf": { "type": "string", "example": "SP" }, "endereco": { "$ref": "#/components/schemas/EnderecoCadastroResponse" }, "contato": { "type": "object", "additionalProperties": true, "example": { "email": "fiscal@exemplo.com.br" } }, "ambiente": { "type": "string", "enum": [ "homolog", "prod" ] }, "emailNfseAutomatico": { "type": "boolean" }, "emailNfseCopia": { "type": "string", "nullable": true }, "serieDpsAtual": { "type": "string", "example": "1", "description": "Série da DPS (1 a 49999)." }, "proximoNumeroDps": { "type": "number", "example": 1 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "emissorNacional": { "description": "Confirmação da emissão em município que só compartilha com o ADN (`POST …/emissor-nacional/confirmar`).", "allOf": [ { "$ref": "#/components/schemas/EmissorNacionalResumoResponse" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-10-23T14:32:10.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-10-23T14:32:10.000Z" } }, "required": [ "id", "documento", "tipoDocumento", "inscricaoMunicipal", "razaoSocial", "nomeFantasia", "regimeTributario", "regimeApuracaoSn", "percentualTotTribSn", "municipioIbge", "uf", "endereco", "contato", "ambiente", "emailNfseAutomatico", "emailNfseCopia", "serieDpsAtual", "proximoNumeroDps", "status", "emissorNacional", "createdAt", "updatedAt" ] }, "AvisoMotorResponse": { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "ADN_INDISPONIVEL", "BASE_CALCULADA", "CALCULADORA_DIVERGENTE", "CALCULADORA_INDISPONIVEL", "CALCULADORA_SIMULADA", "CPRB_FORA_DA_VIGENCIA", "CSRF_ALIQUOTA_DESTAQUE", "CSRF_DISPENSADA", "CSRF_SEM_GRUPO_PISCOFINS", "EXIGENCIA_TOMADOR_CONFLITA_PF", "EXIGENCIA_TOMADOR_IGNORADA_EMITENTE", "EXIGENCIA_TOMADOR_IGNORADA_SIMPLES", "FEDERAIS_IGNORADOS", "FEDERAIS_IGNORADOS_EMITENTE", "IBPT_SEM_ALIQUOTA", "IBPT_TEXTO_NAO_COUBE", "IBPT_VENCIDA", "IBSCBS_ANTES_2026", "IBSCBS_APURADO_SEFIN", "IBSCBS_SIMPLES", "IBSCBS_SUGESTAO", "INSS_MATERIAIS_PISO", "INSS_SIMPLES", "IRRF_DISPENSADO", "ISS_ALIQUOTA_MINIMA_SN", "ISS_SUBSTITUTO_OUTRO_MUNICIPIO", "LOCAL_PRESTACAO_ASSUMIDO", "ORGAO_CODIGO_RECEITA", "ORGAO_DISPENSA", "ORGAO_SIMPLES_DECLARACAO", "PIS_COFINS_SUGERE_CUMULATIVO", "PREMISSA_SEM_CONTADOR", "REGIME_ESPECIAL_IGNORADO", "REGIME_ESPECIAL_ISS", "REGIME_ESPECIAL_SEM_BM", "REGIME_ESPECIAL_SEM_DEDUCAO", "REGIME_SEM_VIGENCIA", "REGRA_CONFLITA_TOMADOR_PF", "REGRA_IGNORADA_SIMPLES", "RETENCAO_SUGERIDA_NAO_CONFIGURADA", "SIMPLES_SEM_PERCENTUAL_TOT_TRIB", "VALOR_INFORMADO_DIFERE" ], "example": "IRRF_DISPENSADO", "description": "Código estável — decida por ele, não pelo texto." }, "mensagem": { "type": "string", "example": "IRRF de R$ 7,50 dispensado (≤ R$ 10,00). A soma mensal de pagamentos ao mesmo prestador é obrigação do tomador." }, "campo": { "type": "string", "example": "tributacao.federal.retencaoIrrf", "description": "Campo da DPS a que o aviso se refere." } }, "required": [ "codigo", "mensagem" ] }, "TotaisMotorResponse": { "type": "object", "properties": { "valorServicos": { "type": "string", "example": "1000.00" }, "descontoIncondicionado": { "type": "string", "example": "0.00" }, "baseCalculoIss": { "type": "string", "example": "1000.00" }, "aliquotaIss": { "type": "string", "example": "2.00" }, "valorIss": { "type": "string", "example": "20.00" }, "issRetido": { "type": "string", "example": "0.00", "description": "ISS retido pelo tomador." }, "retencoesFederais": { "type": "string", "example": "61.50", "description": "vRetIRRF + vRetCSLL + vRetCP (vRetCSLL = PIS+COFINS+CSLL retidos — NT 007)." }, "pisCofinsRetidos": { "type": "string", "example": "36.50", "description": "Parte de PIS/COFINS dentro do vRetCSLL (informativo)." }, "baseCalculoIbsCbs": { "type": "string", "example": "1000.00" }, "valorIbs": { "type": "string", "example": "1.00" }, "valorCbs": { "type": "string", "example": "9.00" }, "valorLiquido": { "type": "string", "example": "938.50", "description": "Valor líquido (vLiq)." }, "valorTotalNota": { "type": "string", "example": "1000.00" } }, "required": [ "valorServicos", "descontoIncondicionado", "baseCalculoIss", "aliquotaIss", "valorIss", "issRetido", "retencoesFederais", "pisCofinsRetidos", "baseCalculoIbsCbs", "valorIbs", "valorCbs", "valorLiquido", "valorTotalNota" ] }, "NfseEmitidaResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "0c3a3f2e-1f55-4c5c-9b22-7e1d5a9d2f76" }, "dpsId": { "type": "string", "example": "0c3a3f2e-1f55-4c5c-9b22-7e1d5a9d2f76" }, "chaveAcesso": { "type": "string", "example": "35503082212345678000195000000000000126101234567895", "minLength": 50, "maxLength": 50, "description": "Presente depois da autorização." }, "numero": { "type": "string", "example": "12345", "description": "Número da NFS-e; presente depois da autorização." }, "serie": { "type": "string", "example": "1" }, "status": { "type": "string", "enum": [ "autorizada", "rejeitada", "processando" ], "example": "autorizada" }, "ambiente": { "type": "string", "enum": [ "homolog", "prod" ], "example": "prod" }, "protocolo": { "type": "string", "example": "135260006543210" }, "xmlUrl": { "type": "string", "example": "https://s3.../tenants/.../nfse.xml?..." }, "pdfUrl": { "type": "string", "example": "https://s3.../tenants/.../nfse.pdf?..." }, "origens": { "type": "object", "description": "Só na forma por cadastros: para cada campo resolvido (ex.: `servicos[0].aliquotaIss`), de onde veio o valor.", "additionalProperties": { "$ref": "#/components/schemas/OrigemCampoResponse" } }, "avisos": { "description": "Só na forma por cadastros: avisos do motor (não impedem a emissão).", "type": "array", "items": { "$ref": "#/components/schemas/AvisoMotorResponse" } }, "totais": { "description": "Só na forma por cadastros: totais calculados pelo motor.", "allOf": [ { "$ref": "#/components/schemas/TotaisMotorResponse" } ] } }, "required": [ "id", "dpsId", "serie", "status", "ambiente" ] }, "RetencaoAplicadaResponse": { "type": "object", "properties": { "tipo": { "type": "string", "enum": [ "regra", "exigencia" ] }, "tributos": { "type": "array", "items": { "type": "string", "enum": [ "irrf", "csrf", "inss", "iss" ] } }, "tomadorId": { "type": "string", "format": "uuid" }, "tomadorNome": { "type": "string" }, "servicoId": { "type": "string", "nullable": true, "format": "uuid" }, "servicoDescricao": { "type": "string", "nullable": true } }, "required": [ "tipo", "tributos", "tomadorId", "tomadorNome", "servicoId", "servicoDescricao" ] }, "NfseResumoResponse": { "type": "object", "properties": { "id": { "type": "string" }, "empresaId": { "type": "string" }, "chaveAcesso": { "type": "string" }, "numero": { "type": "string" }, "dataEmissao": { "type": "string" }, "dataCompetencia": { "type": "string" }, "ambiente": { "type": "string", "enum": [ "homolog", "prod" ] }, "status": { "type": "string", "enum": [ "autorizada", "cancelada", "substituida", "rejeitada" ] }, "valorServicos": { "type": "string", "example": "1500.00" }, "valorIss": { "type": "string", "example": "75.00" }, "valorIbs": { "type": "string", "example": "138.75" }, "valorCbs": { "type": "string", "example": "132.75" }, "valorIs": { "type": "string", "example": "0.00" }, "tomadorDoc": { "type": "string" }, "tomadorNome": { "type": "string" }, "protocolo": { "type": "string" }, "xmlUrl": { "type": "string" }, "pdfUrl": { "type": "string" }, "substituidaPor": { "type": "string", "nullable": true, "description": "Só na listagem: chave da NFS-e que substituiu esta; nulo se não foi substituída." }, "retencaoAplicada": { "description": "Só no detalhe: retenções que vieram de exigência do tomador ou de regra serviço×tomador.", "type": "array", "items": { "$ref": "#/components/schemas/RetencaoAplicadaResponse" } } }, "required": [ "id", "empresaId", "chaveAcesso", "numero", "dataEmissao", "dataCompetencia", "ambiente", "status", "valorServicos", "valorIss", "valorIbs", "valorCbs", "valorIs" ] }, "OrigemCampoResponse": { "type": "object", "properties": { "fonte": { "type": "string", "enum": [ "nota", "regra_servico_tomador", "tomador_exigencia", "servico", "tomador", "cliente", "regime", "municipal_adn", "tabela_municipal", "legislacao", "sugestao", "calculado", "dispensa" ], "example": "servico", "description": "Fonte do valor — significado e ordem de prioridade na introdução (\"Prioridade e origens\")." }, "base": { "type": "string", "description": "Base usada no cálculo (decimal com ponto).", "example": "1000.00" }, "aliquota": { "type": "string", "description": "Alíquota em % (decimal com ponto).", "example": "1.50" }, "fundamento": { "type": "string", "description": "Lei, regra ou conta que justifica o valor.", "example": "RIR/2018, art. 714" }, "ref": { "type": "string", "description": "Id do cadastro, da regra ou da vigência que decidiu." }, "regraId": { "type": "string", "description": "Id da regra fiscal que decidiu." }, "sobrescrito": { "type": "boolean", "description": "`true` quando o valor informado na nota prevaleceu sobre o calculado." }, "anterior": { "type": "string", "description": "Valor que o motor teria posto (quando a nota ajustou ou a retenção foi dispensada).", "example": "7.50" }, "motivo": { "type": "string", "description": "Motivo informado ao reduzir uma retenção calculada." }, "confirmar": { "type": "boolean", "description": "`true` = regra legal adotada como premissa, sem revisão de contador (aviso `PREMISSA_SEM_CONTADOR`)." } }, "required": [ "fonte" ] }, "DetalhesLimitePlanoResponse": { "type": "object", "properties": { "recurso": { "type": "string", "enum": [ "nota" ] }, "franquia": { "type": "number", "example": 1000, "description": "Notas incluídas no plano por mês." }, "notasMes": { "type": "number", "example": 1000, "description": "Notas do mês (horário de Brasília) que ocupam a franquia: autorizadas e em processamento." }, "excedenteDisponivel": { "type": "boolean", "description": "O plano tem preço de excedente (o Dono ou um administrador pode ativá-lo em Plano e uso)." }, "precoExcedenteNota": { "type": "string", "nullable": true, "example": "0.20", "description": "Preço por nota acima da franquia, se houver." }, "acoes": { "type": "array", "items": { "type": "string", "enum": [ "ativar_excedente", "trocar_plano" ] } } }, "required": [ "recurso", "franquia", "notasMes", "excedenteDisponivel", "precoExcedenteNota", "acoes" ] }, "ProblemLimitePlanoResponse": { "type": "object", "properties": { "type": { "type": "string", "example": "https://nf.digla.io/api/erros/validation_error" }, "title": { "type": "string", "example": "Erro de validação" }, "status": { "type": "number", "example": 422 }, "code": { "type": "string", "example": "validation_error" }, "detail": { "type": "string", "example": "Campo \"tomador.documento\" inválido" }, "instance": { "type": "string", "example": "/v1/nfse" }, "requestId": { "type": "string", "example": "1HYz7q5p2a4Tn3" }, "detalhes": { "description": "Presente em `plano.limite` (franquia de notas).", "allOf": [ { "$ref": "#/components/schemas/DetalhesLimitePlanoResponse" } ] } }, "required": [ "type", "title", "status", "code", "detail", "instance" ] }, "PendenciaMotorResponse": { "type": "object", "properties": { "codigo": { "type": "string", "enum": [ "AJUSTE_NAO_PERMITIDO", "CBS_NAO_PUBLICADA", "DESCONTO_MAIOR_QUE_VALOR", "DESCONTO_NEGATIVO", "DPS_INVALIDA", "IBSCBS_INCOMPLETO", "IBS_NAO_PUBLICADO", "INSS_MATERIAIS_MAIOR_QUE_BASE", "ISS_ALIQUOTA_MAXIMA", "ISS_ALIQUOTA_MINIMA", "ISS_SEM_ALIQUOTA", "MOTIVO_OBRIGATORIO", "PIS_COFINS_SEM_CST", "REGIME_ESPECIAL_DEDUCAO_NOTA", "REGIME_ESPECIAL_SEM_ALIQUOTA", "REGIME_ESPECIAL_SEM_RETENCAO", "RETENCAO_ORGAO_MANUAL", "RETENCAO_ORGAO_NATUREZA", "VALOR_AUSENTE" ], "example": "ISS_SEM_ALIQUOTA" }, "mensagem": { "type": "string", "example": "Serviço sem alíquota de ISS e município sem parametrização no ADN — informe a alíquota no cadastro do serviço." }, "campo": { "type": "string", "example": "servicos[0].aliquotaIss" } }, "required": [ "codigo", "mensagem", "campo" ] }, "ProblemPendenciasResponse": { "type": "object", "properties": { "type": { "type": "string", "example": "https://nf.digla.io/api/erros/validation_error" }, "title": { "type": "string", "example": "Erro de validação" }, "status": { "type": "number", "example": 422 }, "code": { "type": "string", "example": "validation_error" }, "detail": { "type": "string", "example": "Campo \"tomador.documento\" inválido" }, "instance": { "type": "string", "example": "/v1/nfse" }, "requestId": { "type": "string", "example": "1HYz7q5p2a4Tn3" }, "pendencias": { "description": "Em `tributacao.pendente`: o que corrigir.", "type": "array", "items": { "$ref": "#/components/schemas/PendenciaMotorResponse" } }, "avisos": { "type": "array", "items": { "$ref": "#/components/schemas/AvisoMotorResponse" } } }, "required": [ "type", "title", "status", "code", "detail", "instance" ] }, "EventoNfseResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tipo": { "type": "string", "example": "cancelamento", "description": "Tipo do evento (`cancelamento`, `substituicao`…)." }, "numeroSeq": { "type": "number", "example": 1 }, "motivo": { "type": "string", "nullable": true, "example": "Erro na emissão do documento" }, "status": { "type": "string", "example": "rejected", "description": "Situação do pedido (`pending`, `sent`, `authorized`, `rejected`…)." }, "protocolo": { "type": "string", "nullable": true }, "rejectionCode": { "type": "string", "nullable": true, "example": "E0822", "description": "Código de rejeição da Sefin." }, "rejectionMessage": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": "string", "nullable": true, "format": "date-time" }, "authorizedAt": { "type": "string", "nullable": true, "format": "date-time" }, "explicacao": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Explicação da rejeição (`codigo`, `mensagemOficial`, `regraOficial`, `campo`, `documento`, `orientacao`); nulo sem rejeição." } }, "required": [ "id", "tipo", "numeroSeq", "motivo", "status", "protocolo", "rejectionCode", "rejectionMessage", "createdAt", "sentAt", "authorizedAt", "explicacao" ] }, "NotaDaCadeiaResponse": { "type": "object", "properties": { "chaveAcesso": { "type": "string", "example": "35503082212345678000195000000000000126101234567895" }, "numero": { "type": "string", "example": "12345" }, "status": { "type": "string", "example": "autorizada" }, "dataEmissao": { "type": "string", "format": "date-time" } }, "required": [ "chaveAcesso", "numero", "status", "dataEmissao" ] }, "CadeiaSubstituicoesResponse": { "type": "object", "properties": { "atual": { "$ref": "#/components/schemas/NotaDaCadeiaResponse" }, "anterior": { "nullable": true, "description": "A nota que esta substituiu.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/NotaDaCadeiaResponse" } ] }, "posteriores": { "description": "As notas que substituíram esta.", "type": "array", "items": { "$ref": "#/components/schemas/NotaDaCadeiaResponse" } } }, "required": [ "atual", "anterior", "posteriores" ] }, "LoteResultadoItemResponse": { "type": "object", "properties": { "index": { "type": "number", "example": 0, "description": "Posição da DPS no corpo." }, "dpsId": { "type": "string", "description": "Id da DPS enfileirada (acompanhe por webhook ou `GET /v1/nfse`)." }, "error": { "type": "string", "example": "Limite do plano atingido", "description": "Mensagem do erro do item." }, "code": { "type": "string", "example": "plano.limite", "description": "Código do erro do item (ex.: `plano.limite`, `tributacao.pendente`, `validation_error`)." } }, "required": [ "index" ] }, "LoteEmitidoResponse": { "type": "object", "properties": { "total": { "type": "number", "example": 2 }, "idempotente": { "type": "boolean", "description": "`true` quando a resposta veio de um reenvio com a mesma `Idempotency-Key`." }, "resultados": { "type": "array", "items": { "$ref": "#/components/schemas/LoteResultadoItemResponse" } } }, "required": [ "total", "idempotente", "resultados" ] }, "DanfseEnfileiradaResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "enqueued" ] }, "nfseId": { "type": "string", "format": "uuid" } }, "required": [ "status", "nfseId" ] }, "EmissorNacionalEstadoResponse": { "type": "object", "properties": { "aplicavel": { "type": "boolean", "description": "Falso quando o regime ou o município do cliente não exigem a confirmação." }, "confirmada": { "type": "boolean" }, "municipioIbge": { "type": "number", "example": 3550308 }, "confirmadoEm": { "type": "string", "nullable": true, "format": "date-time" }, "situacao": { "type": "string", "nullable": true }, "fonte": { "type": "string", "nullable": true } }, "required": [ "aplicavel", "confirmada", "municipioIbge", "confirmadoEm", "situacao", "fonte" ] }, "RegimeVigenteResponse": { "type": "object", "properties": { "regime": { "type": "string", "enum": [ "simples", "mei", "lucroPresumido", "lucroReal", "autonomo" ] }, "regimeApuracaoSn": { "type": "string", "enum": [ "1", "2", "3" ] }, "percentualTotTribSn": { "type": "string", "nullable": true }, "pisCofinsCumulativo": { "type": "boolean", "nullable": true }, "regimeEspecialIss": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "9" ] }, "profissionaisHabilitados": { "type": "integer", "nullable": true }, "cprb": { "type": "boolean" }, "vigenciaId": { "type": "string", "format": "uuid" }, "aviso": { "type": "string", "nullable": true } }, "required": [ "regime", "regimeApuracaoSn", "percentualTotTribSn", "pisCofinsCumulativo", "regimeEspecialIss", "profissionaisHabilitados", "cprb", "vigenciaId", "aviso" ] }, "RegimeResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "7a2e3d4c-5b6a-4f8e-9a0b-1c2d3e4f5a6b" }, "clienteId": { "type": "string", "format": "uuid", "example": "9c2a6f4b-1c7e-4d6e-9a44-a89f1a3e8c4d" }, "vigenciaInicio": { "type": "string", "example": "2026-10-01", "description": "Primeiro dia da competência." }, "vigenciaFim": { "type": "string", "nullable": true, "example": "2026-12-31", "description": "Nulo = vigente." }, "regime": { "type": "string", "enum": [ "simples", "mei", "lucroPresumido", "lucroReal", "autonomo" ] }, "regimeApuracaoSn": { "type": "string", "enum": [ "1", "2", "3" ], "description": "Simples Nacional: 1 todos os tributos pelo Simples; 2 ISS fora do Simples; 3 ISS e PIS/COFINS fora." }, "percentualTotTribSn": { "type": "string", "nullable": true, "example": "6.00", "description": "pTotTribSN (Lei 12.741)." }, "pisCofinsCumulativo": { "type": "boolean", "nullable": true, "description": "PIS/COFINS cumulativo (só no Lucro Real); nulo = padrão do regime." }, "regimeEspecialIss": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "9" ], "description": "Regime especial de tributação do ISS: 0 nenhum; 6 sociedade de profissionais (exige `profissionaisHabilitados`)." }, "profissionaisHabilitados": { "type": "integer", "nullable": true, "description": "Profissionais habilitados da sociedade de profissionais (só com `regimeEspecialIss` \"6\")." }, "cprb": { "type": "boolean", "description": "Contribuição previdenciária sobre a receita bruta (só Lucro Presumido/Real)." }, "motivo": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-10-23T14:32:10.000Z" } }, "required": [ "id", "clienteId", "vigenciaInicio", "vigenciaFim", "regime", "regimeApuracaoSn", "percentualTotTribSn", "pisCofinsCumulativo", "regimeEspecialIss", "profissionaisHabilitados", "cprb", "motivo", "createdAt" ] }, "PerfilFiscalResponse": { "type": "object", "properties": { "clienteId": { "type": "string", "format": "uuid", "example": "9c2a6f4b-1c7e-4d6e-9a44-a89f1a3e8c4d" }, "municipioIbge": { "type": "number", "example": 3550308 }, "tipoDocumento": { "type": "string", "enum": [ "CPF", "CNPJ" ] }, "hoje": { "type": "string", "example": "2026-10-23", "description": "Data de hoje (Brasília) usada para escolher o regime vigente." }, "regimeVigente": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/RegimeVigenteResponse" } ] }, "historico": { "type": "array", "items": { "$ref": "#/components/schemas/RegimeResponse" } } }, "required": [ "clienteId", "municipioIbge", "tipoDocumento", "hoje", "regimeVigente", "historico" ] }, "RegimeCriadoResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "7a2e3d4c-5b6a-4f8e-9a0b-1c2d3e4f5a6b" }, "clienteId": { "type": "string", "format": "uuid", "example": "9c2a6f4b-1c7e-4d6e-9a44-a89f1a3e8c4d" }, "vigenciaInicio": { "type": "string", "example": "2026-10-01", "description": "Primeiro dia da competência." }, "vigenciaFim": { "type": "string", "nullable": true, "example": "2026-12-31", "description": "Nulo = vigente." }, "regime": { "type": "string", "enum": [ "simples", "mei", "lucroPresumido", "lucroReal", "autonomo" ] }, "regimeApuracaoSn": { "type": "string", "enum": [ "1", "2", "3" ], "description": "Simples Nacional: 1 todos os tributos pelo Simples; 2 ISS fora do Simples; 3 ISS e PIS/COFINS fora." }, "percentualTotTribSn": { "type": "string", "nullable": true, "example": "6.00", "description": "pTotTribSN (Lei 12.741)." }, "pisCofinsCumulativo": { "type": "boolean", "nullable": true, "description": "PIS/COFINS cumulativo (só no Lucro Real); nulo = padrão do regime." }, "regimeEspecialIss": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "9" ], "description": "Regime especial de tributação do ISS: 0 nenhum; 6 sociedade de profissionais (exige `profissionaisHabilitados`)." }, "profissionaisHabilitados": { "type": "integer", "nullable": true, "description": "Profissionais habilitados da sociedade de profissionais (só com `regimeEspecialIss` \"6\")." }, "cprb": { "type": "boolean", "description": "Contribuição previdenciária sobre a receita bruta (só Lucro Presumido/Real)." }, "motivo": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-10-23T14:32:10.000Z" }, "avisos": { "description": "Avisos da criação (ex.: notas já autorizadas na competência com o regime anterior). Vazio quando não há.", "type": "array", "items": { "type": "string" } } }, "required": [ "id", "clienteId", "vigenciaInicio", "vigenciaFim", "regime", "regimeApuracaoSn", "percentualTotTribSn", "pisCofinsCumulativo", "regimeEspecialIss", "profissionaisHabilitados", "cprb", "motivo", "createdAt", "avisos" ] }, "RetencoesResumoResponse": { "type": "object", "properties": { "irrfAliquota": { "type": "string", "example": "1.50", "description": "\"0.00\" = a regra força não reter." }, "csrf": { "type": "boolean" }, "inssAliquota": { "type": "string", "example": "11.00" }, "issRetido": { "type": "boolean" } } }, "RegraTomadorItemResponse": { "type": "object", "properties": { "tipo": { "type": "string", "enum": [ "regra", "exigencia" ], "description": "`exigencia` = exigência de retenção do próprio tomador (vale para todos os serviços; `servicoId` nulo)." }, "id": { "type": "string", "format": "uuid", "description": "Id da regra (tipo `regra`) ou do tomador (tipo `exigencia`)." }, "tomadorId": { "type": "string", "format": "uuid" }, "tomadorNome": { "type": "string" }, "servicoId": { "type": "string", "nullable": true, "format": "uuid" }, "servicoDescricao": { "type": "string", "nullable": true }, "retencoes": { "$ref": "#/components/schemas/RetencoesResumoResponse" }, "outrosCampos": { "type": "integer", "description": "Quantidade dos demais campos ajustados pela regra (fora as retenções do resumo)." }, "motivo": { "type": "string", "nullable": true }, "ativo": { "type": "boolean" }, "desde": { "type": "string", "format": "date-time", "example": "2026-10-23T14:32:10.000Z", "description": "Início da vigência (ISO-8601, UTC)." }, "atualizadaEm": { "type": "string", "format": "date-time", "example": "2026-10-23T14:32:10.000Z", "description": "Última alteração (ISO-8601, UTC)." }, "criadoPor": { "type": "string", "nullable": true, "example": "Maria Silva", "description": "Nome de quem criou a regra ou definiu a exigência; nulo se foi um token de API." } }, "required": [ "tipo", "id", "tomadorId", "tomadorNome", "servicoId", "servicoDescricao", "retencoes", "outrosCampos", "motivo", "ativo", "desde", "atualizadaEm", "criadoPor" ] }, "RegraParResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "7a2e3d4c-5b6a-4f8e-9a0b-1c2d3e4f5a6b" }, "clienteId": { "type": "string", "format": "uuid", "example": "9c2a6f4b-1c7e-4d6e-9a44-a89f1a3e8c4d" }, "servicoId": { "type": "string", "format": "uuid" }, "tomadorId": { "type": "string", "format": "uuid" }, "tomadorNome": { "type": "string", "nullable": true }, "campos": { "type": "object", "additionalProperties": true, "example": { "ret.irrf.aliquota": "1.50" }, "description": "Só as chaves aceitas em `PUT` (`iss.*`, `ret.*`, `deducao.*`, `ibscbs.*`)." }, "motivo": { "type": "string", "nullable": true }, "ativo": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-10-23T14:32:10.000Z" } }, "required": [ "id", "clienteId", "servicoId", "tomadorId", "campos", "motivo", "ativo", "updatedAt" ] }, "IbptEstadoResponse": { "type": "object", "properties": { "clienteId": { "type": "string", "format": "uuid", "example": "9c2a6f4b-1c7e-4d6e-9a44-a89f1a3e8c4d" }, "configurado": { "type": "boolean", "description": "Há token cadastrado." }, "tokenFinal": { "type": "string", "nullable": true, "example": "AB12", "description": "Últimos 4 caracteres do token (o token nunca volta)." }, "configuradoEm": { "type": "string", "nullable": true, "format": "date-time" }, "usarIbpt": { "type": "boolean" }, "status": { "type": "string", "enum": [ "sem_token", "pendente", "ok", "token_invalido", "erro" ] }, "statusDetalhe": { "type": "string", "nullable": true }, "testadoEm": { "type": "string", "nullable": true, "format": "date-time" }, "ultimaImportacaoEm": { "type": "string", "nullable": true, "format": "date-time" }, "ultimaImportacaoLinhas": { "type": "integer", "nullable": true }, "apto": { "type": "boolean", "description": "O cliente tem CNPJ e UF (o IBPT exige os dois)." } }, "required": [ "clienteId", "configurado", "tokenFinal", "configuradoEm", "usarIbpt", "status", "statusDetalhe", "testadoEm", "ultimaImportacaoEm", "ultimaImportacaoLinhas", "apto" ] }, "IbptTesteResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "sem_token", "pendente", "ok", "token_invalido", "erro" ] }, "mensagem": { "type": "string" }, "testadoEm": { "type": "string", "format": "date-time" } }, "required": [ "ok", "status", "mensagem", "testadoEm" ] }, "EventoEnfileiradoResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "processando" } }, "required": [ "id", "status" ] }, "SubstituicaoInstrucoesResponse": { "type": "object", "properties": { "next": { "type": "object", "properties": { "method": { "type": "string", "example": "POST" }, "url": { "type": "string", "example": "/v1/nfse" }, "instructions": { "type": "string" }, "substituiChaveAcesso": { "type": "string", "example": "35503082212345678000195000000000000126101234567895" } }, "required": [ "method", "url", "instructions", "substituiChaveAcesso" ] } } }, "WebhookResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "nome": { "type": "string", "example": "ERP Produção" }, "url": { "type": "string", "example": "https://erp.cliente.com/integracoes/nfse" }, "eventos": { "example": [ "nfse.authorized", "nfse.rejected" ], "type": "array", "items": { "type": "string" } }, "ativo": { "type": "boolean" }, "empresaId": { "type": "string", "nullable": true, "format": "uuid", "description": "Cliente a que o webhook se restringe; nulo = todos os clientes da conta." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Só na resposta do `PATCH`." } }, "required": [ "id", "nome", "url", "eventos", "ativo", "empresaId", "createdAt" ] }, "WebhookCreatedResponse": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string", "description": "Segredo do webhook. Mostrado APENAS uma vez." } }, "required": [ "id", "secret" ] }, "OkResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ] }, "EntregaDeTesteResponse": { "type": "object", "properties": { "entregaId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "enqueued" ] } }, "required": [ "entregaId", "status" ] }, "EntregaReenfileiradaResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "entregaId": { "type": "string", "format": "uuid" } }, "required": [ "ok", "entregaId" ] }, "DfeSituacaoResponse": { "type": "object", "properties": { "empresaId": { "type": "string", "format": "uuid", "description": "Id do cliente." }, "razaoSocial": { "type": "string" }, "documento": { "type": "string", "example": "12345678000195" }, "ambiente": { "type": "string", "enum": [ "homolog", "prod" ] }, "temCertificado": { "type": "boolean" }, "ultimaTentativaEm": { "type": "string", "nullable": true, "format": "date-time" }, "ultimoSucessoEm": { "type": "string", "nullable": true, "format": "date-time" }, "ultimoErroEm": { "type": "string", "nullable": true, "format": "date-time" }, "ultimoErroCodigo": { "type": "string", "nullable": true }, "ultimoErro": { "type": "string", "nullable": true }, "falhasConsecutivas": { "type": "integer" }, "recebidosUltimaExecucao": { "type": "integer" }, "recebidasTerceiros": { "type": "integer" }, "ultimaRecebidaEm": { "type": "string", "nullable": true, "format": "date-time" }, "situacao": { "type": "string", "example": "aguardando", "description": "Situação da busca (`aguardando`, `ok`, `atrasada`, `com_erro`, `sem_certificado`…)." }, "detalhe": { "type": "string" } }, "required": [ "empresaId", "razaoSocial", "documento", "ambiente", "temCertificado", "ultimaTentativaEm", "ultimoSucessoEm", "ultimoErroEm", "ultimoErroCodigo", "ultimoErro", "falhasConsecutivas", "recebidosUltimaExecucao", "recebidasTerceiros", "ultimaRecebidaEm", "situacao", "detalhe" ] }, "DfeSincronizacaoResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "enfileirado" ] }, "jobId": { "type": "string", "example": "dfe-manual--" } }, "required": [ "status", "jobId" ] }, "NfeRecebidaItemResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "chave": { "type": "string", "example": "35261012345678000195550010000012341000012345", "description": "Chave de acesso (44 dígitos)." }, "numero": { "type": "string", "nullable": true, "example": "1234" }, "serie": { "type": "string", "nullable": true, "example": "1" }, "emitenteDoc": { "type": "string", "nullable": true, "example": "12345678000195", "description": "CPF/CNPJ do emitente." }, "emitenteNome": { "type": "string", "nullable": true, "example": "Fornecedor Exemplo Ltda" }, "emitenteUf": { "type": "string", "nullable": true, "example": "SP" }, "dataEmissao": { "type": "string", "nullable": true, "format": "date-time", "example": "2026-10-08T14:32:10.000Z" }, "valorTotal": { "type": "string", "nullable": true, "example": "1520.40", "description": "Valor total da NF-e (texto decimal)." }, "situacao": { "type": "string", "enum": [ "autorizada", "denegada", "cancelada" ] }, "manifestacao": { "type": "string", "enum": [ "pendente", "ciencia", "confirmada", "desconhecida", "nao_realizada" ], "description": "Última manifestação registrada pela SEFAZ." }, "manifestadaEm": { "type": "string", "nullable": true, "format": "date-time" }, "canceladaEm": { "type": "string", "nullable": true, "format": "date-time" }, "xmlCompleto": { "type": "boolean", "description": "O XML completo (procNFe) já foi recebido." }, "recebidaEm": { "type": "string", "format": "date-time" } }, "required": [ "id", "chave", "numero", "serie", "emitenteDoc", "emitenteNome", "emitenteUf", "dataEmissao", "valorTotal", "situacao", "manifestacao", "manifestadaEm", "canceladaEm", "xmlCompleto", "recebidaEm" ] }, "NfeRecebidasConfigResponse": { "type": "object", "properties": { "ativo": { "type": "boolean", "description": "Busca automática de NF-e ligada (padrão desligada)." }, "cienciaAutomatica": { "type": "boolean", "description": "Registrar a Ciência da Operação sozinho a cada resumo novo (libera o XML completo)." }, "ativadoEm": { "type": "string", "nullable": true, "format": "date-time" }, "certificado": { "type": "string", "enum": [ "ok", "ausente", "vencido", "ainda_nao_valido" ], "description": "Certificado A1 do cliente (a busca exige `ok`)." } }, "required": [ "ativo", "cienciaAutomatica", "ativadoEm", "certificado" ] }, "NfeBuscaEnfileiradaResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "enfileirado" }, "jobId": { "type": "string", "example": "nfe-dist-…-manual-29884512" } }, "required": [ "status", "jobId" ] }, "NfeSituacaoResponse": { "type": "object", "properties": { "ativo": { "type": "boolean" }, "cienciaAutomatica": { "type": "boolean" }, "certificado": { "type": "string", "enum": [ "ok", "ausente", "vencido", "ainda_nao_valido" ] }, "ultimaTentativaEm": { "type": "string", "nullable": true, "format": "date-time" }, "ultimoSucessoEm": { "type": "string", "nullable": true, "format": "date-time" }, "ultimoCstat": { "type": "string", "nullable": true, "example": "137", "description": "Último cStat da Distribuição (138 = documentos; 137 = nenhum; 656 = consumo indevido)." }, "proximaConsultaEm": { "type": "string", "nullable": true, "format": "date-time", "description": "Próxima consulta permitida pela SEFAZ (regra de 1 h)." }, "consultaPermitidaAgora": { "type": "boolean", "description": "`POST …/sincronizar` será aceito agora." }, "ultimoErroEm": { "type": "string", "nullable": true, "format": "date-time" }, "ultimoErroCodigo": { "type": "string", "nullable": true, "enum": [ "sem_certificado", "certificado_invalido", "sefaz_recusou", "sefaz_indisponivel", "consumo_indevido", "interno" ] }, "ultimoErro": { "type": "string", "nullable": true }, "falhasConsecutivas": { "type": "number" }, "recebidosUltimaExecucao": { "type": "number" }, "consumoIndevidoEm": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "ativo", "cienciaAutomatica", "certificado", "ultimaTentativaEm", "ultimoSucessoEm", "ultimoCstat", "proximaConsultaEm", "consultaPermitidaAgora", "ultimoErroEm", "ultimoErroCodigo", "ultimoErro", "falhasConsecutivas", "recebidosUltimaExecucao", "consumoIndevidoEm" ] }, "EmitenteNfeResponse": { "type": "object", "properties": { "documento": { "type": "string", "nullable": true }, "nome": { "type": "string", "nullable": true }, "inscricaoEstadual": { "type": "string", "nullable": true }, "uf": { "type": "string", "nullable": true } }, "required": [ "documento", "nome", "inscricaoEstadual", "uf" ] }, "XmlDisponivelResponse": { "type": "object", "properties": { "resumo": { "type": "boolean", "description": "Resumo (resNFe) disponível." }, "completo": { "type": "boolean", "description": "XML completo (procNFe) disponível — só após Ciência, Confirmação ou Operação não Realizada." }, "completoEm": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "resumo", "completo", "completoEm" ] }, "DocumentoDistribuicaoResponse": { "type": "object", "properties": { "nsu": { "type": "string", "example": "000000000012345", "description": "NSU do Ambiente Nacional." }, "tipo": { "type": "string", "enum": [ "resNFe", "procNFe", "resEvento", "procEventoNFe", "outro" ] }, "schema": { "type": "string", "example": "resNFe_v1.01.xsd" }, "tpEvento": { "type": "string", "nullable": true, "example": "110111", "description": "Tipo do evento (cancelamento 110111, carta de correção 110110…)." }, "recebidoEm": { "type": "string", "format": "date-time" } }, "required": [ "nsu", "tipo", "schema", "tpEvento", "recebidoEm" ] }, "NfeManifestacaoResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "chave": { "type": "string", "example": "35261012345678000195550010000012341000012345" }, "tipo": { "type": "string", "enum": [ "confirmacao", "ciencia", "desconhecimento", "nao_realizada" ], "example": "ciencia" }, "tpEvento": { "type": "string", "enum": [ "210200", "210210", "210220", "210240" ], "example": "210210", "description": "Código do evento na SEFAZ." }, "nSeq": { "type": "number", "example": 1, "description": "Sequência do evento (1 ou 2 — até 2 por tipo conclusivo)." }, "justificativa": { "type": "string", "nullable": true, "description": "Só em Operação não Realizada." }, "status": { "type": "string", "enum": [ "pendente", "enviando", "registrada", "rejeitada", "erro" ], "example": "pendente" }, "cStat": { "type": "string", "nullable": true, "example": "135", "description": "Código da SEFAZ (135/136 registrado; outros = rejeição)." }, "xMotivo": { "type": "string", "nullable": true }, "protocolo": { "type": "string", "nullable": true }, "registradaEm": { "type": "string", "nullable": true, "format": "date-time" }, "origem": { "type": "string", "enum": [ "usuario", "token", "automatica" ] }, "criadoEm": { "type": "string", "format": "date-time" } }, "required": [ "id", "chave", "tipo", "tpEvento", "nSeq", "justificativa", "status", "cStat", "xMotivo", "protocolo", "registradaEm", "origem", "criadoEm" ] }, "DisponibilidadeManifestacaoResponse": { "type": "object", "properties": { "disponivel": { "type": "boolean" }, "motivo": { "type": "string", "description": "Por que não está disponível (fora_do_prazo, ciencia_apos_conclusiva, limite_eventos, em_andamento, nfe_cancelada…)." }, "prazoAte": { "type": "string", "format": "date-time", "description": "Fim do prazo da SEFAZ para este tipo." } }, "required": [ "disponivel" ] }, "ManifestacoesDisponiveisResponse": { "type": "object", "properties": { "ciencia": { "$ref": "#/components/schemas/DisponibilidadeManifestacaoResponse" }, "confirmacao": { "$ref": "#/components/schemas/DisponibilidadeManifestacaoResponse" }, "desconhecimento": { "$ref": "#/components/schemas/DisponibilidadeManifestacaoResponse" }, "nao_realizada": { "$ref": "#/components/schemas/DisponibilidadeManifestacaoResponse" } }, "required": [ "ciencia", "confirmacao", "desconhecimento", "nao_realizada" ] }, "NfeRecebidaDetalheResponse": { "type": "object", "properties": { "chave": { "type": "string", "example": "35261012345678000195550010000012341000012345" }, "numero": { "type": "string", "nullable": true }, "serie": { "type": "string", "nullable": true }, "emitente": { "$ref": "#/components/schemas/EmitenteNfeResponse" }, "tpNf": { "type": "number", "nullable": true, "description": "0 = entrada, 1 = saída (do ponto de vista do emitente)." }, "dataEmissao": { "type": "string", "nullable": true, "format": "date-time" }, "valorTotal": { "type": "string", "nullable": true }, "protocolo": { "type": "string", "nullable": true }, "autorizadaEm": { "type": "string", "nullable": true, "format": "date-time" }, "situacao": { "type": "string", "enum": [ "autorizada", "denegada", "cancelada" ] }, "canceladaEm": { "type": "string", "nullable": true, "format": "date-time" }, "manifestacao": { "type": "string", "enum": [ "pendente", "ciencia", "confirmada", "desconhecida", "nao_realizada" ] }, "manifestadaEm": { "type": "string", "nullable": true, "format": "date-time" }, "xml": { "$ref": "#/components/schemas/XmlDisponivelResponse" }, "recebidaEm": { "type": "string", "format": "date-time" }, "documentos": { "description": "Documentos e eventos recebidos da SEFAZ para esta chave, por NSU.", "type": "array", "items": { "$ref": "#/components/schemas/DocumentoDistribuicaoResponse" } }, "manifestacoes": { "type": "array", "items": { "$ref": "#/components/schemas/NfeManifestacaoResponse" } }, "manifestacoesDisponiveis": { "description": "O que pode ser manifestado agora (mesma regra do POST …/manifestar).", "allOf": [ { "$ref": "#/components/schemas/ManifestacoesDisponiveisResponse" } ] } }, "required": [ "chave", "numero", "serie", "emitente", "tpNf", "dataEmissao", "valorTotal", "protocolo", "autorizadaEm", "situacao", "canceladaEm", "manifestacao", "manifestadaEm", "xml", "recebidaEm", "documentos", "manifestacoes", "manifestacoesDisponiveis" ] }, "NfeXmlUrlResponse": { "type": "object", "properties": { "tipo": { "type": "string", "enum": [ "completo", "resumo" ] }, "url": { "type": "string", "description": "URL pré-assinada (GET), válida por 300 s." }, "expiraEm": { "type": "string", "format": "date-time" } }, "required": [ "tipo", "url", "expiraEm" ] }, "NfeProdutoResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clienteId": { "type": "string", "format": "uuid" }, "codigo": { "type": "string", "example": "CAM-001", "description": "Código do ERP (cProd), único por cliente." }, "descricao": { "type": "string", "example": "Camiseta algodão" }, "ncm": { "type": "string", "example": "61091000" }, "cest": { "type": "string", "nullable": true }, "gtin": { "type": "string", "nullable": true, "description": "null = \"SEM GTIN\"." }, "unidade": { "type": "string", "example": "UN" }, "valorPadrao": { "type": "string", "nullable": true, "example": "10.5000000000" }, "origem": { "type": "number", "example": 0 }, "cfopInterno": { "type": "string", "example": "5102" }, "cfopInterestadual": { "type": "string", "nullable": true, "example": "6102" }, "icmsCst": { "type": "string", "nullable": true, "example": null, "description": "CST do ICMS (regime normal)." }, "icmsCsosn": { "type": "string", "nullable": true, "example": "102", "description": "CSOSN (Simples Nacional/MEI)." }, "icmsModBc": { "type": "number", "nullable": true }, "icmsAliquota": { "type": "string", "nullable": true }, "icmsReducaoBc": { "type": "string", "nullable": true }, "icmsModBcSt": { "type": "number", "nullable": true }, "icmsMvaOriginal": { "type": "string", "nullable": true }, "icmsAliquotaSt": { "type": "string", "nullable": true }, "icmsReducaoBcSt": { "type": "string", "nullable": true }, "icmsAliquotaCreditoSn": { "type": "string", "nullable": true }, "fcpAliquota": { "type": "string", "nullable": true }, "fcpStAliquota": { "type": "string", "nullable": true }, "cbenef": { "type": "string", "nullable": true }, "pisCst": { "type": "string", "example": "49" }, "pisAliquota": { "type": "string", "nullable": true }, "cofinsCst": { "type": "string", "example": "49" }, "cofinsAliquota": { "type": "string", "nullable": true }, "ipiCst": { "type": "string", "nullable": true }, "ipiCenq": { "type": "string", "nullable": true }, "ipiAliquota": { "type": "string", "nullable": true }, "ibscbsCst": { "type": "string", "nullable": true }, "ibscbsCclassTrib": { "type": "string", "nullable": true }, "fci": { "type": "string", "nullable": true, "example": "A1B2C3D4-E5F6-A7B8-C9D0-E1F2A3B4C5D6", "description": "Ficha de Conteúdo de Importação (8-4-4-4-12 hexadecimal maiúsculo)." }, "ativo": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "clienteId", "codigo", "descricao", "ncm", "cest", "gtin", "unidade", "valorPadrao", "origem", "cfopInterno", "cfopInterestadual", "icmsCst", "icmsCsosn", "icmsModBc", "icmsAliquota", "icmsReducaoBc", "icmsModBcSt", "icmsMvaOriginal", "icmsAliquotaSt", "icmsReducaoBcSt", "icmsAliquotaCreditoSn", "fcpAliquota", "fcpStAliquota", "cbenef", "pisCst", "pisAliquota", "cofinsCst", "cofinsAliquota", "ipiCst", "ipiCenq", "ipiAliquota", "ibscbsCst", "ibscbsCclassTrib", "fci", "ativo", "createdAt", "updatedAt" ] }, "NfeConfigResponse": { "type": "object", "properties": { "clienteId": { "type": "string", "format": "uuid" }, "ie": { "type": "string", "example": "123456785016", "description": "IE do emitente (ou ISENTO)." }, "crt": { "type": "number", "enum": [ 1, 2, 3, 4 ], "description": "1 Simples, 2 Simples com excesso de sublimite, 3 regime normal, 4 MEI." }, "regimePisCofins": { "type": "string", "enum": [ "simples", "cumulativo", "nao_cumulativo" ] }, "serieNfe": { "type": "number", "example": 1 }, "serieNfce": { "type": "number", "example": 1 }, "qrcodeVersao": { "type": "number", "enum": [ 2, 3 ], "description": "Versão do QR Code da NFC-e (v2 com CSC; v3 sem CSC)." }, "infAdicPadrao": { "type": "string", "nullable": true }, "excluirIcmsBasePisCofins": { "type": "boolean", "description": "ICMS fora da base do PIS/COFINS (Tema 69 do STF). Padrão true." }, "tributosAproximados": { "type": "boolean", "description": "Informa os tributos aproximados (Lei 12.741) nas informações complementares. Padrão true." }, "ieSubstituto": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "SP": "110042490114" }, "description": "IE do substituto tributário por UF de destino (só dígitos, 2 a 14)." }, "idCsc": { "type": "string", "nullable": true, "example": "1" }, "cscSufixo": { "type": "string", "nullable": true, "example": "XJ22", "description": "Últimos 4 caracteres do CSC (o CSC nunca volta)." }, "cscConfigurado": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "clienteId", "ie", "crt", "regimePisCofins", "serieNfe", "serieNfce", "qrcodeVersao", "infAdicPadrao", "excluirIcmsBasePisCofins", "tributosAproximados", "ieSubstituto", "idCsc", "cscSufixo", "cscConfigurado", "createdAt", "updatedAt" ] }, "NfeRegraIcmsResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clienteId": { "type": "string", "format": "uuid" }, "ufDestino": { "type": "string", "example": "SP" }, "produtoId": { "type": "string", "nullable": true, "format": "uuid" }, "produtoCodigo": { "type": "string", "nullable": true, "example": "CAM-001", "description": "Código do ERP do produto da regra." }, "cest": { "type": "string", "nullable": true, "example": "1700100" }, "ncm": { "type": "string", "nullable": true, "example": "2203", "description": "Prefixo de NCM (2 a 8 dígitos)." }, "sujeitoSt": { "type": "boolean" }, "mvaOriginal": { "type": "string", "nullable": true, "example": "40.0000" }, "aliquotaInterna": { "type": "string", "nullable": true, "example": "18.0000" }, "fcpAliquota": { "type": "string", "nullable": true, "example": "2.0000" }, "reducaoBcSt": { "type": "string", "nullable": true }, "aliquotaInterestadual": { "type": "string", "nullable": true }, "difalBaseDupla": { "type": "boolean", "nullable": true, "description": "null = usa a referência do sistema; true = base dupla; false = base única." }, "baseLegal": { "type": "string", "nullable": true }, "vigenciaInicio": { "type": "string", "nullable": true, "example": "2026-01-01" }, "vigenciaFim": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "clienteId", "ufDestino", "produtoId", "produtoCodigo", "cest", "ncm", "sujeitoSt", "mvaOriginal", "aliquotaInterna", "fcpAliquota", "reducaoBcSt", "aliquotaInterestadual", "difalBaseDupla", "baseLegal", "vigenciaInicio", "vigenciaFim", "createdAt", "updatedAt" ] }, "ReferenciaUfResponse": { "type": "object", "properties": { "uf": { "type": "string", "example": "SP" }, "aliquotaInterna": { "type": "string", "example": "18.00" }, "fcp": { "type": "string", "example": "2.00" }, "difalBaseDupla": { "type": "boolean" }, "vigenciaInicio": { "type": "string", "example": "2026-01-01" }, "confianca": { "type": "string", "enum": [ "alta", "media", "baixa" ] }, "fonte": { "type": "string" } }, "required": [ "uf", "aliquotaInterna", "fcp", "difalBaseDupla", "vigenciaInicio", "confianca", "fonte" ] }, "ErroLinhaCsvResponse": { "type": "object", "properties": { "linha": { "type": "number", "example": 3, "description": "Linha do arquivo (o cabeçalho é a 1)." }, "mensagem": { "type": "string" } }, "required": [ "linha", "mensagem" ] }, "ImportacaoRegrasResponse": { "type": "object", "properties": { "inseridas": { "type": "number", "example": 120 }, "ignoradas": { "type": "number", "example": 2, "description": "Linhas válidas que repetem uma regra já existente (mesma chave)." }, "erros": { "description": "Sempre vazio em sucesso; com erro a resposta é 422 e nada é gravado.", "type": "array", "items": { "$ref": "#/components/schemas/ErroLinhaCsvResponse" } } }, "required": [ "inseridas", "ignoradas", "erros" ] }, "ProblemCsvResponse": { "type": "object", "properties": { "type": { "type": "string", "example": "https://nf.digla.io/api/erros/validation_error" }, "title": { "type": "string", "example": "Erro de validação" }, "status": { "type": "number", "example": 422 }, "code": { "type": "string", "example": "validation_error" }, "detail": { "type": "string", "example": "Campo \"tomador.documento\" inválido" }, "instance": { "type": "string", "example": "/v1/nfse" }, "requestId": { "type": "string", "example": "1HYz7q5p2a4Tn3" }, "erros": { "type": "array", "items": { "$ref": "#/components/schemas/ErroLinhaCsvResponse" } }, "totalErros": { "type": "number", "example": 3 } }, "required": [ "type", "title", "status", "code", "detail", "instance", "erros", "totalErros" ] }, "IbptResumoResponse": { "type": "object", "properties": { "uf": { "type": "string", "example": "SP" }, "versao": { "type": "string", "example": "26.2.A" }, "chave": { "type": "string", "nullable": true }, "fonte": { "type": "string", "nullable": true, "example": "IBPT/empresometro.com.br" }, "vigenciaInicio": { "type": "string", "example": "2026-09-01" }, "vigenciaFim": { "type": "string", "example": "2026-12-31" }, "linhas": { "type": "number", "example": 10300, "description": "Quantidade de NCM com percentual." }, "importadoEm": { "type": "string", "format": "date-time" }, "vencida": { "type": "boolean", "description": "vigenciaFim anterior a hoje (America/Sao_Paulo): a emissão deixa de usar a tabela." } }, "required": [ "uf", "versao", "chave", "fonte", "vigenciaInicio", "vigenciaFim", "linhas", "importadoEm", "vencida" ] }, "IbptImportadaResponse": { "type": "object", "properties": { "linhas": { "type": "number", "example": 10300 }, "ignoradas": { "type": "number", "example": 120, "description": "Linhas fora do escopo (serviços, NBS, exceções) que não foram gravadas." }, "versao": { "type": "string", "example": "26.2.A" }, "vigenciaFim": { "type": "string", "example": "2026-12-31" } }, "required": [ "linhas", "ignoradas", "versao", "vigenciaFim" ] }, "EpecNfeResponse": { "type": "object", "properties": { "protocolo": { "type": "string", "nullable": true, "example": "891260000000077", "description": "Protocolo do EPEC (impresso no DANFE)." }, "registradoEm": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "protocolo", "registradoEm" ] }, "ContingenciaNfeResponse": { "type": "object", "properties": { "dhCont": { "type": "string", "format": "date-time", "description": "Entrada em contingência (dhCont, B28)." }, "xJust": { "type": "string", "description": "Justificativa (xJust, B29)." }, "pendenteTransmissao": { "type": "boolean", "description": "Ainda não transmitida ao autorizador normal." }, "transmitirAte": { "type": "string", "nullable": true, "format": "date-time" }, "epec": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/EpecNfeResponse" } ] } }, "required": [ "dhCont", "xJust", "pendenteTransmissao", "transmitirAte", "epec" ] }, "NotaRelacionadaResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "numero": { "type": "number" }, "serie": { "type": "number" }, "chave": { "type": "string", "nullable": true }, "status": { "type": "string" }, "tpEmis": { "type": "number" } }, "required": [ "id", "numero", "serie", "chave", "status", "tpEmis" ] }, "ArquivosNfeResponse": { "type": "object", "properties": { "xml": { "type": "boolean", "description": "nfeProc disponível (`GET …/{chave}/xml`)." }, "pdf": { "type": "boolean", "description": "DANFE disponível (`GET …/{chave}/pdf`)." } }, "required": [ "xml", "pdf" ] }, "AcoesNfeResponse": { "type": "object", "properties": { "reenviar": { "type": "boolean", "description": "Rejeitada (salvo 539 ou substituída por NFC-e off-line): pode corrigir e reenviar com o mesmo número." }, "cancelar": { "type": "boolean" }, "cartaCorrecao": { "type": "boolean", "description": "Só NF-e (modelo 55) autorizada." }, "transmitir": { "type": "boolean", "description": "Em contingência e pendente: pode transmitir agora (`POST …/{chave}/transmitir`)." }, "cancelarPorSubstituicao": { "type": "boolean", "description": "NFC-e normal autorizada que tem a substituta off-line: cancelar por substituição (110112)." } }, "required": [ "reenviar", "cancelar", "cartaCorrecao", "transmitir", "cancelarPorSubstituicao" ] }, "EventoNfeResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "nfeId": { "type": "string", "format": "uuid" }, "chave": { "type": "string", "example": "35261011222333000181550010000000071123456781" }, "tipo": { "type": "string", "enum": [ "cancelamento", "cancelamento_substituicao", "carta_correcao", "epec" ] }, "tpEvento": { "type": "string", "example": "110111", "description": "110111 cancelamento, 110112 cancelamento por substituição, 110110 CC-e, 110140 EPEC." }, "nSeq": { "type": "number", "example": 1 }, "justificativa": { "type": "string", "nullable": true }, "correcao": { "type": "string", "nullable": true }, "chaveSubstituta": { "type": "string", "nullable": true, "description": "Cancelamento por substituição: chave da NFC-e substituta (off-line)." }, "status": { "type": "string", "enum": [ "pendente", "enviando", "registrado", "rejeitado", "erro" ], "description": "`erro` = nova tentativa agendada." }, "cStat": { "type": "string", "nullable": true, "example": "135" }, "xMotivo": { "type": "string", "nullable": true }, "protocolo": { "type": "string", "nullable": true }, "registradoEm": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "nfeId", "chave", "tipo", "tpEvento", "nSeq", "justificativa", "correcao", "chaveSubstituta", "status", "cStat", "xMotivo", "protocolo", "registradoEm", "createdAt" ] }, "LinksNfeResponse": { "type": "object", "properties": { "self": { "type": "string" }, "xml": { "type": "string", "nullable": true }, "pdf": { "type": "string", "nullable": true }, "reenviar": { "type": "string", "nullable": true }, "transmitir": { "type": "string", "nullable": true }, "cancelarPorSubstituicao": { "type": "string", "nullable": true } }, "required": [ "self", "xml", "pdf", "reenviar", "transmitir", "cancelarPorSubstituicao" ] }, "NfeDetalheResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "modelo": { "type": "number", "enum": [ 55, 65 ] }, "serie": { "type": "number", "example": 1 }, "numero": { "type": "number", "example": 7 }, "chave": { "type": "string", "nullable": true, "example": "35261011222333000181550010000000071123456781", "description": "Gerada na montagem (antes do envio); nula numa rejeição local." }, "status": { "type": "string", "enum": [ "rascunho", "processando", "contingencia_pendente", "autorizada", "denegada", "rejeitada", "cancelada" ], "description": "`contingencia_pendente` = emitida em contingência (NFC-e off-line ou NF-e com EPEC), DANFE disponível, ainda não transmitida à SEFAZ." }, "ambiente": { "type": "string", "enum": [ "homolog", "prod" ] }, "destDoc": { "type": "string", "nullable": true, "example": "52998224725" }, "destNome": { "type": "string", "nullable": true, "example": "Fulano de Tal" }, "valorTotal": { "type": "string", "nullable": true, "example": "21.00", "description": "vNF (texto decimal)." }, "dhEmi": { "type": "string", "nullable": true, "format": "date-time" }, "cStat": { "type": "string", "nullable": true, "example": "100" }, "xMotivo": { "type": "string", "nullable": true, "example": "Autorizado o uso da NF-e" }, "protocolo": { "type": "string", "nullable": true, "example": "135260000012345" }, "externalRef": { "type": "string", "nullable": true }, "autorizadaEm": { "type": "string", "nullable": true, "format": "date-time" }, "canceladaEm": { "type": "string", "nullable": true, "format": "date-time" }, "tpEmis": { "type": "number", "enum": [ 1, 4, 6, 7, 9 ], "description": "Forma de emissão: 1 normal; 4 EPEC; 6 SVC-AN; 7 SVC-RS; 9 NFC-e off-line." }, "transmitirAte": { "type": "string", "nullable": true, "format": "date-time", "description": "Prazo para transmitir a nota em contingência (NFC-e off-line: fim do 1º dia útil seguinte; EPEC: 168 h); ausente nas notas fora de contingência." }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-10-12T14:32:10.000Z" }, "natOp": { "type": "string", "nullable": true, "example": "Venda de mercadoria" }, "destEmail": { "type": "string", "nullable": true }, "alerta": { "type": "string", "nullable": true, "description": "Alerta da autorização (cStat 120)." }, "updatedAt": { "type": "string", "format": "date-time" }, "entrada": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Corpo da emissão como foi enviado (para corrigir e reenviar a rejeitada)." }, "contingencia": { "nullable": true, "description": "Só nas notas emitidas em contingência (tpEmis ≠ 1).", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ContingenciaNfeResponse" } ] }, "substituidaPor": { "nullable": true, "description": "NFC-e off-line emitida no lugar desta, que ficou sem retorno do autorizador.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/NotaRelacionadaResponse" } ] }, "substitui": { "nullable": true, "description": "A NFC-e normal (sem retorno) que esta NFC-e off-line substituiu.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/NotaRelacionadaResponse" } ] }, "arquivos": { "$ref": "#/components/schemas/ArquivosNfeResponse" }, "acoes": { "$ref": "#/components/schemas/AcoesNfeResponse" }, "eventos": { "type": "array", "items": { "$ref": "#/components/schemas/EventoNfeResponse" } }, "links": { "$ref": "#/components/schemas/LinksNfeResponse" } }, "required": [ "id", "modelo", "serie", "numero", "chave", "status", "ambiente", "destDoc", "destNome", "valorTotal", "dhEmi", "cStat", "xMotivo", "protocolo", "externalRef", "autorizadaEm", "canceladaEm", "tpEmis", "createdAt", "natOp", "destEmail", "alerta", "updatedAt", "entrada", "contingencia", "substituidaPor", "substitui", "arquivos", "acoes", "eventos", "links" ] }, "ProblemaNfeResponse": { "type": "object", "properties": { "codigo": { "type": "string", "example": "nfe.vprod_divergente", "description": "Código da regra (`nfe.*`)." }, "regra": { "type": "string", "example": "I11-10 (Anexo I)", "description": "Regra oficial (Anexo I do MOC 7.0, NT ou \"Cadastro do produto\")." }, "mensagem": { "type": "string", "example": "vProd 21,00 difere de qCom × vUnCom = 21,50 (tolerância R$ 0,01)" }, "caminho": { "type": "string", "nullable": true, "example": "det[1]/prod/vProd", "description": "Caminho no documento (nomes das tags do leiaute)." } }, "required": [ "codigo", "regra", "mensagem", "caminho" ] }, "ProblemValidacaoNfeResponse": { "type": "object", "properties": { "type": { "type": "string", "example": "https://nf.digla.io/api/erros/validation_error" }, "title": { "type": "string", "example": "Erro de validação" }, "status": { "type": "number", "example": 422 }, "code": { "type": "string", "example": "validation_error" }, "detail": { "type": "string", "example": "Campo \"tomador.documento\" inválido" }, "instance": { "type": "string", "example": "/v1/nfse" }, "requestId": { "type": "string", "example": "1HYz7q5p2a4Tn3" }, "problemas": { "type": "array", "items": { "$ref": "#/components/schemas/ProblemaNfeResponse" } } }, "required": [ "type", "title", "status", "code", "detail", "instance", "problemas" ] }, "ValidacaoNfeResponse": { "type": "object", "properties": { "valido": { "type": "boolean" }, "problemas": { "type": "array", "items": { "$ref": "#/components/schemas/ProblemaNfeResponse" } }, "valorTotal": { "type": "string", "nullable": true, "example": "21.00", "description": "vNF calculado." }, "xml": { "type": "string", "nullable": true, "description": "XML da NF-e montado (sem assinatura, com número fictício) — só para conferência." } }, "required": [ "valido", "problemas", "valorTotal", "xml" ] }, "NfeItemResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "modelo": { "type": "number", "enum": [ 55, 65 ] }, "serie": { "type": "number", "example": 1 }, "numero": { "type": "number", "example": 7 }, "chave": { "type": "string", "nullable": true, "example": "35261011222333000181550010000000071123456781", "description": "Gerada na montagem (antes do envio); nula numa rejeição local." }, "status": { "type": "string", "enum": [ "rascunho", "processando", "contingencia_pendente", "autorizada", "denegada", "rejeitada", "cancelada" ], "description": "`contingencia_pendente` = emitida em contingência (NFC-e off-line ou NF-e com EPEC), DANFE disponível, ainda não transmitida à SEFAZ." }, "ambiente": { "type": "string", "enum": [ "homolog", "prod" ] }, "destDoc": { "type": "string", "nullable": true, "example": "52998224725" }, "destNome": { "type": "string", "nullable": true, "example": "Fulano de Tal" }, "valorTotal": { "type": "string", "nullable": true, "example": "21.00", "description": "vNF (texto decimal)." }, "dhEmi": { "type": "string", "nullable": true, "format": "date-time" }, "cStat": { "type": "string", "nullable": true, "example": "100" }, "xMotivo": { "type": "string", "nullable": true, "example": "Autorizado o uso da NF-e" }, "protocolo": { "type": "string", "nullable": true, "example": "135260000012345" }, "externalRef": { "type": "string", "nullable": true }, "autorizadaEm": { "type": "string", "nullable": true, "format": "date-time" }, "canceladaEm": { "type": "string", "nullable": true, "format": "date-time" }, "tpEmis": { "type": "number", "enum": [ 1, 4, 6, 7, 9 ], "description": "Forma de emissão: 1 normal; 4 EPEC; 6 SVC-AN; 7 SVC-RS; 9 NFC-e off-line." }, "transmitirAte": { "type": "string", "nullable": true, "format": "date-time", "description": "Prazo para transmitir a nota em contingência (NFC-e off-line: fim do 1º dia útil seguinte; EPEC: 168 h); ausente nas notas fora de contingência." }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-10-12T14:32:10.000Z" } }, "required": [ "id", "modelo", "serie", "numero", "chave", "status", "ambiente", "destDoc", "destNome", "valorTotal", "dhEmi", "cStat", "xMotivo", "protocolo", "externalRef", "autorizadaEm", "canceladaEm", "tpEmis", "createdAt" ] }, "NfeArquivoResponse": { "type": "object", "properties": { "tipo": { "type": "string", "enum": [ "xml", "pdf" ] }, "url": { "type": "string", "description": "URL pré-assinada (GET), válida por 300 s." }, "expiraEm": { "type": "string", "format": "date-time" } }, "required": [ "tipo", "url", "expiraEm" ] }, "InutilizacaoNfeResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "modelo": { "type": "number", "enum": [ 55, 65 ] }, "serie": { "type": "number" }, "ano": { "type": "number", "example": 26, "description": "Ano (2 dígitos)." }, "numeroIni": { "type": "number" }, "numeroFim": { "type": "number" }, "justificativa": { "type": "string" }, "status": { "type": "string", "enum": [ "pendente", "enviando", "homologada", "rejeitada", "erro" ] }, "cStat": { "type": "string", "nullable": true, "example": "102" }, "xMotivo": { "type": "string", "nullable": true }, "protocolo": { "type": "string", "nullable": true }, "homologadaEm": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "modelo", "serie", "ano", "numeroIni", "numeroFim", "justificativa", "status", "cStat", "xMotivo", "protocolo", "homologadaEm", "createdAt" ] }, "ContingenciaNfeEstadoResponse": { "type": "object", "properties": { "emContingencia": { "type": "boolean" }, "modo": { "type": "string", "nullable": true, "enum": [ "SVC-AN", "SVC-RS", "EPEC" ] }, "desde": { "type": "string", "nullable": true, "format": "date-time" }, "justificativa": { "type": "string", "nullable": true, "description": "Vira o xJust das notas." }, "automatica": { "type": "boolean", "description": "Entrou pelo status do serviço (sai sozinha quando o autorizador volta)." }, "preferencia": { "type": "string", "enum": [ "SVC", "EPEC" ], "description": "Escolha na entrada automática." }, "svcDaUf": { "type": "string", "enum": [ "SVC-AN", "SVC-RS" ], "description": "SVC que atende a UF do cliente no ambiente." }, "epecPermitido": { "type": "boolean", "description": "false em PR e PB (NT 2014.001 v1.41)." } }, "required": [ "emContingencia", "modo", "desde", "justificativa", "automatica", "preferencia", "svcDaUf", "epecPermitido" ] }, "ContingenciaNfceEstadoResponse": { "type": "object", "properties": { "offline": { "type": "boolean" }, "desde": { "type": "string", "nullable": true, "format": "date-time" }, "justificativa": { "type": "string", "nullable": true }, "automatica": { "type": "boolean" } }, "required": [ "offline", "desde", "justificativa", "automatica" ] }, "PendentesTransmissaoResponse": { "type": "object", "properties": { "quantidade": { "type": "number" }, "vencidas": { "type": "number", "description": "Com o prazo de transmissão vencido." }, "proximoPrazo": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "quantidade", "vencidas", "proximoPrazo" ] }, "AutorizadorStatusResponse": { "type": "object", "properties": { "situacao": { "type": "string", "enum": [ "operacao", "paralisado", "sem_resposta" ] }, "cStat": { "type": "string", "nullable": true, "example": "107" }, "verificadoEm": { "type": "string", "format": "date-time" }, "svc": { "type": "string", "nullable": true, "enum": [ "SVC-AN", "SVC-RS" ] }, "svcSituacao": { "type": "string", "nullable": true, "enum": [ "operacao", "paralisado", "sem_resposta" ] } }, "required": [ "situacao", "cStat", "verificadoEm", "svc", "svcSituacao" ] }, "AutorizadoresResponse": { "type": "object", "properties": { "nfe": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/AutorizadorStatusResponse" } ] }, "nfce": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/AutorizadorStatusResponse" } ] } }, "required": [ "nfe", "nfce" ] }, "NfeContingenciaResponse": { "type": "object", "properties": { "clienteId": { "type": "string", "format": "uuid" }, "uf": { "type": "string", "example": "SP" }, "ambiente": { "type": "string", "enum": [ "homolog", "prod" ] }, "nfe": { "$ref": "#/components/schemas/ContingenciaNfeEstadoResponse" }, "nfce": { "$ref": "#/components/schemas/ContingenciaNfceEstadoResponse" }, "pendentesTransmissao": { "$ref": "#/components/schemas/PendentesTransmissaoResponse" }, "autorizador": { "description": "Última verificação do status do serviço (NFeStatusServico4) da UF.", "allOf": [ { "$ref": "#/components/schemas/AutorizadoresResponse" } ] } }, "required": [ "clienteId", "uf", "ambiente", "nfe", "nfce", "pendentesTransmissao", "autorizador" ] }, "ProblemaSubstituicaoResponse": { "type": "object", "properties": { "cStat": { "type": "string", "example": "921", "description": "Rejeição da SEFAZ que a regra antecipa (NT 2018.004)." }, "mensagem": { "type": "string" } }, "required": [ "cStat", "mensagem" ] }, "ProblemSubstituicaoResponse": { "type": "object", "properties": { "type": { "type": "string", "example": "https://nf.digla.io/api/erros/validation_error" }, "title": { "type": "string", "example": "Erro de validação" }, "status": { "type": "number", "example": 422 }, "code": { "type": "string", "example": "validation_error" }, "detail": { "type": "string", "example": "Campo \"tomador.documento\" inválido" }, "instance": { "type": "string", "example": "/v1/nfse" }, "requestId": { "type": "string", "example": "1HYz7q5p2a4Tn3" }, "problemas": { "type": "array", "items": { "$ref": "#/components/schemas/ProblemaSubstituicaoResponse" } } }, "required": [ "type", "title", "status", "code", "detail", "instance", "problemas" ] }, "TomadorResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "7a2e3d4c-5b6a-4f8e-9a0b-1c2d3e4f5a6b" }, "clienteId": { "type": "string", "format": "uuid", "example": "9c2a6f4b-1c7e-4d6e-9a44-a89f1a3e8c4d" }, "tipoDoc": { "type": "string", "enum": [ "CPF", "CNPJ", "EXTERIOR", "NAO_INFORMADO" ] }, "documento": { "type": "string", "nullable": true, "example": "11222333000181", "description": "Só dígitos; nulo em exterior/não informado." }, "nome": { "type": "string", "example": "Tomadora LTDA" }, "inscricaoMunicipal": { "type": "string", "nullable": true }, "inscricaoEstadual": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "telefone": { "type": "string", "nullable": true }, "endereco": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/EnderecoCadastroResponse" } ] }, "observacoes": { "type": "string", "nullable": true }, "codigo": { "type": "string", "nullable": true, "example": "CLI-42", "description": "Código do integrador (único por cliente)." }, "retemIss": { "type": "boolean", "description": "O tomador retém o ISS." }, "retemIssMunicipioIbge": { "type": "integer", "nullable": true, "description": "Município de recolhimento do ISS retido." }, "retencaoFederal": { "type": "string", "enum": [ "nao_retem", "pj_comum", "pj_simples", "orgao_federal", "orgao_outros" ] }, "exigeIrrfAliquota": { "type": "string", "nullable": true, "example": "1.50", "description": "Exigência de IRRF para todos os serviços do tomador (só CNPJ); nulo = não exige." }, "exigeCsrf": { "type": "boolean", "description": "Exigência de retenção da CSRF (PIS/COFINS/CSLL) para todos os serviços (só CNPJ)." }, "exigeInssAliquota": { "type": "string", "nullable": true, "example": "11.00", "description": "Exigência de INSS para todos os serviços do tomador (só CNPJ); nulo = não exige." }, "exigenciaAtualizadaEm": { "type": "string", "nullable": true, "format": "date-time" }, "ativo": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-10-23T14:32:10.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-10-23T14:32:10.000Z" }, "qtdRegras": { "type": "integer", "description": "Só na listagem: regras serviço×tomador do tomador." } }, "required": [ "id", "clienteId", "tipoDoc", "documento", "nome", "inscricaoMunicipal", "inscricaoEstadual", "email", "telefone", "endereco", "observacoes", "codigo", "retemIss", "retemIssMunicipioIbge", "retencaoFederal", "exigeIrrfAliquota", "exigeCsrf", "exigeInssAliquota", "exigenciaAtualizadaEm", "ativo", "createdAt", "updatedAt" ] }, "ServicoResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "7a2e3d4c-5b6a-4f8e-9a0b-1c2d3e4f5a6b" }, "clienteId": { "type": "string", "format": "uuid", "example": "9c2a6f4b-1c7e-4d6e-9a44-a89f1a3e8c4d" }, "descricao": { "type": "string", "example": "Licença de uso {competencia}" }, "codigoTribNacional": { "type": "string", "example": "010501", "description": "cTribNac (LC 116, com desdobro)." }, "codigoTribMunicipal": { "type": "string", "nullable": true, "example": "001" }, "codigoNbs": { "type": "string", "example": "111032900" }, "aliquotaIss": { "type": "string", "nullable": true, "example": "5.00" }, "valorPadrao": { "type": "string", "nullable": true, "example": "750.00" }, "issRetido": { "type": "boolean", "description": "Legado: equivale a `issRetencao = sempre`." }, "codigo": { "type": "string", "nullable": true, "example": "LIC-01", "description": "Código do integrador (único por cliente)." }, "issRetencao": { "type": "string", "enum": [ "conforme_tomador", "sempre", "nunca" ] }, "exigibilidadeIss": { "type": "string", "nullable": true }, "issDetalhe": { "type": "object", "nullable": true, "additionalProperties": true }, "ibscbsCst": { "type": "string", "nullable": true }, "ibscbsCClassTrib": { "type": "string", "nullable": true }, "ibscbsIndOp": { "type": "string", "nullable": true }, "retIrrfAliquota": { "type": "string", "nullable": true }, "retCsrf": { "type": "boolean" }, "retPisAliquota": { "type": "string", "nullable": true }, "retCofinsAliquota": { "type": "string", "nullable": true }, "retCsllAliquota": { "type": "string", "nullable": true }, "retInssAliquota": { "type": "string", "nullable": true }, "deducaoPercentual": { "type": "string", "nullable": true }, "deducaoValor": { "type": "string", "nullable": true }, "pisCofinsRegime": { "type": "string", "enum": [ "empresa", "cumulativo", "nao_cumulativo" ], "description": "`empresa` = o regime do cliente na competência; `cumulativo`/`nao_cumulativo` só no Lucro Real." }, "inssMateriaisPercentual": { "type": "string", "nullable": true, "example": "30.00", "description": "Percentual de materiais/equipamentos fora da base do INSS (exclui `inssMateriaisValor`)." }, "inssMateriaisValor": { "type": "string", "nullable": true, "example": "100.00", "description": "Valor fixo de materiais/equipamentos fora da base do INSS." }, "natureza1234": { "type": "string", "nullable": true }, "ativo": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-10-23T14:32:10.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-10-23T14:32:10.000Z" }, "qtdRegras": { "type": "integer", "description": "Só na listagem: regras serviço×tomador do serviço." } }, "required": [ "id", "clienteId", "descricao", "codigoTribNacional", "codigoTribMunicipal", "codigoNbs", "aliquotaIss", "valorPadrao", "issRetido", "codigo", "issRetencao", "exigibilidadeIss", "issDetalhe", "ibscbsCst", "ibscbsCClassTrib", "ibscbsIndOp", "retIrrfAliquota", "retCsrf", "retPisAliquota", "retCofinsAliquota", "retCsllAliquota", "retInssAliquota", "deducaoPercentual", "deducaoValor", "pisCofinsRegime", "inssMateriaisPercentual", "inssMateriaisValor", "natureza1234", "ativo", "createdAt", "updatedAt" ] }, "ProblemaValidacaoResponse": { "type": "object", "properties": { "etapa": { "type": "string", "example": "tributacao", "enum": [ "schema", "tributacao", "emitente", "coerencia", "regra", "xml", "xsd" ] }, "campo": { "type": "string", "example": "servicos[0].aliquotaIss" }, "codigo": { "type": "string", "example": "ISS_SEM_ALIQUOTA" }, "mensagem": { "type": "string", "example": "Informe a alíquota do ISS no cadastro do serviço." }, "gravidade": { "type": "string", "enum": [ "erro", "aviso" ], "description": "Sem `gravidade` = erro." } }, "required": [ "etapa", "mensagem" ] }, "ValidacaoDpsResponse": { "type": "object", "properties": { "valido": { "type": "boolean", "description": "`true` quando só há avisos — a DPS pode ser emitida." }, "problemas": { "type": "array", "items": { "$ref": "#/components/schemas/ProblemaValidacaoResponse" } }, "numeroPrevisto": { "type": "number", "description": "Número que a DPS receberia (não é reservado)." }, "dpsId": { "type": "string" }, "xml": { "type": "string", "description": "XML da DPS sem assinatura e sem data/hora de emissão." }, "observacao": { "type": "string" }, "dps": { "type": "object", "additionalProperties": true, "description": "Forma por cadastros: a DPS resolvida — pode ser reenviada completa na emissão." }, "origens": { "type": "object", "description": "Só na forma por cadastros: para cada campo resolvido (ex.: `servicos[0].aliquotaIss`), de onde veio o valor.", "additionalProperties": { "$ref": "#/components/schemas/OrigemCampoResponse" } }, "avisos": { "type": "array", "items": { "$ref": "#/components/schemas/AvisoMotorResponse" } }, "pendencias": { "description": "Bloqueiam a emissão.", "type": "array", "items": { "$ref": "#/components/schemas/PendenciaMotorResponse" } }, "totais": { "$ref": "#/components/schemas/TotaisMotorResponse" }, "motorVersao": { "type": "string", "description": "Versão do motor e da tabela legal." }, "versaoTabelasIbsCbs": { "type": "string", "nullable": true, "description": "Versão das tabelas da calculadora oficial (null = cálculo local)." }, "versaoIbpt": { "type": "string", "nullable": true, "description": "Versão da tabela IBPT usada (null = tributos destacados)." } }, "required": [ "valido", "problemas" ] }, "SaudeResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "uptime": { "type": "number", "example": 5.85, "description": "Segundos desde o início do processo." }, "ts": { "type": "string", "format": "date-time" } }, "required": [ "status", "uptime", "ts" ] }, "VerificacaoSaudeResponse": { "type": "object", "properties": { "name": { "type": "string", "example": "postgres" }, "ok": { "type": "boolean" } }, "required": [ "name", "ok" ] }, "ProntidaoResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/VerificacaoSaudeResponse" } } }, "required": [ "status", "checks" ] }, "DpsEmissao": { "type": "object", "properties": { "externalRef": { "type": "string", "maxLength": 100 }, "serie": { "type": "string", "minLength": 1, "maxLength": 5 }, "competencia": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "ambiente": { "type": "string", "enum": [ "1", "2" ] }, "tipoEmitente": { "type": "string", "enum": [ "1", "2", "3" ] }, "motivoEmisTI": { "type": "string", "enum": [ "1", "2", "3", "4" ] }, "municipioEmissorIbge": { "type": "integer", "minimum": 1100000, "maximum": 5399999 }, "naturezaOperacao": { "type": "string", "enum": [ "tributacaoNoMunicipio", "tributacaoForaMunicipio", "imune", "exportacao", "suspensoJudicial", "suspensoAdministrativo" ] }, "regimeEspecial": { "type": "string", "nullable": true }, "prestador": { "type": "object", "properties": { "cnpj": { "type": "string", "minLength": 14, "maxLength": 14, "pattern": "^[0-9A-Z]{12}\\d{2}$" }, "cpf": { "type": "string", "minLength": 11, "maxLength": 11, "pattern": "^\\d{11}$" }, "im": { "type": "string", "maxLength": 30 }, "inscricaoMunicipal": { "type": "string", "maxLength": 30 }, "xNome": { "type": "string", "maxLength": 200 }, "opSimpleNacional": { "type": "string", "enum": [ "1", "2", "3" ] }, "regimeApuracaoSimpNac": { "type": "string", "enum": [ "1", "2", "3" ] }, "regimeEspecialTributacao": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "9" ] } } }, "intermediario": { "$ref": "#/components/schemas/TomadorDps" }, "servico": { "type": "object", "properties": { "codigoTribNacional": { "type": "string", "minLength": 1, "maxLength": 10 }, "codigoTribMun": { "type": "string", "maxLength": 20 }, "codigoNbs": { "type": "string", "maxLength": 20 }, "descricao": { "type": "string", "minLength": 1, "maxLength": 2000 }, "codigoInternoContribuinte": { "type": "string", "maxLength": 50 }, "informarAliquotaIss": { "type": "boolean" }, "localPrestacao": { "type": "object", "properties": { "municipioIbge": { "type": "integer", "minimum": 1100000, "maximum": 5399999 }, "paisIso2": { "type": "string", "minLength": 2, "maxLength": 2 } } }, "obra": { "type": "object", "properties": { "inscricaoImobiliaria": { "type": "string", "minLength": 1, "maxLength": 30 }, "codigoObra": { "type": "string", "minLength": 1, "maxLength": 30 }, "cib": { "type": "string", "minLength": 8, "maxLength": 8 }, "endereco": { "type": "object", "properties": { "cep": { "type": "string", "pattern": "^\\d{8}$" }, "exterior": { "type": "object", "properties": { "codigoPostal": { "type": "string", "minLength": 1, "maxLength": 11 }, "cidade": { "type": "string", "minLength": 1, "maxLength": 60 }, "estadoProvincia": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "codigoPostal", "cidade", "estadoProvincia" ] }, "logradouro": { "type": "string", "minLength": 1, "maxLength": 255 }, "numero": { "type": "string", "minLength": 1, "maxLength": 60 }, "complemento": { "type": "string", "maxLength": 156 }, "bairro": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "logradouro", "numero", "bairro" ] } } }, "evento": { "type": "object", "properties": { "nome": { "type": "string", "minLength": 1, "maxLength": 255 }, "dataInicio": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dataFim": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "identificacao": { "type": "string", "minLength": 1, "maxLength": 30 }, "endereco": { "type": "object", "properties": { "cep": { "type": "string", "pattern": "^\\d{8}$" }, "exterior": { "type": "object", "properties": { "codigoPostal": { "type": "string", "minLength": 1, "maxLength": 11 }, "cidade": { "type": "string", "minLength": 1, "maxLength": 60 }, "estadoProvincia": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "codigoPostal", "cidade", "estadoProvincia" ] }, "logradouro": { "type": "string", "minLength": 1, "maxLength": 255 }, "numero": { "type": "string", "minLength": 1, "maxLength": 60 }, "complemento": { "type": "string", "maxLength": 156 }, "bairro": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "logradouro", "numero", "bairro" ] } }, "required": [ "nome", "dataInicio", "dataFim" ] }, "comercioExterior": { "type": "object", "properties": { "modoPrestacao": { "type": "string", "enum": [ "0", "1", "2", "3", "4" ] }, "vinculo": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "9" ] }, "moeda": { "type": "string", "pattern": "^\\d{3}$" }, "valorMoeda": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "mecanismoApoioPrestador": { "type": "string", "pattern": "^\\d{2}$" }, "mecanismoApoioTomador": { "type": "string", "pattern": "^\\d{2}$" }, "movimentacaoTemporariaBens": { "type": "string", "enum": [ "0", "1", "2", "3" ] }, "numeroDI": { "type": "string", "minLength": 1, "maxLength": 12 }, "numeroRE": { "type": "string", "minLength": 1, "maxLength": 12 }, "enviarMdic": { "type": "string", "enum": [ "0", "1" ] } }, "required": [ "modoPrestacao", "vinculo", "moeda", "valorMoeda", "mecanismoApoioPrestador", "mecanismoApoioTomador", "movimentacaoTemporariaBens", "enviarMdic" ] } }, "required": [ "codigoTribNacional", "descricao" ] }, "substituicao": { "type": "object", "properties": { "chaveSubstituida": { "type": "string" }, "codigoMotivo": { "type": "string", "enum": [ "99", "01", "02", "03", "04", "05" ] }, "motivoLivre": { "type": "string", "minLength": 15, "maxLength": 255 } }, "required": [ "chaveSubstituida", "codigoMotivo" ] }, "tomador": { "$ref": "#/components/schemas/TomadorDps" }, "servicos": { "type": "array", "items": { "type": "object", "properties": { "codigoNbs": { "type": "string", "minLength": 1, "maxLength": 20 }, "codigoServicoMunicipal": { "type": "string", "maxLength": 20 }, "cnae": { "type": "string", "maxLength": 10 }, "descricao": { "type": "string", "minLength": 1, "maxLength": 2000 }, "quantidade": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "valorUnitario": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "valorTotal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "descontoIncondicionado": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "descontoCondicionado": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "issRetido": { "type": "boolean" }, "aliquotaIss": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } }, "required": [ "codigoNbs", "descricao", "quantidade", "valorUnitario", "valorTotal", "issRetido" ] }, "minItems": 1, "maxItems": 100 }, "tributacao": { "type": "object", "properties": { "iss": { "type": "object", "properties": { "valor": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "exigibilidade": { "type": "string", "enum": [ "exigivel", "naoIncidencia", "isencao", "exportacao", "imunidade", "suspensaoJudicial", "suspensaoAdministrativa" ] }, "municipioIncidenciaIbge": { "type": "integer", "minimum": 1100000, "maximum": 5399999 }, "paisResultado": { "type": "string", "minLength": 2, "maxLength": 2 }, "tipoImunidade": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5" ] }, "processoSuspensao": { "type": "string", "pattern": "^\\d{30}$" }, "beneficioMunicipal": { "type": "object", "properties": { "numero": { "type": "string", "pattern": "^\\d{14}$" }, "tipo": { "type": "string", "enum": [ "isencao", "aliquotaDiferenciada", "reducaoBaseCalculo" ] }, "reducaoValor": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "reducaoPercentual": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,2})?$" } }, "required": [ "numero" ] } }, "required": [ "valor", "exigibilidade" ] }, "ibsCbs": { "type": "object", "properties": { "classificacao": { "type": "string", "enum": [ "padrao", "reduzido", "monofasico", "imune", "isento", "suspenso" ] }, "baseCalculo": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "aliquotaIbs": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "aliquotaCbs": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "valorIbs": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "valorCbs": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "imune": { "type": "boolean" }, "is": { "type": "object", "properties": { "incidencia": { "type": "boolean" }, "baseCalculo": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "aliquota": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "valor": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } }, "required": [ "incidencia" ] }, "partilha": { "type": "object", "properties": { "uniao": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "estado": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "municipio": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } }, "required": [ "classificacao", "baseCalculo", "aliquotaIbs", "aliquotaCbs", "valorIbs", "valorCbs", "imune", "is" ] }, "totaisAproximados": { "anyOf": [ { "type": "object", "properties": { "tipo": { "enum": [ "valor" ] }, "federal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "estadual": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "municipal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } }, "required": [ "tipo", "federal", "estadual", "municipal" ] }, { "type": "object", "properties": { "tipo": { "enum": [ "percentual" ] }, "federal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "estadual": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "municipal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } }, "required": [ "tipo", "federal", "estadual", "municipal" ] } ] }, "federal": { "type": "object", "properties": { "pisCofins": { "type": "object", "properties": { "cst": { "type": "string", "enum": [ "49", "50", "51", "52", "53", "54", "55", "56", "60", "61", "62", "63", "64", "65", "66", "67", "70", "71", "72", "73", "74", "75", "98", "99", "00", "01", "02", "03", "04", "05", "06", "07", "08", "09" ] }, "baseCalculo": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "aliquotaPis": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "aliquotaCofins": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "valorPis": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "valorCofins": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "tipoRetencao": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8", "9" ] } }, "required": [ "cst" ] }, "retencaoCp": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "retencaoIrrf": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "retencaoCsll": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } }, "required": [ "iss", "ibsCbs" ] }, "informacoesComplementares": { "type": "string", "maxLength": 2000 }, "deducaoReducao": { "type": "object", "properties": { "percentual": { "type": "string", "pattern": "^\\d{1,3}\\.\\d{2}$" }, "valor": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } }, "rtc": { "type": "object", "properties": { "finalidade": { "enum": [ "0" ] }, "consumoPessoal": { "type": "string", "enum": [ "0", "1" ] }, "codigoIndicadorOperacao": { "type": "string", "pattern": "^\\d{6}$" }, "tipoOperacao": { "type": "string", "enum": [ "1", "2", "3", "4", "5" ] }, "tipoEnteGovernamental": { "type": "string", "enum": [ "1", "2", "3", "4" ] }, "nfseReferenciadas": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]{9}[0-9A-Z]{14}[0-9]{27}$" }, "maxItems": 99 }, "destinatario": { "$ref": "#/components/schemas/TomadorDps" }, "cst": { "type": "string", "pattern": "^\\d{3}$" }, "cClassTrib": { "type": "string", "pattern": "^\\d{6}$" }, "cCredPres": { "type": "string", "pattern": "^\\d{2}$" }, "tributacaoRegular": { "type": "object", "properties": { "cst": { "type": "string", "pattern": "^\\d{3}$" }, "cClassTrib": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "cst", "cClassTrib" ] }, "diferimento": { "type": "object", "properties": { "pDifUF": { "type": "string" }, "pDifMun": { "type": "string" }, "pDifCBS": { "type": "string" } }, "required": [ "pDifUF", "pDifMun", "pDifCBS" ] }, "imovel": { "type": "object", "properties": { "inscricaoImobiliaria": { "type": "string", "minLength": 1, "maxLength": 30 }, "cib": { "type": "string", "minLength": 8, "maxLength": 8 }, "endereco": { "type": "object", "properties": { "cep": { "type": "string", "pattern": "^\\d{8}$" }, "exterior": { "type": "object", "properties": { "codigoPostal": { "type": "string", "minLength": 1, "maxLength": 11 }, "cidade": { "type": "string", "minLength": 1, "maxLength": 60 }, "estadoProvincia": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "codigoPostal", "cidade", "estadoProvincia" ] }, "logradouro": { "type": "string", "minLength": 1, "maxLength": 255 }, "numero": { "type": "string", "minLength": 1, "maxLength": 60 }, "complemento": { "type": "string", "maxLength": 156 }, "bairro": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "logradouro", "numero", "bairro" ] }, "municipioIbge": { "type": "integer", "minimum": 1100000, "maximum": 5399999 }, "locacao": { "type": "object", "properties": { "percentualCopropriedade": { "type": "string", "pattern": "^\\d{1,3}\\.\\d{2}$" }, "valorTotalOperacao": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "descontoIncondicionadoTotal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "descontoCondicionadoTotal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "vencimentoOriginal": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "percentualCopropriedade", "valorTotalOperacao" ] }, "ajustes": { "type": "array", "items": { "type": "object", "properties": { "tipo": { "type": "string", "enum": [ "99", "01", "02", "03", "04" ] }, "descricao": { "type": "string", "minLength": 1, "maxLength": 150 }, "valor": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } }, "required": [ "tipo", "valor" ] }, "maxItems": 10 } } }, "bensMoveis": { "type": "array", "items": { "type": "object", "properties": { "ncm": { "type": "string", "pattern": "^\\d{8}$" }, "descricao": { "type": "string", "minLength": 1, "maxLength": 150 }, "quantidade": { "type": "integer", "minimum": 1, "maximum": 999 } }, "required": [ "ncm", "descricao", "quantidade" ] }, "minItems": 1, "maxItems": 1000 } }, "required": [ "codigoIndicadorOperacao", "cst", "cClassTrib" ] }, "substituiChaveAcesso": { "type": "string" }, "confirmarMunicipioNaoAderente": { "type": "boolean", "description": "Confirma a emissão em município que só compartilha com o ADN (Lucro Presumido/Real); sem isso a emissão responde 422 `nfse.confirmacao_municipio_nao_aderente`. Vale para esta chamada." } }, "required": [ "serie", "competencia", "prestador", "tomador", "servicos", "tributacao" ] }, "TomadorDps": { "type": "object", "properties": { "tipoDoc": { "type": "string", "enum": [ "CPF", "CNPJ", "EXTERIOR", "NAO_INFORMADO" ] }, "documento": { "type": "string", "minLength": 1, "maxLength": 20 }, "inscricaoEstadual": { "type": "string", "maxLength": 20 }, "inscricaoMunicipal": { "type": "string", "maxLength": 20 }, "nome": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email" }, "telefone": { "type": "string", "maxLength": 20 }, "endereco": { "type": "object", "properties": { "cep": { "type": "string", "minLength": 8, "maxLength": 8, "pattern": "^\\d{8}$" }, "logradouro": { "type": "string", "minLength": 1, "maxLength": 150 }, "numero": { "type": "string", "minLength": 1, "maxLength": 20 }, "complemento": { "type": "string", "maxLength": 80 }, "bairro": { "type": "string", "minLength": 1, "maxLength": 80 }, "municipioIbge": { "type": "integer", "minimum": 1100000, "maximum": 5399999 }, "uf": { "type": "string", "enum": [ "AC", "AL", "AP", "AM", "BA", "CE", "DF", "ES", "GO", "MA", "MT", "MS", "MG", "PA", "PB", "PR", "PE", "PI", "RJ", "RN", "RS", "RO", "RR", "SC", "SP", "SE", "TO" ] }, "paisIso2": { "type": "string", "minLength": 2, "maxLength": 2, "default": "BR" } }, "required": [ "cep", "logradouro", "numero", "bairro", "municipioIbge", "uf" ] } }, "required": [ "tipoDoc", "nome" ] }, "EmissaoPorCadastros": { "type": "object", "properties": { "servicoId": { "type": "string", "format": "uuid" }, "servicoCodigo": { "type": "string", "minLength": 1, "maxLength": 60 }, "tomadorId": { "type": "string", "format": "uuid" }, "tomadorCodigo": { "type": "string", "minLength": 1, "maxLength": 60 }, "tomador": { "$ref": "#/components/schemas/TomadorDps" }, "valor": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "descontoIncondicionado": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "inssMateriais": { "type": "object", "properties": { "valor": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "percentual": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "additionalProperties": false }, "competencia": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "descricao": { "type": "string", "minLength": 1, "maxLength": 2000 }, "informacoesComplementares": { "type": "string", "maxLength": 2000 }, "externalRef": { "type": "string", "maxLength": 100 }, "servico": { "type": "object", "properties": { "codigoTribMun": { "type": "string", "maxLength": 20 }, "localPrestacao": { "type": "object", "properties": { "municipioIbge": { "type": "integer", "minimum": 1100000, "maximum": 5399999 }, "paisIso2": { "type": "string", "minLength": 2, "maxLength": 2 } } }, "obra": { "type": "object", "properties": { "inscricaoImobiliaria": { "type": "string", "minLength": 1, "maxLength": 30 }, "codigoObra": { "type": "string", "minLength": 1, "maxLength": 30 }, "cib": { "type": "string", "minLength": 8, "maxLength": 8 }, "endereco": { "type": "object", "properties": { "cep": { "type": "string", "pattern": "^\\d{8}$" }, "exterior": { "type": "object", "properties": { "codigoPostal": { "type": "string", "minLength": 1, "maxLength": 11 }, "cidade": { "type": "string", "minLength": 1, "maxLength": 60 }, "estadoProvincia": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "codigoPostal", "cidade", "estadoProvincia" ] }, "logradouro": { "type": "string", "minLength": 1, "maxLength": 255 }, "numero": { "type": "string", "minLength": 1, "maxLength": 60 }, "complemento": { "type": "string", "maxLength": 156 }, "bairro": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "logradouro", "numero", "bairro" ] } } }, "evento": { "type": "object", "properties": { "nome": { "type": "string", "minLength": 1, "maxLength": 255 }, "dataInicio": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dataFim": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "identificacao": { "type": "string", "minLength": 1, "maxLength": 30 }, "endereco": { "type": "object", "properties": { "cep": { "type": "string", "pattern": "^\\d{8}$" }, "exterior": { "type": "object", "properties": { "codigoPostal": { "type": "string", "minLength": 1, "maxLength": 11 }, "cidade": { "type": "string", "minLength": 1, "maxLength": 60 }, "estadoProvincia": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "codigoPostal", "cidade", "estadoProvincia" ] }, "logradouro": { "type": "string", "minLength": 1, "maxLength": 255 }, "numero": { "type": "string", "minLength": 1, "maxLength": 60 }, "complemento": { "type": "string", "maxLength": 156 }, "bairro": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "logradouro", "numero", "bairro" ] } }, "required": [ "nome", "dataInicio", "dataFim" ] }, "comercioExterior": { "type": "object", "properties": { "modoPrestacao": { "type": "string", "enum": [ "0", "1", "2", "3", "4" ] }, "vinculo": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "9" ] }, "moeda": { "type": "string", "pattern": "^\\d{3}$" }, "valorMoeda": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "mecanismoApoioPrestador": { "type": "string", "pattern": "^\\d{2}$" }, "mecanismoApoioTomador": { "type": "string", "pattern": "^\\d{2}$" }, "movimentacaoTemporariaBens": { "type": "string", "enum": [ "0", "1", "2", "3" ] }, "numeroDI": { "type": "string", "minLength": 1, "maxLength": 12 }, "numeroRE": { "type": "string", "minLength": 1, "maxLength": 12 }, "enviarMdic": { "type": "string", "enum": [ "0", "1" ] } }, "required": [ "modoPrestacao", "vinculo", "moeda", "valorMoeda", "mecanismoApoioPrestador", "mecanismoApoioTomador", "movimentacaoTemporariaBens", "enviarMdic" ] }, "informarAliquotaIss": { "type": "boolean" }, "codigoInternoContribuinte": { "type": "string", "maxLength": 50 } }, "additionalProperties": false }, "servicos": { "type": "array", "items": { "type": "object", "properties": { "aliquotaIss": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "issRetido": { "type": "boolean" } }, "additionalProperties": false }, "maxItems": 1 }, "intermediario": { "$ref": "#/components/schemas/TomadorDps" }, "substituicao": { "type": "object", "properties": { "chaveSubstituida": { "type": "string" }, "codigoMotivo": { "type": "string", "enum": [ "99", "01", "02", "03", "04", "05" ] }, "motivoLivre": { "type": "string", "minLength": 15, "maxLength": 255 } }, "required": [ "chaveSubstituida", "codigoMotivo" ] }, "deducaoReducao": { "type": "object", "properties": { "percentual": { "type": "string", "pattern": "^\\d{1,3}\\.\\d{2}$" }, "valor": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } }, "rtc": { "type": "object", "properties": { "codigoIndicadorOperacao": { "type": "string", "pattern": "^\\d{6}$" }, "cst": { "type": "string", "pattern": "^\\d{3}$" }, "cClassTrib": { "type": "string", "pattern": "^\\d{6}$" }, "consumoPessoal": { "type": "string", "enum": [ "0", "1" ] }, "tipoOperacao": { "type": "string", "enum": [ "1", "2", "3", "4", "5" ] }, "tipoEnteGovernamental": { "type": "string", "enum": [ "1", "2", "3", "4" ] }, "nfseReferenciadas": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]{9}[0-9A-Z]{14}[0-9]{27}$" }, "maxItems": 99 }, "destinatario": { "$ref": "#/components/schemas/TomadorDps" }, "cCredPres": { "type": "string", "pattern": "^\\d{2}$" }, "tributacaoRegular": { "type": "object", "properties": { "cst": { "type": "string", "pattern": "^\\d{3}$" }, "cClassTrib": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "cst", "cClassTrib" ] }, "diferimento": { "type": "object", "properties": { "pDifUF": { "type": "string" }, "pDifMun": { "type": "string" }, "pDifCBS": { "type": "string" } }, "required": [ "pDifUF", "pDifMun", "pDifCBS" ] }, "imovel": { "type": "object", "properties": { "inscricaoImobiliaria": { "type": "string", "minLength": 1, "maxLength": 30 }, "cib": { "type": "string", "minLength": 8, "maxLength": 8 }, "endereco": { "type": "object", "properties": { "cep": { "type": "string", "pattern": "^\\d{8}$" }, "exterior": { "type": "object", "properties": { "codigoPostal": { "type": "string", "minLength": 1, "maxLength": 11 }, "cidade": { "type": "string", "minLength": 1, "maxLength": 60 }, "estadoProvincia": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "codigoPostal", "cidade", "estadoProvincia" ] }, "logradouro": { "type": "string", "minLength": 1, "maxLength": 255 }, "numero": { "type": "string", "minLength": 1, "maxLength": 60 }, "complemento": { "type": "string", "maxLength": 156 }, "bairro": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "logradouro", "numero", "bairro" ] }, "municipioIbge": { "type": "integer", "minimum": 1100000, "maximum": 5399999 }, "locacao": { "type": "object", "properties": { "percentualCopropriedade": { "type": "string", "pattern": "^\\d{1,3}\\.\\d{2}$" }, "valorTotalOperacao": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "descontoIncondicionadoTotal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "descontoCondicionadoTotal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "vencimentoOriginal": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "percentualCopropriedade", "valorTotalOperacao" ] }, "ajustes": { "type": "array", "items": { "type": "object", "properties": { "tipo": { "type": "string", "enum": [ "99", "01", "02", "03", "04" ] }, "descricao": { "type": "string", "minLength": 1, "maxLength": 150 }, "valor": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } }, "required": [ "tipo", "valor" ] }, "maxItems": 10 } } } }, "additionalProperties": false }, "tributacao": { "type": "object", "properties": { "iss": { "type": "object", "properties": { "exigibilidade": { "type": "string", "enum": [ "exigivel", "naoIncidencia", "isencao", "exportacao", "imunidade", "suspensaoJudicial", "suspensaoAdministrativa" ] } }, "additionalProperties": false }, "federal": { "type": "object", "properties": { "pisCofins": { "type": "object", "properties": { "cst": { "type": "string", "enum": [ "49", "50", "51", "52", "53", "54", "55", "56", "60", "61", "62", "63", "64", "65", "66", "67", "70", "71", "72", "73", "74", "75", "98", "99", "00", "01", "02", "03", "04", "05", "06", "07", "08", "09" ] }, "baseCalculo": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "aliquotaPis": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "aliquotaCofins": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "valorPis": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "valorCofins": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "tipoRetencao": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8", "9" ] } }, "additionalProperties": false }, "retencaoCp": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "retencaoIrrf": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "retencaoCsll": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } }, "additionalProperties": false }, "ibsCbs": { "type": "object", "properties": { "classificacao": { "type": "string", "enum": [ "imune", "isento" ] }, "imune": { "type": "boolean" } }, "additionalProperties": false }, "totaisAproximados": { "anyOf": [ { "type": "object", "properties": { "tipo": { "enum": [ "valor" ] }, "federal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "estadual": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "municipal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } }, "required": [ "tipo", "federal", "estadual", "municipal" ] }, { "type": "object", "properties": { "tipo": { "enum": [ "percentual" ] }, "federal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "estadual": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "municipal": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } }, "required": [ "tipo", "federal", "estadual", "municipal" ] } ] } }, "additionalProperties": false }, "ajustes": { "type": "array", "items": { "type": "object", "properties": { "campo": { "type": "string", "enum": [ "servicos[0].aliquotaIss", "servicos[0].issRetido", "tributacao.iss.exigibilidade", "tributacao.federal.pisCofins.cst", "tributacao.federal.pisCofins.aliquotaPis", "tributacao.federal.pisCofins.aliquotaCofins", "tributacao.federal.pisCofins.valorPis", "tributacao.federal.pisCofins.valorCofins", "tributacao.federal.retencaoIrrf", "tributacao.federal.retencaoCsll", "tributacao.federal.pisCofins.tipoRetencao", "tributacao.federal.retencaoCp", "rtc.cst", "rtc.cClassTrib", "rtc.codigoIndicadorOperacao" ] }, "valor": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "boolean" } ] }, "motivo": { "type": "string", "maxLength": 255 } }, "required": [ "campo", "valor" ], "additionalProperties": false }, "maxItems": 30 }, "confirmarMunicipioNaoAderente": { "type": "boolean", "description": "Confirma a emissão em município que só compartilha com o ADN (Lucro Presumido/Real); sem isso a emissão responde 422 `nfse.confirmacao_municipio_nao_aderente`. Vale para esta chamada." } }, "required": [ "competencia" ], "additionalProperties": false }, "WebhookEntrega": { "type": "object", "required": [ "id", "type", "createdAt", "data" ], "properties": { "id": { "type": "string", "maxLength": 40, "pattern": "^(evt|test)_[0-9A-HJKMNP-TV-Z]{26}$", "description": "Id único da entrega (`evt_` + ULID; `test_` + ULID no teste manual), o mesmo nas retentativas e no reenvio — use para deduplicar (a mesma entrega pode chegar mais de uma vez). Trate como opaco. Entregas criadas antes de 07/10/2026 mantêm o formato antigo `evt___`.", "example": "evt_01K6Z8M0S5Q4V7N2D3E9F1G2H3" }, "type": { "type": "string", "enum": [ "nfse.authorized", "nfse.rejected", "nfse.cancelled", "nfse.replaced", "nfse.event.failed", "dfe.received", "nfe.received", "nfe.cancelled", "nfe.manifestation.registered", "nfe.manifestation.rejected", "nfe.emitida.authorized", "nfe.emitida.rejected", "nfe.emitida.denied", "nfe.emitida.cancelled", "nfe.emitida.corrected", "nfe.inutilizacao.registered", "nfe.emitida.contingency", "nfe.contingencia.activated", "nfe.contingencia.deactivated", "cert.expiring", "cert.expired", "cobranca.gerada", "cobranca.paga", "cobranca.vencida", "cobranca.cancelada", "cobranca.estornada", "pedido.criado", "pedido.atualizado", "webhook.test" ], "example": "nfse.authorized" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-10-05T13:42:01.000Z" }, "data": { "type": "object", "description": "Dados do evento. Sempre traz `tenantId` e, quando houver, `empresaId` (cliente emitente); os demais campos dependem do tipo (ex.: `chaveAcesso` nas notas, `nsu` no DF-e).", "additionalProperties": true, "example": { "tenantId": "00000000-0000-4000-8000-000000000001", "empresaId": "00000000-0000-4000-8000-000000000002", "chaveAcesso": "35503082212345678000195000000000000126101234567895" } } } } } }, "x-webhooks": { "evento-nfse": { "post": { "summary": "Entrega de evento (POST na URL cadastrada)", "description": "A plataforma faz `POST` na URL do webhook para cada evento assinado. Responda **2xx em até 10 s**;\nredirecionamentos (3xx) não são seguidos e contam como falha. São 6 tentativas no total, com esperas de\n1 min → 5 min → 30 min → 2 h → 12 h entre elas; depois a entrega fica `dead` e pode ser reenviada por\n`POST /v1/webhooks/entregas/{entregaId}/retry`.\n\n**Assinatura:** `X-Webhook-Signature: sha256=` = HMAC-SHA256 do segredo (`whsec_…`, exibido só na criação)\nsobre `\".\"`. Recuse timestamps com mais de 5 minutos de diferença\n(anti-replay) e compare em tempo constante.", "parameters": [ { "name": "X-Webhook-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Id do webhook cadastrado." }, { "name": "X-Webhook-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "nfse.authorized", "nfse.rejected", "nfse.cancelled", "nfse.replaced", "nfse.event.failed", "dfe.received", "nfe.received", "nfe.cancelled", "nfe.manifestation.registered", "nfe.manifestation.rejected", "nfe.emitida.authorized", "nfe.emitida.rejected", "nfe.emitida.denied", "nfe.emitida.cancelled", "nfe.emitida.corrected", "nfe.inutilizacao.registered", "nfe.emitida.contingency", "nfe.contingencia.activated", "nfe.contingencia.deactivated", "cert.expiring", "cert.expired", "cobranca.gerada", "cobranca.paga", "cobranca.vencida", "cobranca.cancelada", "cobranca.estornada", "pedido.criado", "pedido.atualizado", "webhook.test" ] } }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Epoch em segundos." }, { "name": "X-Webhook-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=`" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEntrega" } } } }, "responses": { "200": { "description": "Recebido (qualquer 2xx)." } } } } } }