Guide : intégrer l'API publique Orkelis

L'API publique Orkelis vous permet d'integrer vos plannings, absences, utilisateurs et pointages avec vos outils existants : SIRH, ERP, logiciels de paie, outils de Business Intelligence, applications metier, etc. L'API suit les principes REST et utilise l'authentification par cle API. Ce guide couvre la generation des cles, l'authentification, tous les endpoints disponibles, la pagination, les webhooks et les bonnes pratiques de securite.

Prerequis

• Un plan Pro ou Enterprise (l'API publique n'est pas disponible sur le plan Essentiel).
• Un compte administrateur pour generer les cles API.
• Des connaissances de base en programmation et en appels HTTP/REST.
• Un outil pour tester les requetes : curl, Postman, Insomnia ou un langage de programmation (Python, JavaScript, PHP, etc.).

1. Generer une cle API

Les cles API sont le mecanisme d'authentification de l'API publique. Chaque cle est associee a des permissions specifiques (scopes) et peut avoir une date d'expiration.

1. Connectez-vous en tant qu'administrateur.
2. Allez dans Cles API (/dashboard/api-keys) depuis le menu lateral.
3. Cliquez sur Generer une cle API.
4. Renseignez les informations de la cle :

• Nom : un nom descriptif pour identifier l'usage de la cle (ex. "Integration Paie Sage", "Synchronisation SIRH", "Dashboard BI").
• Scopes : les permissions accordees a cette cle (voir la section Scopes ci-dessous).
• Date d'expiration : optionnel, mais fortement recommande pour les integrations temporaires.

1. Cliquez sur Creer.
2. La cle API s'affiche une seule fois. Copiez-la immediatement et stockez-la dans un endroit securise.

Securite critique : la cle API est affichee une seule et unique fois lors de sa creation. Si vous la perdez, vous devrez en generer une nouvelle. Stockez-la dans un gestionnaire de secrets (Vault, AWS Secrets Manager, Infisical, etc.). Ne la commitez jamais dans un depot git et ne la transmettez jamais par e-mail non chiffre.

Scopes disponibles

Les scopes controlent les permissions de chaque cle API. Attribuez uniquement les scopes necessaires a chaque integration (principe de moindre privilege) :

• read:users — Lecture des utilisateurs : lister, rechercher et consulter les profils des agents.
• write:users — Ecriture des utilisateurs : creer, modifier et desactiver des agents.
• read:plannings — Lecture des plannings : consulter les plannings, les affectations et les creneaux.
• write:plannings — Ecriture des plannings : creer et modifier des affectations.
• read:absences — Lecture des absences : consulter les absences et les demandes de conge.
• write:absences — Ecriture des absences : creer, modifier et annuler des absences.
• read:time-entries — Lecture des pointages : consulter les entrees de temps et les feuilles de temps.

2. Authentification

Toutes les requetes a l'API publique doivent inclure le header HTTP X-API-Key avec votre cle. L'API retourne une erreur 401 Unauthorized si la cle est manquante, invalide ou expiree.

Exemple d'authentification

curl -H "X-API-Key: sk_live_votre_cle_api" \
  https://orkelis.app/api/v1/public/users

Format des requetes

L'API accepte et retourne du JSON. Incluez le header Content-Type: application/json pour les requetes POST, PATCH et PUT.

curl -X POST \
  -H "X-API-Key: sk_live_votre_cle_api" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}' \
  https://orkelis.app/api/v1/public/endpoint

Codes de reponse HTTP

• 200 OK : requete traitee avec succes.
• 201 Created : ressource creee avec succes.
• 400 Bad Request : donnees invalides (verifiez le corps de la requete).
• 401 Unauthorized : cle API manquante ou invalide.
• 403 Forbidden : scope insuffisant pour cette operation.
• 404 Not Found : ressource inexistante.
• 422 Unprocessable Entity : donnees valides mais non traitables (ex. conflit de dates).
• 429 Too Many Requests : limite de taux atteinte (voir la section Rate Limiting).
• 500 Internal Server Error : erreur interne (contactez le support).

