Tutorial

D'Outil Interne à Produit API : L'Histoire de PunchConnect

Comment nous avons transformé une intégration biométrique interne construite pour 24 000 employés en un produit API REST cloud — et ce que nous avons appris.

PunchConnect Team·Mar 28, 2026·5 min read

Introduction

PunchConnect n'était pas censé être un produit. Il est né de la frustration — et de 4 mois de production intensive.

Nous construisions AgriWise, une plateforme de gestion de la main-d'œuvre pour les entreprises agricoles au Maroc. 24 000+ employés sur des dizaines de sites. Chaque site avait des dispositifs biométriques ZKTeco. Et nous devions récupérer les données de pointage en temps réel dans notre application cloud.

Rien sur le marché ne fonctionnait. Alors nous l'avons construit nous-mêmes.

Le Problème à l'Origine de Tout

AgriWise avait un besoin simple : récupérer les données de pointage des dispositifs biométriques dans une application cloud, de manière fiable, en temps réel.

Ça semble simple. Ça ne l'est pas.

D'Un Client à une Plateforme

Après 6 mois en production avec AgriWise, nous entendions toujours la même question : « Comment connecter les dispositifs ZKTeco au cloud ? »

Des développeurs sur les forums, Stack Overflow, issues GitHub — tous confrontés au même mur. Nous n'avons pas construit une démo. Nous avons ouvert notre système de production. Le même moteur qui gère les 24 000+ employés d'AgriWise alimente chaque appel API PunchConnect.

Les Décisions d'Ingénierie Qui Comptent

1. Multi-Locataire avec Isolation par Dispositif

Chaque client est totalement isolé. Le client A ne peut jamais voir les données du client B.

python

@app.route("/v1/devices", methods=["GET"])
@require_api_key
def lister_dispositifs():
    tenant_id = request.auth.tenant_id
    dispositifs = db.query(
        "SELECT * FROM devices WHERE tenant_id = %s", [tenant_id]
    )
    return jsonify({"devices": dispositifs})

2. Design d'API : Leçons de Stripe

Nous avons étudié les API de Stripe, Twilio et GitHub de façon obsessionnelle :

- Format de réponse cohérent — chaque endpoint retourne la même structure
- Codes d'erreur clairs — identifiants spécifiques, pas juste des codes HTTP
- Clés d'idempotence — opérations retry-safe sur chaque endpoint mutatif

bash

curl -X GET https://api.punchconnect.com/v1/devices/inexistant \
  -H "Authorization: Bearer VOTRE_CLE_API"

# Réponse :
# {
#   "error": {
#     "code": "device_not_found",
#     "message": "Aucun dispositif trouvé avec l'ID 'inexistant'",
#     "status": 404,
#     "doc_url": "https://docs.punchconnect.com/errors/device_not_found"
#   }
# }

3. Système de Livraison Webhook

python

DELAIS_RETRY = [10, 60, 300, 1800, 7200]  # secondes

def livrer_webhook(url: str, payload: dict, secret: str):
    """Livrer un webhook avec signature et retries."""
    body = json.dumps(payload)
    signature = hmac.new(
        secret.encode(), body.encode(), hashlib.sha256
    ).hexdigest()
    
    for tentative, delai in enumerate(DELAIS_RETRY):
        try:
            resp = requests.post(url, data=body, headers={
                "Content-Type": "application/json",
                "X-PunchConnect-Signature": signature,
            }, timeout=10)
            if resp.status_code < 300:
                return True
        except requests.RequestException:
            pass
        time.sleep(delai)
    return False

4. La Documentation Comme Produit

Pour un outil interne, la documentation est un wiki que personne ne lit. Pour un produit API, la documentation EST le produit. Si les développeurs ne comprennent pas votre API en 5 minutes, ils partent.

Hébergement compatible OVH et Scaleway pour la souveraineté des données européennes, conforme aux recommandations RGPD/CNIL.

Ce Que Nous Avons Appris

| Métrique | Interne (AgriWise) | Produit (PunchConnect) |
|----------|-------------------|----------------------|
| Dispositifs | 80+ | En croissance |
| Employés | 24 000+ | Variable par client |
| Disponibilité | 99,7% | 99,7% (même moteur) |
| Latence webhook | 340ms moy. | 340ms moy. |
| Enregistrements perdus | Zéro | Zéro |
| Temps de première intégration | 4 mois | Moins de 5 minutes |

La dernière ligne est le produit. Nous avons passé 4 mois à intégrer. Nos clients passent 5 minutes.

FAQ

PunchConnect est-il toujours utilisé en interne par AgriWise ?

Oui. AgriWise fonctionne sur exactement le même moteur PunchConnect. Les tests en production ne s'arrêtent jamais.

Combien de temps faut-il pour intégrer PunchConnect ?

La plupart des développeurs reçoivent leur premier webhook en 5 minutes : enregistrer un dispositif, le configurer dans le tableau de bord, et commencer à recevoir les données.

Quels dispositifs PunchConnect supporte-t-il ?

Actuellement les dispositifs biométriques ZKTeco — la marque la plus déployée mondialement. SpeedFace, ProFace, UA860, K40, MB460 et la plupart des modèles avec connectivité réseau.

En quoi PunchConnect diffère des bibliothèques open-source ?

Les bibliothèques comme pyzk se connectent aux dispositifs en LAN — un à la fois, sur le même réseau. PunchConnect est un service cloud : les dispositifs se connectent en sortie, fonctionnent sur tout réseau, gèrent le buffering hors ligne et livrent les données via webhooks.

Puis-je essayer PunchConnect avant de m'engager ?

Oui. Essai gratuit de 7 jours avec accès complet à l'API, sans carte bancaire.

---

Chaque produit API commence comme le problème interne de quelqu'un. Nous avons passé 4 mois à résoudre la connectivité des dispositifs biométriques pour AgriWise. Maintenant cette solution est disponible pour tous les développeurs.

Essai gratuit de 7 jours — de zéro au premier webhook en moins de 5 minutes.