PlanningPME

PlanningPME API - Documentatie voor ontwikkelaars

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:

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.

Dedicated URL

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/

Interactieve documentatie

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

Interactieve documentatie

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

Beveiliging

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 of op aanvraag voor onze ondersteuning
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 uw interactieve documentatie, gebruikt u uw appkey als een queryparameter , zoals in het onderstaande voorbeeld:

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

2 / Gebruikerstoken en imitatie

De meeste API-aanroepen moeten door de gebruiker worden geverifieerd om imitatie te gebruiken tijdens de gegevenstoegang en de gedefinieerde gebruikers- en groepsautorisaties te respecteren.

Een autorisatie wordt verleend door gebruikersnaam en wachtwoord in te dienen bij de API en vervolgens een token te krijgen dat zal worden gebruikt om een volgende API-aanroep te verifiëren of na te doen.

Het verkrijgen van een autorisatietoken gebeurt altijd door deze gegevens te posten naar de "/ token" url. 

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

grant_type=password&username=je_gebruikersnaam&password=je_wachtwoord

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

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

De waarde van de eigenschap "access_token" moet vervolgens worden gebruikt in volgende geautoriseerde aanvragen voor de API.
En zoals aangegeven door de eigenschap "token_type", is deze waarde een dragertoken.

Elke volgende geautoriseerde oproep moet dan de kop "Autorisatie" presenteren met deze specifieke "Drager" waarde.

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

API gebruik

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 de lijst enums voor versie 4.1.1.117 van de 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) 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: deens (da), nederlands (nl), engels (en), fins (fi), frans (fr), duits (de), italiaans (it), noors (nee) , pools (pl), russisch (ru), spaans (es), zweeds (sv).

2 / Voorbeelden van API-aanroepen

n de onderstaande voorbeelden wordt de applicatiesleutel genoteerd als " your_key " en de drager token als " uw_token ". Vervang ze door uw 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"
        }
      }
    ]
  ]
}