Fermetures exceptionnelles

Une fermeture exceptionnelle est une période ponctuelle pendant laquelle un établissement est fermé, en complément de ses horaires d’ouverture habituels : jours fériés, événements privés, travaux ou fermeture imprévue, par exemple. Chaque fermeture appartient à un seul établissement et est délimitée par un instant de début et un instant de fin. Les fermetures exceptionnelles appartiennent à leur établissement parent. Le chemin complet est /v1/locations/{location_id}/special_closings, et chaque fermeture est accessible à l’adresse /v1/locations/{location_id}/special_closings/{special_closing_id}.

L’objet special_closing

{
  "id": "scl_3b9f2c7a1e8d40f6",
  "object": "special_closing",
  "location_id": "loc_8f2c91d4a7e34b10",
  "starts_at": "2026-12-24T22:00:00Z",
  "ends_at": "2026-12-26T06:00:00Z",
  "reason": "Christmas holidays",
  "created_at": "2026-05-29T10:15:00Z",
  "updated_at": "2026-05-29T10:15:00Z"
}

string

Identifiant opaque unique, préfixé par scl_. Traitez-le comme une chaîne sensible à la casse.

string

Toujours "special_closing".

string

L’établissement parent (loc_…) auquel cette fermeture s’applique.

string

Instant UTC au format ISO 8601 auquel la fermeture commence.

string

Instant UTC au format ISO 8601 auquel la fermeture prend fin.

string | null

Motif lisible de la fermeture (par exemple "Jour férié"). Ce motif donne au commis IA le contexte nécessaire pour expliquer la fermeture aux clients. Peut valoir null.

string

Horodatage UTC de création au format ISO 8601.

string

Horodatage UTC de dernière mise à jour au format ISO 8601.

Fuseaux horaires

starts_at et ends_at sont des instants UTC absolus : le Z final fait partie du contrat. Il ne s’agit pas d’heures locales. Pour présenter une fermeture à un exploitant de restaurant, convertissez chaque instant dans le timezone de l’établissement (un identifiant IANA tel que Europe/Zurich, disponible dans l’objet établissement).

Envoyez toujours starts_at et ends_at en UTC. Si vous recueillez une date et une heure locales auprès d’un utilisateur, convertissez-les en UTC avant d’appeler l’API, en tenant compte de l’heure d’été dans le fuseau de l’établissement. Une fermeture prévue pour couvrir « toute la journée du 25 décembre à Zurich » s’étend de 23:00 UTC le 24 décembre à 23:00 UTC le 25 décembre, et non de minuit à minuit UTC.

L’exemple ci-dessous convertit une plage horaire locale dans Europe/Zurich en instants UTC attendus par l’API.

// « Fermé toute la journée du 25 décembre 2026 » dans le fuseau local de l’établissement.
const timezone = "Europe/Zurich";

function toUtcInstant(localDateTime, tz) {
  // localDateTime est au format "YYYY-MM-DDTHH:mm" dans le fuseau cible.
  const target = new Date(`${localDateTime}:00`);
  const asUtc = new Date(target.toLocaleString("en-US", { timeZone: "UTC" }));
  const asTz = new Date(target.toLocaleString("en-US", { timeZone: tz }));
  const offsetMs = asUtc.getTime() - asTz.getTime();
  return new Date(target.getTime() + offsetMs).toISOString();
}

const startsAt = toUtcInstant("2026-12-25T00:00", timezone); // 2026-12-24T23:00:00.000Z
const endsAt = toUtcInstant("2026-12-26T00:00", timezone); // 2026-12-25T23:00:00.000Z

// Affiche un instant UTC enregistré à un opérateur dans le fuseau de l’établissement.
function renderLocal(utcInstant, tz) {
  return new Intl.DateTimeFormat("fr-CH", {
    timeZone: tz,
    dateStyle: "medium",
    timeStyle: "short",
  }).format(new Date(utcInstant));
}

renderLocal("2026-12-24T23:00:00Z", "Europe/Zurich"); // "25 déc. 2026, 00:00"

Lister les fermetures exceptionnelles

Renvoie une liste paginée des fermetures d’un établissement, triées par created_at.

Point de terminaison

GET /v1/locations/{location_id}/special_closings

Paramètres de requête

integer

défaut:"10"

Nombre de résultats par page, compris entre 1 et 100.

string

Curseur de la page suivante : l’id du dernier objet de la page précédente. Mutuellement exclusif avec ending_before.

string

Curseur de la page précédente : l’id du premier objet de la page actuelle. Mutuellement exclusif avec starting_after.

string

Renvoie les fermetures créées après cet horodatage ISO 8601.

string

Renvoie les fermetures créées avant cet horodatage ISO 8601.

string

Renvoie les fermetures mises à jour après cet horodatage ISO 8601.

string

Renvoie les fermetures mises à jour avant cet horodatage ISO 8601.

