REST-Schnittstelle für Karriereportale von ontavio

Inhaltsverzeichnis

1. Allgemeine Information zur Nutzung der Schnittstelle
2. Stellenangebote
3. Unternehmensdaten
   1. Ansprechpartner
   2. Standorte
   3. Unternehmens-Uploads
   4. Standardmäßige Vorteile/Benefits des Unternehmens
   5. Jobbörsen des Unternehmens
4. Routen für allgemeine Informationen
   1. Kategorien
   2. HTML-Tags
5. Objektstruktur
   1. Stellenbeschreibung
   2. Ansprechpartner
   3. Standort
   4. Uploads
   5. Zeitarbeit

1. Allgemeine Information zur Nutzung der Schnittstelle

Syntax dieser Dokumentation

Die Routen in dieser REST-Schnittstelle müssen je nach Ziel der Anfrage angepasst werden.
Am Beginn jedes Themenabschnitts befindet sich eine Übersicht über die möglichen Routen. Fügen Sie diese zur jeweiligen Basis-URL hinzu, um die gewünschte Route zu erreichen.
Eckige Klammern bedeuten, dass alles zwischen ihnen optional ist, um einen fehlerfreien Ablauf der Anfrage sicherzustellen.
Geschweifte Klammern zeigen an, dass zwischen Ihnen Daten eingefügt werden müssen.

Allgemeine Information zur Schnittstelle

Wenn keine ID (bzw. Referenz-ID für Stellenangebote) in der URL für PUT- oder DELETE-Requests mitgeliefert wird, muss diese im Request-Body hinzugefügt werden, um das entsprechende Objekt zu bestimmen.
Bei POST- oder PUT-Requests für einzelne Stellenangebote ist es irrelevant, ob diese in einem Array oder als einzelnes Objekt gesendet werden.

Authentifizierung

Sie benötigen ihre Unternehmens-ID und einen unternehmensspezifischen Sicherheitsschlüssel, um einen JSON Web Token (JWT) zu erhalten. Senden sie diese Daten im Body ihrer Anfrage mittels eines form-data kodierten POST-Requests. Der JWT ist 60 Sekunden gültig. To receive test credentials for development, contact our support.

2. Stellenangebote

In POST- und PUT-Requests können folgende Daten als JSON im Request-body gesendet werden.

Standorte werden anhand ihrer ID oder ihres Namens identifiziert. Daraus folgt, dass wenn ein Standort gesendet wird, der in einem dieser Punkte übereinstimmt, die weiteren Standortdaten ignoriert werden. Wenn diese Daten geändert werden sollen, muss der Standort aktualisiert werden. Siehe dazu Abschnitt 3.2.

Dasselbe gilt für die Ansprechpartner, die anhand ihrer ID oder der E-Mail identifiziert werden. Hier können die Daten aktualisiert werden wie beschrieben in Abschnitt 3.1.

Beispiel POST oder PUT

 [
    {
        "ref": "1292346-2022",
        "title": "Worker in example job",
        "description": {
            "introHeadline": "Introduction Headline",
            "introText": "This is an introduction text.",
            "jobProfileText": "Job Profile Text. <strong>You can use HTML here.</strong>",
            "applicantProfileText": "Applicant Profile Text",
            "offerText": "Offer Text",
            "contactText": "Contact Information"
        },
        "applyUrl": "https:www.examplewebsite.com/apply/for-this-job",
        "startType": "date",
        "startFrom": "2022-01-19",
        "limitationType": "date",
        "limitationDate": "2022-03-23",
        "from": "2021-03-28",
        "to": "2022-03-28",
        "contract": 1,
        "categories": [
            "5d9debaf67a3b775bdc8c927",
            "5d9debae67a3b775bdc8c91e"
        ],
        "setReference": true,
        "status": "active",
        "portals": [
            "ksw",
            2,
            4
        ],
        "type": [
            "apprenticeship",
            "dual-study"
        ],
        "leadership": false,
        "students": true,
        "contactPersons": [
            {
                "email": "contact.person@example.com",
                "firstName": "Contact",
                "lastName": "Person",
                "position": "Leader of Example",
                "image": "https://examplewebsite.com/400x300/000/ff0.png",
                "salutation": "Herr",
                "phone": "0160123456789",
                "newsletter": false,
                "persistent": true
            },
            {
                "email": "existing.contact.person@example.com"
            }
        ],
        "locations": [
            {
                "name": "Main Location",
                "amount": 1
            },
            {
                "name": "New Location",
                "street": "Hundemstr. 2",
                "zip": "57368",
                "city": "Lennestadt",
                "logo": "https://linkToExampleImage.com/450x350/000/f0f.png",
                "amount": 1,
                "persistent": true
            }
        ],
        "uploads": {
            "images": [
                "https://linkToExampleImage.com/1200x600/000/ff0.png",
                "https://linkToExampleImage.com/1250x550/000/ff0.jpg"
            ]
        }
    },
    {
        …
    }
]

