Uwierzytelnianie, endpointy, parametry, przykłady curl i odpowiedzi JSON. Baza: wszystkie adresy URL są względne wobec produkcyjnego źródła.
Przekazuj swój token partnerski w jednym z tych nagłówków HTTP przy każdym żądaniu (poza katalogiem publicznym):
Authorization: Bearer <token>
# ou
X-Api-Key: <token>Przykłady zapytań (curl) i odpowiedzi (JSON) są podawane identycznie we wszystkich językach — są to dane techniczne.
/api/v1PublicznySamodokumentujący się katalog API (publiczny, bez tokenu).
curl "https://www.superalternance.com/api/v1"{
"name": "superalternance API partenaires",
"version": "1",
"authentication": { "type": "bearer", "description": "…" },
"endpoints": [ … ]
}/api/v1/suggestWymagany tokenAutouzupełnianie „zawód lub szkolenie” dla paska wyszukiwania.
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
q | string | Tak | Wprowadzony tekst (≥ 2 znaki). |
limit | int | Nie | Liczba podpowiedzi (1–20, domyślnie 8). |
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" }
]
}/api/v1/placesWymagany tokenAutouzupełnianie lokalizacji: regiony, departamenty i gminy.
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
q | string | Tak | Wprowadzony tekst (≥ 2 znaki). |
limit | int | Nie | Liczba podpowiedzi (1–12, domyślnie 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 }
]
}/api/v1/searchWymagany tokenUjednolicone wyszukiwanie ofert + szkoleń, filtrowane według lokalizacji, zawodu, szkolenia i poziomu.
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
q | string | Nie | Tekst dowolny (tytuł szkolenia, słowa kluczowe). |
metier | string | Nie | Nazwa zawodu — rozwiązywana do kodów ROME (jak LBA). |
lieu | string | Nie | Region / departament / gmina. |
lat | float | Nie | Szerokość geograficzna (wyszukiwanie według promienia). |
lng | float | Nie | Długość geograficzna (wyszukiwanie według promienia). |
radius | float | Nie | Promień w km (domyślnie 30). |
type | enum | Nie | jobs | formations | all (domyślnie all). |
niveau | csv | Nie | Poziomy dyplomu spośród 3,4,5,6,7 (3=CAP … 7=Bac+5). |
sort | enum | Nie | relevance | date | diploma (domyślnie relevance). |
limit | int | Nie | Rozmiar strony (1–100, domyślnie 20). |
offset | int | Nie | Przesunięcie paginacji (domyślnie 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 · Lyon", "city": "Lyon",
"latitude": 45.75, "longitude": 4.84,
"labels": ["Apprentissage", "CAP"],
"url": "https://www.superalternance.com/fr/offres/…"
}
]
}/api/v1/jobs/latestWymagany tokenNajnowsze opublikowane oferty nauki zawodu, z opcjonalnym filtrem lokalizacji.
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
lieu | string | Nie | Region / departament / gmina. |
lat | float | Nie | Szerokość geograficzna (wyszukiwanie według promienia). |
lng | float | Nie | Długość geograficzna (wyszukiwanie według promienia). |
radius | float | Nie | Promień w km (domyślnie 30). |
limit | int | Nie | Liczba ofert (1–100, domyślnie 20). |
curl -H "Authorization: Bearer $TOKEN" \
"https://www.superalternance.com/api/v1/jobs/latest?lieu=Bordeaux&limit=10"{
"filters": { "lieu": "Bordeaux" },
"total": 10,
"jobs": [
{ "id": "…", "title": "Développeur web en alternance", "subtitle": "Acme · Bordeaux",
"city": "Bordeaux", "latitude": 44.84, "longitude": -0.58,
"labels": ["Apprentissage"], "url": "https://www.superalternance.com/fr/offres/…" }
]
}/api/v1/jobs/{id}Wymagany tokenPełne szczegóły oferty: umowa, pracodawca, lokalizacja, aplikowanie.
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
id | path | Tak | Identyfikator oferty (pole `id` zwracane przez wyszukiwanie). |
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": "…" }
}
}/api/v1/formations/{id}Wymagany tokenPełne szczegóły szkolenia: dyplom, RNCP, placówka (CFA), tryb nauki.
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
id | path | Tak | Identyfikator szkolenia (pole `id` zwracane przez wyszukiwanie). |
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",
"location": { "city": "Lyon", "region": "Auvergne-Rhône-Alpes" },
"cfa": { "name": "CFA des métiers", "siret": "…" }
}
}/api/v1/companies/{siret}Wymagany tokenProfil pracodawcy według SIRET i lista jego otwartych ofert nauki zawodu.
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
siret | path | Tak | 14-cyfrowy SIRET. |
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": [ … ]
}
}/api/v1/statsWymagany tokenZagregowane statystyki platformy (+ liczniki według zawodu).
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
metier | string | Nie | Jeśli podano, dodaje liczniki właściwe dla tego zawodu. |
curl -H "Authorization: Bearer $TOKEN" \
"https://www.superalternance.com/api/v1/stats?metier=boulanger"{
"jobs": 17658, "formations": 58596, "cfa": 6923,
"lastSyncAt": "2026-06-04T21:01:06.369Z",
"metier": { "name": "boulanger", "jobs": 42, "formations": 120, "diplomas": 8 }
}Błędy mają jednolitą postać: { "error": { "code": "…", "message": "…" } }.
| Status | Kod | Znaczenie |
|---|---|---|
400 | bad_request | Brakujący lub nieprawidłowy parametr. |
401 | unauthorized | Brak tokenu dostępu. |
403 | forbidden | Nieprawidłowy token dostępu. |
404 | not_found | Nie znaleziono zasobu. |
500 | internal | Błąd serwera lub nieskonfigurowane API. |
Publiczny katalog JSON opisuje wszystkie endpointy, parametry i błędy w sposób czytelny dla maszyny, bez uwierzytelniania. Idealny punkt wejścia dla agenta poznającego API.