Operaciones de agencias y partners

Miguel Gómez Pérez · Equipo Bukyapp· 3 min de lectura·Actualizado 17 sept 2026

Consulta, crea, edita y borra agencias y partners con comisión por API v1 o MCP.

Una agencia (o partner) en Buky es un colaborador externo —agencia de viajes, OTA, turoperador— que reserva en nombre de sus clientes y cobra o paga una comisión por ello. Buky calcula esa comisión automáticamente, lleva la trazabilidad de qué reservas vienen de cada agencia y genera la factura correspondiente. Consulta Configurar una agencia (OTA, turoperador) para verlo desde el panel.

Las bases comunes (autenticación, GET frente a POST, prueba en seco, errores HTTP, límites) están en API v1 — Introducción y primeros pasos. En las seis operaciones, customer_id es opcional: se toma de tu token salvo que uses uno multicuenta.

list-partners: enumera las agencias del centro

Devuelve la lista de agencias colaboradoras del centro, sin tener que saber sus nombres de antemano. Es una operación de solo lectura: vale con cualquier token.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/list-partners" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «¿Qué agencias tengo dadas de alta?» o «Enséñame las agencias desactivadas».

Parámetros

Qué devuelve

Ejemplo real, con la única agencia dada de alta en la cuenta demo:

{
  "success": true,
  "operation": "list-partners",
  "detail": "compact",
  "count": 1,
  "total": 1,
  "items": [
    { "_id": "6979efe8cecd6cb2336188a5", "name": "GetYourGuide · auto", "commission": 25, "channel": "getyourguide", "is_disabled": false }
  ],
  "warnings": []
}

Consejos

• No hace falta forzar un error de get-partner con un nombre inventado solo para ver qué agencias existen: para eso está list-partners.
• Con detail: "descriptive" ves de un vistazo el modo de cobro y de facturación de cada agencia, sin consultarlas una a una con get-partner.

get-partner: consulta el doc completo de una agencia

Devuelve el documento fresco de una agencia, resuelta por nombre o identificador. Es una operación de solo lectura: vale con cualquier token.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/get-partner?partner=GetYourGuide" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «¿Qué comisión tiene la agencia GetYourGuide?» o, para forzarla, «Ejecuta get-partner para GetYourGuide».

Parámetros

Qué devuelve

Ejemplo real, para la agencia que la cuenta demo tiene dada de alta desde un canal externo:

{
  "success": true,
  "operation": "get-partner",
  "_id": "6979efe8cecd6cb2336188a5",
  "resolved": {
    "id": "6979efe8cecd6cb2336188a5",
    "reason": "match por nombre 'GetYourGuide · auto'"
  },
  "item": {
    "_id": "6979efe8cecd6cb2336188a5",
    "name": "GetYourGuide · auto",
    "payment_mode": "full_to_agent",
    "invoice_mode": "supplier",
    "commission": 25,
    "recalculate_commission": true,
    "noTax": false,
    "isDisabled": false,
    "channel": "getyourguide",
    "affiliate_link_active": false,
    "commissionByProduct": [],
    "hidePriceDetails": true
  },
  "warnings": []
}

Errores propios

Consejos

• Guarda el _id que te devuelve para usarlo directamente en update-partner o delete-partner, sin repetir la búsqueda por nombre.
• Es la forma de comprobar cómo quedó una agencia después de crearla o editarla. Para enumerar todas de golpe, usa list-partners.

create-partner: da de alta una agencia colaboradora

Crea una agencia nueva con su comisión, su modo de cobro y de facturación. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/create-partner \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Agencia Marea Azul", "commission": 15, "payment_mode": "full_to_agent"}'

Por MCP: «Crea la agencia Agencia Marea Azul con una comisión del 15 %, cobrando ella al cliente.»

Parámetros

Qué devuelve

Prueba en seco con el ejemplo mínimo:

{
  "success": true,
  "operation": "create-partner",
  "applied_defaults": { "commission": 15, "hidePriceDetails": true },
  "resolved_payment_mode": { "mode": "full_to_agent", "reason": "match exacto 'full_to_agent'" },
  "resolved_invoice_mode": { "mode": "supplier", "requiresBusiness": false, "reason": "default (supplier — factura el proveedor)" },
  "resolved_products": [],
  "resolved_catalog": { "categories": [], "products": [] },
  "payload_preview": {
    "name": "Agencia Marea Azul",
    "commission": 15,
    "payment_mode": "full_to_agent",
    "hidePriceDetails": true
  },
  "warnings": []
}

Errores propios

Consejos

• commission es un porcentaje (15 = 15 %), no céntimos; amount_eur dentro de commission_by_product va en euros y Buky lo guarda en céntimos.
• Si no indicas payment_mode ni invoice_mode, la agencia queda igual que si la crearas desde el panel sin tocar esos campos: cobra ella y facturas tú.

update-partner: edita los datos de una agencia existente

Cambia solo los campos que le pases; el resto de la agencia queda igual. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/update-partner \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"partner": "GetYourGuide", "commission": 20}'

Por MCP: «Sube la comisión de la agencia GetYourGuide al 20 %.»

Parámetros

Qué devuelve

Prueba en seco cambiando solo la comisión:

{
  "success": true,
  "operation": "update-partner",
  "_id": "6979efe8cecd6cb2336188a5",
  "changes": { "commission": 20 },
  "note": "PUT parcial: solo estos campos cambian; customer/_id nunca se envían.",
  "warnings": []
}

Errores propios

Consejos

• Es una edición parcial: si quieres saber qué hay antes de sobrescribirlo (por ejemplo, la razón social actual), consúltalo primero con get-partner.
• commission_by_product sustituye el conjunto entero: si la agencia ya tenía comisiones por producto y quieres conservar alguna, inclúyela también en la llamada.

delete-partner: da de baja una agencia

La agencia deja de verse en el panel y deja de estar disponible para nuevas reservas. No puedes deshacerlo desde la API ni desde el asistente, pero el soporte de Buky puede recuperarla si lo necesitas. Es una operación de escritura.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/delete-partner \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"partner": "GetYourGuide", "confirm": true}'

Por MCP: «Borra la agencia GetYourGuide» (el asistente te pedirá confirmar antes de ejecutar el borrado real).

Parámetros

Qué devuelve

Prueba en seco sobre la agencia real de la cuenta demo:

{
  "success": true,
  "operation": "delete-partner",
  "would_delete": { "_id": "6979efe8cecd6cb2336188a5", "name": "GetYourGuide · auto" },
  "soft_deleted": false,
  "reversible": true,
  "warnings": []
}

Errores propios

Consejos

• Las reservas ya hechas con esta agencia no se tocan; el borrado solo afecta a que puedas seguir asignándole reservas nuevas.
• Si te equivocas, el soporte de Buky puede recuperarla.