curl "https://server.chataigne.ai/v1/locations/loc_8f2c91d4a7e34b10/special_closings?limit=20" \
  -H "x-api-key: ch_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const locationId = "loc_8f2c91d4a7e34b10";
const res = await fetch(
  `https://server.chataigne.ai/v1/locations/${locationId}/special_closings?limit=20`,
  { headers: { "x-api-key": process.env.CHATAIGNE_API_KEY } }
);
const closings = await res.json();
console.log(closings.data);

Réponse

{
  "object": "list",
  "data": [
    {
      "id": "scl_3b9f2c7a1e8d40f6",
      "object": "special_closing",
      "location_id": "loc_8f2c91d4a7e34b10",
      "starts_at": "2026-12-24T22:00:00Z",
      "ends_at": "2026-12-26T06:00:00Z",
      "reason": "Christmas holidays",
      "created_at": "2026-05-29T10:15:00Z",
      "updated_at": "2026-05-29T10:15:00Z"
    }
  ],
  "has_more": false,
  "url": "/v1/locations/loc_8f2c91d4a7e34b10/special_closings"
}

Créer une fermeture exceptionnelle

Crée une fermeture pour un établissement. Comme ce POST crée une ressource, l’en-tête Idempotency-Key est obligatoire.

Point de terminaison

POST /v1/locations/{location_id}/special_closings

Paramètres du corps

string

requis

Instant UTC au format ISO 8601 auquel la fermeture commence.

string

requis

Instant UTC au format ISO 8601 auquel la fermeture prend fin.

string

Motif lisible facultatif de la fermeture. Il est transmis au commis IA afin qu’il puisse expliquer la fermeture aux clients. Omettez-le ou envoyez null pour ne pas le définir.

curl https://server.chataigne.ai/v1/locations/loc_8f2c91d4a7e34b10/special_closings \
  -H "x-api-key: ch_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 6f1d3b8a-2c47-4e90-9a1b-0d2f7c5e1234" \
  -H "Content-Type: application/json" \
  -d '{
    "starts_at": "2026-12-24T22:00:00Z",
    "ends_at": "2026-12-26T06:00:00Z",
    "reason": "Christmas holidays"
  }'

import { randomUUID } from "node:crypto";

const locationId = "loc_8f2c91d4a7e34b10";
const res = await fetch(
  `https://server.chataigne.ai/v1/locations/${locationId}/special_closings`,
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.CHATAIGNE_API_KEY,
      "Idempotency-Key": randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      starts_at: "2026-12-24T22:00:00Z",
      ends_at: "2026-12-26T06:00:00Z",
      reason: "Christmas holidays",
    }),
  }
);
const closing = await res.json();

Réponse

{
  "id": "scl_3b9f2c7a1e8d40f6",
  "object": "special_closing",
  "location_id": "loc_8f2c91d4a7e34b10",
  "starts_at": "2026-12-24T22:00:00Z",
  "ends_at": "2026-12-26T06:00:00Z",
  "reason": "Christmas holidays",
  "created_at": "2026-05-29T10:15:00Z",
  "updated_at": "2026-05-29T10:15:00Z"
}

Rejouer la même Idempotency-Key avec le même corps renvoie la fermeture d’origine, avec l’en-tête Idempotent-Replayed: true. Réutiliser la clé avec un corps différent renvoie 409 idempotency_error, tandis qu’une requête identique exécutée simultanément renvoie 409 conflict_error. Les clés sont conservées pendant 24 heures. Consultez Idempotence.

Récupérer une fermeture exceptionnelle

Récupère une fermeture à partir de son identifiant.

Point de terminaison

GET /v1/locations/{location_id}/special_closings/{special_closing_id}

curl https://server.chataigne.ai/v1/locations/loc_8f2c91d4a7e34b10/special_closings/scl_3b9f2c7a1e8d40f6 \
  -H "x-api-key: ch_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const locationId = "loc_8f2c91d4a7e34b10";
const closingId = "scl_3b9f2c7a1e8d40f6";
const res = await fetch(
  `https://server.chataigne.ai/v1/locations/${locationId}/special_closings/${closingId}`,
  { headers: { "x-api-key": process.env.CHATAIGNE_API_KEY } }
);
const closing = await res.json();

Réponse

{
  "id": "scl_3b9f2c7a1e8d40f6",
  "object": "special_closing",
  "location_id": "loc_8f2c91d4a7e34b10",
  "starts_at": "2026-12-24T22:00:00Z",
  "ends_at": "2026-12-26T06:00:00Z",
  "reason": "Christmas holidays",
  "created_at": "2026-05-29T10:15:00Z",
  "updated_at": "2026-05-29T10:15:00Z"
}

Une requête portant sur un identifiant qui n’existe pas pour l’établissement renvoie 404 not_found_error.

Mettre à jour une fermeture exceptionnelle

Met à jour un ou plusieurs champs d’une fermeture. Seuls les champs envoyés sont modifiés ; les champs omis conservent leur valeur actuelle.

Point de terminaison

