PlanningPME API - Documentation développeur

PlanningPME permet l'accès en lecture et écriture aux données de votre base client par le biais d'une API dédiée.

Ce document vous renseignera sur :

L'API PlanningPME est basée sur les principes d'API RESTful et le format de transfert de données utilisé est JSON.
Cette documentation est principalement destinée aux développeurs. Nous recommandons au lecteur de se familiariser avec la programmation d'API REST JSON avant d'aller plus loin.

URL dédiée

Chaque client PlanningPME dispose de sa propre adresse API dédiée.
Supposons que votre marque soit "MyCompany", vous devrez très probablement utiliser la clé "mycompany" (non-sensible à la casse) pour construire votre adresse d'API.
Cette clé sera notée "votre_marque" dans le reste de cette documentation.

L'adresse API de base d'une marque sera toujours de la forme :
https://api.planningpme.com/votre_marque/

Documentation interactive

Chaque API est livrée avec une documentation interactive, très utile pour découvrir les méthodes et modèles utilisés dans l'API PlanningPME, ou générer des requêtes.
Cette documentation est disponible à l'adresse suivante:
https://api.planningpme.com/votre_marque/doc/index

Ces deux adresses ne peuvent pas être appelées sans présentation d'une clé d'API.

Sécurité

1/ Présentation de la clé d'API

L'accès à votre API nécessite une clé identifiant l'application qui appelle l'API : une appkey.
Cette appkey est disponible dans votre compte PlanningPME ou à la demande au support.
Au-delà de la sécurité qu'elle apporte, l'appkey vous permet d'identifier un accès par un partenaire ou une application tierce disposant de sa propre clé.

L'appkey doit toujours être envoyée en en-tête d'une requête d'API, au moyen de l'en-tête dédié "X-APPKEY".

GET /votre_marque/api/config HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac

Pour accéder à votre documentation interactive, utilisez votre appkey en paramètre d'adresse, comme dans l'exemple ci-dessous :

https://api.planningpme.com/votre_marque/doc/index?appkey=e991573da5ffd4sab9b1e26bc6b64aac

2/ Authentification et chargement de profil

La plupart des requêtes d'API doivent être authentifiées par un utilisateur d'application, afin de charger son profil lors de l'accès aux données et de respecter les autorisations d'utilisateur et de groupe définies.

Une autorisation est accordée en soumettant le nom d'utilisateur et le mot de passe à l'API , puis en obtenant un jeton qui sera utilisé pour authentifier ou emprunter l'identité d'un appel d'API ultérieur.

Obtenir un jeton d'autorisation est toujours fait en postant ces données à l'url "/token".

POST /votre_marque/token HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac

grant_type=password&username=votre_utilisateur&password=votre_motdepasse

Dans le cas d'une authentification réussie, le corps de la réponse contiendra un élément JSON comme suit.

{
    "access_token": "KTuZYDLG2qjUMqMVXDuiP9giFbqDXstESvpUWzBFLpkfdlMiB3PD5s2K7En-3o39u56hpr_DlyjEc_oUzBbR0PoEQfOb_O7m5BrLz9vwDzV_YjtRRrQ_7QxYnxO9uZs38SJ7UxTjDZgx_JKRUoZ3Wk6RNnXRpSkcmOrINvJLDMYXptYFiTjn9Op-vkPdtOKFp9M1cNjrH1ho2uaRBpUUMH_vJ-8W8mTH9wgFrJlecGIpntb7jet2GYpGs3Is0gcH",
    "token_type": "bearer",
    "expires_in": 86399,
    "username": "votre_utilisateur"
}

La valeur de la propriété "access_token" devra être utilisée dans toute requête d'API ultérieure nécessitant une autorisation, jusqu'à expiration du jeton. Aussi comme indiqué par la propriété "token_type", cette valeur est un jeton de type "bearer".

Les requêtes nécessitant une autorisation doivent donc présenter l'en-tête "Authorization" avec la valeur "Bearer" indiquée.

POST /votre_marque/api/customer HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
Authorization: Bearer KTuZYDLG2qjUMqMVXDuiP9giFbqDXstESvpUWzBFLpkfdlMiB3PD5s2K7En-3o39u56hpr_DlyjEc_oUzBbR0PoEQfOb_O7m5BrLz9vwDzV_YjtRRrQ_7QxYnxO9uZs38SJ7UxTjDZgx_JKRUoZ3Wk6RNnXRpSkcmOrINvJLDMYXptYFiTjn9Op-vkPdtOKFp9M1cNjrH1ho2uaRBpUUMH_vJ-8W8mTH9wgFrJlecGIpntb7jet2GYpGs3Is0gcH

Utilisation de l'API

1/ Généralités

a) Modèles de données

Les modèles de données PlanningPME sont détaillés dans la documentation interactive de votre API.

