From 405deccb471ae2413051760b891aaca63d19e315 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Eduardo?= Date: Wed, 11 Nov 2026 14:50:31 -0300 Subject: [PATCH 1/2] =?UTF-8?q?docs:=2010=20consultas=20gr=C3=A1tis=20vale?= =?UTF-8?q?m=20para=20toda=20consulta=20avulsa?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- FiscalAPI.postman_collection.json | 2 +- README.md | 2 +- openapi-publico.json | 26 +++++++++++++------------- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/FiscalAPI.postman_collection.json b/FiscalAPI.postman_collection.json index dad92a2..5eafe0b 100644 --- a/FiscalAPI.postman_collection.json +++ b/FiscalAPI.postman_collection.json @@ -2,7 +2,7 @@ "info": { "_postman_id": "a502c70e-5ed7-54dd-9642-eda948b8f723", "name": "FiscalAPI", - "description": "API REST de consultas fiscais e cadastrais do Brasil, com foco no agronegócio: inscrição estadual nas 27 UFs, CNPJ, certidões estaduais e federais, XML de NF-e por chave, imóveis rurais (SIGEF e CNIR) e perfil consolidado do produtor rural. Respostas em JSON.\n\n**Autenticação:** envie sua chave no header `X-API-Key` (formato `fapi_...`). Crie a conta e copie a chave em https://app.fiscalapi.com.br. Nunca exponha a chave no front-end.\n\n**Cobrança:** cada consulta com dado consome créditos do plano (1 na maioria; 3 no CNPJ ao vivo; NF-e conforme o plano). Erros não são cobrados. Erros da origem do dado vêm com HTTP 200 em `source_status` (também não cobrados).\n\n**Limites:** franquia mensal por conta e limite de requisições por minuto conforme o plano (Lite 5, Starter 20, Pro 60, Enterprise 120). Ao exceder: HTTP 402 `LIMITE_ATINGIDO` (saldo) ou HTTP 429 `RATE_LIMIT_EXCEEDED` (com `Retry-After`).\n\n**Erros:** formato RFC 7807 (`application/problem+json`) com `title` = código do erro e `request_id` para o suporte.\n\nDocumentação completa: https://docs.fiscalapi.com.br\n\n## Como usar\n1. Em **Variables** da coleção, cole sua chave em `apiKey` (fica só no seu Postman).\n2. Abra uma pasta, escolha a requisição e clique em **Send**.\n3. Veja respostas de exemplo em **Examples** de cada requisição.\n\nOs exemplos usam documentos fictícios (CNPJ 12.345.678/0001-95). Troque pelo documento que você quer consultar.", + "description": "API REST de consultas fiscais e cadastrais do Brasil, com foco no agronegócio: inscrição estadual nas 27 UFs, CNPJ, certidões estaduais e federais, XML de NF-e por chave, imóveis rurais (SIGEF e CNIR) e perfil consolidado do produtor rural. Respostas em JSON.\n\n**Autenticação:** envie sua chave no header `X-API-Key` (formato `fapi_...`). Crie a conta e copie a chave em https://app.fiscalapi.com.br. Nunca exponha a chave no front-end.\n\n**Cobrança:** cada consulta com dado consome créditos do plano (1 na maioria; 3 no CNPJ ao vivo; NF-e conforme o plano). Erros não são cobrados. Erros da origem do dado vêm com HTTP 200 em `source_status` (também não cobrados).\n\n**Grátis:** conta que nunca assinou, com e-mail confirmado e sem recarga, tem 10 consultas grátis por mês em qualquer consulta avulsa, no painel e pela API (cada consulta entregue gasta 1), e mais 10 XML de NF-e com certificado. Ficam fora a NF-e sem certificado, as consultas em todos os estados (IE ou CND) e todas as certidões de uma vez. Quando acabam, o 402 traz `free_queries_used` e `free_queries_limit`.\n\n**Limites:** franquia mensal por conta e limite de requisições por minuto conforme o plano (Lite 5, Starter 20, Pro 60, Enterprise 120). Ao exceder: HTTP 402 `LIMITE_ATINGIDO` (saldo) ou HTTP 429 `RATE_LIMIT_EXCEEDED` (com `Retry-After`).\n\n**Erros:** formato RFC 7807 (`application/problem+json`) com `title` = código do erro e `request_id` para o suporte.\n\nDocumentação completa: https://docs.fiscalapi.com.br\n\n## Como usar\n1. Em **Variables** da coleção, cole sua chave em `apiKey` (fica só no seu Postman).\n2. Abra uma pasta, escolha a requisição e clique em **Send**.\n3. Veja respostas de exemplo em **Examples** de cada requisição.\n\nOs exemplos usam documentos fictícios (CNPJ 12.345.678/0001-95). Troque pelo documento que você quer consultar.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { diff --git a/README.md b/README.md index 0343f37..c9f79c9 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ A coleção também está publicada no Postman: [FiscalAPI na Postman API Networ 3. Na coleção, abra **Variables** e cole a chave em `apiKey`, na coluna *Current value*. 4. Envie qualquer requisição. A chave vai no cabeçalho `X-API-Key`. -Conta que nunca assinou plano, com e-mail confirmado e sem recarga, tem 10 consultas grátis por mês, no painel e pela API: IE em um estado (`/api/consultar`) e CNPJ (`/api/consultar-cnpj`). Não valem para IE em todos os estados nem para CNPJ ao vivo. Depois disso, é preciso plano ou saldo: a API responde `402`. Sem chave, `403` (`API_KEY_ERROR`). Planos, limites e consumo de créditos estão na [documentação](https://docs.fiscalapi.com.br). +Conta que nunca assinou plano, com e-mail confirmado e sem recarga, tem 10 consultas grátis por mês, no painel e pela API, em qualquer consulta avulsa (IE em um estado, CNPJ inclusive ao vivo, Simples Nacional, NFS-e, certidões, CNIR, SIGEF e as demais). Cada consulta entregue gasta 1 das 10; erro não gasta. Ficam fora a NF-e sem certificado, a IE e a CND em todos os estados (`/api/consultar-ie-todos`, `/api/consultar-cnd-todos`) e todas as certidões de uma vez (`/api/certidoes-todas`). À parte, 10 XML de NF-e com certificado por mês. Fora disso, ou depois das 10, é preciso plano ou saldo: a API responde `402` (`LIMITE_ATINGIDO`; quando acabam as grátis, com `free_queries_used` e `free_queries_limit`). Sem chave, `403` (`API_KEY_ERROR`). Planos, limites e consumo de créditos estão na [documentação](https://docs.fiscalapi.com.br). ## SDKs diff --git a/openapi-publico.json b/openapi-publico.json index 82fd97a..f5dda1f 100644 --- a/openapi-publico.json +++ b/openapi-publico.json @@ -2,7 +2,7 @@ "openapi": "3.1.0", "info": { "title": "FiscalAPI", - "description": "API REST da FiscalAPI para consultar inscrição estadual (IE) nos 27 estados, CNPJ, certidões negativas estaduais e federais, XML de NF-e pela chave de acesso, NFS-e do padrão nacional pela chave de acesso, imóveis rurais (CNIR e SIGEF), Simples Nacional, status da SEFAZ e o catálogo de rejeições da NF-e.\n\nAutenticação: envie a sua chave no cabeçalho `X-API-Key`. A chave é criada no painel (app.fiscalapi.com.br); sem ela, ou com chave inválida, a resposta é 403.\n\nCobrança: as consultas usam o saldo do plano. Conta que nunca assinou, com e-mail confirmado, tem 10 consultas grátis por mês de IE (em um estado) e de CNPJ, somadas com as do painel. O resto pede plano ou saldo, e a chamada sem saldo devolve 402. Limite por minuto conforme o plano; acima dele, 429 com o cabeçalho Retry-After.\n\nDocumentação completa: https://docs.fiscalapi.com.br", + "description": "API REST da FiscalAPI para consultar inscrição estadual (IE) nos 27 estados, CNPJ, certidões negativas estaduais e federais, XML de NF-e pela chave de acesso, NFS-e do padrão nacional pela chave de acesso, imóveis rurais (CNIR e SIGEF), Simples Nacional, status da SEFAZ e o catálogo de rejeições da NF-e.\n\nAutenticação: envie a sua chave no cabeçalho `X-API-Key`. A chave é criada no painel (app.fiscalapi.com.br); sem ela, ou com chave inválida, a resposta é 403.\n\nCobrança: as consultas usam o saldo do plano. Conta que nunca assinou, com e-mail confirmado, tem 10 consultas grátis por mês em qualquer consulta avulsa, somadas com as do painel, e mais 10 XML de NF-e com certificado. Não entram no grátis a NF-e sem certificado e as consultas em todos os estados ou de todas as certidões de uma vez. O resto pede plano ou saldo, e a chamada sem saldo devolve 402. Limite por minuto conforme o plano; acima dele, 429 com o cabeçalho Retry-After.\n\nDocumentação completa: https://docs.fiscalapi.com.br", "version": "1.0.0" }, "servers": [ @@ -470,7 +470,7 @@ } }, "402": { - "description": "Saldo insuficiente para esta consulta. Assine um plano ou recarregue.", + "description": "Saldo insuficiente para esta consulta (ou cota grátis do mês usada). Assine um plano ou recarregue.", "content": { "application/json": { "schema": { @@ -600,7 +600,7 @@ } }, "402": { - "description": "Saldo insuficiente para esta consulta. Assine um plano ou recarregue.", + "description": "Saldo insuficiente para esta consulta (ou cota grátis do mês usada). Assine um plano ou recarregue.", "content": { "application/json": { "schema": { @@ -838,7 +838,7 @@ } }, "402": { - "description": "Saldo insuficiente para esta consulta. Assine um plano ou recarregue.", + "description": "Saldo insuficiente para esta consulta (ou cota grátis do mês usada). Assine um plano ou recarregue.", "content": { "application/json": { "schema": { @@ -969,7 +969,7 @@ } }, "402": { - "description": "Saldo insuficiente para esta consulta. Assine um plano ou recarregue.", + "description": "Saldo insuficiente para esta consulta (ou cota grátis do mês usada). Assine um plano ou recarregue.", "content": { "application/json": { "schema": { @@ -1088,7 +1088,7 @@ } }, "402": { - "description": "Saldo insuficiente para esta consulta. Assine um plano ou recarregue.", + "description": "Saldo insuficiente para esta consulta (ou cota grátis do mês usada). Assine um plano ou recarregue.", "content": { "application/json": { "schema": { @@ -1334,7 +1334,7 @@ } }, "402": { - "description": "Saldo insuficiente para esta consulta. Assine um plano ou recarregue.", + "description": "Saldo insuficiente para esta consulta (ou cota grátis do mês usada). Assine um plano ou recarregue.", "content": { "application/problem+json": { "schema": { @@ -1442,7 +1442,7 @@ } }, "402": { - "description": "Saldo insuficiente para esta consulta. Assine um plano ou recarregue.", + "description": "Saldo insuficiente para esta consulta (ou cota grátis do mês usada). Assine um plano ou recarregue.", "content": { "application/problem+json": { "schema": { @@ -1581,7 +1581,7 @@ } }, "402": { - "description": "Saldo insuficiente para esta consulta. Assine um plano ou recarregue.", + "description": "Saldo insuficiente para esta consulta (ou cota grátis do mês usada). Assine um plano ou recarregue.", "content": { "application/problem+json": { "schema": { @@ -1701,7 +1701,7 @@ } }, "402": { - "description": "Saldo insuficiente para esta consulta. Assine um plano ou recarregue.", + "description": "Saldo insuficiente para esta consulta (ou cota grátis do mês usada). Assine um plano ou recarregue.", "content": { "application/problem+json": { "schema": { @@ -1796,7 +1796,7 @@ } }, "402": { - "description": "Saldo insuficiente para esta consulta. Assine um plano ou recarregue.", + "description": "Saldo insuficiente para esta consulta (ou cota grátis do mês usada). Assine um plano ou recarregue.", "content": { "application/problem+json": { "schema": { @@ -1942,7 +1942,7 @@ "NFS-e" ], "summary": "Consultar NFS-e por chave de acesso", - "description": "Consulta uma NFS-e do padrão nacional a partir da chave de acesso (50 dígitos), sem certificado digital. Retorna emitente, tomador, serviço, tributação municipal e federal e a situação de geração (`situacao`: 100 gerada, 101 de substituição, 102 por decisão judicial, 103 avulsa); `situacao` não indica cancelamento. Com `danfse=true`, inclui o PDF do DANFSe em base64 (`danfse_pdf_base64`). Uma consulta nova leva de 30 a 60 segundos; a mesma chave consultada de novo em até 24 h volta do cache na hora (`cached: true`) e também é cobrada. Cobra só a NFS-e entregue (mesmo preço do XML de NF-e sem certificado). Chave inválida, nota não encontrada e falha não são cobradas. Não entra nas consultas grátis.", + "description": "Consulta uma NFS-e do padrão nacional a partir da chave de acesso (50 dígitos), sem certificado digital. Retorna emitente, tomador, serviço, tributação municipal e federal e a situação de geração (`situacao`: 100 gerada, 101 de substituição, 102 por decisão judicial, 103 avulsa); `situacao` não indica cancelamento. Com `danfse=true`, inclui o PDF do DANFSe em base64 (`danfse_pdf_base64`). Uma consulta nova leva de 30 a 60 segundos; a mesma chave consultada de novo em até 24 h volta do cache na hora (`cached: true`) e também é cobrada. Cobra só a NFS-e entregue (mesmo preço do XML de NF-e sem certificado). Chave inválida, nota não encontrada e falha não são cobradas. Conta sem plano pode usar as consultas grátis do mês.", "operationId": "consultar_nfse_endpoint_api_consultar_nfse_get", "parameters": [ { @@ -1998,7 +1998,7 @@ } }, "402": { - "description": "Saldo insuficiente para esta consulta. Assine um plano ou recarregue.", + "description": "Saldo insuficiente para esta consulta (ou cota grátis do mês usada). Assine um plano ou recarregue.", "content": { "application/problem+json": { "schema": { From ecf099d220c1bb05857a9e43f20730e97aa9860f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Eduardo?= Date: Wed, 11 Nov 2026 15:09:34 -0300 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20OpenAPI=20com=20a=20valida=C3=A7?= =?UTF-8?q?=C3=A3o=20de=20CND=20nas=20consultas=20gr=C3=A1tis?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- openapi-publico.json | 275 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 275 insertions(+) diff --git a/openapi-publico.json b/openapi-publico.json index f5dda1f..22e6194 100644 --- a/openapi-publico.json +++ b/openapi-publico.json @@ -784,6 +784,125 @@ } } }, + "/api/validar-cnd": { + "get": { + "tags": [ + "CND Estadual" + ], + "summary": "Validar CND Estadual pelo código da certidão", + "description": "Confere na fonte uma certidão estadual já emitida, pelo número ou código de autenticidade impresso nela. Use quando o órgão não emite a certidão por CPF/CNPJ para terceiros: RJ (empresa inscrita no ICMS) e MG (certidão positiva). Devolve se a certidão é autêntica, se ainda vale, o tipo (negativa/positiva) e o PDF. Disponível para MG e RJ.", + "operationId": "validar_cnd_estadual_api_validar_cnd_get", + "parameters": [ + { + "name": "uf", + "in": "query", + "required": true, + "schema": { + "type": "string", + "description": "Sigla do estado da certidão: MG ou RJ", + "title": "Uf" + }, + "description": "Sigla do estado da certidão: MG ou RJ" + }, + { + "name": "codigo", + "in": "query", + "required": true, + "schema": { + "type": "string", + "description": "MG: código de autenticidade (32 caracteres). RJ: número da certidão (ex.: 2026.1.8937822-5) ou código de verificação de autenticidade (32 caracteres).", + "title": "Codigo" + }, + "description": "MG: código de autenticidade (32 caracteres). RJ: número da certidão (ex.: 2026.1.8937822-5) ou código de verificação de autenticidade (32 caracteres)." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CNDValidacaoResponse" + } + } + } + }, + "400": { + "description": "UF sem validação ou código em formato inválido", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErroProblema" + } + } + } + }, + "402": { + "description": "Saldo insuficiente para esta consulta (ou cota grátis do mês usada). Assine um plano ou recarregue.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErroLimite" + } + } + } + }, + "403": { + "description": "Chave ausente, inválida ou revogada.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErroProblema" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + }, + "429": { + "description": "Limite de requisições por minuto excedido. Veja o cabeçalho Retry-After.", + "headers": { + "Retry-After": { + "description": "Segundos até poder tentar de novo.", + "schema": { + "type": "integer" + } + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErroLimite" + } + }, + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErroProblema" + } + } + } + }, + "500": { + "description": "Erro interno do servidor", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErroProblema" + } + } + } + } + } + } + }, "/api/consultar-cndt": { "get": { "tags": [ @@ -2812,6 +2931,162 @@ } ] }, + "CNDValidacaoResponse": { + "properties": { + "request_id": { + "type": "string", + "title": "Request Id" + }, + "uf": { + "type": "string", + "title": "Uf" + }, + "codigo": { + "type": "string", + "title": "Codigo" + }, + "source_status": { + "$ref": "#/components/schemas/SourceStatus" + }, + "result": { + "anyOf": [ + { + "$ref": "#/components/schemas/CNDValidacaoResult" + }, + { + "type": "null" + } + ] + } + }, + "type": "object", + "required": [ + "request_id", + "uf", + "codigo", + "source_status" + ], + "title": "CNDValidacaoResponse", + "examples": [ + { + "codigo": "2026189378225", + "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "result": { + "codigo": "2026189378225", + "documento": "76.483.817", + "emissao": "10/11/2026", + "pdf_base64": "", + "situacao": "autentica", + "status": "negativa", + "status_raw": "CERTIDÃO NEGATIVA DE DÉBITOS - CND", + "validade": "10/12/2026" + }, + "source_status": { + "error_code": "", + "error_message": "", + "status": "success" + }, + "uf": "RJ" + } + ] + }, + "CNDValidacaoResult": { + "properties": { + "situacao": { + "type": "string", + "enum": [ + "autentica", + "vencida", + "nao_encontrada" + ], + "title": "Situacao" + }, + "status": { + "type": "string", + "enum": [ + "negativa", + "positiva", + "positiva_com_efeitos_de_negativa", + "nao_contribuinte", + "sem_certidao", + "erro" + ], + "title": "Status", + "default": "erro" + }, + "status_raw": { + "type": "string", + "title": "Status Raw", + "default": "" + }, + "documento": { + "type": "string", + "title": "Documento", + "default": "" + }, + "nome": { + "type": "string", + "title": "Nome", + "default": "" + }, + "emissao": { + "type": "string", + "title": "Emissao", + "default": "" + }, + "validade": { + "type": "string", + "title": "Validade", + "default": "" + }, + "codigo": { + "type": "string", + "title": "Codigo", + "default": "" + }, + "pdf_base64": { + "type": "string", + "title": "Pdf Base64", + "default": "" + }, + "url_verificacao": { + "type": "string", + "title": "Url Verificacao", + "default": "" + }, + "validade_iso": { + "type": "string", + "title": "Validade Iso", + "readOnly": true + }, + "emissao_iso": { + "type": "string", + "title": "Emissao Iso", + "readOnly": true + } + }, + "type": "object", + "required": [ + "situacao", + "validade_iso", + "emissao_iso" + ], + "title": "CNDValidacaoResult", + "examples": [ + { + "codigo": "2026189378225", + "documento": "76.483.817", + "emissao": "10/11/2026", + "nome": "", + "pdf_base64": "", + "situacao": "autentica", + "status": "negativa", + "status_raw": "CERTIDÃO NEGATIVA DE DÉBITOS - CND", + "url_verificacao": "", + "validade": "10/12/2026" + } + ] + }, "CNPJResponse": { "properties": { "request_id": {