3. Endpoints disponibles

Utilisateurs

Les endpoints utilisateurs permettent de gerer les profils de vos agents via l'API.

• GET /api/v1/public/users — Lister les utilisateurs (pagine) — scope: read:users
• GET /api/v1/public/users/:id — Detail d'un utilisateur — scope: read:users
• POST /api/v1/public/users — Creer un utilisateur — scope: write:users
• PATCH /api/v1/public/users/:id — Modifier un utilisateur — scope: write:users
• DELETE /api/v1/public/users/:id — Desactiver un utilisateur — scope: write:users

Structure d'un utilisateur

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "firstName": "Marie",
  "lastName": "Dupont",
  "email": "[email protected]",
  "role": "AGENT",
  "contractHours": 35,
  "specialty": "IDE",
  "status": "ACTIVE",
  "services": ["service-uuid-1"],
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-03-10T14:20:00Z"
}

Plannings

• GET /api/v1/public/plannings — Lister les plannings (filtre par dates, service) — scope: read:plannings
• GET /api/v1/public/plannings/:id — Detail d'une affectation — scope: read:plannings
• POST /api/v1/public/plannings — Creer une affectation — scope: write:plannings
• PATCH /api/v1/public/plannings/:id — Modifier une affectation — scope: write:plannings
• DELETE /api/v1/public/plannings/:id — Supprimer une affectation — scope: write:plannings

Parametres de filtrage des plannings

• startDate (requis) : date de debut au format YYYY-MM-DD.
• endDate (requis) : date de fin au format YYYY-MM-DD.
• serviceId : filtrer par identifiant de service.
• userId : filtrer par identifiant d'agent.
• shiftType : filtrer par type de poste (MORNING, AFTERNOON, NIGHT, etc.).

Absences

• GET /api/v1/public/absences — Lister les absences (filtre par dates, agent, type) — scope: read:absences
• GET /api/v1/public/absences/:id — Detail d'une absence — scope: read:absences
• POST /api/v1/public/absences — Creer une absence — scope: write:absences
• PATCH /api/v1/public/absences/:id — Modifier une absence — scope: write:absences
• DELETE /api/v1/public/absences/:id — Annuler une absence — scope: write:absences

Types d'absence

Le champ type accepte les valeurs suivantes :

• CONGE_PAYE — Conge paye.
• CONGE_SANS_SOLDE — Conge sans solde.
• MALADIE — Arret maladie.
• FORMATION — Journee de formation.
• ECHANGE — Echange de poste entre agents.

Pointages

• GET /api/v1/public/time-entries — Lister les pointages (filtre par dates, agent, methode) — scope: read:time-entries
• GET /api/v1/public/time-entries/:id — Detail d'un pointage — scope: read:time-entries

Parametres de filtrage des pointages

• startDate (requis) : date de debut au format YYYY-MM-DD.
• endDate (requis) : date de fin au format YYYY-MM-DD.
• userId : filtrer par identifiant d'agent.
• method : filtrer par methode de pointage (KIOSK, MOBILE, MANUAL).

4. Pagination

Toutes les listes retournees par l'API sont paginées. L'API supporte deux modes de pagination :

Pagination par page (offset)

La pagination classique par numero de page, adaptee pour les interfaces utilisateur :

GET /api/v1/public/users?page=2&limit=50

• page : numero de page, a partir de 1 (defaut : 1).
• limit : nombre d'elements par page (defaut : 20, minimum : 1, maximum : 100).

Pagination par curseur

La pagination par curseur est recommandee pour les synchronisations et les gros volumes de donnees. Elle est plus performante et coherente en cas de modifications concurrentes :

GET /api/v1/public/users?cursor=eyJpZCI6IjEyMyJ9&limit=50

Quand le parametre cursor est fourni, le parametre page est ignore. Utilisez le champ nextCursor de la reponse pour parcourir les pages suivantes. Quand nextCursor est null, vous avez atteint la derniere page.

Format de reponse pagine

