¡Bienvenido a la Guía de inicio de la API de Moovago!
La API de Moovago le permite crear/leer/modificar/borrar sus diferentes datos almacenados en Moovago, de forma programática (= intercambio de datos con su ERP, sus servidores…).
Esta guía le muestra cómo configurar y utilizar nuestra API.
Los elementos que ofrece actualmente la API son los solicitados por nuestros clientes. Si tiene otros requisitos o preguntas/comentarios, no dude en ponerse en contacto con nosotros en support@moovago.com.
Es útil tener claros los nombres de una serie de elementos vinculados a la aplicación Moovago.
Nuestros puntos finales (API Endpoint) requieren la autenticación de la clave API.
Si aún no dispone de una clave API de Moovago, póngase en contacto con nosotros en support@moovago.com.
Para autenticarse, sólo tiene que añadir su clave API a la cabecera de sus peticiones.
(Consulte las instrucciones en el correo electrónico que recibió con su clave API)
La API de Moovago funciona con GraphQL.
Este es el aspecto que podría tener una CONSULTA GraphQL:
{ "query": "{ team { id name members { id alias } } }" }
o (también puede especificar un nombre de consulta personalizado si lo prefiere):
{ "query": "query MyTeamQuery { team { id name members { id alias } } }" }
A veces puede suministrar parámetros de entrada (= variables) para filtrar los resultados (aquí, un teamId por ejemplo):
¡Tenga cuidado, debe escapar las comillas de los valores de las variables!
{ "query": "{ companyList(filter: { teamId: \"XYZ\" }) { id name ownerIds } }" }
o (también puede utilizar el campo variables en una consulta con nombre si lo prefiere):
Esto no requiere que escape las comillas => «debe escribirse «.
{ "query": "query MyCompanyListQuery($filter: FilterManyCompanyInput!) { companyList(filter: $filter) { id name ownerIds } }", "variables": { "filter": { "teamId": "XYZ" } } }
Este es el aspecto que podría tener una solicitud GraphQL MUTATION:
{ "query": "mutation { company { create( input: { ownerIds: [\"XYZ\"], name: \"Moovago\", city: \"Niort\", address: \"46 Rue du 14 Juillet\", postalCode: \"79000\", phone: \"07 68 45 46 74\", email: \"support@moovago.com\", note: \"L application du commercial\" } ) { recordId } } }" }
o (si lo prefiere, también puede utilizar el campo variables en una consulta con nombre):
{ "query": "mutation MyCompanyCreate($input: CompanyCreateInput!) { company { create(input: $input) { recordId } } }", "variables": { "input": { "ownerIds": ["XYZ"], "name": "Moovago", "city": "Niort", "address": "46 Rue du 14 Juillet", "postalCode": "79000", "phone": "07 68 45 46 74", "email": "support@moovago.com", "note": "L application du commercial" } } }
Antes de continuar, puede consultar la documentación de graphql.org para obtener más información.
Le recomendamos que utilice un cliente GraphQL para ayudarle a escribir, enviar y probar sus consultas GraphQL, como por ejemplo: Altair GraphQL Client
La introspección está desactivada en nuestro servidor. Por lo tanto, no puede recuperar el esquema GraphQL directamente de nuestro servidor.
Sin embargo, puede descargar el archivo del esquema GraphQL de la API de Moovago aquí: moovago_api_graphql_schema.gql
e impórtelo en el cliente Altair (En la ventana superior derecha de Altair, haga clic en : Docs ->… -> Cargar esquema…)
A continuación se muestran algunos ejemplos de peticiones QUERY y MUTATION utilizando la herramienta de línea de comandos curl (sustituya <your-api-key> por el valor de su clave API).
También debe añadir la siguiente cabecera a sus peticiones:
Content-Type: application/json
CONSULTA :
Recupere a su equipo y a sus miembros:
curl https://<api-backend>/graphql \
-X POST \
-H '<your-api-key>' \
-H 'Content-Type: application/json' \
-d '{ "query": "query MyTeamQuery { team { id name members { id alias } } }" }'
Recupere la lista de sus principales (sustituya ‘<your-teamId>’):
curl https://<api-backend>/graphql \
-X POST \
-H '<your-api-key>' \
-H 'Content-Type: application/json' \
-d '{ "query": "query MyMandatorList($filter: FilterManyMandatorInput!) { mandatorList(filter: $filter) { id name } }", "variables": { "filter": { "teamId": "<your-teamId>" } } }'
MUTACIÓN :
Cree una nueva empresa (sustituya ‘<ownerId-value>’):
curl https://<api-backend>/graphql \
-X POST \
-H '<your-api-key>' \
-H 'Content-Type: application/json' \
-d '{ "query": "mutation MyCompanyCreate($input: CompanyCreateInput!) { company { create(input: $input) { recordId } } }", "variables": { "input": { "ownerIds": ["<ownerId-value>"], "name": "Moovago", "city": "Niort", "address": "46 Rue du 14 Juillet", "postalCode": "79000", "phone": "07 68 45 46 74", "email": "support@moovago.com", "note": "L application du commercial" } } }'
Modificar una empresa existente (sustituir ‘<companyId-value>’):
curl https://<api-backend>/graphql \
-X POST \
-H '<your-api-key>' \
-H 'Content-Type: application/json' \
-d '{ "query": "mutation MyCompanyUpdate($input: CompanyUpdateInput!) { company { update(input: $input) { recordId } } }", "variables": { "input": { "id": "<companyId-value>", "input": { "note": "Here is my new note"} } } }'
Consulte nuestra documentación de referencia de la API GraphQL para obtener una lista de todas las solicitudes posibles, así como todos los detalles de nuestra API.
Las API GraphQL pueden devolver tanto datos correctos como errores en paralelo. Esta es la razón por la que la API Moovago devolverá códigos HTTP 200 aunque haya errores.
Los errores están contenidos por defecto en una tabla de errores. Encontrará una descripción de cada error en el campo «mensaje».
Depende de usted detectar y gestionar estos errores. Por ejemplo, interceptando todas las respuestas de nuestra API y comprobando la tabla de errores.
Este es el aspecto que podría tener una respuesta GraphQL que contenga un error:
{
"data": null,
"errors": [
{
"message": "You are not authorized to access this data",
"locations": [],
"errorType": "DataFetchingException",
"path": [
"companyList"
],
"extensions": null
}
]
}
Errores devueltos por las mutaciones
Por defecto, los errores devueltos por las mutaciones son los descritos en la sección anterior.
Pero las mutaciones también pueden devolver errores de lógica de usuario y de negocio, directamente en los sub-datos ‘data’. Esto le permite separar estos errores específicos de las mutaciones de los errores a nivel global vistos anteriormente (que luego se utilizan sólo para errores de análisis y otros errores más generales del lado del servidor).
Todos estos errores específicos de mutación se denominan con el sufijo «Problema» (equivalente a un código de error). Cada mutación puede devolver uno o varios errores. Y cada mutación describe los tipos de error que puede devolver. Puede utilizarla en el lado del cliente si necesita identificar fácilmente los errores. Algunos tipos de error tambiénpueden ir acompañados de metadatos adicionales sobre el error.
Ejemplo
Para recuperar errores específicos de las mutaciones, utilice el campo «mensaje» para recuperar mensajes de error textuales y el campo «__tipo» que contiene el código de error (Tipo de problema).
Por lo tanto, añadiremos el siguiente código a las consultas para recuperar los valores de estos 2 campos (para cada uno de los errores devueltos):
errors {
__typename
... on Problem {
message
}
}
Por ejemplo, para la empresa crear mutación :
{ "query": "mutation { company { create( input: { ownerIds: [\"Space caracter is not allow here\"], name: \"Moovago\", city: \"Niort\", address: \"46 Rue du 14 Juillet\", postalCode: \"79000\", phone: \"07 68 45 46 74\", email: \"support@moovago.com\", note: \"L application du commercial\" } ) { recordId errors { __typename ... on Problem { message } } } } }" }
y la respuesta que contiene un error MalformedParameterProblem con un mensaje de texto que describe el error con más detalle:
{
"data": {
"company": {
"create": {
"recordId": null,
"errors": [
{
"__typename": "MalformedParameterProblem",
"message": "An input parameter is empty, or contains an illegal character."
}
]
}
}
},
"errors": null
}
Códigos de respuesta HTTP
También es posible que el servidor de Moovago devuelva los códigos HTTP convencionales de
para indicar el éxito o el fracaso de una solicitud.
Por regla general, los códigos 2xx indican éxito (a menos que la tabla de errores no esté vacía).
Los códigos 4xx indican que se ha producido un error en los datos suministrados.
Los códigos 5xx indican un error originado en los servidores de Moovago.
200
Ok
Todo salió según lo previsto.
429
Demasiadas peticiones
Demasiadas solicitudes llegaron a la API demasiado rápido. ( 5 peticiones máx / segundo).
5xx
Errores del servidor
Algo ha ido mal en el servidor de Moovago.
Para sus primeras pruebas, le sugerimos que importe algunos de sus datos de uno en uno para probar y asegurarse cada vez de que los datos se han importado con los valores correctos y en los campos adecuados. Sólo entonces podrá importar todos sus datos en masa, a un ritmo razonable (lo ideal sería un máximo de 1 solicitud por segundo).
Los límites del servidor para la API están fijados actualmente en :
Si se supera este límite, el servidor responderá con un código de estado 429 Demasiadas solicitudes
En el servidor de producción, programe su procesamiento masivo para que tenga lugar fuera de los siguientes horarios:
De lunes a viernes, de 8:00 a 18:30
La API de Moovago se actualiza regularmente con nuevas funciones, la mayoría de las cuales no tienen ningún impacto en su conector. Ocasionalmente, sin embargo, ciertos desarrollos nos obligan a dejar obsoletos elementos de la API. Estos elementos se indican en nuestra documentación de referencia como obsoletos durante unos meses, para que tenga tiempo de actualizar su conector. Posteriormente, los elementos obsoletos se eliminan por completo.
Es su responsabilidad desarrollar y mantener su conector. No debe utilizar más elementos obsoletos antes de que sean eliminados, de lo contrario su conector dejará de funcionar.