hajra

Développeurs

L’API Hajra

Une API REST en JSON et des webhooks signés pour relier Hajra au site d’un promoteur, aux formulaires publicitaires, au logiciel de la banque et aux tableaux de bord. Montants en dinars (3 décimales), dates ISO 8601.

Authentification

Chaque requête porte une clé dans l’en-tête Authorization: Bearer hjr_live_…. Les clés sont créées par l’équipe Hajra dans la console (API et webhooks), affichées une seule fois, stockées hachées, révocables à tout moment. Chaque clé n’a que les permissions cochées et peut être limitée aux programmes d’un promoteur. Pour obtenir une clé, écrivez à contact@hajra.tn en précisant les permissions et les programmes concernés.

programs:read Lire les programmes, les lots et les prix
contracts:read Lire les contrats
payments:read Lire les paiements
leads:read Lire les prospects
leads:write Créer des prospects (formulaires, Meta Lead Ads…)
statements:write Envoyer des lignes de relevé bancaire
stats:read Lire les statistiques

Points d’accès

Base : https://hajra.tn/api/v1. Listes paginées avec limit (200 au plus) et offset.

GET/programsProgrammes, prix de la hajra du jour et prochain prix annoncé, lots libres, avancement du chantier, compte dédié.programs:read
GET/programs/{id}/unitsLots d’un programme : type, surface, prix, équivalent en hajras, disponibilité (?status=free).programs:read
GET/contractsContrats, hajras détenues, seuil des clés, mandat de prélèvement (?program=&since=).contracts:read
GET/paymentsPaiements : apports, prélèvements, virements, rejets (?status=paid&since=).payments:read
GET/leadsProspects avec source, UTM, statut et score (?status=&source=&since=).leads:read
POST/leadsCrée un prospect : formulaire d’un site partenaire, Meta Lead Ads via Make ou n8n. Dédoublonné sur le téléphone.leads:write
POST/statementsEnvoie les crédits du compte dédié ; avec reconcile: true, Hajra les rapproche des contrats.statements:write
GET/statsIndicateurs pour Looker Studio, Power BI ou un tableur.stats:read

Exemple : créer un prospect

curl -X POST https://hajra.tn/api/v1/leads \
  -H "Authorization: Bearer hjr_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Sami Trabelsi",
    "phone": "22 123 456",
    "email": "sami@example.com",
    "programId": "…",
    "unitType": "S+2",
    "monthlyTnd": 1500,
    "utm": { "source": "facebook", "campaign": "lancement-yasmine" },
    "consent": true
  }'

Le prospect entre dans le CRM, est attribué au conseiller le moins chargé et reçoit un score. Le même numéro reçu dans les 30 jours complète la fiche existante.

Réponse

{
  "data": {
    "id": "6c0f…",
    "fullName": "Sami Trabelsi",
    "phone": "+21622123456",
    "source": "meta",
    "status": "nouveau",
    "score": 85,
    "createdAt": "2026-11-19T10:42:00.000Z"
  },
  "duplicate": false
}

Erreurs : 401 clé invalide, 403 permission manquante, 422 données invalides, toujours sous la forme { error: { code, message } }.

Webhooks

Hajra prévient vos outils en temps réel par un POST JSON. Chaque livraison est signée avec le secret du webhook, journalisée et peut être relancée depuis la console.

lead.created Nouveau prospect
lead.status_changed Statut d’un prospect modifié
contract.created Réservation signée
payment.paid Paiement encaissé
payment.rejected Prélèvement rejeté
price.announced Nouveau prix de la hajra annoncé

Corps reçu

{
  "id": "0b8e…",
  "event": "payment.paid",
  "createdAt": "2026-11-19T09:00:12.000Z",
  "data": {
    "paymentId": "…",
    "reference": "HJR-27-000123",
    "hajras": 15,
    "amountTnd": 1536,
    "method": "prelevement"
  }
}

Vérifier la signature (Node.js)

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

// corps brut de la requête (texte), en-tête X-Hajra-Signature, secret whsec_…
export function verifierHajra(corps, entete, secret) {
  const { t, v1 } = Object.fromEntries(entete.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // 5 min max
  const attendu = createHmac("sha256", secret).update(`${t}.${corps}`).digest("hex");
  const a = Buffer.from(attendu), b = Buffer.from(v1 ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}