PlanningPME API - Documentazione dello sviluppatore
Interconnettate i vostri dati di pianificazione con il resto del vostro 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:
- Come individuare l'indirizzo della API di PlanningPME ?
- Dove trovare la documentazione interattiva?
- Come vengono implementati i dati di sicurezza nella API di PlanningPME
- Quali sono le considerazioni sui dati comuni nella API di PlanningPME ?
- Come fare le prime richieste alla API di PlanningPME ?
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
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"
}
}
]
]
}