Skip to content

Designed
Get general chapter

Request

Returns typed general information: version info, product identity (derived from the trade item), retailer and supplier companies and contacts, custom fields, and references to the chapter's requirements, documents and questionnaires.

Security
oauth2(Required scopes: t1_api)
Path
specificationIdstring, (uuid)required

The unique identifier of the specification

curl -i -X GET \
  'https://apis.traceone.com/spec/v2/food/specifications/{specificationId}/general-chapter' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Returns the general chapter

Headers
ETagstring

Version tag of the chapter as stored. Pass it back in If-Match on the next write for optimistic concurrency.

Bodyapplication/json
versionInfoobject or null(FoodVersionInfo)

Version section of the food general chapter. A field the template hides is null. reasonForThisVersion receives the create request's reasonForThisVersion.

productobject(FoodProduct)

Product identity for food specifications (READ side). Packaging specs have no direct product link. Every field here is derived from the trade item the specification points at and is refused in a write payload: change the specification's tradeItemId instead.

retailerobject(SpecificationCompany)

Company and contacts for a specification party (retailer or supplier). No name enrichment — IDs only. Resolve via the CUMD public API.

supplierobject(SpecificationCompany)

Company and contacts for a specification party (retailer or supplier). No name enrichment — IDs only. Resolve via the CUMD public API.

customFieldsArray of objects or null(CustomFields)

Custom field VALUES, one entry per custom component of the chapter. The template places retailer-defined custom components in the chapter; each component is a group of fields with its own published JSON Schema, listed by GET /v2/public/templates/{templateId}/chapters/ {chapterType}/custom-fields-schema. A published component never changes, and the same componentId is valid in every template that uses it.

WRITE RULES

  • An entry replaces the values of its component: a field the values object does not carry is cleared. A component the array does not carry keeps what it holds. null or absent = not supplied.
  • An entry is addressed by componentId. sectionCode is needed only when the component appears in more than one section of the chapter; without it, that is a 422 naming the missing field, customFields[i].sectionCode.
  • A componentId (or componentId + sectionCode) that is not in the chapter, or the same one twice: 422 naming the entry.
  • To change one field, read the entry, change it and send the whole values object back, with If-Match: the ETag of the chapter read. Without it, an edit made in between by the counterpart company is overwritten.
  • values is validated against the component's JSON Schema (types, formats, bounds, reference-list items, files owned by your company). A refusal is a 422 naming the field, customFields[i].values.<field>.
  • Mandatory fields (CustomFieldsSchema mandatoryFields) are not checked on write; they are checked when the section is validated.
  • Who may write follows the section that holds the component: in a custom section either party may write; in a standard section the section's own rule applies (e.g. retailer or supplier sections of the general chapter: owner company only). A read returns one entry per custom component of the chapter, with sectionCode always set.
requirementsArray of objects or null(Requirement)
documentsobject(DocumentSection)
questionnairesArray of objects or null(Questionnaire)

Questionnaire instances attached to this chapter (references; content at GET /questionnaires/{questionnaireId}).

Response
{
  "versionInfo": {
    "reasonForThisVersion": "string",
    "impactOnLabeling": true,
    "firstBatchNumber": "string",
    "lastBatchNumber": "string",
    "firstProductionDate": "2019-08-24",
    "lastProductionDate": "2019-08-24"
  },
  "product": {
    "tradeItemId": "ca25da54-cf50-4957-b1f6-2a6f444fe8a3",
    "gtin": "3270190207924",
    "productBrandId": "e8d93bd7-a73f-4b05-adb5-d90661d77d1d",
    "productCategoryIds": [ … ],
    "netContents": [ … ]
  },
  "retailer": {
    "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
    "subsidiaryCompanyId": "b1d3008c-dc97-4956-9b01-8e03b17f3f96",
    "signatoryContacts": [ … ],
    "additionalContacts": [ … ],
    "validations": [ … ]
  },
  "supplier": {
    "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
    "subsidiaryCompanyId": "b1d3008c-dc97-4956-9b01-8e03b17f3f96",
    "signatoryContacts": [ … ],
    "additionalContacts": [ … ],
    "validations": [ … ]
  },
  "customFields": [
    { … }
  ],
  "requirements": [
    { … }
  ],
  "documents": {
    "files": [ … ]
  },
  "questionnaires": [
    { … }
  ]
}