Skip to main content
Esta seção documenta cada endpoint da API da Spedy: parâmetros, corpo da requisição, schema da resposta e códigos de erro possíveis. Todos os endpoints são gerados automaticamente a partir da especificação OpenAPI, no grupo Endpoints do menu ao lado. Para o passo a passo com prosa e exemplos de cada fluxo, veja os guias de emissão (NF-e, NFC-e e NFS-e). Se você ainda não emitiu nenhuma nota, comece pelos primeiros passos antes de usar esta referência — ela assume que você já tem uma chave de API e uma empresa configurada.

​
Base URLs

A API da Spedy tem dois ambientes, cada um com sua própria base URL e suas próprias chaves de API:
Todos os exemplos desta referência usam a base URL de sandbox. Veja Ambiente de testes para as diferenças entre os dois ambientes e o checklist de produção antes de trocar para produção.

​
Autenticação

Toda requisição precisa do header X-Api-Key com a chave de API da sua empresa:
Não há OAuth nem tokens temporários — é uma chave estática por empresa e por ambiente. Veja Autenticação para como obter e gerenciar a chave.

​
Convenções

  • Requisições e respostas usam JSON, exceto upload de certificado digital, que usa multipart/form-data.
  • Campos seguem camelCase (federalTaxNumber, unitAmount).
  • Datas e horários seguem ISO-8601 (2026-07-31T10:00:00Z).
  • IDs de recursos são UUIDs.
Veja Exemplos de requisição para exemplos completos de request e response.

​
Paginação

Endpoints de listagem (ex.: GET /v1/product-invoices, GET /v1/customers) usam paginação por página, com dois parâmetros de query: A resposta vem em um envelope *PagedList (ex.: ProductInvoiceDtoPagedList) com os itens da página atual e metadados da coleção:
A paginação é por número de página (offset), não por cursor. Não há parâmetro de ordenação genérico — consulte o endpoint específico na referência para os filtros e a ordem de retorno disponíveis.

​
Formato de erros

A API usa códigos de status HTTP para indicar o resultado de cada requisição. Os documentados hoje em toda a API são 400, 403 e 429 — 401, 404, 422 e 500 ainda não são padronizados. Veja Erros e respostas para o catálogo completo de códigos HTTP e como tratá-los. Erros de validação da própria SEFAZ ou prefeitura — que chegam como o status rejected da nota, não como um erro HTTP — estão catalogados em Erros e rejeições SEFAZ.

​
Emissão de documentos fiscais

A emissão de NF-e, NFC-e e NFS-e é assíncrona: uma resposta 2xx confirma que a solicitação foi aceita, não que a nota foi autorizada. Veja Ciclo de vida da nota para os estados possíveis e Emissão de NF-e para o fluxo completo de emissão.