Contratti domestici

Gestisci i rapporti di lavoro domestico: anagrafica del lavoratore, orario settimanale, configurazione retributiva, impostazioni contrattuali e voci aggiuntive.

GET/v1/domestic-contracts

Restituisce l'elenco dei contratti domestici. Supporta paginazione, ricerca e filtri.

Parametri query

Parametro	Tipo	Obbligatorio	Descrizione
`organizationId`	`string`	Sì	ID dell'organizzazione.
`page`	`integer`	No	Numero di pagina (default 1).
`limit`	`integer`	No	Numero massimo di risultati (default 20, max 100).
`search`	`string`	No	Termine di ricerca testuale.
`status`	`string`	No	Filtra per stato: draft, active, inactive.
`sortField`	`string`	No	Campo per l'ordinamento.
`sortDirection`	`string`	No	Direzione ordinamento: asc o desc.

Risposta

{
  "data": [
    {
      "id": "dc_01H9Y4N",
      "humanReadableId": "DC-2026-001",
      "employerId": "123e4567-e89b-12d3-a456-426614174000",
      "organizationId": "org_01H8X3K",
      "status": "active",
      "termType": "indefinite",
      "employmentDate": "2026-01-15",
      "contractType": "non_livein",
      "contractLevel": "B",
      "paymentType": "bank_transfer",
      "personalInfo": {
        "firstName": "Anna",
        "lastName": "Bianchi",
        "fiscalCode": "BNCHNN90A01H501Z"
      },
      "weekSchedule": {
        "monday": "5",
        "tuesday": "5",
        "wednesday": "5",
        "thursday": "5",
        "friday": "5",
        "saturday": "0",
        "sunday": "0",
        "hoursPerWeek": "25",
        "workingDaysPerWeek": "5"
      },
      "archived": false,
      "createdAt": "2026-01-10T09:00:00Z",
      "updatedAt": "2026-01-10T09:00:00Z"
    }
  ]
}

GET/v1/domestic-contracts/{id}

Restituisce i dettagli completi di un singolo contratto domestico, inclusi orario, retribuzione, impostazioni e voci aggiuntive.

Parametri path

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

POST/v1/domestic-contracts

Crea un nuovo contratto domestico.

Parametri body

Parametro	Tipo	Obbligatorio	Descrizione
`employerId`	`string`	Sì	ID del datore di lavoro.
`organizationId`	`string`	Sì	ID dell'organizzazione.
`termType`	`string`	Sì	Tipo di contratto: indefinite (tempo indeterminato) o fixed (tempo determinato).
`employmentDate`	`string`	Sì	Data di assunzione (formato YYYY-MM-DD).
`expirationDate`	`string`	No	Data di scadenza (formato YYYY-MM-DD). Obbligatorio per contratti a tempo determinato.
`contractType`	`string`	Sì	Tipo di rapporto: non_livein, livein_fulltime, livein_parttime, livein_night_assistance, livein_night_presence, replacement.
`contractLevel`	`string`	Sì	Livello CCNL: unique, A, AS, B, BS, C, CS, D, DS.
`domesticProfile`	`string`	No	Descrizione del profilo lavorativo.
`domesticInspCode`	`string`	No	Codice ispettorato.
`paymentType`	`string`	Sì	Modalità di pagamento: cash, bank_transfer, check.
`paymentDetails`	`string`	No	Dettagli sul pagamento (es. IBAN).
`personalInfo`	`object`	Sì	Dati anagrafici del lavoratore (vedi tabella sotto).
`weekSchedule`	`object`	Sì	Orario settimanale (vedi tabella sotto).
`misc`	`object`	Sì	Impostazioni contrattuali (vedi tabella sotto).
`wageConfig`	`object`	Sì	Configurazione retributiva (vedi tabella sotto).
`priorPayroll`	`object`	No	Dati di cedolini precedenti per continuità (vedi tabella sotto).
`additionalEntries`	`array`	No	Voci aggiuntive ricorrenti (vedi tabella sotto).

personalInfo (dati del lavoratore)

Stessa struttura del campo personalInfo dei datori di lavoro: firstName, lastName, fiscalCode, birthDate, address, locality, province, zipCode, phone, email, pec, ecc.

weekSchedule (orario settimanale)

