v002/collaborateurs/

L’API de gestion des collaborateurs permet d’ajouter ou de supprimer des membres collaborateurs sur un objet touristique.

Ces modifications ne peuvent être exécutées que par le membre propriétaire d’une offre.

Modes d’utilisation

La même API sert simultanément à l’ajout ou à la suppression de membres collaborateurs. La distinction est faite au travers des méthodes HTTP utilisées pour émettre la request vers l’API.

  • L’ajout de membres collaborateurs se fait par un appel utilisant la méthode PUT
  • La suppression de membres collaborateurs se fait par un appel utilisant la méthode DELETE

Exemples

PHP

Exemple 1 : Méthode d’ajouts de membres collaborateurs :

$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer". $token));
curl_setopt($ch, CURLOPT_URL, "http://lesiteapidae/api/v002/collaborateurs/");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT" );
curl_setopt($ch, CURLOPT_ENCODING, 'UTF-8');
curl_setopt($ch, CURLOPT_POSTFIELDS, $formParameters);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

Exemple 2 : Méthode de membres collaborateurs :

$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer". $token));
curl_setopt($ch, CURLOPT_URL, "http://lesiteapidae/api/v002/collaborateurs/");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE" );
curl_setopt($ch, CURLOPT_ENCODING, 'UTF-8');
curl_setopt($ch, CURLOPT_POSTFIELDS, $formParameters);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

Formulaire d’envoi des données

À l’image de l’api en écriture, un appel au web-service de gestion des membres collaborateurs s’articule autour d’un formulaire au format multipart/form-data.

Ce formulaire comporte un unique champ collaborateurs dont le contenu est encodé au format JSON, permettant de transmettre les identifiants des objets touristiques et les membres à manipuler.

Description du JSON

{
   "id": 5163353,
   "membresCollaborateurs" : [6,7]
}
  1. id : [Obligatoire] Identifiant de l’objet touristique à mettre à jour.
  2. membresCollaborateurs[] : [Obligatoire] Liste des identifiants des membres à ajouter ou retirer de la collaboration sur la fiche.

Règles d’utilisation

  1. Si un membre collaborateur est déjà présent, il est ignoré.
  2. Le membre propriétaire ne peut pas être retiré.
  3. La manipulation des membres collaborateurs est appliquée sans créer de brouillon de l’objet.

Exemples

Exemple 1 : Ajout des membres collaborateurs 6 et 7 sur l’offre 5163353 :

{
   "id": 5163353,
   "membresCollaborateurs" : [6,7]
}

Exemple 2 : Suppression du membre collaborateur 7 sur l’offre 5163353 :

{
   "id": 5163353,
   "membresCollaborateurs" : [7]
}

Retours de la méthode

La méthode renvoie un objet JSON comportant les champs suivants :

errorType

type : chaîne de caractères
description : Type d’erreur technique rencontrée lors du traitement.
valeurs possibles :

  • ECRITURE_FORBIDDEN : vous ne disposez pas de droits suffisants sur le projet.
  • ECRITURE_BAD_REQUEST : Le formulaire avec les données JSON n’a pas été fourni.
  • ECRITURE_INVALID_JSON_DATA : les données JSON à injecter n’ont pas le format attendu.
  • OBJET_TOURISTIQUE_NOT_FOUND : l’objet touristique n’a pas été trouvé.

id

type : entier
description : Identifiants de l’objet touristique mis à jour. Cet attribut est présent uniquement si le traitement s’est déroulé correctement.

status

type : chaîne de caractères
description : indique le résultat de l’appel.
valeurs possibles :

  • PUT_COLLABORATEURS_DONE  : Les membres collaborateurs ont été ajoutés correctement (même si un membre était déjà présent et qu’il a été ignoré dans la série). Si le champ status renvoie cette valeur, le traitement s’est déroulé correctement.
  • REMOVE_COLLABORATEURS : Au moins un membre collaborateur été retiré. Si le champ status renvoie cette valeur, le traitement s’est déroulé correctement.
  • NO_ACTION : Aucune action n’a été réalisée, suite à la présence de contrôles ayant échoué.

message

type : chaîne de caractères
description : Message présent uniquement dans le cas d’un traitement en anomalie et explicitant cette anomalie.

Exemples de retour

Exemple 1 : Retour valide suite à l’ajout d’un membre collaborateur

{
    "status": "PUT_COLLABORATEURS_DONE",
    "referenceId": 5163353,
    "membresCollaborateurs": [
        6,
        96,
        684,
        1080,
        1182,
        1185,
        1,
        171
    ]
}

Exemple 2 : Retour valide suite à la suppression d’un membre collaborateur

{
    "status": "REMOVE_COLLABORATEURS_DONE",
    "referenceId": 5163353,
    "membresCollaborateurs": [
        6,
        96,
        684,
        1080,
        1182,
        1185
    ]
}

Exemple 3 : Retour en erreur suite à une request émise sans le paramètre membresCollaborateurs (données au format JSON)

{
    "message": "Paramètre 'collaborateurs' : les données n'ont pas un format JSON valide : Unexpected character ('}' (code 125)): was expecting double-quote to start field name\n at [Source: (String)\"{\n   \"id\": 5163353,\n\n}\"; line: 4, column: 2]. Cause: Unexpected character ('}' (code 125)): was expecting double-quote to start field name\n at [Source: (String)\"{\n   \"id\": 5163353,\n\n}\"; line: 4, column: 2]",
    "errorType": "ECRITURE_INVALID_JSON_DATA"
}

Exemple 5 : Retour en erreur, car les membres collaborateurs étaient déjà présents ou déjà absents.

{
    "status": "NO_ACTION",
    "message": "Tous les collaborateurs fournis ont déjà été traités"
}