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.

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/

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.

Nota: se l'autenticazione dell'account è abilitata sull'API, l'accesso alla documentazione interattiva è a portata di clic all'interno dell'applicazione dell'account PlanningPME.

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 nell'account PlanningPME (se l'autenticazione dell'account è abilitata nell'API) o su richiesta per l'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 l'appkey come parametro di indirizzo, come nell'esempio seguente.

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

2/ Token utente e impersonificazione

La maggior parte delle richieste API deve inoltre presentare un token di autorizzazione, al fine di determinare il profilo dell'utente che accede ai dati e rispettare le autorizzazioni utente e di gruppo definite nell'applicazione.

Questo token viene ottenuto in anticipo durante l'autenticazione di un utente all'indirizzo /token e rimane valido per 8 ore.

I dati inviati a questo indirizzo variano a seconda del metodo di autenticazione scelto per l'applicazione.

a) Autenticazione classica

Se abilitata, l'autenticazione classica viene eseguita pubblicando il nome utente e la password.

POST /your_brand/token HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=your_username&password=your_password

b) Autenticazione dell'account

Se abilitata, l'autenticazione dell'account viene eseguita inviando un token dell'account di servizio, ottenuto in precedenza nell'applicazione dell'account PlanningPME.

Per ogni utente elencato qui, è possibile copiare il token dell'account di servizio negli appunti.

A questo punto, ottenete un token di autorizzazione dall'API pubblicando il token dell'account copiato (asserzione).

POST /your_brand/token HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=account_token

c) Utilizzo del token di autorizzazione

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

{
    "access_token": "KTuZYDLG2qjUMqMVXDuiP9giFbqDXstESvpUWzBFLpkfdlMiB3PD5s2K7En-3o39u56hpr_DlyjEc_...3Is0gcH",
    "token_type": "bearer",
    "expires_in": 86399,
    "username": "your_username"
}

La proprietà "access_token" contiene il token di autorizzazione dell'API.

Inoltre, come indicato dalla proprietà "token_type", questo token è di tipo "bearer". Pertanto, le richieste che richiedono l'autorizzazione devono avere l'intestazione "Authorization" con il valore "Bearer", come nell'esempio seguente.

POST /your_brand/api/customer HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
Authorization: Bearer KTuZYDLG2qjUMqMVXDuiP9giFbqDXstESvpUWzBFLpkfdlMiB3PD5s2K7En-3o39u56hpr_DlyjEc_...3Is0gcH

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 è riportato l'elenco delle enumerazioni nella versione 4.7.0.26

