API contable del core

La API contable vive en el core bajo /api/v1/ext/gl y se publica hacia afuera por el gateway de API bajo /v1. Esta página usa las rutas del gateway, que son las que usa un sistema externo, y anota la del core cuando difieren.

Estado honesto

Toda la API contable está desplegada en el core y en el gateway del banco piloto. Las lecturas responden. Las escrituras dependen de la parametría que define el contador: en el piloto no existe todavía el concepto de asientos manuales (un POST de asiento responde 422 manual-concept-unavailable), la credencial del gateway no tiene gl:write, hay 0 canales de transacción y 0 reglas inter-sucursal, y la revaluación cambiaria no tiene reglas (su paso del cierre está apagado). «Implementado» aquí significa «en operación en el entorno de demostración», nunca «con bancos reales».

Resumen

Método y ruta en el gateway	En el core	Alcance	Qué hace
GET /v1/glaccounts	GET /api/v1/ext/gl/accounts	gl:read	Lista el plan de cuentas
GET /v1/glaccounts/{glCode}	GET …/accounts/{glCode}	gl:read	Una cuenta, con su saldo si se pide
GET /v1/transactionchannels	GET …/transaction-channels	gl:read	Canales con su cuenta del mayor
POST /v1/gljournalentries	POST …/journal-entries	gl:write	Postea un asiento manual
POST /v1/gljournalentries:search	POST …/journal-entries:search	gl:read	Busca líneas del mayor
GET /v1/gljournalentries/{voucher}	GET …/journal-entries/{voucher}	gl:read	Un asiento por comprobante
POST /v1/gljournalentries/{voucher}:reverse	POST …/journal-entries/{voucher}:reverse	gl:write	Reversa un asiento de esta API
GET /v1/gltrialbalance	GET …/trial-balance	gl:read	Balance de comprobación
POST /v1/accounting/reports	POST …/reports	gl:read	Encola un reporte contable
GET /v1/accounting/reports/{reportKey}	GET …/reports/{reportKey}	gl:read	Estado y resultado del reporte
No expuesta en /v1	POST …/fx-revaluations:preview, POST …/fx-revaluations, GET …/fx-revaluations	gl:read / gl:write	Revaluación cambiaria

En el core, gl:write es un alcance crítico: una credencial con acceso general no lo tiene si no se le da de forma expresa. Toda escritura exige Idempotency-Key. Un interruptor del core apaga la API completa: entonces toda ruta responde 404 gl-api-disabled (en el gateway, CORE_GL_API_DISABLED).

Paginación. offset (0) y limit (50, hasta 1000). El cuerpo es un arreglo; las cabeceras Items-Total, Items-Offset e Items-Limit describen la página (en el gateway, con paginationDetails=ON).

Operaciones que no existen a propósito. POST /v1/glaccounts (el plan de cuentas se administra en la consola), PATCH y DELETE /v1/gljournalentries/{voucher} (un asiento contabilizado se reversa): las tres responden 501 CORE_NO_SOPORTA con la alternativa.

Plan de cuentas

GET /v1/glaccounts

Parámetro	Valores
type	ASSET, LIABILITY, EQUITY, INCOME, EXPENSE
postable	true o false
currency	ISO 4217 de tres letras
detailsLevel	BASIC (defecto) o FULL
offset, limit	Paginación

GET /v1/glaccounts/{glCode}

balanceDate (yyyy-MM-dd) o detailsLevel=FULL agregan el saldo. Sin balanceDate, a la fecha operativa.

Campo	Qué es
glCode, name	Código y nombre de la cuenta
type	Clase: ASSET, LIABILITY, EQUITY, INCOME o EXPENSE
nature	D deudora o C acreedora
postable, usage	DETAIL (postable, recibe asientos) o HEADER (sumaria, agrupa)
allowManualJournalEntries	Si esta API acepta asientos manuales contra la cuenta
active	Si su ciclo de vida está activo
currency	Su moneda; null = multimoneda
cia	Compañía
parentCode, level, lifecycleState	Solo con FULL
balance.asOf, balance.byCurrency[]	Por moneda: debits, credits y balance acumulados hasta asOf, con signo por naturaleza (positivo = saldo normal). Incluye las líneas pendientes del cierre del día

GET /v1/transactionchannels

Canales con code, name, description, glCode (su cuenta del mayor), currency (null = cualquiera), usage (CASH, TRANSFER, CARD, MOBILE, INTERNAL) y active. Una línea de asiento con useChannel: true usa la cuenta del canal en lugar de un glCode.

Asientos manuales

