Consulta analítica

La consulta analítica agrega los datos de la empresa en una sola llamada: eliges una fuente, las medidas que quieres sumar, las dimensiones por las que agrupar, un periodo y unos filtros, y la API devuelve una tabla ya calculada. Es la forma de responder preguntas como «¿quiénes son mis cinco mejores clientes del año?», «¿cuánto suman las facturas vencidas?» o «¿qué provincias facturan más que el año pasado?» sin recorrer los listados página a página.

Las cifras son las mismas que muestran los listados y los informes de la aplicación: cada medida se define una sola vez y con el mismo criterio que la pantalla equivalente. Los importes de las facturas son los del documento (base, impuestos, total y pendiente); los del diario, los de los apuntes.

Es de solo lectura. Las consultas se calculan en el momento, sobre los datos actuales, y cada una tiene un tope de 30 segundos.

Para los informes oficiales (resumen de resultados, pérdidas y ganancias, balance, sumas y saldos) usa los informes: aplican las reglas de presentación de cada modelo. La consulta analítica sirve para rankings, totales y comparativas a medida.

Fuentes#

Cada fuente se llama como el recurso de la API cuyo listado devolvería esos documentos; invoiceLines y billLines son las líneas de esos mismos documentos, con su producto. No hay fuentes genéricas como «ventas» o «compras»: la contabilidad es solo journal.

Los borradores no entran salvo que lo pidas con el filtro draft, y los documentos anulados, salvo que los pidas con el filtro state (voided en value o entre los values). Los documentos borrados no entran nunca.

En invoices, las facturas simplificadas (las de un destinatario sin identificador fiscal) entran como las demás; el filtro simplified las separa. Las sustitutivas de simplificadas (F3) no entran nunca: repiten las ventas de las simplificadas que sustituyen y no tienen asiento, así que contarlas sumaría dos veces la misma venta. Los documentos con total cero entran y cuentan en count.

Petición#

POST /{companyId}/query con un cuerpo JSON:

El periodo acota por la fecha del documento en invoices y bills y por la fecha del apunte en journal. En contacts acota por la fecha de alta del contacto y es opcional: sin period, la consulta cuenta todos los contactos («¿cuántos clientes tengo por provincia?»); con period, los dados de alta en esas fechas, sin el tope de 5 años. compare y breakdown necesitan period también en contacts.

Medidas#

Facturas de venta y de compra#

Las medidas de días admiten la agregación como sufijo: .avg (por defecto), .median, .p90, .min, .max o .count (cuántos documentos entran en el cálculo). Puedes pedir varias a la vez: daysToPayment y daysToPayment.median.

Líneas de facturas de venta y de compra#

En invoiceLines y billLines:

En invoiceLines, además, el margen de las ventas, incluido en todos los planes de pago (ver Planes). El coste sale del precio de compra que tiene hoy el producto, en la moneda de la empresa, así que estas medidas van siempre en esa moneda: con multimoneda, piden amounts: "company" para que las ventas también lo estén (si no, 400).

Contactos#

Diario#

Todos los importes van en la moneda de la empresa.

Dimensiones#

Facturas de venta y de compra#

Líneas de facturas de venta y de compra#

En invoiceLines y billLines, además de contact, contact.region, contact.country, fiscalId, country, series, currency y las de tiempo, que son las del documento de la línea:

Contactos#

Diario#

La dimensión contact del diario es la que responde «ventas de las cuentas 7 por cliente» incluyendo los asientos manuales, algo que invoices no ve. Un apunte de ventas sin contacto queda en unassigned.

Identificador fiscal#

fiscalId agrupa por el identificador fiscal y no por el contacto: dos contactos duplicados con el mismo NIF suman en una sola fila. En las facturas es el identificador que el documento copió de su contacto al emitirse; los documentos más antiguos, que no lo guardan, toman el del contacto hoy, como el listado.

Para agrupar, el identificador se normaliza según su país:

