Convenciones

Dinero y volumen como cadenas

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

Interprételos como decimal, no como float. La moneda es USD. Un gigabyte = 10^9 bytes.

Hora

ISO-8601 con desplazamiento explícito, siempre UTC: 2026-08-28T14:03:11+00:00.

Enumeraciones ampliables

El estado del pedido, el tipo de transacción, el tipo de evento, el estado del paquete, kind y family se amplían dentro de v1 sin previo aviso: su código debe tolerar un valor desconocido. En los filtros, un valor desconocido se interpreta como «sin filtro».

Paginación

Parámetro	Significado
offset	cuántas filas omitir; por defecto 0
limit	1..200, por defecto 50 (para GET /api/v1/packages, 200)

Ambos se ajustan al rango en lugar de rechazarse, y se devuelven ya ajustados en el cuerpo. La respuesta lleva total.

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

En las listas que reciben escrituras, offset indica una posición: en una descarga completa, deduplique por id. El orden es fijo: los más nuevos primero.

El registro de eventos se lee de otra forma: ?after=<id>, y la respuesta lleva next_after.

Idempotencia

Las operaciones que cobran dinero exigen el encabezado: POST /api/v1/packages (compra), POST /api/v1/packages/{id}/topup (recarga de tráfico) y POST /api/v1/packages/{id}/prolong (prolongación de direcciones).

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

Una cadena de hasta 255 caracteres; los espacios en los extremos se eliminan.

Un reintento con la misma clave y el mismo cuerpo devuelve la misma respuesta. Genere la clave antes de la solicitud y reutilícela al repetir, incluido el reintento después de un timeout.

La clave se recuerda 24 horas: la misma clave pasado un día inicia una operación nueva.

Rechazos:

• 422 - idempotency_key_required (falta el encabezado), idempotency_key_invalid (vacío o de más de 255), idempotency_key_reused (la misma clave con otro cuerpo)
• 409 - idempotency_in_progress (la solicitud anterior aún se está ejecutando: repita un poco más tarde con la misma clave)
• 500 - operation_indeterminate (reintento con la clave de una operación cuyo resultado no está determinado; ver Rechazos)

Caché del catálogo geográfico

Los niveles del catálogo geográfico devuelven ETag, un hash opaco de la versión del catálogo. Envíelo en If-None-Match y recibirá 304 sin cuerpo. La misma versión en forma legible está en el cuerpo, en el campo version.

Versionado

Se publica en v1 sin previo aviso: un campo nuevo en la respuesta, un parámetro opcional nuevo, un valor nuevo de una enumeración ampliable, un endpoint nuevo, un código de error nuevo en un estado existente.

Solo con una versión nueva: eliminar o renombrar un campo, restringir un tipo, un campo obligatorio nuevo en la solicitud, cambiar el estado o el código de un caso descrito, cambiar un valor por defecto.

Obsolescencia: encabezados Deprecation y Sunset, con al menos 6 meses antes de la desactivación.