b) Format de date

Le format de date utilisé par l'API et attendu dans chaque requête JSON est le format ISO 8601. Ex:

2018-01-25T18:05:00Z

c) Ordre des listes

Les méthodes GET utilisent souvent un paramètre "sortInfo" pour définir l'ordre de tri de la liste complète ou paginée qui est renvoyée.

Cette information est composée du nom d'une propriété directement suivie d'un signe + ou -.
Par exemple, utilisez "label+" pour demander un tri par ordre alphabétique ascendant sur la propriété "label".

Il est également possible de combiner plusieurs commandes en les ajoutant.
Utilisez par exemple "notValid-label+" pour demander un tri par propriété "notValid" descendante puis par ordre alphabétique ascendant sur "label".

Prenez garde au fait que les noms de propriétés sont sensibles à la casse.

d) Constantes d'énumérations

Bien qu'elle ne soit pas amenée à changer, sauf ajout, la liste complète des énumérations utilisées dans votre version d'API est obtenue en appelant la méthode "/api/config".

GET /votre_marque/api/config HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac

Ci-dessous la liste des enums en version 4.1.1.117.

{
  ...
  enums: {
    "Access": {
      "All": 0,
      "Read": 82,
      "Write": 87
    },
    "BillingType": {
      "Package": 0,
      "Unit": 1
    },
    "ConstraintAction": {
      "NoTaskBeforeNbHours": 0,
      "NoTaskBeforeNbDays": 1,
      "NoTaskSamePeriod": 2,
      "NbMaxHours": 3,
      "NbMax": 4,
      "DurationMaxHours": 5,
      "DurationMaxDays": 6
    },
    "ConstraintFor": {
      "All": 0,
      "Resources": 1,
      "Departments": 2
    },
    "ConstraintIf": {
      "Nothing": 0,
      "Nb": 1,
      "NbHours": 2,
      "Begin": 3,
      "End": 4
    },
    "ConstraintOp": {
      "Nothing": 0,
      "Equal": 1,
      "Inf": 2,
      "InfEqual": 3,
      "Sup": 4,
      "SupEqual": 5,
      "Before": 6,
      "After": 7
    },
    "ConstraintType": {
      "Task": 0,
      "Unavailability": 1
    },
    "ConstraintWhat": {
      "LabelAll": 0,
      "LabelExact": 1,
      "LabelBegin": 2
    },
    "ConstraintWhen": {
      "Nothing": 0,
      "Day": 1,
      "Week": 2,
      "Month": 3,
      "Year": 4
    },
    "CustomerType": {
      "Individual": 1026,
      "Company": 1027
    },
    "DataFieldType": {
      "Date": 1,
      "Time": 2,
      "Text": 3,
      "Numeric": 4,
      "Double": 5,
      "Combo": 6,
      "Link": 7,
      "Check": 8,
      "Memo": 9,
      "Separator": 10,
      "File": 11,
      "Position": 12,
      "SignatureMobile": 13,
      "Hyperlink": 16,
      "Startdate": 17,
      "Enddate": 18,
      "Duration": 19,
      "Signature": 20
    },
    "DescriptionFieldType": {
      "Index1": 49,
      "Index2": 50,
      "EmailBody": 69,
      "Label": 76,
      "Mobile": 77,
      "Calendar": 79,
      "EmailSubject": 83,
      "Tooltip": 84
    },
    "Destination": {
      "Task0": 48,
      "Task2": 50,
      "Task3": 51,
      "Task4": 52,
      "Task5": 53,
      "Equipment0": 65,
      "Customer1": 67,
      "MaterialResource1": 77,
      "MaterialResource2": 78,
      "MaterialResource3": 79,
      "Project0": 80,
      "HumanResource1": 82,
      "HumanResource2": 83,
      "Task1": 84,
      "HumanResource3": 86,
      "Customer0": 97,
      "HumanResource0": 98,
      "Customer2": 99,
      "MaterialResource0": 100
    },
    "DestinationType": {
      "Task": 0,
      "Customer": 1,
      "Equipment": 2,
      "Resource": 3,
      "Project": 4
    },
    "HistoryOp": {
      "Insert": 65,
      "Delete": 68,
      "Email": 69,
      "Invitation": 73,
      "Update": 85
    },
    "HistoryType": {
      "Customer": 67,
      "Unavailability": 73,
      "Project": 80,
      "Resource": 82,
      "Task": 84
    },
    "JsonWritingType": {
      "Normal": 1,
      "KeyLabel": 2,
      "String": 3,
      "Data": 4
    },
    "LicenseStatus": {
      "Other": 0,
      "Evaluation": 1,
      "Ok": 2,
      "NoExpirationDate": -8,
      "WrongDatabase": -7,
      "WrongMachine": -6,
      "ResourceCount": -5,
      "LicenseCount": -4,
      "Expired": -3,
      "Empty": -2,
      "Corrupted": -1
    },
    "NotificationType": {
      "None": 0,
      "TaskInsert": 1,
      "TaskUpdate": 2,
      "UnavailabilityInsert": 4,
      "UnavailabilityUpdate": 8
    },
    "OneOrMoreCustomers": {
      "OneCustomer": 1422,
      "MoreCustomer": 1423
    },
    "OneOrMoreResources": {
      "OneResource": 1076,
      "MoreResource": 1077
    },
    "RecurrenceDaily": {
      "AllThe": 1255,
      "AllWorkingDays": 1256
    },
    "RecurrenceMonthly": {
      "Date": 1258,
      "Day": 1259
    },
    "RecurrenceMonthlyDayWhich": {
      "First": 0,
      "Second": 1,
      "Third": 2,
      "Fourth": 3,
      "Last": 4
    },
    "RecurrenceRange": {
      "NoEndDate": 1250,
      "EndThe": 1252
    },
    "RecurrenceType": {
      "Daily": 1246,
      "Weekly": 1247,
      "Monthly": 1248,
      "Yearly": 1249
    },
    "ResourceFilter": {
      "All": 40960,
      "Human": 45056,
      "Material": 49152,
      "ToPlan": 53248
    },
    "ResourceType": {
      "Human": 1035,
      "Material": 1036,
      "ToPlan": 1537
    },
    "TaskType": {
      "Default": 1467,
      "Duration": 1468,
      "Time": 1469
    },
    "Title": {
      "Miss": 0,
      "Mr": 1,
      "Ms": 2
    },
    "TimeLapseUnit": {
      "Day": 0,
      "Week": 1,
      "Month": 2,
      "Year": 3
    },
    "TypeHatch": {
      "BDIAGONAL": 0,
      "CROSS": 1,
      "DIAGCROSS": 2,
      "FDIAGONAL": 3,
      "HORIZONTAL": 4,
      "VERTICAL": 5
    },
    "WorkCapacity": {
      "Hours": 1590,
      "Slots": 1591
    }
  }
  ...

e) Langues des réponses