El país es el del identificador del contacto o, si no lo tiene, el de su dirección. Los documentos sin identificador forman el grupo null, que en un negocio con muchos tickets puede ser el más grande.

El filtro fiscalId busca la clave tal como la da la dimensión. Admite separadores y minúsculas, y un NIF español con el prefijo ES o un DNI sin sus ceros. Un identificador de otro país de la UE tiene que llevar su prefijo (FR12345678901): sin él, las mismas cifras podrían ser de otro país.

Filtros#

Cada filtro tiene un campo, un operador y un valor (value) o una lista de valores (values):

Respuesta#

En cada fila, el valor de una dimensión depende de su tipo:

• Entidad (contact, product, fiscalId, paymentMethod, thirdParty, account, las provincias): { "id", "name" }, más type en thirdParty, fiscalId y country (los del contacto hoy) en contact, sku en product, y webUrl cuando el elemento tiene ficha en la aplicación (ver Abrir un resultado en FacturaDirecta). name es null si el elemento ya no existe.
• Periodo: las dimensiones de tiempo (day, week, month, quarter, year, createdMonth) valen un texto (2026-W14, 2026-03); la dimensión period del desglose, { "id", "start", "end" }.
• El resto: un texto, un número o un booleano. Una dimensión sin valor (un documento sin país, por ejemplo) vale null y forma su propio grupo.

Las medidas valen un número, o null cuando no hay dato (la media de días de un cliente sin cobros). Los importes van redondeados a céntimos y los días a una décima.

Con compare, cada medida añade tres columnas: <medida>_reference (el valor en el periodo de referencia), <medida>_difference (periodo menos referencia) y <medida>_variance (la variación como fracción, 0.2 es un 20 %, o null si la referencia es cero). Con breakdown, la columna period identifica el tramo de cada fila.

En empresas con multimoneda, currency es una dimensión implícita de invoices, bills y sus líneas cuando la consulta pide importes: aparece en las filas aunque no la pidas y los importes de monedas distintas nunca se mezclan. Una consulta sin importes (documentos, cantidades, días) no se separa por moneda. Con amounts: "company" los importes van en la moneda de la empresa y tampoco se separan. Los importes de journal van siempre en la moneda de la empresa.

Operaciones#

• Consultar

Consultar#

POST /{companyId}/query

Necesita el scope de la fuente: invoices:read, bills:read, contacts:read o accounting:read. Una API key con varios de ellos puede consultar varias fuentes, una por llamada. No admite la cabecera Idempotency-Key: repetir la consulta no tiene efectos.

Ejemplo: los cinco mejores clientes del año#

curl "https://app.facturadirecta.com/api/$COMPANY_ID/query" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "invoices",
    "measures": ["totalBeforeTaxes", "count"],
    "dimensions": ["contact"],
    "limit": 5,
    "includeOther": true
  }'

{
  "meta": {
    "source": "invoices",
    "basis": "documents",
    "period": { "start": "2026-01-01", "end": "2026-12-31" },
    "currency": "EUR",
    "limit": 5,
    "generatedAt": "2026-10-18T10:00:00.000Z"
  },
  "columns": [
    { "id": "contact", "kind": "dimension", "title": "Contacto", "description": "Cliente o proveedor del documento (`id`, `name`).", "type": "entity" },
    { "id": "totalBeforeTaxes", "kind": "measure", "title": "Base imponible", "description": "Suma de la base imponible de cada factura, en la moneda del documento. Es la cifra que el listado muestra como «base».", "type": "money", "measure": "totalBeforeTaxes", "period": { "start": "2026-01-01", "end": "2026-12-31" } },
    { "id": "count", "kind": "measure", "title": "Documentos", "description": "Número de facturas del conjunto filtrado.", "type": "count", "measure": "count", "period": { "start": "2026-01-01", "end": "2026-12-31" } }
  ],
  "rows": [
    { "contact": { "id": "<id-contacto>", "name": "Cliente Uno", "webUrl": "https://app.facturadirecta.com/company/<id-empresa>/contacts/<id-contacto>" }, "totalBeforeTaxes": 18400, "count": 14 },
    { "contact": { "id": "<id-contacto-2>", "name": "Cliente Dos", "webUrl": "https://app.facturadirecta.com/company/<id-empresa>/contacts/<id-contacto-2>" }, "totalBeforeTaxes": 12750, "count": 9 }
  ],
  "totals": { "totalBeforeTaxes": 48200, "count": 61 },
  "other": { "groups": 23, "totalBeforeTaxes": 17050, "count": 38 },
  "truncated": true
}

