---
title: Webhooks para facturas asíncronas
description: 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

1. Envía la factura mediante el endpoint **Enviar una factura** con
   `async_mode` igual a `lite` o `full`.
2. Incluye en `webhook_url` la URL completa en la que quieras recibir el
   resultado.
3. KubiBAI procesa la petición y realiza el envío a TicketBAI.
4. 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](/api).

## Configuración de la petición

Incluye estos campos al enviar la factura:

```json
{
  "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.

```json
{
  "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

```json
{
  "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>"
}
```

:::note
El valor de `tbai_post_response_data` mostrado en el ejemplo está abreviado.
Cuando existe, debes tratarlo como la respuesta completa devuelta por
TicketBAI.
:::

## 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](/api).