Queste risposte riguardano le domande tecniche più comuni sull'integrazione con l'API dei dati valutari. Per ogni endpoint e parametro, consulta la documentazione dell'API. Per una panoramica dei nostri tassi, consulta Come funziona l'API dei dati valutari?

In questo articolo

• Quale endpoint devo usare per ogni tipo di tasso?
• Come posso ottenere l'elenco completo delle valute?
• Quali coppie di valute supporta l'endpoint bid e ask?
• Come gestisce l'API le valute obsolete?
• Come posso ottenere i tassi bid e ask da una banca centrale?
• Perché un tasso di una banca centrale sembra essere del giorno precedente?
• Posso memorizzare nella cache i tassi dell'API?
• Come posso ottenere il tasso di un giorno passato all'orario di blocco?
• Come posso trovare il certificato SSL dell'API?
• Perché ricevo timeout o errori 500?
• Devo inserire gli indirizzi IP in una allow-list?
• Perché ricevo errori 401 o 403?

Quale endpoint devo usare per ogni tipo di tasso?

I tassi delle criptovalute provengono dai nostri tassi mid-market, quindi devi richiederli tramite gli endpoint mid-market. Aggiungi crypto=true alla richiesta per includerli.

Come posso ottenere l'elenco completo delle valute?

Usa l'endpoint /v2/currencies. Per ogni valuta, mostra:

• se si tratta di un codice ISO 4217
• la data di introduzione e, se è obsoleta, la data di ritiro
• le date di inizio e fine dei nostri tassi per la valuta
• la valuta che l'ha sostituita ed eventuali ancoraggi

Per impostazione predefinita, l'elenco include le valute attive e obsolete. Per modificare questa impostazione:

• aggiungi obsolete=true per mostrare solo le valute obsolete per le quali disponiamo di dati storici
• aggiungi obsolete=false per sostituire le valute obsolete con la valuta che le ha sostituite

Quali coppie di valute supporta l'endpoint bid e ask?

L'endpoint /v1/bid_ask supporta AUD, BRL, CAD, CHF, CNH, DKK, EUR, GBP, JPY, NOK, NZD, PLN, SEK e USD.

Puoi richiedere qualsiasi coppia in entrambe le direzioni, ad eccezione delle seguenti coppie con CNH (yuan cinese offshore):

• CNH non è disponibile con BRL, DKK o PLN, in nessuna delle due direzioni.
• CNH è disponibile solo come valuta di destinazione con NOK e SEK. Ad esempio, puoi richiedere from=NOK&to=CNH, ma non from=CNH&to=NOK.

Come gestisce l'API le valute obsolete?

A volte le valute vengono rinominate, ridenominate o ritirate. Per impostazione predefinita, l'API risponde nella valuta utilizzata oggi; pertanto, se richiedi un codice ritirato, ottieni i tassi della valuta che lo ha sostituito. Per ottenere i tassi del codice ritirato stesso, aggiungi obsolete=true alla richiesta.

Calcoliamo i tassi di una valuta obsoleta dopo la data di ritiro a partire dal suo ancoraggio fisso alla valuta che l'ha sostituita. In questo modo le serie storiche lunghe rimangono coerenti, ma questi non sono tassi di mercato.

Per maggiori dettagli, incluso il modo in cui calcoliamo medie e statistiche durante un cambio di valuta, consulta Tassi storici e valute obsolete nella documentazione dell'API.

Come posso ottenere i tassi bid e ask da una banca centrale?

Aggiungi fields=mid,bid,ask alla richiesta /v1/central_bank_rate. Senza questo parametro, otterrai solo il tasso medio.

• Otterrai i tassi bid e ask solo dalle banche centrali che li pubblicano. Lo fanno 37 delle 100 banche centrali, tra cui la Banca del Giappone, l'Autorità monetaria di Hong Kong, la Banca centrale del Brasile e la Banca di Thailandia. La Banca centrale europea, la Banca d'Inghilterra e la Federal Reserve Bank di New York pubblicano solo tassi di riferimento. La colonna Bid/Ask nella documentazione dell'API mostra quali banche li pubblicano.
• I tassi bid e ask sono disponibili solo per i tassi correnti. Se aggiungi una date alla richiesta, otterrai solo tassi medi.
• Questi sono i tassi pubblicati da ciascuna banca centrale. Sono diversi dai tassi bid e ask di Xe dell'endpoint /v1/bid_ask.

Perché un tasso di una banca centrale sembra essere del giorno precedente?

Se non specifichi una data, /v1/central_bank_rate restituisce un timestamp in formato UTC. Quando lo converti nell'ora locale, il tasso può sembrare del giorno precedente.

Per ottenere invece la data locale della banca, aggiungi use_bank_date=true alla richiesta. Ad esempio, per la Banca centrale europea otterresti 2026-08-17 anziché 2026-08-16T22:00:00Z. Funziona per le risposte in formato JSON, XML e CSV.

Posso memorizzare nella cache i tassi dell'API?

