Aller au contenu principal

Gestion des Items

Ce document détaille les différentes méthodes pour ajouter des items (éléments de données) à un dossier dans l'application Certificall.

Création d'un Item​

Endpoint : POST /items/create​

Description​

Ce point d'API permet aux utilisateurs de créer des items dans un dossier. Les types d'items autorisés sont : texte, sélection, date, email, nombre et heure. Les types média (photo, vidéo, signature) ne sont pas autorisés via cet endpoint.

Requête​

  • URL : /items/create

  • Méthode HTTP : POST

  • Headers requis :

    Authorization: Bearer <Votre_Token_JWT>
    Content-Type: application/json

Corps de la Requête (Payload)​

  • caseId (Number, requis): Identifiant du dossier auquel ajouter l'item.
  • stepId (Number, requis): Identifiant de l'étape (obtenu via l'endpoint /frames).
  • data (String, requis): Données de l'item (le format dépend du type d'étape).
  • pos (Number, optionnel): Position de l'item dans un multi-step (par défaut : 0).

Exemple de corps de requête pour un champ texte :

{
  "caseId": 12345,
  "stepId": 101,
  "data": "Commentaire: Installation conforme",
  "pos": 0
}

Exemple de corps de requête pour une date :

{
  "caseId": 12345,
  "stepId": 102,
  "data": "2024-01-15",
  "pos": 0
}

Exemple de corps de requête pour un nombre :

{
  "caseId": 12345,
  "stepId": 103,
  "data": "42.5",
  "pos": 0
}

Types d'Items Autorisés​

Les types d'items suivants sont autorisés :

  • TEXT_FIELD : Champ texte libre
  • SELECT : Liste de sélection
  • DATE : Date
  • EMAIL : Adresse email
  • NUMBER : Nombre
  • TIME : Heure

Les types suivants sont interdits et doivent utiliser l'endpoint /items/:caseId :

  • PHOTOGRAPHY : Photo
  • VIDEO : Vidéo
  • SIGNATURE : Signature

Réponses​

Réponse en cas de succès :

  • Code Statut: 200 OK
  • Description: L'item a été créé avec succès.

Exemple de réponse réussie :

{
  "id": 98765,
  "cfRef": "ITM-98765"
}

Réponse en cas d'échec :

  • Code Statut: 400 Bad Request

  • Description: La requête est invalide (Step ID manquant ou limite maximum atteinte).

  • Code Statut: 403 Forbidden

  • Description: Type média non autorisé (photo/video/signature).

  • Code Statut: 404 Not Found

  • Description: Le dossier ou l'étape spécifiée n'existe pas.

Cas d'Utilisation​

Utilisez cet endpoint pour ajouter des données non-média à un dossier :

  • Commentaires textuels
  • Sélections dans des listes déroulantes
  • Dates d'intervention
  • Coordonnées email
  • Mesures numériques
  • Heures d'intervention

Ajout d'un Item avec Fichier​

Endpoint : POST /items/:caseId​

Description​

Ce point d'API permet aux utilisateurs d'ajouter un item à un dossier avec upload de fichier. Cet endpoint est particulièrement adapté pour les photos, vidéos, signatures et autres types d'items nécessitant un fichier.

Requête​

  • URL : /items/:caseId

  • Méthode HTTP : POST

  • Paramètres de chemin :

    • caseId : number - L'identifiant unique du dossier.

  • Headers requis :

    Authorization: Bearer <Votre_Token_JWT>
    Content-Type: multipart/form-data

Corps de la Requête (Multipart Form-Data)​

La requête doit être envoyée en multipart/form-data et contenir les champs suivants :

Champ file (optionnel) :

  • Type : Fichier binaire (image, vidéo, etc.)
  • Description : Le fichier à uploader (obligatoire pour les items de type photo, vidéo, signature)

Champ createItemDto (requis) :

  • Type : JSON stringifié
  • Description : Objet JSON contenant les informations de l'item

