L'integrazione API per sistemi personalizzati - Integrazioni

L'integrazione API per sistemi personalizzati - Integrazioni | AutoLetter Help Center

Con l'integrazione API puoi trasmettere ordini direttamente dal tuo sistema ad AutoLetter. E ideale per sviluppi personalizzati, sistemi shop individuali o workflow automatizzati che non possono essere gestiti tramite le integrazioni standard (Billbee, Shopify).

Creare l'integrazione

Naviga a Integrazioni, clicca su Aggiungi e seleziona API come tipo di integrazione.

Nominare l'integrazione

Assegna un nome significativo, ad es. "Shop personalizzato API" o "Sistema ERP".

Ottenere le credenziali

Dopo il salvataggio ricevi l'URL dell'endpoint API e puoi generare un token JWT per l'autenticazione.

Il token JWT per l'autenticazione API lo generi nel tuo Workspace in AutoLetter. Conserva questo token in modo sicuro e non condividerlo con persone non autorizzate.

Gli ordini vengono inviati come array JSON tramite una richiesta POST all'endpoint API. L'autenticazione avviene tramite un Bearer JWT-Token nell'header Authorization.

curl -X POST https://api.autoletter.eu/v2/orders \
  -H "Authorization: Bearer IL_TUO_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "OrderNumber": "ORD-2026-001",
      "OrderId": "12345",
      "Date": "2026-02-20T10:30:00Z",
      "Total": 89.99,
      "Address": {
        "FirstName": "Mario",
        "LastName": "Rossi",
        "Street": "Via Roma",
        "HouseNumber": "42",
        "ZIP": "20121",
        "City": "Milano",
        "Country": "IT"
      }
    }
  ]'

Ogni ordine deve contenere i seguenti campi:

Campo	Tipo	Descrizione
`OrderNumber`	String	Il numero d'ordine
`OrderId`	String	Un ID ordine univoco
`Date`	String (ISO 8601)	La data dell'ordine
`Total`	Number	L'importo totale dell'ordine
`Address`	Object

L'oggetto Address contiene l'indirizzo di consegna e deve contenere almeno nome, via, CAP, citta e paese.

Oltre ai campi obbligatori puoi trasmettere i seguenti campi opzionali:

Campo	Tipo	Descrizione
`ExternalId`	String	ID di riferimento esterno dal tuo sistema
`ShopId`	String	Identificativo shop per gestione multi-shop
`InvoiceAddress`	Object	Indirizzo di fatturazione diverso
`LetterAddress`	Object	Indirizzo diverso per la spedizione lettere
`Products`

Per impostazione predefinita vengono creati solo nuovi ordini. Se desideri aggiornare ordini esistenti, aggiungi il parametro allowUpdates alla tua richiesta:

{
  "allowUpdates": true,
  "orders": [...]
}

Con allowUpdates attivato, gli ordini con OrderId corrispondente vengono aggiornati invece di essere rifiutati.

A differenza di Billbee e Shopify, con l'integrazione API non c'e nessun ritardo di sincronizzazione. Gli ordini inviati tramite API sono immediatamente disponibili in AutoLetter e possono essere utilizzati direttamente nelle campagne.

L'API restituisce codici di stato HTTP standardizzati:

200 OK -- Ordini elaborati con successo
400 Bad Request -- Dati errati (dettagli nel corpo della risposta)
401 Unauthorized -- Token JWT non valido o mancante
429 Too Many Requests -- Limite di frequenza raggiunto

In caso di errori, la risposta contiene informazioni dettagliate sui record interessati.