Cedolini

Elabora, consulta e finalizza le buste paga per i contratti domestici. Il flusso prevede tre passaggi: validazione del periodo, calcolo delle settimane contributive, ed esecuzione del cedolino.

Flusso di elaborazione

Per elaborare un cedolino: (1) validare il periodo con validate-before-run, (2) ottenere le settimane contributive con contribution-weeks, (3) eseguire il calcolo con run-payroll. Al termine, finalizzare il cedolino per renderlo definitivo.

GET/v1/domestic-payslips

Restituisce l'elenco dei cedolini per un contratto domestico. Supporta paginazione.

Parametri query

Parametro	Tipo	Obbligatorio	Descrizione
`domesticContractId`	`string`	Sì	ID del contratto domestico.
`page`	`integer`	No	Numero di pagina (default 1).
`limit`	`integer`	No	Numero massimo di risultati (default 20, max 100).
`sortField`	`string`	No	Campo per l'ordinamento.
`sortDirection`	`string`	No	Direzione ordinamento: asc o desc.

Risposta

{
  "data": [
    {
      "id": "pay_01H9Y4N",
      "domesticContractId": "dc_01H9Y4N",
      "organizationId": "org_01H8X3K",
      "status": "draft",
      "startDate": "2026-03-01",
      "endDate": "2026-03-31",
      "isThirteenth": false,
      "isSeveranceLiquidation": false,
      "isEmploymentEnded": false,
      "totalGross": "1250.00",
      "totalDeductions": "50.00",
      "totalEmployeeTaxes": "120.00",
      "totalEmployerTaxes": "180.00",
      "totalNet": "1080.00",
      "totalCost": "1430.00",
      "createdAt": "2026-03-28T10:00:00Z",
      "updatedAt": "2026-03-28T10:00:00Z"
    }
  ]
}

GET/v1/domestic-payslips/{id}

Restituisce i dettagli completi di un cedolino, incluse tutte le voci di competenza, trattenuta, contributi, e gli stati di ferie, TFR, tredicesima, malattia e infortunio.

Parametri path

Parametro	Tipo	Obbligatorio	Descrizione
`id`	`string`	Sì	ID del cedolino.

Risposta (struttura completa)

{
  "id": "pay_01H9Y4N",
  "domesticContractId": "dc_01H9Y4N",
  "organizationId": "org_01H8X3K",
  "status": "draft",
  "startDate": "2026-03-01",
  "endDate": "2026-03-31",
  "isThirteenth": false,
  "isSeveranceLiquidation": false,
  "isEmploymentEnded": false,
  "earningElements": [
    {
      "id": "item_001",
      "type": "earning",
      "code": "0",
      "name": "Retribuzione ordinaria",
      "value": "1000.00",
      "periodType": "hour",
      "periodDuration": "100",
      "rate": "10.00",
      "includedInBaseWage": false,
      "ytd": "3000.00"
    }
  ],
  "deductionElements": [],
  "imputedElements": [],
  "employeeTaxesElements": [
    {
      "id": "item_010",
      "type": "employee_tax",
      "code": "300",
      "name": "Contributi INPS c/dipendente",
      "value": "90.00",
      "periodType": "period",
      "periodDuration": "1",
      "rate": "0.00",
      "includedInBaseWage": false,
      "ytd": "270.00"
    }
  ],
  "employerTaxesElements": [
    {
      "id": "item_020",
      "type": "employer_tax",
      "code": "400",
      "name": "Contributi INPS c/datore",
      "value": "135.00",
      "periodType": "period",
      "periodDuration": "1",
      "rate": "0.00",
      "includedInBaseWage": false,
      "ytd": "405.00"
    }
  ],
  "inpsContributions": [
    {
      "id": "contrib_001",
      "type": "inps",
      "weekStart": "2026-03-02",
      "weekEnd": "2026-03-08",
      "hours": "25.00",
      "rate": "0.0919",
      "employerRate": "0.0919",
      "employeeRate": "0.0919",
      "amount": "36.76",
      "effectiveWageRate": "10.00",
      "isFromNextPeriod": false
    }
  ],
  "cassacolfContributions": [],
  "vacationState": {
    "accrued": "8.33",
    "used": "0.00",
    "previousYearLeft": "0.00",
    "accruedThisYear": "8.33",
    "usedThisYear": "0.00",
    "totalLeft": "8.33"
  },
  "severanceState": {
    "utilWage": "1250.00",
    "accrued": "92.59",
    "liquidated": "0.00",
    "accruedThisYear": "92.59",
    "accruedPreviousYears": "0.00",
    "totalLiquidated": "0.00",
    "totalLeft": "92.59"
  },
  "thirteenthState": {
    "utilWage": "1250.00",
    "accrued": "104.17",
    "liquidated": "0.00",
    "accruedThisYear": "104.17",
    "totalLiquidated": "0.00",
    "totalLeft": "104.17"
  },
  "sickState": {
    "paidHalfDays": "0.00",
    "paidFullDays": "0.00",
    "nonPaidDays": "0.00",
    "totalPaidHalfDays": "0.00",
    "totalPaidFullDays": "0.00",
    "totalNonPaidDays": "0.00"
  },
  "injuryState": {
    "paidFullDays": "0.00",
    "nonPaidDays": "0.00",
    "totalPaidFullDays": "0.00",
    "totalNonPaidDays": "0.00"
  },
  "totalGross": "1250.00",
  "ytdTotalGross": "3750.00",
  "totalDeductions": "50.00",
  "ytdTotalDeductions": "150.00",
  "totalAfterDeductionsGross": "1200.00",
  "ytdTotalAfterDeductionsGross": "3600.00",
  "totalEmployeeTaxes": "120.00",
  "ytdTotalEmployeeTaxes": "360.00",
  "totalEmployeeInpsTaxes": "90.00",
  "ytdTotalEmployeeInpsTaxes": "270.00",
  "totalEmployeeCassacolfTaxes": "30.00",
  "ytdTotalEmployeeCassacolfTaxes": "90.00",
  "totalTaxableGross": "1080.00",
  "ytdTotalTaxableGross": "3240.00",
  "totalEmployerTaxes": "180.00",
  "ytdTotalEmployerTaxes": "540.00",
  "totalCost": "1430.00",
  "ytdTotalCost": "4290.00",
  "totalNet": "1080.00",
  "ytdTotalNet": "3240.00",
  "createdAt": "2026-03-28T10:00:00Z",
  "updatedAt": "2026-03-28T10:00:00Z"
}

