Hego Buyer API

Advertencia de Seguridad Crítica

Nunca compartas tu API key. Quien la posea tiene acceso total para gastar el saldo de tu billetera Hego. No la expongas en frontend, query strings, ni repositorios públicos. Usar variables de entorno protegidas.

Base URL & Autenticación

https://api.hegodigitaldev.com/api/v1/buyer

Todas las peticiones (excepto /health) requieren tu clave secreta de API en los headers:

X-API-Key: hg_live_...
// Alternativamente soportado:
Authorization: Bearer hg_live_...

Servicios Operativos

GET /health

Estado público del servicio y disponibilidad operativa.

GET /products

Catálogo completo con descripciones, precios vigentes e instrucciones.

GET /balance

Consulta el saldo actual (USDT) disponible en tu billetera.

POST /orders

Crea una nueva orden de compra, reserva stock y descuenta saldo de manera atómica.

GET /orders/{id}

Consulta el estado de una orden. Retorna credenciales de entrega si está completada.

GET /orders/{id}/download

Obtén un enlace de descarga seguro para productos que entregan archivos binarios.

GET /webhook

Consulta tu configuración actual de notificaciones push asíncronas.

POST /webhook

Registra o actualiza la URL receptora y los eventos a los que deseas suscribirte.

Reglas Estrictas de Compra

Para proteger tus fondos, el endpoint POST /orders es altamente estricto:

Idempotency-Key: Cada petición POST debe enviar este header. Si tu sistema pierde conexión durante la llamada, reintenta con la misma key. Evitarás pagar dos veces por el mismo pedido.
Protección de Precio (expectedPriceUsdt): Debes informar a qué precio planeas comprar. Si el costo del producto varió desde tu última sincronización de catálogo, la orden es rechazada (409 PRICE_CHANGED) sin cargos.
Stock Integral: No existen entregas parciales. Si pides 5 unidades y solo hay 4, se rechaza la orden completa.
Destinatario Telegram: Si el producto de recarga exige un usuario, el campo recipientUsername debe empezar obligatoriamente con @.

Entrega de Contenido

La arquitectura de Hego procesa algunos proveedores de manera inmediata y otros mediante delegación asíncrona:

Productos Inmediatos (Stock Local/B2B): Al llamar a POST /orders, la respuesta contendrá un estado completed y el array de ítems (credenciales, links, pines) en el campo delivery.items.
Productos Asíncronos (Proveedores Externos): El estado devuelto será pending_delivery. Deberás escuchar el evento webhook order.completed o hacer polling a GET /orders/{id} para obtener el contenido final.
Archivos Binarios (file): Los archivos NUNCA viajan embebidos por JSON. El API te devolverá un downloadUrl autenticado. Haciendo GET a esta URL obtendrás el archivo original en binario puro.

Webhooks y Reintentos

Tu integración debe ser reactiva

Precios, stock y descripciones cambian en tiempo real. Suscríbete a eventos de catálogo para actualizar tu frontend o bases de datos internas antes de intentar vender un producto.

Suscríbete con POST /webhook. Hego despachará un payload POST a tu URL firmado criptográficamente (HMAC-SHA256) en el header X-Hego-Signature.

Eventos Soportados

catalog.updated: Un producto ha cambiado de precio, nombre, estado (activo/inactivo) o descripción.
stock.changed: El inventario de un producto ha variado (recarga, consumo, retiro).
order.completed: Una orden asíncrona se entregó. (El webhook avisa el estado, luego debes hacer GET para leer los items).
order.failed: Una orden asíncrona fracasó y el dinero se ha reembolsado intacto a tu saldo.
balance.low: Tu saldo de billetera USDT ha caído por debajo de tu balanceThresholdUsdt.

Tolerancia a Fallos

Si tu servidor no responde con un estado 2xx a nuestro webhook, reintentaremos la entrega 5 veces progresivamente (1m, 5m, 30m, 6h, 24h). Usa el ID de entrega o el estado del pedido para deduplicar los eventos procesados en tu backend.

Manejo de Errores

Todos los errores 4xx y 5xx retornan un objeto JSON con el código de estado, un código de error (error), un mensaje descriptivo y un requestId único para rastreo.

Nota Operativa: Cualquier error 400, 401 o 429 disparará internamente una alerta automática al equipo de desarrolladores de Hego con tu requestId para diagnosticar tu integración de forma proactiva.

Código HTTP	Causa Principal
400 Bad Request	Payload inválido, falta de `productId` o formato erróneo del destinatario.
401 Unauthorized	API key inválida, revocada o faltante en los headers.
409 Conflict	Conflicto: `expectedPriceUsdt` no coincide con el real (PRICE_CHANGED) o Idempotency-Key en colisión.
429 Too Many Requests	Excedido el Rate Limit o frenado por el límite preventivo de protección de saldo bajo.
500 Server Error	Caída interna de la plataforma o de la BBDD.

¿Para qué sirve el openapi.yaml?

El estándar OpenAPI (antes conocido como Swagger) describe programáticamente todas nuestras rutas, esquemas, ejemplos y parámetros. Te ahorra días de trabajo:

Generación de Código: Usa herramientas como openapi-generator para compilar el cliente completo de nuestra API en Node.js, Python, PHP o Go en un solo comando.
Postman / Insomnia: Importa el archivo openapi.yaml en Postman y tendrás toda la colección de endpoints preconfigurada y lista para lanzar peticiones.

Descargar openapi.yaml