POST /v1/gljournalentries

{
  "date": "2026-09-19",
  "currency": "VES",
  "branchCode": "AG-001",
  "notes": "Cobro de comisión por servicio",
  "transactionId": "erp-000123",
  "channelCode": "CAJA",
  "debits":  [ { "useChannel": true, "amount": "116.00" } ],
  "credits": [ { "glCode": "5110110001", "amount": "100.00" },
               { "glCode": "2810110001", "amount": "16.00", "branchCode": "AG-002" } ]
}

Campo	Obligatorio	Regla
currency	sí	Coherente con cada cuenta y con el canal
date	no	Sin ella, la fecha operativa. No puede ser posterior a la fecha operativa ni caer en un día cerrado
branchCode	no	Agencia principal del asiento
notes	no	Glosa
transactionId	no	Tu referencia de origen; se puede buscar
channelCode	no	Canal para las líneas con useChannel
debits[], credits[]	sí	Al menos una línea por lado. Suma de débitos = suma de créditos, mayor que cero
línea glCode o useChannel	sí	Cuenta postable, activa, de la compañía y con asientos manuales permitidos
línea amount	sí	Mayor que cero
línea branchCode	no	Otra agencia para esa línea. Si el asiento mezcla agencias, el core agrega solo las piernas inter-sucursal según la regla del par de agencias; sin regla, 422 interbranch-rule-missing

Respuesta 201 (o 200 si es una repetición con la misma clave):

Campo	Qué es
voucher	Comprobante, con la forma GL-<fecha>-<sufijo>
date, currency, branchCode, notes, transactionId	Los del asiento
status	DRAFT (en el mayor, pendiente del cierre), POSTED, REVERSED o MIXED
reversalOf, reversedBy	El original que anula o el reverso que lo anula
entries[]	entryId, glCode, glName, type (DEBIT/CREDIT), amount, currency, branchCode, reversalEntryKey

La base de datos vuelve a comprobar el cuadre y la fecha al guardar: ver Partida doble garantizada por la base de datos.

POST /v1/gljournalentries:search

Devuelve líneas del mayor (no asientos), con entryId, voucher, bookingDate, glCode, glName, type, amount, currency, transactionId, branchCode, notes, status, createdBy y createdDate.

{
  "filterCriteria": [
    { "field": "bookingDate", "operator": "BETWEEN", "value": "2026-09-01", "secondValue": "2026-09-30" },
    { "field": "glCode",      "operator": "STARTS_WITH", "value": "1101" },
    { "field": "amount",      "operator": "MORE_THAN",   "value": "1000" }
  ],
  "sortingCriteria": { "field": "bookingDate", "order": "DESC" }
}

Elemento	Valores
Campos de filterCriteria	bookingDate, creationDate, glCode, voucher, type, amount, transactionId, branchCode
Operadores	EQUALS, IN (con values: [...]), BETWEEN (con value y secondValue), MORE_THAN, LESS_THAN, STARTS_WITH
Combinación	Todos los criterios con Y
Rango obligatorio	Un BETWEEN de hasta 366 días. El core lo acepta sobre bookingDate o creationDate; el gateway exige que sea sobre bookingDate
sortingCriteria.field	bookingDate, creationDate, glCode, voucher, type, amount, transactionId
sortingCriteria.order	ASC o DESC

GET /v1/gljournalentries/{voucher}

El asiento completo, con su estado y la relación con su reverso.

POST /v1/gljournalentries/{voucher}:reverse

Cuerpo opcional { "notes": "…" }. Postea en la fecha operativa un contra-asiento espejo (débito por crédito, mismas cuentas e importes) con comprobante REV-<voucher>. Solo para asientos creados por esta API. Responde 201, o 200 si es una repetición con la misma clave; uno ya reversado responde 409.

Balance de comprobación

GET /v1/gltrialbalance?from&to&currency

from y to son obligatorios (yyyy-MM-dd, ambos inclusive). Solo cuenta las líneas ya contabilizadas por el cierre del día: un asiento de hoy no aparece hasta que cierre.

Campo	Qué es
from, to, currency	El rango pedido
balanced	true si todas las monedas cuadran
lines[]	glCode, name, currency, openingBalance, debits, credits, closingBalance
checks[]	Por moneda: accounts, opening, debits, credits, closing y balanced

Reportes contables asíncronos

Para rangos largos o planes grandes, pide el cálculo y vuelve por él.

