zfiscoo-sdk

TypeScript SDK do Fiscal Gateway — emissão async-native de NFC-e/NF-e/NFS-e no Brasil.

ESM nativo, fetch puro (sem axios), zero deps. Funciona em Node 18+, Bun, Deno e browser.

Install

npm install zfiscoo-sdk
# ou
pnpm add zfiscoo-sdk
# ou
bun add zfiscoo-sdk

Uso básico

import { FiscalClient } from 'zfiscoo-sdk';

const fiscal = new FiscalClient({
  apiKey: process.env.FISCAL_KEY!,
  baseUrl: 'https://api.zfiscoo.zek.app.br', // omitir = produção
});

// 1. Cria emissor (uma vez por CNPJ)
const issuer = await fiscal.issuers.create({
  cnpj: '12345678000199',
  razao_social: 'Restaurante X LTDA',
  ie: '123456789',
  regime_tributario: 'simples_nacional',
  endereco: {
    cep: '01310100',
    logradouro: 'Av Paulista',
    numero: '1000',
    bairro: 'Bela Vista',
    municipio: 'São Paulo',
    municipio_codigo: '3550308',
    uf: 'SP',
  },
  cfop_padrao: '5102',
});

// 2. Emite NFC-e (POST recebe 202, processamento async)
const issued = await fiscal.nfce.issue({
  issuer_id: issuer.id,
  external_ref: 'pedido-12345',
  items: [
    {
      codigo: 'X-001',
      descricao: 'X-Burger',
      ncm: '21069090',
      quantidade: 1,
      valor_unitario: 25.0,
    },
  ],
  payments: [{ tipo: 'pix', valor: 25.0 }],
});

// 3. Aguarda status terminal (authorized | denied | failed | cancelled)
const final = await fiscal.nfce.waitForFinal(issued.id);
console.log(final.status); // 'authorized'
console.log(final.chave_acesso); // '35260112345...'

Idempotency

Pra evitar duplicação em retry:

await fiscal.nfce.issue(
  { issuer_id: '...', items: [...], payments: [...] },
  { idempotencyKey: 'pedido-12345' }, // mesma key + mesmo body = mesma resposta
);

Streaming (SSE)

for await (const event of fiscal.nfce.stream(invoiceId)) {
  console.log(event); // { type: 'sefaz_request', data: { ... } }
  if (event.type === 'authorized') break;
}

Webhooks

Em vez de polling, configure um endpoint pra receber:

await fiscal.webhooks.create({
  url: 'https://seu-app.com/fiscal-webhook',
  events: ['invoice.authorized', 'invoice.denied', 'invoice.cancelled'],
});

O SDK retorna secret na criação — use pra validar HMAC:

import { verifyWebhookSignature } from 'zfiscoo-sdk';

const isValid = verifyWebhookSignature({
  body: rawBody,
  signature: req.headers['x-fiscal-signature'],
  secret: SAVED_SECRET,
});

API reference completa

Docs interativas (Swagger): https://api.zfiscoo.zek.app.br/docs

Compatibilidade

| Ambiente | Suportado | |---|---| | Node 18+ | ✅ | | Node 20+ | ✅ | | Bun | ✅ | | Deno | ✅ | | Browser (com cors-proxy) | ✅ |

License

MIT