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.