Litport API

Litport API da a una integración acceso a tus propios tokens, paquetes y datos de pago por GB (PPG), además de un pequeño conjunto de escrituras: ubicación del token, rotación, IP nueva e IP permitidas del paquete.

URL base:

https://litport.net/api/v1

Áreas#

Autenticación#

Crea una clave de API en Configuración. Su valor completo sigue disponible allí después de crearla o rotarla.

export LITPORT_API_KEY='lit_replace_with_your_key'
curl 'https://litport.net/api/v1/tokens' \
  -H "Authorization: Bearer $LITPORT_API_KEY"

Los clientes externos usan exactamente el esquema Bearer. No envíes una clave en la cadena de consulta, el cuerpo JSON, una cookie ni el usuario del proxy. Guárdala como un secreto, restringe el acceso a cargas de trabajo del lado del servidor y rótala si pudo filtrarse.

Los controles Ejecutar de estas páginas de documentación usan tu cuenta de Litport con la sesión iniciada, solo para solicitudes GET. Toda escritura necesita una clave de API Bearer.

Alcance de cada credencial#

Reglas comunes de la API#

Todos los endpoints de todas las áreas siguen las mismas reglas, así que una integración las aprende una sola vez.

Identificadores. Usa los tokenId y packageId numéricos públicos. Selecciona un pool de pago por GB por su authKey y una IP permitida por la propia IP. Ningún endpoint recibe ni devuelve un ID de base de datos.

Nombres. Los campos van en camelCase. Los valores enumerados nuevos y los slugs van en kebab-case en minúsculas, por ejemplo awaiting-payment, more-allowed-ips, package-inactive. Los códigos de error siguen en UPPER_SNAKE. El texto libre (etiquetas, credenciales, nombres de pools) no tiene restricciones. Unos pocos valores conservan su escritura actual en lugar de renombrarse para coincidir: trafficBasis: "customer_chargeable" y timezone: "UTC" en los datos de uso, y los valores type/status de los tokens.

Valores. Las fechas y horas son ISO-8601 en UTC y terminan en Z. Los recuentos grandes de bytes son cadenas decimales, no números JSON, para que un cliente nunca pierda precisión.

Formas de respuesta. Un objeto único es {"data": {...}}. Un endpoint que devuelve una lista siempre responde {"data": [...], "page": {"nextCursor": ...}}. Hay dos tipos de lista:

• una lista paginada (GET /tokens, GET /packages, GET /pay-per-gb/geo) acepta limit y cursor;
• una lista completa (GET /pay-per-gb/pools, GET /tokens/{tokenId}/location/options) siempre devuelve todos los elementos, no acepta limit ni cursor e informa page.nextCursor: null.

Un array dentro de un objeto, como los buckets del uso, las ips de las IP permitidas o los tokenIds de un paquete, es un campo ordinario, no una lista de endpoint.

Paginación. limit va de 1 a 100, con 50 de forma predeterminada. cursor es el page.nextCursor de la respuesta anterior, reenviado sin cambios; trátalo como opaco. Un limit incorrecto es 400 INVALID_LIMIT; un cursor incorrecto o ajeno es 400 INVALID_CURSOR. Sigue solicitando page.nextCursor hasta que sea null.

Errores. Todo error es {"error": {"code", "message", "requestId", "docsUrl"}}, más nextChangeAt cuando se aplica una espera. Consulta Errores de la API para ver la tabla completa de estados y un apartado de detalle por cada código.

Escrituras. Toda escritura necesita una clave de API Bearer; una sesión iniciada en la documentación solo puede leer. Envía un cuerpo JSON cuando el endpoint lo tenga. No hay encabezado de precondición: prevalece la última escritura confirmada. Toda escritura se puede repetir sin riesgo, salvo POST /tokens/{tokenId}/new-ip.

Límites de frecuencia#

Se aplican dos límites, ambos informados mediante encabezados estándar.

• 120 solicitudes cada 60 segundos, por clave de API. Superarlo da 429 RATE_LIMITED.
• 20 escrituras de IP permitidas cada 60 segundos, por paquete (PUT/DELETE /packages/{packageId}/allowed-ips…). El límite por clave se comprueba primero; una solicitud que pasa esa comprobación y además es una escritura de IP permitidas comprueba después el límite del paquete e informa en su lugar los encabezados de ese limitador.

Lee RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset en cada respuesta; una solicitud rechazada incluye además Retry-After.

Convenciones#

• Las respuestas son JSON.
• X-Request-ID identifica la solicitud; inclúyelo cuando informes de un fallo.
• Las respuestas autenticadas incluyen Cache-Control: private, no-store y Vary: Authorization.
• Esta API no usa ETags ni precondiciones If-Match en ningún punto.

Contrato legible por máquinas#

Usa el documento OpenAPI 3.1 para cada ruta, parámetro, cuerpo de solicitud y esquema de respuesta. Gestiona el envoltorio de error antes de usar los datos de cada endpoint.