API publique · v1

Harch Atelier REST API

Intégrez l'intelligence réputationnelle, les alertes, les tendances de sentiment et le screening de sanctions dans vos outils BI, CRM et agents IA. Authentifiez-vous avec une clé API Bearer et recevez du JSON en retour.

Authentification

Toutes les requêtes doivent inclure un en-tête Authorization avec un token Bearer préfixé par harch_ :

Authorization: Bearer harch_<your-key>

Les clés API sont limitées à la société de l'utilisateur qui les a créées. Une clé créée par un utilisateur d'Attijariwafa Bank ne peut lire que les données d'Attijariwafa Bank — jamais celles d'une autre société. Les clés sont hachées au repos (SHA-256) ; le texte en clair n'est affiché qu'une seule fois, à la création.

Pas encore de clé ? Ouvrez Enterprise Admin → onglet API Keys pour en créer une. Maximum 5 clés actives par utilisateur.

URL de base et limites de débit

Tous les endpoints sont relatifs à https://atelier.harchcorp.com. Exemple :

GET https://atelier.harchcorp.com/api/v1/alerts

Limite de débit

60 req / min / clé

Rafale

120 req (10s)

Quota

10,000 req / mois (Corporate)

Délai d'attente

30s par requête

Les réponses en cas de dépassement de débit renvoient le code HTTP 429 avec un en-tête Retry-After. L'en-tête X-Harch-Quota-Remaining est envoyé avec chaque réponse réussie.

Endpoints

GET/api/v1/alerts

Lister les alertes

Renvoie les alertes de crise de la société associée à la clé API — articles à sentiment négatif des 7 derniers jours et évaluations de risque élevé/critique. Triées par detectedAt décroissant.

Paramètres

limitintegerNombre maximum d'alertes renvoyées. 20 par défaut, 100 maximum.

sinceISO dateUniquement les alertes postérieures à cet horodatage. Par défaut : il y a 7 jours.

Exemple de requête

curl -H "Authorization: Bearer harch_your_key_here" \
     "https://atelier.harchcorp.com/api/v1/alerts"

GET/api/v1/reputation

Obtenir le score de réputation

