API Hasfy

L’API REST de Hasfy vous permet d’interagir avec votre organisation de manière programmatique : automatiser des tâches, intégrer Hasfy avec vos outils existants ou construire des workflows personnalisés.

Présentation

L’API Hasfy est une API REST qui répond en JSON, accessible exclusivement en HTTPS.

• Format des données : JSON
• Protocole : HTTPS exclusivement
• Base URL : https://app.hasfy.fr/api/v1
• Versioning : le préfixe /api/v1 indique la version de l’API

Qui peut utiliser l’API ?

L’API est incluse dans l’abonnement Hasfy Pro, sans option supplémentaire, pour tout siège administrateur ou technicien.

Authentification

Clés API

L’accès à l’API se fait via des clés API. Une clé est toujours liée à un utilisateur : elle hérite de ses permissions et est en plus restreinte par les scopes qui lui sont attribués. Une clé ne peut donc jamais faire plus que ce que peut faire l’utilisateur qui l’a créée.

Créer une clé API

1. Accédez à Paramètres > API > Clés API
2. Cliquez sur « Créer une clé API »
3. Donnez un nom descriptif à la clé (ex. « Script sync inventaire », « Intégration Zapier »)
4. Sélectionnez un ou plusieurs scopes (voir tableau ci-dessous)
5. Choisissez une expiration : Jamais, 30 jours, 90 jours, 6 mois ou 1 an
6. Cliquez sur « Créer »
7. La clé est affichée une seule fois : copiez-la et conservez-la en lieu sûr

Important : la clé API est affichée uniquement lors de la création. Si vous la perdez, vous devrez en créer une nouvelle.

Scopes disponibles

D’autres scopes au format ressource:action peuvent être proposés selon les modules activés sur votre organisation.

Utiliser la clé API

Incluez la clé API dans l’en-tête Authorization de vos requêtes :

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://app.hasfy.fr/api/v1/whoami"

Révoquer une clé API

1. Accédez à Paramètres > API > Clés API
2. Cliquez sur « Révoquer » à côté de la clé concernée
3. La clé est immédiatement invalidée

Endpoints

L’API expose actuellement 7 endpoints. Tous les chemins ci-dessous sont relatifs à https://app.hasfy.fr/api/v1.

GET /equipments

Liste l’équipement de l’organisation, paginé.

Paramètres de requête

Permission : equipment:read. Sans la permission de voir tout l’équipement de l’organisation, seul l’équipement assigné au propriétaire de la clé est retourné.

Réponse

{
  "data": [...],
  "pagination": { "total": 142, "limit": 50, "offset": 0 }
}

POST /equipments/bulk-create

Crée jusqu’à 100 équipements en une fois et génère leurs jetons d’installation.

Corps de la requête

{
  "items": [
    {
      "name": "PC-COMPTA-01",
      "type": "workstation",
      "platform": "windows",
      "location": "Bureau 1er étage",
      "unitId": "...",
      "managedBy": "...",
      "assignToUserId": "..."
    }
  ],
  "tokenKind": "bulk"
}

Seuls name et type sont obligatoires pour chaque élément de items. tokenKind vaut bulk ou invitation (optionnel).

Permission : equipment:write (action « Gérer les équipements »).

Réponse

{
  "requested": 1,
  "created": 1,
  "failed": 0,
  "items": [
    { "name": "PC-COMPTA-01", "id": "...", "installUrl": "https://..." }
  ]
}

GET /tickets

Liste les tickets, paginé.

Paramètres de requête

Permission : tickets:read. Sans la permission de voir tous les tickets de l’organisation, seuls les tickets créés par le propriétaire de la clé sont retournés.

Réponse

{
  "data": [...],
  "pagination": { "total": 38, "limit": 50, "offset": 0 }
}

POST /tickets

Crée un ticket pour le compte du propriétaire de la clé.

Corps de la requête

Permission : tickets:write

Réponse 201

{
  "id": "...",
  "title": "Imprimante hors service",
  "status": "open",
  "priority": "high",
  "equipment_id": "...",
  "created_by": "...",
  "created_at": "2026-06-11T10:00:00Z"
}

