Aller au contenu
Livstick Développeurs
v3 Demander un accès

Conteneurs

Le conteneur est l’objet auquel se rattachent toutes les autres ressources v3. Ces dix opérations couvrent tout son cycle de vie — créer, lister, lire, modifier, résoudre une URL, rediriger — ainsi que les quatre appels qui agissent sur un conteneur sans changer son état : notify, unlock et les deux fichiers générés.

API v3 — Actuelle URL de base https://client-api.v5.livstick.com/api/v3 Spécification OpenAPI

Cycle de vie

Créer, lister, lire, modifier et résoudre un conteneur — les appels qu’une intégration type émet le plus souvent.

Méthode GET /containers

Scope containers:read

Lister les conteneurs de la plateforme authentifiée, du plus récent au plus ancien par défaut.

Paramètres

Nom Emplacement Type Requis Description
limit Paramètre de requête integer Facultatif Nombre maximal d’éléments à renvoyer. 50 par défaut, 1 au minimum, 200 au maximum.
skip Paramètre de requête integer Facultatif Nombre d’éléments à ignorer, pour la pagination. 0 par défaut.
order Paramètre de requête string Facultatif Ordre de tri appliqué à la liste. -createdAt par défaut (le plus récent d’abord).

Réponse

json 200 OK 
{
  "items": [
    {
      "crid": "order-48210",
      "urid": "5f3e9c2b8a1d4f60",
      "state": "recording_open",
      "mode": "single"
    }
  ],
  "total": 1,
  "limit": 50,
  "skip": 0
}

Méthode POST /containers

Scope containers:write

Créer un conteneur, ou récupérer le conteneur existant si le crid est déjà pris.

Seul crid est requis. sender, recipient, language, codeGroup, mode et additionalData sont tous facultatifs. Un champ email de premier niveau est également accepté, comme alias obsolète de sender.email.

Paramètres

Nom Emplacement Type Requis Description
crid Corps string Requis Votre propre référence pour le conteneur. Réutiliser un crid existant ne crée pas de second conteneur.
sender Corps object Facultatif firstName, lastName, email.
recipient Corps object Facultatif firstName, lastName, email, phone, channel.
language Corps string Facultatif Langue appliquée aux interfaces présentées au destinataire, générées pour ce conteneur.
codeGroup Corps string Facultatif Groupe de codes dans lequel le conteneur est créé.
mode Corps string Facultatif single ou gallery. single par défaut. Ignoré si le conteneur existe déjà.
additionalData Corps object Facultatif Objet libre, conservé tel quel.
email Corps string Facultatif Alias obsolète de sender.email. Conservé uniquement pour la rétrocompatibilité.

Réponse

json 201 Created 
{
  "crid": "order-48210",
  "urid": "5f3e9c2b8a1d4f60",
  "state": "recording_open",
  "mode": "single",
  "editKey": "ek_9f2a1c7b3e4d5f60a1b2c3d4e5f60718",
  "links": {
    "recordingUrl": "https://client-api.v5.livstick.com/r/5f3e9c2b8a1d4f60",
    "previewUrl": "https://client-api.v5.livstick.com/r/preview/5f3e9c2b8a1d4f60"
  }
}

Remarques

  • editKey n’est renvoyé qu’à la création. Aucun endpoint ne permet de le récupérer ensuite — capturez-le et stockez-le dès la création du conteneur.
  • Si le crid existe déjà pour la plateforme, l’appel renvoie les liens actuels de ce conteneur, inchangés. Il ne modifie jamais un conteneur existant : relancer une requête échouée ou rejouer un webhook est donc sans risque par défaut.
  • Le choix du canal du destinataire est implicite, d’où cette précision : sans recipient.channel, l’e-mail est utilisé dès que recipient.email est présent, même si un numéro de téléphone est aussi fourni. Un destinataire qui n’a qu’un numéro de téléphone doit définir explicitement channel: "sms". phone suit le format E.164 (^\+[1-9][0-9]{7,14}$).

Méthode GET /containers/{crid}

Scope containers:read

Lire l’état actuel d’un conteneur et de son message.

Paramètres

Nom Emplacement Type Requis Description
crid Chemin string Requis Le crid du conteneur.

Méthode PATCH /containers/{crid}

Scope containers:write

Corriger l’expédition, la langue ou les coordonnées d’un conteneur existant.

Paramètres

Nom Emplacement Type Requis Description
crid Chemin string Requis Le crid du conteneur.
shipmentCarrier Corps string Facultatif L’une des valeurs chronopost, ups, coursier, dhl, other.
shipmentCode Corps string Facultatif Code d’expédition ou de suivi propre au transporteur.
newcrid Corps string Facultatif Renomme le conteneur avec un nouveau crid.
language Corps string Facultatif Langue appliquée aux interfaces présentées au destinataire de ce conteneur.
sender Corps object Facultatif firstName, lastName, email.
recipient Corps object Facultatif firstName, lastName, email, phone, channel.

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

Scope containers:read

Résoudre les URL d’enregistrement et d’aperçu d’un conteneur.

Paramètres

Nom Emplacement Type Requis Description
crid Chemin string Requis Le crid du conteneur.

Réponse

json 200 OK 
{
  "recordingUrl": "https://client-api.v5.livstick.com/r/5f3e9c2b8a1d4f60",
  "previewUrl": "https://client-api.v5.livstick.com/r/preview/5f3e9c2b8a1d4f60"
}

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

Résoudre la destination d’un conteneur pour une redirection directe, sans authentification.

Paramètres

Nom Emplacement Type Requis Description
crid Chemin string Requis Le crid du conteneur.

Remarques

  • Aucun scope : cet appel ne prend pas de clé d’API. Il est strictement en lecture seule.
  • Un crid inconnu renvoie une 404.

Notify, unlock et fichiers générés

Quatre appels qui agissent directement sur un conteneur — déclencher l’envoi, ouvrir l’accès au destinataire ou produire un fichier — sans le faire avancer dans le cycle de vie ci-dessus.

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

Scope containers:notify

Déclencher l’envoi au destinataire.

Le corps de la requête est facultatif ; s’il est présent, il remplace les coordonnées enregistrées sur le conteneur, pour cette notification uniquement.

Paramètres

Nom Emplacement Type Requis Description
crid Chemin string Requis Le crid du conteneur.

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

Scope containers:unlock

Rendre le message enregistré accessible au destinataire.

Paramètres

Nom Emplacement Type Requis Description
crid Chemin string Requis Le crid du conteneur.

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

Scope containers:qrcode

Générer une image de QR code qui pointe vers le conteneur.

Paramètres

Nom Emplacement Type Requis Description
crid Chemin string Requis Le crid du conteneur.

Réponse

json 200 OK 
image/png

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

Scope containers:card

Générer une carte imprimable du conteneur, au format PDF.

Paramètres

Nom Emplacement Type Requis Description
crid Chemin string Requis Le crid du conteneur.

Réponse

json 200 OK 
application/pdf