Renvoie le dernier score de réputation + la répartition par pilier (sentiment, visibilité IA, volume, autorité, innovation, performance, raison d'être, part de voix) ainsi qu'un historique sur 30 jours.

Exemple de requête

curl -H "Authorization: Bearer harch_your_key_here" \
     "https://atelier.harchcorp.com/api/v1/reputation"

GET/api/v1/sentiment

Obtenir la tendance de sentiment

Série temporelle quotidienne du sentiment pour la société associée à la clé API. Chaque jour reporte le score de sentiment moyen, le nombre d'articles et la répartition positif/neutre/négatif.

Paramètres

rangestringFenêtre temporelle. L'une de 7d, 30d, 365d. 30d par défaut.

Exemple de requête

curl -H "Authorization: Bearer harch_your_key_here" \
     "https://atelier.harchcorp.com/api/v1/sentiment"

GET/api/v1/screen

Screening de sanctions

Vérifie un nom (individu, entité ou navire) auprès des listes de sanctions consolidées OFAC + UE + ONU. Utilise la correspondance floue avec un seuil de similarité configurable (0.86 par défaut). Renvoie les correspondances classées par similarité.

Paramètres

namestring *Nom d'entité / d'individu / de navire à vérifier. 2-256 caractères.

thresholdfloatSeuil de similarité 0.5-0.99. 0.86 par défaut.

typestringPré-filtre : individual | entity | vessel.

Exemple de requête

curl -H "Authorization: Bearer harch_your_key_here" \
     "https://atelier.harchcorp.com/api/v1/screen?name=Acme+Corp"

Erreurs

L'API utilise les codes de statut HTTP standards. Les réponses d'erreur suivent une structure JSON cohérente :

{
  "error": "Unauthorized",
  "message": "Missing or invalid API key. Pass it as Authorization: Bearer harch_<your-key>."
}

200Succès.

400Requête invalide — paramètre manquant ou invalide.

401Non autorisé — clé API manquante ou invalide.

403Interdit — votre clé fonctionne mais vous n'avez pas accès à cette ressource.

404Introuvable — la ressource ou la société n'existe pas.

429Trop de requêtes — vous avez atteint la limite de débit. Réessayez après le délai indiqué par l'en-tête Retry-After.

503Service indisponible — les listes de sanctions sont en démarrage à froid. Réessayez dans 30s.

500Erreur serveur. Si elle persiste, contactez le support avec l'ID de requête issu de X-Harch-Request-Id.

Webhooks

Enregistrez des webhooks sortants pour recevoir des callbacks POST lorsqu'une alerte critique se déclenche, qu'un rapport est prêt ou qu'un screening de sanctions détecte une correspondance. Gérez vos webhooks dans Enterprise Admin → onglet Webhooks.

Chaque livraison est signée (si vous avez défini un secret) avec X-Harch-Signature: hex(HMAC-SHA256(secret, body)). Les livraisons échouées sont retentées jusqu'à 3 fois avec un backoff exponentiel (2s → 4s → 8s).

Votre récepteur doit :

Vérifier la signature (si vous avez défini un secret).
Répondre avec un HTTP 2xx en moins de 10 secondes.
Être idempotent — un même événement peut être livré deux fois en cas de nouvelle tentative.

alert.critical

Se déclenche lorsqu'un article ou une évaluation de risque de sévérité critique est détecté pour votre société.

{
  "event": "alert.critical",
  "deliveredAt": "2026-07-31T09:00:00.000Z",
  "data": {
    "id": "clk2xyz...",
    "title": "OCP Group under scrutiny over ...",
    "severity": "critical",
    "source": "Le Matin",
    "url": "https://lematin.ma/...",
    "detectedAt": "2026-07-31T08:15:00.000Z",
    "sentimentScore": -0.72,
    "company": { "id": "clk1abc...", "name": "OCP Group", "slug": "ocp-group" }
  }
}

alert.high

Identique à alert.critical, mais pour les alertes de sévérité élevée.

{
  "event": "alert.high",
  "deliveredAt": "2026-07-31T09:05:00.000Z",
  "data": { /* same shape as alert.critical */ }
}

report.ready

Se déclenche lorsqu'un nouveau rapport d'analyse PDF est généré pour votre société.

{
  "event": "report.ready",
  "deliveredAt": "2026-07-31T07:00:00.000Z",
  "data": {
    "reportId": "clk3rep...",
    "type": "risk",
    "period": "2026-07",
    "pdfUrl": "https://atelier.harchcorp.com/api/pdf/report/clk3rep.pdf"
  }
}

reputation.drop

Se déclenche lorsque le score de réputation global chute de 5 points ou plus d'une semaine à l'autre.

{
  "event": "reputation.drop",
  "deliveredAt": "2026-07-31T06:00:00.000Z",
  "data": {
    "previousScore": 84.2,
    "currentScore": 78.1,
    "delta": -6.1,
    "company": { "id": "clk1abc...", "name": "Attijariwafa Bank", "slug": "attijariwafa-bank" }
  }
}

screening.match

Se déclenche lorsqu'un screening de sanctions renvoie une correspondance (similarité >= 0.86).

{
  "event": "screening.match",
  "deliveredAt": "2026-07-31T09:10:00.000Z",
  "data": {
    "query": "Acme Corp",
    "matches": [
      { "list": "OFAC", "name": "ACME CORPORATION", "similarity": 0.92 }
    ],
    "clean": false
  }
}

SDK et bibliothèques clientes

Pas encore de SDK officiel — l'API REST est stable et suffisamment simple pour être appelée avec fetch ou requests. Rejoignez la liste d'attente pour un SDK TypeScript officiel à api@harchcorp.com.

API publique · v1