> ## 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.

# Introdução à referência

> Como usar a referência da API da Spedy.

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](/pages/guides/emissao-nfe),
[NFC-e](/pages/guides/emissao-nfce) e [NFS-e](/pages/guides/emissao-nfse)).

Se você ainda não emitiu nenhuma nota, comece pelos [primeiros
passos](/pages/start/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:

| Ambiente | Base URL                              |
| -------- | ------------------------------------- |
| Produção | `https://api.spedy.com.br/v1`         |
| Sandbox  | `https://sandbox-api.spedy.com.br/v1` |

<Note>
  Todos os exemplos desta referência usam a base URL de sandbox. Veja
  [Ambiente de testes](/pages/start/ambiente-de-testes) para as diferenças
  entre os dois ambientes e o [checklist de produção](/pages/start/go-live)
  antes de trocar para produção.
</Note>

## Autenticação

Toda requisição precisa do header `X-Api-Key` com a chave de API da sua
empresa:

```
X-Api-Key: sua-chave-de-api
```

Não há OAuth nem tokens temporários — é uma chave estática por empresa e por
ambiente. Veja [Autenticação](/pages/start/autenticacao) 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](/pages/start/exemplos-de-requisicao) 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:

| Parâmetro  | Descrição                        |
| ---------- | -------------------------------- |
| `page`     | Número da página (começa em `1`) |
| `pageSize` | Quantidade de itens por página   |

A resposta vem em um envelope `*PagedList` (ex.: `ProductInvoiceDtoPagedList`)
com os itens da página atual e metadados da coleção:

| Campo        | Descrição                                                  |
| ------------ | ---------------------------------------------------------- |
| `totalCount` | Total de itens na coleção, considerando todas as páginas   |
| `pageCount`  | Total de páginas disponíveis                               |
| `pageSize`   | Quantidade de itens por página, igual ao parâmetro enviado |
| `hasNext`    | Indica se existe uma próxima página                        |
| `items`      | Os itens da página atual                                   |

<Note>
  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.
</Note>

## 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](/pages/start/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](/pages/reference/erros-e-rejeicoes).

## 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](/pages/guides/ciclo-de-vida-da-nota) para os estados possíveis
e [Emissão de NF-e](/pages/guides/emissao-nfe) para o fluxo completo de
emissão.