Benvenuto nella Guida introduttiva alle API di Moovago!
L’API di Moovago ti permette di creare, leggere, modificare, cancellare i vari dati memorizzati in Moovago, in modo programmatico (= scambio di dati con il tuo ERP, i tuoi server…).
Questa guida ti mostra come configurare e utilizzare la nostra API.
Gli elementi attualmente offerti dall’API sono quelli richiesti dai nostri clienti. Se hai altri requisiti o domande/commenti, non esitare a contattarci a support@moovago.com.
È utile avere una chiara comprensione dei nomi di alcuni elementi collegati all’applicazione Moovago.
I nostri endpoint (API Endpoint) richiedono l’autenticazione tramite chiave API.
Se non hai ancora una chiave API Moovago, ci contattaci all’indirizzo support@moovago.com.
Per autenticarti, basta aggiungere la tua chiave API all’intestazione delle tue richieste.
(Consulta le istruzioni contenute nell’e-mail che hai ricevuto con la tua chiave API).
L’API Moovago funziona con GraphQL.
Ecco come potrebbe apparire una QUERY GraphQL:
{ "query": "{ team { id name members { id alias } } }" }
oppure (puoi anche specificare un nome di query personalizzato, se preferisci):
{ "query": "query MyTeamQuery { team { id name members { id alias } } }" }
A volte puoi fornire dei parametri di input (= variabili) per filtrare i risultati (qui, un teamId per esempio):
Attenzione, deve fare l’escape delle virgolette nei valori delle variabili!
{ "query": "{ companyList(filter: { teamId: \"XYZ\" }) { id name ownerIds } }" }
oppure (puoi anche utilizzare il campo variables in una query con nome, se preferisci):
Questo non richiede l’escape delle virgolette => “deve essere scritto \ “.
{ "query": "query MyCompanyListQuery($filter: FilterManyCompanyInput!) { companyList(filter: $filter) { id name ownerIds } }", "variables": { "filter": { "teamId": "XYZ" } } }
Ecco come potrebbe apparire una richiesta di MUTATION GraphQL:
{ "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 } } }" }
oppure (puoi anche utilizzare il campo variables in una query nominativa, se preferisci):
{ "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" } } }
Prima di continuare, puoi consultare la documentazione di graphql.org per saperne di più.
Ti consigliamo di utilizzare un client GraphQL per aiutarti a scrivere, inviare e testare le tue query GraphQL, come: Altair GraphQL Client
L’introspezione è disabilitata sul nostro server. Pertanto, non è possibile recuperare lo schema GraphQL direttamente dal nostro server.
Tuttavia, puoi scaricare il file dello schema GraphQL di Moovago API qui: moovago_api_graphql_schema.gql
e importarlo nel client Altair (nella finestra Altair in alto a destra, clicca su : Docs ->… -> Load Schema…)
Di seguito sono riportati alcuni esempi di richieste di QUERY e MUTATION utilizzando lo strumento da linea di comando curl (sostituisci <your-api-key> con il valore della tua chiave API).
Devi anche aggiungere la seguente intestazione alle tue richieste:
Content-Type: application/json
QUERY :
Recupera il tuo team e i tuoi membri:
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 } } }" }'
Recupera l’elenco dei tuoi mandanti (sostituisci ‘<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>" } } }'
MUTATION :
Creare una nuova azienda (sostituisci ‘<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" } } }'
Modificare un’azienda esistente (sostituire ‘<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"} } } }'
Consulta la documentazione di riferimento della nostra API GraphQL per un elenco di tutte le richieste possibili, oltre a tutti i dettagli della nostra API.
Le API GraphQL possono restituire sia dati corretti che errori in parallelo. Questo è il motivo per cui l’API Moovago restituirà i codici HTTP 200 anche in presenza di errori.
Gli errori sono contenuti di default in una tabella errors. Troverà una descrizione di ogni errore nel campo “messaggio”.
Sta a te rilevare e gestire questi errori. Ad esempio, intercettando tutte le risposte della nostra API e controllando la tabella errors.
Ecco come potrebbe apparire una risposta GraphQL contenente un errore:
{
"data": null,
"errors": [
{
"message": "You are not authorized to access this data",
"locations": [],
"errorType": "DataFetchingException",
"path": [
"companyList"
],
"extensions": null
}
]
}
Errori restituiti dalle mutazioni
Per impostazione predefinita, gli errori restituiti dalle mutazioni sono quelli descritti nella sezione precedente.
Ma le mutazioni possono anche restituire errori lato utente e errori di business logic, direttamente nei sottodati “data”. Questo ti permette di separare questi errori specifici delle mutazioni dagli errori di livello globale visti in precedenza (che vengono poi utilizzati solo per gli errori di analisi e altri errori più generali lato server).
Tutti questi errori specifici della mutazione sono denominati con il suffisso “Problem” (equivalente a un codice di errore). Ogni mutazione può restituire uno o più errori. E ogni mutazione descrive i tipi di errore che può restituire. Puoi poi utilizzare queste informazioni lato client per identificare facilmente gli errori. Alcuni tipi di errore possono anche essere accompagnati da metadati aggiuntivi relativi all’errore.
Esempio
Per recuperare gli errori specifici delle mutazioni, utilizza il campo “message” per recuperare i messaggi di errore testuali e il campo “__typename” contenente il codice di errore (di tipo Problema).
Devi quindi aggiungere il seguente codice alle query per recuperare i valori di questi 2 campi (per ciascuno degli errori restituiti):
errors {
__typename
... on Problem {
message
}
}
Ad esempio, per la mutazione company create:
{ "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 } } } } }" }
e la risposta contenente un errore MalformedParameterProblem con un messaggio di testo che descrive l'errore in modo più dettagliato:
{
"data": {
"company": {
"create": {
"recordId": null,
"errors": [
{
"__typename": "MalformedParameterProblem",
"message": "An input parameter is empty, or contains an illegal character."
}
]
}
}
},
"errors": null
}
Codici di risposta HTTP
È anche possibile che il server Moovago restituisca i codici HTTP convenzionali
per indicare il successo o il fallimento di una richiesta.
Come regola generale, i codici 2xx indicano il successo (a meno che la tabella errors non sia vuota).
I codici 4xx indicano che si è verificato un errore nei dati forniti.
I codici 5xx indicano un errore proveniente dai server Moovago.
200
Ok
Tutto è andato secondo i piani.
429
Too Many Requests
Troppe richieste hanno raggiunto l’API troppo rapidamente. (5 richieste al massimo al secondo).
5xx
Server Errors
Qualcosa è andato storto sul server di Moovago.
Per i primi test, ti consigliamo di importare alcuni dei tuoi dati uno alla volta per verificare e assicurarti ogni volta che i dati siano stati importati con i valori giusti e nei campi giusti. Solo dopo potrai importare tutti i tuoi dati in massa, ad una velocità ragionevole (idealmente un massimo di 1 richiesta al secondo).
I limiti del server per l’API sono attualmente impostati a :
Se superi questo limite, il server risponderà con un codice di stato 429 Too Many Requests
Sul server di Produzione, ti preghiamo di programmare le tue elaborazioni in massa in modo che avvenga al di fuori dei seguenti orari:
dal lunedì al venerdì, dalle 8.00 alle 18.30.
L’API di Moovago viene regolarmente aggiornata con nuove funzionalità, la maggior parte delle quali non ha alcun impatto sul tuo connettore. Occasionalmente, tuttavia, alcuni sviluppi ci costringono a deprecare elementi dell’API. Questi elementi vengono indicati nella nostra documentazione di riferimento come deprecati per alcuni mesi, in modo da darti il tempo di aggiornare il tuo connettore. Gli elementi deprecati vengono poi rimossi completamente.
È tua responsabilità far evolvere e mantenere aggiornato il tuo connettore. Non usare elementi deprecati prima della loro rimozione, altrimenti il tuo connettore non funzionerà più.