> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spedy.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Conceitos e modelo de dados

> Principais conceitos e modelo de dados da API da Spedy.

A API da Spedy é organizada em torno de algumas entidades principais. Entender
como elas se relacionam ajuda a decidir em que ordem configurar sua integração e
onde procurar cada informação na referência.

Um detalhe importante: algumas entidades vivem no nível da **conta** (o seu
cadastro na Spedy) e são compartilhadas por todas as empresas — é o caso de
**clientes** e **produtos**. Outras são específicas de cada **empresa** — como
certificado, configurações, vendas e notas.

```mermaid theme={null}
graph TD
  Conta["Conta"]
  Empresa["Empresa<br/>/v1/companies"]
  Certificado["Certificado digital<br/>/v1/companies/{id}/certificates"]
  Config["Configurações de emissão<br/>/v1/companies/{id}/settings"]
  Cliente["Cliente<br/>/v1/customers"]
  Produto["Produto<br/>/v1/products"]
  Venda["Venda<br/>/v1/orders"]
  Nota["Nota fiscal<br/>NF-e / NFC-e / NFS-e"]

  Conta -->|possui| Empresa
  Conta -->|compartilha| Cliente
  Conta -->|compartilha| Produto
  Empresa -->|tem um| Certificado
  Empresa -->|tem uma| Config
  Cliente -->|participa da| Venda
  Produto -->|compõe a| Venda
  Venda -->|gera| Nota
  Empresa -->|emite a| Nota
```

## Empresa

A empresa (`Company`) é o emissor dos documentos fiscais: chave de API,
certificado, configurações, vendas e notas pertencem a uma empresa específica.
Clientes e produtos são a exceção — pertencem à conta e são compartilhados por
todas as empresas (veja abaixo).

A primeira empresa — a **empresa titular** — é criada quando você assina a
Spedy, e a chave dela (disponível no backoffice) é a única que pode gerenciar
empresas. Empresas adicionais são criadas via `POST /v1/companies` usando a
chave da titular; cada empresa tem sua própria `X-Api-Key`, que opera apenas
aquela empresa. Veja [Configuração
inicial](/pages/guides/configuracao-inicial) e
[Autenticação](/pages/start/autenticacao).

## Certificado digital

Cada empresa tem, no máximo, **um** certificado digital A1 (`.pfx`) vigente.
Você pode enviar novos certificados via `POST /v1/companies/{id}/certificates`,
mas apenas o **último enviado** fica ativo — ele substitui o anterior. O
certificado é necessário para assinar NF-e e NFC-e, e para NFS-e em municípios
que o exigem. Veja [Certificado digital](/pages/guides/certificado-digital).

## Configurações de emissão

As configurações (`CompanySettingsDto`, via `PUT /v1/companies/{id}/settings`)
controlam como a empresa emite cada modelo de nota — numeração, série,
ambiente, CSC, credenciais de provedor municipal — organizadas nos blocos
`serviceInvoice`, `productInvoice`, `consumerInvoice` e `general`. Veja
[Configuração inicial](/pages/guides/configuracao-inicial) para o detalhe de
cada bloco.

## Cliente

O cliente (`Customer`, `/v1/customers`) é o destinatário da nota. Pertence à
**conta** e é compartilhado por todas as empresas. Pode ser pessoa física,
jurídica ou um destinatário no exterior — neste caso identificado pelo país no
endereço, com o campo `federalTaxNumber` acomodando o documento de
identificação estrangeiro no lugar do CPF/CNPJ (usado em exportação e serviços
prestados ao exterior).
Pode ser cadastrado antecipadamente ou informado diretamente dentro do payload
de uma venda.

## Produto

O produto (`/v1/products`) representa um item de catálogo com os dados
fiscais que costumam se repetir entre vendas (NCM, código, descrição). Assim
como o cliente, pertence à **conta** (compartilhado por todas as empresas) e
também pode ser referenciado por uma venda sem cadastro prévio, informando os
dados do item diretamente.

## Venda

A venda (`Order`, `/v1/orders`) é o registro comercial da operação —
cliente, itens, valores, forma de pagamento — e é o caminho mais simples
para emitir uma nota: ao criar a venda, você pode configurar emissão
automática (`autoIssueMode`) ou disparar a emissão explicitamente via `POST
/v1/orders/{id}/invoices/issue`. Veja [Fluxo de
emissão](/pages/guides/fluxo-de-emissao).

## Nota fiscal

A nota fiscal é o documento fiscal emitido — NF-e (`product-invoices`), NFC-e
(`consumer-invoices`) ou NFS-e (`service-invoices`), cada uma com seu próprio
conjunto de endpoints. A emissão é sempre assíncrona; veja [Síncrono vs
assíncrono](/pages/guides/sincrono-vs-assincrono) e [Ciclo de vida da
nota](/pages/guides/ciclo-de-vida-da-nota) para os estados possíveis, e
[Emissão de NF-e](/pages/guides/emissao-nfe), [Emissão de
NFC-e](/pages/guides/emissao-nfce) e [Emissão de
NFS-e](/pages/guides/emissao-nfse) para os detalhes de cada tipo.