مرجع API v1

النقاط النهائية

GET/api/v1عام

كتالوج موثَّق ذاتيًا لواجهة API (عام، دون token).

مثال على الطلب

curl "https://www.superalternance.com/api/v1"

مثال على الرد

{
  "name": "superalternance API partenaires",
  "version": "1",
  "authentication": { "type": "bearer", "description": "…" },
  "endpoints": [ … ]
}

GET/api/v1/suggestيتطلب token

إكمال تلقائي «مهنة أو تكوين» لشريط بحث.

المعاملات

المعامل	النوع	مطلوب	الوصف
`q`	string	نعم	النص المُدخَل (≥ حرفان).
`limit`	int	لا	عدد الاقتراحات (1–20، الافتراضي 8).
`types`	csv	لا	Familles à renvoyer : rome \| formation \| job (défaut : toutes). Ex. rome,formation pour une autocomplétion légère.

مثال على الطلب

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.superalternance.com/api/v1/suggest?q=boul&limit=5"

مثال على الرد

{
  "query": "boul",
  "suggestions": [
    { "kind": "rome", "value": "Boulanger", "secondary": "Métier" },
    { "kind": "formation", "value": "CAP Boulanger", "secondary": "CFA des métiers" }
  ]
}

GET/api/v1/placesيتطلب token

إكمال تلقائي للأماكن: الأقاليم والمحافظات والبلديات.

المعاملات

المعامل	النوع	مطلوب	الوصف
`q`	string	نعم	النص المُدخَل (≥ حرفان).
`limit`	int	لا	عدد الاقتراحات (1–12، الافتراضي 8).

مثال على الطلب

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.superalternance.com/api/v1/places?q=lyon"

مثال على الرد

{
  "query": "lyon",
  "suggestions": [
    { "kind": "city", "value": "Lyon", "secondary": "69001 · Rhône", "lat": 45.758, "lng": 4.835 }
  ]
}

GET/api/v1/searchيتطلب token

بحث موحَّد للعروض + التكوينات، قابل للتصفية حسب المكان والمهنة والتكوين والمستوى.

المعاملات

المعامل	النوع	مطلوب	الوصف
`q`	string	لا	نص حر (عنوان التكوين، كلمات مفتاحية).
`metier`	string	لا	اسم المهنة — يُحوَّل إلى رموز ROME (مثل LBA).
`romes`	string	لا	Périmètre ROME explicite, exclusif de metier : domaines, familles ou codes séparés par des virgules (H,I11,I13 = industrie ; K19 = droit). Pour viser un secteur.
`lieu`	string	لا	الجهة / المحافظة / البلدية.
`lat`	float	لا	خط العرض (بحث بالنطاق).
`lng`	float	لا	خط الطول (بحث بالنطاق).
`radius`	float	لا	نصف القطر بالكيلومتر (الافتراضي 30).
`type`	enum	لا	jobs \| formations \| all (الافتراضي all).
`niveau`	csv	لا	مستويات الشهادة من بين 3,4,5,6,7 (3=CAP … 7=Bac+5).
`sort`	enum	لا	relevance \| date \| diploma (الافتراضي relevance).
`limit`	int	لا	حجم الصفحة (1–100، الافتراضي 20).
`offset`	int	لا	إزاحة التصفح (الافتراضي 0).

مثال على الطلب

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.superalternance.com/api/v1/search?metier=boulanger&lieu=Lyon&type=jobs&limit=5"

مثال على الرد

{
  "filters": { "metier": "boulanger", "resolvedRomeCodes": ["D1102", "D1104"], "lieu": "Lyon", "type": "jobs" },
  "pagination": { "limit": 5, "offset": 0 },
  "totals": { "jobs": 42, "formations": 0 },
  "results": [
    {
      "kind": "job", "id": "…", "title": "Boulanger en alternance",
      "subtitle": "Maison Dupain", "companyName": "Maison Dupain",
      "city": "Lyon", "departementNumber": "69",
      "latitude": 45.75, "longitude": 4.84,
      "contractType": "Apprentissage", "rhythm": "2j/semaine",
      "creationDate": "2026-06-01", "partnerLabel": null,
      "diplomaLevel": "CAP", "diploma": null, "rncpCode": null, "period": null,
      "tags": [{ "label": "Apprentissage", "type": "job" }, { "label": "CAP", "type": null }],
      "meta": ["Lyon (69)", "Publié il y a 3 jours"],
      "labels": ["Apprentissage", "CAP"],
      "url": "https://www.superalternance.com/fr/offres/…"
    }
  ]
}

GET/api/v1/jobs/latestيتطلب token

أحدث عروض التناوب المنشورة، مع تصفية اختيارية حسب المكان.

المعاملات

المعامل	النوع	مطلوب	الوصف
`lieu`	string	لا	الجهة / المحافظة / البلدية.
`lat`	float	لا	خط العرض (بحث بالنطاق).
`lng`	float	لا	خط الطول (بحث بالنطاق).
`radius`	float	لا	نصف القطر بالكيلومتر (الافتراضي 30).
`limit`	int	لا	عدد العروض (1–100، الافتراضي 20).

مثال على الطلب

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.superalternance.com/api/v1/jobs/latest?lieu=Bordeaux&limit=10"

مثال على الرد

