Questa guida spiega passo dopo passo come richiedere le credenziali di accesso API ai vettori marittimi (Maersk, CMA CGM, COSCO, Hapag-Lloyd, ecc.) e a sistemi esterni simili, e come registrarle in heyAtlas.
1. Quando ti servono?
Gli strumenti di heyAtlas come ricerca noli, tracciamento container/nave, recupero tariffe e booking si collegano all'API del vettore per conto della tua azienda. Questa connessione richiede le credenziali API che il vettore rilascia specificamente a te. Senza credenziali gli strumenti correlati non possono funzionare e l'assistente ti chiederà i dettagli di connessione.
2. A chi chiedere e come
- Il primo contatto è il referente account o il referente commerciale della tua azienda presso il vettore.
- Nella maggior parte dei grandi vettori, la richiesta viene inoltrata al team integrazione/IT tramite il tuo referente.
- Nella richiesta indica: il caso d'uso (es. richiesta noli, tracciamento container), l'ambiente necessario (test/produzione) e il tuo codice cliente.
Modello email di richiesta da copiare e incollare
Oggetto: Richiesta accesso API / integrazione — [Nome Azienda], cliente n.: [XXXX]
Salve,
In [Nome Azienda] gestiamo le nostre operazioni tramite il nostro assistente digitale. Potreste condividere le credenziali di accesso API a noi assegnate (nome utente / chiave API, URL endpoint e codice cliente se applicabile)? Il nostro caso d'uso: [ricerca noli / tracciamento container / booking]. Vorremmo prima i dettagli dell'ambiente di test e, dopo la validazione, le credenziali di produzione.
Vi chiediamo di condividere password e chiavi tramite un canale sicuro invece che nel corpo dell'email.
Grazie.
3. Cosa chiedere
| Voce | Note |
|---|
| Nome utente API / Client ID | Identità di accesso |
| Password API / chiave / Client Secret | Valore segreto — deve essere condiviso tramite un canale sicuro |
| URL endpoint | Gli indirizzi di test e produzione possono essere diversi |
| Codice cliente | Obbligatorio presso alcuni vettori |
| Ambiente | Test (sandbox) o produzione |
| Restrizione IP | Se il vettore applica una allowlist IP, è necessario aggiungere gli IP di heyAtlas |
4. Suggerimenti specifici per vettore
- Vettori con portale sviluppatori self-service (es. Maersk, CMA CGM, Hapag-Lloyd): puoi registrarti nel portale sviluppatori del vettore per conto della tua azienda, creare un'applicazione e generare la tua chiave. L'approvazione può richiedere alcuni giorni lavorativi.
- Vettori con processo manuale: si compila un modulo tramite il tuo referente; il team integrazione fornisce le chiavi.
- Non è necessario sapere quale tipo di autenticazione (API Key, OAuth2, ecc.) usa ciascun vettore; la definizione di sistema di heyAtlas applica automaticamente il metodo corretto. Il tuo compito è semplicemente inserire in modo completo i dettagli forniti dal vettore.
5. Inserimento dei dettagli in heyAtlas
- Apri Impostazioni → Credenziali nel portale (richiesto permesso di amministratore aziendale).
- Seleziona il sistema pertinente (vettore) e compila i campi forniti dal vettore.
- Puoi definire credenziali multiple per lo stesso sistema e contrassegnarne una come predefinita (es. codici cliente diversi).
- Dopo il salvataggio, verifica la connessione provando lo strumento correlato tramite l'assistente.
Vedi anche: Gestione delle credenziali e Connessioni di sistema.
6. Sicurezza
- Evita di ricevere password e chiavi come testo in chiaro nel corpo dell'email; preferisci un link di condivisione sicuro.
- heyAtlas archivia le credenziali in forma crittografata e non le mostra mai come testo in chiaro a schermo.
- Se sospetti una perdita, chiedi al vettore di ruotare la chiave e aggiorna il nuovo valore in heyAtlas.
- Vedi anche: Sicurezza delle credenziali.
7. Problemi comuni
- Errori 401 / 403: la password potrebbe essere stata digitata in modo errato, essere scaduta o l'account non ancora attivato. Reinserisci i dettagli; se il problema persiste, fai verificare al tuo referente.
- Confusione test / produzione: una chiave di test non funziona con l'endpoint di produzione (o viceversa). Controlla di aver inserito i dettagli dell'ambiente corretto.
- "Accesso concesso" ma non funziona nulla: alcuni vettori attivano gli abbonamenti API per prodotto (es. solo tracking); chiedi quali prodotti copre il tuo abbonamento.
- Blocco IP: se il vettore applica restrizioni IP, l'IP da cui heyAtlas effettua le chiamate deve essere inserito in allowlist; puoi richiedere i dettagli IP al nostro team di supporto.
8. Ottenere aiuto
Se il processo si blocca, apri un ticket di supporto tramite Supporto → I miei ticket; è sufficiente indicare di quale vettore si tratta e in quale passaggio sei bloccato.
