Home / Documentazione / API Reference

API Reference

Documentazione completa dell'API REST di PaySuite. Integra la gestione paghe nei tuoi sistemi con endpoint sicuri e ben documentati.

Base URL

Tutte le richieste API devono essere indirizzate al seguente endpoint base:

https://api.paysuite.it/v1

L'API utilizza il protocollo HTTPS. Le richieste HTTP non crittografate non sono supportate. Tutte le risposte sono in formato JSON con charset UTF-8.

Autenticazione

L'API PaySuite utilizza il protocollo OAuth 2.0 per l'autenticazione. Sono supportati i grant type client_credentials e authorization_code.

Ottenere un Access Token

cURL 
curl -X POST https://api.paysuite.it/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=read write"

Risposta

JSON 
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Utilizzare il Token

Includi il token in ogni richiesta tramite l'header Authorization: 

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Sicurezza

Non condividere mai le credenziali API. Utilizza variabili d'ambiente per memorizzare client_id e client_secret. I token scadono dopo 1 ora e devono essere rinnovati.

Rate Limiting

Le richieste API sono soggette a limiti per garantire la stabilità del servizio:

Piano Richieste/minuto Richieste/giorno
Studio 60 10.000
Professional 120 50.000
Enterprise 300 200.000

Gli header di risposta includono informazioni sui limiti: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Aziende

Endpoint per la gestione delle aziende clienti.

GET /api/v1/aziende Elenco aziende

Restituisce l'elenco di tutte le aziende associate all'account.

Parametri query

Parametro Tipo Descrizione
page integer Numero pagina (default: 1)
per_page integer Risultati per pagina (default: 25, max: 100)
search string Ricerca per ragione sociale o P.IVA
cURL 
curl -X GET "https://api.paysuite.it/v1/aziende?page=1&per_page=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
POST /api/v1/aziende Crea azienda

Crea una nuova azienda cliente.

Body (JSON)

Campo Tipo Obbligatorio Descrizione
ragione_sociale string Sì Ragione sociale dell'azienda
partita_iva string Sì Partita IVA (11 cifre)
codice_fiscale string Sì Codice fiscale dell'azienda
ccnl_id string Sì ID del CCNL applicato
matricola_inps string No Matricola INPS
sede object No Oggetto indirizzo sede legale
cURL 
curl -X POST https://api.paysuite.it/v1/aziende \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ragione_sociale": "Esempio S.r.l.",
    "partita_iva": "01234567890",
    "codice_fiscale": "01234567890",
    "ccnl_id": "commercio_2024",
    "matricola_inps": "1234567890"
  }'
GET /api/v1/aziende/{id} Dettaglio azienda

Restituisce i dettagli di una specifica azienda.

cURL 
curl -X GET https://api.paysuite.it/v1/aziende/az_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Dipendenti

Endpoint per la gestione dell'anagrafica dipendenti.

GET /api/v1/dipendenti Elenco dipendenti

Restituisce l'elenco dei dipendenti. Può essere filtrato per azienda.

Parametro Tipo Descrizione
azienda_id string Filtra per azienda
stato string Filtra per stato: attivo, cessato, sospeso
page integer Numero pagina
cURL 
curl -X GET "https://api.paysuite.it/v1/dipendenti?azienda_id=az_abc123&stato=attivo" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
POST /api/v1/dipendenti Crea dipendente

Inserisce un nuovo dipendente nell'anagrafica.

cURL 
curl -X POST https://api.paysuite.it/v1/dipendenti \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "azienda_id": "az_abc123",
    "nome": "Mario",
    "cognome": "Rossi",
    "codice_fiscale": "RSSMRA80A01H501Z",
    "data_nascita": "1980-01-01",
    "data_assunzione": "2024-01-15",
    "tipo_contratto": "indeterminato",
    "livello": "3",
    "ccnl_id": "commercio_2024",
    "orario_settimanale": 40,
    "iban": "IT60X0542811101000000123456"
  }'
PUT /api/v1/dipendenti/{id} Aggiorna dipendente

Aggiorna i dati di un dipendente esistente.

cURL 
curl -X PUT https://api.paysuite.it/v1/dipendenti/dip_xyz789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "livello": "4",
    "orario_settimanale": 36
  }'
DELETE /api/v1/dipendenti/{id} Elimina dipendente

Elimina un dipendente dall'anagrafica. L'operazione è irreversibile. I cedolini già elaborati vengono mantenuti per obblighi di legge.

cURL 
curl -X DELETE https://api.paysuite.it/v1/dipendenti/dip_xyz789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Cedolini

