Vai al contenuto
API REST v1.0

DOCUMENTAZIONE API

Integra Proofy con il tuo ERP o gestionale tramite le nostre API RESTful complete.

Introduzione

Le API di Proofy ti permettono di gestire spedizioni, autisti e documenti di trasporto in modo programmatico. Tutte le API seguono le convenzioni REST e utilizzano JSON per richieste e risposte.

Base URL: /api/v1

Autenticazione

Tutte le API (eccetto /auth/token) richiedono autenticazione via Bearer token JWT.

  1. Ottieni le credenziali API dal pannello admin (Impostazioni > API)
  2. Chiama POST /api/v1/auth/token con api_key e api_secret
  3. Usa il token ricevuto nell'header Authorization: Bearer {token}
Esempio richiesta: 
{
  "api_key": "tk_live_abc123def456",
  "api_secret": "sk_live_xyz789ghi012"
}

Rate Limiting

  • ! 100 richieste/minuto per endpoint
  • ! 1000 richieste/ora totali

Errori

Gli errori seguono il formato standard:

{
  "message": "Descrizione errore",
  "errors": {
    "campo": ["Dettaglio errore"]
  }
}
400 Bad Request - Parametri non validi
401 Unauthorized - Token mancante o non valido
403 Forbidden - Accesso non consentito
404 Not Found - Risorsa non trovata
422 Unprocessable Entity - Errore di validazione
429 Too Many Requests - Rate limit superato

Authentication

POST /auth/token

Ottieni un token JWT di accesso.

Request Body: 
{
  "api_key": "string (required)",
  "api_secret": "string (required)"
}
Response 200: 
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "tenant": {
    "id": 1,
    "name": "Azienda Demo",
    "plan": "professional"
  }
}
POST /auth/refresh

Rinnova un token JWT valido prima della scadenza. Richiede autenticazione.

GET /auth/me

Restituisce le informazioni del tenant autenticato e le quote di utilizzo.

Response 200: 
{
  "id": 1,
  "name": "Azienda Demo",
  "plan": "professional",
  "quota": {
    "shipments_used": 45,
    "shipments_limit": 1000,
    "drivers_used": 2,
    "drivers_limit": 10
  }
}

Shipments

GET /shipments

Restituisce la lista paginata delle spedizioni.

Query Parameters:
  • status - Filtra per stato (unassigned, assigned, in_delivery, completed, not_delivered)
  • date - Filtra per data (YYYY-MM-DD)
  • driver_id - Filtra per ID autista
  • per_page - Risultati per pagina (default: 15, max: 100)
POST /shipments

Crea una nuova spedizione/DDT.

Request Body: 
{
  "document_number": "DDT-2026-001",
  "customer_name": "Ristorante La Pergola",
  "customer_email": "info@lapergola.it",
  "customer_phone": "+39 06 1234567",
  "delivery_address": "Via Roma 123, 00100 Roma RM",
  "scheduled_date": "2026-01-28",
  "scheduled_time": "10:00",
  "notes": "Consegna al piano terra",
  "driver_id": 1,
  "external_id": "ERP-12345"
}
GET /shipments/{'{id}'}

Restituisce i dettagli completi di una spedizione.

PUT /shipments/{'{id}'}

Aggiorna i dati di una spedizione esistente.

DELETE /shipments/{'{id}'}

Elimina una spedizione. Non è possibile eliminare spedizioni già firmate.

GET /shipments/{'{id}'}/status

Restituisce lo stato corrente e la cronologia degli stati.

GET /shipments/{'{id}'}/pod

Restituisce i dati della prova di consegna (firma, PDF, coordinate GPS).

Response 200: 
{
  "signed": true,
  "signatory_name": "Mario Rossi",
  "signatory_role": "Responsabile Magazzino",
  "signed_at": "2026-01-28T10:30:00Z",
  "signature_image_url": "/storage/signatures/...",
  "pdf_url": "/storage/pods/...",
  "gps_latitude": 41.9028,
  "gps_longitude": 12.4964
}

Drivers

GET /drivers

Restituisce la lista degli autisti del tenant.

Query Parameters:
  • active - Filtra per stato attivo (true/false)
POST /drivers

Crea un nuovo autista. Genera automaticamente badge e codice interno.

Request Body: 
{
  "first_name": "Mario",
  "last_name": "Rossi",
  "email": "mario.rossi@email.it",
  "phone": "+39 333 1234567",
  "internal_code": "DRV001",
  "external_id": "ERP-DRV-001"
}
GET /drivers/{'{id}'}

Restituisce i dettagli di un autista.

PUT /drivers/{'{id}'}

Aggiorna i dati di un autista.

DELETE /drivers/{'{id}'}

Disattiva un autista (soft delete).

GET /drivers/{'{id}'}/shipments

Restituisce le spedizioni assegnate a un autista.

Query Parameters:
  • date - Filtra per data (YYYY-MM-DD)
  • status - Filtra per stato

HAI BISOGNO DI AIUTO?

Contattaci per supporto tecnico sull'integrazione API.

CONTATTACI