Saltar al contenido
KubiBAI Web Services
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

Encadenamiento de facturas

Organiza las cadenas TicketBAI y trata los reintentos del encadenamiento automático.

Cada factura TicketBAI identifica la factura anterior de su cadena. Con el encadenamiento automático, KubiBAI elige la anterior; con el manual, tu aplicación envía esos datos. Si no eres software garante, KubiBAI encadena siempre tus facturas en automático.

Qué es una cadena

Una cadena reúne las facturas de una misma empresa o profesional emitidas con el mismo TPV/POS. Las facturas de esa empresa sin TPV/POS forman otra cadena. Dos TPV distintos tienen cadenas independientes, aunque pertenezcan a la misma empresa.

Encadenamiento automático

Se aplica siempre a las empresas de los intermediarios que no son software garante: sus facturas se firman con el certificado y la licencia TicketBAI de KubiBAI, y KubiBAI responde de su cadena. Si eres software garante, puedes activarlo para todas tus empresas o para una empresa concreta.

Con encadenamiento automático puedes omitir previous_invoice_data en el alta de facturas. Si la cadena ya tiene una factura anterior, KubiBAI la elige al tramitar el alta, aunque tu aplicación envíe ese objeto. En la primera factura de una cadena se respeta el previous_invoice_data que envíes; por ejemplo, para enlazar con la última factura emitida con otro programa.

En los modos none y lite, las altas simultáneas de una misma cadena se tramitan por turnos:

  • En none, el turno abarca la firma y el envío a TicketBAI.
  • En lite, el turno abarca la firma y el encolado del envío. La siguiente factura puede encadenarse a la ya firmada sin esperar su respuesta de TicketBAI.

La espera máxima para obtener el turno es de 20 segundos. A ese tiempo se añade el procesamiento de la propia factura; no es un límite para la duración total de la petición.

En full, la firma y el envío se realizan en segundo plano y no se espera turno. Si otra factura de la cadena sigue en proceso, el alta devuelve 422. También puede ocurrir en none o lite, por ejemplo cuando una factura anterior enviada en full todavía está pendiente de firma.

Cómo tratar los errores de encadenamiento automático

Los dos errores siguientes devuelven HTTP 422 con código E-WRONGARGS, mensaje general The given data was invalid. y un array de mensajes en data.error.errors["previous_invoice_data.signature_value"].

Mensaje literal Qué hacer
The invoice chain is busy processing another invoice. Retry the request in a few seconds. No se ha obtenido turno dentro de los 20 segundos. Reintenta la misma petición unos segundos después.
Another invoice of the same chain is still being processed (invoice ID: [{id}]). Retry the request once it has been sent to TicketBAI. El mensaje contiene el UUID de la factura en proceso entre corchetes. Espera a que termine el procesamiento de esa factura y reintenta la misma petición.

Puedes consultar la factura indicada mediante la consulta de estado o recibir su resultado por webhook. No necesitas cambiar los datos de la factura anterior para reintentar estos dos errores.

Encadenamiento manual

Solo está disponible para los intermediarios que son software garante y no han activado el encadenamiento automático. Tu aplicación envía en previous_invoice_data la firma de la factura anterior y, cuando sean necesarios, su serie, número y fecha. En la primera factura de la cadena no hay una factura anterior que indicar.

KubiBAI exige previous_invoice_data cuando la cadena de la factura ya tiene una factura enviada correctamente. Solo cuentan las facturas de esa cadena: para una factura sin TPV/POS, las enviadas sin TPV/POS; para una de TPV/POS, las de ese TPV/POS. Por ejemplo, la primera factura sin TPV/POS de una empresa que hasta ahora solo ha facturado desde TPV/POS no lo necesita.

Para conservar el orden de emisión, organiza las altas de una misma cadena de forma secuencial. Si trabajas con varios terminales, puedes configurar un TPV/POS distinto para cada uno y mantener cadenas independientes.

Con ignore_signature_value_mismatch a true, KubiBAI no comprueba que la firma indicada sea la de la última factura de la cadena. Las haciendas forales mantienen sus propias validaciones. Con encadenamiento automático, este campo no tiene efecto.