REST Tag-API

Uppdaterad av Victor Jespersen

REST Tags API:t gör det möjligt för dig att hantera taggkategorier och taggar i Quinyx via REST-slutpunkter. Det följer samma REST-designprinciper och autentiseringsmodell som andra Quinyx v2 Integration APIs.

Detta API kan användas för att:

  • Skapa och hämta taggkategorier
  • Skapa, uppdatera, hämta och ta bort taggar

API-dokumentation för rc: https://api-rc.quinyx.com/v2/docs

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

Åtkomsträttigheter

För att kunna skicka förfrågningar till REST Tags API måste du lägga till åtkomsträttigheter för taggar på dina integreringsuppgifter i kontoinställningar:

Taggkategorier

Taggkategorier används för att gruppera relaterade taggar.

Hämta alla taggkategorier

Hämtar alla taggkategorier.

Slutpunkt: GET /categories

Exempelresponse:

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

Hämta taggkategori efter externt ID

Hämtar en enskild taggkategori refererad av det angivna externa ID:t.

Slutpunkt: GET /categories/{categoryExternalId}

Query parametrar:

  • categoryExternalId - Externt ID för tagkategori.

Exempelresponse:

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

Taggar

Taggar tillhör en specifik kategori och enhet.

Skapa tagg

Skapar en ny tagg under den angivna kategorin.

Slutpunkt: POST /categories/{categoryExternalId}/tags

Sökvägsparametrar:

  • categoryExternalId - Externt ID för tagkategori.

Obligatoriska fält i förfrågans kropp:

  • externalId - Externt ID för tagg. Det kan inte finnas två taggar med samma externa ID inom samma kategori.
  • categoryExternalId - Externt ID för tagkategori.
  • unitExternalId - Externt ID för enhet. För taggar på kontonivå bör det vara en tom sträng.
  • name - Taggnamn

Exempelförfrågans kropp:

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

Exempelresponse:

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

Uppdatera tagg

Uppdaterar en befintlig tagg. Ersätter hela resursen (tagg) med det nya innehållet. Förfrågans kropp bör innehålla det fullständiga nya tillståndet för resursen (inte bara de fält som ändras).

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

Sökvägsparametrar:

  • categoryExternalId - Taggkategoris externa ID.
  • tagExternalId - Taggs externa ID.

Obligatoriska fält i förfrågans kropp:

  • externalId - Taggs externa ID. Det kan inte finnas två taggar med samma externa ID inom samma kategori.
  • categoryExternalId - Taggkategoris externa ID.
  • unitExternalId - Enhetens externa ID. För taggar på kontonivå bör det vara en tom sträng.
  • name - Taggnamn.

Exempelförfrågans kropp:

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

Exempelresponse:

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

Ta bort tagg

Tar bort den angivna taggen.

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

Sökvägsparametrar:

  • categoryExternalId - Extern ID för taggkategori.
  • tagExternalId - Extern ID för tagg.

Hämta tagg efter extern ID

Hämtar en specifik tagg.

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

Sökvägsparametrar:

  • categoryExternalId - Extern ID för taggkategori.
  • tagExternalId Tagg externt ID.

Exempelresponse:

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

Hämta alla taggar för taggkategori

Hämtar alla taggar i en kategori med hjälp av markörbaserad sidnumrering. För att hämta nästa sida, inkludera det returnerade nextCursor värdet i nästa begäran. (se Markörbaserad sidnumrering)

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

Sökvägsparametrar:

  • categoryExternalId - Taggkategoris externa ID.

Exempelresponse:

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

Cursorbaserad sidnumrering

Cursorbaserad sidnumrering använder en cursor för att hämta ett datachunk (sida). Cursorn för nästa anrop (nästa datachunk) tillhandahålls i responsen från det aktuella serviceanropet. Följande är ett exempel på hur du använder cursorbaserad sidnumrering för att hämta alla taggar som tillhör kategorin med externalId: ext-123:

  1. Gör det första anropet för att hämta taggar. Det första cursorbaserade sidnumreringsanropet har ingen cursorfrågeparameter. Frånvaron av denna frågeparameter i anropet indikerar att detta är det första anropet och instruerar tjänsten att returnera den första resultatsidan. Parametern size anger hur många objekt varje resultatsida kommer att innehålla. Den kan utelämnas, och då används standardvärdet.
    GET /v2/categories/ext-123/tags?size=100
    I responsen kommer content -fältet att innehålla en lista med 100 taggar, och nextCursor -fältet kommer att innehålla markövärdet för nästa anrop. Låt oss säga att tjänsten returnerade nextCursor: "NDY3NTM="
  2. Använd nextCursor -värdet för att göra det andra anropet för att hämta nästa resultatsida.
    GET /v2/categories/ext-123/tags?size=100&cursor=NDY3NTM=
    Responsen kommer att innehålla en lista över nästa 100 taggposter och markövärdet för nästa anrop.
  3. Upprepa steg 2 tills alla taggar har hämtats, det vill säga tills nextCursor -fältet i responsen är tomt.
  4. Den sista sidan med taggar kommer inte att ha en markör i responsen. Frånvaron av ett markövärde indikerar att den aktuella responsen är den sista resultatsidan.

Fick du hjälp?