Configuración contable como código

Cuando la parametría contable vive solo en pantallas, nadie sabe quién cambió qué ni cómo dejar el sandbox igual a producción. Con la configuración como código, esa parametría es un documento YAML: se exporta, se revisa en un repositorio, se prueba sin escribir y se aplica de una vez.

Estado honesto

La exportación (GET) está activa en el core del banco piloto. La aplicación (PUT) exige el alcance config:write, que hoy no tiene ninguna credencial: es una decisión del banco, no una falta del software. En el piloto hay 0 canales de transacción y la parametría contable la define el contador; esta guía es para cuando la tenga.

Qué cubre el documento

apiVersion: finora.config/v1
kind: AccountingConfiguration
cia: "001"
transactionChannels:
  - code: CAJA
    name: Caja de agencias
    glAccount: "1101010001"
    currency: VES          # vacío = cualquier moneda
    usage: CASH            # CASH, TRANSFER, CARD, MOBILE o INTERNAL
    active: true
productAccountingRules:
  - product: CRED-PER
    rules:
      - role: PRINCIPAL    # el rol contable, por nombre o por código
        glAccount: "1310100001"
licenseModules: [...]      # solo lectura

Sección	Qué es	Al aplicar
transactionChannels	Los canales con su cuenta del mayor	Se crean, cambian o desactivan
productAccountingRules	Por producto, qué cuenta usa cada rol contable	Se crean, cambian o desactivan
licenseModules	El catálogo de módulos de licencia	Nunca se aplica: si difiere, solo avisa. Los módulos se habilitan con su llave de licencia

Las cuentas son las del plan del Banco Demo; usa las de tu plan.

Las reglas que te protegen

• Solo se toca lo que nombras. Una sección que no está en el documento no se toca. Un producto que no aparece en productAccountingRules no se toca.
• Nada se borra. Lo que existe y falta en el documento solo se desactiva, y solo si lo pides con allowDeletes=true. Sin él, recibes un aviso y sigue igual.
• dryRun está encendido por defecto. Un PUT sin parámetros no escribe nada: calcula el plan. Para aplicar hay que pedir dryRun=false de forma expresa.
• Todo o nada. Si un cambio falla al aplicarse, no queda ninguno.
• El ensayo es real. dryRun ejecuta los cambios dentro de una transacción que se revierte, así que también detecta lo que solo aparece al guardar (una cuenta no postable en un canal, un producto que no está aprobado).

flowchart LR
  A["GET accounting.yaml"] --> B["Editar en el repositorio<br/>revisión a cuatro ojos"]
  B --> C["PUT dryRun (por defecto)"]
  C -->|"errores"| B
  C -->|"plan correcto"| D["PUT dryRun=false"]
  D --> E["Cambios confirmados<br/>en una transacción"]

Los pasos

1. Exporta la configuración vigente (alcance config:read):

   curl -s "$GW/v1/configuration/accounting.yaml" -H "Authorization: Bearer $TOKEN" -o accounting.yaml

   Llega en application/yaml. Guárdalo en tu repositorio: es la línea base.

2. Edita el archivo y pide la revisión de otra persona antes de aplicarlo, como con cualquier cambio de código.

3. Ensaya el cambio (alcance config:write). Sin dryRun, no escribe:

   curl -s -X PUT "$GW/v1/configuration/accounting.yaml" -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/yaml" --data-binary @accounting.yaml | jq

   Verás el plan:

   {
     "dryRun": true,
     "applied": false,
     "allowDeletes": false,
     "summary": { "create": 1, "update": 0, "deactivate": 0, "unchanged": 4 },
     "changes": [
       { "section": "transactionChannels", "key": "CAJA", "action": "CREATE",
         "fields": [ { "field": "glAccount", "from": null, "to": "1101010001" } ] }
     ],
     "warnings": [],
     "errors": []
   }

   Lee changes uno por uno. Si errors no está vacío, la respuesta es 422 con este mismo informe y no se aplicó nada: corrige y repite. Un YAML ilegible responde 400 CORE_INVALID_YAML.

4. Aplica cuando el plan sea exactamente lo que esperas:

   curl -s -X PUT "$GW/v1/configuration/accounting.yaml?dryRun=false" -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/yaml" --data-binary @accounting.yaml | jq '.applied, .summary'

   applied: true confirma que los cambios quedaron.

5. Vuelve a exportar y compara con tu archivo: deben coincidir. Haz commit del resultado.

Desactivar lo que ya no está

Si quitaste un canal del documento y quieres que el core lo desactive, agrega allowDeletes=true:

curl -s -X PUT "$GW/v1/configuration/accounting.yaml?allowDeletes=true" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/yaml" --data-binary @accounting.yaml | jq '.changes[] | select(.action == "DEACTIVATE")'

Ensáyalo primero (sin dryRun=false) y revisa cada DEACTIVATE. Un canal desactivado no se borra: su historia sigue en el core.

Si algo falla

Lo que ves	Por qué	Qué hacer
415 GW_TIPO_NO_SOPORTADO	Content-Type no es YAML	Usa application/yaml
413 YAML_DEMASIADO_GRANDE	El documento supera 2 MiB	Divídelo: aplica una sección por vez
403 GW_ALCANCE_INSUFICIENTE	Tu credencial no tiene config:write	Lo decide el banco
422 con errors	Una cuenta, producto o rol no existe o no es válido	Corrige según el mensaje
Un aviso «allowDeletes=false»	Algo existe y no está en tu documento	Agrégalo, o usa allowDeletes=true si de verdad quieres desactivarlo

Para seguir

• Ciclo de vida de un concepto contable: qué es una regla contable y por qué un rol apunta a una cuenta.
• El gateway de API del core.