Sign inGet Started

Concepts SDK

Les SDK TypeScript, Go, Python et PHP suivent une même conception. Chacun possède une base générée avec des types et un client bas niveau produit à partir de la spécification OpenAPI de Bird. Une couche écrite à la main gère le cycle de vie des requêtes et expose la surface organisée. Cette page couvre leur comportement commun. Les pages par langage couvrent les détails idiomatiques.

Idempotence automatique

Chaque mutation (POST, PUT, PATCH, DELETE) reçoit un en-tête Idempotency-Key généré automatiquement. La clé est générée une seule fois par appel logique et réutilisée à chaque tentative de réessai. Cela empêche une écriture réessayée de s'appliquer deux fois. Si un envoi expire après que le serveur l'a traité, le réessai reçoit la réponse stockée. Fournissez votre propre clé (option par appel idempotencyKey / option.WithIdempotencyKey / idempotency_key) lorsque l'opération logique couvre plus d'un appel au SDK, par exemple une boucle de réessai applicative autour du SDK. Consultez Idempotence pour le protocole côté serveur.

Réessais sûrs

Les réessais sont activés par défaut (maxRetries: 2 dans chaque SDK). Le client réessaie les échecs transitoires, y compris les erreurs réseau, les délais d'expiration par tentative, les réponses 429 et les réponses 5xx réessayables. Il utilise un backoff exponentiel avec gigue et respecte l'en-tête Retry-After du serveur. Les échecs déterministes (401, 404, 422 et autres réponses 4xx) ne sont jamais réessayés. La réutilisation de la clé d'idempotence rend les réessais de mutations sûrs. Le délai d'expiration s'applique à chaque tentative (60 secondes par défaut), un appel avec réessais peut donc durer plus longtemps. PHP utilise le délai d'expiration imposé par le client HTTP injecté, car PSR-18 ne propose pas de délai portable par requête.

Pagination

Les endpoints de liste utilisent la pagination par curseur. Chaque SDK prend en charge l'itération native, qui récupère les pages successives automatiquement. Pour un contrôle manuel du curseur, utilisez l'accesseur de page unique. Chaque page inclut data et next_cursor ; renvoyez le curseur comme starting_after pour avancer.
for await (const message of bird.email.list({ status: "bounced" })) {
  console.log(message.id);
}
const page = await bird.email.list({ limit: 50 }); // page.data, page.next_cursor
Consultez la référence de pagination pour les curseurs, limit et include_total.

Inférence de région

Les clés Bird API encodent leur région : bk_{region}_{token}. Le SDK lit le préfixe et route vers https://{region}.platform.bird.com automatiquement. Une option region remplace la région inférée. Une baseUrl explicite (option.WithBaseURL / base_url) prend le pas sur les deux et permet le développement local ou les déploiements auto-hébergés. La construction échoue lorsque la clé ne correspond pas au format bk_{region}_ et qu'aucun remplacement n'est défini.

Options par appel et configuration à la construction uniquement

La configuration comporte deux niveaux. Les paramètres d'identité et de transport sont réservés à la construction : la clé API, l'URL de base ou la région, et le client HTTP ou l'implémentation fetch. Les paramètres de cycle de vie peuvent être définis comme valeurs par défaut à la construction et remplacés par appel : timeout, maxRetries, la clé d'idempotence et les en-têtes supplémentaires. TypeScript, Python et PHP utilisent un objet d'options en fin d'appel ; Go utilise des options variadiques option.With…. Les en-têtes appartenant à SDK (Authorization, User-Agent, Idempotency-Key) ont priorité sur les en-têtes fournis par l'appelant. Les valeurs par défaut de canal, comme un from e-mail par défaut, suivent le même schéma.

Vérification des webhooks

Chaque SDK fournit un point d'entrée de vérification : webhooks.unwrap(rawBody, headers). Il implémente Standard Webhooks avec HMAC-SHA256 sur le payload brut et le secret de signature de votre endpoint. Il accepte les entrées de signature taguées v1, rejette les horodatages en dehors d'une fenêtre de tolérance de 5 minutes et compare les signatures en temps constant. Transmettez les octets bruts du corps de la requête exactement tels que reçus. Parser puis re-sérialiser le JSON modifie les octets et invalide la signature.
En cas de succès, unwrap renvoie un événement typé discriminé sur type, comme email.delivered ou email.bounced. Les types d'événements inconnus sont tout de même vérifiés et décodés : gérez-les dans votre branche default. Un échec de vérification est une erreur distincte (BirdWebhookVerificationError / *WebhookVerificationError / WebhookVerificationError) ; répondez avec 400. Consultez Webhooks pour la configuration des endpoints et le catalogue d'événements.

Étapes suivantes