Cotizaciones y listas públicas

Una cotización para una plataforma y un país

/request/price responde a "¿cuánto cobraría /purchase/sms ahora mismo?" y muestra todas las opciones que hay detrás de la respuesta. Es pública: no necesitas clave.

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",
  "success_rate": null,
  "quality": null,
  "option": "5sQY4PwqkxD3gE7O",
  "options": [
    { "option": "5sQY4PwqkxD3gE7O", "provider": "prv_k3Jd9QmXa2", "rank": 1, "price": "0.99", "price_cents": 99, "quality": null, "success_rate": null, "stock": "plenty", "in_stock": true },
    { "option": "Hq2LmW8eRt5YxP0c", "provider": "prv_9TfXk2LwQa", "rank": 2, "price": "1.30", "price_cents": 130, "quality": null, "success_rate": null, "stock": "limited", "in_stock": true }
  ],
  "shared_inbox": { "price": "0.05", "price_cents": 5 }
}

Cuando no hay respuesta

{
  "success": 0,
  "message": "No Telegram numbers in United States right now.",
  "type": "OUT_OF_STOCK",
  "options": [
    { "option": "5sQY4PwqkxD3gE7O", "provider": "prv_k3Jd9QmXa2", "rank": 1, "price": "0.99", "price_cents": 99, "quality": null, "success_rate": null, "stock": "none", "in_stock": false }
  ],
  "shared_inbox": null
}

Precios públicos y tus precios

Sin clave, una cotización muestra el precio de lista público. Con tu clave, muestra el precio de tu cuenta (el mismo, salvo que tu cuenta tenga precios negociados), que es exactamente lo que se le cobrará a un pedido de esa cuenta.

# Precio de lista público
curl "https://numestri.com/api/v1/request/price?service=telegram&country=US"

# El precio que paga tu cuenta
curl "https://numestri.com/api/v1/request/price?service=telegram&country=US" -H "Authorization: Bearer $NUMESTRI_KEY"

Una clave incorrecta se rechaza con 403 en lugar de mostrar en silencio los precios públicos. Sin clave, las cotizaciones cuentan para el límite por dirección de 10 solicitudes por segundo; consulta Autenticación.

De la cotización al pedido: max_price

Una cotización no es una reserva. Los precios y el stock se mueven, y el precio que se te cobra siempre se calcula de nuestro lado cuando se hace el pedido: tú nunca envías un precio. Para asegurarte de no pagar más de lo que esperas, envía max_price (en dólares) a /purchase/sms:

curl https://numestri.com/api/v1/purchase/sms -H "Authorization: Bearer $NUMESTRI_KEY" \
  -d service=telegram -d country=US -d max_price=0.99

• Si el precio es igual o inferior a max_price, el pedido se completa y el cost de la respuesta es lo que se cobró.

• Si lo supera, el pedido se rechaza antes de cobrar nada:

  {
    "success": 0,
    "message": "The price for this number is $1.05, above your maximum.",
    "type": "PRICE_NOT_FOUND",
    "code": "PRICE_ABOVE_MAX"
  }

• max_price debe ser un importe positivo en dólares, como 0.75; cualquier otra cosa devuelve un 400 con param: "max_price".

Para asegurarte una oferta exacta en lugar de un tope, envía el id option de esa oferta: se compra a su precio de lista o no se compra (OPTION_GONE).

Listas públicas, sin clave

Mantienen el formato que usan la mayoría de las API de verificación, para que una tienda pueda mostrar lo que está a la venta sin una clave de API.

ID es el id exacto que aceptan los endpoints de pedidos. Estas dos muestran siempre los precios públicos y se guardan en caché durante unos minutos.