Ejemplos de código Descargar colección de Postman

Introducción Autenticación Saldo Informes Listar productos Pedido - Travel Crear pedido - VPN Estado del pedido Uso de datos Configuración VPN Códigos de error

Referencia de la API de socios

Todos los endpoints devuelven JSON. Nunca envías un precio - solo indicas qué quieres comprar, y el servidor siempre calcula el precio él mismo, para que no pueda falsificarse ni manipularse.

URL base:

Base URL

https://buyukesim.com/api/v1

Autenticación

Envía tu clave API como token Bearer en cada solicitud siguiente.

Nota: recargar saldo es una acción exclusiva del sitio web (con tu Magic Code del panel), no forma parte de esta API - tu clave API no puede crear ni financiar recargas.

Header

Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Cuenta

GET/api/v1/balance

Saldo de la cuenta

Lo que queda en tu cuenta de prepago. Cada pedido ya devuelve la misma cifra en su propio bloque balance, así que nunca necesitas llamar aquí solo para ver cuánto costó una compra. Este endpoint es para las comprobaciones ajenas a una compra: una alerta de recarga, una tarjeta del panel, un proceso por lotes que se niega a empezar lo que no puede pagar.

Request

curl "https://buyukesim.com/api/v1/balance" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "balance_usd": 477.5,
    "currency": "USD",
    "discount_pct": 10,
    "account": {
      "name": "Acme Telecom",
      "status": "active",
      "api_key_prefix": "buk_live_9f2a"
    }
  }
}

GET/api/v1/reports?from=2026-08-01&to=2026-08-31

Informe de ventas

Qué compraste en un rango de fechas y cuánto costó, desglosado por producto. Las fechas son días naturales UTC sobre la fecha del pedido e incluyen ambos extremos; si las omites se informan los últimos 30 días. Solo pedidos pagados: un pedido cuya entrega falla se cancela y se devuelve a tu saldo, así que nunca costó nada. El array orders está limitado a 100 filas por defecto (limit, máximo 500); para ver más, acota las fechas.

Request

curl "https://buyukesim.com/api/v1/reports?from=2026-08-01&to=2026-08-31" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "period": { "from": "2026-08-01", "to": "2026-08-31", "timezone": "UTC" },
    "totals": {
      "orders": 4,
      "units": 4,
      "spend_usd": 25.16,
      "currency": "USD"
    },
    "products": [
      { "type": "travel_data", "orders": 3, "units": 3, "spend_usd": 16.17 },
      { "type": "vpn",         "orders": 1, "units": 1, "spend_usd": 8.99 }
    ],
    "balance": { "remaining_usd": 477.5, "currency": "USD" },
    "orders": [
      {
        "order_id": 98423,
        "type": "vpn",
        "reference": "order-1236",
        "lookup_code": "K7M9-2XP4",
        "units": 1,
        "spend_usd": 8.99,
        "created_at": "2026-08-29 20:00:00",
        "plan": "30d"
      }
    ],
    "orders_truncated": false
  }
}

Productos

GET/api/v1/products

Listar productos

Obtén todos los paquetes activos de eSIM de viaje (con package_code y price_usd actuales) y los planes y servidores de acceso VPN, para saber siempre qué se puede comprar antes de llamar a Create Order. El array travel_data es todo el catálogo en vivo (unos 198 destinos: aquí se muestra una entrada); ?location_code=GB lo acota. Cada price_usd es TU precio: discount_pct es tu propia tasa, no una fija, y el ejemplo solo usa un 10%.

Request

curl "https://buyukesim.com/api/v1/products" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "discount_pct": 10,
    "travel_data": [
      {
        "package_code": "GB_1GB_7D",
        "name": "United Kingdom 1GB / 7 Days",
        "location_code": "GB",
        "retail_price_usd": 5.99,
        "price_usd": 5.39,
        "volume_label": "1 GB",
        "duration": 7,
        "duration_unit": "DAY"
      }
    ],
    "vpn": {
      "type": "vpn",
      "available": true,
      "currency": "USD",
      "plans": [
        { "plan": "30d", "days": 30, "label": "30 days", "retail_price_usd": 9.99, "price_usd": 8.99, "currency": "USD" }
      ],
      "protocols": ["wireguard", "openvpn", "vless"],
      "servers": [
        { "id": 42, "country_code": "NL", "city": "Amsterdam", "protocol": "wireguard" }
      ]
    }
  }
}

Pedidos

POST/api/v1/orders

Crear pedido - eSIM de viaje

Crea y entrega instantáneamente un pedido de eSIM de viaje para el package_code indicado.

Request

curl -X POST "https://buyukesim.com/api/v1/orders" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "travel_data",
  "package_code": "GB_1GB_7D",
  "reference": "order-1235"
}'

Response

{
  "success": true,
  "data": {
    "order_id": 98422,
    "reference": "order-1235",
    "status": "paid",
    "product": {
      "type": "travel_data",
      "package_code": "GB_1GB_7D",
      "package_name": "United Kingdom 1GB / 7 Days",
      "location_code": "GB",
      "retail_price_usd": 5.99,
      "discount_pct": 10,
      "price_usd": 5.39
    },
    "lookup_code": null,
    "created_at": "2026-07-06T20:00:00+00:00",
    "balance": { "charged_usd": 5.39, "remaining_usd": 472.11, "currency": "USD" }
  }
}

POST/api/v1/orders

Crear pedido - Acceso VPN

Crea y aprovisiona al instante un pedido de acceso VPN para el vpn_plan indicado, descontado de tu saldo prepago. La respuesta incluye el usuario, la contraseña y la fecha de caducidad. Si el proveedor de VPN no responde, el pedido sigue pagado y se conserva: recibes HTTP 202 con el estado "provisioning_pending" y el id del pedido, se avisa a nuestro equipo, y las credenciales aparecen en GET /v1/orders/{id} cuando la cuenta esté creada.

