YA-Planning API दस्तावेज़

परिचय

API REST है, JSON में, संस्करणित। सभी व्यावसायिक संसाधन /api/v1/pub/v1 उपसर्ग के अंतर्गत रहते हैं। सार्वजनिक प्रदर्शन एंडपॉइंट /api/v1/public/api-demo के अंतर्गत हैं।

• Base URL : https://votre-domaine/api/v1/pub/v1
• प्रारूप: अनुरोध और प्रतिक्रियाएँ application/json में (ICS/PDF निर्यात को छोड़कर)।
• संस्करणन: संस्करण पथ में है (/v1); पश्च-संगत परिवर्धन संस्करण नहीं बदलते।
• CORS : सार्वजनिक API तृतीय-पक्ष ब्राउज़र अनुप्रयोगों के लिए खुली है (बिना कुकीज़)।

प्रमाणीकरण

प्रत्येक अनुरोध एक API कुंजी वहन करता है, दो में से किसी एक हेडर में:

X-API-Key: yap_live_xxxxxxxxxxxxxxxxxxxx
# ou
Authorization: Bearer yap_live_xxxxxxxxxxxxxxxxxxxx

एक कुंजी अनेक संस्थानों के लिए अधिकृत हो सकती है (एंटरप्राइज़ कुंजी)। तब लक्ष्य को X-Etablissement-Id हेडर के माध्यम से निर्दिष्ट करें; यदि केवल एक ही अधिकृत संस्थान है, तो वह स्वचालित रूप से अनुमानित हो जाता है। कुंजियाँ, स्कोप के साथ, कंसोल में बनाई जाती हैं।

एनवायरनमेंट और सैंडबॉक्स

दो एनवायरनमेंट, कुंजी के उपसर्ग द्वारा विभेदित:

• yap_live_… — production : आपका वास्तविक डेटा; जनरेशन साप्ताहिक कोटा से घटाता है।
• yap_test_… — sandbox : पठन एक डेमो डेटासेट लौटाते हैं (कभी भी आपका वास्तविक डेटा नहीं), जनरेशन घटाई नहीं जाती, और कॉन्फ़िगरेशन लेखन अस्वीकृत होता है (SANDBOX_READONLY)। बिना जोखिम विकास के लिए आदर्श।

स्कोप

प्रत्येक कुंजी स्कोप का एक उपसमुच्चय वहन करती है; यदि आवश्यक स्कोप अनुपस्थित हो तो एक एंडपॉइंट अस्वीकार करता है (403 INSUFFICIENT_SCOPE)।

दर और कोटा

प्रत्येक कुंजी की एक दर सीमा होती है (डिफ़ॉल्ट 60 req/min)। प्रतिक्रियाएँ वहन करती हैं:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1783919311   # epoch (s) de réinitialisation

अधिकता Retry-After हेडर के साथ 429 RATE_LIMITED लौटाती है। समय-सारणी जनरेशन इसके अतिरिक्त पैकेज के साप्ताहिक कोटा के अधीन है (/me के माध्यम से दृश्यमान)।

API की प्रत्येक प्रतिक्रिया एक X-Request-Id हेडर भी वहन करती है (सहसंबंध पहचानकर्ता) — किसी घटना की स्थिति में इसे सहायता को बताएँ। नोट: दर की गणना वर्तमान में प्रति इंस्टेंस लागू की जाती है; बहु-इंस्टेंस परिनियोजन पर प्रभावी सीमा प्रदर्शित मान का गुणज हो सकती है।

त्रुटियाँ

एकसमान त्रुटि आवरण, सहायता के लिए एक requestId के साथ:

{ "error": "INSUFFICIENT_SCOPE", "message": "Scope requis : config:write.",
  "requestId": "6181762d-…", "requiredScope": "config:write" }

सीधे लाइव परीक्षण करें — बिना पंजीकरण

सार्वजनिक प्रदर्शन एंडपॉइंट (कोई कुंजी आवश्यक नहीं)।

Postman : « Import » → « Link » → /q/openapi?format=json पेस्ट करें।

संदर्भ — खाता और आत्मनिरीक्षण

{
  "environment": "LIVE",
  "etablissementId": "61a9…8cb",
  "scopes": ["config:read", "timetables:write"],
  "entitlements": {
    "plan": "PRO",
    "generationsRestantes": -1,
    "resetLe": "2026-07-14T00:00:00Z",
    "maxClassesExport": -1
  }
}

