Biblioteca Ruby NFE.io

SDK oficial da NFE.io para Ruby: emissão e gestão de documentos fiscais eletrônicos brasileiros (NFS-e, NF-e, NFC-e, CT-e) com ergonomia estilo Stripe e zero dependências de runtime.

• Cliente único Nfe::Client com acessores snake_case por recurso.
• Tipado — assinaturas RBS empacotadas no gem; type-check com Steep.
• Modelos imutáveis (Data.define) gerados das specs OpenAPI oficiais.

Requisitos

• Ruby 3.2 ou superior.
• Zero dependências de runtime — apenas a biblioteca padrão do Ruby.

Instalação

# Gemfile
gem "nfe-io", "~> 1.0"

bundle install   # ou: gem install nfe-io

Primeiros passos

require "nfe"

client = Nfe::Client.new(api_key: ENV.fetch("NFE_API_KEY"))

result = client.service_invoices.create(
  company_id: "55df4dc6b6cd9007e4f13ee8",
  data: {
    cityServiceCode: "2690",
    description: "Manutenção e suporte técnico",
    servicesAmount: 100.0,
    borrower: { federalTaxNumber: "191", name: "Banco do Brasil SA" }
  }
)

O fluxo completo (retorno discriminado + polling) está em Primeiros passos.

Guias

Guia	Conteúdo
Primeiros passos	Instalação, cliente, primeira emissão e polling.
Configuração	Todas as opções, modelo de duas chaves, fallback de ENV, TLS/proxy.
Emissão assíncrona e polling	Contrato 202 Pending/Issued e o laço de polling com FlowStatus.
Tratamento de erros	Hierarquia Nfe::Error e padrões de rescue.
Webhooks	Verificação HMAC-SHA1 e idempotência/replay.
Paginação	Estilos page e cursor; ListResponse enumerável.
Downloads	Bytes binários vs. NfeFileResource.
Roteamento multi-host	Os hosts por família de recurso.
Emissão RTC	IBS/CBS/IS; leiaute ibsCbs/IBSCBS.
Cookbook por recurso	Um exemplo por recurso (os 17 canônicos + RTC).

Referência da API

A referência completa de classes e métodos é gerada com YARD a partir do código-fonte (e dos comentários YARD):

bundle exec rake doc   # gera docs/api/

A versão publicada fica em /api/ruby/ (HTML estático).

Migração

Vindo da série 0.x? Veja o guia de migração — a v1.0 é uma reescrita greenfield, sem camada de compatibilidade.