Request

curl -X POST "https://buyukesim.com/api/v1/orders" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "vpn",
  "vpn_plan": "30d",
  "reference": "order-1236"
}'

Response

{
  "success": true,
  "data": {
    "order_id": 98423,
    "reference": "order-1236",
    "status": "paid",
    "product": {
      "type": "vpn",
      "plan": { "key": "30d", "days": 30, "label": "30 days" },
      "retail_price_usd": 9.99,
      "discount_pct": 10,
      "price_usd": 8.99
    },
    "lookup_code": "K7M9-2XP4",
    "created_at": "2026-08-29T20:00:00+00:00",
    "vpn": {
      "provisioned": true,
      "expires_at": "2026-09-28 00:00:00",
      "username": "bk98423a1c3e",
      "password": "s7Kq2vXpLm4A",
      "protocols": ["wireguard", "openvpn", "vless"],
      "config_endpoint": "https://buyukesim.com/api/v1/orders/98423/vpn-config"
    },
    "success_url": "https://buyukesim.com/en/success?order_id=98423&access_token=...",
    "balance": { "charged_usd": 8.99, "remaining_usd": 463.12, "currency": "USD" }
  }
}

GET/api/v1/orders/98422

Estado del pedido y entrega

La llamada de entrega: consúltala hasta que data.esim.ready sea true y toma el perfil de data.esim.items. Cada elemento trae las dos formas de llegar a un teléfono: qr_code, y manual_install con la dirección SM-DP+ y el código de activación para escribir a mano, para el caso muy habitual de que tu cliente esté leyendo tu app en el mismo teléfono donde debe instalarse el perfil y no tenga una segunda pantalla que escanear. En las eSIM de viaje puk_code es null. No consultes status: marca "paid" en cuanto se descuenta tu saldo, que es un estado de pago, no de entrega.

Request

curl "https://buyukesim.com/api/v1/orders/98422" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "order_id": 98422,
    "reference": "order-1235",
    "status": "paid",
    "product": { "type": "travel_data", "package_code": "GB_1GB_7D", "retail_price_usd": 5.99, "price_usd": 5.39 },
    "lookup_code": "K7M9-2XP4",
    "esim": {
      "ready": true,
      "items": [
        {
          "_comment": "hosts below are placeholders - the real ones differ per profile",
          "qr_code": "https://qr.example-provider.net/8e2bba37e8b94ca49bf23be334a0a57f.png",
          "iccid": "8944...",
          "puk_code": null,
          "manual_install": {
            "activation_string": "LPA:1$rsp.example-provider.com$1173094A3D3A473D84695E0D6C404B34",
            "smdp_address": "rsp.example-provider.com",
            "activation_code": "1173094A3D3A473D84695E0D6C404B34",
            "confirmation_code_required": false
          }
        }
      ]
    }
  }
}

GET/api/v1/orders/98422/usage

Uso de datos del eSIM de viaje

Datos restantes/usados en vivo, estado de activación y caducidad de un pedido de eSIM de viaje, obtenidos directamente del proveedor en cada llamada.

Request

curl "https://buyukesim.com/api/v1/orders/98422/usage" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "order_id": 98422,
    "status": "paid",
    "package": {
      "package_code": "GB_1GB_7D",
      "name": "United Kingdom 1GB / 7 Days",
      "location_code": "GB",
      "volume_label": "1 GB",
      "duration": 7,
      "duration_unit": "DAY"
    },
    "usage": {
      "iccid": "8944...",
      "apn": "cmlink",
      "esim_status": "IN_USE",
      "smdp_status": "ENABLED",
      "total_volume_bytes": 1073741824,
      "used_volume_bytes": 214748364,
      "remaining_volume_bytes": 858993459,
      "usage_percent": 20.0,
      "total_duration": 7,
      "duration_unit": "DAY",
      "expired_time": "2026-07-13T20:00:00+00:00"
    }
  }
}

GET/api/v1/orders/98423/vpn-config?protocol=wireguard&server_id=42

Configuración VPN

Obtiene una configuración WireGuard, OpenVPN o VLESS para un servidor de un pedido VPN que hayas creado. Toma server_id de la lista de servidores de Listar productos. Los servidores WireGuard también sirven OpenVPN; los servidores VLESS solo sirven VLESS. Llámalo tantas veces como necesites, hasta 20 por minuto.

Request

curl "https://buyukesim.com/api/v1/orders/98423/vpn-config?protocol=wireguard&server_id=42" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "order_id": 98423,
    "protocol": "wireguard",
    "server": { "id": 42, "country_code": "NL", "city": "Amsterdam" },
    "name": "buyukesim-nl-amsterdam.conf",
    "content": "[Interface]\nPrivateKey = ...\nAddress = ...",
    "qr_payload": "[Interface]\nPrivateKey = ...\nAddress = ..."
  }
}

Códigos de error

Toda respuesta de error tiene la misma forma: un success: false de nivel superior, más un objeto error con un campo code estable que tu código puede comprobar para saber exactamente qué ha pasado.

Error shape

{
  "success": false,
  "error": { "code": "insufficient_balance", "message": "..." }
}

HTTP	code	Significado
401	unauthorized	Clave API faltante o inválida.
402	insufficient_balance	Saldo prepago insuficiente para el precio de este pedido.
404	package_not_found	package_code de viaje no encontrado o ya no está activo.
409	provisioning_pending	La cuenta VPN de este pedido aún no está creada, o el plan ha caducado.
429	rate_limit	Límite de solicitudes excedido - reduce la frecuencia de solicitudes.