Inbound · Vos la llamás

REST API Reference

Tu POS llama a BipBip para aceptar, rechazar, avanzar el estado y consultar órdenes. Esta es la contraparte del Webhook Spec: una vez que BipBip te entrega una orden, usás esta API para gestionar su ciclo de vida.

Autenticación

Cada request debe incluir el header X-Bipbip-Api-Key con el valor entregado por el equipo BipBip durante el onboarding. No usamos Bearer tokens ni OAuth para esta API. Para obtener tus API Keys, contactá al equipo BipBip en [email protected].

# Cada llamada debe llevar este header
curl -H "X-Bipbip-Api-Key: <tu-api-key>" \
     https://api.bipbip.com/api/v1/Orders/<orderKey>

Idempotency-Key

Todas las mutaciones (/accept, /reject, /status) requieren el header Idempotency-Key. El valor debe ser un UUID v4 único por intento lógico.

• Misma key + mismo body dentro de las 24h → BipBip devuelve la respuesta en caché sin reejecutar.
• Misma key + body diferente → HTTP 409 Conflict.
• Key nueva → request procesado normalmente.
• Sin header en mutaciones → HTTP 422 Unprocessable Entity.

{
  "type": "https://errors.bipbip.com/idempotency-conflict",
  "title": "Idempotency conflict",
  "detail": "Idempotency-Key reused with a different request body.",
  "status": 409,
  "traceId": "00-abc...",
  "meta": null
}

Rate limits

Los límites se aplican por API Key y están activos en todos los endpoints. Si los superás recibís HTTP 429 — implementá exponential backoff con jitter en tu cliente.

Errores

La API sigue el formato RFC 7807 Problem Details. Todos los errores devuelven un body JSON con los campos type, title, detail, status, traceId y meta. Para errores de validación (422), meta incluye un mapa de campo → lista de mensajes.

Error genérico (401, 404, 409, 429)

{
  "type": "https://errors.bipbip.com/not-found",
  "title": "Order not found",
  "detail": "The order ord_xxx does not exist or does not belong to the authenticated client.",
  "status": 404,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "meta": null
}

Error de validación (422)

{
  "type": "https://errors.bipbip.com/validation",
  "title": "Validation failed",
  "detail": "One or more validation errors occurred.",
  "status": 422,
  "traceId": "00-abc...",
  "meta": {
    "errors": {
      "reasonCode": ["The ReasonCode field is required."]
    }
  }
}

Orders

Gestioná el ciclo de vida de las órdenes que BipBip te entregó por webhook. Los endpoints de mutación requieren X-Bipbip-Api-Key e Idempotency-Key.

{
  "message": "Order accepted",
  "data": {
    "orderKey": "ord_7h3nXpQa2KvLmN9F",
    "status": "accepted",
    "acceptedAt": "2026-04-11T15:44:12Z",
    "remoteOrderId": "POS-2026-04-11-00142"
  }
}

{
  "message": "Order rejected",
  "data": {
    "orderKey": "ord_7h3nXpQa2KvLmN9F",
    "status": "rejected",
    "rejectedAt": "2026-04-11T15:44:30Z",
    "reason": "Producto agotado"
  }
}

{
  "message": "Status updated",
  "data": {
    "orderKey": "ord_7h3nXpQa2KvLmN9F",
    "status": "preparing",
    "changedAt": "2026-04-11T15:47:00Z"
  }
}

{
  "message": "Ok",
  "data": {
    "orderKey": "ord_7h3nXpQa2KvLmN9F",
    "storeId": 42,
    "brandId": 7,
    "status": "preparing",
    "merchantStatusReason": null,
    "remoteOrderId": "POS-2026-04-11-00142",
    "receivedAt": "2026-04-11T15:42:00Z",
    "acceptedAt": "2026-04-11T15:44:12Z",
    "rejectedAt": null,
    "preparingAt": "2026-04-11T15:47:00Z",
    "readyAt": null,
    "driverAssignedAt": null,
    "handedOverAt": null,
    "cancelledAt": null,
    "history": [
      {
        "fromStatus": null,
        "toStatus": "pending",
        "changedAt": "2026-04-11T15:42:00Z",
        "actorType": "system",
        "actorId": null,
        "reason": null
      }
    ]
  }
}

{
  "message": "Ok",
  "data": {
    "items": [
      {
        "orderKey": "ord_7h3nXpQa2KvLmN9F",
        "storeId": 42,
        "status": "preparing",
        "receivedAt": "2026-04-11T15:42:00Z",
        "acceptedAt": "2026-04-11T15:44:12Z",
        "remoteOrderId": "POS-2026-04-11-00142"
      }
    ],
    "nextCursor": "eyJsYXN0SWQiOjE3fQ",
    "hasMore": true
  }
}