Tutti gli importi sono espressi come stringhe decimali (es. "1250.00"). I campi con prefisso ytd indicano i totali progressivi da inizio anno.

POST/v1/domestic-payslips/validate-before-run

Verifica che un contratto sia pronto per l'elaborazione del cedolino in un dato periodo. Restituisce eventuali errori o avvisi.

Parametri body

Parametro	Tipo	Obbligatorio	Descrizione
`domesticContractId`	`string`	Sì	ID del contratto domestico.
`date`	`string`	Sì	Periodo da validare (formato YYYY-MM).

Esempio

curl -X POST https://api.workledger.it/v1/domestic-payslips/validate-before-run \
  -H "Authorization: Bearer wl_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "domesticContractId": "dc_01H9Y4N",
    "date": "2026-03"
  }'

POST/v1/domestic-payslips/contribution-weeks

Calcola le settimane contributive per un periodo, necessarie come parametro per l'elaborazione del cedolino.

Parametri body

Parametro	Tipo	Obbligatorio	Descrizione
`domesticContractId`	`string`	Sì	ID del contratto domestico.
`startDate`	`string`	Sì	Data di inizio periodo (formato YYYY-MM-DD).
`endDate`	`string`	Sì	Data di fine periodo (formato YYYY-MM-DD).
`employmentEnding`	`boolean`	No	Indica se il rapporto di lavoro termina in questo periodo.

Risposta

[
  {
    "hours": "25",
    "weekStart": "2026-03-02",
    "weekEnd": "2026-03-08",
    "isFromNextPeriod": false
  },
  {
    "hours": "25",
    "weekStart": "2026-03-09",
    "weekEnd": "2026-03-15",
    "isFromNextPeriod": false
  }
]

Esempio

curl -X POST https://api.workledger.it/v1/domestic-payslips/contribution-weeks \
  -H "Authorization: Bearer wl_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "domesticContractId": "dc_01H9Y4N",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31"
  }'

POST/v1/domestic-payslips/run-payroll

Esegue il calcolo del cedolino per un contratto e un periodo specifici. Restituisce il cedolino completo in stato draft.

Parametri body

Parametro	Tipo	Obbligatorio	Descrizione
`domesticContractId`	`string`	Sì	ID del contratto domestico.
`organizationId`	`string`	Sì	ID dell'organizzazione.
`period`	`string`	Sì	Periodo di elaborazione (formato YYYY-MM).
`contributionWeeks`	`array`	Sì	Settimane contributive ottenute dall'endpoint contribution-weeks.
`notUsedVacationContributionHours`	`string`	Sì	Ore contributive per ferie non godute (default '0.00').
`missingNoticeWeeks`	`string`	Sì	Settimane di mancato preavviso (default '0').
`isThirteenth`	`boolean`	No	Se true, elabora il cedolino della tredicesima.
`employmentEndDate`	`string`	No	Data di fine rapporto (YYYY-MM-DD). Se presente, calcola le spettanze di fine rapporto.
`missingNoticeType`	`string`	No	Tipo di mancato preavviso: EMPLOYER o EMPLOYEE.
`missingNoticeDays`	`string`	No	Giorni di mancato preavviso.
`liquidateSeveranceWithEmploymentEnd`	`boolean`	No	Liquida il TFR con la fine del rapporto.
`severanceLiquidationPayslip`	`boolean`	No	Cedolino di liquidazione TFR.
`severanceAnticipation`	`string`	No	Anticipo TFR.
`vacationAnticipation`	`string`	No	Anticipo ferie.
`accommodationInCash`	`string`	No	Indennità vitto/alloggio in denaro.
`accommodationInNature`	`string`	No	Indennità vitto/alloggio in natura.
`customEarnings`	`array`	No	Competenze aggiuntive personalizzate (vedi tabella sotto).
`customDeductions`	`array`	No	Trattenute aggiuntive personalizzate.
`customImputedElements`	`array`	No	Voci figurative personalizzate.
`note1`	`string`	No	Nota aggiuntiva 1.
`note2`	`string`	No	Nota aggiuntiva 2.