{
  "filters": { "lieu": "Bordeaux" },
  "total": 10,
  "jobs": [
    { "kind": "job", "id": "…", "title": "Développeur web en alternance",
      "subtitle": "Acme", "companyName": "Acme", "city": "Bordeaux", "departementNumber": "33",
      "latitude": 44.84, "longitude": -0.58,
      "contractType": "Apprentissage", "rhythm": null, "creationDate": "2026-06-30",
      "diplomaLevel": "Bac+3", "tags": [{ "label": "Apprentissage", "type": "job" }],
      "meta": ["Bordeaux (33)", "Publié hier"],
      "labels": ["Apprentissage"], "url": "https://www.superalternance.com/fr/offres/…" }
  ]
}

GET/api/v1/jobs/{id}يتطلب token

تفاصيل كاملة لعرض: العقد، صاحب العمل، الموقع، التقديم.

المعاملات

المعامل	النوع	مطلوب	الوصف
`id`	path	نعم	معرّف العرض (حقل `id` المُعاد من البحث).

مثال على الطلب

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.superalternance.com/api/v1/jobs/abc123"

مثال على الرد

{
  "job": {
    "id": "abc123", "title": "Boulanger en alternance",
    "contractTypes": ["Apprentissage"], "duration": "24 mois",
    "location": { "city": "Lyon", "zipCode": "69003", "region": "Auvergne-Rhône-Alpes" },
    "company": { "name": "Maison Dupain", "siret": "…", "siren": "…" },
    "apply": { "email": null, "url": "…" }
  }
}

GET/api/v1/formations/{id}يتطلب token

تفاصيل كاملة لتكوين: الشهادة، RNCP، الهيئة (CFA)، الوتيرة.

المعاملات

المعامل	النوع	مطلوب	الوصف
`id`	path	نعم	معرّف التكوين (حقل `id` المُعاد من البحث).

مثال على الطلب

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.superalternance.com/api/v1/formations/xyz789"

مثال على الرد

{
  "formation": {
    "id": "xyz789", "title": "CAP Boulanger", "diploma": "CAP",
    "rncpCode": "RNCP…", "targetDiplomaLevel": "3", "period": "2 ans", "onisepUrl": "…",
    "location": { "city": "Lyon", "region": "Auvergne-Rhône-Alpes" },
    "cfa": { "name": "CFA des métiers", "siret": "…" },
    "contact": { "phone": "…", "email": null, "hasEmail": true },
    "training": { "objectives": "Maîtriser les techniques…", "programme": "…", "comment": null }
  }
}

GET/api/v1/companies/{siret}يتطلب token

ملف صاحب العمل حسب SIRET وقائمة بعروض التناوب المفتوحة الخاصة به.

المعاملات

المعامل	النوع	مطلوب	الوصف
`siret`	path	نعم	SIRET مكوَّن من 14 رقمًا.

مثال على الطلب

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.superalternance.com/api/v1/companies/12345678901234"

مثال على الرد

{
  "company": {
    "siret": "12345678901234", "siren": "123456789", "name": "Maison Dupain",
    "size": "10 à 19 salariés", "nafCodes": ["1071C"],
    "location": { "city": "Lyon", "region": "Auvergne-Rhône-Alpes" },
    "openJobsCount": 3, "openJobs": [ … ]
  }
}

GET/api/v1/statsيتطلب token

إحصائيات مُجمَّعة للمنصة (+ عدادات حسب المهنة).

المعاملات

المعامل	النوع	مطلوب	الوصف
`metier`	string	لا	إذا قُدِّم، يضيف العدادات الخاصة بهذه المهنة.
`romes`	string	لا	Périmètre ROME explicite (exclusif de metier) : ajoute romes { scope, codes, jobs, formations } et restreint lieu à ce périmètre. Pour compter un secteur.
`lieu`	string	لا	Nombre RÉEL d'offres actives et de formations du lieu (mêmes formes que /search), sans plafond ; restreint au métier si fourni. null si le lieu n'est pas reconnu.

مثال على الطلب

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.superalternance.com/api/v1/stats?metier=boulanger&lieu=Saint-Denis%20(974)"

مثال على الرد

{
  "jobs": 17658, "formations": 58596, "cfa": 6923,
  "lastSyncAt": "2026-06-04T21:01:06.369Z",
  "metier": { "name": "boulanger", "jobs": 412, "formations": 120, "diplomas": 8, "match": "rome" },
  "lieu": { "name": "Saint-Denis (974)", "metier": "boulanger", "match": "rome", "jobs": 6, "formations": 3 }
}

الحالة	الرمز	المعنى
`400`	`bad_request`	مُعامِل مفقود أو غير صالح.
`401`	`unauthorized`	token الوصول مفقود.
`403`	`forbidden`	token الوصول غير صالح.
`404`	`not_found`	المورد غير موجود.
`500`	`internal`	خطأ في الخادم أو واجهة API غير مهيَّأة.
`503`	`unavailable`	Résolution du métier momentanément indisponible : réessayer après le délai Retry-After.

المصادقة

النقاط النهائية

مثال على الطلب

مثال على الرد

المعاملات

مثال على الطلب

مثال على الرد

المعاملات

مثال على الطلب

مثال على الرد

المعاملات

مثال على الطلب

مثال على الرد

المعاملات

مثال على الطلب

مثال على الرد

المعاملات

مثال على الطلب

مثال على الرد

المعاملات

مثال على الطلب

مثال على الرد

المعاملات

مثال على الطلب

مثال على الرد

المعاملات

مثال على الطلب

مثال على الرد

رموز الأخطاء

لوكلاء الذكاء الاصطناعي