Chave e estado

Actualizado em 05/11/20261 min de leitura

Estas operações não alteram nada na conta. Servem para os seus programas confirmarem que está tudo pronto, antes e durante o trabalho.

A ligação à API

GET /v1/ping responde sem chave. Use-a para testar a ligação, por exemplo num alerta que confirme que a API está disponível.

O que a chave pode fazer

GET /v1/token devolve o modo, as permissões, a validade e os limites da chave que fez o pedido, e GET /v1/limits devolve os pedidos que restam neste minuto e o limite de gastos. Qualquer chave válida pode chamar estas duas operações, e a chave em si nunca é devolvida. Veja Permissões e Limites.

Operações longas

Algumas operações respondem 202 com um action_id, porque o trabalho continua depois da resposta. Siga o resultado com GET /v1/actions/{id}, em vez de repetir o pedido. Só se vêem as acções da própria conta.

A especificação

GET /v1/openapi.json devolve toda a API em formato OpenAPI, sem chave. Serve, por exemplo, para gerar um cliente na sua linguagem.

Operações

5 operações nesta área. Clique numa operação para ver os parâmetros, os exemplos e as respostas, ou para a experimentar no Playground, sem sair da página.

GET

Confirmar que a API responde

/v1/ping

GEThttps://api.interweb.ao/v1/ping

Responde sem chave. Serve para testar a ligação.

Autenticação

Esta operação não precisa de chave.

Exemplos

curl

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

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

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

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

Respostas

200

A API está a responder.

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

Cabeçalho	Descrição
`X-Correlation-ID`	Identificador deste pedido. Indique-o ao suporte se comunicar um problema.
`X-RateLimit-Limit`	Pedidos permitidos por minuto.
`X-RateLimit-Remaining`	Pedidos que restam no minuto actual.
`X-RateLimit-Reset`	Quando acaba o minuto, em segundos Unix.

429

Demasiados pedidos. Espere o tempo indicado em Retry-After.

{
  "error": {
    "code": "rate_limited",
    "message": "Demasiados pedidos. Tente de novo daqui a pouco.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {
      "retry_after": 42
    }
  }
}

Cabeçalho	Descrição
`Retry-After`	Segundos a esperar antes de tentar de novo.

500

Ocorreu um erro interno. Indique o correlation_id ao suporte.

