Come connettere Energo a ShippyPro

Energo è un corriere italiano specializzato nella consegna a domicilio di grandi elettrodomestici e articoli ingombranti, con consegna al piano su appuntamento e ritiro dell'elettrodomestico sostituito (WEE/RAEE). È integrato tramite la piattaforma Bluelinks EDI API V2. ✨

Sommario:

Prima di iniziare
Configurazione corriere
Opzioni aggiuntive
Errori & Risoluzioni

1. Prima di iniziare

Per procedere con la connessione, avrai bisogno di una API Key fornita da Energo/Bluelinks. La chiave viene validata in tempo reale al momento del salvataggio della configurazione su ShippyPro.

⚠️ Importante: L'endpoint di produzione non è ancora disponibile. Energo non ha ancora fornito l'host di produzione e la relativa API Key. Fino a quel momento, il connettore può essere utilizzato solo in modalità Test. Tentare di salvare una configurazione con la modalità Test disattivata restituirà un errore esplicito.

Contatta Energo per ottenere la tua API Key e per essere informato quando l'ambiente di produzione sarà disponibile.

2. Configurazione corriere

Accedi alla sezione Corrieri e seleziona il logo di Energo. Puoi trovarlo rapidamente digitando "Energo" nella barra di ricerca. Una volta individuato, clicca per collegare il corriere e compila i campi richiesti:

Label Un soprannome libero per questa configurazione, visibile nella lista corrieri di ShippyPro. Utile se hai più di un account Energo.

API Key La chiave fornita da Energo/Bluelinks. Validata in tempo reale al salvataggio.

Service S01 — Consegna al piano (su appuntamento). Attualmente l'unico servizio disponibile.

Test mode Deve essere attiva fino a quando Energo non fornirà l'host e la API Key di produzione.

3. Opzioni aggiuntive

Destinazioni

Nazionale: Solo Italia
Internazionale: NO

Opzioni

Label PDF: Disponibile (solo A5 — una pagina per collo in un unico PDF)
Label ZPL: NO
Label EPL: NO
Track & Trace: Disponibile
Paperless: NO
PickUp/DropOff (PUDO): NO
Cash On Delivery: Disponibile
Live Rates: NO
Return Labels: Disponibile
Return Labels (in the box): NO
Book/Schedule Pickup: NO
Address Check: NO
Carrier Options: Disponibile
Proof Of Delivery (POD): NO
Insurance: Disponibile (valore dichiarato in EUR, stampato sulla bolla del collo principale)
Multiparcel: Disponibile
Delete Shipment (Void): NO
CloseOut: NO
CN22: NO
CN23: NO
Credentials Validation: Disponibile (verifica live al salvataggio, solo per configurazioni in test)

Opzioni corriere

Nome	Slug	Tipo	Descrizione
Order type	order_type	select	Sovrascrive il tipo di ordine calcolato dal connettore. Valori accettati: C (consegna), R (reso), RR (ritiro WEE/RAEE dal cliente finale), RP (ritiro WEE/RAEE dal punto vendita). Nota: S (swap) non è abilitato dal corriere e verrà rifiutato.
Good type	good_type	text	Classificazione della merce inviata su ogni collo, es. LAVATRICE, FRIGORIFERO. Deve corrispondere a uno dei valori presenti nella lista del corriere. Se vuoto, il connettore usa la descrizione dell'ordine, poi ALTRI ACCESSORI come fallback.
Additional services	services	text	Codici servizio aggiuntivi, separati da virgola, aggiunti al servizio configurato — es. S03,S10. Solo S01 è stato verificato; la lista completa dei codici accettati è in attesa di conferma da parte di Energo.

Servizi corriere

Codice servizio	Nome servizio	Particolarità
S01	Consegna al piano	Consegna su appuntamento. Unico servizio verificato e quello applicato di default dal corriere quando nessun servizio viene specificato.

⚠️ Nota: Il codice servizio "CB" (Consegna bordostrada) non esiste come codice servizio valido. Inviare services=CB verrà rifiutato dal corriere con "Il tipo di servizio CB è sconosciuto". Non utilizzarlo senza conferma scritta da parte di Energo.

Contrassegno (Cash on Delivery)

Il contrassegno è supportato con cinque modalità di pagamento:

Codice	Descrizione
C	Contanti (default)
AB	Assegno bancario alla GDO
AC	Assegno circolare alla GDO
ABT	Assegno bancario al corriere
ACT	Assegno circolare al corriere

Nota: l'importo del contrassegno viene accettato dall'API ma non viene stampato sulla bolla di consegna.

Spedizioni di reso

Le etichette di reso sono supportate (order_type=R). Nel caso di un reso, il cliente è il mittente e il magazzino del merchant è la destinazione. Un singolo ordine di reso può essere indirizzato a più magazzini.

Tracking

Il tracking è supportato tramite polling. Stati disponibili:

Codice	Descrizione
0	Aperto
1	GIT — In transito
2	In Tpoint — All'hub per l'ultimo miglio
3	Prenotato — Appuntamento fissato
4	Consegnato
110	In stock all'hub
900	Non consegnato

4. Errori & Risoluzioni

Durante il tentativo di connessione o durante la spedizione dei tuoi ordini, potresti riscontrare alcuni errori. Niente panico!

Host di produzione non disponibile

L'endpoint di produzione non è ancora stato fornito da Energo. Tentare di salvare una configurazione con la modalità Test disattivata restituirà un errore esplicito. Mantieni la modalità Test attiva fino a quando Energo non fornirà l'host e la API Key di produzione.

Duplicated order_number

Ogni ordine deve avere un riferimento univoco. Se lo stesso numero ordine viene inviato due volte, il corriere restituisce "Duplicated order_number". I retry sulle spedizioni fallite sono disabilitati per questo motivo — verifica i riferimenti degli ordini prima di reinviare.

Please wait until the last execution is completed

La piattaforma Bluelinks serializza le chiamate per API Key. Se una richiesta precedente è ancora in elaborazione, tutte le richieste successive — incluse le letture — vengono rifiutate con questo messaggio. Attendi il completamento dell'esecuzione in corso prima di riprovare. Se l'account rimane bloccato, contatta Energo.

Tipo ordine S (swap) rifiutato

Il tipo di ordine swap non è abilitato dal corriere. Inviare order_type=S restituirà un errore. Utilizza i valori supportati: C, R, RR o RP.

Indirizzo o CAP non valido

Il corriere non valida gli indirizzi alla creazione dell'ordine — un CAP o un comune errato produrrà comunque una bolla di consegna. ShippyPro esegue i propri controlli sull'indirizzo prima di inviare l'ordine. Assicurati che il CAP e il comune di destinazione siano valori italiani corretti.