Tester une négociation bepleez depuis votre backend

Ce que vous construisez

Le code des exemples (MCP et A2A, licence MIT) est dans le dépôt public bepleez/bepleez-for-dev.

Votre backend appelle l'agent vendeur de bepleez par un serveur MCP (JSON-RPC sur HTTPS). L'agent négocie un prix avec votre acheteur dans la limite que vous avez fixée, puis renvoie un jeton d'accord signé que votre backend vérifie avant d'appliquer le prix. Le prix affiché sur votre site ne change pas.

Ce qu'il vous faut : l'adresse MCP de votre agent et une clé de test, toutes deux dans votre tableau de bord (dash.bepleez.com), menu Ma boutique, onglet Intégration. Vous générez la clé vous-même ; elle n'est affichée qu'une fois.

Règles à connaître

• La fiche produit vient de votre backend, jamais du navigateur de l'acheteur. Elle est figée à l'ouverture : un autre prix demande une nouvelle négociation.
• Le vendeur n'affirme rien qui ne soit pas dans description (neuf, garantie, accessoires…). Mettez-y les faits qu'il peut énoncer.
• Un prix absent ou égal à 0 est refusé (product_price_missing) : bepleez n'invente jamais un prix.
• Prix unitaires, quantité 1, dans la devise de la fiche.
• Plan de test : 100 négociations au total, 50 par jour (réglable sur demande). Au-delà : quota_exceeded ; les négociations en cours continuent.
• Vous voyez les actes échangés, jamais le raisonnement interne du vendeur.

1. Configurer

export BEPLEEZ_MCP_URL="https://api.bepleez.com/agents/<id>/mcp"   # affichée dans Intégration
export BEPLEEZ_API_KEY="bpz_test_..."                                # ne la mettez jamais dans un navigateur

Chaque appel porte l'en-tête Authorization: Bearer $BEPLEEZ_API_KEY. Un échec d'authentification renvoie toujours le même 401 invalid_api_key.

2. Ouvrir une négociation

Outil request_offer. Un tour du vendeur prend 9 à 17 s (jusqu'à 60 s pour l'ouverture) : passez async: true pour obtenir status: "in_progress" tout de suite, puis interrogez get_thread jusqu'à status: "ready".

curl -s "$BEPLEEZ_MCP_URL" \
  -H "Authorization: Bearer $BEPLEEZ_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"request_offer","arguments":{
        "product":{"sku":"DEMO-1","title":"Perceuse visseuse 18V","price":129.9,"currency":"EUR",
                   "description":"Neuve, garantie 2 ans, 2 batteries et un chargeur.","stock":40},
        "message":"Bonjour, je cherche une perceuse pour des travaux ce week-end, mon budget est de 110 €.",
        "idempotency_key":"7d1f0c2e-3b9a-4a51-9a6e-0c1d2e3f4a5b","async":true}}}'

Le résultat (dans structuredContent) contient thread_id, status, state, seller_messages (les mots du vendeur) et current_offer : offer_id, binding (firm ou indicative), total, valid_until, et options si le vendeur propose un menu.

3. Contre-proposer

Outil counter_offer avec thread_id, message (les mots de l'acheteur, prix compris s'il en cite un) et une idempotency_key obligatoire. Après tout délai dépassé, renvoyez l'appel avec la même clé : rien n'est répété et vous obtenez le même résultat (replayed: true).

Une offre indicative n'est pas acceptable ; seule une offre firm l'est. Si le vendeur répond par un menu (options), présentez toutes les options sur un pied d'égalité et gardez l'option_id choisi.

4. Accepter

Outil accept_offer, seulement après l'accord explicite de l'acheteur : thread_id, offer_id et, pour un menu, option_id. La réponse porte agreement : deal_token (JWT RS256), jwks_url, verify_url, price, currency, sku, expires_at. Le champ discount.code n'est qu'une référence : aucun coupon n'est créé chez vous.

5. Vérifier le jeton d'accord

Avant de facturer le prix négocié, votre backend vérifie le jeton avec la clé publique de jwks_url (signature RS256, expiration, sku et prix attendus), ou appelle verify_url. Ne faites jamais confiance à un prix envoyé par le navigateur.

Erreurs

Une erreur arrive avec isError et structuredContent.messages[0].code :

• product_missing, product_price_missing, product_invalid : fiche produit absente ou incorrecte.
• quota_exceeded : plafond du jour ou du plan de test atteint.
• idempotency_key_required, invalid_arguments : appel mal formé.
• turn_in_progress : le vendeur répond encore, interrogez get_thread puis réessayez.
• unknown_thread : cette négociation n'est pas la vôtre.
• offer_not_acceptable, option_required, offer_expired : pas d'offre ferme, option à préciser, ou offre périmée (relisez get_thread).
• no_active_strategy : aucune stratégie active pour ce produit, contactez-nous.
• seller_refused, seller_unavailable : refus du vendeur, ou panne passagère (réessayez avec la même clé).

La version du contrat est dans chaque réponse (contract_version, actuellement 2026-11-02).

Des exemples complets

Le dépôt bepleez-for-dev contient deux applications d'essai en Python 3, sans dépendance :

git clone https://github.com/bepleez/bepleez-for-dev && cd bepleez-for-dev
python3 quickstart/python/app.py --auto --budget 118   # MCP : négociation complète dans le terminal
python3 a2a/app.py --budget 118                        # A2A : mêmes étapes, signatures du vendeur vérifiées

Elles lisent seulement BEPLEEZ_MCP_URL (ou BEPLEEZ_A2A_URL) et BEPLEEZ_API_KEY, comme votre propre backend. Le dépôt contient aussi la vérification du jeton d'accord en Python et en Node.

MCP ou A2A

Les deux utilisent la même clé et le même agent. MCP est le contrat le plus simple (résultats structurés, erreurs codées, mode asynchrone, clé d'idempotence). A2A convient si vos agents parlent déjà le protocole : vous envoyez des actes (request, counter, accept), la fiche produit va dans message.metadata["com.bepleez.shopping.product"], et la preuve de l'accord est un acte commit signé (ES256), à vérifier avec les clés du profil UCP du vendeur.

Pour les agents

Le profil UCP (/agents/<id>/.well-known/ucp) et l'agent-card A2A décrivent la découverte automatique ; un résumé pour les agents est publié dans llms.txt.