diff --git a/README.md b/README.md index f6fab6e..3f78dc3 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 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. @@ -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 @@ -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 diff --git a/package.json b/package.json index facc5e0..0507f7a 100644 --- a/package.json +++ b/package.json @@ -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", @@ -24,6 +24,7 @@ "cnd", "certidao", "nfe", + "difal", "sigef", "cnir", "produtor-rural", diff --git a/src/client.ts b/src/client.ts index 4db3648..2709325 100644 --- a/src/client.ts +++ b/src/client.ts @@ -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'; @@ -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 { + 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. diff --git a/src/types.ts b/src/types.ts index 5fc3b11..3b18928 100644 --- a/src/types.ts +++ b/src/types.ts @@ -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; diff --git a/src/version.ts b/src/version.ts index ffd80fd..465e390 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '0.3.0'; +export const VERSION = '0.4.0';