Preguntas frecuentes
Preguntas y respuestas sobre la API de Bulk SMS
39 respuestas sobre cuentas, envíos, precios, informes de entrega y la API, verificadas con los límites en el código. Para endpoints y campos, la Referencia de la API tiene los detalles.
El servicio
¿Qué es BulkSMSAPI?
Una API de SMS Masivos para desarrolladores: envía un mensaje o un lote de hasta 10,000 números por solicitud a 227 países mediante REST, sigue cada mensaje con webhooks firmados y paga por mensaje desde un saldo prepago. Una consola web envía campañas desde una lista pegada o CSV sin código.
¿Quién usa una API de SMS Masivos?
Equipos de producto e ingeniería que envían mensajes desde sus propios sistemas: códigos de inicio de sesión y registro, actualizaciones de pedidos y entregas, recordatorios de citas, alertas de pago, avisos de servicio y campañas de marketing. Cualquier persona que pueda hacer una solicitud HTTPS puede usarlo.
¿A qué países puedo enviar?
227 países y territorios, listados con sus precios en la página de precios y las páginas de países. Una solicitud puede mezclar países: cada número se cobra según el país al que pertenece.
¿Hay una tarifa mensual o un contrato?
No. Pagas por segmento de mensaje desde un saldo prepago, y no hay tarifa mensual, tarifa de configuración o volumen mínimo. El saldo no tiene fecha de vencimiento.
¿Hay una prueba gratuita?
Las cuentas comienzan con un saldo cero y la primera recarga abre todo. La primera recarga añade una bonificación de hasta el 40%, por lo que los primeros mensajes cuestan menos. Los precios son públicos, y el endpoint de estimación y la consola muestran el costo exacto antes de enviar cualquier cosa.
Cuenta y claves API
¿Cómo creo una cuenta?
Abre Obtener clave API. Tu navegador crea una clave de cuenta que comienza con acct_; cópiala o guárdala como un archivo de texto, confirma que la guardaste, y la cuenta estará lista. La clave de cuenta es el único inicio de sesión: no hay correo electrónico o contraseña que gestionar.
¿Qué pasa si pierdo mi clave de cuenta?
Solo almacenamos un hash cifrado de ella, por lo que nadie puede mostrarla nuevamente, incluido nuestro equipo de soporte. Guárdala en un gestor de contraseñas. Mientras sigas conectado, la consola sigue funcionando, y puedes contactar al soporte desde ella.
¿Cómo obtengo una clave API?
En la página de claves API de la consola, después de que se acredite la primera recarga. Nombra la clave, créala y cópiala una vez: comienza con bsa_live_. Una cuenta puede tener 10 claves activas, cada una con su propio nombre y contador de límite de tasa.
¿Puedo usar claves diferentes para producción y staging?
Sí. Crea una clave por app o entorno y asígnale un nombre. Cada clave muestra cuándo se usó por última vez, y revocar una no afecta a las demás.
¿Cuántas cuentas puedo crear?
Hasta 3 cuentas por dirección de red. La mayoría de equipos necesitan una cuenta con varias claves API.
Envío de mensajes
¿Cuántos números puede manejar una solicitud?
POST /v1/batches acepta hasta 10,000 números por solicitud, con un texto para todos o personalizado por número. La consola maneja 50,000 números por campaña. Las listas más grandes se dividen en varias solicitudes.
¿Qué tan rápido se envían los mensajes?
La cola se procesa cada dos segundos y envía hasta 1,200 mensajes por minuto por cuenta a la red, en el orden de recepción. Un mensaje individual suele enviarse en segundos.
¿En qué formato deben estar los números de teléfono?
Formato E.164 internacional: signo +, código de país y número local, ej. +14155550123. Espacios, guiones, paréntesis y prefijo 00 se limpian automáticamente; los duplicados y números inválidos no se cobran.
¿Qué longitud puede tener un mensaje?
Hasta 10 segmentos: 1,530 caracteres GSM-7 o 670 Unicode. Un segmento contiene 160 GSM-7 o 70 Unicode; textos largos se dividen en partes de 153/67 caracteres y se unen en el teléfono.
¿Por qué mi mensaje usó más segmentos de lo esperado?
Un carácter fuera de GSM-7 (como comillas curvas, emoji o letras como á, ç) cambia todo el texto a Unicode (70 caracteres/segmento). El editor de la consola los identifica, y POST /v1/estimates devuelve la codificación antes de enviar.
¿Puedo programar mensajes?
Sí. Agrega send_at en la API o elige hora en la consola (de 2 minutos a 45 días después). Un lote programado puede cancelarse antes de empezar, con reembolso total.
¿Cada destinatario puede recibir un texto diferente?
Sí. Por API, envía un lote con mensajes {to, text} por destinatario. En consola, pega/sube una lista con columnas extra y usa campos {{1}} a {{9}} en el texto.
¿Se añade línea de exclusión a mis mensajes?
Configura el texto de exclusión en Ajustes (ej. enlace o email) y la consola lo añade a campañas si marcas la opción. Por API controlas el texto completo: añádelo tú en mensajes comerciales. Los números en tu lista de no enviar se omiten sin costo.
¿Puedo enviar un mensaje de prueba primero?
Sí. La consola permite prueba a un número antes de la campaña, y por API puedes enviar un mensaje a tu teléfono con POST /v1/messages.
Precios y pagos
¿Cuánto cuesta un SMS?
Depende del país del número: cada país tiene un precio por segmento en USD, desde $0.00247 (Brasil). La página de precios y GET /v1/pricing los listan.
¿Cómo se calcula el costo de un lote?
Por destinatario: precio por segmento de su país × segmentos de su texto. El total se deduce del saldo al aceptar la solicitud, y la respuesta lo muestra en cost.
¿Cuál es el mínimo para recargar?
$40. Una recarga puede ser cualquier cantidad desde $40 hasta $5,000. La primera recarga añade un bono de hasta el 40%, que se muestra en cada cantidad antes de pagar.
¿Cómo puedo pagar?
En la consola, Facturación abre una ventana de pago sobre la página. Eliges la cantidad y pagas con criptomoneda, y la página de pago muestra el monto exacto y la dirección. La página de pagos lista cada paso.
¿Se reembolsan los mensajes fallidos?
Sí. Cuando un mensaje falla, su precio se devuelve automáticamente al saldo en el mismo proceso, como una línea de reembolso en el registro. Un lote programado cancelado se reembolsa en su totalidad.
¿Puedo retirar mi saldo?
El saldo se usa para pagar mensajes y permanece en tu cuenta sin fecha de expiración. Los reembolsos por mensajes fallidos o cancelados también regresan al saldo.
¿Cambian los precios?
Los precios pueden cambiar cuando los costos de la red cambian. La lista actual está fechada, la API devuelve la fecha con cada precio, y los mensajes ya aceptados mantienen el precio al que se les cobró.
Entrega e informes
¿Cómo sé si un mensaje fue entregado?
Cada mensaje pasa de estar en cola a enviado, entregado o fallido. Añade una URL de webhook en la consola para obtener un evento firmado por cada estado final, o lee GET /v1/messages/{id} y GET /v1/batches/{id}.
¿Cómo se firman los webhooks?
En el formato Standard Webhooks: cabeceras webhook-id, webhook-timestamp y webhook-signature, donde la firma es HMAC-SHA256 del id, timestamp y cuerpo crudo con tu secreto whsec_. La documentación tiene código de verificación para Node.js, Python, PHP y Go.
¿Qué pasa si mi endpoint de webhook está caído?
Cada evento recibe 10 intentos durante aproximadamente 24 horas, y cada intento se lista en la consola con su estado HTTP. También puedes sondear los endpoints de mensajes en cualquier momento.
¿Por qué fallaría un mensaje?
El teléfono puede estar apagado por demasiado tiempo, el número puede ya no estar en servicio o la red puede rechazar el mensaje. El estado fallido incluye un código de error, y el precio se reembolsa.
¿Cuánto tiempo se conservan los registros de mensajes?
Los lotes, mensajes y el registro de saldo permanecen en tu cuenta y en la API. El registro de solicitudes guarda tus últimas 500 llamadas API y el registro de webhooks tus últimas 500 entregas.
Para desarrolladores
¿Hay un SDK?
La API es JSON simple sobre HTTPS, por lo que la biblioteca estándar de cualquier lenguaje es suficiente. La documentación tiene ejemplos completos en curl, Node.js, Python, PHP y Go, y la especificación OpenAPI en /openapi.json genera un cliente tipado en la mayoría de los lenguajes.
¿Cuáles son los límites de tasa?
600 solicitudes por minuto por clave API. Cada respuesta tiene las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset, y una respuesta 429 tiene Retry-After.
¿Cómo reintento de manera segura después de un tiempo de espera?
Envía solicitudes POST con una cabecera Idempotency-Key y reintenta con la misma clave. Durante 24 horas, la misma clave y cuerpo devuelven la primera respuesta en lugar de enviar de nuevo.
¿Puedo verificar precios sin una clave API?
Sí. GET /v1/pricing y GET /v1/pricing/{country} son públicos, por lo que una página de pago o panel puede mostrar precios en vivo.
¿Dónde puedo ver lo que envió mi código?
La consola tiene un registro de solicitudes con el método, ruta, estado y hora de tus últimas 500 llamadas API, junto a lotes, mensajes y el registro de webhooks.
La consola
¿Puedo enviar sin escribir código?
Sí. En la consola, pega números o sube un archivo CSV de hasta 50,000 filas, escribe el texto con campos de fusión, revisa la vista previa para cada destinatario y el costo por país, y envía ahora o a una hora programada.
¿Qué muestra la consola?
Saldo, lotes recientes con conteos en vivo, cada lote con sus mensajes y estados, recargas y el libro mayor, claves API, configuraciones y entregas de webhooks, el registro de solicitudes, la lista de precios, tickets de soporte y configuraciones.
¿Cómo contacto al soporte?
Desde la página de Soporte en la consola. Las preguntas sobre pagos se pueden hacer desde el primer día; los otros temas se habilitan después de que se acredite la primera recarga.
¿Aún tienes una pregunta?
Las cuentas registradas pueden abrir un ticket de soporte desde la consola. Las preguntas sobre pagos se pueden hacer desde el primer día.