API pública — Facturas (customerInvoices)

Miguel Gómez Pérez · Equipo Bukyapp· 4 min de lectura·Actualizado 21 may 2026

Consulta las facturas emitidas a clientes de tu cuenta mediante la API pública de Buky, con datos fiscales, líneas de detalle, impuestos y estado VeriFactu

Esta página explica cómo consultar las facturas emitidas a clientes de tu cuenta mediante la API pública de Buky. Cada factura contiene los datos fiscales del emisor y receptor, las líneas de detalle, los impuestos aplicados y, si tu cuenta tiene VeriFactu activado, el estado de la declaración ante Hacienda.

Antes de empezar

• Necesitas un API Token activo. Si aún no lo has creado, sigue la guía Conectar Buky con herramientas externas (API Tokens).
• El token es de solo lectura: puedes listar y consultar facturas, pero no crearlas, modificarlas ni anularlas.
• La función está en fase beta. Si no ves la pestaña "API Tokens" en tu configuración, contacta con soporte.

Autenticación

El token se envía en cada petición de una de estas dos formas:

Opción 1 — Cabecera `auth` (recomendado):

curl "https://app.bukyapp.com/api/customerInvoices" \
  -H "auth: bk_TU_TOKEN"

Opción 2 — Parámetro `token` en la URL:

curl "https://app.bukyapp.com/api/customerInvoices?token=bk_TU_TOKEN"

Usa la cabecera siempre que puedas — las URLs suelen quedarse en logs y expuestas.

Listar facturas

curl "https://app.bukyapp.com/api/customerInvoices" \
  -H "auth: bk_TU_TOKEN"

La respuesta es un array JSON de facturas, ordenado por fecha de creación descendente por defecto (la más reciente primero):

[
  {
    "_id": "66a1b2c3d4e5f67890abcdef",
    "prefix": "FA",
    "number": 42,
    "issuedDate": "2026-03-15T00:00:00.000Z",
    "total": 125.40,
    "mode": "normal",
    "customer": "5f0e1d2c3b4a5968778695a4",
    "orders": ["66b2c3d4e5f67890abcdef01"],
    "from_business_name": "Marea Surf Co.",
    "from_vat": "B12345678",
    "to_business_name": "Laura García",
    "to_vat": "12345678A",
    "items": [
      {
        "label": "Clase de surf grupal",
        "quantity": 2,
        "subtotal": 103.64,
        "total": 125.40,
        "taxes": [{"name": "IVA", "rate": 21, "amount": 21.76}]
      }
    ],
    "isCancelled": null,
    "verifactu_estado": "Aceptado",
    "createdAt": "2026-03-15T10:30:00.000Z"
  },
  ...
]

Paginación

En las cabeceras de la respuesta recibes el total de resultados y el número de páginas:

• X-Count: total de facturas que coinciden con el filtro.
• X-Page-Count: número de páginas.

Por defecto el endpoint devuelve como máximo 100 facturas por página. Para paginar:

curl "https://app.bukyapp.com/api/customerInvoices?page=1&limit=50" \
  -H "auth: bk_TU_TOKEN"

• limit: facturas por página (máximo 100).
• page: número de página, empezando en 1.

Filtrar facturas

El parámetro filter acepta un objeto JSON con sintaxis MongoDB. Envíalo codificado en la URL.

Por fecha de emisión

# Facturas del primer trimestre de 2026
curl -G "https://app.bukyapp.com/api/customerInvoices" \
  -H "auth: bk_TU_TOKEN" \
  --data-urlencode 'filter={"issuedDate":{"$gte":"2026-01-01","$lt":"2026-04-01"}}'

Por serie (prefix)

# Solo facturas de la serie "FA"
curl -G "https://app.bukyapp.com/api/customerInvoices" \
  -H "auth: bk_TU_TOKEN" \
  --data-urlencode 'filter={"prefix":"FA"}'

Facturas de un cliente concreto

Si conoces el _id del cliente (customerClient):

curl -G "https://app.bukyapp.com/api/customerInvoices" \
  -H "auth: bk_TU_TOKEN" \
  --data-urlencode 'filter={"partner":"65f1a2b3c4d5e6f7a8b9c0d1"}'

Solo facturas activas (no anuladas)

--data-urlencode 'filter={"isCancelled":null}'

Solo facturas anuladas

--data-urlencode 'filter={"isCancelled":{"$ne":null}}'

Por número de factura

--data-urlencode 'filter={"number":42}'

Por estado de VeriFactu

# Solo las aceptadas por Hacienda
--data-urlencode 'filter={"verifactu_estado":"Aceptado"}'

# Las que tuvieron error
--data-urlencode 'filter={"verifactu_estado":"Error"}'