La respuesta real tiene cinco filas; aquí se muestran dos. totals suma las 61 facturas del año y other las 38 de los 23 clientes que quedan fuera de las cinco primeras filas.

Ejemplo: los mejores clientes por identificador fiscal#

Si el mismo cliente está dado de alta dos veces, contact lo reparte en dos filas. fiscalId lo reúne, y contacts dice cuántos contactos hay detrás de cada fila.

curl "https://app.facturadirecta.com/api/$COMPANY_ID/query" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "invoices",
    "measures": ["totalBeforeTaxes", "contacts"],
    "dimensions": ["fiscalId"],
    "limit": 5
  }'

{
  "rows": [
    { "fiscalId": { "id": "B12345674", "name": "Cliente Uno SL" }, "totalBeforeTaxes": 21300, "contacts": 2 },
    { "fiscalId": { "id": "FR12345678901", "name": "Client Deux SARL" }, "totalBeforeTaxes": 9800, "contacts": 1 }
  ],
  "totals": { "totalBeforeTaxes": 48200, "contacts": 37 }
}

La primera fila reúne dos contactos con el NIF B12345674. Para ver cuáles son, repite la consulta con "dimensions": ["fiscalId", "contact"] y el filtro { "field": "fiscalId", "op": "eq", "value": "B12345674" }. Para buscar todos los contactos duplicados sin mirar facturas, consulta contacts con la medida count y la dimensión fiscalId: los grupos de más de uno salen primero.

Ejemplo: facturas vencidas y cuánto suman#

Sin dimensiones, la respuesta es una sola fila con los totales del conjunto filtrado.

curl "https://app.facturadirecta.com/api/$COMPANY_ID/query" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "invoices",
    "measures": ["count", "total", "pending"],
    "period": { "start": "2022-01-01", "end": "2026-12-31" },
    "filters": [{ "field": "state", "op": "in", "values": ["overdue"] }]
  }'

{
  "meta": { "source": "invoices", "basis": "documents", "period": { "start": "2022-01-01", "end": "2026-12-31" }, "currency": "EUR", "limit": 10, "generatedAt": "2026-10-18T10:00:00.000Z" },
  "columns": [
    { "id": "count", "kind": "measure", "title": "Documentos", "description": "Número de facturas del conjunto filtrado.", "type": "count", "measure": "count", "period": { "start": "2022-01-01", "end": "2026-12-31" } },
    { "id": "total", "kind": "measure", "title": "Total", "description": "Suma del total de cada factura, impuestos incluidos, en la moneda del documento.", "type": "money", "measure": "total", "period": { "start": "2022-01-01", "end": "2026-12-31" } },
    { "id": "pending", "kind": "measure", "title": "Pendiente", "description": "Importe pendiente de cobro, en la moneda del documento: el total menos lo cobrado; negativo si se ha cobrado de más.", "type": "money", "measure": "pending", "period": { "start": "2022-01-01", "end": "2026-12-31" } }
  ],
  "rows": [
    { "count": 3, "total": 1815, "pending": 1815 }
  ],
  "totals": { "count": 3, "total": 1815, "pending": 1815 },
  "truncated": false
}

Para la lista de esas facturas, con sus datos, usa el listado con state=overdue; con totals=true el listado devuelve también estas sumas.

Ejemplo: provincias con más facturación, frente al año anterior#

