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.
# 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é
| Méthode | Point de terminaison | Ce qu’il fait |
|---|---|---|
GET | /v1/countries | Lister les pays où des cartes-cadeaux sont vendues.Renvoie les codes de pays ISO et leurs noms. |
GET | /v1/currencies | Lister les devises prises en charge.Renvoie les codes de devise et la précision en unités mineures. |
GET | /v1/brands | Chercher 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/quotes | Connaître le prix d’une carte-cadeau avant de l’acheter.Corps: brand, amount, currency. Renvoie une soumission qui expire. |
POST | /v1/orders | Commander 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/balance | Obtenir votre solde prépayé.Renvoie le solde disponible et les dernières lignes du relevé. |
POST | /v1/webhooks | Enregistrer 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
# 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
// 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 ventesQuestions fréquentes
Commencez par le bac à sable
Demandez l’accès anticipé et passez votre première commande dès aujourd’hui.