{
  "data": [
    { "id": "uuid-1", "firstName": "Marie", "lastName": "Dupont", "..." : "..." },
    { "id": "uuid-2", "firstName": "Paul", "lastName": "Martin", "..." : "..." }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "nextCursor": "eyJpZCI6InV1aWQtMiJ9",
    "hasMore": true
  }
}

5. Rate Limiting

L'API impose des limites de taux pour garantir la stabilite du service :

• Plan Pro : 100 requetes par minute par cle API.
• Plan Enterprise : 1 000 requetes par minute par cle API.
• Les headers de reponse incluent les informations de rate limit :

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1711234567

Si vous depassez la limite, l'API retourne une erreur 429 Too Many Requests. Attendez le nombre de secondes indique dans le header Retry-After avant de retenter.

Bonne pratique : implementez un mecanisme d'exponential backoff dans vos integrations. En cas d'erreur 429, attendez 1 seconde, puis 2, puis 4, etc., avant chaque nouvelle tentative.

6. Exemples pratiques

Recuperer tous les agents actifs

curl -H "X-API-Key: sk_live_xxxxx" \
  "https://orkelis.app/api/v1/public/users?limit=100&status=ACTIVE"

Recuperer les plannings de la semaine

curl -H "X-API-Key: sk_live_xxxxx" \
  "https://orkelis.app/api/v1/public/plannings?startDate=2026-03-16&endDate=2026-03-22"

Recuperer les plannings d'un service specifique

curl -H "X-API-Key: sk_live_xxxxx" \
  "https://orkelis.app/api/v1/public/plannings?startDate=2026-03-16&endDate=2026-03-22&serviceId=service-uuid"

Creer un utilisateur

curl -X POST \
  -H "X-API-Key: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Sophie",
    "lastName": "Bernard",
    "email": "[email protected]",
    "role": "AGENT",
    "contractHours": 35,
    "specialty": "AS",
    "services": ["service-uuid-1"]
  }' \
  "https://orkelis.app/api/v1/public/users"

Creer une absence

curl -X POST \
  -H "X-API-Key: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "startDate": "2026-03-20",
    "endDate": "2026-03-22",
    "type": "CONGE_PAYE",
    "reason": "Vacances familiales"
  }' \
  "https://orkelis.app/api/v1/public/absences"

Recuperer les pointages du mois

curl -H "X-API-Key: sk_live_xxxxx" \
  "https://orkelis.app/api/v1/public/time-entries?startDate=2026-03-01&endDate=2026-03-31"

Pagination par curseur (boucle complete)

#!/bin/bash
# Synchroniser tous les utilisateurs avec pagination par curseur
BASE_URL="https://orkelis.app/api/v1/public/users"
API_KEY="sk_live_xxxxx"
CURSOR=""

while true; do
  if [ -z "$CURSOR" ]; then
    RESPONSE=$(curl -s -H "X-API-Key: $API_KEY" "$BASE_URL?limit=100")
  else
    RESPONSE=$(curl -s -H "X-API-Key: $API_KEY" "$BASE_URL?limit=100&cursor=$CURSOR")
  fi

  # Traiter les donnees
  echo "$RESPONSE" | jq '.data[] | .firstName + " " + .lastName'

  # Recuperer le curseur suivant
  CURSOR=$(echo "$RESPONSE" | jq -r '.meta.nextCursor')
  HAS_MORE=$(echo "$RESPONSE" | jq -r '.meta.hasMore')

  if [ "$HAS_MORE" != "true" ]; then
    break
  fi
done

7. Webhooks

Pour recevoir des notifications en temps reel lorsque des evenements se produisent dans Orkelis, configurez des webhooks. Les webhooks envoient des requetes HTTP POST a l'URL de votre choix.

Configurer un webhook

1. Allez dans Webhooks (/dashboard/webhooks) dans le menu lateral.
2. Cliquez sur Ajouter un webhook.
3. Renseignez l'URL cible (ex. https://votre-serveur.com/webhooks/orkelis).
4. Selectionnez les evenements a ecouter :

