Capability Negotiation

Endpoint de découverte

Le marchand expose /.well-known/ucp.json (ou son équivalent MCP) avec la structure :

{
  "ucp_version": "1.2",
  "merchant": {
    "name": "Boutique Aurore",
    "did": "did:web:aurore.fr",
    "url": "https://aurore.fr"
  },
  "capabilities": {
    "catalog": {"version": "1.2", "transports": ["rest", "mcp"]},
    "checkout": {"version": "2.0", "embedded": true},
    "identity": {"version": "1.0", "oauth": true},
    "order": {"version": "1.0", "tracking": true}
  },
  "extensions": [
    "dev.ucp.shopping.checkout.ap2_mandates",
    "fr.aurore.gift_wrapping.v1"
  ]
}

L’agent lit ce manifeste avant toute autre interaction. Il peut ainsi adapter son flow ou abandonner si une capability requise n’est pas supportée.

Versioning par capability

UCP versionne chaque capability indépendamment. Une boutique peut être à jour sur Checkout v2.0 et rester sur Catalog v1.1 sans casser la compatibilité. Les agents acceptent une fenêtre de N-2 versions par capability, ce qui laisse le temps aux marchands de migrer.

Extensions custom

Les extensions sont nommées en reverse-domain (fr.aurore.gift_wrapping.v1). L’agent ignore les extensions qu’il ne comprend pas et l’interaction reste fonctionnelle sur le tronc commun. C’est l’équivalent UCP des extensions XMPP ou des feature flags HTTP.

Cache et invalidation

Le manifeste est servi avec un Cache-Control: max-age=3600 recommandé par la spec. Les agents respectent ce TTL et ne re-fetchent pas le manifeste à chaque interaction. Pour propager rapidement un changement de capability (passage de Checkout v1.9 à v2.0, par exemple), le marchand baisse le max-age à 60 secondes pendant la fenêtre de migration puis le remonte. Un header ETag permet aux agents de revalider à coût zéro via If-None-Match.

Erreur courante

Renvoyer 404 quand /.well-known/ucp.json n’est pas implémenté plutôt que de servir un manifeste vide. Les agents interprètent un 404 comme une absence définitive de support UCP et ne réessaient pas avant 24 à 72 heures. Servir au minimum {"ucp_version": "1.2", "capabilities": {}} laisse la porte ouverte aux retries planifiés et signale clairement votre intention de rejoindre le standard.

À ne pas confondre avec

• [[identity-linking-oauth]] : capability spécifique, négociée mais distincte du protocole de découverte.
• HTTP OPTIONS : verbe HTTP technique sans la sémantique commerce de UCP.