<!-- https://www.akrus.digital/docs/inicio-rapido · revisado em 2026-10-08 · gerado do mesmo conteúdo da página HTML -->
_Comece por aqui · v1 em prévia_

# Sua primeira consulta, passo a passo.

Prepare um ambiente autorizado e uma credencial com o escopo adequado.

> **Contrato em prévia: confirme o acesso primeiro**
>
> Confirme o plano Scale efetivo e solicite à equipe a liberação e a URL do ambiente. As credenciais são emitidas pela administração da Akrus; não há emissão autônoma documentada para o produtor. Peça products:read para executar este exemplo.
>
> [Solicitar acesso à API](https://www.akrus.digital/contato?assunto=api)

## Configure o ambiente local

1. **Defina AKRUS_BASE_URL** — Use a origem do ambiente confirmada pela equipe, sem acrescentar /api/v1.
2. **Guarde AKRUS_API_KEY** — Mantenha a credencial em um gerenciador de segredos ou no ambiente do processo.
3. **Execute no servidor** — Rode a consulta do servidor ou do terminal; nunca inclua a chave no código do navegador.

## Faça uma leitura

O exemplo consulta dados e não cria cobranças. Uma lista vazia é uma resposta válida.

```bash
curl --fail-with-body --get \
  "${AKRUS_BASE_URL}/api/v1/products" \
  --header "Authorization: Bearer ${AKRUS_API_KEY}" \
  --data-urlencode "limit=10"
```

## Trate o envelope

Quando next_cursor tiver um valor, envie-o na próxima consulta como cursor. Quando for null, a coleção terminou. Confira o status HTTP antes de interpretar data.

```
{
  "data": [],
  "next_cursor": null,
  "version": "v1"
}
```

## Confira o resultado antes de ampliar

### Leia o status

- [ ] 200 com data vazia é sucesso; não crie registros reais só para preencher a resposta.
- [ ] 401 exige revisar a credencial; 403 exige revisar plano efetivo e escopo.
- [ ] 429 exige respeitar Retry-After; 503 exige uma política limitada de novas tentativas.

### Proteja a credencial

- [ ] Nunca registre Authorization em capturas, histórico de suporte ou logs compartilhados.

## Dúvidas frequentes

### Posso executar a chamada no navegador do comprador?

Não coloque a credencial em código entregue ao navegador. A consulta deve ocorrer no servidor ou em um ambiente técnico autorizado.

### Qual endereço uso no exemplo?

AKRUS_BASE_URL precisa conter a origem do ambiente confirmada pela equipe, sem acrescentar /api/v1. Esta documentação não declara um domínio de produção liberado.

---

Anterior: [Guias de integração](https://www.akrus.digital/docs/integracoes) · Próximo: [Autenticação](https://www.akrus.digital/docs/autenticacao)
