Consulta de facturas en Hacienda
Consulta las facturas de una empresa que tiene registradas la hacienda de Araba o de Bizkaia, y qué ve cada certificado.
KubiBAI consulta a la hacienda del territorio de una empresa qué facturas emitidas tiene registradas y en qué estado. La respuesta es un JSON común a Araba y Bizkaia, con el estado de cada factura, sus errores o avisos y sus datos principales, sin el XML de la hacienda ni el desglose de IVA.
Hay dos consultas:
| Consulta | Endpoint | Territorios |
|---|---|---|
| Facturas, paginadas y con filtros | POST /invoicing/invoices/query |
Araba y Bizkaia |
| Última factura | POST /invoicing/invoices/query/latest |
Araba |
Las dos usan la API key de la empresa en el encabezado
X-Qbikode-ClientApiKey. En Bizkaia, la empresa debe tener validada su
autorización de representación,
salvo que el intermediario sea software garante.
Qué facturas ve cada certificado
La hacienda solo devuelve las facturas que presentó o firmó el certificado con el que se hace la consulta. KubiBAI elige el certificado así:
- Si la petición incluye
pos_system_data, con el certificado de ese TPV. No hace falta laencryption_keydel software garante. - Si no, y el intermediario es software garante, con su certificado. En ese
caso,
guarantor_software_data.encryption_keyes obligatoria. - En otro caso, con el certificado de KubiBAI, como colaborador social.
El campo queried_as de la respuesta indica el certificado usado:
kubibai, guarantor_software o pos_system.
Consulta paginada
fiscal_year es obligatorio y debe estar entre 2020 y el año en curso. Los
demás filtros son opcionales y se envían en el cuerpo JSON de la petición:
{
"fiscal_year": 2026,
"series": "A2026",
"issued_from": "2026-10-01",
"issued_to": "2026-10-31"
}
Cada territorio admite filtros distintos. Un filtro que el territorio de la
empresa no admite se rechaza con 422, no se ignora.
| Filtro | Araba | Bizkaia | Formato |
|---|---|---|---|
fiscal_year |
Sí | Sí | Entero, entre 2020 y el año en curso. Obligatorio. |
series, number |
Sí | Sí | Cadena de hasta 20 caracteres. |
issued_from, issued_to |
Sí | Sí | Y-m-d. En Araba también Y-m-d H:i:s. |
status |
Sí | Solo registered, registered_with_errors y cancelled |
Uno de los estados de la respuesta. |
period |
Sí | No | 0A (ejercicio completo, por defecto), 1T a 4T o 01 a 12. |
operation_date_from, operation_date_to |
Sí | No | Y-m-d. |
presented_from, presented_to |
Sí | No | Y-m-d H:i:s. |
recipient_tax_id |
No | Sí | NIF de 9 caracteres. |
page |
Sí | Sí | Entero mayor o igual que 1. Por defecto, 1. |
Una fecha de expedición sin hora abarca el día entero: issued_from empieza a
las 00:00 y issued_to termina a las 23:59. Las fechas y horas, tanto de
los filtros como de la respuesta, están en hora peninsular. El final de cada
intervalo no puede ser anterior a su principio.
Paginación
La respuesta indica la página devuelta (page), el total de páginas
(total_pages), el total de facturas que cumplen los filtros
(total_invoices) y si hay más páginas (has_more). Para obtener la siguiente,
repite la consulta con los mismos filtros y page incrementado. Bizkaia
rechaza una página mayor que el total.
Retraso de Araba
En Araba, la consulta paginada devuelve los datos del día anterior. El campo
data_as_of indica el día al que corresponden. Una factura presentada hoy no
aparece hasta mañana, aunque la consulta se responde y se cobra igual. En
Bizkaia, data_as_of es null: los datos están al día.
Última factura
La consulta de la última factura solo existe en Araba y responde en tiempo
real, así que no lleva data_as_of. No admite filtros, ni siquiera
fiscal_year. El cuerpo solo es necesario para elegir el certificado, con
pos_system_data o guarantor_software_data.
La respuesta devuelve la factura en invoice, o null si el certificado de la
consulta no ve ninguna.
Datos de cada factura
Cada factura tiene la misma estructura en las dos consultas. Destacan estos campos:
status: estado común a los dos territorios.hacienda_status: estado tal como lo devuelve la hacienda.errors: errores o avisos con los que la hacienda registró la factura.signature_value: los 100 primeros caracteres de la firma. La hacienda no devuelve la firma completa.tbai_id: identificador TicketBAI. Bizkaia no lo devuelve, y KubiBAI lo calcula a partir del NIF del emisor, la fecha de expedición y la firma.previous_invoice: factura anterior de la cadena. Solo en Bizkaia; en Araba es siemprenull.
Consulta todos los campos en la Referencia API.
Estados
status |
Significado | Araba (hacienda_status) |
Bizkaia (hacienda_status) |
|---|---|---|---|
registered |
Registrada sin errores. | C |
Correcto |
registered_with_errors |
Registrada con errores o avisos. | C, con códigos en errors |
AceptadoConErrores |
cancelled |
Anulada. | A |
Anulado |
rectified |
Rectificada. | Z |
No existe |
substituted |
Sustituida. | S |
No existe |
Errores y avisos
El contenido de errors depende del territorio:
- En Araba, cada elemento lleva un código de 6 cifras sin descripción
(
messageesnull). El código une el del alta y el número del aviso: por ejemplo,010177corresponde al aviso 010-177. Una facturaregisteredno lleva ningún código. - En Bizkaia, cada elemento lleva el código de la hacienda y su descripción.
Aparte, warnings recoge los avisos de la hacienda que no le impiden responder,
por ejemplo, un aviso de certificado caducado en Araba. En Bizkaia siempre está
vacío.
Cobro
Cada consulta que la hacienda responde cuenta como una operación facturable, también si no devuelve ninguna factura. Las consultas que terminan en error no se cobran.
Errores
| HTTP | Código | Cuándo | Qué hacer |
|---|---|---|---|
400 |
E-UNPROCESSABLE |
En Bizkaia, la autorización de representación de la empresa no existe, no está validada o se ha rechazado. | Carga o corrige la autorización. |
422 |
E-UNPROCESSABLE |
La consulta no existe en el territorio de la empresa. | No sirve reintentarla. |
422 |
E-WRONGARGS |
Un filtro o un dato del certificado no es válido, el territorio no admite un filtro o la empresa está deshabilitada. Los errores de cada campo están en errors. |
Corrige la petición. |
422 |
E-WRONGARGS |
Bizkaia rechaza los filtros: intervalo de fechas erróneo (B4_1000027), más resultados de los que puede devolver (B4_1000028) o página mayor que el total (B4_1000029). El código está en details.hacienda_code. |
Cambia los filtros. |
429 |
Se ha superado el límite de peticiones de la API. | Espera y reintenta. | |
500 |
E-INTERROR |
Error interno de KubiBAI. | Reintenta y, si se repite, contacta con soporte. |
502 |
E-TPERROR |
La hacienda no responde o rechaza la consulta. Si ha devuelto un código, está en details.hacienda_code. Si no ha respondido, el mensaje lleva el identificador de la petición. |
Reintenta más tarde. Si se repite, facilita a soporte el mensaje. |