Pedir un reporte contable asíncrono

El reporte asíncrono te da, por cada cuenta, saldo inicial, débitos, créditos, neto y saldo final de un período. Como puede tardar, no se espera: se pide, se recibe una clave y se recoge después. Aprenderás a hacerlo. El porqué está en Reportes contables asíncronos.

Antes de empezar

• Hoy el reporte se pide por la API contable: no tiene pantalla en la consola. Lo normal es que lo pida un sistema (tesorería, un tablero, la herramienta del auditor); esta guía te sirve para entender qué pide y para probarlo.
• Necesitas una clave de API con el alcance de lectura contable (gl:read), que entrega el administrador del core. Nunca la pegues en un correo ni en un documento.
• El detalle de cada campo y de cada error está en la referencia de la API contable.

Estado honesto

Los reportes asíncronos están desplegados y activos en el core piloto. Esta guía no tiene capturas porque no hay pantalla; los pasos se recorrieron contra un core local con datos ficticios.

Paso a paso

1. Pide el reporte. Indica el período (obligatorio, hasta 366 días), y si quieres, la sucursal, la moneda y los tipos de cuenta (ASSET, LIABILITY, EQUITY, INCOME, EXPENSE):

   curl -s -X POST "https://<su-core>/api/v1/ext/gl/reports" \
     -H "X-Api-Key: <su-clave>" -H "Content-Type: application/json" \
     -d '{"startDate":"2026-10-01","endDate":"2026-10-19","currencyCode":"VES","glTypes":["ASSET","LIABILITY"]}'

   El core responde 202 con la clave y el estado QUEUED:

   {"reportKey":"fa04dfcf15ac4cd0be4685227a1034da","status":"QUEUED","startDate":"2026-10-01","endDate":"2026-10-19",
    "currencyCode":"VES","glTypes":["ASSET","LIABILITY"]}

2. Recoge el resultado con la clave. Mientras diga QUEUED o IN_PROGRESS, vuelve a consultar en unos segundos:

   curl -s "https://<su-core>/api/v1/ext/gl/reports/<clave-del-reporte>" -H "X-Api-Key: <su-clave>"

3. Lee las filas cuando el estado sea COMPLETE:

   {"status":"COMPLETE","items":[
     {"glCode":"111.01.01.02","name":"Gestión de efectivo","type":"ASSET","currency":"VES",
      "openingBalance":0,"debits":944135.39,"credits":363901,"netChange":580234.39,"closingBalance":580234.39}]}

   Comprueba siempre que saldo final = saldo inicial + neto.

stateDiagram-v2
  [*] --> QUEUED: POST reports (202)
  QUEUED --> IN_PROGRESS: el ejecutor lo toma
  IN_PROGRESS --> COMPLETE: filas listas
  IN_PROGRESS --> ERROR: falló o se reinició el core
  COMPLETE --> [*]
  ERROR --> [*]: pídelo de nuevo

Si algo sale mal

Lo que ves	Por qué	Qué hacer
400 date-range-too-wide	El período pasa de 366 días	Divídelo en tramos
400 invalid-report-range	El fin es anterior al inicio	Corrige las fechas
400 invalid-account-type	Un tipo de cuenta no está en la lista	Usa ASSET, LIABILITY, EQUITY, INCOME o EXPENSE
422 branch-not-found	La sucursal no existe	Revisa el código de la sucursal
404 report-not-found	La clave no existe	Copia la clave tal como la devolvió el 202
Estado ERROR	El cálculo superó su tiempo máximo o el core se reinició durante el cálculo	Pídelo de nuevo, con un período más corto si es muy largo
El saldo no coincide con el balance de comprobación	El reporte incluye las líneas del día que el cierre todavía no contabilizó	Compáralos después del cierre

Qué sigue

• Reportes contables asíncronos
• Consultar el plan de cuentas y sus saldos

Cómo se verificó esta guía

Los tres pasos se recorrieron contra un core local construido desde el mismo código que corre en el core piloto, con datos ficticios: el 202, la consulta y las filas de ejemplo salen de esa corrida.