API de partners de BuyCheapKeys

URL base: https://buycheapkeys.com/partner-api/v1. Peticiones y respuestas en JSON (UTF-8). Los precios están en EUR con dos decimales y no incluyen IVA. Las fechas son ISO 8601 en UTC.

• Catálogo: lista y sincroniza de forma incremental todos los productos que puedes vender, con tu precio de partner.
• Pedidos: hasta 10 líneas × 9 unidades por petición; el total se descuenta de tu saldo al momento.
• Entrega: las claves vienen en la respuesta del pedido y se pueden volver a leer con GET /orders/{id}/keys.
• Reclamaciones: una clave defectuosa se puede reclamar durante 14 días desde tu panel de partner, con mensajes y capturas. Una clave de sustitución llega sola a tu pedido y un reembolso vuelve a tu saldo.

Crea las claves en Panel → Partner → Claves API. Cada clave se muestra una sola vez; solo guardamos su hash. Envíala en la cabecera Authorization (también se acepta X-Api-Key).

Lista blanca de IPs opcional (IPv4/IPv6, CIDR) por cuenta. Las claves no caducan salvo que las revoques; para rotarlas crea una nueva y revoca la antigua.

1) Crea una clave bck_test_. 2) Lista productos. 3) Haz un pedido: vuelve completado y con las claves. 4) Vuelve a leer las claves cuando quieras con GET /orders/{id}/keys. Las cuentas de partner que aún se están aprobando pueden usar claves sandbox.

GET /products devuelve hasta 100 productos ordenados por updatedAt (y luego id). updatedAt solo cambia cuando cambia algo relevante (precio, stock, nombre, región, textos, imágenes). Sincroniza con el cursor: cada respuesta trae nextCursor y hasMore; pasa nextCursor como ?cursor= hasta que hasMore sea false y guárdalo para la siguiente ejecución. Nunca salta ni repite productos, aunque muchos compartan marca de tiempo. page y updatedSince siguen disponibles para navegar. Filtros: inStock, platform, region, productType, deliveryType, search, ids (separados por comas, máx. 100).

Recomendado: una sincronización completa (sin cursor) y después cada 5–15 minutos desde el nextCursor guardado, siempre con includeRemoved=true. Un producto con removed: true o inStock: false no debe venderse.

POST /orders con externalId (tu referencia única) e items (productId, qty 1–9, maxUnitPrice). En cada línea comprobamos el precio en vivo: si supera maxUnitPrice se rechaza todo el pedido con PRICE_CHANGED y no se cobra nada. Si es menor, pagas el precio menor. Código promocional: añade couponCode: MICROSOFT20 al cuerpo del pedido para pagar un 20 % menos en los productos Microsoft mientras la promoción esté activa (maxUnitPrice se compara con el precio ya rebajado; un código desconocido o una promoción terminada devuelve INVALID_COUPON y no se cobra nada).

• Envía la cabecera Idempotency-Key (8–100 caracteres) y repítela al reintentar: recibes la respuesta original y nunca se cobra dos veces. externalId también es único por cuenta.
• El pedido se completa en la misma petición: la respuesta trae estado completed y un array keys. Una petición repetida (misma Idempotency-Key) devuelve el pedido sin las claves y con keysOmitted: true: léelas con GET /orders/{id}/keys.
• Si no hay stock o tu saldo no alcanza no se cobra nada ni se usa ninguna clave (OUT_OF_STOCK, INSUFFICIENT_BALANCE). maxUnitPrice es un tope para cada clave; una línea puede dividirse en varios items si hacen falta vendedores con precios distintos.
• Si una petición agota el tiempo, envíala otra vez con el mismo externalId: recibes DUPLICATE_EXTERNAL_ID con el id del pedido y puedes leer sus claves.

GET /orders/{id}/keys devuelve cada unidad entregada: value contiene el código, la URL del Steam Gift, las credenciales de la cuenta o el enlace de activación según deliveryType. contentType es text/plain o un tipo de imagen (entonces value va en base64).

Guarda las claves cifradas y muéstralas solo al comprador. La primera descarga de cada pedido queda registrada en nuestro lado como prueba de entrega.

Cada clave viene de un vendedor al que se paga tras un periodo de retención, así que una clave defectuosa se puede reclamar durante 14 días. Abre el pedido en Panel → Pedidos (API), elige la clave, escribe al vendedor y adjunta capturas del error de activación. El vendedor puede enviar una clave de sustitución (aparece en tu pedido y recibes el webhook key.replaced) o reembolsar la clave (el precio vuelve a tu saldo de la API una sola vez y recibes order.refunded). Si no estás de acuerdo, escala y decide BuyCheapKeys.

Revisa la región, excludedCountries y el tipo de licencia antes de vender y muéstraselos a tu cliente. Un reembolso a tu saldo no reembolsa a tu propio cliente: eso lo decides tú.

