{"openapi":"3.1.0","info":{"title":"Tags Service Integration API","description":"Integration API endpoints for the Tags Service","version":"1.0"},"servers":[{"url":"https://api-rc.quinyx.com/v2/tags","description":""}],"tags":[{"name":"Tag Integration API","description":"REST endpoints for managing tags and tag categories"}],"paths":{"/categories/{categoryExternalId}/tags/{tagExternalId}":{"get":{"tags":["Tag Integration API"],"summary":"Get the specified tag by external tag category id and external tag id","description":"Retrieves a specific tag using its category external ID and tag external ID","operationId":"getTagByExternalId","parameters":[{"name":"categoryExternalId","in":"path","description":"External identifier of the tag category","required":true,"schema":{"type":"string"}},{"name":"tagExternalId","in":"path","description":"External identifier of the tag","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tag found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagIntegration"}}}}}},"put":{"tags":["Tag Integration API"],"summary":"Update an existing tag","description":"Updates all values of an existing tag. The categoryExternalId cannot be changed","operationId":"updateTagByExternalId","parameters":[{"name":"categoryExternalId","in":"path","description":"External identifier of the tag category","required":true,"schema":{"type":"string"}},{"name":"tagExternalId","in":"path","description":"External identifier of the tag to update","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Tag details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagIntegration"}}},"required":true},"responses":{"200":{"description":"Tag successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagIntegration"}}}}}},"delete":{"tags":["Tag Integration API"],"summary":"Delete a tag","description":"Deletes the tag with the given external category and tag ID","operationId":"deleteTagByExternalId","parameters":[{"name":"categoryExternalId","in":"path","description":"External identifier of the tag category","required":true,"schema":{"type":"string"}},{"name":"tagExternalId","in":"path","description":"External identifier of the tag to delete","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Tag successfully deleted"}}}},"/categories/{categoryExternalId}/tags":{"get":{"tags":["Tag Integration API"],"summary":"Get all tags by external tag category id","description":"Retrieves all tags associated with the specified category external ID","operationId":"getTagsByExternalCategoryId","parameters":[{"name":"categoryExternalId","in":"path","description":"External identifier of the tag category","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of tags retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TagIntegration"}}}}}}},"post":{"tags":["Tag Integration API"],"summary":"Create a tag with specified values","description":"Creates a new tag within the specified category. The created tag is returned","operationId":"createTagByExternalId","parameters":[{"name":"categoryExternalId","in":"path","description":"External identifier of the tag category","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Tag details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagIntegration"}}},"required":true},"responses":{"200":{"description":"Tag successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagIntegration"}}}}}}},"/categories":{"get":{"tags":["Tag Integration API"],"summary":"Get all tag categories","description":"Retrieves a list of all tag categories associated with the domain group","operationId":"getTagCategoriesExternal","responses":{"200":{"description":"List of tag categories retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TagCategory_Default"}}}}}}}},"/categories/{categoryExternalId}":{"get":{"tags":["Tag Integration API"],"summary":"Get the tag category specified by the external id","description":"Retrieves a tag category using its external identifier","operationId":"getTagCategoryByExternalId","parameters":[{"name":"categoryExternalId","in":"path","description":"External identifier of the tag category","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tag category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagCategory_Default"}}}}}}}},"components":{"schemas":{"Coordinate":{"type":"object","description":"Represents geographic coordinates for a location","properties":{"latitude":{"type":"number","format":"float","description":"Latitude of the location","example":59.334591},"longitude":{"type":"number","format":"float","description":"Longitude of the location","example":18.06324},"radius":{"type":"integer","format":"int32","description":"Radius of the location","minimum":1}},"required":["latitude","longitude","radius"]},"CustomField":{"type":"object","description":"Represents a custom field with key-value pair for additional tag properties","properties":{"label":{"type":"string","description":"Label of the custom field","example":"Phone number","maxLength":50,"minLength":0},"value":{"type":"string","description":"Value of the custom field","example":"+46701234567","maxLength":255,"minLength":0}},"required":["label","value"]},"Period":{"type":"object","description":"Represents an operating period for a tag, defining when it is active","properties":{"from":{"type":"string","format":"date","description":"Start date of the period","example":"2022-01-01"},"to":{"type":"string","format":"date","description":"End date of the period","example":"2022-01-31"},"hours":{"type":"number","format":"float","description":"Number of hours for this period","example":8.0},"type":{"type":"string","description":"Type of period","enum":["PERIOD","DAYS","WEEKS"],"example":"DAYS"},"count":{"type":"number","format":"float","description":"Number of periods","example":1.0}},"required":["count","from","hours","type"]},"TagIntegration":{"type":"object","description":"Represents a tag with integration-specific properties","properties":{"name":{"type":"string","description":"Name of the tag","example":"Downtown Store","maxLength":255,"minLength":0},"code":{"type":"string","description":"Code identifier for the tag","example":"DT-001","maxLength":50,"minLength":0},"externalId":{"type":"string","description":"External identifier for integration purposes","example":"store-123","maxLength":60,"minLength":0},"information":{"type":"string","description":"Additional information about the tag","example":"Main downtown location with parking","maxLength":2000,"minLength":0},"uniqueScheduling":{"type":"boolean","description":"Indicates if this tag requires unique scheduling","example":true},"startDate":{"type":"string","format":"date","description":"Start date for tag validity","example":"2024-01-01"},"endDate":{"type":"string","format":"date","description":"End date for tag validity","example":"2024-12-31"},"periods":{"type":"array","description":"Operating periods for this tag","example":[{"from":"2022-01-01","to":"2022-01-31","hours":8.0,"type":"DAYS","count":1.0}],"items":{"$ref":"#/components/schemas/Period"}},"coordinates":{"type":"array","description":"Geographic coordinates associated with this tag","example":[{"latitude":59.334591,"longitude":18.06324,"name":"Stockholm Mall","radius":100}],"items":{"$ref":"#/components/schemas/Coordinate"}},"customFields":{"type":"array","description":"Custom fields for additional tag properties","example":[{"label":"phoneNumber","value":"+46123456789"}],"items":{"$ref":"#/components/schemas/CustomField"}},"categoryExternalId":{"type":"string","description":"External identifier of the category this tag belongs to","example":"LOC-001"},"unitExternalId":{"type":"string","description":"External identifier of the unit this tag is associated with","example":"UNIT-001"}},"required":["categoryExternalId","name","unitExternalId"]},"TagCategory_Default":{"type":"object","description":"Represents a category for grouping tags with common characteristics","properties":{"name":{"type":"string","description":"Name of the tag category","example":"Store Locations","maxLength":255,"minLength":0},"tagType":{"$ref":"#/components/schemas/TagType_Default","description":"Type of tags in this category","example":"PROJECT"},"color":{"type":"string","description":"Hexadecimal color code for visual representation","example":"#FF5733"},"externalId":{"type":"string","description":"External identifier for integration purposes","example":"LOC-001","maxLength":60,"minLength":0}},"required":["name","tagType"]},"TagType_Default":{"type":"string","description":"Enumeration of possible tag types","enum":["COST_CENTER","PROJECT","ACCOUNT","EXTENDED"]}}}}