Diario contable

El diario contable es la lista cronológica de apuntes (líneas de asiento) generados por todos los documentos contabilizables de la empresa: facturas de venta, facturas de compra, nóminas, asientos manuales, pagos/cobros, modelos de impuestos, amortizaciones, etc.

Cada item del diario es un apunte individual: una línea de un asiento con su cuenta, debe/haber, fecha y referencia al documento que la origina. La API expone una sola operación de lectura paginada: la contabilidad se construye desde los documentos (facturas, nóminas, etc.), no creando apuntes sueltos. Para alterar el diario, hay que crear o modificar el documento de origen.

Estructura de un apunte#

Los campos debit/credit/currency* siguen la convención contable española: positivos en la columna que corresponda; nunca negativos para “contraapuntes”. Para neutralizar un asiento se genera otro con los lados invertidos.

journalPriority: orden de asientos dentro del día#

Los asientos del diario tienen una prioridad numérica entre 1 y 999 que determina su orden dentro de una misma fecha. Los valores que emite FacturaDirecta son:

El filtro journalPriority permite aislar uno de estos tipos (por ejemplo, journalPriority=970 para obtener solo amortizaciones).

Operaciones#

• Lista de apuntes del diario

Lista de apuntes del diario#

GET /{companyId}/journal devuelve la lista de apuntes del diario paginada por la línea individual (no por asiento).

Parámetros de consulta específicos:

• minDate, maxDate — rango por fecha del apunte (YYYY-MM-DD, inclusivos).
• account — cuenta contable. Acepta entre 1 y 6 dígitos:
  • entre 1 y 5 dígitos: prefijo (6 → todos los gastos; 64 → todas las cuentas de personal).
  • 6 dígitos: cuenta completa (700000 → solo apuntes de la cuenta de ventas 700000).
• id — ID del documento que origina los apuntes. Devuelve todas las líneas de ese asiento, factura, gasto, nómina o remesa.
• document — ID del documento que actúa como subcuenta. Filtra los apuntes que afectan al saldo de ese contacto, banco o producto. No equivale a id: un mismo asiento puede tener líneas imputadas a documentos distintos.
• journalPriority — entero. Aísla un tipo concreto de asiento (ver tabla arriba).
• sortBy — solo se acepta date o -date. El orden secundario es siempre por journalPriority, id y line_id (ambos en la misma dirección).
• related — array. Permite añadir datos derivados al item:
  • idAccounting — incluye el asiento contable completo del documento origen en cada apunte. Útil cuando vas a procesar asientos enteros.
  • tags — incluye el array tags (etiquetas del documento origen).
  • currency — incluye los campos currency, currencyDebit y currencyCredit con el contravalor en moneda original. Solo aplica si la empresa tiene multimoneda activo; en caso contrario, los campos se siguen omitiendo aunque pidas related.

Filtros por etiquetas:

Soporta los parámetros estándar allTheseTags, anyOfTheseTags y hasTags (true para documentos con alguna etiqueta y false para documentos sin etiquetas) para filtrar por etiquetas del documento que origina el apunte. Ver [Etiquetas en otros documentos] para la semántica.

Parámetros globales aceptados:

Acepta además los parámetros estándar offset, limit y el header accept-version. Ver Paginación y Autenticación.

Este endpoint no acepta los filtros estándar minCreationDate/minModificationDate (no son apuntes con vida propia: dependen del documento de origen).

Copy as cURL

Saldo de la cuenta 572000 en un rango de fechas:

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/journal?account=572000&minDate=2025-01-01&maxDate=2025-12-31&sortBy=date"

Solo amortizaciones de un año:

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/journal?journalPriority=970&minDate=2025-01-01&maxDate=2025-12-31"

Todos los apuntes que origina un asiento contable:

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/journal?id=tra_3a8f1e29-4d7b-4c5e-9a2f-6d8b1c4e7a5f"

Apuntes que afectan a un contacto, con asiento completo y etiquetas:

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://app.facturadirecta.com/api/$COMPANY_ID/journal?document=con_2e3f4a18-9b7c-4d6a-8e1f-5c2d3b4a7e9f&related=idAccounting&related=tags"

Recomendaciones#

• Lectura por rangos de fecha: el diario crece sin límite. Pagina siempre con minDate/maxDate razonables, no pidas el diario entero. Para exportaciones, itera mes a mes o trimestre a trimestre.
• Para ingresos, gastos y beneficio: usa el resumen de resultados, que da los totales ya calculados con las mismas reglas que la web. No los reconstruyas sumando apuntes: una suma propia puede incluir el asiento de regularización y no coincidir con lo que ve el usuario.
• Para el saldo de una cuenta concreta: usa account=<6 dígitos> y suma debit - credit (o credit - debit según el tipo de cuenta) en el cliente.
• Para recuperar un asiento completo: filtra por id. No filtres por document, porque ese parámetro selecciona las líneas imputadas a una subcuenta y puede dejar fuera otros apuntes del mismo asiento.
• Para vincular con documentos: el id del apunte es el ID del documento origen. Puedes pedir su detalle con la operación de lectura del recurso correspondiente (invoices, bills, payrolls, etc.).
• related=idAccounting es caro: solo pídelo si vas a procesar asientos completos. Si solo necesitas apuntes individuales, no lo uses.
• Multimoneda: si tu empresa no tiene multimoneda activado, no uses related=currency (no devuelve nada). Si lo tiene, los campos currencyDebit/currencyCredit son útiles para informes en la moneda original del movimiento.

Errores comunes#

• 400 — minDate o maxDate es una fecha que no existe, como 2026-02-30. Ver Fechas que no existen.
• 400 ValidationError (code: "invalidParams") — valor incorrecto para sortBy. Solo se acepta date o -date.
• 400 ValidationError — account con formato distinto a 1-6 dígitos.
• 403 Forbidden — falta el scope accounting:read.

Ver Errores y validaciones para el formato general.

Referencia exhaustiva#

Esta página cubre los matices funcionales y los casos típicos. Para el contrato completo del item (incluyendo el schema Accounting devuelto por related=idAccounting), consulta el Swagger UI o el openapi crudo.

Endpoints#

Scopes#

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