Inicio rápido

Esta guía recorre todo el camino, desde "¿qué puedo comprar?" hasta un código de verificación. Los tres primeros pasos no necesitan cuenta ni clave, así que puedes construir y probar las pantallas de tu catálogo antes de registrarte.

1. 1 · Encuentra la plataforma (sin clave)

   Los ids de plataforma son exactos. Lista las plataformas con stock y guarda el id que necesitas:

   curl https://numestri.com/api/v1/catalog/platforms

   {
     "success": 1,
     "prices_at": "2026-10-14T01:40:00.000Z",
     "count": 1326,
     "next": "/api/v1/catalog/platforms/{platform}/countries",
     "data": [
       { "id": "telegram", "name": "Telegram", "countries": 14, "from_price": "0.99", "from_price_cents": 99 }
     ]
   }

   from_price es el número más barato para esa plataforma en cualquier país.

2. 2 · Elige un país (sin clave)

   curl https://numestri.com/api/v1/catalog/platforms/telegram/countries

   {
     "success": 1,
     "prices_at": "2026-10-14T01:40:00.000Z",
     "platform": "telegram",
     "count": 14,
     "next": "/api/v1/catalog/platforms/telegram/countries/{country}/providers",
     "data": [
       { "id": "US", "name": "United States", "providers": 3, "from_price": "0.99", "from_price_cents": 99 }
     ]
   }

   ¿Quieres elegir un proveedor o una oferta concretos? Baja dos niveles más: consulta el árbol del catálogo. Si no, elegimos la mejor opción por ti.

3. 3 · Pide una cotización (sin clave)

   /request/price te dice cuánto costaría un pedido ahora mismo y qué opción lo atendería:

   curl "https://numestri.com/api/v1/request/price?service=telegram&country=US"

   {
     "success": 1,
     "service": { "id": "telegram", "name": "Telegram" },
     "country": { "id": "US", "name": "United States" },
     "price": "0.99",
     "price_cents": 99,
     "high_price": "1.30",
     "option": "5sQY4PwqkxD3gE7O",
     "options": [ … ],
     "shared_inbox": null
   }

   Estos son los precios de lista públicos. Cuando tengas una clave, envíala también aquí y verás los precios de tu cuenta, que son los que realmente se te cobrarán. Consulta Cotizaciones.

4. 4 · Crea una clave y agrega saldo

   Regístrate, abre Desarrolladores en el panel (/dashboard/developer) y elige Nueva clave. Cópiala: solo se muestra una vez. Recarga saldo desde Recargas.

   Guarda la clave en tu servidor, por ejemplo en una variable de entorno, y comprueba que funciona:

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

   { "balance": "10.00" }

   Un 403 aquí significa que la clave es incorrecta; consulta Autenticación.

5. 5 · Pide el número

   Envía la plataforma y el país. Agrega max_price para que el pedido se rechace, sin costo, si el precio subió por encima de lo que estás dispuesto a pagar, y un Idempotency-Key para que una solicitud reintentada nunca compre dos veces.

   • cURL
   • Node
   • Python

   curl https://numestri.com/api/v1/purchase/sms \
     -H "Authorization: Bearer $NUMESTRI_KEY" \
     -H "Idempotency-Key: 7d0f3b8e-4a51-4c1e-9b0a-2f6c1d9e8a31" \
     -d service=telegram -d country=US -d max_price=1.00

   {
     "success": 1,
     "number": 12025550123,
     "cc": "1",
     "phonenumber": "2025550123",
     "order_id": "JRJ5UEXS",
     "country": "United States",
     "country_code": "US",
     "service": "Telegram",
     "service_id": "telegram",
     "expires_in": 1198,
     "expiration": 1792131600,
     "cost": "0.99",
     "cost_in_cents": 99
   }

   cost es lo que se descontó de tu saldo. Se calcula de nuestro lado en el momento del pedido (tú nunca envías un precio) y nunca supera tu max_price. Si lo superara, la respuesta es 400 con el código PRICE_ABOVE_MAX y no se cobra nada.

   Usa el número en la plataforma en la que te estás verificando y guarda el order_id.

6. 6 · Espera el código

   Consulta cada pocos segundos hasta que status sea 3, o evita las consultas por completo con un webhook.

   curl https://numestri.com/api/v1/sms/check -H "Authorization: Bearer $NUMESTRI_KEY" -d orderid=JRJ5UEXS

   • En espera
   • Llegó el código

   { "status": 1, "resend": 0, "time_left": 1188 }

   Deja de consultar con 3 (código) o con 2, 5 o 6 (caducado, cancelado, reembolsado). La lista completa está en Recibir el código.

7. 7 · Cancela, o deja que se reembolse solo

   ¿Cambiaste de idea, o la plataforma nunca envió el SMS? Cancela en cualquier momento antes de que llegue un código y recibirás el reembolso completo:

   curl https://numestri.com/api/v1/sms/cancel -H "Authorization: Bearer $NUMESTRI_KEY" -d orderid=JRJ5UEXS

   { "success": 1, "message": "The order has been cancelled, and you have been refunded 0.99 dollars." }

   Si no haces nada y no llega ningún código antes de que caduque el número, el importe completo se te devuelve automáticamente. Un número que sí recibió un código no se reembolsa. Consulta Cancelaciones, reenvíos y reembolsos.

Todo el ciclo en un script

const api = "https://numestri.com/api/v1";
const auth = { Authorization: `Bearer ${process.env.NUMESTRI_KEY}` };
const call = (path, params, headers = {}) =>
  fetch(`${api}${path}`, { method: "POST", headers: { ...auth, ...headers }, body: new URLSearchParams(params) })
    .then((r) => r.json());

// Público: ¿cuánto costaría? (Va con la clave, así que son tus precios).
const quote = await call("/request/price", { service: "telegram", country: "US" });
if (!quote.success) throw new Error(quote.message ?? quote.errors[0].message);

// Con clave: cómpralo, con el precio cotizado como tope.
const order = await call(
  "/purchase/sms",
  { service: "telegram", country: "US", max_price: quote.price },
  { "Idempotency-Key": crypto.randomUUID() },
);
if (!order.success) throw new Error(`${order.code}: ${order.message}`);
console.log("Usa este número:", order.number);

// Espera el código hasta dos minutos y, si no llega, cancela.
for (let i = 0; i < 30; i++) {
  await new Promise((r) => setTimeout(r, 4000));
  const check = await call("/sms/check", { orderid: order.order_id });
  if (check.status === 3) { console.log("código:", check.sms); process.exit(0); }
  if ([2, 5, 6].includes(check.status)) throw new Error("No llegó ningún código; el pedido se reembolsó.");
}
console.log(await call("/sms/cancel", { orderid: order.order_id }));

Poner quote.price como tope significa que el pedido solo se completa si el precio no cambió desde la cotización. Para admitir una pequeña variación, pon el tope unos centavos más arriba.

Siguientes pasos