{"id":"…","nom":"Groupe Scolaire Les Palmiers","slug":"gs-palmiers","sigle":"GSP","ville":"Abidjan","pays":"CI","type":"PRIVE","siteWeb":"https://…"}

{"apiKeyId":"…","days":30,"daily":[{"day":"2026-07-12","calls":128,"errors":3}]}

संदर्भ — खाता — संस्थान

खाता-स्तर प्रावधान: X-Etablissement-Id हेडर के बिना अपने स्वयं के संस्थान बनाएँ (/account पथ किसी संस्थान से जुड़ा नहीं है)। स्कोप establishments:manage। निर्माण पर, कॉल करने वाली कुंजी को नए संस्थान पर स्वचालित रूप से एक ACTIVE grant मिलता है — फिर उसे कॉन्फ़िगर और जनरेट करने के लिए X-Etablissement-Id का उपयोग करें।

{"nom":"Groupe Scolaire Les Palmiers","type":"PRIVE_LAIC","pays":"CI"}

{"id":"…","nom":"Groupe Scolaire Les Palmiers","slug":"gs-les-palmiers","pays":"CI","type":"PRIVE_LAIC"}

[{"id":"…","nom":"…","slug":"…","pays":"CI","type":"PRIVE_LAIC"}]

संदर्भ — कॉन्फ़िगरेशन

संस्थान की शैक्षणिक संरचना। पठन: स्कोप config:read। लेखन: स्कोप config:write (सैंडबॉक्स में निषिद्ध)। एक नव-निर्मित संस्थान में पहले से ही एक « मुख्य चक्र » होता है।

[{"id":"…","libelle":"Cycle principal","ordre":0}]

{"libelle":"Second cycle","ordre":1}

[{"id":"…","libelle":"6ème 1","cycleId":"…","effectif":42,"ordre":1}]

{"libelle":"6ème 3","cycleId":"<uuid-cycle>","effectif":40,"ordre":3}

[{"id":"…","libelle":"Mathématiques","code":"MATH","couleur":"#6C5CE7","ordre":1}]

{"libelle":"Physique-Chimie","code":"PC","couleur":"#00B894","ordre":5}

[{"id":"…","nom":"Koné","prenoms":"Awa","matricule":"P-0142","email":"…","telephone":"…","nombreHeureAutorise":18,"statut":"TITULAIRE","actif":true}]

{"nom":"Diarra","prenoms":"Sékou","matricule":"P-0210","email":"s.diarra@ecole.ci","nombreHeureAutorise":18,"statut":"VACATAIRE","actif":true}

[{"id":"…","jour":"MONDAY","heureDebut":"08:00","heureFin":"09:00","estPause":false,"libelle":null}]

{"jour":"MONDAY","heureDebut":"08:00","heureFin":"09:00","estPause":false,"libelle":"M1"}

[{"id":"…","cycleId":"…","disciplineId":"…","nombreHeuresObligatoire":4,"minHeuresConsecutives":1,"maxHeuresConsecutives":2}]

{"cycleId":"<uuid>","disciplineId":"<uuid>","nombreHeuresObligatoire":4,"minHeuresConsecutives":1,"maxHeuresConsecutives":2}

संदर्भ — समय-सारणियाँ

अतुल्यकालिक जनरेशन (सॉल्वर पृष्ठभूमि कार्य में चलता है — स्थिति जाँचें), प्रकाशन और अवलोकन। सैंडबॉक्स में, जनरेशन एक डेमो डेटासेट का उपयोग करता है और कोटा से घटाया नहीं जाता।

{"durationMinutes": 5}

{"jobId":"…","status":"SOLVING_SCHEDULED"}

{"items":[{"jobId":"…","name":"…","status":"SOLVING_ENDED","workflowStatus":"BROUILLON","feasible":true,"hardScore":0,"softScore":-42,"createdAt":"…"}],"total":7,"page":0,"size":25}

{"jobId":"…","status":"SOLVING_ENDED","feasible":true,"lessons":[{"id":"1","matiere":"Maths","niveau":"6ème 1","professeur":"M. Koné","jour":"MONDAY","debut":"08:00:00","fin":"09:00:00","couleur":"#6C5CE7","niveauOrdre":1,"verrouille":false}]}

