Passer au contenu
API cartes-cadeauxAccès anticipé

L’API cartes-cadeaux pour humains et agents

Une seule API REST pour demander une soumission, commander et livrer des cartes-cadeaux de plus de 4 700 marques dans plus de 150 pays. L’accès anticipé est ouvert dès maintenant.

curl
# 1. Quote a gift card
curl -X POST "$BIDALI_API_URL/v1/quotes" \
  -H "Authorization: Bearer $BIDALI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand": "starbucks-us", "amount": 25, "currency": "USD"}'

# 2. Order it and email it to the recipient
curl -X POST "$BIDALI_API_URL/v1/orders" \
  -H "Authorization: Bearer $BIDALI_API_KEY" \
  -H "Idempotency-Key: 6f1c2b7e-9d3a-4e58-b1a0-2c5d7e8f9a10" \
  -H "Content-Type: application/json" \
  -d '{"quote_id": "qt_123", "delivery": {"method": "email", "to": "sam@example.com"}}'

Ébauche, sujette à changement

Aperçu de l’API

Neuf points de terminaison, un seul flux

Trouvez une marque, demandez le prix, passez la commande et laissez le webhook vous dire que c’est fait.

Authentification
Clé d’API de type Bearer dans l’en-tête Authorization
Idempotence
En-tête Idempotency-Key sur POST /v1/orders
Livraison
email, sms, link ou inline dans la réponse de la commande
Hôte du bac à sable
Annoncé lors de l’accès anticipé
Ébauche — sujette à changement
Points de terminaison de l’ébauche de l’API cartes-cadeaux. Ébauche — sujette à changement.
MéthodePoint de terminaisonCe qu’il fait
GET/v1/countriesLister les pays où des cartes-cadeaux sont vendues.Renvoie les codes de pays ISO et leurs noms.
GET/v1/currenciesLister les devises prises en charge.Renvoie les codes de devise et la précision en unités mineures.
GET/v1/brandsChercher dans le catalogue.Requête: country, category. Résultats paginés.
GET/v1/brands/{slug}Obtenir une marque.Coupures, conditions et instructions d’utilisation.
POST/v1/quotesConnaître le prix d’une carte-cadeau avant de l’acheter.Corps: brand, amount, currency. Renvoie une soumission qui expire.
POST/v1/ordersCommander une carte-cadeau à partir d’une soumission.Corps: quote_id, delivery (email, sms, link ou inline). Envoyez un en-tête Idempotency-Key.
GET/v1/orders/{id}Obtenir une commande et son statut.Renvoie la carte-cadeau une fois la commande exécutée.
GET/v1/balanceObtenir votre solde prépayé.Renvoie le solde disponible et les dernières lignes du relevé.
POST/v1/webhooksEnregistrer un webhook.Corps: url, events (order.fulfilled, order.failed, balance.low).

En code

Du catalogue à la carte-cadeau livrée

Du HTTPS et du JSON, tout simplement. Si vous savez appeler curl ou fetch, vous savez vendre une carte-cadeau.

Parcourir et enregistrer un webhook

curl
# Groceries available in Canada
curl "$BIDALI_API_URL/v1/brands?country=CA&category=groceries" \
  -H "Authorization: Bearer $BIDALI_API_KEY"

# Get told when an order is done or your balance runs low
curl -X POST "$BIDALI_API_URL/v1/webhooks" \
  -H "Authorization: Bearer $BIDALI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/bidali", "events": ["order.fulfilled", "order.failed", "balance.low"]}'

Soumission et commande

TypeScript (fetch)
// uuid() is any UUID generator; store the key with your own order record.
const base = process.env.BIDALI_API_URL!;
const headers = {
  Authorization: `Bearer ${process.env.BIDALI_API_KEY}`,
  'Content-Type': 'application/json',
};

const quote = await fetch(`${base}/v1/quotes`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ brand: 'starbucks-us', amount: 25, currency: 'USD' }),
}).then((res) => res.json());

const order = await fetch(`${base}/v1/orders`, {
  method: 'POST',
  headers: { ...headers, 'Idempotency-Key': uuid() },
  body: JSON.stringify({
    quote_id: quote.id,
    delivery: { method: 'email', to: 'sam@example.com' },
  }),
}).then((res) => res.json());

console.log(order.id, order.status);

Prête pour la production

Ce qu’il vous faut pour la mettre en ligne

Bac à sable

Testez chaque appel avec de fausses commandes avant de toucher à la production, avec les mêmes réponses et les mêmes erreurs.

Webhooks

Soyez averti quand une commande est exécutée ou échoue, et quand votre solde est bas.

Commandes idempotentes

Envoyez un en-tête Idempotency-Key et réessayez en toute sécurité. Une erreur réseau n’achète jamais deux fois la même carte-cadeau.

Solde et relevés

Consultez votre solde en un seul appel et rapprochez chaque commande de votre relevé.

Documentation lisible par machine

Une spécification OpenAPI 3.1 pour les générateurs de SDK et les agents d’IA: un appel d’outil n’est qu’à un import de distance.

Cas d’usage

Ce que les équipes en font

Les mêmes appels alimentent les récompenses, les avantages de paie et les agents d’IA.

Incitatifs clients

Primes d’inscription, parrainages et sondages.

Récompenses employés

Des récompenses utiles, dans tous les pays.

Commerce agentique

Donnez un budget à votre agent IA, pas une carte.

Accès anticipé

Obtenez l’accès au bac à sable

Dites-nous ce que vous créez. Nous accueillons un petit groupe d’équipes et nous vous répondrons avec les détails du bac à sable.

Parlez-nous de votre projet

Donnez-nous quelques détails et notre équipe vous répondra.

Contacter les ventes

Questions fréquentes

L’accès anticipé est ouvert dès maintenant. Nous communiquerons une date de disponibilité générale aux équipes en accès anticipé dès qu’elle sera fixée.

Les limites seront publiées avec le bac à sable. Les équipes en accès anticipé nous aident à les établir, alors dites-nous quel volume vous prévoyez.

L’accès à la production exige une vérification de l’entreprise, dans le cadre de notre programme de conformité complet. Vous pouvez développer dans le bac à sable avant qu’elle soit terminée.

Il n’y a aucuns frais de plateforme. Vous payez les cartes-cadeaux que vous commandez, et vous voyez le prix dans une soumission avant de vous engager.

Le catalogue couvre plus de 4 700 marques dans plus de 150 pays. Appelez GET /v1/countries et GET /v1/brands pour voir ce qui est offert où.

Oui. L’API est du HTTPS et du JSON tout simples, et l’ébauche de la spécification OpenAPI 3.1 permet à un agent de l’appeler comme un outil. Un serveur MCP est prévu.

Commencez par le bac à sable

Demandez l’accès anticipé et passez votre première commande dès aujourd’hui.