fiscalapi-br 0.1.0__py3-none-any.whl

fiscalapi_br/__init__.py

@@ -0,0 +1,29 @@
+"""SDK oficial da FiscalAPI para Python.
+
+Consulta de Inscrição Estadual, CNPJ, certidões, NF-e, SIGEF, CNIR e perfil
+do produtor rural pela API REST https://api.fiscalapi.com.br.
+"""
+from ._client import DEFAULT_BASE_URL, FiscalAPI
+from ._errors import (
+    APIConnectionError,
+    AuthenticationError,
+    BadRequestError,
+    FiscalAPIError,
+    InsufficientBalanceError,
+    RateLimitError,
+    ServerError,
+)
+from ._version import __version__
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "FiscalAPI",
+    "FiscalAPIError",
+    "AuthenticationError",
+    "InsufficientBalanceError",
+    "RateLimitError",
+    "BadRequestError",
+    "ServerError",
+    "APIConnectionError",
+    "__version__",
+]

fiscalapi_br/_client.py

@@ -0,0 +1,427 @@
+"""Cliente HTTP da FiscalAPI — somente biblioteca padrão (zero dependências)."""
+from __future__ import annotations
+
+import base64
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Mapping, Optional, Union, cast
+
+from ._errors import (
+    APIConnectionError,
+    AuthenticationError,
+    BadRequestError,
+    FiscalAPIError,
+    InsufficientBalanceError,
+    RateLimitError,
+    ServerError,
+)
+from ._version import __version__
+from .types import (
+    CertidaoFederalResponse,
+    CertidoesTodasResponse,
+    CNDResponse,
+    CNDTodosResponse,
+    CnirResponse,
+    CNPJResponse,
+    ConsultaIEResponse,
+    ConsultaIETodosResponse,
+    NfeXmlResponse,
+    PerfilProdutorResponse,
+    SigefParcelaResponse,
+    SigefResponse,
+)
+
+DEFAULT_BASE_URL = "https://api.fiscalapi.com.br"
+# Algumas consultas (NF-e, SIGEF) podem levar até 180 s no servidor.
+DEFAULT_TIMEOUT = 200.0
+DEFAULT_MAX_RETRIES = 3
+
+_RETRYABLE_ANY_METHOD = {429}
+_RETRYABLE_IDEMPOTENT = {500, 502, 503, 504}
+_MAX_BACKOFF = 30.0
+_MAX_RETRY_AFTER = 60.0
+
+Certificado = Union[bytes, bytearray, str, "os.PathLike[str]"]
+
+
+class FiscalAPI:
+    """Cliente da FiscalAPI.
+
+    Exemplo::
+
+        from fiscalapi_br import FiscalAPI
+
+        api = FiscalAPI("sua-chave")
+        resp = api.consultar_ie(uf="MT", cpf="12345678909")
+
+    Args:
+        api_key: chave de API do painel. Se omitida, lê ``FISCALAPI_API_KEY``.
+        base_url: URL base da API.
+        timeout: tempo máximo, em segundos, de cada tentativa.
+        max_retries: novas tentativas em 429 e (para GET) em 5xx/falha de rede.
+        user_agent: sufixo opcional para o cabeçalho ``User-Agent``.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        key = api_key or os.environ.get("FISCALAPI_API_KEY")
+        if not key:
+            raise ValueError(
+                "Informe a chave de API: FiscalAPI('sua-chave') ou a variável FISCALAPI_API_KEY."
+            )
+        self.api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max(0, int(max_retries))
+        ua = f"fiscalapi-br-python/{__version__}"
+        self.user_agent = f"{ua} {user_agent}" if user_agent else ua
+
+    # ------------------------------------------------------------------ IE
+
+    def consultar_ie(
+        self,
+        uf: str,
+        *,
+        cpf: Optional[str] = None,
+        cnpj: Optional[str] = None,
+        ie: Optional[str] = None,
+        secundarias: bool = False,
+    ) -> ConsultaIEResponse:
+        """Inscrição Estadual em uma UF (``GET /api/consultar``).
+
+        Informe exatamente um entre ``cpf``, ``cnpj`` e ``ie``. Com
+        ``secundarias=True`` a resposta traz as atividades secundárias
+        (``cnaes_secundarios``) — a consulta fica mais lenta.
+        """
+        doc = _um_documento(cpf=cpf, cnpj=cnpj, ie=ie)
+        params = {"uf": _uf(uf), **doc, "secundarias": secundarias or None}
+        return cast(ConsultaIEResponse, self._get("/api/consultar", params))
+
+    def consultar_ie_todos(
+        self,
+        *,
+        cpf: Optional[str] = None,
+        cnpj: Optional[str] = None,
+        ie: Optional[str] = None,
+        secundarias: bool = False,
+    ) -> ConsultaIETodosResponse:
+        """Inscrição Estadual em todos os estados (``GET /api/consultar-ie-todos``).
+
+        Confira ``complete``: quando ``False``, algum estado falhou e um
+        resultado vazio não significa "não encontrado".
+        """
+        doc = _um_documento(cpf=cpf, cnpj=cnpj, ie=ie)
+        params = {**doc, "secundarias": secundarias or None}
+        return cast(ConsultaIETodosResponse, self._get("/api/consultar-ie-todos", params))
+
+    # ---------------------------------------------------------------- CNPJ
+
+    def consultar_cnpj(self, cnpj: str, *, force_fresh: bool = False) -> CNPJResponse:
+        """Dados cadastrais do CNPJ na Receita Federal (``GET /api/consultar-cnpj``).
+
+        ``force_fresh=True`` consulta o dado atual, sem cache (mais lento e
+        consome mais créditos).
+        """
+        if not cnpj:
+            raise ValueError("Informe o CNPJ.")
+        params = {"cnpj": cnpj, "force_fresh": force_fresh or None}
+        return cast(CNPJResponse, self._get("/api/consultar-cnpj", params))
+
+    # ----------------------------------------------------------- Certidões
+
+    def consultar_cnd(
+        self, uf: str, *, cpf: Optional[str] = None, cnpj: Optional[str] = None
+    ) -> CNDResponse:
+        """CND estadual (ICMS) em uma UF (``GET /api/consultar-cnd``)."""
+        params = {"uf": _uf(uf), **_um_documento(cpf=cpf, cnpj=cnpj)}
+        return cast(CNDResponse, self._get("/api/consultar-cnd", params))
+
+    def consultar_cnd_todos(
+        self, *, cpf: Optional[str] = None, cnpj: Optional[str] = None
+    ) -> CNDTodosResponse:
+        """CND estadual em todos os estados disponíveis (``GET /api/consultar-cnd-todos``)."""
+        params = _um_documento(cpf=cpf, cnpj=cnpj)
+        return cast(CNDTodosResponse, self._get("/api/consultar-cnd-todos", params))
+
+    def consultar_cnd_federal(
+        self,
+        *,
+        cpf: Optional[str] = None,
+        cnpj: Optional[str] = None,
+        emitir_nova: bool = False,
+    ) -> CertidaoFederalResponse:
+        """CND Federal — Receita Federal + PGFN (``GET /api/consultar-cnd-federal``).
+
+        Devolve a certidão vigente quando ela vale por mais de 3 dias
+        (``modo="consulta"``); senão, emite uma nova (``modo="emissao"``).
+        ``emitir_nova=True`` força uma nova emissão.
+        """
+        params = {**_um_documento(cpf=cpf, cnpj=cnpj), "emitir_nova": emitir_nova or None}
+        return cast(CertidaoFederalResponse, self._get("/api/consultar-cnd-federal", params))
+
+    def consultar_cndt(
+        self, *, cpf: Optional[str] = None, cnpj: Optional[str] = None
+    ) -> CertidaoFederalResponse:
+        """CNDT — débitos trabalhistas (``GET /api/consultar-cndt``)."""
+        params = _um_documento(cpf=cpf, cnpj=cnpj)
+        return cast(CertidaoFederalResponse, self._get("/api/consultar-cndt", params))
+
+    def consultar_crf_fgts(
+        self, *, cpf: Optional[str] = None, cnpj: Optional[str] = None
+    ) -> CertidaoFederalResponse:
+        """CRF — regularidade do FGTS (``GET /api/consultar-crf-fgts``)."""
+        params = _um_documento(cpf=cpf, cnpj=cnpj)
+        return cast(CertidaoFederalResponse, self._get("/api/consultar-crf-fgts", params))
+
+    def consultar_certidoes_todas(
+        self,
+        *,
+        cpf: Optional[str] = None,
+        cnpj: Optional[str] = None,
+        skip_estaduais: bool = False,
+    ) -> CertidoesTodasResponse:
+        """CNDs estaduais + CNDT + CND Federal + CRF/FGTS em uma chamada
+        (``GET /api/certidoes-todas``)."""
+        params = {**_um_documento(cpf=cpf, cnpj=cnpj), "skip_estaduais": skip_estaduais or None}
+        return cast(CertidoesTodasResponse, self._get("/api/certidoes-todas", params))
+
+    # ---------------------------------------------------------------- NF-e
+
+    def consultar_nfe_xml(
+        self,
+        chave: str,
+        *,
+        certificado: Certificado,
+        senha: str,
+        manifestar: bool = True,
+    ) -> NfeXmlResponse:
+        """XML completo de uma NF-e pela chave de acesso (``POST /api/consultar-nfe-xml``).
+
+        Args:
+            chave: chave de acesso com 44 dígitos.
+            certificado: certificado A1 (.pfx/.p12) do participante da nota —
+                caminho do arquivo, ``bytes`` do arquivo ou o conteúdo já em
+                base64. O certificado não é armazenado pela API.
+            senha: senha do certificado.
+            manifestar: quando só há o resumo da nota, registra a manifestação
+                do destinatário para liberar o XML. ``False`` não registra
+                nenhum evento.
+        """
+        if not chave:
+            raise ValueError("Informe a chave de acesso.")
+        body = {
+            "chave": "".join(ch for ch in chave if ch.isdigit()),
+            "certificado": _certificado_base64(certificado),
+            "senha": senha,
+            "manifestar": manifestar,
+        }
+        # POST não é repetido em 5xx: a manifestação pode já ter sido registrada.
+        return cast(NfeXmlResponse, self._request("POST", "/api/consultar-nfe-xml", json_body=body))
+
+    # ------------------------------------------------------- Imóvel rural
+
+    def consultar_sigef(
+        self, *, cpf: Optional[str] = None, cnpj: Optional[str] = None
+    ) -> SigefResponse:
+        """Parcelas certificadas no SIGEF/INCRA do detentor (``GET /api/consultar-sigef``)."""
+        params = _um_documento(cpf=cpf, cnpj=cnpj)
+        return cast(SigefResponse, self._get("/api/consultar-sigef", params))
+
+    def consultar_sigef_parcela(
+        self, uuid: str, *, force_fresh: bool = False
+    ) -> SigefParcelaResponse:
+        """Uma parcela SIGEF pelo UUID, com polígono, vértices e confrontantes
+        (``GET /api/consultar-sigef-parcela``)."""
+        if not uuid:
+            raise ValueError("Informe o UUID da parcela.")
+        params = {"uuid": uuid.strip(), "force_fresh": force_fresh or None}
+        return cast(SigefParcelaResponse, self._get("/api/consultar-sigef-parcela", params))
+
+    def consultar_cnir(
+        self, *, cpf: Optional[str] = None, cnpj: Optional[str] = None
+    ) -> CnirResponse:
+        """Imóveis rurais no CNIR/CAFIR (``GET /api/consultar-cnir``)."""
+        params = _um_documento(cpf=cpf, cnpj=cnpj)
+        return cast(CnirResponse, self._get("/api/consultar-cnir", params))
+
+    # ------------------------------------------------------------- Perfil
+
+    def perfil_produtor(
+        self, *, cpf: Optional[str] = None, cnpj: Optional[str] = None
+    ) -> PerfilProdutorResponse:
+        """Perfil consolidado do produtor rural (``GET /api/perfil-produtor``)."""
+        params = _um_documento(cpf=cpf, cnpj=cnpj)
+        return cast(PerfilProdutorResponse, self._get("/api/perfil-produtor", params))
+
+    # ----------------------------------------------------------- Transporte
+
+    def _get(self, path: str, params: Mapping[str, Any]) -> Dict[str, Any]:
+        return self._request("GET", path, params=params)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json_body: Optional[Mapping[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        url = self.base_url + path
+        query = _encode_query(params or {})
+        if query:
+            url = f"{url}?{query}"
+
+        data: Optional[bytes] = None
+        headers = {
+            "X-API-Key": self.api_key,
+            "Accept": "application/json",
+            "User-Agent": self.user_agent,
+        }
+        if json_body is not None:
+            data = json.dumps(json_body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        idempotent = method == "GET"
+        attempt = 0
+        while True:
+            req = urllib.request.Request(url, data=data, method=method, headers=headers)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    raw = resp.read()
+                return _decode_success(raw)
+            except urllib.error.HTTPError as exc:
+                status = exc.code
+                resp_headers = dict(exc.headers.items()) if exc.headers else {}
+                try:
+                    raw_err = exc.read()
+                except OSError:
+                    raw_err = b""
+                retryable = status in _RETRYABLE_ANY_METHOD or (
+                    idempotent and status in _RETRYABLE_IDEMPOTENT
+                )
+                if retryable and attempt < self.max_retries:
+                    time.sleep(_delay(attempt, resp_headers.get("Retry-After")))
+                    attempt += 1
+                    continue
+                raise _error_from_response(status, raw_err, resp_headers) from None
+            except OSError as exc:  # URLError, timeout, conexão recusada
+                if idempotent and attempt < self.max_retries:
+                    time.sleep(_delay(attempt, None))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"Falha ao conectar à FiscalAPI: {exc}") from exc
+
+
+# ---------------------------------------------------------------- utilitários
+
+
+def _um_documento(**docs: Optional[str]) -> Dict[str, str]:
+    informados = {k: v.strip() for k, v in docs.items() if v is not None and v.strip()}
+    nomes = " ou ".join(docs.keys())
+    if not informados:
+        raise ValueError(f"Informe {nomes}.")
+    if len(informados) > 1:
+        raise ValueError(f"Informe apenas um: {nomes}.")
+    return informados
+
+
+def _uf(uf: str) -> str:
+    if not uf or len(uf.strip()) != 2:
+        raise ValueError("Informe a UF com 2 letras (ex.: MT).")
+    return uf.strip().upper()
+
+
+def _encode_query(params: Mapping[str, Any]) -> str:
+    clean = []
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            value = "true" if value else "false"
+        clean.append((key, str(value)))
+    return urllib.parse.urlencode(clean)
+
+
+def _certificado_base64(cert: Certificado) -> str:
+    if isinstance(cert, (bytes, bytearray)):
+        return base64.b64encode(bytes(cert)).decode("ascii")
+    if isinstance(cert, os.PathLike):
+        with open(cert, "rb") as fh:
+            return base64.b64encode(fh.read()).decode("ascii")
+    if isinstance(cert, str):
+        try:
+            is_file = len(cert) < 4096 and os.path.isfile(cert)
+        except (OSError, ValueError):
+            is_file = False
+        if is_file:
+            with open(cert, "rb") as fh:
+                return base64.b64encode(fh.read()).decode("ascii")
+        return "".join(cert.split())  # já está em base64
+    raise TypeError("certificado deve ser caminho, bytes ou string base64.")
+
+
+def _delay(attempt: int, retry_after: Optional[str]) -> float:
+    if retry_after:
+        try:
+            return min(max(float(retry_after), 0.0), _MAX_RETRY_AFTER)
+        except ValueError:
+            pass
+    base = min(_MAX_BACKOFF, 0.5 * (2 ** attempt))
+    return base + random.uniform(0, base / 4)
+
+
+def _decode_success(raw: bytes) -> Dict[str, Any]:
+    if not raw:
+        return {}
+    try:
+        decoded = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise FiscalAPIError("Resposta da API não é JSON válido.", body=raw[:500]) from exc
+    return decoded if isinstance(decoded, dict) else {"data": decoded}
+
+
+def _error_from_response(status: int, raw: bytes, headers: Mapping[str, str]) -> FiscalAPIError:
+    body: Any
+    try:
+        body = json.loads(raw.decode("utf-8")) if raw else None
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        body = raw.decode("utf-8", errors="replace")[:500]
+
+    code: Optional[str] = None
+    message = f"Erro HTTP {status}"
+    request_id: Optional[str] = None
+    if isinstance(body, dict):
+        code = body.get("error") or body.get("title")
+        detail = body.get("message") or body.get("detail")
+        if isinstance(detail, str) and detail:
+            message = detail
+        elif isinstance(detail, list) and detail:
+            message = "; ".join(str(d.get("msg", d)) if isinstance(d, dict) else str(d) for d in detail)
+        request_id = body.get("request_id") or None
+    elif isinstance(body, str) and body:
+        message = body
+
+    kwargs = dict(status_code=status, code=code, request_id=request_id, body=body, headers=headers)
+    if status in (401, 403):
+        return AuthenticationError(message, **kwargs)
+    if status == 402:
+        return InsufficientBalanceError(message, **kwargs)
+    if status == 429:
+        return RateLimitError(message, **kwargs)
+    if status >= 500:
+        return ServerError(message, **kwargs)
+    if 400 <= status < 500:
+        return BadRequestError(message, **kwargs)
+    return FiscalAPIError(message, **kwargs)

fiscalapi_br/_errors.py

@@ -0,0 +1,99 @@
+"""Exceções levantadas pelo cliente da FiscalAPI."""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+
+class FiscalAPIError(Exception):
+    """Erro base. Toda exceção do SDK herda desta classe.
+
+    Atributos:
+        message: mensagem legível devolvida pela API (ou gerada pelo SDK).
+        status_code: status HTTP (``None`` em falha de conexão).
+        code: código do erro devolvido pela API (ex.: ``PARAMETRO_AUSENTE``).
+        request_id: identificador da requisição — informe-o ao suporte.
+        body: corpo da resposta já decodificado (dict) ou texto bruto.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+        body: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.body = body
+        self.headers = dict(headers or {})
+
+    def __str__(self) -> str:
+        parts = []
+        if self.status_code is not None:
+            parts.append(f"HTTP {self.status_code}")
+        if self.code:
+            parts.append(self.code)
+        prefix = " ".join(parts)
+        suffix = f" (request_id={self.request_id})" if self.request_id else ""
+        return f"{prefix}: {self.message}{suffix}" if prefix else f"{self.message}{suffix}"
+
+
+class AuthenticationError(FiscalAPIError):
+    """Chave de API ausente, inválida ou revogada (HTTP 401/403)."""
+
+
+class InsufficientBalanceError(FiscalAPIError):
+    """Sem plano ativo ou saldo esgotado (HTTP 402).
+
+    ``consultas_restantes`` diz quantas consultas desse tipo o saldo ainda paga
+    (quando a API informa).
+    """
+
+    @property
+    def consultas_restantes(self) -> Optional[int]:
+        if isinstance(self.body, dict):
+            value = self.body.get("consultas_restantes")
+            return value if isinstance(value, int) else None
+        return None
+
+    @property
+    def plan(self) -> Optional[str]:
+        if isinstance(self.body, dict):
+            value = self.body.get("plan")
+            return value if isinstance(value, str) else None
+        return None
+
+
+class RateLimitError(FiscalAPIError):
+    """Limite de requisições por minuto do plano excedido (HTTP 429).
+
+    ``retry_after`` traz, em segundos, quanto esperar antes de tentar de novo.
+    """
+
+    @property
+    def retry_after(self) -> Optional[int]:
+        raw = self.headers.get("Retry-After") or self.headers.get("retry-after")
+        if raw is None and isinstance(self.body, dict):
+            raw = self.body.get("retry_after")
+        try:
+            return int(raw) if raw is not None else None
+        except (TypeError, ValueError):
+            return None
+
+
+class BadRequestError(FiscalAPIError):
+    """Parâmetro ausente, conflitante ou inválido (HTTP 400/404/422)."""
+
+
+class ServerError(FiscalAPIError):
+    """Falha do lado da API ou tempo esgotado na fonte (HTTP 5xx)."""
+
+
+class APIConnectionError(FiscalAPIError):
+    """Não foi possível falar com a API (DNS, TLS, conexão recusada, timeout)."""