La langue voulue dans les textes de réponse tels que les messages d'erreur peut être spécifiée dans l'en-tête "Accept-Language".

Accept-Language: fr

Les langues disponibles dans PlanningPME API et PlanningPME WebAccess sont : allemand (de), anglais (en), danois (da), espagnol (es), finnois (fi), français (fr), italien (it), néerlandais (nl), norvégien (no), polonais (pl), russe (ru), suédois (sv).

2/ Exemples de requêtes d'API

Dans les exemples ci-dessous, la clé d'application utilisée est notée "votre_clé", et le jeton d'authentification "votre_jeton". Veuillez les remplacer par vos propres valeurs.

/api/task

→ Récupérer une liste (complète ou paginée) des tâches avec la méthode GET "/api/task".

GET /votre_marque/api/task?pageIndex=1&pageSize=20&sortInfo=label- HTTP/1.1
Host: api.planningpme.com
X-APPKEY: votre_clé
Authorization: Bearer votre_jeton

Retourne la seconde page de vingt tâches dans un tableau trié par ordre croissant sur le libellé.

{
  "totalItems": 97,
  "items": [
    {
      "key": 756,
      "label": "Cours d'anglais pour enfant",
      "type": 1467,
      "style": {
        "backgroundColor": "#65A18D",
        "color": "#000000"
      }
    },
	...
    {
      "key": 131,
      "label": "Coaching",
      "type": 1467,
      "style": {
        "backgroundColor": "#214DE9",
        "color": "#000000"
      }
    }
  ]
}

→ Récupérer le détail d'une tâche avec la méthode GET "/api/task/{id}".

GET /votre_marque/api/task/756 HTTP/1.1
Host: api.planningpme.com
X-APPKEY: votre_clé
Authorization: Bearer votre_jeton

Retourne le détail de la tâche d'identifiant 756.

{
  "key": 756,
  "label": "Cours d'anglais pour enfant",
  "type": 1467,
  "style": {
    "backgroundColor": "#65A18D",
    "color": "#000000"
  },
  "skills": [
    [
      {
        "key": 12,
        "name": "Enfant",
        "label": "Pédagogie > Enfant",
        "level": 1,
        "domain": {
          "key": 4,
          "label": "Pédagogie"
        }
      },
      {
        "key": 83,
        "name": "Anglais",
        "label": "Langue > Anglais",
        "level": 1,
        "domain": {
          "key": 4,
          "label": "Langue"
        }
      }
    ]
  ]
}

/api/do

Bientôt disponible...

/api/resource

Bientôt disponible...

/api/project

Bientôt disponible...

/api/file

Bientôt disponible...

A voir également :