🔗 Webhooks de Compañía en Buq

📍 ¿Dónde se configura?

Ingresa a tu panel de administración en buq.partners y ve a:

Ajustes → Editar los datos de la compañía → Webhook del sitio de la compañía

Ahí debes colocar la URL a la que se enviarán todas las peticiones webhook.

🔐 Validación y Seguridad

Antes de cada acción, Buq realiza una llamada previa de verificación (ping) a la URL que configuraste. Este ping contiene los siguientes parámetros:

[
  'form_params' => [
    'type'        => 'permission',
    'auth_id'     => $client_id,
    'auth_secret' => $client_secret,
  ],
]

El client_id y client_secret se encuentran en los ajustes de la compañía.
Si el webhook responde con un código 200 y cualquier contenido en el body (por ejemplo, simplemente 'ok'), se considera válido.
Si no se obtiene respuesta válida, la operación no se ejecuta.

👤 Creación y Actualización de Usuarios

Después del ping exitoso, se enviará la información del usuario. Se utiliza el mismo formato para crear o actualizar, cambiando únicamente el valor del parámetro type.

Crear Usuario

'type' => 'adduser'

Actualizar Usuario

'type' => 'updateuser'

Payload completo:

[
  'type'             => 'adduser' | 'updateuser',
  'auth_id'          => $client_id,
  'auth_secret'      => $client_secret,
  'email'            => $userprofile->email,
  'password'         => $userprofile->password,
  'first_name'       => $userprofile->first_name,
  'last_name'        => $userprofile->last_name,
  'birth_date'       => $userprofile->birth_date,
  'address'          => $userprofile->address,
  'external_number'  => $userprofile->external_number,
  'internal_number'  => $userprofile->internal_number,
  'postal_code'      => $userprofile->postal_code,
  'municipality'     => $userprofile->municipality,
  'city'             => $userprofile->city,
  'gender'           => $userprofile->gender,
  'phone'            => $userprofile->phone,
  'cel_phone'        => $userprofile->cel_phone,
]

🛒 Registro de Compras

Cuando un usuario realiza una compra, se envía una estructura más amplia al webhook.

Tipo

'type' => 'addpurchase'

Payload:

[
  'auth_id'             => $client_id,
  'auth_secret'         => $client_secret,
  'type'                => 'addpurchase',
  'admin_profiles_id'   => $purchase->admin_profiles_id,
  'user_profiles_email' => $purchase->user_profiles_email,
  'userName'            => $purchase->user_profile->first_name,
  'last_name'           => $purchase->user_profile->last_name,
  'address'             => $purchase->user_profile->address,
  'external_number'     => $purchase->user_profile->external_number,
  'postal_code'         => $purchase->user_profile->postal_code,
  'municipality'        => $purchase->user_profile->municipality,
  'city'                => $purchase->user_profile->city,
  'cel_phone'           => $purchase->user_profile->cel_phone,
  'total'               => $purchase->total,
  'subtotal'            => $purchase->subtotal,
  'discount'            => $purchase->discount,
  'has_discount_code'   => $purchase->hasDiscountCode(),
  'iva'                 => $purchase->iva,
  'is_giftcard'         => $purchase->isGiftCard(),
  'status'              => $purchase->status,
  'currency'            => $purchase->currency->code3 ?? 'MXN',
  'payment_type'        => $purchase->payment_type->slug ?? 'cash',
  'subscription'        => $purchase->subscription,
  'locations_id'        => $purchase->locations_id,
  'Created_at'          => $purchase->created_at->format('Y-m-d H:i:s'),
  'location_name'       => $locationName,
  'itemsId'             => '5,9,7',
  'itemType'            => 'class,class,product',
  'itemQuantity'        => '1,1,3',
  'itemName'            => '1 clase bici,1 clase pilates,botella de agua',
  'itemdiscount'        => '0,0,10',
  'itemprice'           => '150,150,25',
  'itemDescription'     => 'Clase indoor,Clase relax,Botella BPA Free',
  'itempriceFinal'      => '150,150,15',
  'itemSKU'             => 'bici001,pila001,btl001',
  'iteminventory'       => 'yes,yes,no',
]

Los arrays de ítems (itemsId, itemQuantity, etc.) están separados por comas y deben coincidir en orden y longitud.

⚠️ Consideraciones Técnicas

Todos los datos se envían vía POST.
Si no se recibe una respuesta 200 OK con contenido (por ejemplo 'ok'), la acción no se ejecuta.
No hay reintentos automáticos. En caso de falla, la sincronización debe realizarse manualmente desde consola o con soporte técnico.
No se guarda un log detallado de errores, solo el estado de éxito o fallo por cada webhook enviado.

🕒 ¿Qué viene después?

Actualmente, las reservas aún no están integradas en los Webhooks. Este módulo está en desarrollo y se agregará en futuras versiones del sistema.