contributionWeeks (elemento dell'array)

Parametro	Tipo	Obbligatorio	Descrizione
`hours`	`string`	Sì	Ore nella settimana contributiva.
`weekStart`	`string`	Sì	Inizio settimana (YYYY-MM-DD).
`weekEnd`	`string`	Sì	Fine settimana (YYYY-MM-DD).
`isFromNextPeriod`	`boolean`	Sì	Se la settimana appartiene al periodo successivo.

Voci personalizzate (customEarnings, customDeductions, customImputedElements)

Parametro	Tipo	Obbligatorio	Descrizione
`name`	`string`	Sì	Nome della voce.
`periodType`	`string`	Sì	Tipo periodo: period, week, hour, day, month, year.
`periodDuration`	`string`	Sì	Durata del periodo (es. '1' per un periodo intero, '10' per 10 ore).
`value`	`string`	Sì	Importo della voce.

Esempio

curl -X POST https://api.workledger.it/v1/domestic-payslips/run-payroll \
  -H "Authorization: Bearer wl_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "domesticContractId": "dc_01H9Y4N",
    "organizationId": "org_01H8X3K",
    "period": "2026-03",
    "contributionWeeks": [
      {
        "hours": "25",
        "weekStart": "2026-03-02",
        "weekEnd": "2026-03-08",
        "isFromNextPeriod": false
      },
      {
        "hours": "25",
        "weekStart": "2026-03-09",
        "weekEnd": "2026-03-15",
        "isFromNextPeriod": false
      }
    ],
    "notUsedVacationContributionHours": "0.00",
    "missingNoticeWeeks": "0"
  }'

PATCH/v1/domestic-payslips/{id}

Aggiorna le note di un cedolino.

Parametri path

Parametro	Tipo	Obbligatorio	Descrizione
`id`	`string`	Sì	ID del cedolino.

Parametri body

Parametro	Tipo	Obbligatorio	Descrizione
`note1`	`string`	No	Nota aggiuntiva 1.
`note2`	`string`	No	Nota aggiuntiva 2.

POST/v1/domestic-payslips/{id}/finalize

Finalizza un cedolino in stato draft, rendendolo definitivo.

Parametri path

Parametro	Tipo	Obbligatorio	Descrizione
`id`	`string`	Sì	ID del cedolino.

Operazione irreversibile

Un cedolino finalizzato non può essere modificato. Per correggere un cedolino finalizzato, è necessario eliminarlo e rielaborarlo.

Esempio

curl -X POST https://api.workledger.it/v1/domestic-payslips/pay_01H9Y4N/finalize \
  -H "Authorization: Bearer wl_test_abc123"

DELETE/v1/domestic-payslips/{id}

Elimina un cedolino.

Parametri path

Parametro	Tipo	Obbligatorio	Descrizione
`id`	`string`	Sì	ID del cedolino.

L'eliminazione di un cedolino finalizzato richiede attenzione: i calcoli progressivi (ferie, TFR, tredicesima) dei cedolini successivi potrebbero risultare non aggiornati. Si consiglia di rielaborare i cedolini successivi dopo un'eliminazione.

Struttura del cedolino

Ogni cedolino contiene le seguenti sezioni principali:

Sezione	Descrizione
`earningElements`	Voci di competenza (retribuzione ordinaria, straordinari, indennità)
`deductionElements`	Trattenute (anticipi, prestiti)
`imputedElements`	Voci figurative (vitto/alloggio in natura)
`employeeTaxesElements`	Contributi a carico del lavoratore (INPS, Cassa Colf)
`employerTaxesElements`	Contributi a carico del datore (INPS, Cassa Colf)
`inpsContributions`	Dettaglio contributi INPS per settimana contributiva
`cassacolfContributions`	Dettaglio contributi Cassa Colf per settimana contributiva
`vacationState`	Stato ferie (maturate, godute, residue)
`severanceState`	Stato TFR (maturato, liquidato, residuo)
`thirteenthState`	Stato tredicesima (maturata, liquidata, residua)
`sickState`	Stato malattia (giorni retribuiti e non)
`injuryState`	Stato infortunio (giorni retribuiti e non)

Totali del cedolino

Campo	Descrizione
`totalGross`	Lordo totale
`totalDeductions`	Totale trattenute
`totalAfterDeductionsGross`	Lordo al netto delle trattenute
`totalEmployeeTaxes`	Contributi totali a carico del lavoratore
`totalEmployerTaxes`	Contributi totali a carico del datore
`totalTaxableGross`	Imponibile
`totalCost`	Costo totale per il datore
`totalNet`	Netto in busta

Ogni campo totale ha un corrispondente con prefisso ytd (year-to-date) che indica il progressivo da inizio anno.