Audit Trail - Clevis Payroll API

Every calculation includes an audit trail — a step-by-step record of how each value was computed. Required for legal compliance in most Latin American countries.

Enabling the audit trail

The audit trail is included by default. To disable it (useful for high-frequency batch runs where you only need the summary):

{
  "options": {
    "include_audit_trail": false
  }
}

Structure

Each step in the audit trail records exactly how a value was calculated:

{
  "audit_trail": [
    {
      "step": 1,
      "concept_id": "sueldo",
      "label": "Sueldo mensual",
      "formula": "input.daily_salary * input.period_days",
      "inputs": {
        "input.daily_salary": "800.00",
        "input.period_days": "30"
      },
      "result_unrounded": "24000.000000",
      "result_final": "24000.00"
    },
    {
      "step": 2,
      "concept_id": "salario_diario_integrado",
      "label": "Salario Diario Integrado (SDI)",
      "formula": "input.daily_salary * input.factor_integracion",
      "inputs": {
        "input.daily_salary": "800.00",
        "input.factor_integracion": "1.0493"
      },
      "result_unrounded": "839.440000",
      "result_final": "839.44"
    },
    {
      "step": 3,
      "concept_id": "isr",
      "label": "ISR (Impuesto Sobre la Renta)",
      "formula": "apply_bracket(base_gravable_isr, brackets.isr_mensual)",
      "inputs": {
        "base_gravable_isr": "24000.00"
      },
      "result_unrounded": "2897.321600",
      "result_final": "2897.32"
    }
  ]
}

Field reference

Field	Description
`step`	Sequential step number in the calculation order
`concept_id`	Internal identifier of the payroll concept
`label`	Human-readable label (typically in Spanish)
`formula`	The DSL formula that was evaluated
`inputs`	Snapshot of all input values used in the formula
`result_unrounded`	Result before rounding (full precision)
`result_final`	Final value after rounding

Use cases

Compliance audits — Demonstrate to tax authorities exactly how each value was derived
Debugging — Identify which formula or input caused an unexpected result
Reconciliation — Compare engine results against manual calculations step by step
Employee inquiries — Explain payslip line items with full transparency

Performance considerations

For batch requests processing hundreds of employees, disabling the audit trail can significantly reduce response payload size. The calculation itself is not affected — only the response content changes.

{
  "options": {
    "include_audit_trail": false
  }
}

When disabled, the audit_trail field in the response will be null.