API-documentatie

Met Shifton Taken kunt u het werk met het platform automatiseren en het via de open API aan externe diensten koppelen. Via de API zijn alle belangrijke entiteiten beschikbaar — taken, klanten, medewerkers, controlelijsten, inventaris, servicegebieden, documenten van Facturatie en rapporten — waardoor u Shifton kunt koppelen aan uw systemen voor HR, salarisadministratie en analyse, en ook aan de interne diensten van het bedrijf.

De documentatie is in twee versies gepubliceerd:

🚀 Nieuwe documentatie — de actuele versie van het naslagwerk met een bijgewerkte structuur en de nieuwste methodes: 👉 https://api2.shifton.com/openapi/
📄 Oude documentatie — de vorige versie (wordt nog steeds ondersteund voor bestaande integraties): 👉 https://api2.shifton.com/docs/

U kunt beide versies rechtstreeks vanuit de applicatie openen — in het gedeelte Developer, op het tabblad Overzicht, met de knoppen “Nieuwe documentatie” en “Oude documentatie”.

De documentatie is in twee talen beschikbaar. In de rechterbovenhoek van de pagina met de nieuwe documentatie staat een schakelaar EN / RU — de gekozen taal wordt onthouden.

Hoe u een API-sleutel krijgt

De API-sleutel maakt u in de applicatie zelf aan:

Open het gedeelte Developer.
Ga naar het tabblad API-sleutels (“API-sleutels”).
Klik op “API-sleutel aanmaken”.

Wat u bij het aanmaken van een sleutel invult

Het zijpaneel API-sleutel aanmaken wordt geopend met de velden:

Titel — de naam van de sleutel, een verplicht veld. Noem hem naar zijn doel, zodat later duidelijk is wat u kunt uitschakelen: “Export naar 1C”, “Rapporten voor analyse”.
Verloopt om — de datum waarna de sleutel niet meer werkt. Als u het veld leeg laat, is de geldigheidsduur onbeperkt.
Toegang — de omvang van de rechten van de sleutel:
Full access (act as me) — de sleutel werkt namens u en met uw rechten.
Beperkte machtigingen — een beperkte set machtigingen die u zelf kiest.

Klik op Toevoegen om de sleutel aan te maken, of op Annuleren om het paneel te sluiten.

📷 *Schermafbeelding van het paneel voor het aanmaken van een sleutel — op prod maken*

De sleutel wordt aangemaakt voor een bepaald bedrijf en werkt alleen met de gegevens daarvan. U kunt de sleutel op elk moment intrekken — het intrekken gaat onmiddellijk in en alle volgende verzoeken met die sleutel geven de fout 401 terug.

Belangrijk: de aangemaakte sleutel wordt maar één keer getoond. Kopieer hem meteen en bewaar hem op een veilige plek — u kunt hem niet nog een keer opvragen. Als de sleutel kwijt is, maak dan een nieuwe aan en trek de oude in.

Autorisatie

Alle verzoeken aan de API worden met de sleutel in de header ondertekend:

Authorization: Bearer {your_API_key}

Het basisadres van de API:

https://api2.shifton.com/work/1.0.0

Een verzoek zonder geldige sleutel geeft 401 terug en de body {"message":"Unauthenticated."}.

Het eerste verzoek

Om bijvoorbeeld de lijst met medewerkers van het bedrijf op te halen (vul uw eigen bedrijfs-ID in in plaats van {companyId}):

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

Hetzelfde via curl:

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

Het bedrijfs-ID ziet u in de adresbalk van de applicatie: app.shifton.com/c/8397/... — het getal na /c/.

Wat er via de API beschikbaar is

Het naslagwerk beslaat meer dan 360 methodes. De belangrijkste onderdelen voor buitendienst:

Taken — /companies/{companyId}/tasks: aanmaken, wijzigen, statussen, bestanden van taken.
Takenlijst (To Do) — /companies/{companyId}/todo.
Klanten — /companies/{companyId}/clients, en ook adressen en aangepaste velden van klanten.
Controlelijsten — /companies/{companyId}/checklists.
Servicegebieden — /companies/{companyId}/tasks/service-areas.
Vaardigheden — /companies/{companyId}/skills.
Medewerkers — /companies/{companyId}/employees: toevoegen, bewerken, ontslaan en herstellen.
Inventaris — artikelen, categorieën, sets en voorraden in de magazijnen.
Facturatie — offertes, werkorders, facturen, ontvangstbewijzen, documenttellers en het logo.
Rapporten — export van gegevens over werk en aanwezigheid.

Daarnaast zijn er roosters en diensten, verlof en verlofaanvragen, aanwezigheid, facturatie en SMS-facturatie, meldingen en modules beschikbaar.

Webhooks

Als u in plaats van regelmatige verzoeken aan de API gebeurtenissen wilt ontvangen op het moment dat ze plaatsvinden, gebruik dan webhooks — het tabblad Webhooks in het gedeelte Developer. Shifton stuurt zelf een verzoek naar uw adres wanneer de gewenste gebeurtenis plaatsvindt; de lijst met ondersteunde gebeurtenissen geeft een aparte methode terug.

