Referencia de Commerce API

LauncherForge Commerce API permite que una integración de tienda ejecutada en el servidor genere una key después de que la tienda confirme una compra.

LauncherForge no cobra al comprador. WooCommerce, PrestaShop, tu página personalizada o el proveedor de pagos procesa el cobro. LauncherForge solamente genera y devuelve la key del juego.

Página de Commerce API key de LauncherForge

Cómo funciona

El comprador completa el pago
        ↓
La tienda confirma la orden
        ↓
El servidor de la tienda llama a LauncherForge
        ↓
LauncherForge genera una key
        ↓
La tienda guarda la key en la orden
        ↓
WooCommerce o la tienda envía la key al comprador

Antes de comenzar

Necesitas:

Un plan pagado de LauncherForge con el add-on Commerce API activo.
Una Commerce API key completa.
Un juego perteneciente al mismo workspace.
Protección mediante CD-Key habilitada para ese juego.
El App ID numérico de LauncherForge.
Una integración ejecutada en el servidor. Nunca llames Commerce API desde JavaScript público del navegador.

Un valor como lf_commerce_live_d122d2cc091f es solamente el prefijo visible. No sirve para autenticar solicitudes. La key completa se muestra una sola vez al crearla o regenerarla.

URL base

https://backend.launcherforge.io/api/v1

El endpoint estable actual es:

POST /external/commerce/deliveries

URL completa:

https://backend.launcherforge.io/api/v1/external/commerce/deliveries

Autenticación

Envía la Commerce API key completa como Bearer token:

Authorization: Bearer TU_COMMERCE_API_KEY_COMPLETA

Nunca pongas la key en:

JavaScript del navegador.
HTML.
Aplicaciones móviles.
Repositorios públicos.
Capturas de pantalla.
Logs visibles para el cliente.

Idempotencia

Toda entrega debe incluir:

Idempotency-Key: <identificador-estable-y-unico>

El valor debe identificar una unidad comprada específica. Si la tienda reintenta la misma operación con el mismo valor, LauncherForge devuelve la entrega anterior en vez de generar otra key. Formato recomendado:

<proveedor>:<id-tienda>:<id-orden>:<id-item>:<unidad>

Ejemplo para WooCommerce:

wc:40c19d4c0ed64ca1:1001:72:1

Si el comprador adquiere tres unidades:

wc:40c19d4c0ed64ca1:1001:72:1
wc:40c19d4c0ed64ca1:1001:72:2
wc:40c19d4c0ed64ca1:1001:72:3

Repetir el mismo Idempotency-Key devuelve la misma entrega y la misma key con alreadyProcessed: true.

Crear una entrega

POST /external/commerce/deliveries

Headers

Header	Obligatorio	Valor
`Authorization`	Sí	`Bearer <commerce-api-key-completa>`
`Idempotency-Key`	Sí	ID estable para esta unidad comprada
`Content-Type`	Sí	`application/json`
`Accept`	Recomendado	`application/json`

Body

Campo	Tipo	Obligatorio	Descripción
`appId`	integer	Sí	App ID numérico de LauncherForge.
`externalOrderId`	string	Sí	ID de la orden en la tienda.
`externalOrderItemId`	string	No	ID de la línea o unidad comprada.
`customerEmail`	string	No	Correo del comprador.
`customerName`	string	No	Nombre del comprador.
`provider`	string	No	`CUSTOM`, `WOOCOMMERCE` o `NATIVE_APP`.
`expiresAt`	string ISO 8601	No	Expiración futura opcional.
`note`	string	No	Referencia interna para la key.

Solicitud recomendada

{
  "appId": 1,
  "externalOrderId": "1001",
  "externalOrderItemId": "72:1",
  "customerEmail": "comprador@example.com",
  "customerName": "Comprador de ejemplo",
  "provider": "WOOCOMMERCE",
  "note": "WooCommerce order 1001, item 72, unit 1"
}

Ejemplo cURL

curl --request POST \
  --url "https://backend.launcherforge.io/api/v1/external/commerce/deliveries" \
  --header "Authorization: Bearer TU_COMMERCE_API_KEY_COMPLETA" \
  --header "Idempotency-Key: tienda-personalizada:1001:1:1" \
  --header "Content-Type: application/json" \
  --data '{
    "appId": 1,
    "externalOrderId": "1001",
    "externalOrderItemId": "1",
    "customerEmail": "comprador@example.com",
    "customerName": "Comprador de ejemplo",
    "provider": "CUSTOM"
  }'

Ejemplo PowerShell

