@rodrigogs/focusnfe-sdk

SDK TypeScript para a API FocusNFe de emissao de documentos fiscais eletronicos brasileiros (NFe, NFCe, NFSe, CTe, MDFe, NFCom).

English version (coming soon)

Features

• Zero runtime dependencies - Footprint minimo usando APIs nativas do Node.js
• TypeScript-first - Tipagem completa com union types para status e eventos
• ESM-only - Sistema de modulos moderno para tree-shaking otimo
• Error handling - Hierarquia de erros estruturada com deteccao de retry
• Lazy-loaded services - Inicializacao eficiente sob demanda
• Ambientes configuraveis - Troca simples entre HOMOLOGACAO e PRODUCTION
• Native fetch - Sem dependencias de cliente HTTP externo
• 100% coverage - Statements, branches, functions e lines

Instalacao

npm install @rodrigogs/focusnfe-sdk

Requisitos: Node.js >= 20

Quick Start

import { FocusNFeClient } from '@rodrigogs/focusnfe-sdk'

const client = new FocusNFeClient({
  token: process.env.FOCUSNFE_TOKEN!,
  environment: 'HOMOLOGACAO', // Opcional: HOMOLOGACAO ou PRODUCTION (default)
})

// Emitir uma NFe
const nfe = await client.nfe.create('ref-001', {
  natureza_operacao: 'Venda de produto',
  data_emissao: '2026-03-18T10:00:00-03:00',
  tipo_documento: 1,
  finalidade_emissao: 1,
  consumidor_final: 1,
  presenca_comprador: 1,
  cnpj_emitente: '51916585000125',
  items: [
    {
      numero_item: 1,
      codigo_produto: 'PROD001',
      descricao: 'Peca automotiva',
      cfop: '5102',
      codigo_ncm: '87089990',
      quantidade_comercial: 1,
      valor_unitario_comercial: 150.0,
      unidade_comercial: 'UN',
      icms_origem: 0,
      icms_situacao_tributaria: '102',
    },
  ],
  formas_pagamento: [
    { forma_pagamento: '01', valor_pagamento: '150.00' },
  ],
})

console.log('Status:', nfe.status)
console.log('Ref:', nfe.ref)

Configuracao

const client = new FocusNFeClient({
  token: 'seu_token_api',           // Obrigatorio
  environment: 'PRODUCTION',         // Opcional: HOMOLOGACAO | PRODUCTION (default)
  timeout: 30000,                    // Opcional: Timeout em ms (default: 30000)
  baseUrl: 'https://custom.api.com', // Opcional: Sobrescrever URL base
  userAgent: 'MinhaApp/1.0.0',      // Opcional: User agent customizado
  fetch: customFetch,                // Opcional: Implementacao de fetch customizada
})

URLs dos Ambientes

• HOMOLOGACAO: https://homologacao.focusnfe.com.br
• PRODUCTION: https://api.focusnfe.com.br

Servicos

| Servico | Descricao | Exemplo | |---------|-----------|---------| | nfe | Nota Fiscal Eletronica (modelo 55) | client.nfe.create(ref, params) | | nfce | Nota Fiscal de Consumidor Eletronica (modelo 65) | client.nfce.create(ref, params) | | nfse | Nota Fiscal de Servicos Eletronica (municipal) | client.nfse.create(ref, params) | | nfseNacional | NFSe Nacional (padrao nacional) | client.nfseNacional.create(ref, params) | | cte | Conhecimento de Transporte Eletronico + CTe OS | client.cte.create(ref, params) | | mdfe | Manifesto Eletronico de Documentos Fiscais | client.mdfe.create(ref, params) | | nfcom | Nota Fiscal Fatura de Servico de Comunicacao | client.nfcom.create(ref, params) | | nfeRecebidas | NFe recebidas + manifestacao do destinatario | client.nfeRecebidas.list(params) | | cteRecebidas | CTe recebidos + desacordo | client.cteRecebidas.list(params) | | nfseRecebidas | NFSe recebidas | client.nfseRecebidas.list(params) | | empresas | Gerenciamento de empresas | client.empresas.create(params) | | webhooks | Gatilhos/webhooks | client.webhooks.create(params) | | consultas | NCM, CFOP, CEP, CNAE, Municipios, CNPJ, Emails, Backups | client.consultas.ncm(params) |

Error Handling

Todos os erros estendem FocusNFeError com tipos especificos para diferentes cenarios:

import {
  FocusNFeApiError,
  FocusNFeConnectionError,
} from '@rodrigogs/focusnfe-sdk'

try {
  const nfe = await client.nfe.create('ref-001', { /* ... */ })
} catch (error) {
  if (error instanceof FocusNFeApiError) {
    console.error('Erro da API:', error.status, error.mensagem)
    console.error('Detalhes:', error.erros)

    if (error.isAuth) {
      console.error('Token invalido ou sem permissao')
    } else if (error.isRateLimit) {
      console.error('Limite de requisicoes excedido')
    } else if (error.isRetryable) {
      console.error('Erro retentavel, tente novamente')
    }
  } else if (error instanceof FocusNFeConnectionError) {
    console.error('Erro de rede:', error.message)
  }
}

Status Types

O SDK exporta union types para os status de cada tipo de documento:

import type { NfeStatus, NfceStatus, CteStatus, MdfeStatus } from '@rodrigogs/focusnfe-sdk'

// NfeStatus = 'processando_autorizacao' | 'autorizado' | 'cancelado' | 'erro_autorizacao' | 'denegado'
// NfceStatus = 'processando_autorizacao' | 'autorizado' | 'cancelado' | 'erro_autorizacao'
// MdfeStatus = ... | 'encerrado'  (status adicional para MDFe)

Webhooks

// Criar webhook
const hook = await client.webhooks.create({
  cnpj: '51916585000125',
  event: 'nfe',
  url: 'https://meusite.com/webhook/nfe',
})

// Listar, consultar, remover
const hooks = await client.webhooks.list()
const hook = await client.webhooks.get('hook_id')
await client.webhooks.remove('hook_id')

// Reenviar webhook de um documento especifico
await client.nfe.resendWebhook('ref-001')

Consultas Utilitarias

// Buscar NCM por descricao
const ncms = await client.consultas.ncm({ descricao: 'pecas' })

// Consultar CEP
const cep = await client.consultas.cepByCodigo('01001000')

// Verificar status NFSe de um municipio
const municipios = await client.consultas.municipios({
  sigla_uf: 'SP',
  status_nfse: 'ativo',
})

// Consultar CNPJ
const empresa = await client.consultas.cnpj('51916585000125')

Documentacao

Guias

• Primeiros Passos
• Tratamento de Erros
• Webhooks
• Limites de Requisicao

Servicos

• NFe - Nota Fiscal Eletronica

• NFCe - Nota Fiscal de Consumidor

• NFSe - Nota Fiscal de Servicos (municipal)

• NFSe Nacional - NFSe padrao nacional

• CTe - Conhecimento de Transporte + CTe OS

• MDFe - Manifesto de Documentos Fiscais

• NFCom - Nota Fiscal de Comunicacao

• Documentos Recebidos - NFe, CTe e NFSe recebidas

• Empresas - Gerenciamento de empresas

• Consultas - NCM, CFOP, CEP, CNAE, Municipios, CNPJ

• Documentacao Oficial FocusNFe

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

Apache License 2.0