REST API Reference

Tu POS llama a BipBip. La API tiene dos superficies: Órdenes, para gestionar el ciclo de vida de lo que BipBip te entrega por webhook, y Menú, para mantener sincronizado tu catálogo — disponibilidad, precios y el menú completo de la marca. Es la contraparte delWebhook Spec.

Autenticación

Incluí el headerX-Bipbip-Api-Keyen cada request, con el valor que el equipo BipBip te entrega durante el onboarding. Cada comercio integrado recibe su propia API Key, que identifica al cliente y acota todo lo que la API te devuelve — órdenes, tiendas y marca. Las mutaciones (POST/PUT/PATCH) requieren ademásIdempotency-Key yX-Bipbip-Schema-Version(hoy 1.0). Para obtener tus API Keys, escribí al equipo BipBip a [email protected].

# Lectura — solo X-Bipbip-Api-Key
curl -H "X-Bipbip-Api-Key: <api-key>" \
     https://merchant-api.bipbip.hn/api/v1/Orders/<orderKey>

# Mutación — agregar Idempotency-Key y X-Bipbip-Schema-Version
curl -X POST \
     -H "X-Bipbip-Api-Key: <api-key>" \
     -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
     -H "X-Bipbip-Schema-Version: 1.0" \
     -H "Content-Type: application/json" \
     -d '{}' \
     https://merchant-api.bipbip.hn/api/v1/Orders/<orderKey>/accept

Idempotency-Key

Todas las mutaciones — las de Órdenes y las de Menú — requieren el headerIdempotency-Key(UUID v4, único por intento lógico) junto conX-Bipbip-Schema-Version: 1.0. Las respuestas se cachean en el servidor por 24 horas.

• Misma key + mismo body dentro de 24h → BipBip devuelve la respuesta original sin reejecutar.
• Misma key + body diferente → HTTP 422 con type terminado en /idempotency-conflict.
• Key nueva → request procesado normalmente.
• Sin Idempotency-Key → HTTP 422.
• Sin X-Bipbip-Schema-Version o valor no soportado → HTTP 400.

{
  "type": "https://bipbip.app/probs/idempotency-conflict",
  "title": "Idempotency conflict",
  "detail": "Idempotency-Key reutilizada con un body distinto.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

Rate limits

Los límites se aplican por API Key y están activos en todos los endpoints. Al superarlos, BipBip devuelve HTTP 429 con el headerRetry-After — la solución es exponential backoff con jitter en el cliente.

Errores

Toda respuesta de error sigue RFC 7807 Problem Details, con los campostype,title,detail,status,traceId ymeta. El contenido de meta depende del error: los 409 de transición traencurrentStatus y allowedTransitions[]; los 422 de validación traen errors, un mapa de ruta de campo a lista de reglas incumplidas.

Error genérico

{
  "type": "https://bipbip.app/probs/not-found",
  "title": "Order not found",
  "detail": "La orden ord_xxx no existe o no pertenece al cliente autenticado.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

Transición inválida (409)

{
  "type": "https://bipbip.app/probs/invalid-state-transition",
  "title": "Invalid state transition",
  "detail": "No se permite la transición de 'Preparing' a 'HandedOver'.",
  "status": 409,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "currentStatus": "Preparing",
    "allowedTransitions": [
      "Ready"
    ]
  }
}

Error de validación (422)

{
  "type": "https://bipbip.app/probs/validation",
  "title": "Validation failed",
  "detail": "Uno o más campos del request son inválidos.",
  "status": 422,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": {
    "errors": {
      "items[0].targetCode": [
        "El campo targetCode es obligatorio."
      ]
    }
  }
}