REST Tag API

Updated durch Victor Jespersen

Die REST Tags API ermöglicht es Ihnen, Tag-Kategorien und Tags in Quinyx über REST-Endpunkte zu verwalten. Sie folgt den gleichen REST-Designprinzipien und dem Authentifizierungsmodell wie andere Quinyx v2 Integration APIs.

Diese API kann verwendet werden für:

  • Erstellen und Abrufen von Tag-Kategorien
  • Erstellen, Aktualisieren, Abrufen und Löschen von Tags

API-Dokumentation für rc: https://api-rc.quinyx.com/v2/docs

API-Dokumentation: https://api.quinyx.com/v2/docs

Zugriffsrechte

Um Anfragen an die REST Tags API senden zu können, müssen Sie Zugriffsrechte für Tags in Ihren Integrationsdaten in den Kontoeinstellungen hinzufügen:

Tag-Kategorien

Tag-Kategorien werden verwendet, um verwandte Tags zu gruppieren.

Alle Tag-Kategorien abrufen

Ruft alle Tag-Kategorien ab.

Endpunkt: GET /categories

Beispielantwort:

[ 
     { "name": "Store Locations",  
       "tagType": "PROJECT",  
       "color": "#FF5733",  
       "externalId": "LOC-001"  
     },  
     { "name": "Services",  
       "tagType": "ACCOUNT",  
       "color": "#32CD32",  
       "externalId": "SRV-002"  
    } 
]

Tag-Kategorie nach External ID abrufen

Ruft eine einzelne Tag-Kategorie ab, auf die durch die angegebene External ID verwiesen wird.

Endpunkt: GET /categories/{categoryExternalId}

Abfrageparameter:

  • categoryExternalId - Externe ID der Tag-Kategorie.

Beispielantwort:

{ 
     "name": "Store Locations",  
     "tagType": "PROJECT",  
     "color": "#FF5733",  
     "externalId": "LOC-001"  
}

Tags

Tags gehören zu einer bestimmten Kategorie und Einheit.

Tag erstellen

Erstellt einen neuen Tag unter der angegebenen Kategorie.

Endpunkt: POST /categories/{categoryExternalId}/tags

Pfadparameter:

  • categoryExternalId - Externe ID der Tag-Kategorie.

Erforderliche Felder im Anforderungstext:

  • externalId - Externe ID des Tags. Es können nicht zwei Tags mit derselben externen ID innerhalb derselben Kategorie vorhanden sein.
  • categoryExternalId - Externe ID der Tag-Kategorie.
  • unitExternalId - Externe ID der Einheit. Für Tags auf Kontoebene sollte es eine leere Zeichenkette sein.
  • name - Tag-Name

Beispiel-Anforderungstext:

{ 
     "externalId": "STORE-001",  
     "categoryExternalId": "LOC-001",  
     "unitExternalId": "UNIT-01",  
     "name": "Downtown Store",  
     "uniqueScheduling": false,  
     "periods": [],  
     "coordinates": [],  
     "customFields": [],  
     "information": "Main location",  
     "startDate": "2025-01-01", 
 "endDate": "2025-12-31"  
}

Beispielantwort:

{ 
     "externalId": "STORE-001",  
     "categoryExternalId": "LOC-001",  
     "name": "Downtown Store",  
     "uniqueScheduling": false,  
     "periods": [],  
     "coordinates": [],  
     "customFields": [],  
     "information": "Main location",  
     "startDate": "2025-01-01",  
     "endDate": "2025-12-31"  
}

Tag aktualisieren

Aktualisiert ein vorhandenes Tag. Ersetzt die gesamte Ressource (Tag) durch den neuen Inhalt. Der Anforderungstext sollte den vollständigen, neuen Status der Ressource enthalten (nicht nur die geänderten Felder).

Endpunkt: PUT /categories/{categoryExternalId}/tags/{tagExternalId}

Pfadparameter:

  • categoryExternalId - Externe ID der Tag-Kategorie.
  • tagExternalId - Externe ID des Tags.

Erforderliche Felder im Anforderungstext:

  • externalId - Externe ID des Tags. Es können nicht zwei Tags mit derselben externen ID innerhalb derselben Kategorie vorhanden sein.
  • categoryExternalId - Externe ID der Tag-Kategorie.
  • unitExternalId - Externe ID der Einheit. Für Tags auf Kontoebene sollte es eine leere Zeichenkette sein.
  • name - Tag-Name.

Beispiel-Anforderungstext:

{ 
 "externalId": "STORE-001",  
     "categoryExternalId": "LOC-001",  
     "unitExternalId": "UNIT-01",  
     "name": "Downtown Store",  
     "uniqueScheduling": false,  
     "periods": [],  
     "coordinates": [],  
     "customFields": [],  
     "information": "Hauptstandort",  
     "startDate": "2025-01-01",  
     "endDate": "2025-12-31"  
}

