Compra productos digitales desde tu propio sistema

Guía rápida#

En cinco pasos pasas de cero a tu primera compra automatizada.

1. Genera tu API key

   En el bot de Telegram abre Perfil → API de desarrollador → Generar y acepta las condiciones. La key empieza con hg_live_ y se muestra una sola vez: guárdala en un gestor de secretos.

   Puedes tener una sola key activa. Puedes generarla aunque todavía no hayas recargado saldo.

2. Recarga tu billetera

   Las compras por API se cobran de tu billetera en USDT, la misma que usas en el bot. Recarga desde la sección de billetera del bot y comprueba el saldo:

   cURLJavaScriptPython

   Copiar

   curl https://api.hegodigitaldev.com/api/v1/buyer/balance \
     -H "X-API-Key: hg_live_TU_API_KEY"

   200 OKRespuestaCopiar

   {
     "success": true,
     "balanceUsdt": 143.25,
     "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
   }

3. Consulta el catálogo

   Elige un id y anota su priceUsdt. Si requiresRecipient es true, necesitarás el usuario de Telegram que recibirá el producto.

   cURLJavaScriptPython

   Copiar

   curl https://api.hegodigitaldev.com/api/v1/buyer/products \
     -H "X-API-Key: hg_live_TU_API_KEY"

   200 OKRespuestaCopiar

   {
     "success": true,
     "products": [
       {
         "id": 102,
         "name": "Netflix 1 Pantalla (30 días)",
         "description": "Perfil individual con PIN. Renovable.",
         "instructions": "Ingresa con el correo y la clave entregados. No cambies la contraseña.",
         "priceUsdt": 3.5,
         "availableStock": 18,
         "requiresRecipient": false
       },
       {
         "id": 215,
         "name": "Telegram Premium 3 meses",
         "description": "Activación directa en la cuenta que indiques.",
         "instructions": "",
         "priceUsdt": 14.9,
         "availableStock": "unlimited",
         "requiresRecipient": true
       }
     ],
     "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
   }

4. Haz tu primera compra

   Envía productId, quantity y el precio total que esperas pagar. Genera un Idempotency-Key nuevo (un UUID) para cada compra y guárdalo antes de enviar.

   cURLJavaScriptPython

   Copiar

   curl -X POST https://api.hegodigitaldev.com/api/v1/buyer/orders \
     -H "X-API-Key: hg_live_TU_API_KEY" \
     -H "Idempotency-Key: 7f9c2e0a-51d4-4c1b-9a67-3e0d2b8a11f4" \
     -H "Content-Type: application/json" \
     -d '{"productId": 102, "quantity": 2, "expectedPriceUsdt": 7}'

   201 CreatedRespuestaCopiar

   {
     "success": true,
     "orderId": 45012,
     "status": "completed",
     "productId": 102,
     "quantity": 2,
     "totalPriceUsdt": 7,
     "createdAt": 1767225600000,
     "delivery": {
       "items": [
         "maria.lopez@example.com:Pass#8842",
         "juan.perez@example.com:Pass#1937"
       ]
     },
     "balanceAfterUsdt": 143.25,
     "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
   }

   Ya compraste

   La entrega viene en delivery.items. Además recibes una copia en tu chat de Telegram.

5. Recibe eventos (recomendado)

   Configura un webhook para enterarte de cambios de precio y stock, entregas asíncronas y saldo bajo sin consultar la API cada minuto. Ver Webhooks.

Formato de las respuestas#

Todas las respuestas son JSON en UTF-8, salvo la descarga de archivos. Cada respuesta incluye:

Convenciones

• Montos: siempre en USDT, como número JSON (3.5, no "3.50"). Los precios tienen hasta 2 decimales.
• Fechas: createdAt es un entero en milisegundos Unix (UTC).
• IDs: orderId y productId son enteros.
• Sin caché: las respuestas llevan Cache-Control: no-store.
• Ignora los campos que no conozcas: podemos añadir campos nuevos sin avisar (nunca quitaremos ni cambiaremos los existentes dentro de /v1).

