Idempotencia

El campo reference

B4bit Pay no expone una cabecera Idempotency-Key estándar, pero ofrece un equivalente funcional: el campo reference del POST /orders/.

• Tipo: string.
• Longitud: 1-256 caracteres.
• Alcance: usted decide el formato y la unicidad.

Recomendaciones

1. Use el ID interno de su pedido como reference. Por ejemplo, si su e-commerce genera pedidos ORD-2026-04-17-000123, páselo tal cual.
2. Garantice unicidad: si reintenta el POST /orders/ tras un timeout, no debería crear una orden duplicada en su sistema. Controle el reintento con una tabla local y un único reference por intento.
3. Persista el identifier devuelto por B4bit Pay junto a su reference para hacer lookups bidireccionales.
4. Formato recomendado: UUID v4 o {tipo}-{fecha}-{id}-{random} (por ejemplo ORD-20260417-000123-ab34).

Precaución

Si crea dos órdenes con el mismo reference, ambas se procesarán (B4bit Pay no deduplica automáticamente). La idempotencia es responsabilidad del merchant.

Reconciliación

Cuando reciba un webhook, úselo para localizar su pedido interno por reference:

// pseudocódigo
async function handleWebhook(body) {
  const order = await db.orders.findOne({ b4bit_identifier: body.identifier });
  if (!order) {
    // no debería pasar si persistió `reference` + `identifier` al crear.
    logger.warn('Webhook de orden desconocida', { identifier: body.identifier });
    return;
  }
  await db.orders.updateStatus(order.id, body.status, body);
}

Qué NO usar como reference

• ❌ El email del cliente (no único por pedido).
• ❌ El importe (no único por pedido).
• ❌ Un timestamp en segundos sin otro factor (colisiones fáciles bajo carga).