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 e
Autenticação.
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.
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 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.
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 e Ciclo de vida da
nota para os estados possíveis, e
Emissão de NF-e, Emissão de
NFC-e e Emissão de
NFS-e para os detalhes de cada tipo.