API REFERENCE

Integra Proofy con il tuo ERP, gestionale o qualsiasi sistema esterno tramite le nostre API REST. Documentazione completa con esempi pratici.

AUTENTICAZIONE

Le API utilizzano autenticazione Bearer Token (JWT). Per ottenere un token valido:

POST /auth/token
Content-Type: application/json

{
  "api_key": "your_api_key",
  "api_secret": "your_api_secret"
}

Risposta:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Includi il token in tutte le richieste successive:

Authorization: Bearer {access_token}

ENDPOINTS PRINCIPALI

Spedizioni

METODO	ENDPOINT	DESCRIZIONE
GET	/shipments	Lista spedizioni (paginata)
POST	/shipments	Crea nuova spedizione
GET	/shipments/{id}	Dettaglio singola spedizione
PUT	/shipments/{id}	Aggiorna spedizione esistente
DELETE	/shipments/{id}	Elimina spedizione
GET	/shipments/{id}/status	Stato attuale e storico
GET	/shipments/{id}/pod	Download prova di consegna (PDF)

Autisti

METODO	ENDPOINT	DESCRIZIONE
GET	/drivers	Lista autisti
POST	/drivers	Crea nuovo autista
GET	/drivers/{id}	Dettaglio autista
PUT	/drivers/{id}	Aggiorna autista
DELETE	/drivers/{id}	Disattiva autista
GET	/drivers/{id}/shipments	Spedizioni assegnate all'autista

ESEMPIO: CREARE UNA SPEDIZIONE

POST /shipments
Authorization: Bearer {token}
Content-Type: application/json

{
  "document_number": "DDT-2026-001",
  "customer_name": "Acme Srl",
  "customer_email": "info@acme.it",
  "customer_phone": "+39 02 1234567",
  "delivery_address": "Via Roma 1, 20100 Milano MI",
  "scheduled_date": "2026-01-29",
  "scheduled_time": "10:00:00",
  "driver_id": 5,
  "notes": "Chiamare 10 minuti prima dell'arrivo",
  "external_id": "ERP-ORDER-12345"
}

Risposta (201 Created):

{
  "id": 123,
  "document_number": "DDT-2026-001",
  "status": "assigned",
  "customer_name": "Acme Srl",
  "delivery_address": "Via Roma 1, 20100 Milano MI",
  "scheduled_date": "2026-01-29",
  "driver": {
    "id": 5,
    "name": "Mario Rossi"
  },
  "created_at": "2026-01-28T15:30:00Z",
  "updated_at": "2026-01-28T15:30:00Z"
}

WEBHOOK

Configura i webhook per ricevere notifiche in tempo reale. I webhook sono disponibili nei piani Pro e Enterprise.

Eventi disponibili

EVENTO	DESCRIZIONE
shipment.created	Nuova spedizione creata
shipment.status_changed	Cambio di stato della spedizione
shipment.completed	Consegna completata con successo
shipment.failed	Consegna non riuscita
signature.acquired	Firma digitale acquisita
document.uploaded	Nuovo documento caricato

Payload esempio

{
  "event": "shipment.completed",
  "timestamp": "2026-01-28T16:45:00Z",
  "data": {
    "shipment_id": 123,
    "document_number": "DDT-2026-001",
    "status": "completed",
    "completed_at": "2026-01-28T16:44:30Z",
    "signature": {
      "signer_name": "Luigi Bianchi",
      "signer_role": "Magazziniere"
    },
    "location": {
      "lat": 45.4642,
      "lng": 9.1900
    }
  }
}

RATE LIMITING

Per garantire la stabilità del servizio, le API hanno limiti di richieste:

PIANO	RICHIESTE/MINUTO
Free	60
Pro	300
Enterprise	1.000

Quando superi il limite, ricevi una risposta 429 Too Many Requests. Attendi e riprova con backoff esponenziale.

CODICI DI ERRORE

CODICE	DESCRIZIONE	SOLUZIONE
400	Bad Request	Verifica i parametri inviati
401	Unauthorized	Token mancante, scaduto o non valido
402	Payment Required	Quota mensile superata
403	Forbidden	Non hai i permessi per questa risorsa
404	Not Found	Risorsa non trovata
429	Too Many Requests	Rate limit superato, attendi e riprova
500	Internal Error	Errore lato server, contatta il supporto

DOCUMENTAZIONE COMPLETA

Per la documentazione API interattiva con tutti gli endpoint, parametri e possibilità di test: