Documentazione API

In breve

L'API REST di Shipper collega il vostro negozio online, il vostro ERP o il vostro software logistico al vostro conto Shipper. Permette di:

• ottenere con una sola richiesta le offerte di più corrieri;
• ordinare la spedizione a partire dall'offerta scelta;
• scaricare le etichette, la fattura e i documenti doganali;
• seguire e annullare una spedizione.

Siete voi ad aprire gli accessi dal vostro conto Shipper. Il vostro sviluppatore realizza l'integrazione in un ambiente di prova, la sandbox, poi passate in produzione.

Avvio in 4 passi

1. Invitate il vostro sviluppatore nella sandbox

   In Dati del conto › API, sezione «Accesso all'ambiente di sviluppo», indicate l'indirizzo e-mail del vostro sviluppatore. Riceve un invito, sceglie la sua password e accede alla sandbox con questo indirizzo.

   La sandbox è interamente fittizia: il vostro sviluppatore non ha accesso né al vostro conto né ai vostri dati. Per togliergli l'accesso, eliminate il suo indirizzo; per affidare la sandbox a un'altra persona, sostituitelo. La persona rimossa viene avvisata per e-mail.

2. Sviluppate e testate

   Nella sandbox, il vostro sviluppatore inserisce un indirizzo di fatturazione, aggiunge crediti (pagamenti fittizi), poi crea la sua chiave in Dati del conto › API. Può quindi chiedere preventivi e ordinare spedizioni di prova, senza spedire nulla.

3. Chiedete il passaggio in produzione

   Quando l'integrazione è pronta, aprite Dati del conto › API nel vostro conto Shipper e cliccate su «Richiesta di avvio della produzione». Un ticket accompagna la richiesta; contate da 48 a 72 ore. Sarete avvisati non appena l'accesso è attivo.

4. Create le vostre chiavi di produzione

   Una volta attivo l'accesso, «Aggiungere una chiave» genera una chiave con la sua password. La password viene mostrata una sola volta: annotatela, altrimenti dovrete creare una nuova chiave.

   Ogni chiave può essere limitata a un elenco di indirizzi IP, modificabile in seguito. Potete creare tutte le chiavi necessarie, per esempio una per sistema.

Server

Le chiavi valgono solo nel loro ambiente: una chiave della sandbox non funziona in produzione.

Autenticazione

Ogni richiesta si autentica in HTTP Basic con la chiave e la sua password: intestazione Authorization: Basic seguita da chiave:password codificato in base64. Gli strumenti HTTP lo fanno per voi:

curl -u "VOSTRA_CHIAVE:VOSTRA_PASSWORD" \
     -H "Accept: application/json" \
     https://api.sandbox.shipper.ch/quotation/12345

Una chiave limitata a indirizzi IP rifiuta le richieste provenienti da altrove. Tenete la password sul vostro server: mai nel JavaScript di una pagina web né in un'applicazione installata presso i vostri clienti.

Svolgimento di una spedizione

1. Preventivo: inviate mittente, destinatario e colli a POST /quotation. La risposta contiene un quotationId e le offerte dei corrieri.
2. Scelta: scegliete l'offerta che fa per voi (il suo quoteId).
3. Ordine: POST /order con il quoteId, la data di ritiro e, se la spedizione passa la dogana, gli articoli doganali.
4. Documenti: GET /order/{orderId}/document/{type} restituisce il file: labels (etichette), invoice (fattura) o customs (dogana).
5. Tracciamento: GET /order/{orderId}/tracking.

Route

• POST /quotation Creare un preventivo (offerte di più corrieri)
• GET /quotation/{quotationId} Rileggere un preventivo
• POST /order Ordinare una spedizione a partire da un'offerta
• GET /order/{orderId} Rileggere un ordine
• GET /order/{orderId}/tracking Seguire la spedizione
• GET /order/{orderId}/document/{type} Scaricare un documento
• GET /order/{orderId}/cancel Annullare l'ordine

Campi, valori ammessi ed esempi completi: riferimento dell'API.

Richieste e risposte

Le richieste POST inviano un corpo JSON (Content-Type: application/json); le richieste GET passano i loro parametri nell'indirizzo. Chiedete JSON in risposta con Accept: application/json.

Tranne che per un documento scaricato (il corpo è allora il file), la risposta è un oggetto JSON che contiene sempre header: error ed endpoint, più errorCode, errorMessage ed errorField in caso di errore. Il codice HTTP indica il risultato:

Riferimenti prodotto per l'UE

Per una spedizione dalla Svizzera (o da un altro paese fuori dall'UE) a un privato nell'UE, l'UE richiede due riferimenti per articolo doganale:

• merchantProductId: il vostro codice articolo (SKU);
• manufacturerProductId: il codice del fabbricante (modello o numero del pezzo). Se fabbricate voi il prodotto, riprendete il vostro codice articolo.

standardProductId (codice GTIN o EAN) è facoltativo. Il destinatario è un privato quando quotation.to.isCompany vale false.

Nella vostra area clienti

I preventivi chiesti tramite l'API compaiono nei vostri preventivi, con mittente, destinatario e tariffe proposte. Le spedizioni ordinate tramite l'API compaiono nelle vostre spedizioni, contrassegnate «API», e un filtro le separa dalle spedizioni fatte sul sito.

Aiuto

Una domanda sull'integrazione? Aprite un ticket dal vostro conto o scriveteci a E-mail: il nostro team tecnico vi risponde.