Sì, per un periodo limitato. La memorizzazione nella cache aiuta l'integrazione a funzionare più velocemente e riduce il numero di richieste effettuate. Rimuovi i tassi memorizzati nella cache quando non sono più aggiornati. La memorizzazione nella cache significa conservare temporaneamente i tassi. Non significa archiviarli in modo permanente.

Come posso ottenere il tasso di un giorno passato all'orario di blocco?

Chiama /v1/historic_rate con date=YYYY-MM-DD e use_lock_in_time=true. Otterrai il tasso applicato all'orario di blocco giornaliero del tuo account in quel giorno. Ad esempio, puoi usarlo per ottenere il tasso del venerdì durante la settimana successiva.

Il tuo orario di blocco non influisce sui tassi delle banche centrali. Questi seguono il calendario di pubblicazione di ciascuna banca.

Come posso trovare il certificato SSL dell'API?

Puoi scaricare il certificato dal browser, usando Chrome o Edge.

In Chrome

1. Apri Chrome e vai su https://dfs.xe.com/dfs o https://xecdapi.xe.com/v1.

2. Seleziona l'icona delle informazioni sul sito a sinistra della barra degli indirizzi.

   

3. Seleziona La connessione è sicura, quindi seleziona Il certificato è valido.

   

4. Nella finestra dei dettagli del certificato, vai alla scheda Dettagli.

   

5. Seleziona Esporta per scaricare il certificato nel sistema.

   

In Edge

1. Vai su https://dfs.xe.com/dfs o https://xecdapi.xe.com/v1.

2. Seleziona l'icona del lucchetto nella barra degli indirizzi.

   

3. Seleziona La connessione è sicura.
4. Seleziona l'icona del certificato in alto a destra nella finestra popup.

5. Nella finestra del certificato, apri la scheda Dettagli.

   

6. Seleziona Esporta per scaricare il certificato.
   
   

Perché ricevo timeout o errori 500?

La maggior parte dei timeout intermittenti e degli errori 5xx ha origine nella rete o nel gateway tra il tuo sistema e il nostro. Prima di contattarci, controlla:

• Gateway e middleware: se chiami l'API tramite una piattaforma di integrazione o un gateway API, controlla prima i relativi log. Gli errori generati da questi sistemi possono sembrare errori della nostra API.
• DNS: non codificare né memorizzare nella cache il nostro indirizzo IP. Risolvi normalmente xecdapi.xe.com e rispetta i TTL DNS, poiché l'indirizzo IP associato può cambiare.
• Timeout e pool di connessioni: assicurati che le impostazioni del client siano adeguate al volume di richieste. Distribuisci i batch di grandi dimensioni invece di inviarli tutti contemporaneamente.
• TLS: il client deve supportare TLS 1.2 o versioni successive con suite di cifratura moderne (GCM). Gli stack meno recenti, come Java 7 o le versioni legacy di .NET, potrebbero offrire solo cifrari CBC, che stiamo dismettendo. Puoi testare il client all'indirizzo https://xecd-rates-api-test.xe.com/, che accetta solo TLS 1.3 e TLS 1.2 con GCM.

Se gli errori persistono, scrivici all'indirizzo data@xe.com indicando l'ID del tuo account, l'endpoint e i parametri, gli orari UTC dei problemi e la risposta completa dell'errore.

Devo inserire gli indirizzi IP in una allow-list?

No. L'API dei dati valutari non limita i chiamanti in base all'indirizzo IP. Puoi chiamare https://xecdapi.xe.com da qualsiasi IP pubblico e non devi registrare il tuo presso di noi.

Se il firewall consente il traffico in uscita solo verso indirizzi IP fissi, usa il nostro endpoint con IP statico, xecd-proxy.xe.com, e aggiungi il relativo indirizzo IP alla tua allow-list per l'IP corrente. Inviamo un'e-mail a tutti gli utenti di questo endpoint prima che l'IP cambi e prima della manutenzione pianificata.

• Usa xecd-proxy.xe.com solo se hai bisogno di un IP fisso. Altrimenti, chiama direttamente xecdapi.xe.com.
• Se le richieste iniziano a non riuscire dopo una modifica della rete da parte tua, verifica che la allow-list del firewall includa ancora il nostro IP statico.

Se usi il Datafeed legacy (DFS)

DFS accetta richieste solo da IP presenti nella allow-list. Se gli IP del tuo ufficio o del tuo server cambiano, inviaci quelli nuovi. Se passi all'API, non dovrai inserire gli IP nella allow-list.

Perché ricevo errori 401 o 403?

• 401 Credenziali non valide: controlla l'ID account e la chiave API inviati dall'integrazione. Entrambi distinguono tra maiuscole e minuscole.
• 403 "numero massimo di tentativi di accesso superato": dopo 3 tentativi di autenticazione non riusciti, blocchiamo l'account per un massimo di 5 minuti. Il blocco si applica a tutte le integrazioni dell'account, comprese quelle che usano le credenziali corrette. Di solito significa che un altro sistema, come un vecchio server o uno script di test, sta ancora inviando una chiave non aggiornata.

Per risolvere un errore 403:

1. Individua il sistema che invia la vecchia chiave e aggiornalo oppure disattivalo.
2. Attendi 5 minuti, quindi riprova.