GET /users

Liste les membres de l’organisation, paginé.

Paramètres de requête : limit (1-200, défaut 50), offset (défaut 0)

Permission : users:read. Le champ email n’est inclus dans profile que si le propriétaire de la clé dispose de la permission de gestion des utilisateurs.

Réponse

{
  "data": [
    { "userId": "...", "role": "technician", "profile": { ... } }
  ],
  "pagination": { "total": 12, "limit": 50, "offset": 0 }
}

GET /whoami

Retourne l’identité associée à la clé : organisation, utilisateur et rôle effectif, ainsi que les métadonnées de la clé (nom, scopes, expiration).

Aucun scope spécifique n’est requis : une clé valide suffit. Pratique pour déboguer une intégration.

Réponse

{
  "organization": { "id": "...", "name": "..." },
  "user": { "id": "...", "role": "admin" },
  "apiKey": {
    "name": "Script sync inventaire",
    "scopes": ["equipment:read", "tickets:write"],
    "expiresAt": "2026-12-01T00:00:00Z"
  }
}

GET /health

Vérifie que la clé est valide et que les quotas associés ne sont pas dépassés.

Réponse

{ "status": "ok" }

Pagination & filtrage

Pagination

Les endpoints qui renvoient des listes (/equipments, /tickets, /users) sont paginés via deux paramètres de requête :

La réponse inclut les métadonnées de pagination :

{
  "data": [...],
  "pagination": { "total": 142, "limit": 50, "offset": 0 }
}

Filtrage

GET /api/v1/equipments?status=active&limit=20
GET /api/v1/tickets?status=open&priority=high

Aucun paramètre de tri (sort) n’est disponible actuellement.

Limites de débit (rate limiting)

Deux mécanismes distincts s’appliquent à chaque requête.

1. Limite par minute (anti-abus)

En-têtes de réponse :

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

En cas de dépassement, l’API renvoie 429 avec un en-tête Retry-After (en secondes) :

{ "error": "Too many requests", "retryAfter": 12 }

ou, si c’est la limite propre à la clé API qui est atteinte :

{ "error": "API key rate limit exceeded", "retryAfter": 12 }

2. Quota journalier par plan

Chaque organisation dispose d’un quota de requêtes /api/v1 par jour (fenêtre glissante de 24h), dépendant de son plan. Ce quota peut être illimité selon le plan souscrit.

En-têtes de réponse :

• X-Quota-Limit
• X-Quota-Used
• X-Quota-Remaining

En cas de dépassement, l’API renvoie 429 avec Retry-After: 3600 :

{ "error": "API quota exceeded", "limit": 5000, "used": 5000, "window": "24h" }

Gestion des erreurs

L’API utilise des codes HTTP standards. Les erreurs sont renvoyées dans un format simple et plat :

{ "error": "message décrivant l'erreur" }

Exemple d’erreur de validation (400) :

{
  "error": "Validation failed",
  "details": [
    { "path": ["title"], "message": "String must contain at least 5 character(s)" }
  ]
}

Exemples d’utilisation

Lister les équipements actifs

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://app.hasfy.fr/api/v1/equipments?status=active&limit=20"

Créer un ticket

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Imprimante hors service",
       "description": "Cette imprimante du 2e étage ne répond plus depuis ce matin.",
       "priority": "high",
       "equipmentId": "5b1f7e2a-6e3a-4b8b-9a90-2f6a6f0c7e10"
     }' \
     "https://app.hasfy.fr/api/v1/tickets"

Créer plusieurs équipements en une fois

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "items": [
         { "name": "PC-COMPTA-01", "type": "workstation", "location": "1er étage" },
         { "name": "PC-COMPTA-02", "type": "workstation", "location": "1er étage" }
       ]
     }' \
     "https://app.hasfy.fr/api/v1/equipments/bulk-create"

Vérifier l’identité de la clé

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://app.hasfy.fr/api/v1/whoami"

Bonnes pratiques