> ## 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.
# Exemplos de requisição
> Convenções da API e exemplos prontos dos principais fluxos da Spedy.
Esta página resume os padrões que se repetem em toda a API e traz exemplos
prontos (happy-path) dos fluxos mais comuns. Cada exemplo aponta para o guia
detalhado, que é a fonte completa de campos e regras de cada operação.
## Convenções
* Requisições e respostas usam **JSON** (`Content-Type: application/json`),
exceto o upload de certificado digital, que usa `multipart/form-data`.
* Todos os endpoints exigem o header `X-Api-Key`. Veja
[Autenticação](/pages/start/autenticacao).
* Campos seguem **camelCase** (`federalTaxNumber`, `unitAmount`,
`autoIssueMode`).
* Datas e horários seguem **ISO-8601** (`2026-07-31T10:00:00Z`).
* IDs de recursos são **UUIDs**.
* Todos os exemplos usam a base URL de **sandbox**
(`https://sandbox-api.spedy.com.br/v1`).
A emissão é **assíncrona**: um `2xx` confirma que a solicitação foi aceita,
não que a nota foi autorizada. Acompanhe o resultado por
[webhook](/pages/webhooks/visao-geral) ou consulta de status. Veja [Ciclo de
vida da nota](/pages/guides/ciclo-de-vida-da-nota).
## Fluxos principais
Os exemplos abaixo têm **fins didáticos**. Os valores de tributação (CFOP,
CSOSN/CST, alíquotas etc.) dependem do seu regime, produto e operação —
**valide com o seu contador** ou responsável fiscal antes de emitir em
produção.
### Criar uma venda
O caminho mais simples: criar uma venda emite uma nota automaticamente (por
padrão, uma **NFS-e**). Detalhes em [Primeiros
passos](/pages/start/primeiros-passos) e [Fluxo de
emissão](/pages/guides/fluxo-de-emissao).
```bash cURL theme={null}
curl -X POST https://sandbox-api.spedy.com.br/v1/orders \
-H "X-Api-Key: sua-chave-de-api" \
-H "Content-Type: application/json" \
-d '{
"transactionId": "PEDIDO-12345",
"date": "2026-07-31T10:00:00Z",
"amount": 100.00,
"customer": {
"name": "Cliente Exemplo",
"federalTaxNumber": "00000000000",
"email": "cliente@exemplo.com.br",
"address": {
"street": "Rua Exemplo", "number": "100", "district": "Centro",
"postalCode": "01310100",
"city": { "name": "São Paulo", "state": "SP" }
}
},
"items": [
{
"quantity": 1,
"price": 100.00,
"amount": 100.00,
"product": { "code": "SKU-001", "name": "Produto de teste", "price": 100.00 }
}
]
}'
```
### Emitir uma NF-e
Nota de produto (modelo 55). Exemplo para o Simples Nacional (tributação por
item com `csosn`/`cst`). Detalhes em [Emissão de
NF-e](/pages/guides/emissao-nfe).
```bash cURL theme={null}
curl -X POST https://sandbox-api.spedy.com.br/v1/product-invoices \
-H "X-Api-Key: sua-chave-de-api" \
-H "Content-Type: application/json" \
-d '{
"integrationId": "pedido-12345",
"effectiveDate": "2026-08-03T10:00:00Z",
"operationNature": "Venda de mercadoria",
"isFinalCustomer": true,
"receiver": {
"name": "Cliente Exemplo",
"federalTaxNumber": "11144477735",
"address": {
"street": "Rua Exemplo", "number": "100", "district": "Centro",
"postalCode": "01001000",
"city": { "name": "São Paulo", "state": "SP" }
}
},
"items": [
{
"code": "SKU-001", "description": "Produto Exemplo",
"ncm": "61091000", "cfop": 5102, "unit": "UN",
"quantity": 1, "unitAmount": 100.0, "totalAmount": 100.0,
"unitTax": "UN", "quantityTax": 1, "unitTaxAmount": 100.0,
"taxes": {
"icms": { "origin": 0, "csosn": 102 },
"pis": { "cst": 49 },
"cofins": { "cst": 49 }
}
}
]
}'
```
### Emitir uma NFC-e
Nota ao consumidor (modelo 65), para varejo/PDV. Detalhes em [Emissão de
NFC-e](/pages/guides/emissao-nfce).
```bash cURL theme={null}
curl -X POST https://sandbox-api.spedy.com.br/v1/consumer-invoices \
-H "X-Api-Key: sua-chave-de-api" \
-H "Content-Type: application/json" \
-d '{
"integrationId": "venda-pdv-98765",
"effectiveDate": "2026-08-03T10:00:00Z",
"operationNature": "Venda de mercadoria",
"isFinalCustomer": true,
"receiver": { "name": "Consumidor Final", "federalTaxNumber": "11144477735" },
"items": [
{
"code": "SKU-001", "description": "Produto Exemplo",
"ncm": "61091000", "cfop": 5102, "unit": "UN",
"quantity": 1, "unitAmount": 100.0, "totalAmount": 100.0,
"unitTax": "UN", "quantityTax": 1, "unitTaxAmount": 100.0,
"taxes": {
"icms": { "origin": 0, "csosn": 102 },
"pis": { "cst": 49 },
"cofins": { "cst": 49 }
}
}
],
"payments": [ { "method": "creditCard", "amount": 100.0 } ]
}'
```
### Emitir uma NFS-e
Nota de serviço. Antes, confirme se o município é integrado (veja [Emissão de
NFS-e](/pages/guides/emissao-nfse)).
```bash cURL theme={null}
curl -X POST https://sandbox-api.spedy.com.br/v1/service-invoices \
-H "X-Api-Key: sua-chave-de-api" \
-H "Content-Type: application/json" \
-d '{
"integrationId": "servico-45678",
"effectiveDate": "2026-07-31T10:00:00Z",
"description": "Consultoria em tecnologia da informação",
"receiver": {
"name": "Cliente Exemplo Ltda",
"federalTaxNumber": "00000000000191",
"address": {
"street": "Rua Exemplo", "number": "100", "district": "Centro",
"postalCode": "01310100",
"city": { "name": "São Paulo", "state": "SP" }
}
},
"total": {
"invoiceAmount": 1000.0, "netAmount": 950.0,
"issBaseTax": 1000.0, "issRate": 5, "issAmount": 50.0
}
}'
```
## Formato de resposta
Respostas de sucesso retornam o objeto criado ou consultado, com `id` e os
campos normalizados. Para o formato de respostas de erro, veja [Erros e
respostas](/pages/start/erros-e-respostas); para rejeições fiscais, [Erros e
rejeições SEFAZ](/pages/reference/erros-e-rejeicoes).
## Paginação e consultas
Endpoints de listagem (ex.: `GET /v1/customers`) aceitam `page` e `pageSize` e
retornam um envelope paginado. Veja os parâmetros de filtro de cada endpoint na
[Referência da API](/pages/reference/introducao).
Troque a base URL para `https://api.spedy.com.br/v1` e use sua chave de
produção quando for para o ar — veja o [checklist de
produção](/pages/start/go-live).