API Infrastructure Wivly

Authentification

Chaque requête porte une clé API en bearer token. Créez vos clés dans Réglages → Développeurs ; la clé complète est affichée une seule fois, à la création, et n'est stockée que sous forme d'empreinte.

curl https://wivly.me/api/v1/passes \
  -H "Authorization: Bearer wivly_..." \
  -H "Content-Type: application/json" \
  -d '{"templateId":"tpl_123","customer":{"name":"Marco"}}'

Les clés peuvent être limitées à certaines boutiques. Une clé restreinte n'agit que sur les cartes de ces boutiques, ce qui permet de la confier à un seul point de vente.

Portées des clés

Chaque clé porte exactement une portée. Choisissez la plus étroite qui fait le travail.

Limites de débit

60 requêtes par minute et par clé. Au-delà, l'API renvoie 429 et la requête n'est pas traitée : réessayez après la minute suivante plutôt qu'immédiatement.

Endpoints

Tous les chemins sont relatifs à https://wivly.me/api/v1 et renvoient du JSON.

Webhooks

Enregistrez une URL et Wivly y publie quand quelque chose se produit. Les livraisons sont réessayées en cas d'échec.

Événements

Vérifier une livraison

Chaque requête porte un en-tête x-wivly-signature : HMAC-SHA256 du corps brut de la requête, avec votre secret de webhook comme clé. Comparez-le aux octets bruts avant tout parsing, avec une comparaison à temps constant.

import { createHmac, timingSafeEqual } from "node:crypto";

const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
const received = req.headers["x-wivly-signature"];
const ok =
  received.length === expected.length &&
  timingSafeEqual(Buffer.from(expected), Buffer.from(received));

Idempotence

Chaque livraison porte un id stable dans le corps, avec apiVersion « 2026-01-01 ». Une nouvelle tentative réutilise l'id : stockez-le et ignorez ceux déjà traités.

Erreurs

Les erreurs renvoient un corps JSON avec un message, et un code lorsque c'est utile.

OpenAPI

La spécification lisible par machine, pour Postman, Swagger, Stoplight ou la génération de code. Publique et sans authentification : elle décrit la surface, pas les données.