Beispiel DELETE

Fügen Sie für DELETE-Requests entweder die Referenz-ID der Stelle zur URL hinzu oder senden Sie ein Array mit Objekten im JSON-Format entsprechend der folgenden Tabelle im Body mit.

Beispiel DELETE-Request, bei dem die erste Stelle von Karriere-Südwestfalen und Karriere-Mittelhessen gelöscht wird, und die zweite von alle Jobbörsen

[
    {
        "ref": "123456789",
        "portals": ["ksw", "kmh"]
    },
    {
        "ref": "123456-2022"
    },
    {
	…
     }
]

3. Unternehmensdaten

3.1 Ansprechpartner

Beispiele

POST/PUT

[
   {
       "email": "erika@example.com",
       "firstName": "Erika",
       "lastName": "Mustermann",
       "salutation": "Frau",
       "position": "Personalleitung",
       "phone": "01234 / 123456",
       "emailAlias": "e.mustermann@example.com",
       "newsletter": false,
       "cpCompanyPortrait": true,
       "cpEmailCompanyPortrait": false,
       "cpPhoneCompanyPortrait": false,
       "cpEmailJoboffer": false,
       "cpPhoneJoboffer": false
   },
   ...
]

DELETE

[
    {
        "id": "621f6a03bdef404ecf3b20ca"
    },
    {
        "id": "6220d1a6bdef404ecf3b2172"
    },
    ...
]

3.2 Standorte

Beispiele

POST/PUT

[
   {
       "name": "Example Location",
       "city": "ExampleCity",
       "zip": 12345,
       "street" : "Example street 10",
       "region" : "Südwestfalen",
       "logo" : "https://example.com/logo/1234.jpg",
   }
   ...
]

DELETE

[
    {
        "id": "621f6a03bdef404ecfxxxxx"
    },
    {
        "id": "6220d1a6bdef404ecf3xxxxx"
    },
    ...
]

3.3 Unternehmens-Uploads

3.4 Standardmäßige Vorteile/Benefits des Unternehmens

Wenn sie nicht alle Unternehmensbenefits für ein bestimmtes Jobangebot anzeigen möchten, senden sie nur die IDs der gewollten Benefits in einem Array im Stellenangebot mit.

3.5 Jobbörsen des Unternehmens

4. Routen für allgemeine Informationen

4.1 Kategorien

Derzeit unterstützen wir folgende Kategorien, die Sie über ihre ID an uns übergeben können:

4.2 HTML-Tags

Die in der Stellenbeschreibung erlaubten Tags sind "<h3>", "<ul>", "<ol>", "<li>", "<a>", "<b>", "<strong>", "<br>", "<p>" und "<small>"..

5. Objektstruktur

5.1 Stellenbeschreibung

Sie können die in 4.2 erwähnten HTML-Tags in den Text-Teilen der Beschreibung nutzen.

Wenn Ihnen ein benötigter Teil des Textes fehlt, senden Sie einen leeren String für diesen Teil mit.

5.2 Ansprechpartner

5.3 Standort

5.4 Uploads

Wenn einem Stellenangebot keine Bilder hinzugefügt werden, wird das zweite Bild aus dem Unternehmensporträt hinzugefügt.

Erlaubte Formate sind: .jpg, .png und .gif.

Das bevorzugte Bildverhältnis für Stellenangebotsbilder ist 2:1 und die standardmäßige Größe ist 1200x600px.

Wenn das Verhältnis kleiner als 1,7 oder größer als 2,3 ist, wird es zugeschnitten. Pro Stellenangebot sind maximal 5 Bilder erlaubt.

Bilder von Ansprechpersonen sollten ein Seitenverhältnis von 1:1 haben, ansonsten werden sie in dieses Format zurechtgeschnitten.

5.5 Zeitarbeit