Hacer un pedido
Pide un número con /purchase/sms: la mejor opción, la de un proveedor concreto o exactamente la opción que elegiste, con un precio máximo.
Insertar
<a href="https://numestri.com/docs/es/placing-an-order"><img src="https://numestri.com/docs/_api/public/orgs/25229885-9620-4c08-bd2e-a0d0d74ac8b6/spaces/ef21e0c3-966d-4b03-b6d2-e66d449835d4/pages/314bc2ee-7b02-4d05-8ab0-b69f802e413e/social-card.svg?v=3e7ae33eec8b" alt="Hacer un pedido" width="600" height="315"></a>/purchase/sms compra un número para una plataforma y un país. Necesita una clave de API, y se descuenta de tu saldo en el momento en que se emite el número.
Todo lo que necesitas para elegir (los ids de plataforma y de país, los proveedores, las opciones y sus precios) lo obtienes del catálogo y de /request/price, que puedes llamar sin clave.
Tres formas de elegir
- Mejor opción
- Un proveedor
- Opción exacta
Indica la plataforma y el país. La mejor opción con stock atiende el pedido y, si no puede entregarlo, la siguiente toma el relevo.
curl https://numestri.com/api/v1/purchase/sms -H "Authorization: Bearer $NUMESTRI_KEY" \
-d service=telegram -d country=USAñade provider. Solo ese proveedor atiende el pedido, empezando por su mejor opción.
curl https://numestri.com/api/v1/purchase/sms -H "Authorization: Bearer $NUMESTRI_KEY" \
-d service=telegram -d country=US -d provider=prv_k3Jd9QmXa2Si no tiene nada en stock, el pedido se rechaza con el código PROVIDER_UNAVAILABLE; nadie más lo atiende.
Añade option. Esa oferta exacta atiende el pedido al precio indicado, o el pedido se rechaza con el código OPTION_GONE. Nunca se sustituye por otra.
curl https://numestri.com/api/v1/purchase/sms -H "Authorization: Bearer $NUMESTRI_KEY" \
-d service=telegram -d country=US -d option=5sQY4PwqkxD3gE7OParámetros
Parámetro | Obligatorio | Significado |
|---|---|---|
| sí | Id de la plataforma en el catálogo, p. ej. |
| sí | Código ISO del país, p. ej. |
| no | Un id de proveedor. Solo ese proveedor atiende el pedido. |
| no | Un id de opción. Exactamente esa oferta, o nada. |
| no | Rechaza el pedido si el precio supera este importe, en dólares, p. ej. |
| no |
|
| no | Una cabecera (o parámetro |
El precio que pagas
Nunca envías un precio. El importe que se cobra se calcula de nuestro lado cuando se hace el pedido, para tu cuenta: es el mismo precio que te muestran el catálogo y /request/price cuando envías tu clave, y puede ser distinto de la lista pública si tu cuenta tiene precios negociados. Con option, es el precio de lista de esa opción; con provider, la opción más barata con stock de ese proveedor; y si no, el precio de la mejor opción. Si una opción falla y la siguiente toma el relevo, se te sigue cobrando el precio fijado al principio.
Los precios se mueven con el mercado, así que una cotización no es una reserva. max_price es tu tope: si el precio lo supera, el pedido se rechaza con 400 y el código PRICE_ABOVE_MAX, y no se cobra nada. El cost de la respuesta es siempre lo que realmente se cobró.
Respuesta
{
"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
}Guarda order_id: es lo que te permite recibir el código, cancelar o pedir un reenvío.
Los números compartidos son públicos
number_class=shared compra un número cuyo buzón es una página web pública: cualquiera puede leer el código. Úsalo solo cuando eso no importe.
Cuando se rechaza un pedido
Un pedido rechazado no cuesta nada. Decide según type (o el más específico code) y no según el texto del mensaje; consulta Errores para ver la lista completa.
{
"success": 0,
"message": "That option is no longer available. Pick another.",
"type": "OUT_OF_STOCK",
"code": "OPTION_GONE"
}