---
title: Consulta de facturas en Hacienda
description: 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`](/api#tag/consultas-de-facturas/POST/invoicing/invoices/query) | Araba y Bizkaia |
| Última factura | [`POST /invoicing/invoices/query/latest`](/api#tag/consultas-de-facturas/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](/guides/autorizaciones-de-representacion),
salvo que el intermediario sea software garante.

:::note
Gipuzkoa solo ofrece la consulta de facturas en su entorno de pruebas. Para una
empresa de Gipuzkoa, las dos consultas responden `422` con el código
`E-UNPROCESSABLE`. La última factura tampoco existe en Bizkaia, y responde
igual.
:::

## 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`.

:::warning
Una respuesta sin facturas no prueba que la hacienda no tenga una factura:
solo que el certificado de la consulta no la ve. Por ejemplo:

- Una factura que firmó y presentó un TPV con su propio certificado no aparece
  al consultar con el certificado de KubiBAI. Consulta con `pos_system_data`
  de ese TPV.
- Las facturas de un software garante no aparecen al consultar con el
  certificado de KubiBAI. Consulta con su `encryption_key`.
:::

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

```json
{
  "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:00 y `issued_to` termina a las 23:59: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.

:::note
No confundas esta consulta con [Obtener la última factura correctamente
procesada](/api#tag/facturas/GET/invoicing/invoices/latest), que busca entre
las facturas enviadas mediante KubiBAI sin consultar a la hacienda.
:::

## 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](/api#tag/consultas-de-facturas/POST/invoicing/invoices/query).

### 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. |