{
  "error": {
    "code": "internal_error",
    "message": "Ocorreu um erro interno. Indique o correlation_id ao suporte.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

503

A API está desligada.

{
  "error": {
    "code": "disabled",
    "message": "A API está desligada de momento.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

Erros

Estado	Código	Significado
429	`rate_limited`	Demasiados pedidos. Espere o tempo indicado em `Retry-After`.
500	`internal_error`	Ocorreu um erro interno. Indique o `correlation_id` ao suporte.
503	`disabled`	A API está desligada.

O formato dos erros está explicado em Erros.

GET

Ver a chave em uso

/v1/token

GEThttps://api.interweb.ao/v1/token

Devolve as permissões, a validade e os limites da chave que fez o pedido. Qualquer chave válida pode chamar. A chave em si nunca é devolvida.

Autenticação

Precisa de uma chave válida no cabeçalho Authorization: Bearer. Basta uma chave válida: não precisa de nenhuma permissão de área.

Parâmetros

Nome	Onde	Tipo	Obrigatório	Descrição
`X-API-Mode`	cabeçalho	string: sandbox, production	não	Opcional. Se não coincidir com o modo da chave, o pedido é recusado com `invalid_request` e a razão `mode_mismatch`. Serve para garantir que um programa nunca corre com a chave errada.

Exemplos

curl

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

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

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

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());

Respostas

200

Dados da chave.

{
  "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": {}
}

Campo	Tipo	Descrição
`data.suffix`	string	Os 4 últimos caracteres da chave.
`data.allowed_ips`	array<string>	Vazio quer dizer qualquer endereço IP.
`data.expires_at`	string, null (date-time)	`null` quer dizer sem validade.
`data.rate_limit.reset`	integer	Data e hora Unix, em segundos.
`data.spending.limit`	number	Máximo por 30 dias, na moeda do cliente. 0 quer dizer que a chave não pode gastar.
`data.mode`	string: sandbox, production	O modo desta chave.
`data.writes_simulated`	boolean	Verdadeiro quando as escritas com esta chave são simuladas: uma chave de Sandbox, ou uma chave de Produção enquanto a API está em preparação.

Cabeçalho	Descrição
`X-Correlation-ID`	Identificador deste pedido. Indique-o ao suporte se comunicar um problema.
`X-RateLimit-Limit`	Pedidos permitidos por minuto.
`X-RateLimit-Remaining`	Pedidos que restam no minuto actual.
`X-RateLimit-Reset`	Quando acaba o minuto, em segundos Unix.
`X-API-Mode`	O modo da chave que fez o pedido: `sandbox` ou `production`.

401

A chave está em falta, não é válida, foi revogada ou passou da validade, ou quem a criou já não tem acesso à conta.

{
  "error": {
    "code": "unauthorized",
    "message": "Chave da API em falta ou inválida.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

403

A conta não pode usar a API (forbidden), a chave não tem a permissão necessária (insufficient_scope), ou o endereço IP não está na lista da chave (ip_not_allowed).

{
  "error": {
    "code": "insufficient_scope",
    "message": "Esta chave não tem a permissão necessária.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {
      "required": "dns:read"
    }
  }
}

429

Demasiados pedidos. Espere o tempo indicado em Retry-After.

{
  "error": {
    "code": "rate_limited",
    "message": "Demasiados pedidos. Tente de novo daqui a pouco.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {
      "retry_after": 42
    }
  }
}

Cabeçalho	Descrição
`Retry-After`	Segundos a esperar antes de tentar de novo.

500

Ocorreu um erro interno. Indique o correlation_id ao suporte.

{
  "error": {
    "code": "internal_error",
    "message": "Ocorreu um erro interno. Indique o correlation_id ao suporte.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

503

A API está desligada.

{
  "error": {
    "code": "disabled",
    "message": "A API está desligada de momento.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

Erros

Estado	Código	Significado
401	`unauthorized`	A chave está em falta, não é válida, foi revogada ou passou da validade, ou quem a criou já não tem acesso à conta.
403	`forbidden`, `insufficient_scope`, `ip_not_allowed`	A conta não pode usar a API (`forbidden`), a chave não tem a permissão necessária (`insufficient_scope`), ou o endereço IP não está na lista da chave (`ip_not_allowed`).
429	`rate_limited`	Demasiados pedidos. Espere o tempo indicado em `Retry-After`.
500	`internal_error`	Ocorreu um erro interno. Indique o `correlation_id` ao suporte.
503	`disabled`	A API está desligada.

O formato dos erros está explicado em Erros.

GET

Ver os limites da chave

/v1/limits

GEThttps://api.interweb.ao/v1/limits

Devolve os pedidos que restam no minuto actual e o limite de gastos da chave.

Autenticação

Precisa de uma chave válida no cabeçalho Authorization: Bearer. Basta uma chave válida: não precisa de nenhuma permissão de área.

Parâmetros

Nome	Onde	Tipo	Obrigatório	Descrição
`X-API-Mode`	cabeçalho	string: sandbox, production	não	Opcional. Se não coincidir com o modo da chave, o pedido é recusado com `invalid_request` e a razão `mode_mismatch`. Serve para garantir que um programa nunca corre com a chave errada.

Exemplos

curl

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

PHP

<?php
$ch = curl_init('https://api.interweb.ao/v1/limits');
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

import os
import requests

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

JavaScript

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

Respostas

200

Os limites da chave.

{
  "data": {
    "mode": "sandbox",
    "requests": {
      "limit": 90,
      "remaining": 88,
      "reset": 1793820660,
      "window_seconds": 60
    },
    "unauthenticated_requests_per_minute": 30,
    "spending": {
      "limit": 500,
      "spent": 120.5,
      "currency": "AOA",
      "window_days": 30
    }
  },
  "meta": {}
}

Campo	Tipo	Descrição
`data.requests.reset`	integer	Data e hora Unix, em segundos.
`data.spending.limit`	number	Máximo por 30 dias, na moeda do cliente. 0 quer dizer que a chave não pode gastar.
`data.mode`	string: sandbox, production	O modo desta chave.

Cabeçalho	Descrição
`X-Correlation-ID`	Identificador deste pedido. Indique-o ao suporte se comunicar um problema.
`X-RateLimit-Limit`	Pedidos permitidos por minuto.
`X-RateLimit-Remaining`	Pedidos que restam no minuto actual.
`X-RateLimit-Reset`	Quando acaba o minuto, em segundos Unix.
`X-API-Mode`	O modo da chave que fez o pedido: `sandbox` ou `production`.

401

A chave está em falta, não é válida, foi revogada ou passou da validade, ou quem a criou já não tem acesso à conta.

{
  "error": {
    "code": "unauthorized",
    "message": "Chave da API em falta ou inválida.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

403

A conta não pode usar a API (forbidden), a chave não tem a permissão necessária (insufficient_scope), ou o endereço IP não está na lista da chave (ip_not_allowed).

{
  "error": {
    "code": "insufficient_scope",
    "message": "Esta chave não tem a permissão necessária.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {
      "required": "dns:read"
    }
  }
}

429

Demasiados pedidos. Espere o tempo indicado em Retry-After.

{
  "error": {
    "code": "rate_limited",
    "message": "Demasiados pedidos. Tente de novo daqui a pouco.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {
      "retry_after": 42
    }
  }
}

Cabeçalho	Descrição
`Retry-After`	Segundos a esperar antes de tentar de novo.

500

Ocorreu um erro interno. Indique o correlation_id ao suporte.

{
  "error": {
    "code": "internal_error",
    "message": "Ocorreu um erro interno. Indique o correlation_id ao suporte.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

503

A API está desligada.

{
  "error": {
    "code": "disabled",
    "message": "A API está desligada de momento.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

Erros

Estado	Código	Significado
401	`unauthorized`	A chave está em falta, não é válida, foi revogada ou passou da validade, ou quem a criou já não tem acesso à conta.
403	`forbidden`, `insufficient_scope`, `ip_not_allowed`	A conta não pode usar a API (`forbidden`), a chave não tem a permissão necessária (`insufficient_scope`), ou o endereço IP não está na lista da chave (`ip_not_allowed`).
429	`rate_limited`	Demasiados pedidos. Espere o tempo indicado em `Retry-After`.
500	`internal_error`	Ocorreu um erro interno. Indique o `correlation_id` ao suporte.
503	`disabled`	A API está desligada.

O formato dos erros está explicado em Erros.

GET

Acompanhar uma operação longa

/v1/actions/{id}

GEThttps://api.interweb.ao/v1/actions/{id}

As operações longas respondem 202 com um action_id. Use esta operação para ver o resultado, em vez de repetir o pedido. Só se vêem as acções da própria conta.

Autenticação

Precisa de uma chave válida no cabeçalho Authorization: Bearer. Basta uma chave válida: não precisa de nenhuma permissão de área.

Parâmetros

Nome	Onde	Tipo	Obrigatório	Descrição
`id`	caminho	string (uuid)	sim	O action_id recebido na resposta 202.
`X-API-Mode`	cabeçalho	string: sandbox, production	não	Opcional. Se não coincidir com o modo da chave, o pedido é recusado com `invalid_request` e a razão `mode_mismatch`. Serve para garantir que um programa nunca corre com a chave errada.

Exemplos

curl

curl "https://api.interweb.ao/v1/actions/00000000-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $RLX_API_KEY" \
  -H "Accept-Language: pt"

PHP

<?php
$ch = curl_init('https://api.interweb.ao/v1/actions/00000000-0000-4000-8000-000000000000');
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

import os
import requests

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

JavaScript

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

Respostas

200

O estado da acção.

{
  "data": {
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "type": "example.operation",
    "target": "example.com",
    "status": "running",
    "result": null,
    "created_at": "2026-11-04T21:30:00+02:00",
    "updated_at": "2026-11-04T21:30:05+02:00"
  },
  "meta": {}
}

Campo	Tipo	Descrição
`data.result`	any	`null` até a acção terminar.

Cabeçalho	Descrição
`X-Correlation-ID`	Identificador deste pedido. Indique-o ao suporte se comunicar um problema.
`X-RateLimit-Limit`	Pedidos permitidos por minuto.
`X-RateLimit-Remaining`	Pedidos que restam no minuto actual.
`X-RateLimit-Reset`	Quando acaba o minuto, em segundos Unix.
`X-API-Mode`	O modo da chave que fez o pedido: `sandbox` ou `production`.

401

A chave está em falta, não é válida, foi revogada ou passou da validade, ou quem a criou já não tem acesso à conta.

{
  "error": {
    "code": "unauthorized",
    "message": "Chave da API em falta ou inválida.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

403

A conta não pode usar a API (forbidden), a chave não tem a permissão necessária (insufficient_scope), ou o endereço IP não está na lista da chave (ip_not_allowed).

{
  "error": {
    "code": "insufficient_scope",
    "message": "Esta chave não tem a permissão necessária.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {
      "required": "dns:read"
    }
  }
}

404

Não encontrado.

{
  "error": {
    "code": "not_found",
    "message": "Não encontrado.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

429

Demasiados pedidos. Espere o tempo indicado em Retry-After.

{
  "error": {
    "code": "rate_limited",
    "message": "Demasiados pedidos. Tente de novo daqui a pouco.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {
      "retry_after": 42
    }
  }
}

Cabeçalho	Descrição
`Retry-After`	Segundos a esperar antes de tentar de novo.

500

Ocorreu um erro interno. Indique o correlation_id ao suporte.

{
  "error": {
    "code": "internal_error",
    "message": "Ocorreu um erro interno. Indique o correlation_id ao suporte.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

503

A API está desligada.

{
  "error": {
    "code": "disabled",
    "message": "A API está desligada de momento.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

Erros

Estado	Código	Significado
401	`unauthorized`	A chave está em falta, não é válida, foi revogada ou passou da validade, ou quem a criou já não tem acesso à conta.
403	`forbidden`, `insufficient_scope`, `ip_not_allowed`	A conta não pode usar a API (`forbidden`), a chave não tem a permissão necessária (`insufficient_scope`), ou o endereço IP não está na lista da chave (`ip_not_allowed`).
404	`not_found`	Não encontrado.
429	`rate_limited`	Demasiados pedidos. Espere o tempo indicado em `Retry-After`.
500	`internal_error`	Ocorreu um erro interno. Indique o `correlation_id` ao suporte.
503	`disabled`	A API está desligada.

O formato dos erros está explicado em Erros.

GET

Descarregar esta especificação

/v1/openapi.json

GEThttps://api.interweb.ao/v1/openapi.json

Responde sem chave. Devolve este documento OpenAPI tal como está, sem o envelope data e meta.

Autenticação

Esta operação não precisa de chave.

Exemplos

curl

curl "https://api.interweb.ao/v1/openapi.json" \
  -H "Accept-Language: pt"

PHP

<?php
$ch = curl_init('https://api.interweb.ao/v1/openapi.json');
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

import os
import requests

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

JavaScript

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

Respostas

200

O documento OpenAPI.

A resposta é o documento pedido.

Cabeçalho	Descrição
`X-Correlation-ID`	Identificador deste pedido. Indique-o ao suporte se comunicar um problema.
`X-RateLimit-Limit`	Pedidos permitidos por minuto.
`X-RateLimit-Remaining`	Pedidos que restam no minuto actual.
`X-RateLimit-Reset`	Quando acaba o minuto, em segundos Unix.

429

Demasiados pedidos. Espere o tempo indicado em Retry-After.

{
  "error": {
    "code": "rate_limited",
    "message": "Demasiados pedidos. Tente de novo daqui a pouco.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {
      "retry_after": 42
    }
  }
}

Cabeçalho	Descrição
`Retry-After`	Segundos a esperar antes de tentar de novo.

500

Ocorreu um erro interno. Indique o correlation_id ao suporte.

{
  "error": {
    "code": "internal_error",
    "message": "Ocorreu um erro interno. Indique o correlation_id ao suporte.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

503

A API está desligada.

{
  "error": {
    "code": "disabled",
    "message": "A API está desligada de momento.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {}
  }
}

Erros

Estado	Código	Significado
429	`rate_limited`	Demasiados pedidos. Espere o tempo indicado em `Retry-After`.
500	`internal_error`	Ocorreu um erro interno. Indique o `correlation_id` ao suporte.
503	`disabled`	A API está desligada.

O formato dos erros está explicado em Erros.