Informes

Los informes devuelven, ya calculadas, las mismas cifras que los informes de la web. Son de solo lectura y se generan en el momento a partir de la contabilidad de la empresa.

El resumen de resultados responde a «cuánto he facturado, cuánto he gastado y cuánto he ganado» en un periodo, separando cada importe por su origen: facturas, gastos, nóminas, amortizaciones, diferencias de cambio y otros. Está disponible en todos los planes y da las mismas cifras que las tarjetas de Ingresos, Gastos y Beneficio del panel.

Para ver qué documentos componen una cifra, el detalle del resumen lista los documentos de una categoría con el importe que aporta cada uno.

Los informes contables (pérdidas y ganancias, balance de situación y sumas y saldos) siguen el modelo oficial del Plan General Contable y necesitan el módulo de Contabilidad, como en la web.

Para totales usa estos informes y no sumes apuntes del diario: los informes aplican las mismas reglas que la web (por ejemplo, excluyen el asiento de regularización), y una suma propia puede no coincidir con lo que ve el usuario.

Para rankings, totales y comparativas a medida (los cinco mejores clientes, el gasto por proveedor, las provincias que más facturan frente al año pasado) usa la consulta analítica: agrupa facturas, compras, contactos o apuntes por la dimensión que elijas, con las mismas cifras que los listados.

Estructura del resumen de resultados#

La respuesta tiene meta y rows:

Cada fila de rows:

Las filas aparecen en este orden: categorías de ingresos, total de ingresos, categorías de gastos, total de gastos y beneficio. Una categoría solo aparece si tiene importe en alguna columna; los tres totales aparecen siempre.

Los importes son positivos cuando suman a su lado: un ingreso de 100 € vale 100 en ingresos y un gasto de 40 € vale 40 en gastos. El beneficio es el total de ingresos menos el total de gastos.

Columnas#

Cada columna de meta.columns tiene un id, que es la clave de values en cada fila, y un kind:

Sin opciones de comparativa hay una sola columna, current. Con compare las columnas son current y reference, más difference y variance si se piden. Con breakdown son p0, p1… por orden de fechas, más total si se pide.

Qué importes entran#

El resumen suma los apuntes de las cuentas de los grupos 6 (gastos) y 7 (ingresos) del periodo, sin el asiento de regularización de fin de año. Por eso coincide con sumas y saldos de esos grupos y con el resultado de pérdidas y ganancias excluyendo la regularización.

Cada importe va a una categoría:

1. Las cuentas de diferencias de cambio de la configuración contable (768000 y 668000 por defecto) van a currencyGains y currencyLosses, sea cual sea el documento que las genera.
2. El resto se reparte por el documento que genera el asiento: las facturas de venta en invoices, los gastos en bills y las nóminas en payrolls.
3. Lo que queda del grupo 68 va a depreciation.
4. Todo lo demás va a otherIncome u otherExpenses.

Estructura de los informes contables#

Pérdidas y ganancias y el balance de situación tienen meta, rows y diagnostics. meta añade a lo del resumen:

Cada fila de rows:

Una fila cuyas columnas son todas cero no aparece, igual que en la web. En el balance, cada columna es de tipo balanceAt: el saldo acumulado a su date. Con revenueShare, pérdidas y ganancias añade columnas shareOfRow con el peso de cada fila sobre el importe neto de la cifra de negocios.

Cada aviso de diagnostics tiene code, severity (info o warning), message en el idioma de la petición y, según el caso, years o accounts. Son los mismos avisos que muestra la web, por ejemplo un ejercicio anterior sin regularizar (previousYearNotClosed) o cuentas con saldo fuera del modelo (unmappedBalances).

Sumas y saldos tiene meta, rows, totals y pagination. Cada fila es un subtotal (group, con accountPrefix), una cuenta (account) o un tercero de una cuenta (thirdParty), con sus importes en amounts: previousBalance, debit, credit y balance. totals es el total del informe completo, no solo de la página.

Operaciones#

• Obtener el resumen de resultados
• Listar los documentos de una categoría
• Obtener pérdidas y ganancias
• Obtener el balance de situación
• Obtener sumas y saldos

Obtener el resumen de resultados#

GET /{companyId}/reports/resultsSummary

compare y breakdown no se combinan. difference y variance necesitan compare, y total necesita breakdown. Cualquier combinación no válida responde 400.

