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

# Consulte acessos.

Lista concessões de acesso. Uma concessão pode ser reutilizada após uma recompra: esta coleção não representa um histórico de matrículas. A relação com a venda é feita por sale_id, sem identificar a pessoa.

> **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/access`

Requer plano Scale efetivo. Escopo necessário: access:read. O produtor é definido pela credencial, enviada em Authorization: Bearer <sua-credencial>. Ordem decrescente por granted_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: `access: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-000000000301",
      "product_slug": "curso-exemplo",
      "sale_id": "00000000-0000-4000-8000-000000000201",
      "status": "active",
      "origin": "purchase",
      "granted_at": "2026-09-03T12:01:00.000001Z",
      "revoked_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 concessão de acesso. |
| product_slug | Produto ao qual a concessão se refere. |
| sale_id | Venda relacionada, quando existe; pode ser null. |
| status | Estado da concessão: active, revoked ou refunded no contrato atual. |
| origin | Origem da concessão. Trate como texto; não presuma que toda concessão veio de uma compra. |
| granted_at | Data e hora da concessão; usada na ordenação. |
| revoked_at | Data e hora de revogação, quando registrada; pode ser null. |

> **Relação com a venda e com a pessoa**
>
> sale_id pode relacionar a concessão a uma venda; ele pode ser null. O recurso não retorna o identificador do perfil, e-mail ou nome da pessoa. Não o utilize como diretório de alunos. Como uma recompra pode reutilizar a concessão, contagem de linhas não equivale à quantidade histórica de compras ou matrículas.

## 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 vendas](https://www.akrus.digital/docs/api/vendas) · Próximo: [Paginação](https://www.akrus.digital/docs/paginacao)