Facturas rectificativas

# Solo rectificativas (tienen referencia a la factura original)
--data-urlencode 'filter={"isRectification":{"$ne":null}}'

Combinando filtros

Cualquier combinación funciona — se aplica como AND:

--data-urlencode 'filter={"prefix":"FA","issuedDate":{"$gte":"2026-01-01"},"isCancelled":null}'

Ordenar los resultados

Con sort, también en formato JSON:

# Por fecha de emisión, más antiguas primero
--data-urlencode 'sort={"issuedDate":1}'

# Por número de factura descendente
--data-urlencode 'sort={"number":-1}'

# Por total, de mayor a menor
--data-urlencode 'sort={"total":-1}'

1 = ascendente, -1 = descendente.

Traer solo los campos que necesites

Con fields reduces el tamaño de la respuesta pidiendo solo las columnas que usas:

--data-urlencode 'fields={"prefix":1,"number":1,"issuedDate":1,"total":1,"to_business_name":1,"isCancelled":1}'

Útil cuando exportas facturas y solo necesitas un resumen contable.

Expandir relaciones (populate)

Las referencias a otros recursos vienen como IDs. Para obtener el objeto completo en la misma respuesta:

curl -G "https://app.bukyapp.com/api/customerInvoices" \
  -H "auth: bk_TU_TOKEN" \
  --data-urlencode 'populate=partner'

Relaciones expandibles:

• partner — ficha del cliente destinatario (customerClient).
• orders — reservas asociadas a la factura.
• order — reserva individual (campo legacy, usar orders preferiblemente).
• isRectification — factura original si esta es una rectificativa.

Úsalo con moderación: expandir relaciones en consultas grandes puede hacer la respuesta muy pesada.

Consultar una factura concreta

curl "https://app.bukyapp.com/api/customerInvoices/66a1b2c3d4e5f67890abcdef" \
  -H "auth: bk_TU_TOKEN"

Devuelve la factura completa con todos sus campos.

Campos útiles del objeto CustomerInvoice

Líneas de detalle (items)

Cada factura tiene un array items con las líneas:

VeriFactu

Si tu cuenta tiene VeriFactu activado, las facturas incluyen campos adicionales que reflejan el estado de la declaración ante la AEAT:

• verifactu_estado: estado actual (Aceptado, Pendiente, Error...).
• verifactu_url: enlace para verificar la factura en la web de la AEAT.
• verifactu_qr: código QR que puedes incluir en la factura impresa.
• verifactu_uuid: identificador único de la declaración.

Si tu cuenta no tiene VeriFactu, estos campos estarán vacíos.

Consejos

• Filtra por fecha de emisión. La mayoría de consultas contables necesitan un rango de fechas. Usa issuedDate con $gte y $lt para acotar el trimestre, mes o año fiscal que necesites.
• Distingue activas de anuladas. Una factura anulada tiene isCancelled con una fecha. Si estás haciendo cálculos contables, recuerda excluirlas con "isCancelled": null.
• Usa `fields` para exportaciones. Si solo necesitas serie, número, fecha y total para un libro de facturas, no pidas la factura completa con todos los datos fiscales.
• Cuidado con `order` vs `orders`. El campo order es legacy y apunta a una sola reserva. El campo orders es un array y es el que se usa actualmente. Si una factura agrupa varias reservas (por ejemplo, de una agencia), todas estarán en orders.
• Las rectificativas tienen referencia. Si isRectification tiene valor, esa factura es una rectificativa de otra. Puedes expandirla con populate=isRectification para ver la original.

Preguntas frecuentes

¿Puedo crear o anular facturas por la API?

No. Los API Tokens son de solo lectura. Sirven para consultar datos, no para modificarlos. La creación y anulación de facturas se hace desde el panel de Buky.

¿Cómo sé si una factura es rectificativa?

Si el campo isRectification tiene un valor (el ID de otra factura), es una rectificativa. Si es null, es una factura original.

¿Por qué hay facturas sin número?

Las facturas sin number son borradores que aún no se han emitido. No tienen validez fiscal y no deberían incluirse en tus cálculos contables. Puedes excluirlas con filter={"number":{"$ne":null}}.

¿Qué significa el campo `version`?

Indica el formato de la factura. null corresponde al formato anterior a VeriFactu, donde las rectificativas anulaban en negativo. 2 es el formato actual, donde las facturas rectificativas son sustitutivas. Si tu cuenta activó VeriFactu recientemente, puedes tener facturas con ambos formatos.

¿Los datos fiscales (from/to) siempre están completos?

Depende de cómo se configuró la factura. Las facturas en modo simple pueden tener menos datos del destinatario que las de modo normal. Si necesitas datos fiscales completos, verifica que mode sea normal.