Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 22 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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`, 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

```python
Expand Down
6 changes: 3 additions & 3 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,16 @@ 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"]
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",
Expand Down
42 changes: 41 additions & 1 deletion src/fiscalapi_br/_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -31,6 +32,7 @@
ConsultaIEResponse,
ConsultaIETodosResponse,
CteXmlResponse,
DifalSaidaResponse,
NfeXmlResponse,
NfseResponse,
PerfilProdutorResponse,
Expand Down Expand Up @@ -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``).

Expand Down
2 changes: 1 addition & 1 deletion src/fiscalapi_br/_version.py
Original file line number Diff line number Diff line change
@@ -1 +1 @@
__version__ = "0.3.0"
__version__ = "0.4.0"
83 changes: 83 additions & 0 deletions src/fiscalapi_br/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,89 @@ 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, 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",
"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 # sem guia no portal (menos em DF, GO e MT), guia pendente ou rejeitada
valor_em_aberto: float
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


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
Expand Down
Loading