curl "https://app.facturadirecta.com/api/$COMPANY_ID/query" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "invoices",
    "measures": ["totalBeforeTaxes"],
    "dimensions": ["contact.region"],
    "period": { "start": "2026-01-01", "end": "2026-06-30" },
    "compare": "previousYear",
    "limit": 5
  }'

{
  "meta": { "source": "invoices", "basis": "documents", "period": { "start": "2026-01-01", "end": "2026-06-30" }, "compare": { "kind": "previousYear", "start": "2025-01-01", "end": "2025-06-30" }, "currency": "EUR", "limit": 5, "generatedAt": "2026-10-18T10:00:00.000Z" },
  "columns": [
    { "id": "contact.region", "kind": "dimension", "title": "Provincia del contacto", "description": "Provincia de la dirección actual del contacto (la del contacto hoy, no la del documento): `id` es el código y `name` el nombre para España.", "type": "entity" },
    { "id": "totalBeforeTaxes", "kind": "measure", "title": "Base imponible", "description": "…", "type": "money", "measure": "totalBeforeTaxes", "period": { "start": "2026-01-01", "end": "2026-06-30" } },
    { "id": "totalBeforeTaxes_reference", "kind": "measure", "title": "Base imponible (referencia)", "description": "La medida en el periodo de referencia (el mismo periodo del año anterior).", "type": "money", "measure": "totalBeforeTaxes", "period": { "start": "2025-01-01", "end": "2025-06-30" } },
    { "id": "totalBeforeTaxes_difference", "kind": "measure", "title": "Base imponible (diferencia)", "description": "Periodo menos referencia.", "type": "money", "measure": "totalBeforeTaxes" },
    { "id": "totalBeforeTaxes_variance", "kind": "measure", "title": "Base imponible (variación)", "description": "Variación sobre la referencia, como fracción (`0.2` es un 20 %); `null` si la referencia es cero.", "type": "ratio", "measure": "totalBeforeTaxes" }
  ],
  "rows": [
    { "contact.region": { "id": "08", "name": "Barcelona" }, "totalBeforeTaxes": 31200, "totalBeforeTaxes_reference": 27400, "totalBeforeTaxes_difference": 3800, "totalBeforeTaxes_variance": 0.1387 },
    { "contact.region": { "id": "28", "name": "Madrid" }, "totalBeforeTaxes": 12900, "totalBeforeTaxes_reference": 14100, "totalBeforeTaxes_difference": -1200, "totalBeforeTaxes_variance": -0.0851 }
  ],
  "totals": { "totalBeforeTaxes": 52300, "totalBeforeTaxes_reference": 48900, "totalBeforeTaxes_difference": 3400, "totalBeforeTaxes_variance": 0.0695 },
  "truncated": false
}

Ejemplo: ventas de las cuentas 7 por cliente, asientos manuales incluidos#

curl "https://app.facturadirecta.com/api/$COMPANY_ID/query" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "journal",
    "measures": ["net"],
    "dimensions": ["contact"],
    "filters": [{ "field": "account", "op": "startsWith", "value": "7" }],
    "limit": 5
  }'

{
  "meta": { "source": "journal", "basis": "accounting", "period": { "start": "2026-01-01", "end": "2026-12-31" }, "currency": "EUR", "limit": 5, "generatedAt": "2026-10-18T10:00:00.000Z" },
  "columns": [
    { "id": "contact", "kind": "dimension", "title": "Contacto del asiento", "description": "…", "type": "entity" },
    { "id": "net", "kind": "measure", "title": "Importe neto", "description": "…", "type": "money", "measure": "net", "period": { "start": "2026-01-01", "end": "2026-12-31" } }
  ],
  "rows": [
    { "contact": { "id": "<id-contacto>", "name": "Cliente Uno", "webUrl": "https://app.facturadirecta.com/company/<id-empresa>/contacts/<id-contacto>" }, "net": 18400 },
    { "contact": { "id": "unassigned", "name": null }, "net": 300 }
  ],
  "totals": { "net": 48500 },
  "truncated": false
}

Ejemplo: resultado del año mes a mes#