Endpoint per la gestione e consultazione dei cedolini elaborati.

GET /api/v1/cedolini Elenco cedolini

Restituisce l'elenco dei cedolini, con filtri per periodo, azienda e dipendente.

Parametro Tipo Descrizione
azienda_id string Filtra per azienda
dipendente_id string Filtra per dipendente
mese string Periodo in formato YYYY-MM
stato string bozza, elaborato, confermato
cURL 
curl -X GET "https://api.paysuite.it/v1/cedolini?azienda_id=az_abc123&mese=2026-03" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
GET /api/v1/cedolini/{id} Dettaglio cedolino

Restituisce il dettaglio completo di un cedolino, inclusi tutti gli elementi retributivi e contributivi.

Risposta (esempio parziale) 
{
  "id": "ced_001",
  "dipendente_id": "dip_xyz789",
  "mese": "2026-03",
  "stato": "confermato",
  "retribuzione_lorda": 2150.00,
  "contributi_inps_dipendente": 197.36,
  "imponibile_irpef": 1952.64,
  "irpef_lorda": 458.92,
  "detrazioni": 145.83,
  "irpef_netta": 313.09,
  "addizionale_regionale": 28.45,
  "addizionale_comunale": 14.22,
  "netto_in_busta": 1597.52
}
GET /api/v1/cedolini/{id}/pdf Download PDF cedolino

Restituisce il PDF del cedolino. Content-Type: application/pdf.

cURL 
curl -X GET https://api.paysuite.it/v1/cedolini/ced_001/pdf \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o cedolino_marzo_2026.pdf

Elaborazione

Endpoint per avviare e monitorare le elaborazioni paghe.

POST /api/v1/elaborazione Avvia elaborazione

Avvia un'elaborazione cedolini per un'azienda e un periodo specificato. L'operazione è asincrona: viene restituito un ID di elaborazione da utilizzare per monitorarne lo stato.

cURL 
curl -X POST https://api.paysuite.it/v1/elaborazione \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "azienda_id": "az_abc123",
    "mese": "2026-03",
    "tipo": "mensile",
    "dipendenti": ["dip_xyz789", "dip_abc456"]
  }'
GET /api/v1/elaborazione/{id} Stato elaborazione

Controlla lo stato di un'elaborazione in corso o completata.

Risposta 
{
  "id": "elab_12345",
  "stato": "completata",
  "progresso": 100,
  "cedolini_elaborati": 15,
  "errori": 0,
  "avvisi": 2,
  "created_at": "2026-03-25T10:30:00Z",
  "completed_at": "2026-03-25T10:31:45Z"
}

Adempimenti

Endpoint per la generazione e gestione degli adempimenti fiscali e previdenziali.

GET /api/v1/adempimenti Elenco adempimenti

Restituisce l'elenco degli adempimenti generati, con filtri per tipo e periodo.

Parametro Tipo Descrizione
tipo string f24, uniemens, cu, mod770
azienda_id string Filtra per azienda
periodo string Periodo di riferimento (YYYY-MM)
cURL 
curl -X GET "https://api.paysuite.it/v1/adempimenti?tipo=f24&periodo=2026-03" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
POST /api/v1/adempimenti/genera Genera adempimento

Genera un adempimento specifico per un'azienda e un periodo.

cURL 
curl -X POST https://api.paysuite.it/v1/adempimenti/genera \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "f24",
    "azienda_id": "az_abc123",
    "periodo": "2026-03"
  }'
GET /api/v1/adempimenti/{id}/download Download adempimento

Scarica il file dell'adempimento in formato PDF o XML (a seconda del tipo).

cURL 
curl -X GET https://api.paysuite.it/v1/adempimenti/adm_f24_001/download \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o f24_marzo_2026.pdf

Codici di Errore

L'API utilizza codici di stato HTTP standard. In caso di errore, il body contiene dettagli aggiuntivi.

Codice Significato Descrizione
400 Bad Request Richiesta non valida (parametri mancanti o errati)
401 Unauthorized Token di autenticazione mancante o non valido
403 Forbidden Permessi insufficienti per l'operazione richiesta
404 Not Found Risorsa non trovata
422 Unprocessable Entity Dati validi sintatticamente ma non processabili
429 Too Many Requests Superato il limite di richieste (rate limiting)
500 Internal Server Error Errore interno del server

Formato errore

JSON 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Il campo 'codice_fiscale' non e' valido.",
    "details": [
      {
        "field": "codice_fiscale",
        "message": "Il codice fiscale deve essere di 16 caratteri."
      }
    ]
  }
}