Autenticación

Puedes construir todo lo que va hasta tu primer pedido sin una clave de API. El catálogo, las cotizaciones, los precios de alquiler y los productos de correo son públicos: cualquiera puede llamarlos, y responden con los precios de lista públicos. Solo necesitas una clave para lo que gasta dinero o lee tu cuenta.

Públicos o con clave

Todas las rutas cuelgan de https://numestri.com/api/v1. El documento OpenAPI marca la misma división: las operaciones públicas no tienen requisito de seguridad.

Qué cambia una clave en un endpoint público

• Sin clave: recibes los precios de lista públicos y el límite por dirección IP que verás más abajo.

• Con una clave válida: recibes los precios de tu cuenta y el límite de solicitudes de tu cuenta. Una cuenta puede tener sus propios precios negociados, que pueden ser distintos de la lista pública; con tu clave, lo que muestra el catálogo es lo que te cobrará un pedido.

• Con una clave no válida: se rechaza con 403, exactamente igual que en un endpoint con clave. Nunca se recurre a los precios públicos, así que un error al escribir tu clave aparece mientras todavía estás explorando, no en tu primer pedido.

# Precios públicos, sin clave
curl https://numestri.com/api/v1/catalog/platforms

# Los precios de tu cuenta
curl https://numestri.com/api/v1/catalog/platforms -H "Authorization: Bearer $NUMESTRI_KEY"

Obtener una clave

1. Crea una clave

   Inicia sesión, abre Desarrolladores en el panel (/dashboard/developer) y elige Nueva clave. Ponle un nombre según dónde se va a usar (por ejemplo, Servidor de producción). Las claves solo existen si tú las creas: no se genera ninguna al registrarte.

   La clave completa se muestra una sola vez, al crearla; solo guardamos una huella. Si la pierdes, crea una nueva y revoca la anterior.

2. Envíala con cada solicitud que la necesite

   Cualquiera de estas formas funciona. Usa la que ya emplee tu cliente HTTP.

   • Bearer token
   • X-API-Key header
   • key parameter

   curl https://numestri.com/api/v1/request/balance \
     -H "Authorization: Bearer $NUMESTRI_KEY"

   { "balance": "12.50" }

   Si se envía más de una, gana la cabecera Authorization, luego X-API-Key y luego key. Mejor usa una cabecera: una clave en una URL termina en los registros.

3. Revócala cuando ya no la necesites

   Al revocar una clave en Desarrolladores, deja de funcionar de inmediato. Para cambiar una clave, crea la nueva, despliégala y luego revoca la anterior: así nunca hay un momento sin una clave que funcione.

Cuando falta la clave o es incorrecta

{
  "success": 0,
  "errors": [{
    "message": "Invalid API key",
    "param": "key",
    "description": "Your API key, which you can create on the Developer page at /dashboard/developer"
  }]
}

Límites de solicitudes

Si superas un límite, la solicitud se rechaza con 429 y una cabecera Retry-After que indica cuántos segundos esperar. Los dos límites de solicitudes también envían RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset con el rechazo.

{
  "success": 0,
  "errors": [{
    "message": "Rate limit exceeded. Slow down and try again.",
    "description": "Requests without an API key are limited per IP address; send your key for a higher limit."
  }]
}

La description solo aparece en el límite anónimo. Si lo alcanzas desde un servidor, envía tu clave: el límite de la cuenta es más alto y no lo compartes con nadie más que esté detrás de tu dirección. Consultar un pedido cada pocos segundos, o usar /request/active para muchos pedidos a la vez, queda muy por debajo de cualquiera de estos límites. Los niveles del catálogo también admiten If-None-Match, y un 304 es la forma más barata de comprobar si hubo cambios.