Create or fetch a container

Méthode POST https://<client-api-host>/api/v3.1/containers

Create the container of an order or a savings pot, identified by your reference (crid). The response carries the recording link and the editKey of the first message. Replaying the same crid returns the existing container with 200 and ignores mode, gallery, notifications and the contacts of the body. A crid that belongs to a container created through /api/v3 answers 409 CRID_IN_USE.

Autorisation

Scope requis containers:write

Use Authorization: Bearer liv_<prefix>_<secret>. The key must belong to a platform served by the V3 pipeline; otherwise every route answers 403 PLATFORM_NOT_V3.

Corps de la requête

Requis application/json Schéma V31CreateContainerRequest

Nom	Type	Requis	Description
`crid`	`string`	Requis	Contraintes pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
`mode`	`V31ContainerMode`	Requis	`single` holds one message (gift message); `gallery` accepts several (savings pot). Required at creation and immutable afterwards. Valeurs `single` `gallery`
`language`	`string`	Facultatif	`uid` of a platform language.
`codeGroup`	`string`	Facultatif	`publicId` of a code group of the platform; ignored when unknown.
`sender`	`V31Sender`	Facultatif
`recipient`	`V31Recipient`	Facultatif
`gallery`	`V31GalleryInput`	Facultatif
`notifications`	`V31Notifications`	Facultatif
`additionalData`	`object`	Facultatif	At most 20 keys matching `^[A-Za-z0-9_]{1,40}$`; values are strings (500 characters at most), numbers or booleans. Key names containing `mail` or `phone` are refused.

Réponses

200 application/json Schéma V31CreateContainerResponse

Container already existed; returned unchanged.

201 application/json Schéma V31CreateContainerResponse

Container created.

400 application/json Schéma V31ErrorEnvelope

Invalid payload, unknown field or invalid value.

json 400

{
  "error": {
    "code": "DATA_INVALID",
    "message": "Invalid field crid"
  }
}

401 application/json Schéma V31ErrorEnvelope

Authentication failed or missing bearer token.

json 401

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key"
  }
}

403 application/json Schéma V31ErrorEnvelope

Authenticated but not allowed: missing scope (FORBIDDEN), invalid platform constraints (INVALID_PLATFORM_CONSTRAINTS) or a platform not served by API v3.1 (PLATFORM_NOT_V3).

json 403

{
  "error": {
    "code": "PLATFORM_NOT_V3",
    "message": "Platform is not served by API v3.1"
  }
}

409 application/json Schéma V31ErrorEnvelope

The request conflicts with the state of the container or message: CRID_IN_USE, MODE_MISMATCH, GALLERY_CLOSED, GALLERY_NOT_EMPTY, MESSAGE_REJECTED, MESSAGE_MISSING.

json 409

{
  "error": {
    "code": "GALLERY_CLOSED",
    "message": "Gallery is closed"
  }
}

429 application/json Schéma V31ErrorEnvelope

Rate limit exceeded.

json 429

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests"
  }
}

500 application/json Schéma V31ErrorEnvelope

Unexpected server error.

json 500

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error"
  }
}