Structure du createItemDto :

  • companyId (Number, requis): Identifiant de l'entreprise.
  • stepId (Number, requis): Identifiant de l'étape (obtenu via /frames).
  • data (String, requis): Données de l'item ou nom du fichier pour les photos.
  • caseId (Number, optionnel): Identifiant du dossier (peut être omis car déjà dans l'URL).
  • userDeviceManufacturer (String, requis): Fabricant de l'appareil.
  • userDeviceModel (String, requis): Modèle de l'appareil.
  • userDeviceName (String, requis): Nom de l'appareil.
  • userDevicePlatform (String, requis): Plateforme de l'appareil (iOS, Android, etc.).
  • userDeviceOs (String, requis): Système d'exploitation.
  • userDeviceOsVersion (String, requis): Version du système d'exploitation.
  • userDeviceCarrierIpAddress (String, optionnel): Adresse IP du réseau mobile.
  • userDeviceWifiIpAddress (String, optionnel): Adresse IP du réseau WiFi.
  • geolocLatitude (String, optionnel): Latitude (obligatoire pour les photos).
  • geolocLongitude (String, optionnel): Longitude (obligatoire pour les photos).
  • geolocAccuracy (String, optionnel): Précision de la géolocalisation.

Exemple de Requête avec cURL​

curl -X POST "https://admin.certificall.app/certificall/api/items/12345" \
  -H "Authorization: Bearer votre_token_jwt" \
  -F "file=@/chemin/vers/photo.jpg" \
  -F 'createItemDto={
    "companyId": 1,
    "stepId": 101,
    "data": "photo_facade.jpg",
    "userDeviceManufacturer": "Apple",
    "userDeviceModel": "iPhone 13",
    "userDeviceName": "iPhone de Jean",
    "userDevicePlatform": "iOS",
    "userDeviceOs": "iOS",
    "userDeviceOsVersion": "16.0",
    "geolocLatitude": "48.8566",
    "geolocLongitude": "2.3522",
    "geolocAccuracy": "5.0"
  }'

Réponses​

Réponse en cas de succès :

  • Code Statut: 200 OK
  • Description: L'item a été créé et le fichier uploadé avec succès.

Exemple de réponse réussie :

{
  "id": 98765,
  "cfRef": "ITM-98765",
  "fileUrl": "https://certificall.app/files/photo_facade.jpg"
}

Réponse en cas d'échec :

  • Code Statut: 400 Bad Request

  • Description: La requête est invalide (paramètres manquants ou incorrects).

  • Code Statut: 403 Forbidden

  • Description: Vous n'avez pas les permissions nécessaires ou le dossier n'appartient pas à votre entreprise.

  • Code Statut: 413 Payload Too Large

  • Description: Le fichier uploadé est trop volumineux.

Permissions Requises​

  • Le dossier doit appartenir à votre entreprise.
  • Votre entreprise doit être autorisée à utiliser cette API, contactez Certificall pour savoir si c'est le cas

Types d'Items Supportés​

Cet endpoint supporte tous les types d'items, notamment :

  • PHOTOGRAPHY : Photos avec géolocalisation
  • VIDEO : Vidéos
  • SIGNATURE : Signatures
  • TEXT_FIELD, SELECT, DATE, EMAIL, NUMBER, TIME : Items non-média

Cas d'Utilisation​

Utilisez cet endpoint pour :

  • Ajouter des photos avec métadonnées de localisation
  • Uploader des vidéos d'inspection
  • Capturer des signatures numériques
  • Ajouter tout type d'item avec traçabilité complète de l'appareil

Sécurité et Bonnes Pratiques​

  • Récupérez d'abord la liste des étapes disponibles via l'endpoint /frames pour obtenir les stepId valides.
  • Assurez-vous que le format de data correspond au type d'étape attendu.
  • Pour les photos, la géolocalisation (geolocLatitude, geolocLongitude) est obligatoire.
  • Incluez toujours les informations complètes de l'appareil pour assurer la traçabilité.
  • Limitez la taille des fichiers uploadés pour éviter les erreurs de timeout.
  • Vérifiez que le dossier n'est pas encore fermé avant d'ajouter des items.
  • Les interactions avec l'API Certificall doivent toujours être effectuées via une connexion sécurisée (HTTPS).

En suivant ces instructions, vous pourrez ajouter en toute sécurité des items à vos dossiers via l'API Certificall.