Skip to content

Designed
Replace general chapter

Request

Writes the writable part of the general chapter (PackagingGeneralChapterWrite). The general chapter belongs to this specification only (never a library chapter).

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

The unique identifier of the specification

Headers
If-Matchstring

Optional optimistic concurrency: the ETag returned by the chapter GET. When provided, the write is rejected with 412 if the specification changed since the chapter was read (anything on it: another chapter, a contact, a share), or, for a library chapter, if the chapter changed. Guards against concurrent writers within the same owner company (cross-company overwrite is already impossible — the chapter is the ownership boundary).

Bodyapplication/jsonrequired
versionInfoobject or null(PackagingVersionWrite)

Section packaging_version. Either party may write it. Inside a supplied section, null clears a field.

retailerobject or null(SpecificationPartyWrite)

The writable part of a party's section of the general chapter. null or absent means the section is not supplied: the chapter keeps what it holds. The retailer section is written by the specification owner only: a supplier caller sending a value in it gets a 422 naming the field. The supplier section is written by either party.

supplierobject or null(SpecificationPartyWrite)

The writable part of a party's section of the general chapter. null or absent means the section is not supplied: the chapter keeps what it holds. The retailer section is written by the specification owner only: a supplier caller sending a value in it gets a 422 naming the field. The supplier section is written by either party.

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.
curl -i -X PUT \
  'https://apis.traceone.com/spec/v2/packaging/specifications/{specificationId}/general-chapter' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: string' \
  -d '{
    "versionInfo": {
      "reasonForThisVersion": "string",
      "impactOnLabeling": true
    },
    "retailer": {
      "subsidiaryCompanyId": "b1d3008c-dc97-4956-9b01-8e03b17f3f96",
      "additionalContacts": [
        {
          "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b"
        }
      ]
    },
    "supplier": {
      "subsidiaryCompanyId": "b1d3008c-dc97-4956-9b01-8e03b17f3f96",
      "additionalContacts": [
        {
          "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b"
        }
      ]
    },
    "customFields": [
      {
        "componentId": "616ccd92-d666-4180-8349-8d125b269fac",
        "sectionCode": "string",
        "values": {}
      }
    ]
  }'

Responses

The chapter was written. Read it back, with its new ETag, from the chapter GET.

Response
No content