# Começar com a API

Do primeiro pedido à primeira chave, em poucos minutos.

Actualizado em 04/11/2026

## Antes de começar

Precisa de uma conta na Interweb com um serviço ou um domínio activo. A API responde em:

```text
https://api.interweb.ao/v1
```

A API usa JSON sobre HTTPS, e os nomes dos campos estão em inglês.

## Confirmar que a API responde

Esta operação não precisa de chave, por isso é o melhor primeiro teste:

**curl**

```bash
curl "https://api.interweb.ao/v1/ping" \
  -H "Accept-Language: pt"
```

**PHP**

```php
<?php
$ch = curl_init('https://api.interweb.ao/v1/ping');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept-Language: pt',
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL, $body, PHP_EOL;
```

**Python**

```python
import os
import requests

headers = {
    "Accept-Language": "pt",
}
r = requests.get("https://api.interweb.ao/v1/ping", headers=headers, timeout=30)
print(r.status_code)
print(r.text)
```

**JavaScript**

```javascript
const response = await fetch("https://api.interweb.ao/v1/ping", {
  headers: {
    "Accept-Language": "pt",
  },
});
console.log(response.status);
console.log(await response.text());
```


Resposta:

```json
{
  "data": {
    "status": "ok",
    "version": "v1",
    "time": "2026-11-04T21:30:00+02:00"
  },
  "meta": {}
}
```

O exemplo em Python usa a biblioteca `requests`, e o de JavaScript corre no Node.js 18 ou mais recente.

## Criar uma chave

1. Entre no Meu Interweb e abra a página [API](https://www.meu.interweb.ao/api-center.php?language=portuguese&currency=1).
2. Dê um nome à chave e escolha o tipo. Para começar, escolha o modo Sandbox (`sandbox_`).
3. Escolha as permissões e a validade.
4. Confirme com a sua senha e com o código de 6 dígitos que recebe por e-mail.
5. Copie a chave. Só é mostrada desta vez.

Os pormenores estão em [Autenticação e chaves](https://docs.interweb.ao/pt/authentication.md).

## Guardar a chave

Guarde a chave numa variável de ambiente, fora do código:

```bash
export RLX_API_KEY="sandbox_..."
```

Os exemplos desta documentação lêem a chave de `RLX_API_KEY`.

## Fazer o primeiro pedido com chave

Esta operação mostra as permissões, a validade e os limites da chave que fez o pedido:

**curl**

```bash
curl "https://api.interweb.ao/v1/token" \
  -H "Authorization: Bearer $RLX_API_KEY" \
  -H "Accept-Language: pt"
```

**PHP**

```php
<?php
$ch = curl_init('https://api.interweb.ao/v1/token');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RLX_API_KEY'),
        'Accept-Language: pt',
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL, $body, PHP_EOL;
```

**Python**

```python
import os
import requests

headers = {
    "Authorization": "Bearer " + os.environ["RLX_API_KEY"],
    "Accept-Language": "pt",
}
r = requests.get("https://api.interweb.ao/v1/token", headers=headers, timeout=30)
print(r.status_code)
print(r.text)
```

**JavaScript**

```javascript
const response = await fetch("https://api.interweb.ao/v1/token", {
  headers: {
    Authorization: `Bearer ${process.env.RLX_API_KEY}`,
    "Accept-Language": "pt",
  },
});
console.log(response.status);
console.log(await response.text());
```


Resposta:

```json
{
  "data": {
    "id": 12,
    "name": "Example key",
    "type": "sandbox",
    "mode": "sandbox",
    "writes_simulated": true,
    "suffix": "AbCd",
    "permissions": [
      "dns:read"
    ],
    "allowed_ips": [
      "198.51.100.0/24"
    ],
    "expires_at": "2027-02-02T10:00:00+02:00",
    "created_at": "2026-11-04T10:00:00+02:00",
    "last_used_at": "2026-11-04T21:30:00+02:00",
    "rate_limit": {
      "limit": 90,
      "remaining": 89,
      "reset": 1793820660,
      "window_seconds": 60
    },
    "spending": {
      "limit": 0,
      "spent": 0,
      "currency": "AOA",
      "window_days": 30
    }
  },
  "meta": {}
}
```

## Formato das respostas

Uma resposta com sucesso traz sempre `data` e `meta`, excepto em `GET /v1/openapi.json`, que devolve o documento sem este envelope:

```json
{
  "data": {},
  "meta": {}
}
```

Uma resposta com erro traz `error`, com um código estável. Veja [Erros](https://docs.interweb.ao/pt/api-rules.md).

Todas as respostas trazem o cabeçalho `X-Correlation-ID`. Indique-o ao suporte se comunicar um problema.

## Língua das mensagens

Envie `Accept-Language: pt` ou `Accept-Language: en` para escolher a língua das mensagens de erro. Sem este cabeçalho, as mensagens vêm em inglês. O campo `code` nunca muda com a língua.

## Operações longas

As operações que demoram respondem `202` com um `action_id`. Em vez de repetir o pedido, acompanhe o resultado com [`GET /v1/actions/{id}`](https://docs.interweb.ao/pt/key-status.md). Os estados são `queued`, `running`, `done` e `failed`.

> **Nota:**
>
> Nesta versão, o registo, a renovação e a transferência de domínios respondem `202`.

## Próximos passos

- [Permissões](https://docs.interweb.ao/pt/permissions.md): dê a cada chave só aquilo de que ela precisa.
- [Limites](https://docs.interweb.ao/pt/api-rules.md): quantos pedidos pode fazer por minuto.
- [Sandbox e Produção](https://docs.interweb.ao/pt/api-rules.md): o que as chaves `sandbox_` e `prod_` fazem.
- [Referência](https://docs.interweb.ao/pt/reference.md): todas as operações, com filtro, a ligar à página de cada área.