<!-- https://www.akrus.digital/docs/sdks · revisado em 2026-10-08 · gerado do mesmo conteúdo da página HTML -->
_Ferramentas e versões · v1 em prévia_

# Comece pelo HTTP da sua linguagem.

Os exemplos usam HTTP diretamente. Não há SDK oficial ou coleção de ferramentas para download publicada nesta documentação.

> **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)

## JavaScript no servidor

Defina as duas variáveis de ambiente com os dados confirmados pela equipe. A função abaixo consulta uma página e devolve o envelope para que sua aplicação trate o cursor. O exemplo faz uma única chamada.

```js
export async function listarProdutos() {
  const base = process.env.AKRUS_BASE_URL;
  const token = process.env.AKRUS_API_KEY;
  if (!base || !token) throw new Error("Configure o ambiente Akrus");

  const url = new URL("/api/v1/products", base);
  url.searchParams.set("limit", "50");
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${token}` },
    cache: "no-store",
    signal: AbortSignal.timeout(10000),
  });
  const body = await response.json();
  if (!response.ok) {
    throw new Error(`Akrus ${response.status}: ${body.error?.code ?? "erro"}`);
  }
  return body;
}
```

## Python e PHP no servidor

Exemplos de uma página, com timeout e validação do envelope. Python usa a biblioteca padrão; PHP exige a extensão cURL. Configure a origem HTTPS autorizada em AKRUS_BASE_URL e a credencial em AKRUS_API_KEY. Falhas de transporte e JSON devem ser tratadas pela aplicação, sem registrar segredos.

**Python**

```python
import json
import os
from urllib.error import HTTPError
from urllib.parse import urlencode, urljoin
from urllib.request import Request, urlopen

base = os.environ["AKRUS_BASE_URL"]
key = os.environ["AKRUS_API_KEY"]
url = urljoin(base, "/api/v1/products") + "?" + urlencode({"limit": 50})
request = Request(url, headers={"Authorization": "Bearer " + key})
try:
    with urlopen(request, timeout=10) as response:
        body = json.load(response)
except HTTPError as error:
    raise RuntimeError(f"Akrus HTTP {error.code}") from None

if (body.get("version") != "v1"
    or not isinstance(body.get("data"), list)
    or "next_cursor" not in body
    or not (body["next_cursor"] is None
            or isinstance(body["next_cursor"], str))):
    raise ValueError("Envelope inesperado")
# Uma página: processe body["data"] no seu servidor.
# Continue a coleção com body["next_cursor"], até receber None.
```

**PHP**

```
<?php
$base = getenv('AKRUS_BASE_URL');
$key = getenv('AKRUS_API_KEY');
if (!$base || !$key) {
    throw new RuntimeException('Configure o ambiente Akrus');
}
$url = rtrim($base, '/') . '/api/v1/products?' . http_build_query(['limit' => 50]);
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $key],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_FOLLOWLOCATION => false,
]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($raw === false || $status !== 200) {
    throw new RuntimeException('Falha na consulta Akrus. HTTP ' . $status);
}
$body = json_decode($raw, false, 512, JSON_THROW_ON_ERROR);
if (!is_object($body) || ($body->version ?? null) !== 'v1'
    || !is_array($body->data ?? null)
    || !property_exists($body, 'next_cursor')
    || !($body->next_cursor === null || is_string($body->next_cursor))) {
    throw new RuntimeException('Envelope inesperado');
}
// Uma página: processe $body->data no seu servidor.
// Continue com $body->next_cursor, até receber null.
```

## O que sua aplicação precisa acrescentar

### Configuração e segurança

- [ ] Configuração por ambiente e armazenamento seguro da credencial.
- [ ] Nunca exponha a chave em código entregue ao navegador.
- [ ] Limites de tentativas e observabilidade sem segredos.

### Tratamento e continuidade

- [ ] Tratamento de timeout, falhas de rede, JSON inesperado e status HTTP.
- [ ] Paginação, persistência por identificador e reconciliação.
- [ ] Retentativas de forma controlada.

## Como avaliar uma biblioteca de terceiros

Verifique autoria, manutenção e o contrato que a biblioteca implementa. Um pacote com “Akrus” no nome não é automaticamente oficial. Não entregue credenciais a serviços intermediários sem avaliar o acesso que receberão.

- [Exemplo completo de paginação](https://www.akrus.digital/docs/paginacao)

---

Anterior: [Webhooks](https://www.akrus.digital/docs/webhooks) · Próximo: [Glossário](https://www.akrus.digital/docs/glossario)
