PlanningPME API - Documentazione dello sviluppatore

nterconnetti i tuoi dati di pianificazione con il resto del tuo sistema informativo.
PlanningPME consente l'accesso in lettura e scrittura al vostro database attraverso una API dedicata. La API PlanningPME segue l'attuale standard di sviluppo (implementazione REST e trasporto dati in formato JSON) per una semplice programmazione delle vostre sincronizzazioni e integrazioni.

Indice dei contenuti:

La API di PlanningPME si basa su RESTful principi, e il modello di trasferimento dei dati di default è JSON.
Questa documentazione è principalmente rivolta agli sviluppatori. Consigliamo al lettore di familiarizzare con la API JSON REST di programmazione prima di procedere ulteriormente.

URL dedicato

Ogni cliente PlanningPME dispone di un proprio indirizzo API dedicato.
Supponiamo che il vostro marchio sia "MyCompany", dovreste probabilmente usare la chiave del marchio "mycompany" (maiuscole ignorate) per costruire il vostro indirizzo API.
Questa chiave sarà indicata come "your_brand" nella parte restante della presente documentazione.

L’ indirizzo base della API di un marchio sarà sempre come segue:
https://api.planningpme.com/your_brand/
o
https://try.planningpme.com/your_brand/

Documentazione interattiva

Ogni marchio API presenta anche una documentazione interattiva, molto utile per scoprire i vostri metodi e modelli API di PlanningPME e costruire chiamate API.

Questa documentazione è disponibile al seguente indirizzo :
https://api.planningpme.com/your_brand/doc/index
o
https://try.planningpme.com/your_brand/doc/index

Documentazione interattiva

Non è possibile chiamare a questi due indirizzi senza presentare una chiave di richiesta.

Sicurezza

1/ Presentazione chiave di richiesta

È necessaria una chiave di applicazione (appkey) per accedere alla propria API, in modo da identificare l'applicazione chiamante.
Questa appkey è disponibile nel vostro account PlanningPME o su richiesta al nostro servizio di assistenza.
Oltre a garantire l'accesso alla API, l'appkey consente di concedere l'accesso a un partner o a un'applicazione di livello, fornendo loro la propria chiave per identificare le loro chiamate alla API.

La appkey dovrebbe essere sempre inserita nelle intestazioni di una chiamata API, utilizzando l'intestazione "X-APPKEY" dedicata.

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

Per accedere alla documentazione interattiva, utilizzate la appkey come parametro di interrogazione, come nell'esempio sottostante:

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

2/ Token utente e impersonificazione

La maggior parte delle chiamate API deve essere identificata tramite l'utente, in modo da utilizzare l'impersonificazione durante l'accesso ai dati e rispettare le autorizzazioni definite dall'utente e dal gruppo.

Viene concessa un'autorizzazione tramite invio del nome utente e della password alla API, ottenendo poi un token che verrà utilizzato per autenticare o impersonare qualsiasi successiva chiamata API.

Per ottenere un token identificativo di autorizzazione è sempre necessario inserire questi dati nell'url "/token"..

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

grant_type=password&username=your_username&password=your_password

In caso di autenticazione riuscita, l'organismo di risposta conterrà un elemento JSON come segue.

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

Il valore del parametro "access_token" deve poi essere utilizzato nelle successive richieste autorizzate alla API.
. E come indicato dalla proprietà "token_type", si tratta di un token al portatore.

Ogni successiva chiamata autorizzata dovrebbe poi presentare l'intestazione "Autorizzazione" con questo specifico valore "Portatore".

POST /your_brand/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

Uso della API

1/ Considerazioni dati comuni

a) Modelli

I modelli di dati PlanningPME possono essere facilmente recuperati utilizzando la documentazione interattiva della API.

b) Formato data

Il formato data usato dalla API e previsto in ogni richiesta JSON è formato ISO 8601. Ex:

2018-01-25T18:05:00Z

c) Elenchi ordini

I metodi GET spesso usano un"sortInfo" parametro per impostare l’ordine di selezione dell’elenco completo/impaginato restituito.

Questa informazione è composta dal nome di una proprietà seguito direttamente da un segno + o -.
Ad esempio, utilizzare "etichetta+" per ordinare in base alla proprietà "etichetta" ascendente.

È possibile anche combinare più ordini aggiungendoli.
Ad esempio, utilizzare "notValid-label+" per ordinare in ordine decrescente la proprietà "notValid" e poi in ordine ascendente la proprietà "label".

Attenzione: le etichette delle proprietà sono sensibili alle lettere maiuscole e minuscole.

d) Enumerazioni costanti

Un elenco completo dei conteggi in uso con la vostra versione API si ottiene chiamando il metodo "/api/config". Questo elenco può essere modificato soltanto successivamente.

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

Di seguito l'elenco dei conteggi per la versione 4.1.1.117 dell'API.

{
  ...
  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) Lingua di risposta

La lingua utilizzata nei testi di risposta, come i messaggi di errore, può essere specificata con l'intestazione "Accetta-Lingua".

Accetta-Lingua: it

Le lingue disponibili nella API di PlanningPME API e PlanningPME WebAccess sono: danese (da), olandese (nl), inglese (en), finlandese (fi), francese (fr), tedesco (de), italiano (it), norvegese (no), polacco (pl), russo (ru), spagnolo (es), svedese (sv).

2/ Esempi di chiamate API

Negli esempi di seguito riportati In la application key sarà indicata come "your_key" e il portatore del token come "your_token". Sostituirli con i vostri valori.

/api/task

→ Ottenere un elenco completo o impaginato di attività con il metodo GET "/api/task".

GET /your_brand/api/task?pageIndex=1&pageSize=20&sortInfo=label- HTTP/1.1
Host: api.planningpme.com
X-APPKEY: your_key
Authorization: Bearer your_token

Restituisce una matrice di attività contenente una seconda pagina di 20 attività ordinate con etichetta in ordine decrescente.

{
  "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"
      }
    }
  ]
}

→ Ottenere un’attività dettagliata con il metodo GET "/api/task/{id}".

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

Restituisce una rappresentazione dettagliata dell'oggetto dell'attività con l'id 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"
        }
      }
    ]
  ]
}