curl "https://app.facturadirecta.com/api/$COMPANY_ID/query" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "journal",
    "measures": ["income", "expenses", "result"],
    "breakdown": "month",
    "limit": 12
  }'

Cada fila lleva la dimensión period con el tramo:

{
  "meta": { "source": "journal", "basis": "accounting", "period": { "start": "2026-01-01", "end": "2026-12-31" }, "breakdown": "month", "currency": "EUR", "limit": 12, "generatedAt": "2026-10-18T10:00:00.000Z" },
  "columns": [
    { "id": "period", "kind": "dimension", "title": "Periodo", "description": "Tramo del desglose por meses: `id`, `start` y `end`.", "type": "period" },
    { "id": "income", "kind": "measure", "title": "Ingresos", "description": "…", "type": "money", "measure": "income", "period": { "start": "2026-01-01", "end": "2026-12-31" } },
    { "id": "expenses", "kind": "measure", "title": "Gastos", "description": "…", "type": "money", "measure": "expenses", "period": { "start": "2026-01-01", "end": "2026-12-31" } },
    { "id": "result", "kind": "measure", "title": "Resultado", "description": "…", "type": "money", "measure": "result", "period": { "start": "2026-01-01", "end": "2026-12-31" } }
  ],
  "rows": [
    { "period": { "id": "2026-01", "start": "2026-01-01", "end": "2026-01-31" }, "income": 8200, "expenses": 5100, "result": 3100 },
    { "period": { "id": "2026-02", "start": "2026-02-01", "end": "2026-02-28" }, "income": 7600, "expenses": 5400, "result": 2200 }
  ],
  "totals": { "income": 91500, "expenses": 60300, "result": 31200 },
  "truncated": false
}

Las filas del desglose van por tramo y, dentro de cada tramo, por el orden pedido. Un tramo sin apuntes no aparece.

Ejemplo: días medios de cobro por cliente#

curl "https://app.facturadirecta.com/api/$COMPANY_ID/query" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "invoices",
    "measures": ["daysToPayment", "daysToPayment.median", "count"],
    "dimensions": ["contact"],
    "orderBy": [{ "field": "daysToPayment", "direction": "desc" }],
    "limit": 10
  }'

{
  "rows": [
    { "contact": { "id": "<id-contacto>", "name": "Cliente Uno", "webUrl": "…" }, "daysToPayment": 41.5, "daysToPayment.median": 38, "count": 14 },
    { "contact": { "id": "<id-contacto-2>", "name": "Cliente Dos", "webUrl": "…" }, "daysToPayment": null, "daysToPayment.median": null, "count": 2 }
  ],
  "totals": { "daysToPayment": 27.3, "daysToPayment.median": 24, "count": 61 }
}

El segundo cliente tiene dos facturas sin cobrar: cuenta en count, pero no en los días, que valen null.

Ejemplo: los productos que más vendes a cada cliente#

Las tres primeras líneas de producto de cada cliente, por unidades, sin las líneas de texto libre:

curl "https://app.facturadirecta.com/api/$COMPANY_ID/query" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "invoiceLines",
    "measures": ["quantity", "totalBeforeTaxes"],
    "dimensions": ["contact", "product"],
    "filters": [{ "field": "hasProduct", "op": "eq", "value": true }],
    "orderBy": [{ "field": "contact", "direction": "asc" }, { "field": "quantity", "direction": "desc" }],
    "limitPerGroup": 3,
    "limit": 100
  }'

{
  "rows": [
    { "contact": { "id": "<id-contacto>", "name": "Cliente Uno", "webUrl": "…" }, "product": { "id": "<id-producto>", "name": "Tornillo M4", "sku": "TOR-M4", "webUrl": "…" }, "quantity": 1200, "totalBeforeTaxes": 240 },
    { "contact": { "id": "<id-contacto>", "name": "Cliente Uno", "webUrl": "…" }, "product": { "id": "<id-producto-2>", "name": "Tuerca M4", "sku": "TUE-M4", "webUrl": "…" }, "quantity": 800, "totalBeforeTaxes": 96 }
  ],
  "totals": { "quantity": 5310, "totalBeforeTaxes": 1874.5 }
}

