Conteneurs

Un conteneur contient un seul message (single) ou une galerie de messages (gallery). Son mode est fixé à sa création : l’API refuse de le modifier ensuite, et un widget affiche toujours le mode avec lequel le conteneur a été créé.

API v3.1 URL de base https://<client-api-host>/api/v3.1

Cycle de vie

Créer un conteneur, le relire, les lister et corriger les champs qui peuvent changer.

Méthode POST `/containers`

Scope containers:write

Crée un conteneur avec son mode, ses notifications et ses contacts. Renvoie la clé d’édition une seule fois.

Un corps de requête qui contient un champ inconnu est refusé avec 400 DATA_INVALID. Le mode est obligatoire : la v3.1 n’a pas de valeur par défaut.

Paramètres

Nom	Emplacement	Type	Requis	Description
`crid`	Corps	`string`	Requis	Votre référence pour le conteneur, de 1 à 128 caractères : lettres, chiffres, point, tiret bas, deux-points et tiret, en commençant par une lettre ou un chiffre.
`mode`	Corps	`"single" \| "gallery"`	Requis	Fixé pour toute la vie du conteneur.
`language`	Corps	`string`	Facultatif	Identifiant d’une langue activée sur la plateforme.
`codeGroup`	Corps	`string`	Facultatif	Identifiant public d’un groupe de codes de la plateforme. Une valeur inconnue est ignorée.
`sender`	Corps	`object`	Facultatif	firstName et lastName (50 caractères au plus chacun), email (adresse valide, 254 caractères au plus).
`recipient`	Corps	`object`	Facultatif	firstName, lastName, email et phone au format E.164. Un champ channel est refusé : le SMS n’entre pas dans le périmètre de la v3.1.
`gallery`	Corps	`object`	Facultatif	title, 80 caractères au plus. Valable uniquement quand mode vaut gallery.
`notifications`	Corps	`object`	Facultatif	Clés organizer, contributors et recipient. Voir le groupe de champs Notifications ci-dessous.
`additionalData`	Corps	`object`	Facultatif	Jusqu’à 20 clés composées de lettres, de chiffres et de tirets bas, avec des valeurs string (500 caractères au plus), number ou boolean. Une clé qui contient mail ou phone est refusée.

Réponse

json 201 Created (200 on a replay)

{
  "crid": "AUB-20481",
  "urid": "7kq2mx9k3p",
  "mode": "gallery",
  "state": "recording_open",
  "editKey": "<uuid>",
  "notifications": {…},
  "links": {"recordingUrl": "…", "previewUrl": "…"},
  "platformId": "…",
  "createdAt": "…"
}

Remarques

editKey est renvoyée à la création et lors d’un rejeu : une réponse réseau perdue ne la fait donc pas perdre. Elle n’est jamais renvoyée par une lecture.
Rejeu : un crid qui existe déjà sur la plateforme, créé par la v3.1, renvoie 200 avec le conteneur existant. Le mode, les notifications et les contacts du corps sont ignorés.
Un crid qui existe mais a été créé par une autre API renvoie 409 CRID_IN_USE.
Les contacts sont conservés pour l’e-mail et la carte, et ne sont jamais renvoyés par les lectures de la v3.1.

Méthode GET `/containers`

Scope containers:read

Liste les conteneurs créés via la v3.1 sur la plateforme de la clé, du plus récent au plus ancien.

Paramètres

Nom	Emplacement	Type	Requis	Description
`limit`	Paramètre de requête	`integer`	Facultatif	De 1 à 100. 20 par défaut.
`skip`	Paramètre de requête	`integer`	Facultatif	Décalage, 0 ou plus.
`order`	Paramètre de requête	`"createdAt" \| "-createdAt"`	Facultatif	Ordre de tri. -createdAt par défaut.

Réponse

json 200 OK

{"items": [ … ], "total": 42, "limit": 20, "skip": 0}

Méthode GET `/containers/{crid}`

Scope containers:read

Lit un conteneur : son mode, son état, ses notifications et les compteurs de sa galerie.

Paramètres

Nom	Emplacement	Type	Requis	Description
`crid`	Chemin	`string`	Requis	Votre référence pour le conteneur.

Réponse

json 200 OK

{
  "crid": "AUB-20481",
  "urid": "7kq2mx9k3p",
  "mode": "gallery",
  "state": "recording_open",
  "shipped": false,
  "shippedAt": null,
  "notifiedAt": null,
  "notifications": {…},
  "gallery": {"title": "…", "messageCount": 5, "listedCount": 4, "closed": false},
  "links": {…},
  "createdAt": "…",
  "updatedAt": "…"
}

Remarques

gallery vaut null pour un conteneur single.
state vaut recording_open tant que le conteneur accepte un message (un conteneur single sans message principal, ou une galerie qui n’est pas fermée), et recording_closed sinon.
listedCount compte les messages listés publiquement, par opposition aux messages retenus ou en attente.

Méthode PATCH `/containers/{crid}`

Scope containers:write

Corrige les champs qui peuvent changer après la création. L’envoi de mode, ou de gallery.mode, est refusé.

Mise à jour partielle. Un corps vide est refusé avec 400 DATA_INVALID. Un champ qui ne figure pas dans le corps de création est refusé.

Paramètres