$commerceKey = "TU_COMMERCE_API_KEY_COMPLETA"

$headers = @{
    Authorization     = "Bearer $commerceKey"
    "Idempotency-Key" = "tienda-personalizada:1001:1:1"
}

$body = @{
    appId                = 1
    externalOrderId      = "1001"
    externalOrderItemId  = "1"
    customerEmail        = "comprador@example.com"
    customerName         = "Comprador de ejemplo"
    provider             = "CUSTOM"
} | ConvertTo-Json

$response = Invoke-RestMethod `
    -Method Post `
    -Uri "https://backend.launcherforge.io/api/v1/external/commerce/deliveries" `
    -Headers $headers `
    -ContentType "application/json" `
    -Body $body

$response | ConvertTo-Json -Depth 10

Respuesta exitosa

{
  "success": true,
  "data": {
    "deliveryId": "dlv_98c0b1c0dae6ec7376597758",
    "alreadyProcessed": false,
    "provider": "CUSTOM",
    "externalOrderId": "1001",
    "externalOrderItemId": "1",
    "customerEmail": "comprador@example.com",
    "status": "GENERATED",
    "game": {
      "id": 1,
      "slug": "cs-1-6",
      "name": "CS 1.6"
    },
    "gameKey": {
      "key": "A0622-F4BF7-00204",
      "status": "ACTIVE",
      "expiresAt": null,
      "generatedAt": "2026-08-01T03:29:50.422Z"
    },
    "createdAt": "2026-08-01T03:29:50.431Z"
  }
}

Campos de respuesta

Campo	Significado
`deliveryId`	Identificador estable de la entrega.
`alreadyProcessed`	`true` cuando la operación idempotente ya existía.
`status`	Estado actual de la entrega.
`gameKey.key`	Key que debe recibir el comprador.
`gameKey.status`	Estado actual de la key.
`gameKey.expiresAt`	Expiración o `null`.

Errores comunes

`INVALID_COMMERCE_API_KEY`

La credencial es inválida, fue revocada, está incompleta o solamente contiene el prefijo visible.

`COMMERCE_API_NOT_ENABLED`

El add-on Commerce API no está activo para el workspace.

`EXTERNAL_GAME_NOT_AVAILABLE`

Falló alguna de estas condiciones:

El App ID no existe.
El juego pertenece a otro workspace.
El juego no está vinculado correctamente.
La protección mediante CD-Key está deshabilitada.

`IDEMPOTENCY_KEY_REQUIRED`

Falta el header Idempotency-Key.

Error de validación

El body contiene un campo, tipo o valor inválido.

¿Quién envía el correo?

El backend de LauncherForge devuelve la key a la integración autenticada. No envía el correo al comprador en las entregas externas de Commerce API. La tienda externa realiza la entrega:

El plugin de WooCommerce agrega la key a los correos del pedido enviados al cliente.
También muestra la key en Mi cuenta → Pedidos.
Una tienda personalizada debe enviar o mostrar la key mediante su propio sistema de correo y órdenes.

Seguridad

Guarda la key completa solamente en el servidor.
Usa HTTPS.
Regenera la key si se expone.
Nunca registres Bearer tokens.
Nunca expongas la key en frontend.
Usa una idempotency key determinística por unidad.
Confirma el pago antes de solicitar la key.
No cambies la idempotency key solamente porque una solicitud agotó el tiempo de espera.

​Referencia de Commerce API

​Cómo funciona

​Antes de comenzar

​URL base

​Autenticación

​Idempotencia

​Crear una entrega

​Headers

​Body

​Solicitud recomendada

​Ejemplo cURL

​Ejemplo PowerShell

​Respuesta exitosa

​Campos de respuesta

​Errores comunes

​INVALID_COMMERCE_API_KEY

​COMMERCE_API_NOT_ENABLED

​EXTERNAL_GAME_NOT_AVAILABLE

​IDEMPOTENCY_KEY_REQUIRED

​Error de validación

​¿Quién envía el correo?

​Seguridad

Referencia de Commerce API

Cómo funciona

Antes de comenzar

URL base

Autenticación

Idempotencia

Crear una entrega

Headers

Body

Solicitud recomendada

Ejemplo cURL

Ejemplo PowerShell

Respuesta exitosa

Campos de respuesta

Errores comunes

`INVALID_COMMERCE_API_KEY`

`COMMERCE_API_NOT_ENABLED`

`EXTERNAL_GAME_NOT_AVAILABLE`

`IDEMPOTENCY_KEY_REQUIRED`

Error de validación

¿Quién envía el correo?

Seguridad