fiscalapi_br/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

fiscalapi_br/types.py

@@ -0,0 +1,250 @@
+"""Tipos (TypedDict) das respostas mais usadas da FiscalAPI.
+
+As respostas são dicionários comuns; estes tipos servem para autocompletar no
+editor e para checagem estática. Campos novos podem aparecer sem aviso — o
+SDK não descarta nada do que a API devolve.
+"""
+from __future__ import annotations
+
+from typing import List, Literal, Optional, TypedDict
+
+StatusFonte = Literal["success", "error", "timeout", "skipped"]
+StatusCertidao = Literal[
+    "negativa",
+    "positiva",
+    "positiva_com_efeitos_de_negativa",
+    "nao_contribuinte",
+    "sem_certidao",
+    "erro",
+]
+
+
+class SourceStatus(TypedDict, total=False):
+    status: StatusFonte
+    error_code: str
+    error_message: str
+
+
+class CnaeSecundario(TypedDict, total=False):
+    codigo: str
+    descricao: str
+
+
+class InscricaoEstadual(TypedDict, total=False):
+    inscricao_estadual: str
+    razao_social: str
+    nome_fantasia: str
+    situacao_ie: str
+    uf_ie: str
+    tipo_ie: str
+    logradouro: str
+    complemento: str
+    bairro: str
+    numero: str
+    municipio: str
+    municipio_ibge: str
+    cep: str
+    regime_pagamento: str
+    data_situacao: str
+    situacao_contribuinte: str
+    data_inicio_atividade: str
+    cnae_codigo: str
+    cnae_descricao: str
+    regime_apuracao_icms: str
+    situacao_nfe: str
+    cpf_cnpj: str
+    situacao_cadastral: str
+    cnaes_secundarios: Optional[List[CnaeSecundario]]
+
+
+class ConsultaIEResponse(TypedDict, total=False):
+    request_id: str
+    document: str
+    document_type: str
+    uf: str
+    cached: bool
+    results: List[InscricaoEstadual]
+
+
+class IEPorUF(TypedDict, total=False):
+    uf: str
+    source_status: SourceStatus
+    results: List[InscricaoEstadual]
+
+
+class ConsultaIETodosResponse(TypedDict, total=False):
+    request_id: str
+    document: str
+    document_type: str
+    cached_ufs: List[str]
+    results: List[IEPorUF]
+    complete: bool
+
+
+class CNPJResult(TypedDict, total=False):
+    razao_social: str
+    nome_fantasia: str
+    situacao_cadastral: str
+    data_situacao_cadastral: str
+    cnae_principal_codigo: str
+    cnae_principal_descricao: str
+    cnaes_secundarios: List[dict]
+    natureza_juridica: str
+    capital_social: str
+    endereco: dict
+    qsa: List[dict]
+    porte: str
+
+
+class CNPJResponse(TypedDict, total=False):
+    request_id: str
+    cnpj: str
+    cached: bool
+    source_status: SourceStatus
+    result: Optional[CNPJResult]
+
+
+class Certidao(TypedDict, total=False):
+    status: StatusCertidao
+    status_raw: str
+    validade: str
+    validade_iso: str
+    emissao: str
+    emissao_iso: str
+    protocolo: str
+    pdf_base64: str
+    url_verificacao: str
+    codigo_autenticacao: str
+
+
+class CNDResponse(TypedDict, total=False):
+    request_id: str
+    document: str
+    document_type: str
+    uf: str
+    cached: bool
+    source_status: SourceStatus
+    result: Optional[Certidao]
+
+
+class CNDPorUF(TypedDict, total=False):
+    uf: str
+    source_status: SourceStatus
+    result: Optional[Certidao]
+
+
+class CNDTodosResponse(TypedDict, total=False):
+    request_id: str
+    document: str
+    document_type: str
+    results: List[CNDPorUF]
+
+
+class CertidaoFederal(Certidao, total=False):
+    tipo: Literal["cndt", "cnd_federal", "crf_fgts"]
+    orgao: str
+    modo: Literal["consulta", "emissao"]
+
+
+class CertidaoFederalResponse(TypedDict, total=False):
+    request_id: str
+    document: str
+    document_type: str
+    cached: bool
+    source_status: SourceStatus
+    result: Optional[CertidaoFederal]
+
+
+class CertidoesTodasResponse(TypedDict, total=False):
+    request_id: str
+    document: str
+    document_type: str
+    cnd_estaduais: Optional[CNDTodosResponse]
+    certidoes_federais: List[CertidaoFederalResponse]
+
+
+class NfeXmlResultado(TypedDict, total=False):
+    chave: str
+    status: str
+    cstat: str
+    mensagem: str
+    from_cache: bool
+    manifestacao: Optional[str]
+    xml: Optional[str]
+
+
+class NfeXmlResponse(TypedDict, total=False):
+    request_id: str
+    total: int
+    com_dado: int
+    creditos_cobrados: int
+    resultados: List[NfeXmlResultado]
+
+
+class SigefParcela(TypedDict, total=False):
+    parcel_id: str
+    codigo_parcela: str
+    denominacao: str
+    area_ha: float
+    municipio: str
+    uf: str
+    codigo_ibge: str
+    detentor: str
+    matricula: str
+    cns: str
+    status: str
+    data_certificacao: str
+    natureza: str
+    codigo_sncr: str
+    cartorio: str
+    geometria_wkt: str
+    vertices: List[dict]
+    confrontantes: List[dict]
+
+
+class SigefResult(TypedDict, total=False):
+    total_parcelas: int
+    area_total_ha: float
+    parcelas: List[SigefParcela]
+
+
+class SigefResponse(TypedDict, total=False):
+    request_id: str
+    document: str
+    document_type: str
+    cached: bool
+    source_status: SourceStatus
+    result: Optional[SigefResult]
+
+
+class SigefParcelaResponse(TypedDict, total=False):
+    request_id: str
+    parcel_id: str
+    cached: bool
+    consultado_em: str
+    completo: bool
+    avisos: List[str]
+    source_status: SourceStatus
+    result: Optional[SigefParcela]
+
+
+class CnirResponse(TypedDict, total=False):
+    request_id: str
+    document: str
+    document_type: str
+    source_status: SourceStatus
+    pessoa_fisica: Optional[dict]
+    pessoa_juridica: Optional[dict]
+    imoveis_cafir: List[dict]
+    total_imoveis: int
+    total_imoveis_ativos: int
+
+
+class PerfilProdutorResponse(TypedDict, total=False):
+    request_id: str
+    document: str
+    receita_federal: Optional[CNPJResponse]
+    inscricoes_estaduais: Optional[ConsultaIETodosResponse]
+    cnd_estaduais: Optional[CNDTodosResponse]
+    certidoes_federais: List[CertidaoFederalResponse]
+    cnir: Optional[CnirResponse]