Foutcodes

De API van Shifton gebruikt de standaard HTTP-statuscodes:

200 — het verzoek is succesvol uitgevoerd.
201 — het object is succesvol aangemaakt.
400 — onjuiste parameters van het verzoek.
401 — autorisatiefout: de sleutel is niet meegestuurd, is ongeldig of is ingetrokken.
403 — toegang geweigerd.
404 — de bron is niet gevonden (meestal een typefout in het adres van de methode).
500 — serverfout.

Tips voor het gebruik

Gebruik voor nieuwe integraties de nieuwe documentatie — de oude is er voor integraties die al draaien.
Om verzoeken te controleren zijn Postman of curl handig — daarmee ziet u het antwoord zonder ook maar één regel code te schrijven.
Bewaar de sleutel niet in leesbare vorm in de code en geef hem niet aan derden: de sleutel geeft toegang tot de gegevens van het bedrijf.
Houd u aan de limieten op de verzoekfrequentie (rate limits) — als u die overschrijdt, kan de toegang tot de API tijdelijk worden geblokkeerd.

Veelgestelde vragen

Vraag: Waar haal ik een API-sleutel vandaan? Antwoord: In de applicatie: het gedeelte Developer → tabblad API-sleutels → knop “API-sleutel aanmaken”. De sleutel wordt voor het huidige bedrijf uitgegeven.

Vraag: Ik heb het venster gesloten zonder de sleutel te kopiëren. Waar kan ik hem zien? Antwoord: Nergens — de sleutel wordt maar één keer getoond en wordt niet opnieuw uitgegeven. Maak een nieuwe sleutel aan en trek de oude in.

Vraag: Hoe trek ik een sleutel in als hij in verkeerde handen is gekomen? Antwoord: Verwijder hem op het tabblad API-sleutels. Het intrekken gaat onmiddellijk in: alle verzoeken met die sleutel geven meteen 401 terug.

Vraag: Wat is het verschil tussen “Full access” en “Restricted permissions”? Antwoord: Full access (act as me) geeft de sleutel dezelfde rechten als u hebt. Met Beperkte machtigingen geeft u de sleutel alleen de gekozen set machtigingen — dat is veiliger voor een integratie die maar een deel van de gegevens nodig heeft.

Vraag: Kan ik de geldigheidsduur van een sleutel beperken? Antwoord: Ja, met het veld Verloopt om bij het aanmaken. Als u dat niet invult, is de sleutel onbeperkt geldig.

Vraag: Werkt één sleutel voor meerdere bedrijven? Antwoord: Nee. De sleutel is gekoppeld aan het bedrijf waarin hij is aangemaakt en werkt alleen met de gegevens daarvan. Maak voor een ander bedrijf een aparte sleutel aan.

Vraag: Wat is het basisadres van de API? Antwoord: https://api2.shifton.com/work/1.0.0. Daarna volgt het pad van de methode, bijvoorbeeld /companies/{companyId}/tasks.

Vraag: Waar haal ik het bedrijfs-ID voor de verzoeken vandaan? Antwoord: Dat staat in de adresbalk van de applicatie direct na /c/ — in app.shifton.com/c/8397/tasks is het bedrijfs-ID bijvoorbeeld 8397.

Vraag: Welke versie van de documentatie moet ik gebruiken? Antwoord: Voor nieuwe integraties de nieuwe (api2.shifton.com/openapi). De oude (api2.shifton.com/docs) wordt ondersteund voor bestaande integraties.

Vraag: Is er documentatie in het Russisch? Antwoord: Ja. Op de pagina met de nieuwe documentatie staat in de rechterbovenhoek de schakelaar EN / RU.

Vraag: Waarmee test ik verzoeken aan de API? Antwoord: Het handigst zijn Postman of curl — daarmee stuurt u verzoeken en bekijkt u de antwoorden zonder code te schrijven.

Vraag: Waarom krijg ik 401, terwijl ik de sleutel heb gekopieerd? Antwoord: Controleer of de sleutel in de header Authorization wordt meegestuurd met het woord Bearer ervoor, of de sleutel niet is ingetrokken en of de geldigheidsduur niet is verlopen.

Vraag: Waarom krijg ik 404? Antwoord: Meestal klopt het adres niet: het basisdeel moet https://api2.shifton.com/work/1.0.0 zijn en in het pad van de methode moet de juiste {companyId} staan.

Vraag: Wat kan ik via de API automatiseren? Antwoord: Het aanmaken en wijzigen van taken, het werk met klanten en hun adressen, controlelijsten, servicegebieden, vaardigheden, medewerkers, inventaris, documenten van Facturatie en de export van rapporten, en ook roosters, diensten en verlof.

Vraag: Kan ik gebeurtenissen uit Shifton ontvangen in plaats van de API te bevragen? Antwoord: Ja, daarvoor zijn er webhooks — het tabblad Webhooks in het gedeelte Developer.

Vraag: Heeft het wijzigen van het wachtwoord invloed op de integratie? Antwoord: Nee. Integraties werken met de API-sleutel en niet met het wachtwoord van het account.