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
27 changes: 25 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -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 e de CT-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, DIFAL de saída por UF, 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.
Expand Down Expand Up @@ -57,12 +57,13 @@ const { FiscalAPI } = require('fiscalapi-br');
| `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 |
| `consultarDifalSaida({ certificado, senha, competencia, ufs? })` | `POST /api/consultar-difal-saida` | DIFAL de saída por UF de destino (Beta) |
| `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`, `CteXmlResponse` etc.).
Informe **um** documento por chamada. Pontuação é aceita. As respostas trazem o JSON completo da API, com tipos exportados (`ConsultaIEResponse`, `CNDResponse`, `NfeXmlResponse`, `CteXmlResponse`, `DifalSaidaResponse` etc.).

## Exemplos

Expand Down Expand Up @@ -164,6 +165,28 @@ if (cte.status === 'ok' && cte.xml) {

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)

```ts
import { readFile } from 'node:fs/promises';

const difal = await api.consultarDifalSaida({
certificado: await readFile('certificado-do-emitente.pfx'), // bytes ou string base64
senha: 'senha-do-certificado',
competencia: '2026-10',
ufs: ['RS', 'SC'], // omita para as 10 UFs
});
for (const uf of difal.ufs) {
console.log(uf.uf, uf.status, uf.valor_em_aberto);
for (const nota of uf.notas.filter((n) => n.em_aberto)) {
console.log(' ', nota.serie, nota.numero, nota.situacao_guia_difal, nota.valor_em_aberto);
}
}
if (!difal.completo) console.log('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

```ts
Expand Down
5 changes: 3 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"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.",
"license": "MIT",
"author": {
"name": "FiscalAPI",
Expand All @@ -24,6 +24,7 @@
"cnd",
"certidao",
"nfe",
"difal",
"sigef",
"cnir",
"produtor-rural",
Expand Down
33 changes: 33 additions & 0 deletions src/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,14 @@ import type {
ConsultaIEResponse,
ConsultaIETodosResponse,
CteXmlResponse,
DifalSaidaResponse,
NfeXmlResponse,
NfseResponse,
PerfilProdutorResponse,
SigefParcelaResponse,
SigefResponse,
SimplesNacionalResponse,
UfDifal,
} from './types.js';
import { VERSION } from './version.js';

Expand Down Expand Up @@ -223,6 +225,37 @@ export class FiscalAPI {
});
}

// ------------------------------------------------------------- DIFAL

/**
* DIFAL de saída (EC 87/2015) por UF de destino, num mês
* (`POST /api/consultar-difal-saida`). Beta. O certificado A1 é o do
* EMITENTE das notas e não é armazenado. `ufs` omitido = as 10 UFs
* atendidas (AC, AP, DF, GO, MS, MT, RR, RS, SC, SE). Cobra 1 consulta por
* UF com `status: 'ok'`. Pode levar cerca de 70 s. Não é repetido
* automaticamente em 5xx.
*/
consultarDifalSaida(params: {
certificado: Certificado;
senha: string;
/** Mês de emissão das notas, `AAAA-MM`. */
competencia: string;
/** UFs de destino. Omitido ou vazio = as 10. */
ufs?: UfDifal[];
}): Promise<DifalSaidaResponse> {
const competencia = (params.competencia ?? '').trim();
if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(competencia)) {
throw new Error('Informe a competência no formato AAAA-MM (ex.: 2026-10).');
}
const ufs = params.ufs?.map((u) => uf(u));
return this.request('POST', '/api/consultar-difal-saida', undefined, {
certificado: certificadoBase64(params.certificado),
senha: params.senha,
competencia,
...(ufs && ufs.length ? { ufs } : {}),
});
}

/**
* NFS-e (padrão nacional) pela chave de acesso, sem certificado
* (`GET /api/consultar-nfse`). Com `danfse: true`, inclui o PDF em base64.
Expand Down
94 changes: 94 additions & 0 deletions src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,100 @@ export interface CteXmlResponse {
creditos_cobrados: number;
}

/** UFs de destino atendidas pelo DIFAL de saída. */
export type UfDifal = 'AC' | 'AP' | 'DF' | 'GO' | 'MS' | 'MT' | 'RR' | 'RS' | 'SC' | 'SE';

/** Situação da guia de um tributo da nota. Só `paga` quita. */
export type SituacaoGuiaDifal =
| 'sem_guia_no_portal'
| 'pendente_pagamento'
| 'paga'
| 'geracao_rejeitada'
| 'aguardando_processamento'
| 'substituida'
| 'guia_gerada'
| 'nao_se_aplica'
| 'desconhecida';

/** ok (cobrada) | parcial, erro, nao_consultada (não cobradas). */
export type StatusUfDifal = 'ok' | 'parcial' | 'erro' | 'nao_consultada';

export interface NotaDifal {
serie: string;
numero: string;
/** AAAA-MM-DD */
data_emissao: string | null;
/** Vencimento do imposto, AAAA-MM-DD. */
vencimento: string | null;
destinatario: string;
uf_destino: string;
valor_total: number | null;
valor_difal: number | null;
valor_fcp: number | null;
situacao_guia_difal: SituacaoGuiaDifal;
situacao_guia_fcp: SituacaoGuiaDifal;
/** Sem guia no portal (menos em DF, GO e MT), ou guia pendente de pagamento ou rejeitada. */
em_aberto: boolean;
valor_em_aberto: number;
/**
* Guia existe, mas o pagamento não foi confirmado; em DF, GO e MT, também a nota
* sem guia no portal (lá a guia é emitida no sistema da SEFAZ). Fora do valor em aberto.
*/
a_conferir: boolean;
valor_a_conferir: number;
}

export interface GuiaDifal {
numero: string;
vencimento_imposto: string | null;
data_limite_pagamento: string | null;
uf: string;
tributo: string;
valor: number | null;
/** paga | pendente_pagamento | geracao_rejeitada | aguardando_processamento | substituida */
situacao: string | null;
}

export interface UfDifalResultado {
uf: string;
status: StatusUfDifal;
mensagem: string;
total_documentos: number;
valor_difal: number;
valor_fcp: number;
valor_em_aberto: number;
notas_em_aberto: number;
valor_a_conferir: number;
notas_a_conferir: number;
notas: NotaDifal[];
guias: GuiaDifal[];
}

export interface DifalSaidaResponse {
request_id: string;
fonte: string;
/** CNPJ ou CPF do titular do certificado. */
emitente_tipo: string;
emitente_documento: string;
/** AAAA-MM */
competencia: string;
periodo_inicio: string;
periodo_fim: string;
total_documentos: number;
valor_difal: number;
valor_fcp: number;
valor_em_aberto: number;
notas_em_aberto: number;
valor_a_conferir: number;
notas_a_conferir: number;
/** `true` só quando todas as UFs pedidas vieram `ok`. */
completo: boolean;
ufs: UfDifalResultado[];
avisos: string[];
/** Consultas usadas: 1 por UF com `status: 'ok'`. */
creditos_cobrados: number;
}

export interface SigefParcela {
parcel_id?: string;
codigo_parcela?: string;
Expand Down
2 changes: 1 addition & 1 deletion src/version.ts
Original file line number Diff line number Diff line change
@@ -1 +1 @@
export const VERSION = '0.3.0';
export const VERSION = '0.4.0';
Loading