Una integración fiable separa catálogo, cotización vinculada al usuario, creación idempotente, consulta y cancelación confirmada. Mantén claves del proveedor en el servidor y comprueba titularidad en cada petición. Una respuesta incierta requiere conciliación, no otra compra automática ni un reembolso sin confirmación.
Separa la interfaz del acceso al proveedor
El navegador llama a tu API; el servidor contacta al proveedor SMS. Guarda credenciales como secretos del entorno y devuelve únicamente campos necesarios al usuario autenticado. Un catálogo público es distinto de una cuenta o bandeja privada. Comprueba titularidad en cada consulta, cancelación y finalización. Autenticar solo la ruta de compra no protege el resto del ciclo.
Usa una cotización autorizada y breve
POST /api/v1/quotes de ReceiveSMSGo crea una cotización vinculada al usuario por 60 segundos. El servidor calcula USD como max(0,39 USD, coste convertido × 2). El cliente envía un identificador para comprar, no un precio confiable. Si caduca, solicita otra. Una oferta puede agotarse entre consulta y compra; representa los errores de disponibilidad explícitamente.
Reserva una vez y concilia compras inciertas
POST /api/v1/orders exige Idempotency-Key y quoteId. Reutilizar la misma clave para la misma operación devuelve el pedido existente. Reserva de saldo y registro contable se implementan de forma atómica. Si la respuesta es ambigua, el pedido pasa a revisión en vez de volver a comprar. La idempotencia protege tu aplicación, pero no concilia por sí sola un timeout del proveedor.
- Crea una clave por compra prevista y mantenla en reintentos.
- Envía la cotización actual con el contexto autenticado.
- Concilia resultados ambiguos antes de iniciar otra compra.
Consulta el pedido sin saturar al proveedor
GET /api/v1/orders/{id} devuelve el pedido del usuario y puede refrescar un estado activo. La implementación limita consultas al proveedor a una cada cinco segundos por pedido. Modela espera, recibido, finalizado, cancelado, caducado y revisión por separado. No inventes una caducidad si las unidades de la documentación no están claras. Cerrar el navegador no prueba que el pedido remoto terminó.
Confirma la cancelación antes de modificar saldo
POST /api/v1/orders/{id} admite cancel o finish. La cancelación se bloquea 120 segundos desde la creación; después el servidor solicita confirmación antes de un reembolso único. Finalizar requiere un código recibido. Las acciones simultáneas usan transiciones para evitar solapamientos. Un fallo de red no debe interpretarse como cancelación confirmada ni permiso para duplicar el crédito.
Verifica callbacks y preparación operativa
Una notificación entrante no es automáticamente una fuente autorizada. Tras verificar la firma de Stripe, se consulta el registro oficial del pago antes de acreditar saldo. Una notificación de estado de SMS sin firma solo sirve como señal para consultar el estado autenticado del pedido. Los eventos de prueba y reales de Stripe deben coincidir con su secreto de endpoint, cuenta y entorno del ingreso. Las notificaciones externas deben ser accesibles; un redireccionamiento no es prueba de pago. Las API del espacio de trabajo requieren una sesión autenticada del sitio, no una clave pública de API para desarrolladores. Consulta las operaciones habilitadas y OpenAPI antes de integrar.
Preguntas útiles, respuestas claras
¿Puedo poner la clave del proveedor en el frontend?
No. Guárdala como secreto del servidor. El frontend llama a tu API con contexto del usuario autenticado.
¿Reintento una compra con timeout usando otra clave?
Primero consulta y concilia el pedido original. Otra clave representa otra compra y puede generar otro cargo.
¿La API del panel es un producto público con clave de desarrollador?
No. Cuenta y pedidos requieren sesión del sitio. El producto público separado aún no está disponible; revisa operaciones habilitadas antes de integrar.
Fuentes y lecturas adicionales
Las fuentes describen sus propios servicios y pueden cambiar. Consulta los requisitos actuales del destino antes de elegir un número.
Entiende el flujo antes de empezar.
Explora la selección de servicios, las opciones de países y el estado del SMS en el espacio de trabajo. Las cotizaciones y la disponibilidad dependen del proveedor; la aceptación y la entrega no están garantizadas. El monedero y los pedidos requieren iniciar sesión.
Abrir espacio de trabajo
