From 192cc35f9a726076233014ece8ece2b68a7a7558 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Eduardo?= Date: Sun, 15 Nov 2026 22:38:37 -0300 Subject: [PATCH 1/3] =?UTF-8?q?feat:=20m=C3=A9todo=20consultarCteXml=20par?= =?UTF-8?q?a=20o=20XML=20de=20CT-e=20por=20chave?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 24 ++++++++++++++++++++++-- src/client.ts | 20 ++++++++++++++++++++ src/types.ts | 11 +++++++++++ 3 files changed, 53 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f8f316a..f6fab6e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # FiscalAPI — SDK Node.js / TypeScript -Cliente JavaScript/TypeScript 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 JavaScript/TypeScript 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: usa o `fetch` nativo (Node 18+, Bun, Deno, edge runtimes). - Tipado em TypeScript, com ESM e CommonJS. @@ -56,12 +56,13 @@ const { FiscalAPI } = require('fiscalapi-br'); | `consultarSimplesNacional({ cnpj })` | `GET /api/consultar-simples-nacional` | Situação no Simples Nacional e SIMEI | | `consultarNfse({ chave, danfse? })` | `GET /api/consultar-nfse` | NFS-e (padrão nacional) por chave, sem certificado | | `consultarNfeXml({ chave, certificado, senha, manifestar? })` | `POST /api/consultar-nfe-xml` | XML completo da NF-e | +| `consultarCteXml({ chave, certificado, senha })` | `POST /api/consultar-cte-xml` | XML completo do CT-e | | `consultarSigef({ cpf \| cnpj })` | `GET /api/consultar-sigef` | Parcelas certificadas no SIGEF/INCRA | | `consultarSigefParcela({ uuid, forceFresh? })` | `GET /api/consultar-sigef-parcela` | Uma parcela com polígono, vértices e confrontantes | | `consultarCnir({ cpf \| cnpj })` | `GET /api/consultar-cnir` | Imóveis rurais no CNIR/CAFIR | | `perfilProdutor({ cpf \| cnpj })` | `GET /api/perfil-produtor` | Perfil consolidado do produtor | -Informe **um** documento por chamada. Pontuação é aceita. As respostas trazem o JSON completo da API, com tipos exportados (`ConsultaIEResponse`, `CNDResponse`, `NfeXmlResponse` etc.). +Informe **um** documento por chamada. Pontuação é aceita. As respostas trazem o JSON completo da API, com tipos exportados (`ConsultaIEResponse`, `CNDResponse`, `NfeXmlResponse`, `CteXmlResponse` etc.). ## Exemplos @@ -144,6 +145,25 @@ if (nota.status === 'ok' && nota.xml) { 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 + +```ts +import { readFile, writeFile } from 'node:fs/promises'; + +const cte = await api.consultarCteXml({ + chave: '51261011222333000181570010000001231123456784', + certificado: await readFile('certificado.pfx'), // bytes ou string base64 + senha: 'senha-do-certificado', +}); +if (cte.status === 'ok' && cte.xml) { + await writeFile(`${cte.chave}.xml`, cte.xml, 'utf8'); +} else { + console.log(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 ```ts diff --git a/src/client.ts b/src/client.ts index bacb9ca..2b4d659 100644 --- a/src/client.ts +++ b/src/client.ts @@ -16,6 +16,7 @@ import type { CNPJResponse, ConsultaIEResponse, ConsultaIETodosResponse, + CteXmlResponse, NfeXmlResponse, NfseResponse, PerfilProdutorResponse, @@ -202,6 +203,25 @@ export class FiscalAPI { }); } + /** + * XML completo de um CT-e, CT-e OS ou GTV-e pela chave de acesso + * (`POST /api/consultar-cte-xml`). O certificado A1 precisa ser de um + * participante do documento e não é armazenado. Só há cobrança quando o XML + * é devolvido. Não é repetido automaticamente em 5xx. + */ + consultarCteXml(params: { + chave: string; + certificado: Certificado; + senha: string; + }): Promise { + if (!params.chave) throw new Error('Informe a chave de acesso.'); + return this.request('POST', '/api/consultar-cte-xml', undefined, { + chave: params.chave.replace(/\D/g, ''), + certificado: certificadoBase64(params.certificado), + senha: params.senha, + }); + } + /** * NFS-e (padrão nacional) pela chave de acesso, sem certificado * (`GET /api/consultar-nfse`). Com `danfse: true`, inclui o PDF em base64. diff --git a/src/types.ts b/src/types.ts index 2e0da02..864c4cb 100644 --- a/src/types.ts +++ b/src/types.ts @@ -181,6 +181,17 @@ export interface NfeXmlResponse { resultados: NfeXmlResultado[]; } +export interface CteXmlResponse { + request_id: string; + chave: string; + /** ok | nao_autorizado | nao_encontrado | erro */ + status: string; + /** XML completo (cteProc), presente quando `status === 'ok'`. */ + xml?: string | null; + mensagem?: string; + creditos_cobrados: number; +} + export interface SigefParcela { parcel_id?: string; codigo_parcela?: string; From 4b63a26d590bfa875d33b42c78ca9af41f1b4289 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Eduardo?= Date: Sun, 15 Nov 2026 22:45:15 -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 --- src/client.ts | 3 ++- src/types.ts | 3 +-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/client.ts b/src/client.ts index 2b4d659..4db3648 100644 --- a/src/client.ts +++ b/src/client.ts @@ -216,7 +216,8 @@ export class FiscalAPI { }): Promise { if (!params.chave) throw new Error('Informe a chave de acesso.'); return this.request('POST', '/api/consultar-cte-xml', undefined, { - chave: params.chave.replace(/\D/g, ''), + // Aceita CNPJ alfanumérico: só tira separadores e põe em maiúsculas. + chave: params.chave.replace(/[^0-9A-Za-z]/g, '').toUpperCase(), certificado: certificadoBase64(params.certificado), senha: params.senha, }); diff --git a/src/types.ts b/src/types.ts index 864c4cb..5fc3b11 100644 --- a/src/types.ts +++ b/src/types.ts @@ -184,8 +184,7 @@ export interface NfeXmlResponse { export interface CteXmlResponse { request_id: string; chave: string; - /** ok | nao_autorizado | nao_encontrado | erro */ - status: string; + status: 'ok' | 'nao_autorizado' | 'nao_encontrado' | 'erro'; /** XML completo (cteProc), presente quando `status === 'ok'`. */ xml?: string | null; mensagem?: string; From 35681dcbe80bd98707f77060044fad800e24f911 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(consultarCt?= =?UTF-8?q?eXml)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- package.json | 2 +- src/version.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 6828d5f..facc5e0 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "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.", "license": "MIT", "author": { diff --git a/src/version.ts b/src/version.ts index 8e1492f..ffd80fd 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '0.2.0'; +export const VERSION = '0.3.0';