🚛 CAF Jesi - Guida Sviluppo Client API

📋 Panoramica

L'API CAF Jesi Carico Gestionale consente l'upload sicuro di file CSV contenenti dati di carichi di merce e relative DDT di accompagno. Questo documento fornisce tutte le informazioni tecniche necessarie per sviluppare un client di integrazione.

🔗 Endpoint API

🔐 Autenticazione

L'API utilizza un sistema di autenticazione basato su API Key. La chiave deve essere fornita in ogni richiesta.

Come Ottenere le Chiavi API

Per ottenere le chiavi API valide:

1. Contattare l'amministratore del sistema CAF Jesi
2. Richiedere l'accesso specificando:
   • Nome dell'azienda/organizzazione
   • Scopo dell'integrazione
   • Responsabile tecnico del progetto
3. Ricevere le credenziali tramite canale sicuro

Formato Chiavi API

Le chiavi API hanno il seguente formato:

• Lunghezza: 32-64 caratteri alfanumerici
• Formato esempio: your-api-key-here-1234567890abcdef
• Prefisso: Solitamente iniziano con identificativo CAF

📤 Parametri di Richiesta

Metodo di Invio

• Content-Type: multipart/form-data
• Metodo HTTP: POST

📁 Specifiche File CSV

Formato Supportato

• Estensione: .csv
• Encoding: UTF-8 (raccomandato)
• Separatore: Virgola (,)
• Dimensione massima: 10 MB

Validazioni

• Il file deve contenere almeno 2 colonne
• Il file non deve essere vuoto
• MIME type accettati: text/csv, text/plain, application/csv

Esempio Struttura CSV

Codice_Carico,Data_Carico,Destinatario,Peso_Kg,Numero_DDT,Data_DDT
C001,2025-01-15,Azienda XYZ Srl,1250.5,DDT001,2025-01-15
C002,2025-01-15,Ditta ABC Snc,890.0,DDT002,2025-01-15

📨 Formato Risposte

Risposta di Successo (HTTP 200)

{
    "success": true,
    "message": "File caricato con successo",
    "data": {
        "filename": "carichi_20250724_143022_a1b2c3d4.csv",
        "original_name": "carichi.csv",
        "size": 2048,
        "description": "Carichi gennaio 2025",
        "upload_path": "/path/to/uploads/carichi_20250724_143022_a1b2c3d4.csv",
        "upload_time": "2025-07-24 14:30:22"
    },
    "timestamp": "2025-07-24 14:30:22"
}

Risposta di Errore

{
    "success": false,
    "error": "Descrizione dell'errore",
    "timestamp": "2025-07-24 14:30:22"
}

Codici di Stato HTTP

💻 Esempi di Implementazione

<?php
function uploadFileToCAF($filePath, $description = '') {
    // IMPORTANTE: Sostituire con la chiave API reale ottenuta da CAF Jesi
    $apiKey = $_ENV['CAF_API_KEY'] ?? 'your-api-key-here';
    $apiUrl = 'https://caricogestionale.caf-jesi.it/api.php';
    
    $ch = curl_init();
    
    curl_setopt_array($ch, [
        CURLOPT_URL => $apiUrl,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => [
            'api_key' => $apiKey,
            'file' => new CURLFile($filePath),
            'description' => $description
        ],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_SSL_VERIFYPEER => true
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    return [
        'http_code' => $httpCode,
        'response' => json_decode($response, true)
    ];
}

// Utilizzo
$result = uploadFileToCAF('/path/to/carichi.csv', 'Carichi gennaio 2025');
if ($result['response']['success']) {
    echo "Upload completato: " . $result['response']['data']['filename'];
} else {
    echo "Errore: " . $result['response']['error'];
}
?>

using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;
using Newtonsoft.Json;

public class CAFApiClient
{
    private readonly HttpClient _httpClient;
    private readonly string _apiKey = "caf-jesi-2025-api-key-1234567890abcdef";
    private readonly string _apiUrl = "https://caricogestionale.caf-jesi.it/api.php";

    public CAFApiClient()
    {
        _httpClient = new HttpClient();
    }

    public async Task<ApiResponse> UploadFileAsync(string filePath, string description = "")
    {
        using var form = new MultipartFormDataContent();
        form.Add(new StringContent(_apiKey), "api_key");
        form.Add(new StringContent(description), "description");
        
        var fileContent = new ByteArrayContent(File.ReadAllBytes(filePath));
        fileContent.Headers.ContentType = 
            new System.Net.Http.Headers.MediaTypeHeaderValue("text/csv");
        form.Add(fileContent, "file", Path.GetFileName(filePath));

        var response = await _httpClient.PostAsync(_apiUrl, form);
        var jsonResponse = await response.Content.ReadAsStringAsync();
        
        return JsonConvert.DeserializeObject<ApiResponse>(jsonResponse);
    }
}

public class ApiResponse
{
    public bool Success { get; set; }
    public string Message { get; set; }
    public string Error { get; set; }
    public FileData Data { get; set; }
    public DateTime Timestamp { get; set; }
}

import requests
import json

class CAFApiClient:
    def __init__(self):
        self.api_key = "caf-jesi-2025-api-key-1234567890abcdef"
        self.api_url = "https://caricogestionale.caf-jesi.it/api.php"
    
    def upload_file(self, file_path, description=""):
        """
        Carica un file CSV tramite API
        
        Args:
            file_path (str): Percorso del file CSV
            description (str): Descrizione opzionale
            
        Returns:
            dict: Risposta dell'API
        """
        try:
            with open(file_path, 'rb') as file:
                files = {'file': file}
                data = {
                    'api_key': self.api_key,
                    'description': description
                }
                
                response = requests.post(
                    self.api_url,
                    data=data,
                    files=files,
                    timeout=30
                )
                
                return {
                    'status_code': response.status_code,
                    'response': response.json()
                }
                
        except requests.exceptions.RequestException as e:
            return {
                'status_code': 0,
                'error': str(e)
            }

# Utilizzo
client = CAFApiClient()
result = client.upload_file('/path/to/carichi.csv', 'Carichi gennaio 2025')

if result['response']['success']:
    print(f"Upload completato: {result['response']['data']['filename']}")
else:
    print(f"Errore: {result['response']['error']}")

🛠️ Gestione Errori e Best Practice

Gestione Errori Comuni

{"success": false, "error": "Chiave API non valida o mancante."}

{"success": false, "error": "Estensione file non consentita. Estensioni consentite: csv"}

Best Practice di Sviluppo

🧪 Testing e Debug

Test dell'Integrazione

1. Test connettività: Verificare che l'endpoint sia raggiungibile
2. Test autenticazione: Provare con chiavi valide e non valide
3. Test file: Provare con file di diverse dimensioni e formati
4. Test errori: Simulare scenari di errore

Endpoint di Test

Per verificare che l'API sia attiva:

File di Test

Un file CSV di esempio è disponibile:

🔧 Supporto e Troubleshooting

Problemi Comuni