Lee el catálogo y fija un límite de precio
Empieza con GET /api/auth/me para confirmar la cuenta autenticada y el saldo. GET /api/catalog/services y GET /api/catalog/countries proporcionan los identificadores. Consulta ofertas con GET /api/catalog/prices?service=tg y sustituye tg por el código elegido; el parámetro opcional country limita el resultado a un país.
POST /api/orders acepta service, country, max_price_micros e idempotency_key. Envía country como cadena. Los límites monetarios usan enteros en microdólares: 1.000.000 de unidades equivalen a 1 USD. Utiliza el price_micros recibido como límite. Si la oferta lo supera, actualízala y confirma el nuevo importe antes de comprar.
Haz que los reintentos correspondan a la misma compra
Genera un idempotency_key único para cada compra prevista y guárdalo antes de enviar la solicitud. Si la respuesta se interrumpe, repite esa operación con la misma clave. Crear una clave nueva para un reintento de transporte puede generar otra compra.
Comprueba el estado devuelto: no toda respuesta HTTP 200 significa que se haya asignado un número. El pedido puede estar en compra, espera, recibido, fallido o en revisión. La revisión puede indicar un resultado incierto del proveedor y un cargo reservado. No lo sustituyas automáticamente por un pedido nuevo.
Consulta y actúa sobre el pedido existente
GET /api/orders lista tus pedidos; GET /api/orders/{id} consulta uno, y POST /api/orders/{id}/refresh solicita actualizar su estado. Respeta los límites de frecuencia y usa consultas periódicas con pausas y retroceso ante errores. Después de utilizar el código, POST /api/orders/{id}/finish permite finalizar una activación recibida elegible.
POST /api/orders/{id}/cancel aplica la misma espera y condición de no haber recibido código que la web. Una solicitud o un tiempo de espera agotado no prueba un reembolso. Consulta el resultado y GET /api/wallet/transactions para conciliar tus registros.
Protege la clave como acceso a tu cuenta
No incluyas claves en JavaScript del navegador, repositorios públicos, URL ni capturas. Revoca una clave desde el área de desarrolladores si se expone o deja de ser necesaria. Evita registrar cabeceras de autorización y mensajes completos de verificación cuando no sean necesarios.
Gestiona explícitamente el saldo insuficiente, la falta de inventario, los cambios de precio, los límites de frecuencia y los resultados inciertos. Prueba un flujo pequeño e intencionado, conserva los identificadores de pedido y consulta la referencia interactiva antes de desplegar tu integración.