API et webhooks

Pour connecter les logiciels d'une mairie (comptabilité, Trésor, tableau de bord, archivage) à Yomara Mairie. Disponible avec le module « API et webhooks ».

Authentification

Un administrateur de la mairie crée une clé dans le back-office : Paramètres → Clés API, en cochant seulement les droits utiles. La clé n'est affichée qu'une fois ; elle donne accès aux seules données de sa mairie.

curl https://mairie.yomaratechnologies.com/api/mairie/v1/me \
  -H "Authorization: Bearer ymk_xxxxxxxx_…"

Données

Toutes les listes acceptent from et to (dates, sur la date de mise à jour), status, page et per_page (100 au plus), et renvoient data + meta (page, per_page, total, last_page). Montants en francs CFA, dates ISO 8601.

Adresse de base : https://mairie.yomaratechnologies.com/api/mairie/v1

Journal comptable

GET /accounting/journal?from=2026-10-01&to=2026-10-31&format=csv renvoie une ligne par encaissement : paiements réussis et tickets payés en espèces, sans double compte. Le CSV (séparateur « ; », UTF-8) s'ouvre dans Excel. Colonnes : date, journal (CAISSE ou BANQUE), piece, label, code (code de la taxe ou nature de la recette, à rapprocher de votre plan comptable), amount, method, channel, external_ref, agent.

Webhooks

Dans Paramètres → Webhooks, la mairie indique l'adresse HTTPS de son logiciel et les événements à recevoir. Chaque événement est envoyé en POST JSON :

{
  "id": "4f0c…",                 // identifiant unique de l'envoi (évite les doublons)
  "event": "payment.succeeded",
  "created_at": "2026-10-18T10:21:07+00:00",
  "mairie": "cocody",
  "data": { "reference": "PAY-…", "amount": 5000, "status": "success", … }
}

Événements : payment.succeeded, payment.failed, receipt.created, receipt.canceled, application.created, application.status_changed, civil_request.created, civil_request.status_changed, report.created, report.status_changed, building_permit.created, building_permit.status_changed , et ping pour le bouton de test.

Répondez avec un code 2xx en moins de 10 secondes. Sinon l'envoi est retenté 6 fois (après 1 min, 5 min, 30 min, 2 h, 6 h et 24 h) ; après 20 échecs d'affilée le webhook est désactivé. Chaque envoi se consulte et se renvoie depuis le back-office.

Vérifier la signature

L'en-tête X-Yomara-Signature: t=1760782867,v1=5a9c… contient l'horodatage et le HMAC SHA-256, avec le secret du webhook, de la chaîne t + "." + corps brut. Refusez les signatures fausses et celles de plus de 5 minutes.

// PHP
[$t, $v1] = sscanf($_SERVER['HTTP_X_YOMARA_SIGNATURE'], 't=%d,v1=%s');
$body = file_get_contents('php://input');
$ok = hash_equals(hash_hmac('sha256', $t.'.'.$body, $secret), $v1) && abs(time() - $t) < 300;

// Node.js
const [t, v1] = req.get('X-Yomara-Signature').split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - t) < 300;

Erreurs et limites

© 2026 Yomara Technologies