Update a reconciliation context

Use this endpoint to update the fields of a specific reconciliation context by its identifier. Setting status to ACTIVE is refused with 409 while the context is not ready for activation. A signConvention change is refused with 409 once the context has carried a partial balance, or while a match run is in progress.

PATCH /v1/contexts/{contextId}

Update a reconciliation context

cURL

curl --request PATCH \
  --url https://matcher.sandbox.lerian.net/v1/contexts/{contextId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agedBreakCalendar": "BR_ANBIMA",
  "agedBreakThresholdDays": 30,
  "autoMatchOnUpload": true,
  "feeNormalization": "NET",
  "feeToleranceAbs": "0.01",
  "feeTolerancePct": "0.5",
  "name": "Bank Reconciliation Q2",
  "signConvention": "OPPOSITE",
  "status": "ACTIVE",
  "type": "1:N"
}
'

200

Example

{
  "autoMatchOnUpload": false,
  "createdAt": "2025-01-15T10:30:00Z",
  "feeToleranceAbs": "0.50",
  "feeTolerancePct": "0.5",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Bank Reconciliation Q1",
  "signConvention": "SAME",
  "status": "ACTIVE",
  "tenantId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "1:1",
  "updatedAt": "2025-01-15T10:30:00Z",
  "agedBreakCalendar": "BR_ANBIMA",
  "agedBreakThresholdDays": 30,
  "feeNormalization": "NET"
}

Autorizaciones

Authorization · string · header · requerido

Bearer token authentication (format: "Bearer {token}")

Encabezados

X-Request-Id · string

A unique identifier for tracing the request across services.

X-Idempotency · string

Optional idempotency key for safe retries. Matcher reads the key only from this header, and only when you send one. A request that carries a key only in X-Idempotency-Key or Idempotency-Key is refused with 400 (MTCH-0015), and nothing is processed. If the same key is sent again and the original request was already processed, the stored response is returned with X-Idempotency-Replayed: true. A malformed key returns 400, a key whose first request is still in progress returns 409 (MTCH-0018), a key whose earlier attempt already ran but whose answer cannot be replayed returns 409 (MTCH-0022), and an idempotency storage failure returns 500. POST, PUT, PATCH and DELETE requests accept the header. These refusals are problem documents.

Parámetros de ruta

contextId · string<uuid> · requerido

The unique identifier of the reconciliation context. Context ID

Cuerpo

application/json

Context updates

agedBreakCalendar · string

Business-day calendar the aging threshold is measured against. Empty string clears it (raw calendar days); omit to leave it unchanged.

Ejemplo:

"BR_ANBIMA"

agedBreakThresholdDays · integer<int64>

Open-item aging SLA in business days. A positive value enables/changes aging; 0 disables it (clears the threshold); omit to leave it unchanged.

Ejemplo:

30

autoMatchOnUpload · boolean

When true, a match run is triggered automatically after a file upload completes.

Ejemplo:

true

feeNormalization · string

Fee normalization mode. NET compares amounts after fees are deducted; GROSS compares amounts before fees. Send an empty string to clear the mode; omit to leave it unchanged. (No enum constraint: unlike create, the update path accepts the empty string to clear.)

Ejemplo:

"NET"

feeToleranceAbs · string

Absolute fee tolerance as a decimal string in the context currency.

Ejemplo:

"0.01"

feeTolerancePct · string

Fee tolerance in percent, as a decimal string: 0.5 means 0.5%, not 50%.

Ejemplo:

"0.5"

name · string

New human-readable name of the reconciliation context.

Maximum string length: 100

Ejemplo:

"Bank Reconciliation Q2"

signConvention · enum<string>

