Willkommen bei der Moovago API-Startanleitung!
Die Moovago API ermöglicht es Ihnen, Ihre verschiedenen in Moovago gespeicherten Daten programmatisch zu erstellen/lesen/ändern/löschen (= Datenaustausch mit Ihrem ERP-System, Ihren Servern…).
Dieser Leitfaden zeigt Ihnen, wie Sie unsere API konfigurieren und nutzen können.
Die derzeit von der API angebotenen Elemente sind die von unseren Kunden gewünschten Elemente. Wenn Sie weitere Anforderungen oder Fragen/Bemerkungen haben, teilen Sie uns dies bitte unter support@moovago.com mit.
Es ist hilfreich, die Bezeichnung einiger Elemente der Moovago app zu verstehen.
Unsere Endpunkte (API Endpoint) erfordern eine Authentifizierung mit API-Schlüssel.
Wenn Sie noch keinen Moovago API-Schlüssel haben, kontaktieren Sie uns bitte unter support@moovago.com.
Um sich zu authentifizieren, fügen Sie einfach Ihren API-Schlüssel in den Kopf Ihrer Abfragen ein.
(Beachten Sie die Hinweise in der E-Mail, die Sie mit Ihrem API-Schlüssel erhalten haben.)
Die Moovago API arbeitet mit GraphQL.
So könnte eine GraphQL QUERY Abfrage aussehen:
{ "query": "{ team { id name members { id alias } } }" }
oder (Sie können auch einen eigenen Namen für die Abfrage angeben, wenn Sie dies bevorzugen):
{ "query": "query MyTeamQuery { team { id name members { id alias } } }" }
Manchmal können Sie Eingabeparameter (= Variablen) angeben, um die Ergebnisse zu filtern (hier z.B. ein teamId ):
Achtung, Sie müssen die Anführungszeichen bei den Werten der Variablen weglassen!
{ "query": "{ companyList(filter: { teamId: \"XYZ\" }) { id name ownerIds } }" }
oder (Sie können auch das Feld variables in einer benannten Abfrage verwenden, wenn Sie dies bevorzugen):
Dies erfordert nicht, dass die Anführungszeichen weggelassen werden => „muss geschrieben werden \ „.
{ "query": "query MyCompanyListQuery($filter: FilterManyCompanyInput!) { companyList(filter: $filter) { id name ownerIds } }", "variables": { "filter": { "teamId": "XYZ" } } }
So könnte eine GraphQL MUTATION Abfrage aussehen:
{ "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 } } }" }
oder (Sie können auch das Feld variables in einer benannten Abfrage verwenden, wenn Sie dies bevorzugen):
{ "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" } } }
Bevor Sie fortfahren, sollten Sie die Dokumentation von graphql.org lesen, um mehr darüber zu erfahren.
Wir empfehlen die Verwendung eines GraphQL-Clients, der Sie beim Schreiben, Senden und Testen von GraphQL-Abfragen unterstützt, wie z.B.: Altair GraphQL Client
Die Introspektion ist auf unserem Server deaktiviert. Daher können Sie das GraphQL-Schema nicht direkt von unserem Server abrufen.
Sie können jedoch die Datei mit dem GraphQL-Schema der Moovago API hier herunterladen: moovago_api_graphql_schema.gql
und importieren Sie es in den Altair Client (Im Fenster oben rechts in Altair klicken Sie auf: Docs ->… -> Load Schema…)
Nachfolgend finden Sie einige Beispiele für QUERY- und MUTATION-Abfragen mit dem Befehlszeilen-Tool curl (ersetzen Sie <your-api-key> durch den Wert Ihres API-Schlüssels).
Sie müssen Ihren Abfragen auch die folgende Überschrift hinzufügen:
Content-Type: application/json
QUERY :
Holen Sie Ihr Team und die Teammitglieder zurück:
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 } } }" }'
Rufen Sie die Liste Ihrer Prinzipale ab (ersetzen Sie ‚<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 :
Gründung eines neuen Unternehmens (ersetzen Sie ‚<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" } } }'
Bearbeiten Sie ein bestehendes Unternehmen (ersetzen Sie ‚<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"} } } }'
In unserer GraphQL API Referenzdokumentation finden Sie eine Liste aller möglichen Abfragen sowie weitere Details zu unserer API.
GraphQL APIs können sowohl korrekte Daten als auch Fehler zurückgeben. Aus diesem Grund wird die Moovago API HTTP 200 Codes zurückgeben , auch wenn es Fehler gibt.
Fehler sind standardmäßig in einer Error-Tabelle enthalten. Eine Beschreibung jedes Fehlers finden Sie im Feld „Nachricht“.
Es liegt an Ihnen, diese Fehler zu erkennen und zu behandeln. Zum Beispiel, indem Sie alle Antworten unserer API abfangen und die Tabelle errors überprüfen.
Eine GraphQL-Antwort, die einen Fehler enthält, kann wie folgt aussehen:
{
"data": null,
"errors": [
{
"message": "You are not authorized to access this data",
"locations": [],
"errorType": "DataFetchingException",
"path": [
"companyList"
],
"extensions": null
}
]
}
Fehler, die von den Mutationen zurückgegeben werden
Standardmäßig werden die von den Mutationen zurückgegebenen Fehler wie im vorherigen Abschnitt beschrieben.
Aber Mutationen können auch Benutzer- und Geschäftslogikfehler direkt in den Unterdaten von „data“ zurückgeben. Dies ermöglicht es Ihnen, diese spezifischen Fehler, die für jede Mutation spezifisch sind, von den zuvor beschriebenen Fehlern auf globaler Ebene zu trennen (die dann nur für Analysefehler und andere allgemeinere serverseitige Fehler verwendet werden).
Alle diese mutationsspezifischen Fehler werden mit dem Suffix „Problem“ (entspricht einem Fehlercode) benannt. Jede Mutation kann einen oder mehrere Fehler zurückgeben. Und jede Mutation beschreibt die Arten von Fehlern, die sie zurückgeben kann. Sie können diese dann auf der Kundenseite verwenden, um die Fehler leicht zu identifizieren. Einige Fehlertypen können auch mit zusätzlichen Metadaten über den Fehler versehen werden.
Beispiel
Die Abfrage von Mutationsfehlern erfolgt über das Feld „message“, um Textfehlermeldungen abzurufen, und das Feld „__typename“, das den Fehlercode (vom Typ Problem) enthält.
Wir werden daher den folgenden Code in die Abfragen einfügen, um die Werte dieser beiden Felder (für jeden zurückgegebenen Fehler) zu erhalten:
errors {
__typename
... on Problem {
message
}
}
Dies ergibt z.B. für die Mutation 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 } } } } }" }
und die Antwort mit einem Fehler vom Typ MalformedParameterProblem mit einer Textnachricht, die den Fehler genauer beschreibt:
{
"data": {
"company": {
"create": {
"recordId": null,
"errors": [
{
"__typename": "MalformedParameterProblem",
"message": "An input parameter is empty, or contains an illegal character."
}
]
}
}
},
"errors": null
}
HTTP-Antwortcodes
Es ist auch möglich, dass der Moovago-Server herkömmliche HTTP-Codes
zurücksendet, um den Erfolg oder Misserfolg einer Anfrage anzuzeigen.
Im Allgemeinen zeigen die Codes 2xx einen Erfolg an (außer wenn die Errors-Tabelle nicht leer ist).
Die Codes 4xx zeigen an, dass ein Fehler bei den ge lieferten Daten aufgetreten ist .
Die Codes 5xx weisen auf einen Fehler hin, der von den Moovago-Servern herrührt.
200
Ok
Alles funktionierte wie geplant.
429
Too Many Requests
Zu viele Anfragen erreichten die API zu schnell. (max. 5 Anfragen pro Sekunde).
5xx
Server Errors
Irgendetwas ist mit dem Moovago-Server schief gelaufen.
Bei Ihren ersten Tests empfehlen wir Ihnen, einige Ihrer Daten nacheinander zu importieren, um zu testen und jedes Mal sicherzustellen, dass die Daten mit den richtigen Werten und in die richtigen Felder importiert wurden. Und erst dann können Sie alle Ihre Daten in Massen importieren, wobei Sie eine angemessene Rate bevorzugen sollten (idealerweise max. 1 Abfrage pro Sekunde).
Die Servergrenzen für API sind derzeit auf :
Wenn diese Grenze überschritten wird, antwortet der Server mit einem Statuscode. 429 Too Many Requests (Zu viele Anfragen)
Auf dem Produktionsserver programmieren Sie bitte Ihre Massenverarbeitung so, dass sie außerhalb des Zeitfensters erfolgt:
Montag bis Freitag von 8.00 bis 18.30 Uhr.
Die Moovago API wird regelmäßig weiterentwickelt, um neue Funktionen zu bieten, die meist keine Auswirkungen auf Ihren Connector haben. Es kann jedoch vorkommen, dass wir aufgrund bestimmter Entwicklungen gezwungen sind, Teile der API zu veralten. Diese Elemente werden dann in unserer Referenzdokumentation für einige Monate als deprecated gekennzeichnet, so dass Sie Zeit haben, Ihren Konnektor zu aktualisieren. Die deprecated Elemente werden dann vollständig entfernt.
Es liegt in Ihrer Verantwortung, Ihren Konnektor weiterzuentwickeln und auf dem neuesten Stand zu halten. Sie sollten keine veralteten Elemente mehr verwenden, bevor diese entfernt wurden, da Ihr Konnektor sonst nicht mehr funktioniert.