totals es el de todas las líneas del filtro, no solo el de las filas que deja limitPerGroup.

Qué cifras salen#

• Una consulta sin dimensiones sobre invoices da el mismo recuento y las mismas sumas que el listado de facturas con los mismos filtros, state con todos los estados menos draft y voided, y totals=true, salvo por las sustitutivas (F3), que el listado sí incluye. Lo mismo entre bills y el listado de facturas de compra, que no tiene sustitutivas.
• invoiceLines agrupado por product da las mismas cantidades e importes que el informe «Ventas por producto» de la aplicación, y billLines, que «Compras por producto», salvo que este cuenta también las líneas de las compras anuladas.
• Una factura anulada tiene los importes a cero: pedirla con state solo cambia count y las medidas que dependen de él (average, contacts).
• journal con la dimensión category da las mismas cifras que el resumen de resultados: los apuntes de los grupos 6 y 7 del periodo, sin el asiento de regularización.
• La provincia (contact.region) es la de la dirección actual del contacto. Un cliente que cambió de provincia cuenta en la nueva para todas sus facturas.
• state y agingBucket se calculan a la fecha de hoy en la zona horaria de la empresa, como el listado.
• Las medidas que no se suman (average, contacts y las de días) se calculan en totals sobre todos los documentos, no como media o suma de las filas.

Permisos#

Cada fuente necesita su scope: invoices:read (también para invoiceLines), bills:read (también para billLines), contacts:read o accounting:read. En contacts, la credencial solo ve las facetas (clientes, proveedores, empleados) que su permiso le da.

Planes#

Todos los planes consultan sus datos. Dos grupos de nombres están incluidos en todos los planes de pago y no en el Gratis, igual en la aplicación, en la API y en el MCP:

• Cobros y pagos a fondo: la dimensión agingBucket y las medidas daysToPayment y daysOverdue, en invoices y bills. Sin ellos la consulta responde 403 con code: plan_limit_exceeded y hint.features: ["collectionsAnalytics"].
• Margen: las medidas cost, margin y marginRate de invoiceLines. Sin él, 403 con hint.features: ["marginAnalytics"].

Los nombres siguen en el vocabulario y en las descripciones de describe, así que una aplicación puede anunciar lo que la empresa podría consultar si ampliara su plan. Un administrador de la empresa lo amplía en FacturaDirecta; volver a conectar la aplicación no lo soluciona. La contabilidad (journal) no depende del plan en la API: la decide el scope accounting:read.

Errores comunes#

• 400 Bad Request: una fuente, medida, dimensión o filtro fuera del vocabulario. El mensaje propone el nombre más parecido: «La medida ’totalbefore’ no existe en ‘invoices’: ¿quieres decir ’totalBeforeTaxes’?». Algunos sinónimos también tienen sugerencia: taxId, nif o vat proponen fiscalId. También compare y breakdown a la vez, más de 2 dimensiones, 10 medidas o 10 filtros, un periodo de más de 5 años o de más de 24 tramos, una fecha que no existe, un operador que el filtro no admite, limit fuera de 1 a 500 o limitPerGroup sin dos dimensiones.
• 403 Forbidden (token_scope_missing): la credencial no tiene el scope de la fuente.
• 403 Forbidden (plan_limit_exceeded): la consulta pide cifras de cobros a fondo o de margen que el plan de la empresa no incluye; hint.features dice cuál falta (ver Planes).
• 422 Unprocessable Entity (report_query_timeout): la consulta ha tardado más de 30 segundos. Acota el periodo, las dimensiones o los filtros.

Endpoints#

Scopes#

• accounting:read — Lectura de datos de contabilidad (diario).
• bills:read — Lectura de facturas de compra y tickets.
• contacts:read — Lectura de contactos.
• invoices:read — Lectura de facturas.