> For the complete documentation index, see [llms.txt](https://ereemby.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ereemby.gitbook.io/docs/desenvolvedores/documentacao-api-publica/vendas.md).

# Vendas

Endpoints para verificar históricos de vendas e informações específicas de uma ordem

## Listar vendas

> Retorna uma lista de vendas com filtros opcionais.

```json
{"openapi":"3.0.3","info":{"title":"Ereemby API - Pedidos","version":"1.0.0"},"tags":[{"name":"pedidos","description":"Endpoints para gerenciamento de pedidos e vendas"}],"servers":[{"url":"https://api.ereemby.app","description":"Produção"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Insira sua chave de API privada"}},"responses":{"UnauthorizedError":{"description":"Erro de autenticação (Chave inválida ou não encontrada)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequestsError":{"description":"Muitas requisições (Rate Limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/api/v1/sales":{"get":{"tags":["pedidos"],"summary":"Listar vendas","description":"Retorna uma lista de vendas com filtros opcionais.","parameters":[{"in":"query","name":"page","required":true,"schema":{"type":"integer","minimum":1,"default":1},"description":"Número da página (sempre maior ou igual a 1)"},{"in":"query","name":"search","schema":{"type":"string"},"description":"Filtrar por nome do produto ou nome do cliente"},{"in":"query","name":"status","schema":{"type":"string","enum":["s","p","r","semestoque"]},"description":"Status do pedido:\n* `s` - Aprovado\n* `p` - Pendente\n* `r` - Reembolso\n* `semestoque` - Produto sem estoque"},{"in":"query","name":"order","schema":{"type":"string","default":"createdAt"},"description":"Campo para ordenação (ex: createdAt)"},{"in":"query","name":"start","schema":{"type":"string","format":"date-time"},"description":"Data de início (ISO 8601)"},{"in":"query","name":"end","schema":{"type":"string","format":"date-time"},"description":"Data de fim (ISO 8601)"},{"in":"query","name":"coupon","schema":{"type":"string"},"description":"Filtrar por nome do cupom"},{"in":"query","name":"affiliate","schema":{"type":"string"},"description":"Filtrar por ID do afiliado"},{"in":"query","name":"method","schema":{"type":"string","enum":["pix","card","ltc"]},"description":"Método de pagamento (pix, card, ltc)"},{"in":"query","name":"utm","schema":{"type":"string"},"description":"Filtrar por UTM source da campanha"}],"responses":{"200":{"description":"Lista de vendas recuperada com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"totalItens":{"type":"integer"},"totalPaginas":{"type":"integer"},"paginaAtual":{"type":"integer"},"itens":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"nome":{"type":"string"},"quantidade":{"type":"integer"},"total":{"type":"number","format":"float"},"metodo":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"email":{"type":"string","format":"email"},"cupom":{"type":"string","nullable":true},"cupom_nome":{"type":"string","nullable":true},"mailstatus":{"type":"string"},"banco":{"type":"string"},"entregue":{"type":"boolean"},"afiliado":{"type":"string","nullable":true},"auto_approve":{"type":"boolean"},"afiliado_id":{"type":"string","nullable":true},"utm":{"type":"object","nullable":true,"properties":{"utm_term":{"type":"string"},"utm_medium":{"type":"string"},"utm_source":{"type":"string"},"utm_content":{"type":"string"},"utm_campaign":{"type":"string"}}}}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/TooManyRequestsError"}}}}}}
```

## Detalhes da venda

> Retorna os detalhes de uma venda específica.

```json
{"openapi":"3.0.3","info":{"title":"Ereemby API - Pedidos","version":"1.0.0"},"tags":[{"name":"pedidos","description":"Endpoints para gerenciamento de pedidos e vendas"}],"servers":[{"url":"https://api.ereemby.app","description":"Produção"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Insira sua chave de API privada"}},"responses":{"UnauthorizedError":{"description":"Erro de autenticação (Chave inválida ou não encontrada)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequestsError":{"description":"Muitas requisições (Rate Limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/api/v1/sale":{"get":{"tags":["pedidos"],"summary":"Detalhes da venda","description":"Retorna os detalhes de uma venda específica.","parameters":[{"in":"query","name":"id","required":true,"schema":{"type":"string"},"description":"ID da venda"}],"responses":{"200":{"description":"Detalhes da venda recuperados com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"nome":{"type":"string"},"quantidade":{"type":"integer"},"total":{"type":"number","format":"float"},"metodo":{"type":"string"},"status":{"type":"string"},"link":{"type":"string","nullable":true},"qr":{"type":"string","description":"Base64 do QRCode"},"copiaecola":{"type":"string"},"linkPagamento":{"type":"string","nullable":true},"email":{"type":"string","format":"email"},"ip":{"type":"string"},"estado":{"type":"string"},"pais":{"type":"string"},"loja":{"type":"string"},"entrega":{"type":"boolean"},"cupom":{"type":"string","nullable":true},"cupom_porcentagem":{"type":"number","nullable":true},"cupom_nome":{"type":"string","nullable":true},"banco":{"type":"string"},"taxa":{"type":"number","nullable":true},"afiliado":{"type":"string","nullable":true},"afiliado_id":{"type":"string","nullable":true},"afiliado_lucro":{"type":"number","nullable":true},"mailid":{"type":"string"},"mailstatus":{"type":"string"},"approved_at":{"type":"string","format":"date-time"},"entregue":{"type":"boolean"},"auto_approve":{"type":"boolean"},"desconto":{"type":"number"},"address_crypto":{"type":"string","nullable":true},"utm":{"type":"object","nullable":true},"utm_source_virtual":{"type":"string","nullable":true},"cpf":{"type":"string"},"client_name":{"type":"string","nullable":true},"client_address":{"type":"string","nullable":true},"client_phone":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"carrinhos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"icon":{"type":"string"},"produto":{"type":"string"},"variante":{"type":"string","nullable":true},"nome":{"type":"string"},"valor":{"type":"number"},"quantidade":{"type":"integer"},"estoques":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"produto":{"type":"string"},"tipo":{"type":"string","nullable":true},"estoque":{"type":"string"},"pos":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"automatic":{"type":"boolean"},"tipo":{"type":"string"},"feedback":{"type":"boolean"},"campos":{"type":"array","items":{"type":"object"}}}}},"banido":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"429":{"$ref":"#/components/responses/TooManyRequestsError"}}}}}}
```

### Teste rápido (cURL)

Listar vendas/pedidos:

```bash
curl -sS \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  "https://api.ereemby.app/api/v1/sales?page=1"
```

### Erros comuns

* `400 Bad Request`: query inválida ou inexistente.
* `401 Unauthorized`: faltou `x-api-key` ou você enviou vazio.
* `429 Too Many Requests`: você está fazendo polling agressivo.

### Boas práticas (pra não sofrer em produção)

* Prefira **webhooks** para “tempo real”. Use API para backfill.
* Faça retry apenas em erro transitório (`429`/`5xx`). Use backoff exponencial.
* Evite rodar "listar tudo" a cada minuto. Use janelas de tempo e cache.

#### Fluxo recomendado (webhook + API)

* Webhook chega ([`order_paid`](/docs/desenvolvedores/webhooks/vendas.md)) → salve `pedido.id` e timestamps.
* Se precisar reprocessar, consulte no endpoint de vendas e reconcilie.
* Se o seu worker cair, você consegue “voltar no tempo” pelo histórico.

{% hint style="info" %}
Você pode visualizar os payloads de webhook completos aqui: [Vendas (webhook)](/docs/desenvolvedores/webhooks/vendas.md).
{% endhint %}