Compra nuestras propias tarjetas regalo para revenderlas: códigos BCK-XXXX-XXXX-XXXX-XXXX que suman su valor a la Wallet de BuyCheapKeys de quien los canjea en buycheapkeys.com/wallet. GET /gift-cards devuelve los importes a la venta, los descuentos por volumen, los máximos por pedido y el saldo de tu Wallet. POST /gift-cards/orders compra N tarjetas de un mismo importe y devuelve los códigos al momento; GET /gift-cards/orders/{id} los vuelve a mostrar con el estado de cada código.

• Se paga solo con la Wallet de BuyCheapKeys de tu cuenta de la tienda (recárgala en buycheapkeys.com/wallet), no con el saldo de la API. Precio = valor facial menos el descuento por volumen de esa cantidad.
• Los importes, descuentos y máximos pueden cambiar: envía maxTotal para rechazar un total mayor (PRICE_CHANGED, sin cobro). Idempotency-Key y el externalId único funcionan igual que en los pedidos.
• Venta en pausa: PRODUCT_UNAVAILABLE (409). Importe que no se vende o cantidad fuera de rango: VALIDATION_ERROR. Pedido demasiado grande: ORDER_LIMIT_EXCEEDED. Saldo insuficiente en la Wallet: INSUFFICIENT_BALANCE (402).
• Las claves de sandbox devuelven códigos falsos BCK-TEST-… que no se pueden canjear y no cobran nada.
• Los códigos vendidos son definitivos. Cada código caduca (expiresAt) y tiene límites de canje por cuenta. Un código que bloqueemos por fraude deja de mostrarse (code: null, estado blocked). Guarda los códigos cifrados.

Configura una URL https en Panel → Webhooks y recibirás un secreto de firma (whsec_…). Cada evento es un POST con las cabeceras X-BCK-Event, X-BCK-Delivery (id único: úsalo para descartar duplicados) y X-BCK-Signature: t=<unix>,v1=<hex> donde v1 = HMAC-SHA256(secreto, t + "." + cuerpo).

• Responde 2xx en menos de 8 s y procesa en segundo plano. No se siguen redirecciones.
• Los envíos fallidos se reintentan tras 10 s, 30 s, 1 min, 5 min, 15 min, 30 min, 1 h, 2 h, 4 h, 6 h y 12 h (~26 h).
• Los eventos pueden llegar desordenados o repetidos: ante la duda vuelve a leer GET /orders/{id}.

Los errores usan códigos HTTP y un code estable. Indica el requestId al contactar con soporte.

GET /balance devuelve el saldo del modo de la clave. Recarga desde Panel → Saldo: recibes una referencia única para indicar en la transferencia; el importe se abona al recibirlo (e-mail + webhook balance.credited). Todos los movimientos aparecen en el extracto.

Documentación legible por máquinas: https://buycheapkeys.com/developers.es.md (esta página en Markdown), https://buycheapkeys.com/developers.md (inglés), la especificación OpenAPI 3.1 https://buycheapkeys.com/partner-api/v1/openapi.json y https://buycheapkeys.com/llms.txt. Pásale estas URLs a tu asistente de IA junto con el prompt de abajo.

Integración de referencia completa (Node.js 18+, sin dependencias): https://buycheapkeys.com/developers/bck-partner-client.mjs — sincronización del catálogo con cursor, pedidos seguros con reintentos e idempotencia, descarga de claves y un receptor de webhooks con verificación de firma.

• Regla 1 — vende solo productos con inStock=true y removed=false; resincroniza cada 5–15 min desde el nextCursor guardado.
• Regla 2 — un pedido de cliente = un externalId = una Idempotency-Key; reutiliza ambos en cada reintento.
• Regla 3 — envía siempre maxUnitPrice; los errores 4xx de negocio son definitivos y no se ha cobrado nada.
• Regla 4 — reintenta solo errores de red, 429, 5xx e IDEMPOTENCY_IN_PROGRESS, con espera exponencial.
• Regla 5 — nunca repitas un pedido tras un timeout: repite el mismo externalId y lee las claves del pedido existente.
• Regla 6 — guarda la clave API en el servidor; verifica la firma de los webhooks; muestra al cliente el deliveryType y la región de activación.

• Guarda las claves API solo en tu servidor (nunca en navegadores ni apps), en variables de entorno o un gestor de secretos.
• Usa claves distintas por sistema y con los permisos mínimos; activa la lista blanca de IPs.
• Envía siempre maxUnitPrice y una Idempotency-Key.
• Verifica la firma y la marca de tiempo de cada webhook antes de fiarte de él.
• Si sospechas una filtración, crea claves nuevas, rota el secreto del webhook y revoca las antiguas.