Ejemplo: ingresos, gastos y beneficio del año comparados con el anterior#

curl "https://app.facturadirecta.com/api/$COMPANY_ID/reports/resultsSummary?startDate=2025-01-01&endDate=2025-12-31&compare=previousYear&difference=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "meta": {
    "report": "resultsSummary",
    "currency": "EUR",
    "columns": [
      { "id": "current", "kind": "movement", "start": "2025-01-01", "end": "2025-12-31" },
      { "id": "reference", "kind": "movement", "start": "2024-01-01", "end": "2024-12-31" },
      { "id": "difference", "kind": "difference", "current": "current", "reference": "reference" }
    ],
    "generatedAt": "2025-12-31T10:00:00.000Z"
  },
  "rows": [
    { "id": "invoices", "kind": "category", "side": "income", "title": "Ventas facturadas", "values": { "current": 98000, "reference": 91500, "difference": 6500 } },
    { "id": "currencyGains", "kind": "category", "side": "income", "title": "Diferencias de cambio a favor", "values": { "current": 1200, "reference": 0, "difference": 1200 } },
    { "id": "income", "kind": "total", "title": "Total ingresos", "values": { "current": 99200, "reference": 91500, "difference": 7700 } },
    { "id": "bills", "kind": "category", "side": "expenses", "title": "Compras y gastos", "values": { "current": 41500, "reference": 39000, "difference": 2500 } },
    { "id": "payrolls", "kind": "category", "side": "expenses", "title": "Nóminas", "values": { "current": 22000, "reference": 21000, "difference": 1000 } },
    { "id": "expenses", "kind": "total", "title": "Total gastos", "values": { "current": 63500, "reference": 60000, "difference": 3500 } },
    { "id": "profit", "kind": "total", "title": "Beneficio", "values": { "current": 35700, "reference": 31500, "difference": 4200 } }
  ]
}

Ejemplo: evolución mensual#

curl "https://app.facturadirecta.com/api/$COMPANY_ID/reports/resultsSummary?startDate=2025-01-01&endDate=2025-12-31&breakdown=month&total=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Devuelve las columnas p0 (enero) a p11 (diciembre) y total.

Listar los documentos de una categoría#

GET /{companyId}/reports/resultsDetail

Con la categoría y las fechas de una columna del resumen, la suma de amount de todas las páginas es el importe de esa celda.

La respuesta tiene meta (con category, side y period), items y pagination. Cada elemento de items:

Los documentos van de más antiguo a más reciente. Con el id puedes abrir el documento en su recurso, por ejemplo GET /{companyId}/invoices/{id}.

Ejemplo#

curl "https://app.facturadirecta.com/api/$COMPANY_ID/reports/resultsDetail?category=currencyGains&startDate=2025-01-01&endDate=2025-12-31" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "meta": {
    "report": "resultsDetail",
    "currency": "EUR",
    "category": "currencyGains",
    "side": "income",
    "period": { "start": "2025-01-01", "end": "2025-12-31" },
    "generatedAt": "2025-12-31T10:00:00.000Z"
  },
  "items": [
    { "id": "<id-cobro>", "type": "transaction", "title": "Cobro en dólares", "date": "2025-04-01", "amount": 1200 }
  ],
  "pagination": { "limit": 25, "offset": 0, "total": 1 }
}

Obtener pérdidas y ganancias#

GET /{companyId}/reports/profitLoss

Ejemplo#

curl "https://app.facturadirecta.com/api/$COMPANY_ID/reports/profitLoss?startDate=2025-01-01&endDate=2025-12-31&detail=summary&compare=previousYear" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "meta": {
    "report": "profitLoss",
    "template": { "id": "profitLoss", "variant": "pyme", "version": 1 },
    "currency": "EUR",
    "detail": "summary",
    "policies": { "includeClosure": false, "excludeRevenueClearing": false },
    "columns": [
      { "id": "current", "kind": "movement", "start": "2025-01-01", "end": "2025-12-31" },
      { "id": "reference", "kind": "movement", "start": "2024-01-01", "end": "2024-12-31" }
    ],
    "generatedAt": "2025-12-31T10:00:00.000Z"
  },
  "rows": [
    { "id": "A_1", "parentId": "A", "kind": "accounts", "level": 2, "title": "1. Importe neto de la cifra de negocios", "values": { "current": 98000, "reference": 91500 } },
    { "id": "A_4", "parentId": "A", "kind": "accounts", "level": 2, "title": "4. Aprovisionamientos", "values": { "current": -41500, "reference": -39000 } },
    { "id": "A", "parentId": "C", "kind": "sum", "level": 1, "title": "A) RESULTADO DE EXPLOTACIÓN ( 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 )", "values": { "current": 56500, "reference": 52500 } },
    { "id": "D", "kind": "sum", "level": 1, "title": "D) RESULTADO DEL EJERCICIO (C + 17)", "values": { "current": 56500, "reference": 52500 } }
  ],
  "diagnostics": []
}