Parametro	Tipo	Obbligatorio	Descrizione
`monday`	`string`	Sì	Ore di lavoro il lunedì.
`tuesday`	`string`	Sì	Ore di lavoro il martedì.
`wednesday`	`string`	Sì	Ore di lavoro il mercoledì.
`thursday`	`string`	Sì	Ore di lavoro il giovedì.
`friday`	`string`	Sì	Ore di lavoro il venerdì.
`saturday`	`string`	Sì	Ore di lavoro il sabato.
`sunday`	`string`	Sì	Ore di lavoro la domenica.

wageConfig (configurazione retributiva)

Parametro	Tipo	Obbligatorio	Descrizione
`wageTypeOverwrite`	`string`	No	Tipo di retribuzione: hourly o monthly.
`basePay`	`string`	No	Paga base (importo decimale).
`isBasePayOverwritten`	`boolean`	No	Se true, il valore di basePay sovrascrive il minimo tabellare.
`extraMinVariable`	`string`	No	Superminimo variabile.
`isExtraMinVariableAutomatic`	`boolean`	No	Se true, il superminimo variabile è calcolato automaticamente.
`extraMinSetDate`	`string`	No	Data di impostazione del superminimo variabile (YYYY-MM-DD).
`extraMinNonVariable`	`string`	No	Superminimo non variabile.
`extraSeniority`	`string`	No	Scatto di anzianità.
`extraSeniorityCount`	`string`	No	Numero di scatti maturati.
`nextSeniorityIncreaseDate`	`string`	No	Data del prossimo scatto (YYYY-MM-DD).
`isExtraSeniorityOverwritten`	`boolean`	No	Se true, lo scatto è sovrascritto manualmente.
`functioningAllowance`	`string`	No	Indennità di funzione.
`isFunctioningAllowanceOverwritten`	`boolean`	No	Se true, l'indennità di funzione è sovrascritta.
`accommodationLunch`	`string`	No	Indennità vitto pranzo.
`accommodationDinner`	`string`	No	Indennità vitto cena.
`accommodationLodge`	`string`	No	Indennità alloggio.
`isAccommodationOverwritten`	`boolean`	No	Se true, le indennità vitto/alloggio sono sovrascritte.

misc (impostazioni contrattuali)

Parametro	Tipo	Obbligatorio	Descrizione
`isRelative`	`boolean`	No	Il lavoratore è un familiare del datore.
`isPreschoolChildCare`	`boolean`	No	Assistenza a bambini in età prescolare.
`isCareForMultipleNotSelfSufficient`	`boolean`	No	Assistenza a persone non autosufficienti.
`isUniCertificated`	`boolean`	No	Lavoratore con certificazione universitaria.
`isVacationEnabled`	`boolean`	No	Maturazione ferie abilitata.
`vacationCalculationType`	`string`	No	Calcolo ferie: hours o days.
`isVacationLiquidatedMonthly`	`boolean`	No	Ferie liquidate mensilmente.
`isSeveranceEnabled`	`boolean`	No	TFR abilitato.
`isSeveranceLiquidatedMonthly`	`boolean`	No	TFR liquidato mensilmente.
`isSeveranceCalculatedOnAnnualBase`	`boolean`	No	TFR calcolato su base annuale.
`isThirteenthEnabled`	`boolean`	No	Tredicesima abilitata.
`isThirteenthLiquidatedMonthly`	`boolean`	No	Tredicesima liquidata mensilmente.
`isInpsContributionEnabled`	`boolean`	No	Contributi INPS abilitati.
`isInpsContributionWithheld`	`boolean`	No	Contributi INPS trattenuti dal netto.
`isCassaColfContributionEnabled`	`boolean`	No	Contributi Cassa Colf abilitati.
`isCassaColfContributionWithheld`	`boolean`	No	Contributi Cassa Colf trattenuti dal netto.
`isAccommodationEnabled`	`boolean`	No	Indennità vitto/alloggio abilitata.
`accommodationDaysMonth`	`string`	No	Calcolo giorni vitto: week_schedule, days_26, days_30.

additionalEntries (voci aggiuntive ricorrenti)

Parametro	Tipo	Obbligatorio	Descrizione
`name`	`string`	Sì	Descrizione della voce.
`amount`	`string`	Sì	Importo (decimale, es. '100.00').
`type`	`string`	Sì	Tipo di voce: earning (competenza), withholding (trattenuta), figurative (figurativo).