• planning.published — Un planning a ete publie.
• planning.updated — Un planning a ete modifie.
• absence.created — Une absence a ete creee.
• absence.approved — Une absence a ete validee.
• absence.rejected — Une absence a ete refusee.
• user.created — Un utilisateur a ete cree.
• user.updated — Un utilisateur a ete modifie.
• time-entry.created — Un pointage a ete enregistre.

1. Optionnel : ajoutez un secret pour verifier la signature des webhooks.
2. Cliquez sur Enregistrer.

Format du payload webhook

{
  "event": "absence.approved",
  "timestamp": "2026-03-17T10:30:00Z",
  "data": {
    "id": "absence-uuid",
    "userId": "user-uuid",
    "type": "CONGE_PAYE",
    "startDate": "2026-03-20",
    "endDate": "2026-03-22",
    "status": "APPROVED"
  }
}

Verification de la signature

Si vous avez configure un secret, chaque requete webhook inclut un header X-Webhook-Signature contenant un HMAC SHA-256 du corps de la requete. Verifiez cette signature dans votre serveur pour vous assurer que le webhook provient bien d'Orkelis.

# Verification en Python
import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

8. Gestion des cles API

La gestion rigoureuse de vos cles API est essentielle pour la securite de vos donnees.

• Rotation : regenerez une cle sans la supprimer via le bouton Rotation dans la page Cles API. L'ancienne cle est immediatement invalidee et remplacee par une nouvelle. Mettez a jour votre integration dans la foulee.
• Revocation : supprimez une cle compromise via le bouton Supprimer. Toutes les requetes utilisant cette cle recevront une erreur 401.
• Logs d'utilisation : consultez l'historique d'utilisation de chaque cle dans l'onglet Logs : nombre de requetes, dates, endpoints appeles, codes de reponse, adresses IP sources.
• Expiration : definissez une date d'expiration pour les cles temporaires. Orkelis envoie un e-mail de rappel 7 jours avant l'expiration.

Principe de moindre privilege : creez une cle API par integration avec uniquement les scopes necessaires. Par exemple, une integration de paie n'a besoin que de read:time-entries et read:users. Cela limite l'impact en cas de compromission.

9. Bonnes pratiques d'integration

• Utilisez la pagination par curseur pour les synchronisations volumineuses : elle est plus performante et coherente que la pagination par page.
• Implementez un exponential backoff en cas d'erreur 429 ou 5xx.
• Stockez les cles API dans un gestionnaire de secrets (jamais en dur dans le code).
• Verifiez les signatures des webhooks pour eviter les attaques par injection.
• Loguez toutes les erreurs API de votre cote pour faciliter le depannage.
• Testez vos integrations sur un environnement de staging avant la production.
• Surveillez la consommation de votre cle via l'onglet Logs de la page Cles API.

10. Depannage

• Erreur 401 Unauthorized : la cle API est manquante, invalide ou expiree. Verifiez le header X-API-Key et la validite de votre cle.
• Erreur 403 Forbidden : la cle n'a pas le scope necessaire pour cette operation. Verifiez les scopes attribues a votre cle dans la page Cles API.
• Erreur 404 Not Found : la ressource demandee n'existe pas. Verifiez l'identifiant (UUID) utilise dans l'URL.
• Erreur 422 Unprocessable Entity : les donnees sont valides mais incoherentes (ex. date de fin avant date de debut, agent inexistant). Consultez le champ errors de la reponse pour le detail.
• Erreur 429 Too Many Requests : vous avez depasse la limite de taux. Attendez le delai indique dans le header Retry-After.
• Webhook non recu : verifiez que votre URL est accessible publiquement (pas localhost). Consultez les logs de livraison dans Webhooks > Logs pour voir les tentatives et les codes de reponse de votre serveur.
• Donnees manquantes dans la reponse : certains champs ne sont retournes que si vous avez le scope correspondant. Verifiez vos permissions.

Support technique API : pour toute question sur l'API publique, contactez notre equipe technique a [email protected] ou consultez la documentation interactive (Swagger) a orkelis.app/api/docs.