Webhooks para facturas asíncronas

Recibe el resultado del procesamiento asíncrono de una factura mediante una petición POST de KubiBAI.

Cuando una factura se procesa de forma asíncrona, puedes indicar una URL de webhook para recibir el resultado sin tener que consultar periódicamente su estado.

Funcionamiento

Envía la factura mediante el endpoint Enviar una factura con async_mode igual a lite o full.
Incluye en webhook_url la URL completa en la que quieras recibir el resultado.
KubiBAI procesa la petición y realiza el envío a TicketBAI.
Cuando el procesamiento termina, tanto con éxito como con error, KubiBAI realiza una petición POST a la URL indicada.

El cuerpo del POST contiene la misma información que devuelve el endpoint Consultar el estado de una factura asíncrona, pero los campos se envían directamente en la raíz del objeto JSON, sin un envoltorio data.

Puedes consultar ambos endpoints en la Referencia API.

Configuración de la petición

Incluye estos campos al enviar la factura:

{
  "async_mode": "lite",
  "webhook_url": "https://example.com/webhooks/kubibai"
}

El campo webhook_url se ignora cuando async_mode es none, ya que en ese modo el procesamiento es síncrono y el resultado se devuelve en la respuesta de la propia petición.

Cuerpo del webhook

Campo	Tipo	Descripción
`id`	`string`	Identificador UUID de la factura en KubiBAI. Consérvalo para consultar posteriormente su estado.
`tbai_post_state`	`string`	Estado del envío a TicketBAI: `pending` indica que está pendiente y `sent` que ya se ha realizado el intento de envío. Cuando se envía el webhook, su valor es `sent`.
`tbai_post_status`	`string \| null`	Resultado del envío: `success` si terminó correctamente, `fail` si terminó con errores o `null` si todavía no se ha procesado.
`invoice_data`	`object`	Información de la factura con los mismos campos que la respuesta de una petición síncrona.
`tbai_post_response_data`	`string \| null`	Si el procesamiento termina con error, contiene la respuesta del sistema TicketBAI, normalmente en formato XML. En un envío correcto su valor es `null`.

Ejemplo de procesamiento correcto

Para facilitar la lectura, los ejemplos muestran solo algunos campos de invoice_data. El objeto recibido contiene todos los campos de la respuesta de una petición síncrona.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tbai_post_state": "sent",
  "tbai_post_status": "success",
  "invoice_data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "series_code": "A",
    "invoice_number": "2026-001",
    "tbai_identifier": "TBAI-B12345678-210726-abc123",
    "tbai_post_status": "success"
  },
  "tbai_post_response_data": null
}

Ejemplo de procesamiento con error

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tbai_post_state": "sent",
  "tbai_post_status": "fail",
  "invoice_data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "series_code": "A",
    "invoice_number": "2026-001",
    "tbai_identifier": null,
    "tbai_post_status": "fail"
  },
  "tbai_post_response_data": "<respuesta>...</respuesta>"
}

Consulta alternativa del estado

Si no incluyes webhook_url, o si necesitas volver a comprobar el resultado, utiliza el identificador id con el endpoint Consultar el estado de una factura asíncrona de la Referencia API.