<!-- https://www.akrus.digital/docs/api/vendas · revisado em 2026-10-08 · gerado do mesmo conteúdo da página HTML -->
_Referência da API · v1 em prévia_

# Consulte vendas.

Lista vendas reais do produtor. Valores em reais são representados em centavos. O recurso não retorna nome, e-mail, documento, telefone ou identificador do perfil do comprador.

> **Antes de integrar**
>
> Contrato em prévia. A implementação foi validada localmente; a liberação em produção ainda precisa ser confirmada pela equipe. O acesso programático exige plano Scale efetivo, credencial e escopos autorizados. Solicite acesso e a URL do ambiente antes de integrar.
>
> [Ver disponibilidade](https://www.akrus.digital/docs/ambientes)

## `GET /api/v1/sales`

Requer plano Scale efetivo. Escopo necessário: sales:read. O produtor é definido pela credencial, enviada em Authorization: Bearer <sua-credencial>. Ordem decrescente por created_at, com desempate por id. A resposta abaixo usa dados sintéticos e ilustra o formato, sem representar uma operação real; a coleção também pode estar vazia.

Escopos: `sales:read`

| Nome | Descrição |
| --- | --- |
| limit | De 1 a 100; padrão 50. |
| cursor | Cursor opaco da página anterior. Omita na primeira consulta. |

**Resposta**

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000201",
      "product_id": "00000000-0000-4000-8000-000000000101",
      "offer_id": null,
      "product_slug": "curso-exemplo",
      "status": "paid",
      "amount_brl_cents": 10000,
      "net_brl_cents": 9500,
      "created_at": "2026-09-03T12:00:00.000001Z",
      "paid_at": "2026-09-03T12:01:00.000001Z",
      "refunded_at": null
    }
  ],
  "next_cursor": null,
  "version": "v1"
}
```

## Campos retornados

Campos sem valor são retornados como null. Campos adicionais devem ser tolerados pelo consumidor.

| Campo | Significado e tratamento |
| --- | --- |
| id | Identificador da venda. |
| product_id | Referência ao produto; pode ser null. |
| offer_id | Referência à oferta; pode ser null. |
| product_slug | Identificador legível do produto associado à venda. |
| status | Estado da venda. Exemplos: pending, paid, refunded. Uma linha não representa necessariamente receita confirmada. |
| amount_brl_cents | Valor bruto da venda em centavos de real: 10000 representa R$ 100,00. |
| net_brl_cents | Valor líquido registrado em centavos de real. Não é uma cotação de saque ou o saldo total da conta. |
| created_at | Data e hora de criação; usada na ordenação. |
| paid_at | Data e hora de pagamento, quando registrada; pode ser null. |
| refunded_at | Data e hora de reembolso, quando registrada; pode ser null. |

## Conferência de valores e estados

A coleção contém vendas reais e pode incluir diferentes estados. Para um relatório de pagamentos confirmados, interprete o estado e as datas; somar todas as linhas como receita produz um resultado incorreto.

Mantenha valores em centavos durante os cálculos. O exemplo apresenta um líquido ilustrativo e não define uma regra de cálculo de taxas. Use o valor registrado e reconcilie alterações como reembolso.

## Dúvidas frequentes

### Posso filtrar por estado, período ou outro produtor?

O contrato publicado aceita limit e cursor. Filtros por estado, período, busca ou seleção de outro produtor não fazem parte desta referência. O produtor é determinado pela credencial.

### Como tratar campos vazios ou novos?

Preserve null como ausência de valor. Não transforme uma data ausente em uma data atual ou um valor financeiro ausente em zero. Tolere campos adicionais e valores de estado que sua aplicação ainda não conheça.

## Percorra a coleção completa

Use o cursor retornado para continuar e mantenha a conferência do estado atual dos registros.

[Implementar paginação](https://www.akrus.digital/docs/paginacao)

---

Anterior: [API de produtos](https://www.akrus.digital/docs/api/produtos) · Próximo: [API de acessos](https://www.akrus.digital/docs/api/acessos)