PATCH /v1/locations/{location_id}/special_closings/{special_closing_id}

Paramètres du corps

string

Nouvel instant de début, au format ISO 8601 UTC.

string

Nouvel instant de fin, au format ISO 8601 UTC.

string | null

Nouveau motif transmis au commis IA afin qu’il puisse expliquer la fermeture aux clients. Envoyez null pour effacer un motif existant.

curl -X PATCH https://server.chataigne.ai/v1/locations/loc_8f2c91d4a7e34b10/special_closings/scl_3b9f2c7a1e8d40f6 \
  -H "x-api-key: ch_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "ends_at": "2026-12-27T06:00:00Z",
    "reason": "Christmas & Boxing Day"
  }'

const locationId = "loc_8f2c91d4a7e34b10";
const closingId = "scl_3b9f2c7a1e8d40f6";
const res = await fetch(
  `https://server.chataigne.ai/v1/locations/${locationId}/special_closings/${closingId}`,
  {
    method: "PATCH",
    headers: {
      "x-api-key": process.env.CHATAIGNE_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ends_at: "2026-12-27T06:00:00Z",
      reason: "Christmas & Boxing Day",
    }),
  }
);
const closing = await res.json();

Réponse

{
  "id": "scl_3b9f2c7a1e8d40f6",
  "object": "special_closing",
  "location_id": "loc_8f2c91d4a7e34b10",
  "starts_at": "2026-12-24T22:00:00Z",
  "ends_at": "2026-12-27T06:00:00Z",
  "reason": "Christmas & Boxing Day",
  "created_at": "2026-05-29T10:15:00Z",
  "updated_at": "2026-05-29T11:42:08Z"
}

Supprimer une fermeture exceptionnelle

Supprime définitivement une fermeture. L’établissement revient à ses horaires d’ouverture habituels pendant cette période.

Point de terminaison

DELETE /v1/locations/{location_id}/special_closings/{special_closing_id}

curl -X DELETE https://server.chataigne.ai/v1/locations/loc_8f2c91d4a7e34b10/special_closings/scl_3b9f2c7a1e8d40f6 \
  -H "x-api-key: ch_org_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const locationId = "loc_8f2c91d4a7e34b10";
const closingId = "scl_3b9f2c7a1e8d40f6";
const res = await fetch(
  `https://server.chataigne.ai/v1/locations/${locationId}/special_closings/${closingId}`,
  {
    method: "DELETE",
    headers: { "x-api-key": process.env.CHATAIGNE_API_KEY },
  }
);

Supprimer une fermeture qui n’existe pas renvoie 404 not_found_error.

Erreurs

Les points de terminaison des fermetures exceptionnelles utilisent le modèle d’erreur standard. Cas les plus courants :

Statut HTTP	`error.type`	Cas
`400`	`invalid_request_error`	Un horodatage est manquant ou n’est pas conforme au format ISO 8601, ou un paramètre est mal formé.
`401`	`authentication_error`	Aucune clé API n’a été fournie.
`403`	`authorization_error`	Le périmètre ou les permissions de la clé n’autorisent pas cette action.
`404`	`not_found_error`	L’identifiant de l’établissement ou de la fermeture n’existe pas ou n’est pas accessible avec votre clé.
`409`	`idempotency_error`	L’`Idempotency-Key` a été réutilisée avec un corps différent.
`409`	`conflict_error`	Une requête simultanée en cours a utilisé la même `Idempotency-Key`.
`429`	`rate_limit_error`	La limite de débit par clé a été dépassée ; réessayez après `Retry-After`.

Exemple d’erreur

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "ends_at must be a valid ISO 8601 UTC timestamp.",
    "param": "ends_at",
    "request_id": "req_2y8Fk1Zx0Qm7"
  }
}

Étapes suivantes

Horaires d’ouverture

Les fermetures exceptionnelles s’ajoutent au planning hebdomadaire habituel de livraison et de retrait d’un établissement.

Établissements

Consultez le timezone d’un établissement pour afficher starts_at et ends_at en heure locale.

Idempotence

La création d’une fermeture nécessite une Idempotency-Key. Découvrez le fonctionnement des nouvelles tentatives sécurisées.

​L’objet special_closing

​Fuseaux horaires

​Lister les fermetures exceptionnelles

​Paramètres de requête

​Créer une fermeture exceptionnelle

​Paramètres du corps

​Récupérer une fermeture exceptionnelle

​Mettre à jour une fermeture exceptionnelle

​Paramètres du corps

​Supprimer une fermeture exceptionnelle

​Erreurs

​Étapes suivantes

Horaires d’ouverture

Établissements

Idempotence

L’objet special_closing

Fuseaux horaires

Lister les fermetures exceptionnelles

Paramètres de requête

Créer une fermeture exceptionnelle

Paramètres du corps

Récupérer une fermeture exceptionnelle

Mettre à jour une fermeture exceptionnelle

Paramètres du corps

Supprimer une fermeture exceptionnelle

Erreurs

Étapes suivantes