Contributi

Consulta e gestisci i contributi previdenziali (INPS e Cassa Colf) generati dall'elaborazione dei cedolini. I contributi sono raggruppati per trimestre e per contratto domestico.

I contributi vengono generati automaticamente durante l'elaborazione dei cedolini. Non è necessario crearli manualmente: questa sezione riguarda la consultazione e la gestione dello stato di pagamento.

GET/v1/domestic-contributions

Restituisce l'elenco dei contributi per un'organizzazione e un anno specifici. Supporta paginazione e ricerca.

Parametri query

Parametro	Tipo	Obbligatorio	Descrizione
`organizationId`	`string`	Sì	ID dell'organizzazione.
`year`	`number`	Sì	Anno di riferimento (es. 2026).
`page`	`integer`	No	Numero di pagina (default 1).
`limit`	`integer`	No	Numero massimo di risultati (default 10, max 100).
`search`	`string`	No	Termine di ricerca testuale.
`sortField`	`string`	No	Campo per l'ordinamento.
`sortDirection`	`string`	No	Direzione ordinamento: ASC o DESC.

Esempio

curl "https://api.workledger.it/v1/domestic-contributions?organizationId=org_01H8X3K&year=2026" \
  -H "Authorization: Bearer wl_test_abc123"

Risposta

{
  "data": [
    {
      "id": "contrib_01H9Y4N",
      "domesticContractId": "dc_01H9Y4N",
      "organizationId": "org_01H8X3K",
      "quarter": 1,
      "year": 2026,
      "totalAmount": "450.00",
      "totalEmployerAmount": "300.00",
      "totalEmployeeAmount": "150.00",
      "pagoPAElaborated": false,
      "files": [],
      "createdAt": "2026-03-28T10:00:00Z",
      "updatedAt": "2026-03-28T10:00:00Z"
    }
  ]
}

GET/v1/domestic-contributions/contribution-details

Restituisce il dettaglio dei contributi per un contratto domestico, un trimestre e una data specifici. Include il calcolo disaggregato di INPS e Cassa Colf.

Parametri query

Parametro	Tipo	Obbligatorio	Descrizione
`domesticContractId`	`string`	Sì	ID del contratto domestico.
`quarter`	`number`	Sì	Trimestre (1, 2, 3 o 4).
`year`	`number`	Sì	Anno di riferimento.
`date`	`string`	Sì	Data di riferimento per il calcolo (formato YYYY-MM-DD).

Esempio

curl "https://api.workledger.it/v1/domestic-contributions/contribution-details?domesticContractId=dc_01H9Y4N&quarter=1&year=2026&date=2026-04-10" \
  -H "Authorization: Bearer wl_test_abc123"

Risposta

{
  "id": "contrib_01H9Y4N",
  "domesticContractId": "dc_01H9Y4N",
  "quarter": 1,
  "year": 2026,
  "items": [
    {
      "type": "inps",
      "weekStart": "2026-01-06",
      "weekEnd": "2026-01-12",
      "hours": "25.00",
      "rate": "0.0919",
      "employerRate": "0.0919",
      "employeeRate": "0.0919",
      "amount": "36.76",
      "effectiveWageRate": "10.00"
    },
    {
      "type": "cassacolf",
      "weekStart": "2026-01-06",
      "weekEnd": "2026-01-12",
      "hours": "25.00",
      "rate": "0.0050",
      "employerRate": "0.0033",
      "employeeRate": "0.0017",
      "amount": "2.00",
      "effectiveWageRate": "10.00"
    }
  ],
  "totalAmount": "450.00",
  "totalEmployerAmount": "300.00",
  "totalEmployeeAmount": "150.00",
  "pagoPAElaborated": false
}

Il campo date indica la data di scadenza del pagamento, utile per calcolare eventuali interessi o sanzioni. Le scadenze trimestrali INPS sono: 10 aprile (Q1), 10 luglio (Q2), 10 ottobre (Q3), 10 gennaio dell'anno successivo (Q4).

PATCH/v1/domestic-contributions/{id}

Aggiorna lo stato di un contributo. Attualmente consente di contrassegnare un contributo come elaborato tramite PagoPA.

Parametri path

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

Parametri body

Parametro	Tipo	Obbligatorio	Descrizione
`domesticContractId`	`string`	Sì	ID del contratto domestico.
`pagoPAElaborated`	`boolean`	No	Indica se il pagamento PagoPA è stato elaborato.

Esempio

curl -X PATCH https://api.workledger.it/v1/domestic-contributions/contrib_01H9Y4N \
  -H "Authorization: Bearer wl_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "domesticContractId": "dc_01H9Y4N",
    "pagoPAElaborated": true
  }'

POST/v1/domestic-contributions/{id}/files

Allega un file (es. ricevuta di pagamento) a un contributo. Il file viene caricato in formato multipart.

Parametri path

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

Parametri query

Parametro	Tipo	Obbligatorio	Descrizione
`domesticContractId`	`string`	Sì	ID del contratto domestico.
`organizationId`	`string`	Sì	ID dell'organizzazione.

Body

Il body deve essere inviato come multipart/form-data con un campo file contenente il file da allegare.

Esempio

curl -X POST "https://api.workledger.it/v1/domestic-contributions/contrib_01H9Y4N/files?domesticContractId=dc_01H9Y4N&organizationId=org_01H8X3K" \
  -H "Authorization: Bearer wl_test_abc123" \
  -F "[email protected]"

DELETE/v1/domestic-contributions/{id}/files/{fileId}

Rimuove un file allegato a un contributo.

Parametri path

Parametro	Tipo	Obbligatorio	Descrizione
`id`	`string`	Sì	ID del contributo.
`fileId`	`string`	Sì	ID del file da rimuovere.

Parametri query

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

Esempio

curl -X DELETE "https://api.workledger.it/v1/domestic-contributions/contrib_01H9Y4N/files/file_01H9Y4P?domesticContractId=dc_01H9Y4N" \
  -H "Authorization: Bearer wl_test_abc123"

L'eliminazione del file è definitiva: il file viene rimosso sia dal contributo che dallo storage.

Scadenze trimestrali

I contributi INPS per il lavoro domestico devono essere versati entro le seguenti scadenze:

Trimestre	Periodo	Scadenza pagamento
Q1	Gennaio - Marzo	10 aprile
Q2	Aprile - Giugno	10 luglio
Q3	Luglio - Settembre	10 ottobre
Q4	Ottobre - Dicembre	10 gennaio (anno successivo)