PlanningPME API - Documentación del desarrollador
Interconecta tu agenda con el resto de tu sistema de información.
PlanningPME permite el acceso de lectura y escritura a los datos de la base de datos de sus clientes a través de una API dedicada.
La API de PlanningPME cumple con los estándares de desarrollo actuales (implementación de REST e intercambio de datos en formato JSON) para una programación sencilla de sus sincronizaciones e integraciones.
Este documento le informará sobre:
- ¿Dónde puedo encontrar la dirección de su API de PlanningPME?
- ¿Cómo acceder a su documentación interactiva?
- Implementando seguridad en la API de PlanningPME
- ¿Cuáles son los hechos generales sobre los datos de la API de PlanningPME?
- ¿Cómo hacer sus primeras solicitudes a la API de PlanningPME?
La API de PlanningPME está basada en los principios de la API RESTful y el formato de transferencia de datos utilizado es JSON.
Esta documentación es principalmente para desarrolladores. Le recomendamos que lea la API REST de la API de JSON antes de continuar.
URL deseada
Cada cliente PlanningPME tiene su propia dirección de API dedicada.
Supongamos que su marca es "MyCompany", lo más probable es que necesite usar la clave "mycompany" (que no distingue entre mayúsculas y minúsculas) para crear su dirección API.
Esta clave se marcará como " su_marca " en el resto de esta documentación.
La dirección API base de una marca registrada siempre tendrá el formato:
https://api.planningpme.com/su_marca/
Documentación interactiva
Cada API viene con una documentación interactiva, muy útil para descubrir los métodos y modelos utilizados en la API de PlanningPME, o generar consultas.
Esta documentación está disponible en la siguiente dirección:
https://api.planningpme.com/su_marca/doc/index
Estas dos direcciones no se pueden llamar sin presentar una clave de API .
Seguridad
1 / Presentación de la clave API
El acceso a su API requiere una clave que identifique la aplicación que llama a la API: una clave de aplicación.
Esta clave de aplicación está disponible en su cuenta de PlanningPME o bajo demanda en soporte.
Más allá de la seguridad que brinda, la clave de aplicación le permite identificar un acceso por parte de un socio o una aplicación de terceros con su propia clave.
La clave de aplicación siempre debe enviarse en el encabezado de una solicitud de API, utilizando el encabezado "X-APPKEY" dedicado.
GET /su_marca/api/config HTTP/1.1 Host: api.planningpme.com X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
Para acceder a su documentación interactiva, use su tecla de aplicación como parámetro de dirección , como se muestra en el siguiente ejemplo:
https://api.planningpme.com/su_marca/doc/index?appkey=e991573da5ffd4sab9b1e26bc6b64aac
2 / Autenticación y carga de perfil.
La mayoría de las solicitudes de API deben ser autenticadas por un usuario de la aplicación para cargar su perfil al acceder a los datos y respetar los permisos definidos de usuario y grupo.
Se otorga una autorización al enviar el nombre de usuario y la contraseña a la API y luego obtener un token que se usará para autenticar o suplantar una llamada a la API más tarde.
La obtención de un token de autorización siempre se realiza mediante la publicación de estos datos en la url "/ token".
POST /votre_marque/token HTTP/1.1 Host: api.planningpme.com X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac grant_type=password&username=su_usuario&password=su_contraseña
En el caso de una autentificación exitosa, el cuerpo de la respuesta contendrá un elemento JSON de la siguiente manera.
{
"access_token": "KTuZYDLG2qjUMqMVXDuiP9giFbqDXstESvpUWzBFLpkfdlMiB3PD5s2K7En-3o39u56hpr_DlyjEc_oUzBbR0PoEQfOb_O7m5BrLz9vwDzV_YjtRRrQ_7QxYnxO9uZs38SJ7UxTjDZgx_JKRUoZ3Wk6RNnXRpSkcmOrINvJLDMYXptYFiTjn9Op-vkPdtOKFp9M1cNjrH1ho2uaRBpUUMH_vJ-8W8mTH9wgFrJlecGIpntb7jet2GYpGs3Is0gcH",
"token_type": "bearer",
"expires_in": 86399,
"username": "su_usuario"
}
El valor de la propiedad "access_token" debe usarse en cualquier solicitud posterior de API que requiera autorización hasta que el token caduque. Además, como lo indica la propiedad "token_type", este valor es un token "portador".
Por lo tanto, las consultas que requieren autorización deben presentar el encabezado "Autorización" con el valor "Portador" especificado.
POST /su_marca/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
Utilización de la API
1/ Generalidades
a) Modelos de datos
Los modelos de datos de PlanningPME se detallan en la documentación interactiva de su API.
b) Formato de fecha
El formato de fecha utilizado por la API y esperado en cada solicitud JSON es el formato ISO 8601 . Ex:
2018-01-25T18:05:00Z
c) orden de lista
Los métodos GET a menudo usan un parámetro " sortInfo " para establecer el orden de clasificación de la lista completa o paginada que se devuelve.
Esta información se compone del nombre de una propiedad seguida directamente por un signo + o -.
Por ejemplo, use " label + " para solicitar una ordenación alfabética ascendente en la propiedad "label".
También es posible combinar varios comandos agregándolos.
Por ejemplo, use " not Valid-label " para solicitar una clasificación descendiendo la propiedad "notValid" y luego alfabéticamente ascendiendo a "label".
Tenga en cuenta que los nombres de propiedades distinguen entre mayúsculas y minúsculas.
d) Constantes de enumeración
Aunque no cambiará, excepto agregar, la lista completa de enumeración utilizada en su versión de API se obtiene llamando al método "/ api / config".
GET /su_marca/api/config HTTP/1.1 Host: api.planningpme.com X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
A continuación se muestra la lista de enumeraciones en la versión 4.1.1.117.
{
...
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) Lenguaje de respuesta
El idioma deseado en los textos de respuesta, como los mensajes de error, se puede especificar en el encabezado " Aceptar-Idioma ".
Aceptar-Idioma: es
Los idiomas disponibles en PlanningPME API y PlanningPME WebAccess son: alemán (de), inglés (en), danés (da), español (es), finlandés (fi), francés (fr), italiano (it), holandés (nl) , Noruego (no), polaco (pl), ruso (ru), sueco (sv).
Ejemplos de consulta API
En los ejemplos a continuación, la clave de aplicación utilizada se indica como " su_clave ", y la token de autenticación " your_jeton ". Por favor reemplazarlos con sus propios valores.
/api/task
→ Recupera una lista (completa o paginada) de tareas con el método GET "/ api / task".
GET /su_marca/api/task?pageIndex=1&pageSize=20&sortInfo=label- HTTP/1.1 Host: api.planningpme.com X-APPKEY: tu_clave Authorization: Bearer tu_token
Devuelva la segunda página de veinte tareas en una tabla clasificada en orden ascendente en la etiqueta.
{
"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"
}
}
]
}
→ Recupere los detalles de una tarea con el método GET "/ api / task / {id}".
GET /su_marca/api/task/756 HTTP/1.1 Host: api.planningpme.com X-APPKEY: votre_clé Authorization: Bearer tu_token
Devuelve los detalles de la tarea 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"
}
}
]
]
}