Autenticación y permisos#

Envía tu API key en cada petición (salvo /health), con cualquiera de estos dos headers:

X-API-Key: hg_live_TU_API_KEY

# o, equivalente
Authorization: Bearer hg_live_TU_API_KEY

Cada key tiene permisos (scopes). Las keys nuevas incluyen todos:

• 401UNAUTHORIZED — la key falta, es inválida, fue regenerada o desactivada.
• 403FORBIDDEN — la key es válida pero no tiene el scope necesario (Missing orders:write scope).

{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

Productos y entrega#

El catálogo es vivo: precios, descripciones y stock cambian en tiempo real. Cada producto se entrega de una de estas formas:

Precio y stock

• priceUsdt es el precio por unidad. El precio total de una compra puede diferir de priceUsdt × quantity si el producto tiene precios por volumen.
• availableStock es un número, o "unlimited" para productos sin límite. En productos de proveedores externos es una cifra aproximada que se refresca periódicamente: si se agota antes, la compra responde OUT_OF_STOCK o PURCHASE_FAILED.
• El stock se reserva de forma atómica por compra: dos compras simultáneas nunca reciben el mismo item.
• Saldo retenido: mientras una compra a un proveedor externo está en curso (normalmente un instante), el importe queda retenido y tu saldo disponible en GET /balance baja. Se descuenta definitivamente al completarse y se libera solo si la compra falla.
• Solo aparecen los productos activos.

Estados de una orden#

GET /orders/{id} devuelve cualquier orden de tu cuenta, incluidas las que hiciste desde el bot de Telegram.

Idempotencia y reintentos#

Las redes fallan: una petición puede llegar y su respuesta perderse. Para que reintentar nunca compre dos veces, POST /orders exige el header Idempotency-Key.

Qué se repite y qué no

Límites y tiempos#

Ante un 429 o un 5xx, espera con retroceso exponencial (1 s, 2 s, 4 s…) y respeta Retry-After cuando exista.

Copia en Telegram#

Aunque compres por API, la entrega también llega a tu chat con el bot, idéntica a una compra normal: resumen de la orden, un archivo .txt de respaldo, los items listos para copiar y botones de soporte, reporte de problemas y “Mis compras”.

Es una copia de cortesía: tu integración debe usar siempre la respuesta de la API. Si bloqueaste el bot o no tienes chat abierto, la compra funciona igual.

Referencia de endpoints#

Base URL: https://api.hegodigitaldev.com/api/v1/buyer. Todos los endpoints salvo /health requieren tu API key.

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

const res = await fetch('https://api.hegodigitaldev.com/api/v1/buyer/health');
console.log(await res.json());

import requests

print(requests.get('https://api.hegodigitaldev.com/api/v1/buyer/health', timeout=10).json())

{
  "success": true,
  "service": "buyer-api",
  "status": "ok",
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

curl https://api.hegodigitaldev.com/api/v1/buyer/products \
  -H "X-API-Key: hg_live_TU_API_KEY"

const res = await fetch('https://api.hegodigitaldev.com/api/v1/buyer/products', {
  headers: { 'X-API-Key': process.env.HEGO_API_KEY },
});
const { products } = await res.json();

for (const p of products) {
  console.log(p.id, p.name, p.priceUsdt, p.availableStock);
}

import os, requests

res = requests.get(
    'https://api.hegodigitaldev.com/api/v1/buyer/products',
    headers={'X-API-Key': os.environ['HEGO_API_KEY']},
    timeout=15,
)
for p in res.json()['products']:
    print(p['id'], p['name'], p['priceUsdt'], p['availableStock'])

{
  "success": true,
  "products": [
    {
      "id": 102,
      "name": "Netflix 1 Pantalla (30 días)",
      "description": "Perfil individual con PIN. Renovable.",
      "instructions": "Ingresa con el correo y la clave entregados. No cambies la contraseña.",
      "priceUsdt": 3.5,
      "availableStock": 18,
      "requiresRecipient": false
    },
    {
      "id": 215,
      "name": "Telegram Premium 3 meses",
      "description": "Activación directa en la cuenta que indiques.",
      "instructions": "",
      "priceUsdt": 14.9,
      "availableStock": "unlimited",
      "requiresRecipient": true
    }
  ],
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

curl https://api.hegodigitaldev.com/api/v1/buyer/balance \
  -H "X-API-Key: hg_live_TU_API_KEY"

const res = await fetch('https://api.hegodigitaldev.com/api/v1/buyer/balance', {
  headers: { 'X-API-Key': process.env.HEGO_API_KEY },
});
const { balanceUsdt } = await res.json();
console.log(`Saldo: ${balanceUsdt} USDT`);

import os, requests

res = requests.get(
    'https://api.hegodigitaldev.com/api/v1/buyer/balance',
    headers={'X-API-Key': os.environ['HEGO_API_KEY']},
    timeout=15,
)
print(res.json()['balanceUsdt'])

{
  "success": true,
  "balanceUsdt": 143.25,
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

curl -X POST https://api.hegodigitaldev.com/api/v1/buyer/orders \
  -H "X-API-Key: hg_live_TU_API_KEY" \
  -H "Idempotency-Key: 7f9c2e0a-51d4-4c1b-9a67-3e0d2b8a11f4" \
  -H "Content-Type: application/json" \
  -d '{"productId": 102, "quantity": 2, "expectedPriceUsdt": 7}'

import { randomUUID } from 'node:crypto';

const idempotencyKey = randomUUID(); // guárdala ANTES de enviar

const res = await fetch('https://api.hegodigitaldev.com/api/v1/buyer/orders', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.HEGO_API_KEY,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ productId: 102, quantity: 2, expectedPriceUsdt: 7 }),
});

const order = await res.json();
if (res.status === 201) {
  console.log(order.orderId, order.status, order.delivery?.items);
} else {
  console.error(order.error, order.message);
}

import os, uuid, requests

idempotency_key = str(uuid.uuid4())  # guárdala ANTES de enviar

res = requests.post(
    'https://api.hegodigitaldev.com/api/v1/buyer/orders',
    headers={
        'X-API-Key': os.environ['HEGO_API_KEY'],
        'Idempotency-Key': idempotency_key,
    },
    json={'productId': 102, 'quantity': 2, 'expectedPriceUsdt': 7},
    timeout=30,
)
order = res.json()
if res.status_code == 201:
    print(order['orderId'], order['status'], order.get('delivery'))
else:
    print(order['error'], order['message'])

{
  "success": true,
  "orderId": 45012,
  "status": "completed",
  "productId": 102,
  "quantity": 2,
  "totalPriceUsdt": 7,
  "createdAt": 1767225600000,
  "delivery": {
    "items": [
      "maria.lopez@example.com:Pass#8842",
      "juan.perez@example.com:Pass#1937"
    ]
  },
  "balanceAfterUsdt": 143.25,
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

{
  "success": true,
  "orderId": 45013,
  "status": "pending_delivery",
  "productId": 215,
  "quantity": 1,
  "totalPriceUsdt": 14.9,
  "createdAt": 1767225600000,
  "balanceAfterUsdt": 128.35,
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

{
  "success": true,
  "orderId": 45014,
  "status": "completed",
  "productId": 320,
  "quantity": 1,
  "totalPriceUsdt": 9,
  "createdAt": 1767225600000,
  "delivery": {
    "downloadUrl": "/api/v1/buyer/orders/45014/download"
  },
  "balanceAfterUsdt": 119.35,
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

{
  "success": false,
  "error": "PRICE_CHANGED",
  "message": "Price changed",
  "currentPriceUsdt": 7.2,
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

{
  "success": false,
  "error": "INSUFFICIENT_BALANCE",
  "message": "Insufficient wallet balance",
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

{
  "success": false,
  "error": "PROVIDER_TIMEOUT",
  "message": "The supplier did not answer in time. Your balance was not debited.",
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

curl https://api.hegodigitaldev.com/api/v1/buyer/orders/45012 \
  -H "X-API-Key: hg_live_TU_API_KEY"

const res = await fetch('https://api.hegodigitaldev.com/api/v1/buyer/orders/45012', {
  headers: { 'X-API-Key': process.env.HEGO_API_KEY },
});
const order = await res.json();
console.log(order.status, order.delivery);

import os, requests

res = requests.get(
    'https://api.hegodigitaldev.com/api/v1/buyer/orders/45012',
    headers={'X-API-Key': os.environ['HEGO_API_KEY']},
    timeout=15,
)
print(res.json()['status'])

{
  "success": true,
  "orderId": 45012,
  "status": "completed",
  "productId": 102,
  "quantity": 2,
  "totalPriceUsdt": 7,
  "createdAt": 1767225600000,
  "delivery": {
    "items": [
      "maria.lopez@example.com:Pass#8842",
      "juan.perez@example.com:Pass#1937"
    ]
  },
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Order not found",
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

curl -L https://api.hegodigitaldev.com/api/v1/buyer/orders/45014/download \
  -H "X-API-Key: hg_live_TU_API_KEY" \
  -o pedido-45014

import { writeFile } from 'node:fs/promises';

const res = await fetch('https://api.hegodigitaldev.com/api/v1/buyer/orders/45014/download', {
  headers: { 'X-API-Key': process.env.HEGO_API_KEY },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
await writeFile('pedido-45014', Buffer.from(await res.arrayBuffer()));
console.log(res.headers.get('content-type'));

import os, requests

res = requests.get(
    'https://api.hegodigitaldev.com/api/v1/buyer/orders/45014/download',
    headers={'X-API-Key': os.environ['HEGO_API_KEY']},
    timeout=60,
)
res.raise_for_status()
open('pedido-45014', 'wb').write(res.content)
print(res.headers['Content-Type'])

curl https://api.hegodigitaldev.com/api/v1/buyer/webhook \
  -H "X-API-Key: hg_live_TU_API_KEY"

{
  "success": true,
  "webhook": {
    "url": "https://tienda.example.com/hooks/hego",
    "events": [
      "order.completed",
      "order.failed",
      "stock.changed",
      "balance.low"
    ],
    "balanceThresholdUsdt": 20,
    "secretMasked": "***5f80"
  },
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

curl -X POST https://api.hegodigitaldev.com/api/v1/buyer/webhook \
  -H "X-API-Key: hg_live_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tienda.example.com/hooks/hego",
    "events": ["order.completed", "order.failed", "stock.changed", "balance.low"],
    "balanceThresholdUsdt": 20
  }'

const res = await fetch('https://api.hegodigitaldev.com/api/v1/buyer/webhook', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.HEGO_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://tienda.example.com/hooks/hego',
    events: ['order.completed', 'order.failed', 'stock.changed', 'balance.low'],
    balanceThresholdUsdt: 20,
  }),
});
const { webhook } = await res.json();
// El secret solo se muestra ahora: guárdalo en tu gestor de secretos
console.log(webhook.secret);

import os, requests

res = requests.post(
    'https://api.hegodigitaldev.com/api/v1/buyer/webhook',
    headers={'X-API-Key': os.environ['HEGO_API_KEY']},
    json={
        'url': 'https://tienda.example.com/hooks/hego',
        'events': ['order.completed', 'order.failed', 'stock.changed', 'balance.low'],
        'balanceThresholdUsdt': 20,
    },
    timeout=15,
)
# El secret solo se muestra ahora: guárdalo en tu gestor de secretos
print(res.json()['webhook']['secret'])

{
  "success": true,
  "webhook": {
    "url": "https://tienda.example.com/hooks/hego",
    "events": [
      "order.completed",
      "order.failed",
      "stock.changed",
      "balance.low"
    ],
    "balanceThresholdUsdt": 20,
    "secret": "whsec_live_5b1e0c7a94d3f28a6e1b0d47c93f5a82e6d1074b3c9a5f80"
  },
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

curl -X DELETE https://api.hegodigitaldev.com/api/v1/buyer/webhook \
  -H "X-API-Key: hg_live_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

{
  "success": true,
  "message": "Webhook deleted",
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

Webhooks#

En lugar de consultar la API continuamente, deja que Hego te avise: enviamos un POST con JSON a tu URL cuando ocurre un evento al que te suscribiste. Configúralo con POST /webhook.

Lo que recibe tu servidor

El cuerpo es un JSON con los datos del evento más eventId y type. Ambos van dentro de la firma, así que puedes confiar en ellos.

Responde con cualquier 2xx en menos de 10 segundos. Cualquier otro resultado (o un timeout) se considera fallido y se reintenta.

Eventos y payloads#

{
  "orderId": 45013,
  "eventId": "evt_9f2b7c1d4a6e08355b2c9d1e7f30a4b6",
  "type": "order.completed"
}

{
  "orderId": 45013,
  "eventId": "evt_9f2b7c1d4a6e08355b2c9d1e7f30a4b6",
  "type": "order.failed"
}

{
  "productId": 102,
  "productIds": [
    98,
    102
  ],
  "eventId": "evt_9f2b7c1d4a6e08355b2c9d1e7f30a4b6",
  "type": "catalog.updated"
}

{
  "productId": 102,
  "productIds": [
    98,
    102
  ],
  "eventId": "evt_9f2b7c1d4a6e08355b2c9d1e7f30a4b6",
  "type": "stock.changed"
}

{
  "balanceUsdt": 18.4,
  "thresholdUsdt": 20,
  "eventId": "evt_9f2b7c1d4a6e08355b2c9d1e7f30a4b6",
  "type": "balance.low"
}

Verificar la firma#

Cualquiera puede enviar un POST a tu URL. La firma demuestra que lo envió Hego y que nadie alteró el cuerpo. Verifícala siempre antes de actuar.

1. Lee t y v1 del header X-Hego-Signature.
2. Construye el texto firmado: t + . + X-Hego-Delivery + . + cuerpo crudo exacto.
3. Calcula HMAC-SHA256 con tu secret (whsec_live_…) y compáralo en hexadecimal con v1, en tiempo constante.
4. Rechaza si t (milisegundos) tiene más de 5 minutos de diferencia con tu reloj: evita reproducir envíos viejos.

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const TOLERANCE_MS = 5 * 60 * 1000;

// IMPORTANTE: usa el cuerpo CRUDO (Buffer), no el JSON ya parseado
app.post('/hooks/hego', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-Hego-Signature') || '';
  const eventId = req.get('X-Hego-Delivery') || '';
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));

  const fresh = Math.abs(Date.now() - Number(parts.t)) <= TOLERANCE_MS;
  const expected = crypto
    .createHmac('sha256', process.env.HEGO_WEBHOOK_SECRET)
    .update(`${parts.t}.${eventId}.${req.body.toString('utf8')}`)
    .digest('hex');
  const given = Buffer.from(parts.v1 || '');
  const valid = given.length === expected.length &&
    crypto.timingSafeEqual(given, Buffer.from(expected));

  if (!fresh || !valid) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(200); // responde rápido y procesa después
  queueForProcessing(event); // deduplica por event.eventId
});

import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)
TOLERANCE_S = 5 * 60

@app.post('/hooks/hego')
def hego_webhook():
    raw = request.get_data()  # cuerpo CRUDO, sin re-serializar
    parts = dict(p.split('=', 1) for p in request.headers.get('X-Hego-Signature', '').split(','))
    event_id = request.headers.get('X-Hego-Delivery', '')

    fresh = abs(time.time() * 1000 - int(parts.get('t', 0))) <= TOLERANCE_S * 1000
    expected = hmac.new(
        os.environ['HEGO_WEBHOOK_SECRET'].encode(),
        f"{parts.get('t')}.{event_id}.".encode() + raw,
        hashlib.sha256,
    ).hexdigest()

    if not fresh or not hmac.compare_digest(expected, parts.get('v1', '')):
        abort(401)

    event = request.get_json()
    enqueue(event)  # deduplica por event["eventId"]
    return '', 200

Prueba tu verificación

Con tu secret puedes firmar un envío de prueba y mandarlo a tu propio endpoint:

# Simula una entrega firmada contra tu endpoint (útil para probar tu verificación)
SECRET="whsec_live_..."
BODY='{"orderId":45013,"eventId":"evt_test_1","type":"order.completed"}'
TS=$(date +%s%3N)
SIG=$(printf '%s' "$TS.evt_test_1.$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

curl -X POST https://tienda.example.com/hooks/hego \
  -H "Content-Type: application/json" \
  -H "X-Hego-Event: order.completed" \
  -H "X-Hego-Delivery: evt_test_1" \
  -H "X-Hego-Signature: t=$TS,v1=$SIG" \
  -d "$BODY"

Reintentos y orden#

• Responde rápido (2xx) y procesa en segundo plano.
• No seguimos redirecciones: una respuesta 3xx cuenta como fallo. Registra la URL final.
• Antes de cada envío volvemos a comprobar que tu dominio resuelve a una IP pública.
• Si tu endpoint estuvo caído más de unas horas, reconcilia con GET /products y GET /orders/{id}.

Códigos de error#

Todos los errores comparten el mismo formato y un error estable sobre el que puedes programar.

{
  "success": false,
  "error": "INSUFFICIENT_BALANCE",
  "message": "Insufficient wallet balance",
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

{
  "success": false,
  "error": "OUT_OF_STOCK",
  "message": "Insufficient stock",
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

{
  "success": false,
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded",
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

{
  "success": false,
  "error": "BAD_REQUEST",
  "message": "Invalid order payload",
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

Flujo de compra robusto#

Un ejemplo completo en Node.js que combina lo esencial: una Idempotency-Key por compra, reintentos seguros con la misma key, manejo de 429 y 5xx, y espera de entregas asíncronas.

import { randomUUID } from 'node:crypto';

const BASE = 'https://api.hegodigitaldev.com/api/v1/buyer';
const headers = (extra = {}) => ({ 'X-API-Key': process.env.HEGO_API_KEY, ...extra });
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// 1) Compra con reintentos seguros: MISMA key mientras sea el mismo intento
async function buy({ productId, quantity, expectedPriceUsdt, recipient }) {
  const idempotencyKey = randomUUID(); // persístela en tu base de datos antes de llamar
  const body = JSON.stringify({ productId, quantity, expectedPriceUsdt, recipient });

  for (let attempt = 1; attempt <= 4; attempt++) {
    try {
      const res = await fetch(`${BASE}/orders`, {
        method: 'POST',
        headers: headers({ 'Idempotency-Key': idempotencyKey, 'Content-Type': 'application/json' }),
        body,
        signal: AbortSignal.timeout(30_000), // el servidor espera al proveedor hasta 15 s
      });
      const data = await res.json();

      if (res.status === 201) return data;
      if (res.status === 504) throw Object.assign(new Error(data.message), { code: data.error, data }); // proveedor lento: no se cobró; reintenta más tarde con una key NUEVA
      if (res.status === 429) { await sleep(Number(res.headers.get('retry-after') || 1) * 1000); continue; }
      if (res.status >= 500 || res.status === 409 && data.error === 'OUT_OF_STOCK') { await sleep(2 ** attempt * 500); continue; }
      throw Object.assign(new Error(data.message), { code: data.error, data }); // 402, 400, 404, 409 de precio: no se reintentan
    } catch (err) {
      if (err.code) throw err;              // error de negocio: sube al llamador
      await sleep(2 ** attempt * 500);       // timeout/red: reintenta con la MISMA key
    }
  }
  throw new Error('No se pudo confirmar la compra');
}

// 2) Si quedó pending_delivery, espera el webhook o consulta el pedido
async function waitForDelivery(orderId, { every = 5000, timeout = 600_000 } = {}) {
  const deadline = Date.now() + timeout;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/orders/${orderId}`, { headers: headers() });
    const order = await res.json();
    if (order.status === 'completed' || order.status === 'failed') return order;
    await sleep(every);
  }
  throw new Error('Entrega aún pendiente');
}

// 3) Uso
const order = await buy({ productId: 215, quantity: 1, expectedPriceUsdt: 14.9, recipient: { username: '@cliente_final' } });
const final = order.status === 'pending_delivery' ? await waitForDelivery(order.orderId) : order;
console.log(final.status, final.delivery);

Por qué así

• La key se crea una vez por compra y se reutiliza en los reintentos: si la respuesta se perdió, recibes la misma orden.
• Los errores de negocio (402, 400, 404, precio) no se reintentan: repetirlos no los arregla.
• Guarda el orderId y el resultado en tu base de datos dentro de la misma operación que entrega el producto a tu cliente.

Mantener tu catálogo sincronizado#

Los precios y el stock cambian todo el tiempo. El patrón recomendado:

1. Al arrancar, carga todo con GET /products y guárdalo.
2. Suscríbete a catalog.updated y stock.changed.
3. Al recibir un evento, vuelve a leer el catálogo (o solo los productIds indicados) y actualiza tu copia.
4. Como red de seguridad, refresca el catálogo completo cada 10–15 minutos.
5. Envía siempre expectedPriceUsdt: si tu copia quedó vieja, la API te protege con PRICE_CHANGED.

Productos con destinatario#

Los productos con requiresRecipient: true (por ejemplo Telegram Premium o Stars) se activan directamente en una cuenta de Telegram. Indica quién lo recibe en recipient.username:

curl -X POST https://api.hegodigitaldev.com/api/v1/buyer/orders \
  -H "X-API-Key: hg_live_TU_API_KEY" \
  -H "Idempotency-Key: 0c5d7a2e-93b1-4f68-8e0a-6d41b7c9e2f5" \
  -H "Content-Type: application/json" \
  -d '{"productId": 215, "quantity": 1, "expectedPriceUsdt": 14.9,
       "recipient": {"username": "@cliente_final"}}'

{
  "success": true,
  "orderId": 45013,
  "status": "pending_delivery",
  "productId": 215,
  "quantity": 1,
  "totalPriceUsdt": 14.9,
  "createdAt": 1767225600000,
  "balanceAfterUsdt": 128.35,
  "requestId": "3f0c6a52-8d1b-4a0e-9c47-2b5e7d9a1c30"
}

• El usuario debe empezar con @ y tener 5–32 caracteres (letras, números o _).
• Verifica el usuario antes de comprar: una activación en la cuenta equivocada no se puede deshacer.
• Si te olvidas del destinatario, recibes 400 BAD_REQUEST y no se cobra.

Productos tipo archivo#

Cuando el producto es un archivo, la compra devuelve delivery.downloadUrl (una ruta relativa). Descárgalo con tu API key:

curl -L https://api.hegodigitaldev.com/api/v1/buyer/orders/45014/download \
  -H "X-API-Key: hg_live_TU_API_KEY" \
  -o pedido-45014

import { writeFile } from 'node:fs/promises';

const res = await fetch('https://api.hegodigitaldev.com/api/v1/buyer/orders/45014/download', {
  headers: { 'X-API-Key': process.env.HEGO_API_KEY },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
await writeFile('pedido-45014', Buffer.from(await res.arrayBuffer()));
console.log(res.headers.get('content-type'));

import os, requests

res = requests.get(
    'https://api.hegodigitaldev.com/api/v1/buyer/orders/45014/download',
    headers={'X-API-Key': os.environ['HEGO_API_KEY']},
    timeout=60,
)
res.raise_for_status()
open('pedido-45014', 'wb').write(res.content)
print(res.headers['Content-Type'])

Puedes descargarlo de nuevo cuando quieras mientras la orden exista. Guarda el archivo en tu almacenamiento: tu cliente no debería usar tu API key para descargarlo.

Checklist de producción#

Preguntas frecuentes#

Cambios#

Los cambios compatibles (campos nuevos, eventos nuevos) se añaden dentro de /v1. Un cambio incompatible saldría como /v2 con aviso previo.