---
title: "Update Operator Payment"
method: PATCH
path: "/api/operator-payments/{payment_id}"
tags: ["operator-payments"]
---

# Update Operator Payment

`PATCH /api/operator-payments/{payment_id}`

Update single operator payment by id for admin or operator

## Path parameters

- `payment_id` string, uuid, required

## Request body

- OperatorPaymentUpdateRequest — Partial update; omitted fields are left unchanged.
  - `payment_month` string, date, nullable
  - `payment_kind` 'appointments' | 'supervision_t0_extra' | 'supervision_mini_equipe' | 'supervisions' — Operator payment row kind.
  - `total_visit_count` integer, nullable
  - `billable_visit_count` integer, nullable
  - `supervision_meeting_count` integer, nullable — Manual supervision meeting count; only editable on the supervision_mini_equipe row
  - `invoice_received_at` string, date-time, nullable
  - `invoice_amount` union
    - number
    - string
  - `invoice_status` 'pending' | 'invoice_declared' | 'correction_declared' | 'wrong_invoice_number' | 'verified' | 'amount_mismatch' — Operator payment invoice workflow status. ``invoice_declared`` / ``correction_declared`` are what the expert claims when closing the corresponding alert: the document number they say is on Zucchetti. Neither is evidence — the sweep still has to find that number and check its total before the voce reaches ``verified``. ``wrong_invoice_number`` is the sweep's answer when that number is nowhere on the portal.
  - `invoice_verified_at` string, date-time, nullable
  - `expected_invoice_number` string, nullable — Invoice number to look for in Zucchetti instead of searching by amount.
  - `invoice_number` string, nullable — Invoice number settled on this row. Normally written by the Zucchetti sync, which overwrites a manual value on the next reload.
  - `paid` boolean, nullable
  - `paid_at` string, date-time, nullable
  - `paid_amount` union
    - number
    - string
  - `marked_as_sent_at` string, date-time, nullable
  - `notes` string, nullable
  - `invoice_tax_regime` 'forfettario_2_pc' | 'forfettario_4_pc' | 'forfettario_inps_separato' | 'ordinario_2_pc' | 'ordinario_4_pc' | 'ordinario_4_pc_inps_separato', nullable

## Response `200`

Successful Response

- OperatorPaymentResponse — Single operator payment row.
  - `id` string, required — Primary key UUID
  - `operator_id` string, required — Operator UUID
  - `payment_kind` 'appointments' | 'supervision_t0_extra' | 'supervision_mini_equipe' | 'supervisions' — Operator payment row kind.
  - `operator_name` string, nullable — Operator display name (first_name + last_name)
  - `operator_iban` string, nullable — Operator IBAN from profile
  - `operator_tax_regime` string, nullable — Current operator tax regime from profile
  - `payment_month` string, date, required — First day of the payment month
  - `total_visit_count` integer, nullable — Total completed visits in the payment month (including non-billable/free visits)
  - `billable_visit_count` integer, nullable — Visits used for billing (computed on create from FATTO appointments; same rule as invoice modal)
  - `invoice_received_at` string, date-time, nullable
  - `invoice_amount` string, nullable
  - `invoice_status` 'pending' | 'invoice_declared' | 'correction_declared' | 'wrong_invoice_number' | 'verified' | 'amount_mismatch' — Operator payment invoice workflow status. ``invoice_declared`` / ``correction_declared`` are what the expert claims when closing the corresponding alert: the document number they say is on Zucchetti. Neither is evidence — the sweep still has to find that number and check its total before the voce reaches ``verified``. ``wrong_invoice_number`` is the sweep's answer when that number is nowhere on the portal.
  - `invoice_payment_url` string, nullable — Storage path of the legacy uploaded invoice; read-only, no longer written
  - `invoice_number` string, nullable — SDI invoice number the expert issued, read from Zucchetti; used in the monthly payment XML
  - `expected_invoice_number` string, nullable — Lookup invoice number declared for this voce.
  - `invoice_verified_at` string, date-time, nullable
  - `paid` boolean
  - `paid_at` string, date-time, nullable
  - `paid_amount` string, nullable
  - `marked_as_sent_at` string, date-time, nullable
  - `payout_amount` string, nullable — Amount to actually transfer.
  - `payout_deducted_supervision_count` integer — Supervisions already subtracted from payout_amount. Drives the compensation causale of the credit transfer.
  - `payout_deducted_amount` string — Euro value of the supervisions subtracted from payout_amount (count x unit).
  - `invoiceable_supervision_count` integer — Supervisions the sales invoice for this voce may cover, counted on the amount computed for the month rather than on the total read from Zucchetti. Gates the send.
  - `notes` string, nullable
  - `supervision_meeting_count` integer — Completed supervision meetings in the payment month
  - `free_supervision_count` integer — Completed free supervision meetings in the payment month
  - `previous_remaining_deductible_supervision_count` integer — Derived deductible supervision meetings carried in from the latest previous paid appointments row
  - `pending_deductible_supervision_count` integer — Deductible supervision meetings available on this row before payment absorption
  - `applied_deductible_supervision_count` integer — Deductible supervision meetings recovered from this invoice
  - `remaining_deductible_supervision_count` integer — Deductible supervision meetings still to recover after this row
  - `verified_source` string, nullable — How the invoice was verified: 'auto' (Zucchetti match) or 'manual' (admin override)
  - `invoice_tax_regime` string, nullable — Operator tax regime snapshot
  - `zucchetti_received_total` string, nullable — Invoice total fetched from Zucchetti for this row (None = not yet fetched)
  - `zucchetti_synced_at` string, date-time, nullable — Last time the Zucchetti total was fetched for this row
  - `zucchetti_match` string — Zucchetti total vs the amount expected for the voce, within ZUCCHETTI_MATCH_TOLERANCE_EUR: gross document total (±10c roundings) for appointments, meeting count x unit for supervisions. match | mismatch | unknown.
  - `zucchetti_calculated_net` string, nullable — Expected net-to-pay from the fac-simile calculator (regime + billable visits, all regimes). None when not computable.
  - `supervision_invoice_sent` boolean — Whether the supervision sales invoice for this operator+month was sent to Zucchetti

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/corabea/apis/corabea-api.md) · [All operations](https://skmtc.dev/corabea/apis/corabea-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/corabea/corabea-api/revisions/13c1bce1bdc4/schema)