priorPayroll (dati pregressi)

Utilizzare questo oggetto quando si importa un contratto con cedolini già elaborati da un altro sistema, per garantire la continuità nei calcoli di ferie, TFR e tredicesima.

Parametro	Tipo	Obbligatorio	Descrizione
`date`	`string`	Sì	Data di riferimento dei dati pregressi (YYYY-MM-DD).
`ytdGross`	`string`	No	Imponibile lordo da inizio anno.
`ytdInpsContributions`	`string`	No	Contributi INPS da inizio anno.
`ytdCassacolfContributions`	`string`	No	Contributi Cassa Colf da inizio anno.
`accruedPreviousYearsSeverance`	`string`	No	TFR maturato anni precedenti.
`accruedThisYearSeverance`	`string`	No	TFR maturato anno corrente.
`totalLiquidatedSeverance`	`string`	No	TFR totale liquidato.
`leftPreviousYearsVacation`	`string`	No	Ferie residue anni precedenti.
`accruedThisYearVacation`	`string`	No	Ferie maturate anno corrente.
`usedThisYearVacation`	`string`	No	Ferie godute anno corrente.
`accruedThirteenth`	`string`	No	Tredicesima maturata.

Esempio

curl -X POST https://api.workledger.it/v1/domestic-contracts \
  -H "Authorization: Bearer wl_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "employerId": "123e4567-e89b-12d3-a456-426614174000",
    "organizationId": "org_01H8X3K",
    "termType": "indefinite",
    "employmentDate": "2026-01-15",
    "contractType": "non_livein",
    "contractLevel": "B",
    "paymentType": "bank_transfer",
    "personalInfo": {
      "firstName": "Anna",
      "lastName": "Bianchi",
      "fiscalCode": "BNCHNN90A01H501Z"
    },
    "weekSchedule": {
      "monday": "5",
      "tuesday": "5",
      "wednesday": "5",
      "thursday": "5",
      "friday": "5",
      "saturday": "0",
      "sunday": "0"
    },
    "wageConfig": {},
    "misc": {
      "isVacationEnabled": true,
      "isSeveranceEnabled": true,
      "isThirteenthEnabled": true,
      "isInpsContributionEnabled": true,
      "isCassaColfContributionEnabled": true
    }
  }'

I campi di wageConfig non specificati vengono calcolati automaticamente in base al livello contrattuale e alle tabelle retributive CCNL vigenti.

PATCH/v1/domestic-contracts/{id}

Aggiorna un contratto domestico esistente. Accetta gli stessi campi della creazione; vengono aggiornati solo i campi inclusi nel body.

Parametri path

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

Esempio

curl -X PATCH https://api.workledger.it/v1/domestic-contracts/dc_01H9Y4N \
  -H "Authorization: Bearer wl_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "contractLevel": "CS",
    "weekSchedule": {
      "monday": "6",
      "tuesday": "6",
      "wednesday": "6",
      "thursday": "6",
      "friday": "6",
      "saturday": "0",
      "sunday": "0"
    }
  }'

DELETE/v1/domestic-contracts/{id}

Elimina un contratto domestico.

Parametri path

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

Operazione irreversibile

L'eliminazione rimuove il contratto e tutti i dati associati (eventi lavorativi, cedolini). Verificare attentamente prima di procedere.

Tipi di contratto

Valore	Descrizione
`non_livein`	Non convivente
`livein_fulltime`	Convivente a tempo pieno
`livein_parttime`	Convivente a tempo parziale
`livein_night_assistance`	Convivente con assistenza notturna
`livein_night_presence`	Convivente con presenza notturna
`replacement`	Sostituzione

Livelli contrattuali CCNL

Livello	Descrizione
`unique`	Livello unico
`A`	Collaboratore generico non addetto all'assistenza
`AS`	Addetto alla compagnia
`B`	Collaboratore generico con esperienza
`BS`	Assistente a persone autosufficienti
`C`	Collaboratore con competenze specifiche
`CS`	Assistente a persone non autosufficienti
`D`	Collaboratore con esperienza e responsabilità
`DS`	Assistente formato a persone non autosufficienti