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

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í:

  1. Si la petición incluye pos_system_data, con el certificado de ese TPV. No hace falta la encryption_key del software garante.
  2. Si no, y el intermediario es software garante, con su certificado. En ese caso, guarantor_software_data.encryption_key es obligatoria.
  3. 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 siempre null.

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 (message es null). El código une el del alta y el número del aviso: por ejemplo, 010177 corresponde al aviso 010-177. Una factura registered no 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.