Consultar facturas y registros

Estado, QR, XML firmado y listados. Los endpoints de lectura de la API.

El alta de una factura es asíncrona: la API valida, firma y encola el registro, y la remisión a Hacienda se completa en segundo plano. Los endpoints de lectura permiten seguir cada factura hasta su estado final y recuperar sus artefactos.

Estado de una factura

GET /v1/facturas/{idFactura}/estado

{idFactura} es el identificador que devuelve el alta. Consulta este endpoint para conocer el resultado de la remisión, por ejemplo tras recibir pendiente_proceso (VeriFactu) o en_cola (TicketBAI) en la respuesta del alta.

En Python, client.facturas.esperar_verdicto() hace este sondeo y devuelve un veredicto sobre el que ramificar. Ver Del 200 al veredicto.

GET/v1/facturas/ID_FACTURA/estado?nifEmisor=NIF_EMISOR

curl "https://sandbox.veribai.com/v1/facturas/ID_FACTURA/estado?nifEmisor=NIF_EMISOR" \
  -H "x-api-key: TU_CLAVE"

import veribai

client = veribai.Client(api_key="TU_CLAVE", environment="test")

respuesta = client.facturas.estado("ID_FACTURA", nif_emisor="NIF_EMISOR")

const respuesta = await fetch("https://sandbox.veribai.com/v1/facturas/ID_FACTURA/estado?nifEmisor=NIF_EMISOR", {
  method: "GET",
  headers: { "x-api-key": "TU_CLAVE" },
});

if (!respuesta.ok) throw new Error(`VeriBai ${respuesta.status}`);
const datos = await respuesta.json();

Las lecturas llevan siempre el parámetro nifEmisor, el NIF del emisor. La respuesta y sus campos, en la referencia de consulta.

Detalle, QR y XML

GET /v1/facturas/{idFactura}          # detalle completo
GET /v1/facturas/{idFactura}/qr       # código QR
GET /v1/facturas/{idFactura}/xml      # XML firmado

El XML firmado es el documento que se remite a la administración. Está disponible para su descarga y custodia en cualquier momento. Es útil para auditorías o para conservación propia.

Si has perdido el `idFactura`

GET /v1/facturas/buscar?nifEmisor=…&serie=…&numero=…&fechaExpedicion=…

Localiza la factura por su identidad fiscal (serie, número y fecha de expedición) y devuelve el mismo sobre que el detalle, con el idFactura dentro. A partir de ahí vuelven a estar disponibles /estado, /qr, /xml y /registros. serie y numero viajan como parámetros separados, nunca concatenados. Ver la referencia.

Listados

GET /v1/facturas      # facturas del emisor
GET /v1/registros     # registros de facturación
GET /v1/registros/{idRegistro}

Facturas y registros son recursos distintos: la factura es la operación; el registro es el documento firmado y encadenado que la documenta ante Hacienda. Una factura puede tener más de un registro asociado: el alta y, si los hubo, su subsanación o anulación. Ver El registro de facturación.

Patrón recomendado

Da de alta la factura y guarda idFactura junto a tu entidad local. Es la vía directa a todo lo demás; si se pierde, se recupera con /buscar.
Incrusta qrBase64 en el PDF en el momento. No esperes a la remisión.
Sigue el desenlace de la remisión. Con webhooks llega solo: factura.registrada, factura.rechazada o factura.anulada, con el motivo incluido en el rechazo. Sin ellos, consulta /estado de forma diferida (job periódico) y marca la factura al alcanzar su estado final.
Si el desenlace es un rechazo, la factura no está presentada. Lee el motivo (codigoRespuestaAeat y descripcionRespuestaAeat en el registro, o motivoRechazo en el webhook), corrige y reenvía con subsanación.