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: claves, enlaces de Steam Gift, credenciales de cuenta o enlaces de activación, por API o webhook.
• Reembolsos: las unidades que no se pudieron entregar se abonan automáticamente. Las claves, Steam Gifts, cuentas y enlaces entregados son definitivos: no se pueden devolver ni reembolsar.

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 con ?wait=20 para recibirlo ya completado. 4) Descarga las claves.

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.

• 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.
• ?wait=N (0–25 s) espera a que termine antes de responder. Sin él, el pedido vuelve en processing y te avisamos por webhook o consultando GET /orders/{id}.
• El total se descuenta al aceptar el pedido. Las unidades que no se puedan entregar se abonan automáticamente (refunded).

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 unidad entregada (clave, enlace de Steam Gift, cuenta o enlace de activación) es definitiva: se compra al proveedor para ti en el momento de la entrega y no se puede devolver ni reembolsar, aunque no se haya canjeado. Solo se reembolsan, automáticamente, las unidades que no se pudieron entregar. Revisa la región, activation.excludedCountries y deliveryType antes de vender y muéstraselos a tu cliente.

Si una clave entregada no funciona, escribe a [email protected] en los 7 días siguientes con el id del pedido y una captura del error de activación. La reclamación se traslada al proveedor; solo habrá sustitución o abono si el proveedor sustituye o reembolsa esa clave.

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 — un pedido en processing ya está pagado: espera al webhook o consulta GET /orders/{id}; nunca lo repitas.
• 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.