{
...
"enums": {
  "Access": {
    "All": "All",
    "Read": "Read",
    "Write": "Write"
  },
  "BillingType": {
    "Package": "Package",
    "Unit": "Unit"
  },
  "ColorDepending": {
    "Label": "Label",
    "Category": "Category",
    "Customer": "Customer",
    "Time": "Time",
    "Project": "Project"
  },
  "ConfigType": {
    "ExportTemplates": "ExportTemplates",
    "TimeRestrictedView": "TimeRestrictedView",
    "Filterings": "Filterings",
    "Language": "Language",
    "DateTimeFormat": "DateTimeFormat",
    "GCSync": "GCSync",
    "EffectTemplates": "EffectTemplates",
    "SyncResource": "SyncResource",
    "PrintTemplates": "PrintTemplates"
  },
  "ConstraintAction": {
    "NoTaskBeforeNbHours": "NoTaskBeforeNbHours",
    "NoTaskBeforeNbDays": "NoTaskBeforeNbDays",
    "NoTaskSamePeriod": "NoTaskSamePeriod",
    "NbMaxHours": "NbMaxHours",
    "NbMax": "NbMax",
    "DurationMaxHours": "DurationMaxHours",
    "DurationMaxDays": "DurationMaxDays"
  },
  "ConstraintFor": {
    "All": "All",
    "Resources": "Resources",
    "Departments": "Departments"
  },
  "ConstraintIf": {
    "Nothing": "Nothing",
    "Nb": "Nb",
    "NbHours": "NbHours",
    "Begin": "Begin",
    "End": "End"
  },
  "ConstraintOp": {
    "Nothing": "Nothing",
    "Equal": "Equal",
    "Inf": "Inf",
    "InfEqual": "InfEqual",
    "Sup": "Sup",
    "SupEqual": "SupEqual",
    "Before": "Before",
    "After": "After"
  },
  "ConstraintType": {
    "Task": "Task",
    "Unavailability": "Unavailability"
  },
  "ConstraintWhat": {
    "LabelAll": "LabelAll",
    "LabelExact": "LabelExact",
    "LabelBegin": "LabelBegin"
  },
  "ConstraintWhen": {
    "Nothing": "Nothing",
    "Day": "Day",
    "Week": "Week",
    "Month": "Month",
    "Year": "Year"
  },
  "CountHolidays": {
    "Five": "Five",
    "Six": "Six"
  },
  "CurrencyCode": {
    "GBP": "GBP",
    "EUR": "EUR",
    "USD": "USD",
    "DEM": "DEM",
    "FRF": "FRF",
    "CHF": "CHF",
    "ARS": "ARS",
    "BRL": "BRL",
    "CLP": "CLP",
    "CRC": "CRC",
    "RUB": "RUB",
    "GTQ": "GTQ",
    "PAB": "PAB",
    "PYG": "PYG",
    "PEN": "PEN",
    "UYU": "UYU",
    "SVC": "SVC",
    "HNL": "HNL",
    "NOK": "NOK",
    "CNY": "CNY",
    "JPY": "JPY",
    "CAD": "CAD"
  },
  "CustomerType": {
    "Individual": "Individual",
    "Company": "Company"
  },
  "DataFieldType": {
    "Date": "Date",
    "Time": "Time",
    "Text": "Text",
    "Numeric": "Numeric",
    "Double": "Double",
    "Combo": "Combo",
    "Link": "Link",
    "Check": "Check",
    "Memo": "Memo",
    "Separator": "Separator",
    "File": "File",
    "Position": "Position",
    "SignatureMobile": "SignatureMobile",
    "Hyperlink": "Hyperlink",
    "ProjectStartDate": "ProjectStartDate",
    "ProjectEndDate": "ProjectEndDate",
    "ProjectDuration": "ProjectDuration",
    "ProjectDeadline": "ProjectDeadline",
    "ProjectDeadlineOver": "ProjectDeadlineOver",
    "Signature": "Signature",
    "ProjectEstimateDuration": "ProjectEstimateDuration",
    "SubProjectEstimateDuration": "SubProjectEstimateDuration"
  },
  "DescriptionFieldType": {
    "Index1": "Index1",
    "Index2": "Index2",
    "EmailBody": "EmailBody",
    "Label": "Label",
    "Mobile": "Mobile",
    "CalendarBody": "CalendarBody",
    "EmailSubject": "EmailSubject",
    "Tooltip": "Tooltip",
    "LabelAssignment": "LabelAssignment",
    "CalendarSubject": "CalendarSubject",
    "Print": "Print",
    "LabelUnavailability": "LabelUnavailability",
    "PrintUnavailability": "PrintUnavailability"
  },
  "DescriptionFieldStyle": {
    "Normal": "Normal",
    "Bold": "Bold",
    "Italic": "Italic",
    "Underline": "Underline"
  },
  "DescriptionFieldColor": {
    "Custom": "Custom",
    "Default": "Default",
    "Destination": "Destination"
  },
  "Destination": {
    "Task0": "Task0",
    "Task2": "Task2",
    "Task3": "Task3",
    "Task4": "Task4",
    "Task5": "Task5",
    "Equipment0": "Equipment0",
    "Customer1": "Customer1",
    "MaterialResource1": "MaterialResource1",
    "MaterialResource2": "MaterialResource2",
    "MaterialResource3": "MaterialResource3",
    "Project0": "Project0",
    "HumanResource1": "HumanResource1",
    "HumanResource2": "HumanResource2",
    "Task1": "Task1",
    "HumanResource3": "HumanResource3",
    "Customer0": "Customer0",
    "HumanResource0": "HumanResource0",
    "Customer2": "Customer2",
    "MaterialResource0": "MaterialResource0",
    "Customer3": "Customer3",
    "Project1": "Project1",
    "Project2": "Project2",
    "SubProject0": "SubProject0",
    "Project3": "Project3"
  },
  "DestinationType": {
    "Task": "Task",
    "Customer": "Customer",
    "Equipment": "Equipment",
    "Resource": "Resource",
    "Project": "Project",
    "SubProject": "SubProject"
  },
  "DoMode": {
    "None": "None",
    "End": "End",
    "Duration": "Duration"
  },
  "EffActionType": {
    "Email": "Email",
    "Sms": "Sms",
    "MicrosoftOutlook": "MicrosoftOutlook",
    "GoogleCalendar": "GoogleCalendar"
  },
  "EffIfType": {
    "Category": "Category",
    "Status": "Status"
  },
  "EffIfOp": {
    "IsIn": "IsIn",
    "BecomesIn": "BecomesIn"
  },
  "EffSourceType": {
    "Customer": "Customer",
    "Resource": "Resource",
    "Project": "Project",
    "Status": "Status",
    "ResourceIn": "ResourceIn",
    "ProjectIn": "ProjectIn",
    "TaskIn": "TaskIn",
    "Assignment": "Assignment",
    "Unavailability": "Unavailability",
    "Task": "Task"
  },
  "EffStepType": {
    "Start": "Start",
    "End": "End",
    "Insert": "Insert",
    "Delete": "Delete",
    "Unperiodize": "Unperiodize",
    "Update": "Update"
  },
  "EffSubjectType": {
    "Assignment": "Assignment",
    "Unavailability": "Unavailability",
    "Task": "Task"
  },
  "EffTargetType": {
    "Customer": "Customer",
    "Resource": "Resource",
    "User": "User",
    "Account": "Account"
  },
  "HistoryOp": {
    "Insert": "Insert",
    "Delete": "Delete",
    "Email": "Email",
    "Invitation": "Invitation",
    "Unperiodize": "Unperiodize",
    "Session": "Session",
    "Update": "Update"
  },
  "HistoryType": {
    "Assignment": "Assignment",
    "Customer": "Customer",
    "SessionDesktop": "SessionDesktop",
    "Unavailability": "Unavailability",
    "SessionMobile": "SessionMobile",
    "Project": "Project",
    "Resource": "Resource",
    "Task": "Task",
    "SessionWebAccess": "SessionWebAccess"
  },
  "InRootType": {
    "Customer": "Customer",
    "Project": "Project",
    "Resource": "Resource"
  },
  "JoinStatus": {
    "Invited": "Invited",
    "Connected": "Connected"
  },
  "JsonWritingType": {
    "None": "None",
    "Normal": "Normal",
    "KeyLabel": "KeyLabel",
    "String": "String",
    "Data": "Data"
  },
  "LicenseStatus": {
    "Other": "Other",
    "Evaluation": "Evaluation",
    "Ok": "Ok",
    "NoExpirationDate": "NoExpirationDate",
    "WrongDatabase": "WrongDatabase",
    "WrongMachine": "WrongMachine",
    "ResourceCount": "ResourceCount",
    "LicenseCount": "LicenseCount",
    "Expired": "Expired",
    "Empty": "Empty",
    "Corrupted": "Corrupted"
  },
  "LinkRefType": {
    "Assignment": "Assignment",
    "Customer": "Customer",
    "Unavailability": "Unavailability",
    "Project": "Project",
    "Resource": "Resource",
    "Task": "Task"

  },
  "NotificationType": {
    "None": "None",
    "TaskInsert": "TaskInsert",
    "TaskUpdate": "TaskUpdate",
    "UnavailabilityInsert": "UnavailabilityInsert",
    "UnavailabilityUpdate": "UnavailabilityUpdate"
  },
  "OneOrMoreCustomers": {
    "OneCustomer": "OneCustomer",
    "MoreCustomer": "MoreCustomer"
  },
  "OneOrMoreResources": {
    "OneResource": "OneResource",
    "MoreResource": "MoreResource"
  },
  "RecurrenceDaily": {
    "AllThe": "AllThe",
    "AllWorkingDays": "AllWorkingDays"
  },
  "RecurrenceMonthly": {
    "Date": "Date",
    "Day": "Day"
  },
  "RecurrenceMonthlyDayWhich": {
    "First": "First",
    "Second": "Second",
    "Third": "Third",
    "Fourth": "Fourth",
    "Last": "Last"
  },
  "RecurrenceRange": {
    "NoEndDate": "NoEndDate",
    "EndThe": "EndThe"
  },
  "RecurrenceType": {
    "Daily": "Daily",
    "Weekly": "Weekly",
    "Monthly": "Monthly",
    "Yearly": "Yearly"
  },
  "ResourceType": {
    "Human": "Human",
    "Material": "Material",
    "ToPlan": "ToPlan",
    "Extern": "Extern"
  },
  "StatusType": {
    "Task": "Task",
    "Unavailability": "Unavailability"
  },
  "SyncType": {
    "_Google": "_Google",
    "Microsoft": "Microsoft",
    "Google": "Google"
  },
  "TaskType": {
    "Default": "Default",
    "Duration": "Duration",
    "Time": "Time"
  },
  "Title": {
    "Miss": "Miss",
    "Mr": "Mr",
    "Ms": "Ms"
  },
  "TimeLapseUnit": {
    "Day": "Day",
    "Week": "Week",
    "Month": "Month",
    "Year": "Year"
  },
  "TypeHatch": {
    "BDIAGONAL": "BDIAGONAL",
    "CROSS": "CROSS",
    "DIAGCROSS": "DIAGCROSS",
    "FDIAGONAL": "FDIAGONAL",
    "HORIZONTAL": "HORIZONTAL",
    "VERTICAL": "VERTICAL"
  },
  "WorkCapacity": {
    "Hours": "Hours",
    "Slots": "Slots"
  }
},
...

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 nell'API di PlanningPME e in PlanningPME WebAccess sono: tedesco(de), inglese (en), danese (da), spagnolo(es), finlandese(fi), francese (fr), italiano(it), giapponese (ja), ollandese(nl) norvegese (no), polacco (pl), portoghese (pt), russo (ru), svedese (sv).

Negli esempi seguenti, la chiave dell'applicazione utilizzata è indicata come "your_key" e il token di autorizzazione è "your_token". Si prega di sostituirli con i propri 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"
        }
      }
    ]
  ]
}