How this context's data carries sign. SAME: a payment carries the same sign as what it settles, so a negative amount is a reversal. OPPOSITE: a payment carries the opposite sign of the invoice it settles. Omit to leave it unchanged. In 1:N contexts only payments of the declared sign are allocated to an invoice, and in N:M contexts a short-paid invoice keeps an open balance only when it is positive under SAME, or when the rule's sign mode is opposite under OPPOSITE; any other short payment stays unmatched; a carried open balance settles on a payment of the declared sign or on a reversal from the invoice's own side, and a row from an archived source stays unmatched. It cannot change once the context has carried a partial balance, or while a match run is in progress.

Opciones disponibles: SAME, OPPOSITE

Ejemplo:

"OPPOSITE"

status · enum<string>

Lifecycle status to transition to. ACTIVE runs the context; PAUSED suspends scheduling; ARCHIVED retires it.

Opciones disponibles: ACTIVE, PAUSED, ARCHIVED

Ejemplo:

"ACTIVE"

type · enum<string>

Reconciliation topology. 1:1 matches one left transaction to one right transaction; 1:N matches one transaction against many on the other side; N:M matches groups on both sides.

Opciones disponibles: 1:1, 1:N, N:M

Ejemplo:

"1:N"

Respuesta

200

application/json

Successfully updated context.

autoMatchOnUpload · boolean · requerido

When true, a match run is triggered automatically after a file upload completes.

Ejemplo:

false

createdAt · string · requerido

Creation timestamp in RFC 3339 format.

Ejemplo:

"2025-01-15T10:30:00Z"

feeToleranceAbs · string · requerido

Absolute fee tolerance as a decimal string in the context currency.

Ejemplo:

"0.50"

feeTolerancePct · string · requerido

Fee tolerance in percent, as a decimal string: 0.5 means 0.5%, not 50%.

Ejemplo:

"0.5"

id · string · requerido

Unique identifier of the context.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

name · string · requerido

Human-readable name of the reconciliation context.

Ejemplo:

"Bank Reconciliation Q1"

signConvention · enum<string> · requerido

How this context's data carries sign. SAME: a payment carries the same sign as what it settles, so a negative amount is a reversal. OPPOSITE: a payment carries the opposite sign of the invoice it settles. In 1:N contexts only payments of the declared sign are allocated to an invoice, and in N:M contexts a short-paid invoice keeps an open balance only when it is positive under SAME, or when the rule's sign mode is opposite under OPPOSITE; any other short payment stays unmatched; a carried open balance settles on a payment of the declared sign or on a reversal from the invoice's own side, and a row from an archived source stays unmatched. It cannot change once the context has carried a partial balance, or while a match run is in progress.

Opciones disponibles: SAME, OPPOSITE

Ejemplo:

"SAME"

status · enum<string> · requerido

Lifecycle status. DRAFT is being configured; ACTIVE runs; PAUSED is suspended; ARCHIVED is retired.

Opciones disponibles: DRAFT, ACTIVE, PAUSED, ARCHIVED

Ejemplo:

"ACTIVE"

tenantId · string · requerido

Identifier of the tenant that owns the context.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

type · enum<string> · requerido

Reconciliation topology. 1:1 matches one left transaction to one right transaction; 1:N matches one transaction against many on the other side; N:M matches groups on both sides.

Opciones disponibles: 1:1, 1:N, N:M

Ejemplo:

"1:1"

updatedAt · string · requerido

Last update timestamp in RFC 3339 format.

Ejemplo:

"2025-01-15T10:30:00Z"

agedBreakCalendar · string

Business-day calendar the aging threshold is measured against. Absent/empty means raw calendar days.

Ejemplo:

"BR_ANBIMA"

agedBreakThresholdDays · integer<int64>

Open-item aging SLA in business days. An open-item residual older than this surfaces as an AGED_BREAK exception. Absent when aging is disabled for the context.

Ejemplo:

30

feeNormalization · enum<string>

Fee normalization mode. NET compares amounts after fees are deducted; GROSS compares amounts before fees.

Opciones disponibles: NET, GROSS

Ejemplo:

"NET"