Modelo de Dados e Entidades

Entidades da API NFER e como se relacionam.

A API do NFER foi estruturada sobre um modelo relacional limpo e consistente, desenhado para acomodar desde pequenos sistemas de faturamento até plataformas SaaS multi-tenant e marketplaces de alta escala.

Diagrama Estrutural de Entidades

Account / Organization (Conta Master)
  ├── Company (Empresa Emissora / Tenant)
  │     ├── Certificado A1 (.pfx) & CSC
  │     ├── Séries & Numeração Fiscal
  │     │
  │     ├── Customer (Clientes / Destinatários)
  │     ├── Product (Produtos & Perfis Fiscais)
  │     ├── Service (Serviços Municipais)
  │     │
  │     ├── Documentos Fiscais (Emissão Outbound)
  │     │     ├── NF-e (Modelo 55 - Mercantil / E-commerce)
  │     │     ├── NFC-e (Modelo 65 - Cupom de Varejo / PDV)
  │     │     ├── NFS-e (Padrão Nacional ADN)
  │     │     └── CT-e (Modelo 57 - Carga & Frete)
  │     │
  │     ├── Monitor Fiscal (Documentos Recebidos / Inbound)
  │     │     ├── NF-e Recebidas & Eventos MD-e
  │     │     ├── NFS-e Tomadas
  │     │     └── CT-e Fretes & Desacordo
  │     │
  │     └── Webhooks (Endpoints HTTPS & Assinatura HMAC)
  │           └── Deliveries (Tentativas de Entrega & Logs)

Principais Entidades

Entidade	Identificador	Papel no Sistema
Company	`UUID v4`	Representa a pessoa jurídica emissora (CNPJ). Armazena o certificado A1, tokens CSC, configurações fiscais e contadores de séries.
Customer	`UUID v4`	Destinatário ou tomador do serviço. Pode ser pré-cadastrado via API ou enviado inline diretamente no JSON da nota.
Product / Service	`UUID v4`	Itens comercializados. Produtos contêm NCM, CEST e regras de ICMS; Serviços contêm cTribNac (6 dígitos) e alíquota de ISS.
FiscalProfile	`UUID v4`	Motor de inteligência tributária que resolve automaticamente CFOP, CST e CSOSN com base na UF de destino e tipo de cliente.
Document (DF-e)	`UUID v4`	O registro fiscal da nota. Possui ciclo de vida próprio, histórico de XMLs (assinado e protocolado) e links públicos de DANFE.
Webhook	`UUID v4`	Ponto de escuta configurado com URL HTTPS e chave secreta para recebimento de eventos assinados via HMAC-SHA256.
Delivery	`UUID v4`	Registro imutável de cada tentativa de entrega de webhook, com código HTTP, payload enviado e tempo de resposta.

IDs e Imutabilidade

Todos os registros gerados pela API utilizam UUID v4 como chave primária. Chaves de acesso da SEFAZ (44 dígitos para NF-e/NFC-e/CT-e e 50 dígitos para NFS-e) são geradas automaticamente na assinatura e mantidas imutáveis no banco de dados.

Próximos Passos

Entenda os status e transições dos documentos em Ciclo de Vida & Fluxo Assíncrono.
Veja como evitar notas duplicadas na integração em Evitando Duplicidade.