Benvenuto nella Guida introduttiva alle API di Moovago!
L’API di Moovago le consente di creare/leggere/modificare/cancellare i vari dati memorizzati in Moovago, in modo programmatico (= scambio di dati con il suo ERP, i suoi server…).
Questa guida le mostra come configurare e utilizzare la nostra API.
Gli elementi attualmente offerti dall’API sono quelli richiesti dai nostri clienti. Se ha altri requisiti o domande/commenti, non esiti a contattarci all’indirizzo support@moovago.com.
È utile avere una chiara comprensione dei nomi di una serie di elementi collegati all’applicazione Moovago.
I nostri endpoint (API Endpoint) richiedono l’autenticazione della chiave API.
Se non dispone ancora di una chiave API Moovago, ci contatti all’indirizzo support@moovago.com.
Per autenticarsi, basta aggiungere la sua chiave API all’intestazione delle sue richieste.
(Consulti le istruzioni contenute nell’e-mail che ha ricevuto con la sua chiave API).
L’API Moovago funziona con GraphQL.
Ecco come potrebbe apparire una QUERY GraphQL:
{ "query": "{ team { id name members { id alias } } }" }
oppure (può anche specificare un nome di query personalizzato, se preferisce):
{ "query": "query MyTeamQuery { team { id name members { id alias } } }" }
A volte può fornire dei parametri di input (= variabili) per filtrare i risultati (qui, un teamId per esempio):
Attenzione, deve sfuggire alle virgolette dai valori delle variabili!
{ "query": "{ companyList(filter: { teamId: \"XYZ\" }) { id name ownerIds } }" }
oppure (può anche utilizzare il campo variables in una query con nome, se preferisce):
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 (può anche utilizzare il campo variables in una query nominativa, se preferisce):
{ "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, può consultare la documentazione di graphql.org per saperne di più.
Le consigliamo di utilizzare un client GraphQL per aiutarla a scrivere, inviare e testare le sue query GraphQL, come: Altair GraphQL Client
L’introspezione è disabilitata sul nostro server. Pertanto, non è possibile recuperare lo schema GraphQL direttamente dal nostro server.
Tuttavia, può 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, faccia clic su : Docs ->… -> Carica schema…)
Di seguito sono riportati alcuni esempi di richieste di QUERY e MUTATION utilizzando lo strumento da linea di comando curl (sostituisca <your-api-key> con il valore della sua chiave API).
Deve anche aggiungere la seguente intestazione alle sue richieste:
Content-Type: application/json
DOMANDA :
Recupera il suo team e i suoi 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 suoi mandanti (sostituire ‘<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>" } } }'
MUTAZIONE :
Creare una nuova azienda (sostituire ‘<proprietarioId-valore>’):
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 ‘<aziendaId-valore>’):
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"} } } }'
Consulti 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 di errori. Troverà una descrizione di ogni errore nel campo “messaggio”.
Sta a lei rilevare e gestire questi errori. Ad esempio, intercettando tutte le risposte della nostra API e controllando la tabella degli errori.
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 di logica utente e aziendale, direttamente nei sottodati ‘dati’. Ciò consente 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 “Problema” (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. Può quindi utilizzarla sul lato client, se ha bisogno di identificare facilmente gli errori. Alcuni tipi di errore possono anche essere accompagnati da metadati aggiuntivi sull’errore.
Esempio
Per recuperare gli errori specifici delle mutazioni, utilizzi il campo “message” per recuperare i messaggi di errore testuali e il campo “__typename” contenente il codice di errore (Tipo di problema).
Aggiungeremo quindi 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 l'azienda creare la mutazione :
{ "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 degli errori 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
Troppe richieste
Troppe richieste hanno raggiunto l’API troppo rapidamente. (5 richieste al massimo al secondo).
5xx
Errori del server
Qualcosa è andato storto sul server di Moovago.
Per i primi test, le suggeriamo di importare alcuni dei suoi dati uno alla volta per verificare e assicurarsi ogni volta che i dati siano stati importati con i valori giusti e nei campi giusti. Solo allora sarà in grado di importare tutti i suoi 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 questo limite viene superato, il server risponderà con un codice di stato 429 Troppe richieste
Sul server di Produzione, la preghiamo di programmare l’elaborazione di 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 suo 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 che lei abbia il tempo di aggiornare il suo connettore. Gli elementi deprecati vengono poi rimossi completamente.
È sua responsabilità sviluppare e mantenere il suo connettore. Non deve utilizzare altri elementi deprecati prima che vengano rimossi, altrimenti il suo connettore non funzionerà più.