fiscalapi_br-0.1.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: fiscalapi-br
+Version: 0.1.0
+Summary: SDK da FiscalAPI (Brasil): Inscrição Estadual, CNPJ, certidões, NF-e, SIGEF, CNIR e perfil do produtor rural.
+Project-URL: Homepage, https://fiscalapi.com.br
+Project-URL: Documentation, https://docs.fiscalapi.com.br
+Project-URL: Source, https://github.com/fiscaIapi/fiscalapi-python
+Project-URL: Issues, https://github.com/fiscaIapi/fiscalapi-python/issues
+Author-email: FiscalAPI <contato@fiscalapi.com.br>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: brasil,certidao,cnd,cnir,cnpj,fiscalapi,inscricao estadual,nfe,produtor rural,sefaz,sigef
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Portuguese (Brazilian)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# 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 por chave, SIGEF, CNIR e perfil do produtor rural.
+
+- Zero dependências (só a biblioteca padrão).
+- Python 3.9 ou superior.
+- Novas tentativas automáticas em `429` e em falhas temporárias.
+- Erros tipados para chave inválida, falta de saldo e limite de requisições.
+
+## Instalação
+
+```bash
+pip install fiscalapi-br
+```
+
+## Antes de começar
+
+1. Crie sua conta em [app.fiscalapi.com.br](https://app.fiscalapi.com.br) e copie a chave de API no painel.
+2. **O uso pela API exige um plano ativo ou créditos.** As consultas gratuitas do mês valem só no painel; pela API, uma conta sem plano recebe `402` (`InsufficientBalanceError`).
+3. Planos e consumo de créditos: [docs.fiscalapi.com.br](https://docs.fiscalapi.com.br/docs/referencia/plans-and-limits).
+
+## Uso rápido
+
+```python
+from fiscalapi_br import FiscalAPI
+
+api = FiscalAPI("sua-chave")          # ou defina FISCALAPI_API_KEY
+
+resp = api.consultar_ie(uf="MT", cpf="12345678909")
+for ie in resp["results"]:
+    print(ie["inscricao_estadual"], ie["situacao_ie"], ie["municipio"])
+```
+
+## Métodos
+
+| Método | Endpoint | O que retorna |
+|---|---|---|
+| `consultar_ie(uf, cpf=/cnpj=/ie=, secundarias=False)` | `GET /api/consultar` | Inscrições estaduais em uma UF |
+| `consultar_ie_todos(cpf=/cnpj=/ie=, secundarias=False)` | `GET /api/consultar-ie-todos` | Inscrições em todos os estados |
+| `consultar_cnpj(cnpj, force_fresh=False)` | `GET /api/consultar-cnpj` | Dados cadastrais da Receita Federal |
+| `consultar_cnd(uf, cpf=/cnpj=)` | `GET /api/consultar-cnd` | CND estadual (ICMS) com PDF |
+| `consultar_cnd_todos(cpf=/cnpj=)` | `GET /api/consultar-cnd-todos` | CND estadual em todos os estados disponíveis |
+| `consultar_cnd_federal(cpf=/cnpj=, emitir_nova=False)` | `GET /api/consultar-cnd-federal` | CND Federal (Receita Federal + PGFN) |
+| `consultar_cndt(cpf=/cnpj=)` | `GET /api/consultar-cndt` | Certidão de débitos trabalhistas |
+| `consultar_crf_fgts(cpf=/cnpj=)` | `GET /api/consultar-crf-fgts` | Regularidade do FGTS |
+| `consultar_certidoes_todas(cpf=/cnpj=, skip_estaduais=False)` | `GET /api/certidoes-todas` | Todas as certidões em uma chamada |
+| `consultar_nfe_xml(chave, certificado=, senha=, manifestar=True)` | `POST /api/consultar-nfe-xml` | XML completo da NF-e |
+| `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 |
+| `perfil_produtor(cpf=/cnpj=)` | `GET /api/perfil-produtor` | Perfil consolidado do produtor |
+
+Informe **um** documento por chamada (`cpf`, `cnpj` ou, onde couber, `ie`). Pontuação é aceita. Todas as respostas são `dict` com o JSON da API; os tipos em `fiscalapi_br.types` ajudam no autocompletar.
+
+## Exemplos
+
+### Inscrição Estadual em todos os estados
+
+```python
+resp = api.consultar_ie_todos(cnpj="12.345.678/0001-95")
+if not resp.get("complete", True):
+    print("Algum estado não respondeu; tente de novo antes de concluir que não há IE.")
+for uf in resp["results"]:
+    for ie in uf["results"]:
+        print(uf["uf"], ie["inscricao_estadual"], ie["situacao_ie"])
+```
+
+### CNPJ
+
+```python
+empresa = api.consultar_cnpj("12345678000195")
+print(empresa["result"]["razao_social"], empresa["result"]["situacao_cadastral"])
+
+# Dado atual, sem cache (consome mais créditos):
+api.consultar_cnpj("12345678000195", force_fresh=True)
+```
+
+### Certidões com PDF
+
+```python
+import base64
+
+cnd = api.consultar_cnd("MT", cpf="12345678909")
+resultado = cnd["result"]
+print(resultado["status"], resultado["validade_iso"])
+if resultado.get("pdf_base64"):
+    with open("cnd-mt.pdf", "wb") as f:
+        f.write(base64.b64decode(resultado["pdf_base64"]))
+
+federal = api.consultar_cnd_federal(cnpj="12345678000195")
+trabalhista = api.consultar_cndt(cnpj="12345678000195")
+fgts = api.consultar_crf_fgts(cnpj="12345678000195")
+```
+
+O campo `status` vem como `negativa`, `positiva`, `positiva_com_efeitos_de_negativa`, `nao_contribuinte`, `sem_certidao` ou `erro`.
+
+### XML de NF-e por chave
+
+```python
+resp = api.consultar_nfe_xml(
+    "35260112345678000195550010000012341000012345",
+    certificado="certificado.pfx",   # caminho, bytes do arquivo ou base64
+    senha="senha-do-certificado",
+)
+nota = resp["resultados"][0]
+if nota["status"] == "ok":
+    with open(f"{nota['chave']}.xml", "w", encoding="utf-8") as f:
+        f.write(nota["xml"])
+else:
+    print(nota["status"], nota["mensagem"])
+```
+
+O certificado A1 precisa ser de um participante da nota (emitente, destinatário, transportador ou autorizado) e **não é armazenado** pela API. Só há cobrança quando o XML é devolvido.
+
+### Imóvel rural
+
+```python
+sigef = api.consultar_sigef(cpf="12345678909")
+for parcela in (sigef["result"] or {}).get("parcelas", []):
+    print(parcela["denominacao"], parcela["area_ha"], parcela["municipio"], parcela["uf"])
+
+parcela = api.consultar_sigef_parcela("0f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b")
+print(parcela["result"]["geometria_wkt"])
+
+cnir = api.consultar_cnir(cpf="12345678909")
+print(cnir["total_imoveis"], "imóveis")
+```
+
+### Perfil do produtor
+
+```python
+perfil = api.perfil_produtor(cpf="12345678909")
+```
+
+## Status da fonte
+
+Uma resposta `200` pode trazer `source_status.status` diferente de `success` (por exemplo, `timeout` quando o órgão não respondeu a tempo). Confira esse campo antes de concluir que o documento não tem registro.
+
+## Erros
+
+```python
+from fiscalapi_br import (
+    FiscalAPIError, AuthenticationError, InsufficientBalanceError,
+    RateLimitError, BadRequestError, ServerError, APIConnectionError,
+)
+
+try:
+    api.consultar_ie(uf="SP", cnpj="12345678000195")
+except AuthenticationError:
+    ...  # chave ausente, inválida ou revogada (401/403)
+except InsufficientBalanceError as e:
+    print(e.consultas_restantes)  # sem plano ou saldo esgotado (402)
+except RateLimitError as e:
+    print(e.retry_after)  # limite por minuto do plano (429)
+except BadRequestError as e:
+    print(e.code, e.message)  # parâmetro ausente ou inválido (400/422)
+except FiscalAPIError as e:
+    print(e.status_code, e.request_id)  # demais erros; informe o request_id ao suporte
+```
+
+## Novas tentativas e timeout
+
+```python
+api = FiscalAPI("sua-chave", timeout=200, max_retries=3)
+```
+
+- `429`: o SDK espera o tempo do cabeçalho `Retry-After` e tenta de novo.
+- `500`, `502`, `503`, `504` e falhas de rede: novas tentativas com espera exponencial, **só em consultas GET**. A consulta de NF-e (POST) não é repetida automaticamente.
+- Algumas consultas (NF-e, SIGEF) podem levar até 3 minutos; o timeout padrão é 200 s.
+
+## Links
+
+- Documentação: [docs.fiscalapi.com.br](https://docs.fiscalapi.com.br)
+- Painel: [app.fiscalapi.com.br](https://app.fiscalapi.com.br)
+- Suporte: contato@fiscalapi.com.br
+
+## Licença
+
+MIT

fiscalapi_br-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+fiscalapi_br/__init__.py,sha256=eb6jgTWRPuSPmDzuxikMpbOGOhi7REMDuiSxjP_qF2Q,698
+fiscalapi_br/_client.py,sha256=T1rUn4kSs7ohrlghUSeoya8bQjpueoEzF8MBL4YB_3U,16364
+fiscalapi_br/_errors.py,sha256=j5P99VOLWr3POhEfs-9I8759PrV2X6WWoMTggXW8fx8,3266
+fiscalapi_br/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+fiscalapi_br/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fiscalapi_br/types.py,sha256=4E3ZuzqlfVRu4WxSXxChIRw_ieCnoDQZgbINdguLvLw,5636
+fiscalapi_br-0.1.0.dist-info/METADATA,sha256=dWa4hhlvlRm10JAiuUFv630IDQgvb9NtRTe6QuJg0Iw,8298
+fiscalapi_br-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fiscalapi_br-0.1.0.dist-info/licenses/LICENSE,sha256=JYVGpyx18Er2Yj8Io6pcym-gw0pHA0I0wgNl8HiQFmQ,1066
+fiscalapi_br-0.1.0.dist-info/RECORD,,

fiscalapi_br-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

fiscalapi_br-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FiscalAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.