REST Tag-API

Updated by Victor Jespersen

De REST Tags API stelt u in staat om tagcategorieën en tags in Quinyx via REST-eindpunten te beheren. Deze volgt dezelfde REST-ontwerpprincipes en verificatiemodel als andere Quinyx v2 Integration APIs.

Deze API kan worden gebruikt voor:

  • Tagcategorieën maken en ophalen
  • Tags maken, bijwerken, ophalen en verwijderen

API-docs voor rc: https://api-rc.quinyx.com/v2/docs

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

Toegangsrechten

Om verzoeken naar de REST Tags API te kunnen verzenden, moet u toegangsrechten voor Tags toevoegen aan uw integratiereferenties in accountinstellingen:

Tagcategorieën

Tagcategorieën worden gebruikt om gerelateerde tags te groeperen.

Alle tagcategorieën ophalen

Haalt alle tagcategorieën op.

Eindpunt: GET /categories

Voorbeeldrespons:

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

Tagcategorie ophalen op basis van externe ID

Haalt een enkele tagcategorie op waarnaar wordt verwezen door de gegeven externe ID.

Eindpunt: GET /categories/{categoryExternalId}

Queryparameters:

  • categoryExternalId - Externe ID van tagcategorie.

Voorbeeldrespons:

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

Tags

Tags behoren tot een specifieke categorie en unit.

Tag maken

Maakt een nieuwe tag onder de opgegeven categorie.

Eindpunt: POST /categories/{categoryExternalId}/tags

Padparameters:

  • categoryExternalId - Externe ID van tagcategorie.

Verplichte velden in de requestbody:

  • externalId - Externe ID van tag. Er kunnen niet twee tags met dezelfde externe ID binnen dezelfde categorie bestaan.
  • categoryExternalId - Externe ID van tagcategorie.
  • unitExternalId - Externe ID van unit. Voor tags op accountniveau moet dit een lege tekenreeks zijn.
  • name - Tagnaam

Voorbeeldrequest body:

{ 
     "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"  
}

Voorbeeldrespons:

{ 
     "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 bijwerken

Werkt een bestaande tag bij. Vervangt de volledige resource (tag) met de nieuwe inhoud. De aanvraagtekst moet de volledige, nieuwe status van de resource bevatten (niet alleen de velden die worden gewijzigd).

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

Padparameters:

  • categoryExternalId - Tag Category externe ID.
  • tagExternalId - Tag externe ID.

Verplichte velden in de aanvraagtekst:

  • externalId - Tag externe ID. Er kunnen niet twee tags met dezelfde externe ID binnen dezelfde categorie bestaan.
  • categoryExternalId - Tag Category externe ID.
  • unitExternalId - Unit externe ID. Voor tags op accountniveau moet dit een lege tekenreeks zijn.
  • name - Tagnaam.

Voorbeeldaanvraagtekst:

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

Voorbeeldrespons:

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

Tag verwijderen

Verwijdert de opgegeven tag.

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

Padparameters:

  • categoryExternalId - Externe ID van tagcategorie.
  • tagExternalId - Externe ID van tag.

Tag ophalen op basis van externe ID

Haalt een specifieke tag op.

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

Padparameters:

  • categoryExternalId - Externe ID van tagcategorie.
  • tagExternalId Tag externe ID.

Voorbeeldrespons:

{ 
     "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 voor tagcategorie ophalen

Haalt alle tags in een categorie op met behulp van cursor-gebaseerde paginering. Om de volgende pagina op te halen, voegt u de geretourneerde nextCursor waarde in het volgende verzoek in. (zie Cursor-gebaseerde paginering)

Eindpunt: GET /v2/categories/{categoryExternalId}/tags

Padparameters:

  • categoryExternalId - Tag categorie externe ID.

Voorbeeldrespons:

{ 
     "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-gebaseerde paginering

Cursor-gebaseerde paginering gebruikt een cursor om een gedeelte (pagina) van gegevens op te halen. De cursor voor de volgende aanroep (het volgende gedeelte van gegevens) wordt verstrekt in het antwoord van de huidige serviceaanroep. Hieronder volgt een voorbeeld van hoe u cursor-gebaseerde paginering kunt gebruiken om alle tags op te halen die behoren tot de categorie met externalId: ext-123:

  1. Voer de eerste aanroep uit om tags op te halen. De eerste cursor-gebaseerde pagineringsaanroep heeft geen cursor-queryparameter. De afwezigheid van deze queryparameter in de aanroep geeft aan dat dit de eerste aanroep is en geeft de service de opdracht om de eerste pagina met resultaten te retourneren. De size-parameter geeft aan hoeveel items elke pagina met resultaten zal bevatten. Deze kan worden weggelaten, en dan wordt de standaardwaarde gebruikt.
    GET /v2/categories/ext-123/tags?size=100
    In het antwoord bevat het content veld een lijst met 100 tags, en de nextCursor veld bevat de cursorwaarde voor de volgende aanroep. Stel dat de service nextCursor: "NDY3NTM="
  2. heeft geretourneerd. Gebruik de nextCursor waarde om de tweede aanroep uit te voeren en de volgende pagina met resultaten op te halen.
    GET /v2/categories/ext-123/tags?size=100&cursor=NDY3NTM=
    Het antwoord bevat een lijst met de volgende 100 tagrecords en de cursorwaarde voor de volgende aanroep.
  3. Herhaal stap 2 totdat alle tags zijn opgehaald, dus totdat het nextCursor veld in het antwoord leeg is.
  4. De laatste pagina met tags bevat geen cursor in het antwoord. De afwezigheid van een cursorwaarde geeft aan dat het huidige antwoord de laatste pagina met resultaten is.

How did we do?