sequenceDiagram
  participant S as Tu sistema
  participant G as Gateway
  S->>G: POST /v1/accounting/reports {startDate, endDate, …}
  G-->>S: 202 {reportKey, status: QUEUED} + Location
  loop hasta COMPLETE o ERROR
    S->>G: GET /v1/accounting/reports/{reportKey}
    G-->>S: QUEUED · IN_PROGRESS · COMPLETE · ERROR
  end

POST /v1/accounting/reports es lectura (alcance gl:read) y no lleva Idempotency-Key:

Campo	Obligatorio	Regla
startDate, endDate	sí	yyyy-MM-dd, ambos inclusive, hasta 366 días
branchCode	no	Una agencia
currencyCode	no	Una moneda
glTypes	no	Clases de cuenta, p. ej. ["ASSET","LIABILITY"]

Responde 202 con reportKey (32 caracteres hexadecimales), status: QUEUED y la cabecera Location: /v1/accounting/reports/{reportKey}. El GET trae status, las fechas de creación y fin, error (solo en ERROR) e items (solo en COMPLETE): glCode, name, type, currency, openingBalance, debits, credits, netChange y closingBalance. netChange lleva signo (por naturaleza de la cuenta), no es un valor absoluto. El saldo es el mismo que el de las cuentas de esta API: todas las líneas del mayor.

Revaluación cambiaria

Por ahora solo en la API del core (/api/v1/ext/gl), no en /v1. Recalcula a la tasa de cierre el valor en moneda funcional de los saldos en moneda extranjera, según las reglas de revaluación que define el contador.

Ruta en el core	Alcance	Qué hace
POST /fx-revaluations:preview {date, cia}	gl:read	Por regla activa: saldo en moneda extranjera, valor en libros a la tasa histórica, valor a la tasa de cierre y diferencia. No escribe nada
POST /fx-revaluations {date, cia} + Idempotency-Key	gl:write	Postea por regla el asiento FXREV-<fecha>-<regla> y su reverso FXREV-R-<fecha>-<regla> en la fecha operativa siguiente. Idempotente por fecha y regla
GET /fx-revaluations?date&cia	gl:read	Las revaluaciones registradas (POSTED o NO_DIFFERENCE) con su detalle

Errores

Del core, con su tipo. A través del gateway llegan como CORE_<TIPO> en mayúsculas y con guion bajo (unbalanced-entry → CORE_UNBALANCED_ENTRY), con el mismo estado. Los del propio gateway están en Códigos de error del gateway de API.

Estado	Tipo	Cuándo
400	validation-error	Falta un campo o tiene un formato inválido
400	invalid-account-type, invalid-details-level, invalid-pagination	Filtro de cuentas, detailsLevel o paginación fuera de rango
400	date-range-required, date-range-too-wide	Búsqueda sin BETWEEN de fechas, o de más de 366 días
400	invalid-filter-criteria, invalid-filter-field, invalid-filter-operator	Un criterio mal formado, un campo o un operador fuera de la lista
400	invalid-sorting-field, invalid-sorting-order	Ordenamiento no admitido
400	invalid-trial-balance-range, invalid-report-range	Rango del balance o del reporte ausente, invertido o demasiado ancho
404	gl-account-not-found, journal-entry-not-found, report-not-found	No existe
404	gl-api-disabled, gl-reports-disabled	La API o los reportes están apagados en ese core
409	journal-entry-already-reversed	El asiento ya tiene su reverso
409	idempotency-key-reused	Misma clave con otra petición (directo al core; el gateway lo detecta antes)
422	unbalanced-entry	Débitos ≠ créditos, o un lado vacío
422	gl-account-not-postable, gl-account-inactive, gl-account-other-company, gl-account-manual-entries-not-allowed	La cuenta no admite el asiento
422	currency-mismatch	Moneda distinta de la de la cuenta o del canal
422	transaction-channel-inactive	El canal está inactivo
422	branch-not-found	La agencia no existe
422	future-booking-date, period-closed	Fecha posterior a la operativa o de un día cerrado
422	interbranch-disabled, interbranch-rule-missing	Asiento con varias agencias sin la función encendida o sin regla para el par
422	manual-concept-unavailable	La institución no tiene el concepto de asientos manuales
422	journal-entry-not-reversible	El asiento no fue creado por esta API
422	fx-revaluation-no-rules, fx-revaluation-missing-rate, fx-revaluation-missing-historical-rate, fx-revaluation-concept-unavailable	Revaluación sin reglas, sin tasa de cierre o histórica, o sin su concepto

Para seguir

• Tu primera llamada a la API del core
• Consultar el plan de cuentas y sus saldos, lo mismo desde la consola.