Intégration Terminal de Pointage

NERP Suite expose un endpoint générique qui accepte les événements de pointage depuis n'importe quel terminal physique (badge NFC, empreinte digitale, code PIN, QR code, etc.). Votre terminal envoie un simple appel HTTP — NERP Suite se charge de l'enregistrement, de la validation et de la mise à jour du statut de l'employé.

Pré-requis

1. Un terminal capable d'envoyer des requêtes HTTP (push to URL)
2. Une clé API terminal générée dans le dashboard RH
3. Les matricules employés configurés dans NERP Suite

---

Authentification

Toutes les requêtes doivent inclure la clé terminal dans le header X-Terminal-Key :

X-Terminal-Key: tk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Les clés terminal suivent le format :

tk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• tk — Terminal Key
• live — Environnement production (test pour le sandbox)
• XXXX... — Identifiant unique généré

---

Envoyer un événement

POST /api/hr/time/terminal/event

Headers

Corps de la requête

{
  "employeeNumber": "EMP-0042",
  "eventType": "CLOCK_IN",
  "timestamp": "2026-05-13T08:47:00Z",
  "terminalId": "terminal-hall-entree",
  "metadata": {
    "method": "NFC",
    "cardUid": "04:A3:B2:C1:D0:E9:F8",
    "location": "Hall d'entrée"
  }
}

Paramètres

Réponse — succès 200

{
  "success": true,
  "data": {
    "entryId": "cuid_abc123",
    "employeeNumber": "EMP-0042",
    "employeeName": "Marie Dubois",
    "eventType": "CLOCK_IN",
    "clockIn": "2026-05-13T08:47:00Z",
    "clockOut": null,
    "status": "OPEN"
  }
}

Réponse — doublon 200

Si l'employé a déjà pointé son arrivée et envoie un second CLOCK_IN, NERP Suite retourne l'entrée existante sans créer de doublon :

{
  "success": true,
  "duplicate": true,
  "data": {
    "entryId": "cuid_abc123",
    "employeeNumber": "EMP-0042",
    "eventType": "CLOCK_IN",
    "clockIn": "2026-05-13T08:47:00Z",
    "status": "OPEN"
  }
}

---

Vérifier le statut d'un terminal

GET /api/hr/time/terminal/status

Retourne le statut du terminal associé à la clé API utilisée.

Réponse 200

{
  "terminalId": "terminal-hall-entree",
  "companyId": "uuid-de-la-company",
  "companyName": "ACME Bénin",
  "active": true,
  "lastEventAt": "2026-05-13T08:47:00Z"
}

---

Codes d'erreur

---

Exemples complets

Pointage arrivée — badge NFC

curl -X POST "https://api.nerpsuite.com/api/hr/time/terminal/event" \
  -H "X-Terminal-Key: tk_live_votre_cle_ici" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeNumber": "EMP-0042",
    "eventType": "CLOCK_IN",
    "timestamp": "2026-05-13T08:47:00Z",
    "terminalId": "terminal-hall-entree",
    "metadata": {
      "method": "NFC",
      "cardUid": "04:A3:B2:C1:D0:E9:F8"
    }
  }'

Pointage départ — empreinte digitale

curl -X POST "https://api.nerpsuite.com/api/hr/time/terminal/event" \
  -H "X-Terminal-Key: tk_live_votre_cle_ici" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeNumber": "EMP-0042",
    "eventType": "CLOCK_OUT",
    "timestamp": "2026-05-13T17:30:00Z",
    "terminalId": "terminal-hall-entree",
    "metadata": {
      "method": "FINGERPRINT"
    }
  }'

Pointage — QR code sur badge imprimé

curl -X POST "https://api.nerpsuite.com/api/hr/time/terminal/event" \
  -H "X-Terminal-Key: tk_live_votre_cle_ici" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeNumber": "EMP-0042",
    "eventType": "CLOCK_IN",
    "timestamp": "2026-05-13T08:47:00Z",
    "terminalId": "terminal-atelier",
    "metadata": {
      "method": "QR_CODE"
    }
  }'

---

Configuration par marque de terminal

La plupart des terminaux de pointage physiques supportent le mode "Push to URL" ou "HTTP POST". Voici les paramètres génériques à renseigner dans l'interface de configuration de votre terminal :

---

Retry et idempotence

Si votre terminal envoie plusieurs fois le même événement (réseau instable, retry automatique), NERP Suite détecte les doublons via la combinaison employeeNumber + eventType + date. Un doublon retourne un 200 avec "duplicate": true — aucune entrée supplémentaire n'est créée.