From 844b6df524c1ed38020f1108ca65cd8f10d878a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Eduardo?= Date: Mon, 16 Nov 2026 20:42:30 -0300 Subject: [PATCH 1/2] =?UTF-8?q?feat:=20m=C3=A9todo=20consultar=5Fdifal=5Fs?= =?UTF-8?q?aida=20para=20o=20DIFAL=20de=20sa=C3=ADda=20por=20UF=20(Beta)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 23 +++++++++- pyproject.toml | 6 +-- src/fiscalapi_br/_client.py | 42 ++++++++++++++++++- src/fiscalapi_br/_version.py | 2 +- src/fiscalapi_br/types.py | 81 ++++++++++++++++++++++++++++++++++++ 5 files changed, 148 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2e649ad..5f9e1ab 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # FiscalAPI — SDK Python -Cliente Python 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 e de CT-e por chave, NFS-e por chave, Simples Nacional, SIGEF, CNIR e perfil do produtor rural. +Cliente Python 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 e de CT-e por chave, DIFAL de saída por UF, NFS-e por chave, Simples Nacional, SIGEF, CNIR e perfil do produtor rural. - Zero dependências (só a biblioteca padrão). - Python 3.9 ou superior. @@ -48,6 +48,7 @@ for ie in resp["results"]: | `consultar_nfse(chave, danfse=False)` | `GET /api/consultar-nfse` | NFS-e (padrão nacional) por chave, sem certificado | | `consultar_nfe_xml(chave, certificado=, senha=, manifestar=True)` | `POST /api/consultar-nfe-xml` | XML completo da NF-e | | `consultar_cte_xml(chave, certificado=, senha=)` | `POST /api/consultar-cte-xml` | XML completo do CT-e | +| `consultar_difal_saida(competencia, certificado=, senha=, ufs=)` | `POST /api/consultar-difal-saida` | DIFAL de saída por UF de destino (Beta) | | `consultar_sigef(cpf=/cnpj=)` | `GET /api/consultar-sigef` | Parcelas certificadas no SIGEF/INCRA | | `consultar_sigef_parcela(uuid, force_fresh=False)` | `GET /api/consultar-sigef-parcela` | Uma parcela com polígono, vértices e confrontantes | | `consultar_cnir(cpf=/cnpj=)` | `GET /api/consultar-cnir` | Imóveis rurais no CNIR/CAFIR | @@ -151,6 +152,26 @@ else: Aceita CT-e (modelo 57), CT-e OS (67) e GTV-e (64). O certificado A1 precisa ser de um participante do documento (emitente, tomador, remetente, destinatário, expedidor ou recebedor) e **não é armazenado** pela API. Só há cobrança quando o XML é devolvido. +### DIFAL de saída por UF de destino (Beta) + +```python +difal = api.consultar_difal_saida( + "2026-10", + certificado="certificado-do-emitente.pfx", # caminho, bytes do arquivo ou base64 + senha="senha-do-certificado", + ufs=["RS", "SC"], # omita para as 10 UFs +) +for uf in difal["ufs"]: + print(uf["uf"], uf["status"], uf["valor_em_aberto"]) + for nota in uf["notas"]: + if nota["em_aberto"]: + print(" ", nota["serie"], nota["numero"], nota["situacao_guia_difal"], nota["valor_em_aberto"]) +if not difal["completo"]: + print("Alguma UF não veio completa: os totais podem estar incompletos.") +``` + +Lista as NF-e do mês com DIFAL e FCP destacados, a situação da guia de cada nota e o valor em aberto, nas UFs de destino AC, AP, DF, GO, MS, MT, RR, RS, SC e SE. O certificado A1 é o do **emitente** das notas e **não é armazenado** pela API. Só `paga` quita: `sem_guia_no_portal`, `pendente_pagamento` e `geracao_rejeitada` somam em `valor_em_aberto`. Cobra 1 consulta por UF com `status` `ok`. Guia emitida fora do portal (ERP, Portal GNRE) não aparece. Detalhes: [documentação](https://docs.fiscalapi.com.br/docs/difal/consultar-difal-saida). + ### Imóvel rural ```python diff --git a/pyproject.toml b/pyproject.toml index 530bc6e..51465e1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,8 +4,8 @@ build-backend = "hatchling.build" [project] name = "fiscalapi-br" -version = "0.3.0" -description = "SDK da FiscalAPI (Brasil): Inscrição Estadual, CNPJ, certidões, NF-e, SIGEF, CNIR e perfil do produtor rural." +version = "0.4.0" +description = "SDK da FiscalAPI (Brasil): Inscrição Estadual, CNPJ, certidões, NF-e, CT-e, DIFAL, SIGEF, CNIR e perfil do produtor rural." readme = "README.md" license = "MIT" license-files = ["LICENSE"] @@ -13,7 +13,7 @@ requires-python = ">=3.9" authors = [{ name = "FiscalAPI", email = "contato@fiscalapi.com.br" }] keywords = [ "fiscalapi", "inscricao estadual", "sefaz", "cnpj", "cnd", "certidao", - "nfe", "sigef", "cnir", "produtor rural", "brasil", + "nfe", "difal", "sigef", "cnir", "produtor rural", "brasil", ] classifiers = [ "Development Status :: 4 - Beta", diff --git a/src/fiscalapi_br/_client.py b/src/fiscalapi_br/_client.py index 96001e6..e8b68cb 100644 --- a/src/fiscalapi_br/_client.py +++ b/src/fiscalapi_br/_client.py @@ -5,11 +5,12 @@ import json import os import random +import re import time import urllib.error import urllib.parse import urllib.request -from typing import Any, Dict, Mapping, Optional, Union, cast +from typing import Any, Dict, Mapping, Optional, Sequence, Union, cast from ._errors import ( APIConnectionError, @@ -31,6 +32,7 @@ ConsultaIEResponse, ConsultaIETodosResponse, CteXmlResponse, + DifalSaidaResponse, NfeXmlResponse, NfseResponse, PerfilProdutorResponse, @@ -269,6 +271,44 @@ def consultar_cte_xml( # POST não é repetido em 5xx. return cast(CteXmlResponse, self._request("POST", "/api/consultar-cte-xml", json_body=body)) + def consultar_difal_saida( + self, + competencia: str, + *, + certificado: Certificado, + senha: str, + ufs: Optional[Sequence[str]] = None, + ) -> DifalSaidaResponse: + """DIFAL de saída (EC 87/2015) por UF de destino, num mês (``POST /api/consultar-difal-saida``). Beta. + + Lista as NF-e do emitente com DIFAL e FCP destacados, a situação da + guia de cada nota e o valor em aberto. Cobra 1 consulta por UF com + ``status`` "ok". Pode levar cerca de 70 s. + + Args: + competencia: mês de emissão das notas, ``AAAA-MM`` (ex.: "2026-10"). + certificado: certificado A1 (.pfx/.p12) do EMITENTE das notas — + caminho do arquivo, ``bytes`` do arquivo ou o conteúdo já em + base64. O certificado não é armazenado pela API. + senha: senha do certificado. + ufs: siglas das UFs de destino. Omitido ou vazio = as 10 atendidas + (AC, AP, DF, GO, MS, MT, RR, RS, SC, SE). + """ + competencia = (competencia or "").strip() + if not re.fullmatch(r"\d{4}-(0[1-9]|1[0-2])", competencia): + raise ValueError("Informe a competência no formato AAAA-MM (ex.: 2026-10).") + if isinstance(ufs, str): + raise ValueError('Informe as UFs em lista, ex.: ["RS", "SC"].') + body: Dict[str, Any] = { + "certificado": _certificado_base64(certificado), + "senha": senha, + "competencia": competencia, + } + if ufs: + body["ufs"] = [_uf(u) for u in ufs] + # POST não é repetido em 5xx. + return cast(DifalSaidaResponse, self._request("POST", "/api/consultar-difal-saida", json_body=body)) + def consultar_nfse(self, chave: str, *, danfse: bool = False) -> NfseResponse: """NFS-e (padrão nacional) pela chave de acesso, sem certificado (``GET /api/consultar-nfse``). diff --git a/src/fiscalapi_br/_version.py b/src/fiscalapi_br/_version.py index 493f741..6a9beea 100644 --- a/src/fiscalapi_br/_version.py +++ b/src/fiscalapi_br/_version.py @@ -1 +1 @@ -__version__ = "0.3.0" +__version__ = "0.4.0" diff --git a/src/fiscalapi_br/types.py b/src/fiscalapi_br/types.py index 188fbbd..245e202 100644 --- a/src/fiscalapi_br/types.py +++ b/src/fiscalapi_br/types.py @@ -190,6 +190,87 @@ class CteXmlResponse(TypedDict, total=False): creditos_cobrados: int +# DIFAL de saída (Beta). Só "paga" quita; sem_guia_no_portal, +# pendente_pagamento e geracao_rejeitada somam em valor_em_aberto. +SituacaoGuiaDifal = Literal[ + "sem_guia_no_portal", + "pendente_pagamento", + "paga", + "geracao_rejeitada", + "aguardando_processamento", + "substituida", + "guia_gerada", + "nao_se_aplica", + "desconhecida", +] +# ok é cobrada; parcial, erro e nao_consultada não são. +StatusUfDifal = Literal["ok", "parcial", "erro", "nao_consultada"] + + +class NotaDifal(TypedDict, total=False): + serie: str + numero: str + data_emissao: Optional[str] # AAAA-MM-DD + vencimento: Optional[str] # vencimento do imposto, AAAA-MM-DD + destinatario: str + uf_destino: str + valor_total: Optional[float] + valor_difal: Optional[float] + valor_fcp: Optional[float] + situacao_guia_difal: SituacaoGuiaDifal + situacao_guia_fcp: SituacaoGuiaDifal + em_aberto: bool + valor_em_aberto: float + a_conferir: bool # guia existe, pagamento não confirmado; fora do valor em aberto + valor_a_conferir: float + + +class GuiaDifal(TypedDict, total=False): + numero: str + vencimento_imposto: Optional[str] + data_limite_pagamento: Optional[str] + uf: str + tributo: str + valor: Optional[float] + situacao: Optional[str] # paga | pendente_pagamento | geracao_rejeitada | aguardando_processamento | substituida + + +class UfDifalResultado(TypedDict, total=False): + uf: str + status: StatusUfDifal + mensagem: str + total_documentos: int + valor_difal: float + valor_fcp: float + valor_em_aberto: float + notas_em_aberto: int + valor_a_conferir: float + notas_a_conferir: int + notas: List[NotaDifal] + guias: List[GuiaDifal] + + +class DifalSaidaResponse(TypedDict, total=False): + request_id: str + fonte: str + emitente_tipo: str # CNPJ ou CPF do titular do certificado + emitente_documento: str + competencia: str # AAAA-MM + periodo_inicio: str + periodo_fim: str + total_documentos: int + valor_difal: float + valor_fcp: float + valor_em_aberto: float + notas_em_aberto: int + valor_a_conferir: float + notas_a_conferir: int + completo: bool # True só quando todas as UFs pedidas vieram "ok" + ufs: List[UfDifalResultado] + avisos: List[str] + creditos_cobrados: int # 1 por UF "ok" + + class SigefParcela(TypedDict, total=False): parcel_id: str codigo_parcela: str From 0487ecd4e1aa90d61def87842bafe0acc9549680 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Eduardo?= Date: Mon, 16 Nov 2026 21:43:53 -0300 Subject: [PATCH 2/2] =?UTF-8?q?fix:=20exce=C3=A7=C3=A3o=20de=20DF,=20GO=20?= =?UTF-8?q?e=20MT=20no=20em=20aberto=20do=20DIFAL?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- src/fiscalapi_br/types.py | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 5f9e1ab..df9f97d 100644 --- a/README.md +++ b/README.md @@ -170,7 +170,7 @@ if not difal["completo"]: print("Alguma UF não veio completa: os totais podem estar incompletos.") ``` -Lista as NF-e do mês com DIFAL e FCP destacados, a situação da guia de cada nota e o valor em aberto, nas UFs de destino AC, AP, DF, GO, MS, MT, RR, RS, SC e SE. O certificado A1 é o do **emitente** das notas e **não é armazenado** pela API. Só `paga` quita: `sem_guia_no_portal`, `pendente_pagamento` e `geracao_rejeitada` somam em `valor_em_aberto`. Cobra 1 consulta por UF com `status` `ok`. Guia emitida fora do portal (ERP, Portal GNRE) não aparece. Detalhes: [documentação](https://docs.fiscalapi.com.br/docs/difal/consultar-difal-saida). +Lista as NF-e do mês com DIFAL e FCP destacados, a situação da guia de cada nota e o valor em aberto, nas UFs de destino AC, AP, DF, GO, MS, MT, RR, RS, SC e SE. O certificado A1 é o do **emitente** das notas e **não é armazenado** pela API. Só `paga` quita: `sem_guia_no_portal`, `pendente_pagamento` e `geracao_rejeitada` somam em `valor_em_aberto`, menos em DF, GO e MT, onde a guia é emitida no sistema da SEFAZ e a nota `sem_guia_no_portal` soma em `valor_a_conferir`. Cobra 1 consulta por UF com `status` `ok`. Guia emitida fora do portal (ERP, Portal GNRE) não aparece. Detalhes: [documentação](https://docs.fiscalapi.com.br/docs/difal/consultar-difal-saida). ### Imóvel rural diff --git a/src/fiscalapi_br/types.py b/src/fiscalapi_br/types.py index 245e202..42e6dcc 100644 --- a/src/fiscalapi_br/types.py +++ b/src/fiscalapi_br/types.py @@ -191,7 +191,9 @@ class CteXmlResponse(TypedDict, total=False): # DIFAL de saída (Beta). Só "paga" quita; sem_guia_no_portal, -# pendente_pagamento e geracao_rejeitada somam em valor_em_aberto. +# pendente_pagamento e geracao_rejeitada somam em valor_em_aberto, menos em +# DF, GO e MT: lá a guia é emitida no sistema da SEFAZ e sem_guia_no_portal +# soma em valor_a_conferir. SituacaoGuiaDifal = Literal[ "sem_guia_no_portal", "pendente_pagamento", @@ -219,9 +221,9 @@ class NotaDifal(TypedDict, total=False): valor_fcp: Optional[float] situacao_guia_difal: SituacaoGuiaDifal situacao_guia_fcp: SituacaoGuiaDifal - em_aberto: bool + em_aberto: bool # sem guia no portal (menos em DF, GO e MT), guia pendente ou rejeitada valor_em_aberto: float - a_conferir: bool # guia existe, pagamento não confirmado; fora do valor em aberto + a_conferir: bool # guia sem pagamento confirmado ou, em DF, GO e MT, sem guia no portal; fora do em aberto valor_a_conferir: float