From 6e9ae38115e59a24fb7ec88ec5cd4a8b9167c9cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Eduardo?= Date: Sun, 15 Nov 2026 22:38:32 -0300 Subject: [PATCH 1/3] =?UTF-8?q?feat:=20m=C3=A9todo=20consultar=5Fcte=5Fxml?= =?UTF-8?q?=20para=20o=20XML=20de=20CT-e=20por=20chave?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 20 +++++++++++++++++++- src/fiscalapi_br/_client.py | 27 +++++++++++++++++++++++++++ src/fiscalapi_br/types.py | 9 +++++++++ 3 files changed, 55 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a9d973e..8cbf01a 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 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, 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. @@ -47,6 +47,7 @@ for ie in resp["results"]: | `consultar_simples_nacional(cnpj)` | `GET /api/consultar-simples-nacional` | Situação no Simples Nacional e SIMEI | | `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_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 | @@ -133,6 +134,23 @@ else: 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. +### XML de CT-e por chave + +```python +cte = api.consultar_cte_xml( + "51261011222333000181570010000001231123456784", + certificado="certificado.pfx", # caminho, bytes do arquivo ou base64 + senha="senha-do-certificado", +) +if cte["status"] == "ok": + with open(f"{cte['chave']}.xml", "w", encoding="utf-8") as f: + f.write(cte["xml"]) +else: + print(cte["status"], cte["mensagem"]) +``` + +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. + ### Imóvel rural ```python diff --git a/src/fiscalapi_br/_client.py b/src/fiscalapi_br/_client.py index 03beea1..79d80d0 100644 --- a/src/fiscalapi_br/_client.py +++ b/src/fiscalapi_br/_client.py @@ -30,6 +30,7 @@ CNPJResponse, ConsultaIEResponse, ConsultaIETodosResponse, + CteXmlResponse, NfeXmlResponse, NfseResponse, PerfilProdutorResponse, @@ -241,6 +242,32 @@ def consultar_nfe_xml( # 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)) + def consultar_cte_xml( + self, + chave: str, + *, + certificado: Certificado, + senha: str, + ) -> CteXmlResponse: + """XML completo de um CT-e, CT-e OS ou GTV-e pela chave de acesso (``POST /api/consultar-cte-xml``). + + Args: + chave: chave de acesso com 44 dígitos. + certificado: certificado A1 (.pfx/.p12) do participante do documento — + caminho do arquivo, ``bytes`` do arquivo ou o conteúdo já em + base64. O certificado não é armazenado pela API. + senha: senha do certificado. + """ + 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, + } + # POST não é repetido em 5xx. + return cast(CteXmlResponse, self._request("POST", "/api/consultar-cte-xml", 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/types.py b/src/fiscalapi_br/types.py index f6067de..cab1d0d 100644 --- a/src/fiscalapi_br/types.py +++ b/src/fiscalapi_br/types.py @@ -181,6 +181,15 @@ class NfeXmlResponse(TypedDict, total=False): resultados: List[NfeXmlResultado] +class CteXmlResponse(TypedDict, total=False): + request_id: str + chave: str + status: str # ok | nao_autorizado | nao_encontrado | erro + xml: Optional[str] # cteProc completo, só com status "ok" + mensagem: str + creditos_cobrados: int + + class SigefParcela(TypedDict, total=False): parcel_id: str codigo_parcela: str From 9e0b755ad460f3abe249e5eb107ebb9355e5f99c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Eduardo?= Date: Sun, 15 Nov 2026 22:45:18 -0300 Subject: [PATCH 2/3] =?UTF-8?q?fix:=20chave=20do=20CT-e=20aceita=20CNPJ=20?= =?UTF-8?q?alfanum=C3=A9rico=20(tira=20s=C3=B3=20separadores)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- src/fiscalapi_br/_client.py | 3 ++- src/fiscalapi_br/types.py | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8cbf01a..2e649ad 100644 --- a/README.md +++ b/README.md @@ -144,7 +144,7 @@ cte = api.consultar_cte_xml( ) if cte["status"] == "ok": with open(f"{cte['chave']}.xml", "w", encoding="utf-8") as f: - f.write(cte["xml"]) + f.write(cte.get("xml") or "") else: print(cte["status"], cte["mensagem"]) ``` diff --git a/src/fiscalapi_br/_client.py b/src/fiscalapi_br/_client.py index 79d80d0..96001e6 100644 --- a/src/fiscalapi_br/_client.py +++ b/src/fiscalapi_br/_client.py @@ -261,7 +261,8 @@ def consultar_cte_xml( if not chave: raise ValueError("Informe a chave de acesso.") body = { - "chave": "".join(ch for ch in chave if ch.isdigit()), + # Aceita CNPJ alfanumérico: só tira separadores e põe em maiúsculas. + "chave": "".join(ch for ch in chave if ch.isascii() and ch.isalnum()).upper(), "certificado": _certificado_base64(certificado), "senha": senha, } diff --git a/src/fiscalapi_br/types.py b/src/fiscalapi_br/types.py index cab1d0d..188fbbd 100644 --- a/src/fiscalapi_br/types.py +++ b/src/fiscalapi_br/types.py @@ -184,7 +184,7 @@ class NfeXmlResponse(TypedDict, total=False): class CteXmlResponse(TypedDict, total=False): request_id: str chave: str - status: str # ok | nao_autorizado | nao_encontrado | erro + status: Literal["ok", "nao_autorizado", "nao_encontrado", "erro"] xml: Optional[str] # cteProc completo, só com status "ok" mensagem: str creditos_cobrados: int From 9456eceec2936b599c2825d521ba534901185612 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Eduardo?= Date: Mon, 16 Nov 2026 08:51:10 -0300 Subject: [PATCH 3/3] =?UTF-8?q?chore:=20vers=C3=A3o=200.3.0=20(consultar?= =?UTF-8?q?=5Fcte=5Fxml)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pyproject.toml | 2 +- src/fiscalapi_br/_version.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index a372e80..530bc6e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "fiscalapi-br" -version = "0.2.0" +version = "0.3.0" description = "SDK da FiscalAPI (Brasil): Inscrição Estadual, CNPJ, certidões, NF-e, SIGEF, CNIR e perfil do produtor rural." readme = "README.md" license = "MIT" diff --git a/src/fiscalapi_br/_version.py b/src/fiscalapi_br/_version.py index d3ec452..493f741 100644 --- a/src/fiscalapi_br/_version.py +++ b/src/fiscalapi_br/_version.py @@ -1 +1 @@ -__version__ = "0.2.0" +__version__ = "0.3.0"