Skip to content

Designed
Get custom chapter

Request

Returns a retailer-defined custom chapter of this specification. The chapterType is the retailer-defined type code, communicated with the template at onboarding.

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

The unique identifier of the specification

chapterTypestringrequired

Retailer-defined custom chapter type code (communicated with the template at onboarding). Standard chapters have their own routes; library chapter types are rejected (they cannot be customized).

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

Responses

Returns the custom 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
chapterTypestringread-only

Retailer-defined custom chapter type code

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)
Response
{
  "chapterType": "string",
  "customFields": [
    { … }
  ],
  "requirements": [
    { … }
  ],
  "documents": {
    "files": [ … ]
  }
}