{"classes":["6ème 1","6ème 2","5ème 1"]}

संदर्भ — वेबहुक

हस्ताक्षरित इवेंट प्राप्त करें। स्कोप webhooks:manage। गुप्त कुंजी केवल निर्माण पर (या रोटेशन के बाद) लौटाई जाती है। इवेंट: timetable.job.completed, timetable.job.failed, timetable.published, webhook.test। प्रत्येक डिलीवरी हस्ताक्षरित (HMAC-SHA256) होती है और विफलता की स्थिति में 5 बार तक दोहराई जाती है। URL को SSRF के विरुद्ध सत्यापित किया जाता है (आंतरिक/निजी लक्ष्य अस्वीकृत)।

{"url":"https://exemple.com/webhooks/yap","events":["timetable.published","timetable.job.completed"]}

{"endpoint":{"id":"…","url":"…","events":["timetable.published"],"active":true},"secret":"whsec_…"}

{"endpoint":{"id":"…","url":"…"},"secret":"whsec_…"}

संदर्भ — डेमो (सार्वजनिक, बिना कुंजी)

प्रतिक्रियाओं का स्वरूप जानने के लिए अप्रमाणित सार्वजनिक एंडपॉइंट।

वेबहुक — हस्ताक्षर सत्यापित करें

प्रत्येक डिलीवरी एक POST JSON है जिसमें X-Webhook-Event, X-Webhook-Timestamp और X-Webhook-Signature = HMAC-SHA256(timestamp + "." + body, secret) हेडर होते हैं। रीप्ले से बचने के लिए हस्ताक्षर और timestamp की ताज़गी (5 मिनट से कम) सत्यापित करें। इवेंट : timetable.published, timetable.job.completed, timetable.job.failed, webhook.test।

POST https://votre-app/webhook
X-Webhook-Event: timetable.published
X-Webhook-Timestamp: 1712345678
X-Webhook-Signature: 9f86d081…

{ "event":"timetable.published", "jobId":"…", "etablissementId":"…", "occurredAt":"…" }

import crypto from "crypto";

// Express — vérifier la signature d'un webhook YA-Planning
app.post("/webhooks/yap", express.raw({ type: "*/*" }), (req, res) => {
  const ts  = req.header("X-Webhook-Timestamp");
  const sig = req.header("X-Webhook-Signature");
  const body = req.body.toString("utf8");

  const expected = crypto.createHmac("sha256", process.env.YAP_WEBHOOK_SECRET)
    .update(`${ts}.${body}`).digest("hex");

  // fraîcheur (anti-rejeu) : < 5 min
  const fresh = Math.abs(Date.now()/1000 - Number(ts)) < 300;
  if (!fresh || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
    return res.sendStatus(400);

  const event = JSON.parse(body); // { event, jobId, etablissementId, occurredAt }
  res.sendStatus(200);
});

कोड उदाहरण

# Vérifier ses droits
curl https://votre-domaine/api/v1/pub/v1/me \
  -H "X-API-Key: yap_live_xxxxxxxxxxxx"

# Générer un EDT puis suivre le job
JOB=$(curl -s -X POST .../api/v1/pub/v1/timetables/generate \
  -H "X-API-Key: yap_live_xxxx" -H "Content-Type: application/json" \
  -d '{"durationMinutes":5}' | jq -r .jobId)

curl .../api/v1/pub/v1/timetables/jobs/$JOB \
  -H "X-API-Key: yap_live_xxxx"

संस्करण और अवमूल्यन

API पथ में संस्करणित है (/api/v1/pub/v1/…)। हम फ़ील्ड और एंडपॉइंट पश्च-संगत तरीके से जोड़ते हैं; ये परिवर्धन कोई विच्छेद नहीं हैं, इसलिए सहिष्णु तरीके से कोड करें (अज्ञात फ़ील्ड को अनदेखा करें)। कोई भी विच्छेद एक नए प्रमुख संस्करण और कम से कम 90 दिनों की पूर्व-सूचना को जन्म देगा, जो Deprecation प्रतिक्रिया हेडर और नीचे दिए परिवर्तन-लॉग के माध्यम से घोषित की जाएगी।