diff --git a/FiscalAPI.postman_collection.json b/FiscalAPI.postman_collection.json index 097adec..43e6433 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 e de CT-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**Plano ou recarga:** pela API, toda consulta pede plano (a partir de R$ 50 por mês) ou saldo de recarga. As 10 consultas grátis do mês são só no painel (https://app.fiscalapi.com.br): teste lá antes de assinar. Sem plano nem saldo, o 402 é `LIMITE_ATINGIDO`.\n\n**Limites:** franquia mensal por conta e limite de requisições por minuto conforme o plano (Starter 20, Pro 60, Enterprise 120; conta sem plano, 5). 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 e de CT-e por chave, DIFAL de saída por UF de destino, 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**Plano ou recarga:** pela API, toda consulta pede plano (a partir de R$ 50 por mês) ou saldo de recarga. As 10 consultas grátis do mês são só no painel (https://app.fiscalapi.com.br): teste lá antes de assinar. Sem plano nem saldo, o 402 é `LIMITE_ATINGIDO`.\n\n**Limites:** franquia mensal por conta e limite de requisições por minuto conforme o plano (Starter 20, Pro 60, Enterprise 120; conta sem plano, 5). 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": { @@ -60,6 +60,12 @@ "value": "", "type": "string", "description": "Senha do certificado. Não salve em workspace público." + }, + { + "key": "competenciaDifal", + "value": "2026-10", + "type": "string", + "description": "Mês de emissão das notas para o DIFAL de saída (AAAA-MM)." } ], "item": [ @@ -1878,6 +1884,280 @@ } ] }, + { + "name": "DIFAL", + "description": "DIFAL de saída por UF de destino, com o certificado do emitente (Beta).", + "item": [ + { + "name": "Consultar DIFAL de saída por UF de destino (Beta)", + "request": { + "method": "POST", + "header": [ + { + "key": "Accept", + "value": "application/json" + }, + { + "key": "Content-Type", + "value": "application/json" + } + ], + "url": { + "raw": "{{baseUrl}}/api/consultar-difal-saida", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "consultar-difal-saida" + ] + }, + "description": "**Beta.** Lista, para o mês informado (`competencia`, AAAA-MM), as NF-e do emitente com **DIFAL** (EC 87/2015) e **FCP** destacados para cada UF de destino, a situação da guia de cada nota e o **valor em aberto**. UFs atendidas: AC, AP, DF, GO, MS, MT, RR, RS, SC e SE. `ufs` omitido = as 10.\n\n**Certificado:** A1 (e-CNPJ ou e-CPF) do **emitente** das notas, em base64. Zero custódia: usado só durante a consulta e descartado.\n\n**Em aberto × a conferir:** só `paga` quita. `sem_guia_no_portal`, `pendente_pagamento` e `geracao_rejeitada` somam em `valor_em_aberto` (em DF, GO e MT, onde a guia é emitida no sistema da SEFAZ, a nota `sem_guia_no_portal` fica a conferir); guia existente sem pagamento confirmado soma em `valor_a_conferir`. Guia emitida fora do portal (ERP, Portal GNRE) e o recolhimento mensal de quem tem IE na UF de destino não aparecem (a nota sai `sem_guia_no_portal`).\n\n**Cobrança:** 1 consulta por UF com `status: ok`. UF `parcial`, `erro` ou `nao_consultada` não é cobrada. `completo: true` só quando todas as UFs vieram `ok`. Pode levar cerca de 70 s.\n\nDocumentação: https://docs.fiscalapi.com.br/docs/difal/consultar-difal-saida", + "body": { + "mode": "raw", + "raw": "{\n \"certificado\": \"{{certificadoBase64}}\",\n \"senha\": \"{{senhaCertificado}}\",\n \"competencia\": \"{{competenciaDifal}}\",\n \"ufs\": [\"RS\", \"SC\"]\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "response": [ + { + "name": "200 - Sucesso", + "originalRequest": { + "method": "POST", + "header": [ + { + "key": "Accept", + "value": "application/json" + }, + { + "key": "Content-Type", + "value": "application/json" + } + ], + "url": { + "raw": "{{baseUrl}}/api/consultar-difal-saida", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "consultar-difal-saida" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"certificado\": \"MIIKcQIBAzCCCjcGCSqGSIb3DQEHAaCCCigEggokMIIK...\",\n \"senha\": \"senha-do-certificado\",\n \"competencia\": \"2026-10\",\n \"ufs\": [\n \"RS\",\n \"SC\"\n ]\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "status": "OK", + "code": 200, + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "cookie": [], + "body": "{\n \"request_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"fonte\": \"Portal da DIFAL - Módulo de Apuração\",\n \"emitente_tipo\": \"CNPJ\",\n \"emitente_documento\": \"12345678000195\",\n \"competencia\": \"2026-10\",\n \"periodo_inicio\": \"2026-10-01\",\n \"periodo_fim\": \"2026-10-31\",\n \"total_documentos\": 3,\n \"valor_difal\": 650.05,\n \"valor_fcp\": 80.0,\n \"valor_em_aberto\": 370.05,\n \"notas_em_aberto\": 2,\n \"valor_a_conferir\": 0.0,\n \"notas_a_conferir\": 0,\n \"completo\": true,\n \"ufs\": [\n {\n \"uf\": \"RS\",\n \"status\": \"ok\",\n \"mensagem\": \"\",\n \"total_documentos\": 3,\n \"valor_difal\": 650.05,\n \"valor_fcp\": 80.0,\n \"valor_em_aberto\": 370.05,\n \"notas_em_aberto\": 2,\n \"valor_a_conferir\": 0.0,\n \"notas_a_conferir\": 0,\n \"notas\": [\n {\n \"serie\": \"1\",\n \"numero\": \"1001\",\n \"data_emissao\": \"2026-10-03\",\n \"vencimento\": \"2026-10-03\",\n \"destinatario\": \"MARIA DA SILVA\",\n \"uf_destino\": \"RS\",\n \"valor_total\": 1000.0,\n \"valor_difal\": 100.0,\n \"valor_fcp\": 20.0,\n \"situacao_guia_difal\": \"sem_guia_no_portal\",\n \"situacao_guia_fcp\": \"sem_guia_no_portal\",\n \"em_aberto\": true,\n \"valor_em_aberto\": 120.0,\n \"a_conferir\": false,\n \"valor_a_conferir\": 0.0\n },\n {\n \"serie\": \"1\",\n \"numero\": \"1002\",\n \"data_emissao\": \"2026-10-05\",\n \"vencimento\": \"2026-10-05\",\n \"destinatario\": \"JOAO PEREIRA\",\n \"uf_destino\": \"RS\",\n \"valor_total\": 2500.0,\n \"valor_difal\": 250.05,\n \"valor_fcp\": 0.0,\n \"situacao_guia_difal\": \"pendente_pagamento\",\n \"situacao_guia_fcp\": \"nao_se_aplica\",\n \"em_aberto\": true,\n \"valor_em_aberto\": 250.05,\n \"a_conferir\": false,\n \"valor_a_conferir\": 0.0\n },\n {\n \"serie\": \"1\",\n \"numero\": \"1003\",\n \"data_emissao\": \"2026-10-08\",\n \"vencimento\": \"2026-10-08\",\n \"destinatario\": \"ANA SOUZA\",\n \"uf_destino\": \"RS\",\n \"valor_total\": 3000.0,\n \"valor_difal\": 300.0,\n \"valor_fcp\": 60.0,\n \"situacao_guia_difal\": \"paga\",\n \"situacao_guia_fcp\": \"paga\",\n \"em_aberto\": false,\n \"valor_em_aberto\": 0.0,\n \"a_conferir\": false,\n \"valor_a_conferir\": 0.0\n }\n ],\n \"guias\": [\n {\n \"numero\": \"2026100000001\",\n \"vencimento_imposto\": \"2026-10-05\",\n \"data_limite_pagamento\": \"2026-10-05\",\n \"uf\": \"RS\",\n \"tributo\": \"ICMS DIFAL\",\n \"valor\": 250.05,\n \"situacao\": \"pendente_pagamento\"\n },\n {\n \"numero\": \"2026100000002\",\n \"vencimento_imposto\": \"2026-10-08\",\n \"data_limite_pagamento\": \"2026-10-08\",\n \"uf\": \"RS\",\n \"tributo\": \"ICMS DIFAL\",\n \"valor\": 300.0,\n \"situacao\": \"paga\"\n },\n {\n \"numero\": \"2026100000003\",\n \"vencimento_imposto\": \"2026-10-08\",\n \"data_limite_pagamento\": \"2026-10-08\",\n \"uf\": \"RS\",\n \"tributo\": \"FCP\",\n \"valor\": 60.0,\n \"situacao\": \"paga\"\n }\n ]\n },\n {\n \"uf\": \"SC\",\n \"status\": \"ok\",\n \"mensagem\": \"\",\n \"total_documentos\": 0,\n \"valor_difal\": 0.0,\n \"valor_fcp\": 0.0,\n \"valor_em_aberto\": 0.0,\n \"notas_em_aberto\": 0,\n \"valor_a_conferir\": 0.0,\n \"notas_a_conferir\": 0,\n \"notas\": [],\n \"guias\": []\n }\n ],\n \"avisos\": [\n \"O Portal da DIFAL atende 10 UFs de destino: AC, AP, DF, GO, MS, MT, RR, RS, SC e SE. As demais UFs têm sistema próprio e não são consultadas por esta fonte.\",\n \"Nota 'sem_guia_no_portal' significa que nenhuma guia foi gerada no próprio portal. Guia emitida pelo ERP ou pelo Portal GNRE, e o recolhimento mensal de quem tem inscrição estadual na UF de destino, não aparecem aqui: confira antes de tratar como débito.\",\n \"'a_conferir' marca nota cuja guia existe mas o pagamento não foi confirmado pelo portal (aguardando processamento, substituída ou não localizada) e, em DF, GO e MT, nota sem guia no portal, porque nesses estados a guia é emitida no sistema da SEFAZ. Ela não entra no valor em aberto.\",\n \"A situação de cada guia (paga, pendente, rejeitada) é a informada pelo portal.\"\n ],\n \"creditos_cobrados\": 2\n}" + }, + { + "name": "200 - Uma UF não consultada (completo false)", + "originalRequest": { + "method": "POST", + "header": [ + { + "key": "Accept", + "value": "application/json" + }, + { + "key": "Content-Type", + "value": "application/json" + } + ], + "url": { + "raw": "{{baseUrl}}/api/consultar-difal-saida", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "consultar-difal-saida" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"certificado\": \"MIIKcQIBAzCCCjcGCSqGSIb3DQEHAaCCCigEggokMIIK...\",\n \"senha\": \"senha-do-certificado\",\n \"competencia\": \"2026-10\",\n \"ufs\": [\n \"RS\",\n \"SC\"\n ]\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "status": "OK", + "code": 200, + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + } + ], + "cookie": [], + "body": "{\n \"request_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"fonte\": \"Portal da DIFAL - Módulo de Apuração\",\n \"emitente_tipo\": \"CNPJ\",\n \"emitente_documento\": \"12345678000195\",\n \"competencia\": \"2026-10\",\n \"periodo_inicio\": \"2026-10-01\",\n \"periodo_fim\": \"2026-10-31\",\n \"total_documentos\": 3,\n \"valor_difal\": 650.05,\n \"valor_fcp\": 80.0,\n \"valor_em_aberto\": 370.05,\n \"notas_em_aberto\": 2,\n \"valor_a_conferir\": 0.0,\n \"notas_a_conferir\": 0,\n \"completo\": false,\n \"ufs\": [\n {\n \"uf\": \"RS\",\n \"status\": \"ok\",\n \"mensagem\": \"\",\n \"total_documentos\": 3,\n \"valor_difal\": 650.05,\n \"valor_fcp\": 80.0,\n \"valor_em_aberto\": 370.05,\n \"notas_em_aberto\": 2,\n \"valor_a_conferir\": 0.0,\n \"notas_a_conferir\": 0,\n \"notas\": [\n {\n \"serie\": \"1\",\n \"numero\": \"1001\",\n \"data_emissao\": \"2026-10-03\",\n \"vencimento\": \"2026-10-03\",\n \"destinatario\": \"MARIA DA SILVA\",\n \"uf_destino\": \"RS\",\n \"valor_total\": 1000.0,\n \"valor_difal\": 100.0,\n \"valor_fcp\": 20.0,\n \"situacao_guia_difal\": \"sem_guia_no_portal\",\n \"situacao_guia_fcp\": \"sem_guia_no_portal\",\n \"em_aberto\": true,\n \"valor_em_aberto\": 120.0,\n \"a_conferir\": false,\n \"valor_a_conferir\": 0.0\n },\n {\n \"serie\": \"1\",\n \"numero\": \"1002\",\n \"data_emissao\": \"2026-10-05\",\n \"vencimento\": \"2026-10-05\",\n \"destinatario\": \"JOAO PEREIRA\",\n \"uf_destino\": \"RS\",\n \"valor_total\": 2500.0,\n \"valor_difal\": 250.05,\n \"valor_fcp\": 0.0,\n \"situacao_guia_difal\": \"pendente_pagamento\",\n \"situacao_guia_fcp\": \"nao_se_aplica\",\n \"em_aberto\": true,\n \"valor_em_aberto\": 250.05,\n \"a_conferir\": false,\n \"valor_a_conferir\": 0.0\n },\n {\n \"serie\": \"1\",\n \"numero\": \"1003\",\n \"data_emissao\": \"2026-10-08\",\n \"vencimento\": \"2026-10-08\",\n \"destinatario\": \"ANA SOUZA\",\n \"uf_destino\": \"RS\",\n \"valor_total\": 3000.0,\n \"valor_difal\": 300.0,\n \"valor_fcp\": 60.0,\n \"situacao_guia_difal\": \"paga\",\n \"situacao_guia_fcp\": \"paga\",\n \"em_aberto\": false,\n \"valor_em_aberto\": 0.0,\n \"a_conferir\": false,\n \"valor_a_conferir\": 0.0\n }\n ],\n \"guias\": [\n {\n \"numero\": \"2026100000001\",\n \"vencimento_imposto\": \"2026-10-05\",\n \"data_limite_pagamento\": \"2026-10-05\",\n \"uf\": \"RS\",\n \"tributo\": \"ICMS DIFAL\",\n \"valor\": 250.05,\n \"situacao\": \"pendente_pagamento\"\n },\n {\n \"numero\": \"2026100000002\",\n \"vencimento_imposto\": \"2026-10-08\",\n \"data_limite_pagamento\": \"2026-10-08\",\n \"uf\": \"RS\",\n \"tributo\": \"ICMS DIFAL\",\n \"valor\": 300.0,\n \"situacao\": \"paga\"\n },\n {\n \"numero\": \"2026100000003\",\n \"vencimento_imposto\": \"2026-10-08\",\n \"data_limite_pagamento\": \"2026-10-08\",\n \"uf\": \"RS\",\n \"tributo\": \"FCP\",\n \"valor\": 60.0,\n \"situacao\": \"paga\"\n }\n ]\n },\n {\n \"uf\": \"SC\",\n \"status\": \"nao_consultada\",\n \"mensagem\": \"Tempo da consulta esgotado antes desta UF. Consulte-a de novo.\",\n \"total_documentos\": 0,\n \"valor_difal\": 0.0,\n \"valor_fcp\": 0.0,\n \"valor_em_aberto\": 0.0,\n \"notas_em_aberto\": 0,\n \"valor_a_conferir\": 0.0,\n \"notas_a_conferir\": 0,\n \"notas\": [],\n \"guias\": []\n }\n ],\n \"avisos\": [\n \"O Portal da DIFAL atende 10 UFs de destino: AC, AP, DF, GO, MS, MT, RR, RS, SC e SE. As demais UFs têm sistema próprio e não são consultadas por esta fonte.\",\n \"Nota 'sem_guia_no_portal' significa que nenhuma guia foi gerada no próprio portal. Guia emitida pelo ERP ou pelo Portal GNRE, e o recolhimento mensal de quem tem inscrição estadual na UF de destino, não aparecem aqui: confira antes de tratar como débito.\",\n \"'a_conferir' marca nota cuja guia existe mas o pagamento não foi confirmado pelo portal (aguardando processamento, substituída ou não localizada) e, em DF, GO e MT, nota sem guia no portal, porque nesses estados a guia é emitida no sistema da SEFAZ. Ela não entra no valor em aberto.\",\n \"A situação de cada guia (paga, pendente, rejeitada) é a informada pelo portal.\"\n ],\n \"creditos_cobrados\": 1\n}" + }, + { + "name": "400 - UF_NAO_ATENDIDA", + "originalRequest": { + "method": "POST", + "header": [ + { + "key": "Accept", + "value": "application/json" + }, + { + "key": "Content-Type", + "value": "application/json" + } + ], + "url": { + "raw": "{{baseUrl}}/api/consultar-difal-saida", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "consultar-difal-saida" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"certificado\": \"MIIKcQIBAzCCCjcGCSqGSIb3DQEHAaCCCigEggokMIIK...\",\n \"senha\": \"senha-do-certificado\",\n \"competencia\": \"2026-10\",\n \"ufs\": [\n \"SP\"\n ]\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "status": "Bad Request", + "code": 400, + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/problem+json" + } + ], + "cookie": [], + "body": "{\n \"type\": \"urn:fiscalapi:error:uf_nao_atendida\",\n \"title\": \"UF_NAO_ATENDIDA\",\n \"status\": 400,\n \"detail\": \"UF fora do Portal da DIFAL: SP. Atendidas: AC, AP, DF, GO, MS, MT, RR, RS, SC, SE.\",\n \"instance\": \"https://api.fiscalapi.com.br/api/consultar-difal-saida\",\n \"request_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"timestamp\": \"2026-11-16T13:00:00+00:00\"\n}" + }, + { + "name": "400 - COMPETENCIA_INVALIDA (mês futuro)", + "originalRequest": { + "method": "POST", + "header": [ + { + "key": "Accept", + "value": "application/json" + }, + { + "key": "Content-Type", + "value": "application/json" + } + ], + "url": { + "raw": "{{baseUrl}}/api/consultar-difal-saida", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "consultar-difal-saida" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"certificado\": \"MIIKcQIBAzCCCjcGCSqGSIb3DQEHAaCCCigEggokMIIK...\",\n \"senha\": \"senha-do-certificado\",\n \"competencia\": \"2027-01\",\n \"ufs\": [\n \"RS\",\n \"SC\"\n ]\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "status": "Bad Request", + "code": 400, + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/problem+json" + } + ], + "cookie": [], + "body": "{\n \"type\": \"urn:fiscalapi:error:competencia_invalida\",\n \"title\": \"COMPETENCIA_INVALIDA\",\n \"status\": 400,\n \"detail\": \"A competência não pode ser um mês futuro.\",\n \"instance\": \"https://api.fiscalapi.com.br/api/consultar-difal-saida\",\n \"request_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"timestamp\": \"2026-11-16T13:00:00+00:00\"\n}" + }, + { + "name": "503 - FONTE_INDISPONIVEL", + "originalRequest": { + "method": "POST", + "header": [ + { + "key": "Accept", + "value": "application/json" + }, + { + "key": "Content-Type", + "value": "application/json" + } + ], + "url": { + "raw": "{{baseUrl}}/api/consultar-difal-saida", + "host": [ + "{{baseUrl}}" + ], + "path": [ + "api", + "consultar-difal-saida" + ] + }, + "body": { + "mode": "raw", + "raw": "{\n \"certificado\": \"MIIKcQIBAzCCCjcGCSqGSIb3DQEHAaCCCigEggokMIIK...\",\n \"senha\": \"senha-do-certificado\",\n \"competencia\": \"2026-10\",\n \"ufs\": [\n \"RS\",\n \"SC\"\n ]\n}", + "options": { + "raw": { + "language": "json" + } + } + } + }, + "status": "Service Unavailable", + "code": 503, + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/problem+json" + } + ], + "cookie": [], + "body": "{\n \"type\": \"urn:fiscalapi:error:fonte_indisponivel\",\n \"title\": \"FONTE_INDISPONIVEL\",\n \"status\": 503,\n \"detail\": \"O Portal da DIFAL não respondeu para nenhuma UF. Nada foi cobrado.\",\n \"instance\": \"https://api.fiscalapi.com.br/api/consultar-difal-saida\",\n \"request_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"timestamp\": \"2026-11-16T13:00:00+00:00\"\n}" + } + ] + } + ] + }, { "name": "SIGEF", "description": "Parcelas georreferenciadas certificadas pelo INCRA.", diff --git a/README.md b/README.md index 440c261..ebaeff4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # FiscalAPI — coleção Postman e OpenAPI -Coleção Postman e especificação OpenAPI 3.1 da [FiscalAPI](https://fiscalapi.com.br): Inscrição Estadual nos 27 estados, CNPJ, certidões (CND estadual, CND Federal, CNDT, CRF/FGTS), XML de NF-e por chave (com certificado, ou cópia para leitura sem certificado), XML de CT-e por chave (com certificado), NFS-e por chave, Simples Nacional, SIGEF, CNIR e perfil do produtor rural. +Coleção Postman e especificação OpenAPI 3.1 da [FiscalAPI](https://fiscalapi.com.br): Inscrição Estadual nos 27 estados, CNPJ, certidões (CND estadual, CND Federal, CNDT, CRF/FGTS), XML de NF-e por chave (com certificado, ou cópia para leitura sem certificado), XML de CT-e por chave (com certificado), DIFAL de saída por UF de destino (Beta, com o certificado do emitente), NFS-e por chave, Simples Nacional, SIGEF, CNIR e perfil do produtor rural. | Arquivo | O que é | |---|---| diff --git a/openapi-publico.json b/openapi-publico.json index b519b47..cf25896 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 e de CT-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. Sem plano ou saldo, a chamada devolve 402. Para testar antes de assinar, use as 10 consultas grátis do mês no painel. 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 e de CT-e pela chave de acesso, NFS-e do padrão nacional pela chave de acesso, DIFAL de saída por UF de destino, 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. Sem plano ou saldo, a chamada devolve 402. Para testar antes de assinar, use as 10 consultas grátis do mês no painel. 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": [ @@ -1867,6 +1867,91 @@ } } }, + "/api/consultar-difal-saida": { + "post": { + "tags": [ + "DIFAL" + ], + "summary": "DIFAL de saída por UF de destino, com certificado do emitente", + "description": "Lista, para o mês informado, as NF-e do emitente com DIFAL (EC 87/2015) e FCP destacados para cada UF de destino atendida pelo Portal da DIFAL (AC, AP, DF, GO, MS, MT, RR, RS, SC, SE), a situação da guia de cada nota (paga, pendente, rejeitada ou sem guia gerada no portal) e o valor em aberto. Usa o certificado digital do PRÓPRIO emitente (e-CNPJ ou e-CPF), enviado na requisição e NÃO armazenado. Cobra 1 consulta por UF com resposta completa; UF parcial, com falha da fonte ou não consultada por tempo não é cobrada.", + "operationId": "consultar_difal_saida_endpoint_api_consultar_difal_saida_post", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DifalSaidaRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DifalSaidaResponse" + } + } + } + }, + "402": { + "description": "Saldo insuficiente para esta consulta. Assine um plano ou compre créditos extras.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "#/components/schemas/ErroProblema" + } + } + } + }, + "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" + } + } + } + } + } + } + }, "/api/consultar-nfe-xml-sem-certificado": { "post": { "tags": [ @@ -4225,6 +4310,163 @@ ], "title": "CteXmlResponse" }, + "DifalSaidaRequest": { + "properties": { + "certificado": { + "type": "string", + "title": "Certificado", + "description": "Binario do .pfx do EMITENTE das notas, em base64" + }, + "senha": { + "type": "string", + "title": "Senha", + "description": "Senha do certificado" + }, + "competencia": { + "type": "string", + "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", + "title": "Competencia", + "description": "Mes de emissao das notas, no formato AAAA-MM", + "examples": [ + "2026-10" + ] + }, + "ufs": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Ufs", + "description": "UFs de destino a consultar. Vazio = todas as atendidas pelo Portal da DIFAL (AC, AP, DF, GO, MS, MT, RR, RS, SC, SE).", + "examples": [ + [ + "RS", + "SC" + ] + ] + } + }, + "type": "object", + "required": [ + "certificado", + "senha", + "competencia" + ], + "title": "DifalSaidaRequest" + }, + "DifalSaidaResponse": { + "properties": { + "request_id": { + "type": "string", + "title": "Request Id" + }, + "fonte": { + "type": "string", + "title": "Fonte" + }, + "emitente_tipo": { + "type": "string", + "title": "Emitente Tipo", + "description": "CNPJ ou CPF do titular do certificado" + }, + "emitente_documento": { + "type": "string", + "title": "Emitente Documento" + }, + "competencia": { + "type": "string", + "title": "Competencia" + }, + "periodo_inicio": { + "type": "string", + "title": "Periodo Inicio" + }, + "periodo_fim": { + "type": "string", + "title": "Periodo Fim" + }, + "total_documentos": { + "type": "integer", + "title": "Total Documentos" + }, + "valor_difal": { + "type": "number", + "title": "Valor Difal" + }, + "valor_fcp": { + "type": "number", + "title": "Valor Fcp" + }, + "valor_em_aberto": { + "type": "number", + "title": "Valor Em Aberto" + }, + "notas_em_aberto": { + "type": "integer", + "title": "Notas Em Aberto" + }, + "valor_a_conferir": { + "type": "number", + "title": "Valor A Conferir" + }, + "notas_a_conferir": { + "type": "integer", + "title": "Notas A Conferir" + }, + "completo": { + "type": "boolean", + "title": "Completo", + "description": "True so quando TODAS as UFs pedidas voltaram 'ok'. False = totais podem estar incompletos." + }, + "ufs": { + "items": { + "$ref": "#/components/schemas/UfDifalOut" + }, + "type": "array", + "title": "Ufs" + }, + "avisos": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Avisos" + }, + "creditos_cobrados": { + "type": "integer", + "title": "Creditos Cobrados" + } + }, + "type": "object", + "required": [ + "request_id", + "fonte", + "emitente_tipo", + "emitente_documento", + "competencia", + "periodo_inicio", + "periodo_fim", + "total_documentos", + "valor_difal", + "valor_fcp", + "valor_em_aberto", + "notas_em_aberto", + "valor_a_conferir", + "notas_a_conferir", + "completo", + "ufs", + "avisos", + "creditos_cobrados" + ], + "title": "DifalSaidaResponse" + }, "ErroLimite": { "type": "object", "required": [ @@ -4445,6 +4687,73 @@ } ] }, + "GuiaGnreOut": { + "properties": { + "numero": { + "type": "string", + "title": "Numero" + }, + "vencimento_imposto": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Vencimento Imposto" + }, + "data_limite_pagamento": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Data Limite Pagamento" + }, + "uf": { + "type": "string", + "title": "Uf" + }, + "tributo": { + "type": "string", + "title": "Tributo" + }, + "valor": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Valor" + }, + "situacao": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Situacao" + } + }, + "type": "object", + "required": [ + "numero", + "uf", + "tributo" + ], + "title": "GuiaGnreOut" + }, "HTTPValidationError": { "properties": { "detail": { @@ -5539,6 +5848,126 @@ ], "title": "NfseTributoTotal" }, + "NotaDifalOut": { + "properties": { + "serie": { + "type": "string", + "title": "Serie" + }, + "numero": { + "type": "string", + "title": "Numero" + }, + "data_emissao": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Data Emissao", + "description": "AAAA-MM-DD" + }, + "vencimento": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Vencimento", + "description": "Vencimento do imposto, AAAA-MM-DD" + }, + "destinatario": { + "type": "string", + "title": "Destinatario" + }, + "uf_destino": { + "type": "string", + "title": "Uf Destino" + }, + "valor_total": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Valor Total" + }, + "valor_difal": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Valor Difal", + "description": "ICMS interestadual da UF de destino destacado na nota" + }, + "valor_fcp": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Valor Fcp", + "description": "Fundo de Combate a Pobreza destacado na nota" + }, + "situacao_guia_difal": { + "type": "string", + "title": "Situacao Guia Difal", + "description": "sem_guia_no_portal | pendente_pagamento | paga | geracao_rejeitada | aguardando_processamento | substituida | guia_gerada | nao_se_aplica | desconhecida" + }, + "situacao_guia_fcp": { + "type": "string", + "title": "Situacao Guia Fcp" + }, + "em_aberto": { + "type": "boolean", + "title": "Em Aberto", + "description": "Imposto da nota sem guia no portal ou com guia pendente/rejeitada" + }, + "valor_em_aberto": { + "type": "number", + "title": "Valor Em Aberto" + }, + "a_conferir": { + "type": "boolean", + "title": "A Conferir", + "description": "Guia existe mas a situação não foi confirmada pelo portal (aguardando processamento, substituída ou não localizada), ou nota sem guia no portal em DF, GO e MT, onde a guia é emitida no sistema da SEFAZ. Não entra no valor em aberto." + }, + "valor_a_conferir": { + "type": "number", + "title": "Valor A Conferir" + } + }, + "type": "object", + "required": [ + "serie", + "numero", + "destinatario", + "uf_destino", + "situacao_guia_difal", + "situacao_guia_fcp", + "em_aberto", + "valor_em_aberto", + "a_conferir", + "valor_a_conferir" + ], + "title": "NotaDifalOut" + }, "RegimeTributarioAno": { "properties": { "ano": { @@ -5773,13 +6202,13 @@ "examples": [ { "consultas_restantes": 1500, - "notas_restantes": 500, "creditos": { - "plano": 97.5, + "disponivel": 97.5, "extras": 0.0, "guardados": 0.0, - "disponivel": 97.5 - } + "plano": 97.5 + }, + "notas_restantes": 500 } ] }, @@ -6815,6 +7244,81 @@ } ] }, + "UfDifalOut": { + "properties": { + "uf": { + "type": "string", + "title": "Uf" + }, + "status": { + "type": "string", + "title": "Status", + "description": "ok (completa, cobrada) | parcial (dados incompletos, nao cobrada) | erro (falha da fonte, nao cobrada) | nao_consultada (tempo esgotado, nao cobrada)" + }, + "mensagem": { + "type": "string", + "title": "Mensagem", + "default": "" + }, + "total_documentos": { + "type": "integer", + "title": "Total Documentos", + "default": 0 + }, + "valor_difal": { + "type": "number", + "title": "Valor Difal", + "default": 0.0 + }, + "valor_fcp": { + "type": "number", + "title": "Valor Fcp", + "default": 0.0 + }, + "valor_em_aberto": { + "type": "number", + "title": "Valor Em Aberto", + "default": 0.0 + }, + "notas_em_aberto": { + "type": "integer", + "title": "Notas Em Aberto", + "default": 0 + }, + "valor_a_conferir": { + "type": "number", + "title": "Valor A Conferir", + "default": 0.0 + }, + "notas_a_conferir": { + "type": "integer", + "title": "Notas A Conferir", + "default": 0 + }, + "notas": { + "items": { + "$ref": "#/components/schemas/NotaDifalOut" + }, + "type": "array", + "title": "Notas", + "default": [] + }, + "guias": { + "items": { + "$ref": "#/components/schemas/GuiaGnreOut" + }, + "type": "array", + "title": "Guias", + "default": [] + } + }, + "type": "object", + "required": [ + "uf", + "status" + ], + "title": "UfDifalOut" + }, "ValidationError": { "properties": { "loc": { @@ -6911,6 +7415,10 @@ "name": "CT-e XML", "description": "XML do CT-e, CT-e OS ou GTV-e pela chave de acesso, com o certificado digital de quem participa do documento." }, + { + "name": "DIFAL", + "description": "DIFAL de saída (EC 87/2015) por UF de destino: notas com DIFAL destacado, situação da guia e valor em aberto, com o certificado digital do emitente." + }, { "name": "Saldo", "description": "Saldo restante da conta."