URL di base e regioni

Il Bird API è servito da host regionali. Ogni richiesta va direttamente alla regione che contiene i dati della tua organizzazione. Il API non fornisce un URL data-plane globale.

I codici di regione sono due lettere minuscole per la geografia più una cifra di istanza (^[a-z]{2}[0-9]+$). us1 e eu1 sono attivi; lo schema supporta regioni future come us2 e ap1 senza alcuna modifica al client.

Le organizzazioni sono vincolate a una regione

A ogni organizzazione viene assegnata una regione al momento della registrazione. La regione viene rilevata dalla tua posizione, può essere modificata prima della conferma ed è immutabile nella v1. Lo spazio di lavoro, le chiavi API, i messaggi, i dati dei destinatari e i log degli eventi restano in quella regione. Non vengono mai replicati tra regioni diverse. Questa separazione supporta impegni di residenza dei dati come l'archiviazione e l'elaborazione in UE per un'organizzazione UE.

Solo l'autenticazione e l'amministrazione dell'account (/v1/auth, /v1/admin) operano su dati replicati globalmente, motivo per cui sono serviti dall'host non regionale platform.bird.com.

Routing: la chiave seleziona l'host

Una chiave API codifica la propria regione nel prefisso: le chiavi bk_us1_... appartengono a us1, le chiavi bk_eu1_... a eu1. Invia ogni chiave all'host regionale corrispondente.

Una richiesta che raggiunge la regione sbagliata viene rifiutata con 421 Misdirected Request anziché essere inoltrata. Il messaggio di errore indica l'host corretto:

{
  "error": {
    "type": "misdirected_error",
    "code": "E01010",
    "name": "MisdirectedRequest",
    "message": "Organization belongs to region eu1 but this request reached us1. Send the request to eu1.platform.bird.com.",
    "doc_url": "https://bird.com/docs/api/errors/E01010",
    "request_id": "..."
  }
}

Ogni risposta API include anche un header X-Bird-Region che indica la regione che l'ha servita, utile per verificare in quale regione è effettivamente arrivata una richiesta.

Gli SDK e il CLI effettuano il routing automaticamente

Gli SDK ufficiali e il CLI ricavano la regione dal prefisso della chiave e scelgono l'host. Con una chiave bk_eu1_..., ogni chiamata va a eu1.platform.bird.com senza alcuna configurazione. Per un ambiente di test puoi sovrascrivere l'host dedotto: usa baseUrl negli SDK TypeScript e PHP, base_url nel SDK Python, option.WithBaseURL nel SDK Go, oppure --base-url (o BIRD_API_URL) nel CLI.

Correlati

• Autenticazione: formato della chiave e risposte di errore
• Paesi supportati e restrizioni: copertura di consegna e scelta della residenza alla registrazione