---
title: "Issue one supervision sales invoice for selected meetings"
method: POST
path: "/api/operator-payments/send-supervision/by-meeting"
tags: ["operator-payments"]
---

# Issue one supervision sales invoice for selected meetings

`POST /api/operator-payments/send-supervision/by-meeting`

## Request

- Base URL: `https://api.corabea.it` (the document declares no server; this is the origin it was published from)
- URL: `https://api.corabea.it/api/operator-payments/send-supervision/by-meeting`
- Auth: HTTP bearer

For supervisions the payout cannot absorb: one document for the selected meetings of a single expert, still open in the deduction ledger and not yet invoiced (gated by ZUCCHETTI_DRY_RUN).

## Request body

- OperatorPaymentSendSupervisionByMeetingRequest: Issue one sales invoice for supervisions the payout cannot absorb (all of one expert).
  - `meeting_ids` string[], required: Supervision meeting UUIDs (max 30)
  - `document_number` integer, required: Progressive document number
  - `document_series` string, required: Document series/sezionale

## Response `200`

Successful Response

- SupervisionInvoiceBatchResponse: Batch response for the supervision-invoice send, plus the per-row Zucchetti preview.
  - `updated` OperatorPaymentResponse[]
    - `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.
    - `supervision_deduction_summary` SupervisionDeductionSummary: Current status of supervision charges dated through the payment month, including arrears.
      - `open_count` integer
      - `settled_count` integer
      - `waived_count` integer
      - `backlog_count` integer: Open charges through this month that the deduction backlog lists: no payout withholds them, the back-office has to decide.
      - `withheld_meeting_dates` string[]: Supervisions this voce withholds, oldest first: the ones applied to it once paid, the ones its payout would take before.
    - `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
    - `expected_invoice_total` string, nullable: Expected gross invoice total, before rounding tolerances; compared with zucchetti_received_total, not the net transfer amount.
    - `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
  - `failed` OperatorPaymentBatchFailure[]
    - `id` string, uuid, required
    - `status` integer, required
    - `detail` string, required
  - `previews` ZucchettiSupervisionInvoicePreview[]
    - `id` string, uuid, required
    - `operator_id` string, uuid, nullable
    - `operator_name` string, nullable
    - `dry_run` boolean, required
    - `submitted` boolean, required
    - `supplier_code` string, nullable
    - `supplier_label` string, nullable
    - `payload` object

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-01** `6108ff351838`: 2 info
  - added the optional property `updated/items/supervision_deduction_summary/anyOf[subschema #1: SupervisionDeductionSummary]/backlog_count` to the response with the `200` status
  - added the optional property `updated/items/supervision_deduction_summary/anyOf[subschema #1: SupervisionDeductionSummary]/withheld_meeting_dates` to the response with the `200` status
- **2026-09-11** `969efd5098c9`: 2 info
  - added the optional property `updated/items/expected_invoice_total` to the response with the `200` status
  - added the optional property `updated/items/supervision_deduction_summary` to the response with the `200` status
- **2026-09-11** `6afa01417695`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/corabea/apis/corabea-api/changes/api/operator-payments/send-supervision/by-meeting/post.md)

---

[API](https://skmtc.dev/corabea/apis/corabea-api.md) · [All operations](https://skmtc.dev/corabea/apis/corabea-api/llms.txt) · [OpenAPI document](https://skmtc.dev/corabea/apis/corabea-api/revisions/d8cdee1d5474?raw)