Verbind uw planning met de rest van uw informatiesysteem.
PlanningPME biedt lees- en schrijftoegang tot uw database via een speciale API. De PlanningPME API volgt de huidige ontwikkelingsstandaard (REST-implementatie en JSON-geformatteerd gegevenstransport) voor een eenvoudige programmering van uw synchronisaties en integraties.

Dit document informeert u over:

Hoe uw PlanningPME API-adres bepalen?
Waar vindt u uw interactieve documentatie?
Hoe de beveiliging is geïmplementeerd in PlanningPME API?
Wat zijn de algemene gegevensoverwegingen in PlanningPME API?
Hoe uw eerste verzoeken aan PlanningPME API te doen?

PlanningPME API is gebaseerd op RESTful principes, en het standaardformaat voor gegevensoverdracht is JSON.
Deze documentatie is voornamelijk voor ontwikkelaars. We raden de lezer aan zich vertrouwd te maken met de JSON REST API-programmering voordat hij verder gaat.

Elke PlanningPME-client heeft zijn eigen speciale API-adres.
Stel dat uw merknaam "MyCompany" is, u moet waarschijnlijk de merkcode "mycompany" gebruiken (case negeren) om uw API-adres op te bouwen.
Deze sleutel wordt in de rest van deze documentatie genoteerd als " your_brandk ".

Het basis-API-adres van een merk is altijd:
https://api.planningpme.com/your_brand/
of 
https://try.planningpme.com/your_brand/

Elke merk-API presenteert ook een interactieve documentatie, erg handig om uw PlanningPME API-methoden en modellen te ontdekken en API-aanroepen te bouwen.

Deze documentatie is beschikbaar op het volgende adres:
https://api.planningpme.com/your_brand/doc/index
of 
https://try.planningpme.com/your_brand/doc/index

Die twee adressen kunnen niet worden aangeroepen zonder een toepassingssleutel te presenteren .

Opmerking: als accountverificatie is ingeschakeld op uw API, is de toegang tot de interactieve documentatie één klik verwijderd binnen de PlanningPME accounttoepassing.

1 / Toepassing sleutel presentatie

U hebt een applicatiesleutel (appkey) nodig om toegang te krijgen tot uw API, waarmee de beller-applicatie wordt geïdentificeerd.
Deze appkey is beschikbaar in uw PlanningPME-account (als accountverificatie is geactiveerd op uw API), of op verzoek bij support.
Naast het beveiligen van API-toegang, kunt u met de appkey toegang verlenen tot een partner of een laag-applicatie, door hen hun eigen sleutel te geven om hun oproepen naar de API te identificeren.

De appkey moet altijd worden doorgegeven in de headers van een API-aanroep, met behulp van een speciale "X-APPKEY" -header.

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

Om toegang te krijgen tot je interactieve documentatie gebruik je de appkey als adresparameter, zoals in het onderstaande voorbeeld.

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

2 / Gebruikerstoken en imitatie

De meeste API-verzoeken moeten ook een authorisatie token bevatten, om het profiel te bepalen van de gebruiker die toegang heeft tot de gegevens en om de gebruikers- en groepsautorisaties te respecteren die in de applicatie zijn gedefinieerd.

Dit token wordt vooraf verkregen wanneer een gebruiker wordt geverifieerd op het /token adres, en blijft 8 uur geldig.

De gegevens die naar dit adres worden verzonden, verschillen afhankelijk van de authenticatiemodus die voor je toepassing is gekozen.

a) Traditionele authenticatie

Als dit is ingeschakeld, wordt traditionele authenticatie uitgevoerd door de gebruikersnaam en het wachtwoord op te geven.

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=je_gebruikersnaam&password=je_wachtwoord

b) Accountverificatie

Als dit is ingeschakeld, wordt accountverificatie bereikt door een serviceaccounttoken te posten, die eerder is verkregen in de PlanningPME-accounttoepassing.

Voor elke gebruiker die hier wordt vermeld, kunt u het token van de serviceaccount naar uw klembord kopiëren.

Verkrijg nu een autorisatietoken van je API, door het gekopieerde accounttoken (assertie) te posten.

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) Gebruik van het autorisatietoken

In het geval van succesvolle authenticatie zal de responsinstantie als volgt een JSON-element bevatten.

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

De eigenschap "access_token" bevat het API autorisatietoken.

Zoals aangegeven door de eigenschap "token_type" is dit token van het type "bearer". Verzoeken die autorisatie vereisen moeten daarom de "Authorization" header met de waarde "Bearer" presenteren, zoals in het onderstaande voorbeeld.

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

1 / Algemene gegevensoverwegingen

a) Modellen

PlanningPME-datamodellen kunnen eenvoudig worden ontdekt met behulp van de interactieve documentatie van uw API.

b) Datumnotatie

Datumnotatie die door de API wordt gebruikt en in elk JSON-verzoek wordt verwacht, is de ISO 8601-indeling . Ex:

2018-01-25T18:05:00Z

c) Sorteerlijsten

GET-methoden gebruiken vaak een parameter " sortInfo " om de sorteervolgorde van de geretourneerde volledige / gepagineerde lijst in te stellen.

Deze info bestaat uit de naam van een woning, direct gevolgd door een + of - teken.
Gebruik bijvoorbeeld " label+ " om te sorteren op oplopende eigenschap "label".

Het is ook mogelijk om meerdere bestellingen te combineren door ze toe te voegen.
Gebruik bijvoorbeeld " not Valid-label+ " om te sorteren door de eigenschap "not Valid" af te dalen en vervolgens door de eigenschap "label" te laten stijgen.

Be aware that property labels are case sensitive.

d) Constante opsommingen

De volledige lijst met enums die in uw API-versie worden gebruikt, wordt verkregen door de methode "/ api/config" aan te roepen. Deze lijst kan niet worden gewijzigd, behalve in de toekomst.

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

Hieronder staat de lijst met enums in versie 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) Antwoordtaal

De taal die wordt gebruikt in antwoordteksten zoals foutmeldingen kan worden gespecificeerd met de kop " Accept-Language ".

Accept-Language: nl

De beschikbare talen in PlanningPME API en PlanningPME WebAccess zijn: Duits (de), Engels (en), Deens (da), Spaans (es), Fins (fi), Frans (fr), Italiaans (it), Japans (ja), Nederlands (nl), Noors (no), Pools (pl), Portugees (pt), Russisch (ru), Zweeds (sv).

In de onderstaande voorbeelden is de gebruikte applicatiesleutel "your_key" en het autorisatietoken "your_token". Vervang ze alsjeblieft door je eigen waarden.

/api/task

Krijg een volledige of gepagineerde lijst met taken met de GET "/ api/task" -methode.

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

Retourneert een reeks taken met de tweede pagina van 20 taken geordend op aflopend label.

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

Krijg een gedetailleerde taak met de GET "/api/task/{id}" methode.

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

Retourneert een gedetailleerde weergave van een taakobject van de taak met 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"
        }
      }
    ]
  ]
}