Documentazione API

Integra le funzionalità di Shippidu direttamente nel tuo sistema.

Introduzione

Le API REST di Shippidu permettono di gestire ordini, spedizioni e corrieri in modo programmatico. Tutte le risposte sono nel formato standard JSON.

Base URL: https://app.shippidu.com/api/v1
Encoding: UTF-8
Format: application/json

Autenticazione

L'autenticazione avviene tramite Bearer Token nell'header della richiesta. Puoi generare le chiavi API direttamente dal pannello impostazioni di Shippidu.

Authorization: Bearer shpd_sk_test_123456789

POST/api/v1/orders

Crea un nuovo ordine nel sistema. Il corriere viene assegnato automaticamente se sono configurate regole di spedizione.

Scope richiesto: orders:write

Request

POST https://app.shippidu.com/api/v1/orders
Authorization: Bearer shpd_sk_your_key
Content-Type: application/json

Body di esempio:

{
  "externalId": "ORD-12345",
  "buyerName": "Mario Rossi",
  "buyerEmail": "mario@esempio.it",
  "buyerUsername": "mario_rossi_99",
  "paymentStatus": "pagato",
  "total": 49.99,
  "currency": "EUR",
  "orderDate": "2026-03-09T10:00:00Z",
  "shipByDate": "2026-03-11T10:00:00Z",
  "items": [
    {
      "title": "Prodotto A",
      "sku": "SKU-001",
      "quantity": 2,
      "unitPrice": 24.99,
      "imageUrl": "https://cdn.esempio.it/prodotto-a.jpg",
      "shipByDate": "2026-03-11T10:00:00Z"
    }
  ],
  "shippingAddress": {
    "recipientName": "Mario Rossi",
    "address1": "Via Roma 1",
    "address2": "Interno 3",
    "city": "Milano",
    "province": "MI",
    "postalCode": "20121",
    "countryCode": "IT",
    "phone": "+39 02 1234567",
    "email": "mario@esempio.it"
  }
}

Campi — radice

Campo	Tipo	Richiesto	Descrizione
buyerName	string	OBBLIGATORIO	Nome e cognome dell'acquirente
total	number	OBBLIGATORIO	Importo totale (positivo)
items	array	OBBLIGATORIO	Minimo 1 articolo
shippingAddress	object	OBBLIGATORIO	Indirizzo di spedizione
externalId	string	opzionale	ID ordine nel tuo sistema. Se omesso viene generato automaticamente
buyerEmail	string	opzionale	Email dell'acquirente
buyerUsername	string	opzionale	Username/nickname dell'acquirente sul canale originale (es. nick eBay, handle Shopify)
paymentStatus	string (enum)	opzionale	Stato del pagamento. Valori: in_attesa, pagato, fallito, rimborsato. Default: pagato
orderDate	string ISO8601	opzionale	Data ordine. Default: ora corrente
shipByDate	string ISO8601	opzionale	Data entro cui spedire l'intero ordine
currency	string 3 char	opzionale	Codice valuta ISO 4217. Default: EUR

Campi — items[]

Campo	Tipo	Richiesto	Descrizione
title	string	OBBLIGATORIO	Nome del prodotto
quantity	integer	OBBLIGATORIO	Quantità (minimo 1)
unitPrice	number	OBBLIGATORIO	Prezzo unitario (maggiore o uguale a 0)
sku	string	opzionale	Codice SKU del prodotto
imageUrl	string URL	opzionale	URL immagine del prodotto (deve usare https://). Mostrata nel dashboard
shipByDate	string ISO8601	opzionale	Data spedizione prevista per questo specifico articolo

Campi — shippingAddress

Campo	Tipo	Richiesto	Descrizione
recipientName	string	OBBLIGATORIO	Nome del destinatario
address1	string	OBBLIGATORIO	Indirizzo principale
city	string	OBBLIGATORIO	Città
postalCode	string	OBBLIGATORIO	CAP
countryCode	string 2 char	OBBLIGATORIO	Codice paese ISO 3166-1 alpha-2 (es. IT)
address2	string	opzionale	Indirizzo secondario (interno, scala, ecc.)
province	string	opzionale	Provincia o stato
phone	string	opzionale	Telefono del destinatario
email	string	opzionale	Email del destinatario, usata dai corrieri per notifiche di consegna

Response 201 Created

{
  "data": {
    "id": 1042,
    "externalId": "ORD-12345",
    "marketplace": "api",
    "status": "da_spedire",
    "paymentStatus": "pagato",
    "buyerName": "Mario Rossi",
    "buyerEmail": "mario@esempio.it",
    "buyerUsername": "mario_rossi_99",
    "total": "49.99",
    "currency": "EUR",
    "carrierIntegrationId": 3,
    "orderDate": "2026-03-09T10:00:00.000Z",
    "shipByDate": "2026-03-11T10:00:00.000Z",
    "shippingAddress": {
      "recipientName": "Mario Rossi",
      "address1": "Via Roma 1",
      "city": "Milano",
      "postalCode": "20121",
      "countryCode": "IT",
      "email": "mario@esempio.it"
    },
    "items": [
      {
        "title": "Prodotto A",
        "sku": "SKU-001",
        "quantity": 2,
        "unitPrice": "24.99",
        "imageUrl": "https://cdn.esempio.it/prodotto-a.jpg",
        "shipByDate": "2026-03-11T10:00:00.000Z"
      }
    ]
  }
}

carrierIntegrationId — presente se il merchant ha regole di spedizione configurate e una di esse corrisponde all'ordine. Se null, il corriere può essere assegnato manualmente dal dashboard.

buyerUsername — corrisponde al campo externalUsername nel sistema interno. Utile per tracciare ordini migrati da altri marketplace o sistemi esterni.

paymentStatus — se omesso nella richiesta, il valore predefinito è "pagato".

GET/orders

Recupera una lista paginata di ordini.

Query Parameters

page (int) - Numero di pagina (default 1)
limit (int) - Elementi per pagina (max 100)
status (string) - Filtra per stato (es. 'shipped')

curl -G https://app.shippidu.com/api/v1/orders \
  -H "Authorization: Bearer shpd_sk_your_key" \
  -d "limit=10&status=pending"

GET/orders/:id

Recupera i dettagli completi di un singolo ordine specifico.

PATCH/orders/:id

Aggiorna uno o più campi di un ordine esistente.

curl -X PATCH https://app.shippidu.com/api/v1/orders/ord_123 \
  -H "Authorization: Bearer shpd_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "status": "annullato" }'

Errori

L'API usa i codici di stato HTTP convenzionali per indicare il successo o il fallimento di una richiesta.

Codice	Significato
400	Bad Request – Parametri non validi
401	Unauthorized – Token non valido o mancante
403	Forbidden – Scope insufficiente
404	Not Found – Risorsa non trovata
429	Too Many Requests – Rate limit superato
500	Server Error – Errore interno

Rate Limits

Per garantire stabilità al servizio, applichiamo un limite di 1.000 richieste per ora per singola chiave API. In caso di superamento, l'API risponderà con un codice 429.

Scopes

Quando generi una chiave API, puoi limitare il suo accesso associando specifici scope. Attualmente supportiamo:

orders:read - Permette di leggere ordini.
orders:write - Permette di creare o modificare ordini.