Los gastos aparecen en negativo, con el signo de presentación del modelo oficial.

Obtener el balance de situación#

GET /{companyId}/reports/balanceSheet

El saldo de cada columna suma todos los apuntes hasta su fecha. El resultado del ejercicio se calcula desde la cuenta de pérdidas y ganancias, aunque el año no esté regularizado. Si el activo no coincide con el patrimonio neto y el pasivo, aparece la fila imbalance con la diferencia y el aviso imbalance.

Con detail=full el informe resuelve el tercero de todos los documentos de la historia, y en empresas con mucho volumen puede tardar varios segundos.

Obtener sumas y saldos#

GET /{companyId}/reports/trialBalance

Para el saldo contable de un banco no hace falta este informe: GET /{companyId}/banks/{id}?related=balance lo da con el mismo criterio (y con balanceDate, a una fecha), en todos los planes y con el scope banks:read. Ver Bancos.

thirdPartyDetail necesita thirdParty porque el detalle por tercero de una cuenta entera, como la de clientes, puede tardar decenas de segundos en empresas con miles de clientes.

Ejemplo: saldo de un cliente#

curl "https://app.facturadirecta.com/api/$COMPANY_ID/reports/trialBalance?startDate=2025-01-01&endDate=2025-12-31&account=430&thirdParty=<id-contacto>&thirdPartyDetail=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "meta": {
    "report": "trialBalance",
    "currency": "EUR",
    "period": { "start": "2025-01-01", "end": "2025-12-31" },
    "groups": [],
    "thirdPartyDetail": true,
    "policies": { "includeClosure": false, "excludeRevenueClearing": false },
    "generatedAt": "2025-12-31T10:00:00.000Z"
  },
  "rows": [
    { "id": "430000", "kind": "account", "level": 0, "title": "430000 Clientes", "account": "430000", "accountTitle": "Clientes", "amounts": { "previousBalance": 0, "debit": 1210, "credit": 0, "balance": 1210 } },
    { "id": "430000/<id-contacto>", "kind": "thirdParty", "level": 1, "title": "Cliente Uno", "account": "430000", "accountTitle": "Clientes", "thirdParty": { "id": "<id-contacto>", "type": "contact", "name": "Cliente Uno" }, "amounts": { "previousBalance": 0, "debit": 1210, "credit": 0, "balance": 1210 } }
  ],
  "totals": { "previousBalance": 0, "debit": 1210, "credit": 0, "balance": 1210 },
  "pagination": { "limit": 25, "offset": 0, "total": 2 }
}

Permisos#

Todas las operaciones necesitan el scope accounting:read, el mismo que el diario: los informes muestran el beneficio y el gasto en nóminas de la empresa.

Pérdidas y ganancias, el balance de situación y sumas y saldos necesitan además el módulo de Contabilidad. Sin él responden 403 con plan_limit_exceeded y hint.features: ["fullAccounting"], sin enviar ningún aviso a los administradores (ver Errores). Una aplicación conectada puede saber de antemano si una empresa lo tiene con accountingModule en el perfil.

Errores comunes#

• 400 Bad Request: fechas no válidas, también las que no existen como 2026-02-30 (nunca se sustituyen por el periodo por defecto), startDate posterior a la fecha final, un periodo de más de 5 años, compare y breakdown a la vez, difference, variance o total sin la opción que necesitan, más de 24 columnas o thirdPartyDetail sin thirdParty.
• 403 Forbidden: la credencial no tiene el scope accounting:read, o la empresa no tiene el módulo de Contabilidad (plan_limit_exceeded).
• 422 Unprocessable Entity (report_query_timeout): el informe ha tardado demasiado. Acota el periodo, el nivel de detalle o las columnas.

Endpoints#

Scopes#

• accounting:read — Lectura de datos de contabilidad (diario).