Nom	Emplacement	Type	Requis	Description
`crid`	Chemin	`string`	Requis	Référence actuelle du conteneur.
`newcrid`	Corps	`string`	Facultatif	Une nouvelle référence. Les jetons déjà émis restent valables : ils portent l’identifiant du conteneur, pas le crid.
`shipmentCarrier`	Corps	`string`	Facultatif	Un transporteur de la liste autorisée par la plateforme.
`shipmentCode`	Corps	`string`	Facultatif	Numéro de suivi, 100 caractères au plus.
`language`	Corps	`string`	Facultatif	Identifiant d’une langue activée sur la plateforme.
`sender`	Corps	`object`	Facultatif	Mêmes règles qu’à la création.
`recipient`	Corps	`object`	Facultatif	Mêmes règles qu’à la création.
`notifications`	Corps	`object`	Facultatif	Fusionné clé par clé avec les réglages enregistrés.
`gallery`	Corps	`object`	Facultatif	title uniquement, et seulement pour une galerie.

Réponse

json 200 OK

The container, in the same shape as the read.

Remarques

Un newcrid déjà utilisé sur la plateforme renvoie 409 CRID_IN_USE.

Actions

Des appels qui agissent sur un conteneur sans changer son mode ni ses messages.

Méthode POST `/containers/{crid}/notify`

Scope containers:notify

Demande à Livstick de prévenir le destinataire qu’un message est prêt.

Paramètres

Nom	Emplacement	Type	Requis	Description
`crid`	Chemin	`string`	Requis	Votre référence pour le conteneur.
`recipient`	Corps	`object`	Facultatif	firstName et email facultatifs, enregistrés avant la mise en file d’attente de la notification.

Réponse

json 200 OK

{"result": "ok", "notifiedAt": "…", "emailQueued": true}

Remarques

Un conteneur single doit avoir un message principal listé, et une galerie au moins un message listé. Sinon, l’appel renvoie 409 MESSAGE_MISSING.
L’envoi d’un e-mail dépend du réglage de notification du destinataire. Avec la valeur client, Livstick n’envoie pas l’e-mail et emailQueued vaut false.
Deux appels dans la même minute n’envoient qu’un seul e-mail.

Méthode POST `/containers/{crid}/unlock`

Scope containers:unlock

Marque le conteneur comme expédié. Cela ne change pas la visibilité des messages.

Paramètres

Nom	Emplacement	Type	Requis	Description
`crid`	Chemin	`string`	Requis	Votre référence pour le conteneur.

Réponse

json 200 OK

{"result": "ok", "shipped": true, "shippedAt": "…"}

Remarques

Les messages sont publiés dès qu’ils sont encodés. Leur visibilité ne dépend pas de l’expédition.

Méthode GET `/containers/{crid}/qrcode`

Scope containers:qrcode

QR code PNG qui renvoie vers la page d’enregistrement du conteneur.

Paramètres

Nom	Emplacement	Type	Requis	Description
`crid`	Chemin	`string`	Requis	Votre référence pour le conteneur.
`size`	Paramètre de requête	`integer`	Facultatif	Largeur en pixels, de 64 à 1024. 256 par défaut.

Réponse

json 200 OK

image/png

Méthode GET `/containers/{crid}/card`

Scope containers:card

Carte PDF imprimable avec le QR code et l’identifiant du conteneur.

Paramètres

Nom	Emplacement	Type	Requis	Description
`crid`	Chemin	`string`	Requis	Votre référence pour le conteneur.

Réponse

json 200 OK

application/pdf

Remarques

Renvoie 400 NO_PDF_TEMPLATE quand la plateforme n’a pas de modèle PDF, et 400 NO_LANGUAGE quand aucune langue ne peut être déterminée.
Renvoie 503 CARD_RENDERER_UNAVAILABLE ou 502 CARD_RENDERER_FAILED quand le rendu échoue.

Notifications

Réglées par public. Une clé non envoyée garde la valeur livstick. Le réglage décide de qui envoie l’e-mail ; il n’a aucun effet sur les webhooks.

Nom	Type	Par défaut	Description
`notifications.organizer`	`string`	`livstick`	Qui envoie les e-mails à l’organisateur d’une galerie. Valeurs `livstick` `client` `none`
`notifications.contributors`	`string`	`livstick`	Qui envoie les e-mails aux contributeurs d’une galerie. Valeurs `livstick` `client` `none`
`notifications.recipient`	`string`	`livstick`	Qui envoie l’e-mail au destinataire. client signifie que Livstick n’envoie rien et que votre système prévient le destinataire, par exemple à partir du webhook message.ready. Les webhooks sont envoyés quel que soit le réglage. Valeurs `livstick` `client` `none`

États

Le champ state d’un conteneur.

Nom	Type	Par défaut	Description
`state`	`string`		Le conteneur accepte un message. Valeurs `recording_open` `recording_closed`

Cycle de vie

Méthode POST /containers

Paramètres

Réponse

Remarques

Méthode GET /containers

Paramètres

Réponse

Méthode GET /containers/{crid}

Paramètres

Réponse

Remarques

Méthode PATCH /containers/{crid}

Paramètres

Réponse

Remarques

Actions

Méthode POST /containers/{crid}/notify

Paramètres

Réponse

Remarques

Méthode POST /containers/{crid}/unlock

Paramètres

Réponse

Remarques

Méthode GET /containers/{crid}/qrcode

Paramètres

Réponse

Méthode GET /containers/{crid}/card

Paramètres

Réponse

Remarques

Notifications

États

Méthode POST `/containers`

Méthode GET `/containers`

Méthode GET `/containers/{crid}`

Méthode PATCH `/containers/{crid}`

Méthode POST `/containers/{crid}/notify`

Méthode POST `/containers/{crid}/unlock`

Méthode GET `/containers/{crid}/qrcode`

Méthode GET `/containers/{crid}/card`