Convenções

Dinheiro e volume são strings

{
  "balance": "124.30",
  "currency": "USD"
}
{
  "purchased_gb": "25.000",
  "used_gb": "2.566",
  "left_gb": "22.434"
}

Converta para decimal, não para float. A moeda é USD. Um gigabyte = 10^9 bytes.

Horário

ISO-8601 com offset explícito, sempre UTC: 2026-08-28T14:03:11+00:00.

Enumerações extensíveis

Status do pedido, tipo de transação, tipo de evento, status do pacote, kind e family ganham valores dentro da v1 sem aviso - seu código precisa tolerar um valor desconhecido. Nos filtros, um valor desconhecido é lido como “sem filtro”.

Paginação

Parâmetro	Significado
offset	quantas linhas pular; padrão 0
limit	1..200, padrão 50 (para GET /api/v1/packages - 200)

Ambos são ajustados ao intervalo, e não recusados, e voltam no corpo já ajustados. A resposta traz total.

GET /api/v1/orders?limit=100&offset=100
    -> { "orders": [...], "total": 317, "offset": 100, "limit": 100 }

Em listas que recebem novas entradas, o offset aponta para uma posição: ao exportar tudo, deduplique por id. A ordem é fixa - os mais novos primeiro.

O log de eventos é lido de outra forma: ?after=<id>, e a resposta traz next_after.

Idempotência

As operações que debitam dinheiro exigem o cabeçalho: POST /api/v1/packages (compra), POST /api/v1/packages/{id}/topup (recarga de tráfego) e POST /api/v1/packages/{id}/prolong (prolongamento de endereços).

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

String de até 255 caracteres; espaços nas pontas são removidos.

Repetir com a mesma chave e o mesmo corpo retorna a mesma resposta. Gere a chave antes da requisição e reutilize-a ao repetir, inclusive depois de um timeout.

A chave é lembrada por 24 horas: a mesma chave depois de um dia inicia uma nova operação.

Recusas:

• 422 - idempotency_key_required (sem cabeçalho), idempotency_key_invalid (vazio ou com mais de 255), idempotency_key_reused (a mesma chave com outro corpo)
• 409 - idempotency_in_progress (a requisição anterior ainda está em execução - repita um pouco depois com a mesma chave)
• 500 - operation_indeterminate (repetição com a chave de uma operação cujo resultado não está definido - veja Recusas)

Cache do catálogo geográfico

Os níveis do catálogo geográfico retornam ETag - um hash opaco da versão do catálogo. Envie-o em If-None-Match e você recebe 304 sem corpo. A mesma versão em forma legível está no corpo, no campo version.

Versionamento

Lançado na v1 sem aviso: novo campo na resposta, novo parâmetro opcional, novo valor de uma enumeração extensível, novo endpoint, novo código de erro em um status existente.

Só em uma nova versão: remoção ou renomeação de campo, restrição de tipo, novo campo obrigatório na requisição, mudança de status ou código para um caso descrito, mudança de valor padrão.

Descontinuação: cabeçalhos Deprecation e Sunset, com pelo menos 6 meses antes do desligamento.