Roteamento multi-host
A plataforma NFE.io expõe várias APIs em hosts diferentes. O SDK roteia cada
recurso automaticamente para o host certo — nenhum recurso hard-codeia uma
URL. Cada recurso declara uma família (api_family) e obtém seu host a
partir da Nfe::Configuration.
Famílias, hosts e recursos
| Família | Host | Recursos |
|---|---|---|
main | api.nfe.io (/v1) | service_invoices, service_invoices_rtc, entidades (companies, legal/natural people), webhooks |
cte | api.nfse.io (/v2) | product_invoices, product_invoices_rtc, consumer_invoices, transportation_invoices, inbound_product_invoices, tax_calculation, tax_codes, state_taxes |
addresses | address.api.nfe.io/v2 | consulta de endereços (CEP) |
legal-entity | legalentity.api.nfe.io | consulta de pessoa jurídica (CNPJ) |
natural-person | naturalperson.api.nfe.io | consulta de pessoa física (CPF) |
nfe-query | nfe.api.nfe.io | product_invoice_query, consumer_invoice_query |
Para a família main, o /v1 é fornecido pelo api_version de cada recurso,
não pelo host. O host de addresses já embute o /v2.
Modelo de duas chaves
O SDK usa duas chaves de API. As famílias de dados preferem data_api_key
(com fallback para api_key); todas as outras famílias usam api_key.
As famílias de dados são:
addresseslegal-entitynatural-personnfe-query
client = Nfe::Client.new(
api_key: ENV.fetch("NFE_API_KEY"),
data_api_key: ENV.fetch("NFE_DATA_API_KEY")
)
Qualquer das chaves pode vir das variáveis de ambiente NFE_API_KEY /
NFE_DATA_API_KEY (o argumento explícito sempre vence).
:cte NÃO é família de dadosA família :cte (api.nfse.io — emissão de NF-e/NFC-e/CT-e + regras de imposto,
tax codes e state taxes) usa a api_key principal, e não a data_api_key.
Neste SDK a emissão é uma capacidade central, não uma consulta de dados. Isso é
uma divergência deliberada do SDK Node (que roteia api.nfse.io pela cadeia
de fallback da chave de dados).
Escape hatch: base_url_overrides
Para apontar uma família para outro host (ambiente de testes próprio, proxy,
mock), use base_url_overrides: na configuração. Um override por família vence
o host padrão:
client = Nfe::Client.new(
api_key: ENV.fetch("NFE_API_KEY"),
base_url_overrides: {
cte: "https://mock.local/nfse"
}
)
Uma família desconhecida cai no host main como padrão seguro.
Próximos passos
- Downloads — por que
product_invoices(hostcte) devolve uma URI em vez de bytes. - Emissão RTC — os recursos RTC e seus hosts.
- Paginação — formas de paginação por família.