Beispielantwort:

{ 
     "externalId": "STORE-001",  
     "categoryExternalId": "LOC-001",  
     "name": "Downtown Store",  
     "uniqueScheduling": false,  
     "periods": [],  
     "coordinates": [],  
     "customFields": [],  
     "information": "Hauptstandort",  
     "startDate": "2025-01-01",  
     "endDate": "2025-12-31"  
}

Tag löschen

Löscht das angegebene Tag.

Endpunkt: DELETE /categories/{categoryExternalId}/tags/{tagExternalId}

Pfadparameter:

  • categoryExternalId - Externe ID der Tag-Kategorie.
  • tagExternalId - Externe ID des Tags.

Tag nach externer ID abrufen

Ruft ein bestimmtes Tag ab.

Endpunkt: GET /categories/{categoryExternalId}/tags/{tagExternalId}

Pfadparameter:

  • categoryExternalId - Externe ID der Tag-Kategorie.
  • tagExternalId Tag externe ID.

Beispielantwort:

{ 
     "externalId": "STORE-001",  
     "categoryExternalId": "LOC-001",  
     "unitExternalId": "UNIT-01",  
     "name": "Downtown Store",  
     "uniqueScheduling": false,  
     "periods": [],  
     "coordinates": [],  
     "customFields": [],  
     "information": "Main location",  
     "startDate": "2025-01-01",  
     "endDate": "2025-12-31"  
}

Alle Tags für Tag-Kategorie abrufen

Ruft alle Tags in einer Kategorie ab und verwendet cursor-basierte Pagination. Um die nächste Seite abzurufen, fügen Sie den zurückgegebenen nextCursor Wert in die nächste Anfrage ein. (siehe Cursor-basierte Pagination)

Endpunkt: GET /v2/categories/{categoryExternalId}/Tags

Pfadparameter:

  • categoryExternalId - Tag-Kategorie externe ID.

Beispielantwort:

{ 
     "content": [  
      { 
         "externalId": "STORE-001",  
         "categoryExternalId": "LOC-001",  
         "unitExternalId": "UNIT-01",  
         "name": "Downtown Store",  
         "uniqueScheduling": false,  
         "periods": [],  
         "coordinates": [],  
         "customFields": [],  
         "information": "Main location", 
 "startDate": "2025-01-01",  
         "endDate": "2025-12-31"  
      } 
     ],  
     "page": {  
       "contentSize": 1,  
       "nextCursor": "eyJjdXJzb3IiOiIxMjM0In0="  
    } 
}

Cursor-basierte Pagination

Cursor-basierte Pagination verwendet einen Cursor, um einen Datenblock (Seite) abzurufen. Der Cursor für den nächsten Aufruf (der nächste Datenblock) wird in der Antwort des aktuellen Service-Aufrufs bereitgestellt. Im Folgenden finden Sie ein Beispiel für die Verwendung von cursor-basierter Pagination zum Abrufen aller Tags, die zur Kategorie mit externalId gehören: ext-123:

  1. Führen Sie den ersten Aufruf durch, um Tags abzurufen. Der erste cursor-basierte Pagination-Aufruf hat keinen cursor-Abfrageparameter. Das Fehlen dieses Abfrageparameters im Aufruf zeigt an, dass dies der erste Aufruf ist und teilt dem Service mit, die erste Seite der Ergebnisse zurückzugeben. Der size-Parameter gibt an, wie viele Elemente jede Ergebnisseite enthält. Er kann weggelassen werden, und dann wird der Standardwert verwendet.
    GET /v2/categories/ext-123/tags?size=100
    In der Antwort enthält das content Feld eine Liste von 100 Tags und das nextCursor Feld enthält den Cursor-Wert für den nächsten Aufruf. Angenommen, der Service hat nextCursor: "NDY3NTM="
  2. zurückgegeben. Verwenden Sie den nextCursor Wert, um den zweiten Aufruf zum Abrufen der nächsten Ergebnisseite zu tätigen.
    GET /v2/categories/ext-123/tags?size=100&cursor=NDY3NTM=
    Die Antwort enthält eine Liste der nächsten 100 Tag-Datensätze und den Cursor-Wert für den nächsten Aufruf.
  3. Wiederholen Sie Schritt 2, bis alle Tags abgerufen sind, d. h. bis das nextCursor Feld in der Antwort leer ist.
  4. Die letzte Seite der Tags hat keinen Cursor in der Antwort. Das Fehlen eines Cursor-Werts zeigt an, dass die aktuelle Antwort die letzte Ergebnisseite ist.

Wie haben wir das gemacht?