API docs by Redocly

Ciklik API (1.0.0)

Download OpenAPI specification:

Bienvenue sur l'API Ciklik. Vous pouvez l'utiliser pour accéder aux ressources de votre compte, ou lancer des actions de base.

API Endpoints

The base endpoint is https://{environment}.ciklik.co/api/v3

Authentification

L'API s'authentifie par un jeton d'API Ciklik (jeton opaque, ce n'est pas un JWT) envoyé dans l'en-tête Authorization: Bearer.

Exemple :

curl --location 'https://{environment}.ciklik.co/api/v3/whoiam' --header 'Authorization: Bearer <Ciklik Token>'

Une requête sans jeton ou avec un jeton invalide reçoit 401 ; un jeton valide qui n'a pas accès à la ressource reçoit 403.

Request Limit

Le nombre de requêtes est limité à 200 par minute, compté par adresse IP (toutes les requêtes émises depuis la même adresse IP partagent ce quota). Si la limite est atteinte, la réponse http sera 429 Too Many Requests.

Filtres

Certains endpoints de l'API prennent en charge le filtrage des résultats sur un ensemble spécifié de champs. Chaque endpoint qui prend en charge le filtrage énumérera les champs qui peuvent être filtrés. Plusieurs champs peuvent être combinés en utilisant un caractère esperluette &

Exemple: /subscriptions?filter[activated]=1&filter[created_at_after]=2026-01-01&sort=-created_at

Un filtre ou un tri qui n'est pas dans la liste de l'endpoint est refusé avec une réponse 400 Bad Request (les endpoints qui valident eux-mêmes le paramètre sort répondent 422 pour un tri hors liste). Une valeur de filtre au mauvais format peut être refusée en 422.

Pagination

Les listes de résultats de l'API sont paginées. La pagination est fixe : 20 éléments par page, quelle que soit la valeur d'un éventuel paramètre per_page (ignoré). Vous pouvez obtenir les différentes pages avec la query string page, default value 1.

Le nombre total d'éléments dans une liste est disponible dans le champ meta.total.

Exemple: ?page=2

tenant

Opérations liées à l'entité "Website".

Récupérer les données de l'entité "Website"

Renvoie le site du jeton, enveloppé dans data. Le champ metadata contient toutes les clés de métadonnées du site, y compris celles qui n'ont pas été posées par l'API.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Mettre à jour les métadonnées d'un site web (WebsiteEntity)

Permet de mettre à jour les métadonnées d'un site web (WebsiteEntity) en modifiant ou ajoutant des clés/valeurs au champ "metadata". Les clés envoyées sont fusionnées avec les métadonnées existantes ; les clés absentes du corps sont conservées (elles ne sont pas effacées). La réponse renvoie le site complet, enveloppé dans data.

Authorizations:
bearerAuth
Request Body schema: application/json
required
object

Métadonnées personnalisées. Les valeurs doivent être des chaînes de caractères (max 5000 caractères) ou null. Seules les clés envoyées sont modifiées, les autres clés du site sont conservées. Les clés commençant par "ciklik_encrypted_" seront automatiquement encryptées.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Récupérer l'état d'installation de l'espace

Route destinée au back-office du module PrestaShop : elle renvoie l'état d'installation de l'espace du jeton (espace de test ou de production, étapes franchies, ce qui reste à faire et adresse de la page de suivi d'installation). Les libellés sont traduits dans la langue de la requête. L'état est lu tel qu'il a été relevé lors des dernières vérifications : aucune vérification n'est lancée pendant la requête.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

products

Opérations liées aux produits

Récupérer une liste de produits

Authorizations:
bearerAuth
query Parameters
filter[id]
integer
Example: filter[id]=1

Filtrer par ID du produit

filter[name]
string
Example: filter[name]=Produit exemple

Filtrer par nom du produit

filter[id_category]
integer
Example: filter[id_category]=5

Filtrer par ID de catégorie

filter[quantity]
integer
Example: filter[quantity]=10

Filtrer par quantité

filter[price]
number
Example: filter[price]=29.99

Filtrer par prix

filter[active]
boolean
Example: filter[active]=true

Filtrer par état d'activité

filter[slug]
string
Example: filter[slug]=produit-exemple

Filtrer par slug

filter[virtual_product]
boolean

Filtrer par produit virtuel (correspondance exacte)

filter[salable]
boolean

Filtrer par produit vendable

filter[gift_card]
boolean

Filtrer par carte cadeau

filter[gift_plan]
string

Filtrer par plan cadeau (UUID du plan, correspondance partielle)

filter[disable_seo]
boolean

Filtrer par désactivation SEO (correspondance exacte)

filter[ref]
string

Filtrer par référence

filter[composable]
boolean

Filtrer par composable

sort
string
Enum: "id" "name" "id_category" "quantity" "price" "active" "slug" "virtual_product" "salable" "gift_card" "gift_plan" "disable_seo" "ref" "composable" "created_at" "updated_at" "-id" "-name" "-id_category" "-quantity" "-price" "-active" "-slug" "-virtual_product" "-salable" "-gift_card" "-gift_plan" "-disable_seo" "-ref" "-composable" "-created_at" "-updated_at"

Trier les résultats (ex: -name pour un tri descendant). Tri par défaut : -id (plus récent en premier).

page
integer

Numéro de la page pour la pagination

per_page
integer

Ignoré. La pagination est fixe à 20 éléments par page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Créer ou mettre à jour un produit

Crée le produit, ou le met à jour s'il existe déjà. Le produit est cherché par external_id s'il est fourni, sinon par ref.

Deux formes de corps sont acceptées :

  • un produit seul (champs à la racine) : la réponse contient le produit dans data, avec le statut 201 s'il vient d'être créé et 200 s'il a été mis à jour ;
  • un lot {"products": [...]} : chaque élément suit le schéma d'un produit seul, la réponse contient la liste des produits dans data avec le statut 200.

À chaque enregistrement par cette route, le slug du produit est remplacé par un identifiant aléatoire (la valeur envoyée est ignorée) et meta_title reprend name. Si description est absente, un produit existant garde la sienne et un nouveau produit en reçoit une vide.

Authorizations:
bearerAuth
Request Body schema: application/json
required
One of
name
required
string <= 255 characters
ref
required
string <= 255 characters

Référence du produit (SKU).

external_id
string <= 255 characters

Identifiant du produit chez le vendeur connecté (identifiant de déclinaison pour PrestaShop).

slug
string <= 255 characters

Ignoré : un slug aléatoire est attribué à chaque enregistrement par POST /products.

description
string <= 255 characters

Facultative. Recopiée dans la description courte et la meta description du produit.

id_category
integer
quantity
integer
price
required
number
tax
required
number
Enum: 0 0.2 0.055 0.1 0.021 0.21 0.06
active
boolean
virtual_product
boolean
Array of objects

Responses

Request samples

Content type
application/json
Example
{
  • "ref": "REFABOPRODUIT",
  • "name": "Super nom produit",
  • "price": "17.50",
  • "description": "Petite description produit",
  • "tax": "0.2",
  • "frequencies": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Récupérer un produit par référence (SKU)

Authorizations:
bearerAuth
path Parameters
ref
required
string

Référence du produit (SKU)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Mettre à jour un produit par référence (SKU)

Met à jour le produit dont la référence est dans le chemin. Si external_id est fourni dans le corps, le produit est cherché par external_id et la référence du chemin est ignorée. name, ref et price sont obligatoires, même pour une mise à jour partielle.

Authorizations:
bearerAuth
path Parameters
ref
required
string

Référence du produit (SKU)

Request Body schema: application/json
required
name
required
string <= 255 characters
ref
required
string <= 255 characters

Référence du produit (SKU).

external_id
string <= 255 characters

Identifiant du produit chez le vendeur connecté (identifiant de déclinaison pour PrestaShop).

slug
string <= 255 characters

Slug du produit.

description
string <= 255 characters

Facultative.

id_category
integer
quantity
integer
price
required
number
tax
number
Enum: 0 0.2 0.055 0.1 0.021 0.21 0.06
active
boolean
virtual_product
boolean
Array of objects

Responses

Request samples

Content type
application/json
{
  • "ref": "REFABOPRODUIT",
  • "name": "Super nom produit",
  • "price": "17.50",
  • "description": "Petite description produit",
  • "tax": "0.2",
  • "frequencies": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

webhooks

Opérations liées aux webhooks

Lister les derniers webhooks envoyés

Renvoie les trois derniers webhooks envoyés pour cet évènement, du plus récent au plus ancien. Chaque élément est la charge utile (payload) envoyée. Un event_type absent ou inconnu répond 404.

Authorizations:
bearerAuth
query Parameters
event_type
required
string
Enum: "created_subscription" "updated_subscription" "deleted_subscription" "created_checkoutorder" "updated_checkoutorder" "created_checkouttransaction" "updated_checkouttransaction" "created_checkoutinvoice" "created_address" "updated_address" "created_shippingbox" "updated_shippingbox" "deleted_shippingbox" "created_user" "updated_user" "deleted_user" "created_optin" "updated_optin"

Nom de l'évènement à avoir

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Ajouter un webhook

Enregistre l'adresse appelée pour un type d'évènement. Il n'y a qu'une adresse par type d'évènement : un nouvel enregistrement remplace l'adresse précédente pour ce type, y compris celle posée par le module PrestaShop. La réponse renvoie le site, enveloppé dans data, avec la liste des webhooks actifs.

Authorizations:
bearerAuth
Request Body schema: application/json
required
event_type
required
string
Enum: "created_subscription" "updated_subscription" "deleted_subscription" "created_checkoutorder" "updated_checkoutorder" "created_checkouttransaction" "updated_checkouttransaction" "created_checkoutinvoice" "created_address" "updated_address" "created_shippingbox" "updated_shippingbox" "deleted_shippingbox" "created_user" "updated_user" "deleted_user" "created_optin" "updated_optin"
hook_url
required
string <uri>

URL http ou https publique, joignable depuis internet. Les adresses internes, privées ou réservées (localhost, 10.x, 192.168.x, 169.254.x...) sont refusées en 422.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Supprimer un webhook

Retire l'adresse enregistrée pour ce type d'évènement. La réponse renvoie le site, enveloppé dans data.

Authorizations:
bearerAuth
Request Body schema: application/json
required
event_type
required
string
Enum: "created_subscription" "updated_subscription" "deleted_subscription" "created_checkoutorder" "updated_checkoutorder" "created_checkouttransaction" "updated_checkouttransaction" "created_checkoutinvoice" "created_address" "updated_address" "created_shippingbox" "updated_shippingbox" "deleted_shippingbox" "created_user" "updated_user" "deleted_user" "created_optin" "updated_optin"

Responses

Request samples

Content type
application/json
{
  • "event_type": "created_subscription"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

subscriptions

Opérations liées aux abonnements

Obtenir les détails d'un abonnement

Authorizations:
bearerAuth
path Parameters
id
required
string

UUID de l'abonnement

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Mettre à jour un abonnement

Permet de mettre à jour un abonnement, le résilier, le mettre en pause pour 1, 2 ou 3 mois, ou le relancer. L'adresse (address_id), le transporteur (transporter) et la déclinaison (declinaison_id) sont contrôlés avant toute écriture : une référence inconnue ou qui n'appartient pas au site répond 404 et l'abonnement n'est pas modifié. Les autres refus (422 sur content ou next_billing, par exemple) peuvent intervenir après l'application des changements qui les précèdent : n'envoyez qu'un changement par requête si vous avez besoin d'un résultat tout ou rien. La réponse renvoie l'abonnement relu après les modifications, enveloppé dans data.

Authorizations:
bearerAuth
path Parameters
id
required
string

UUID de l'abonnement à mettre à jour

Request Body schema: application/json
required

Données à modifier sur l'abonnement

address_id
integer

ID d'une adresse du site à affecter à l'abonnement (404 si elle n'appartient pas au site).

declinaison_id
integer

ID d'une déclinaison du site à affecter à l'abonnement (404 si elle n'appartient pas au site).

transporter
integer

ID d'un transporteur du site (404 s'il n'appartient pas au site). Peut être accompagné d'un objet relay décrivant le point relais choisi.

object

Point relais, lu uniquement avec transporter.

voucher
boolean

Si vrai, applique l'offre de rétention (bon de réduction) proposée au désabonnement.

break
boolean

Accepté par la validation, sans effet (la mise en pause passe par pause et months).

months
number <float> [ 1 .. 3 ]

Nombre de mois pour mettre en pause l'abonnement (1, 2 ou 3 mois) (!= résiliation). Obligatoire si pause vaut true.

active
boolean

Indique si l'abonnement est actif.

notification
boolean
Default: true

Lors de la résiliation d'un abonnement, notifier ou non par email.

pause
boolean

Indique si l'abonnement doit être mis en pause.

next_billing
string <date>

Modifier la date du prochain paiement (date postérieure à aujourd'hui). Refusé en 422 si une commande du cycle est en attente avec une relance programmée.

Array of objects

nouveau contenu de l'abonnement, via external_id

interval
string

Nouvel intervalle de renouvellement (month, week ou day), lu seulement avec interval_count.

interval_count
integer

Nouveau nombre d'intervalles, lu seulement avec interval.

Array of objects

Produits complémentaires (PrestaShop) enregistrés dans l'empreinte du panier de l'abonnement.

object

Métadonnées personnalisées pour l'abonnement. Les valeurs doivent être des chaînes de caractères (max 5000 caractères). Les clés commençant par "ciklik_encrypted_" seront automatiquement encryptées.

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Supprimer un abonnement

Supprime un abonnement (soft delete). L'abonnement doit être inactif (active = false) et appartenir au tenant authentifié pour pouvoir être supprimé.

Authorizations:
bearerAuth
path Parameters
id
required
string

UUID de l'abonnement à supprimer.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Modifier la quantité d'un produit dans un abonnement

Met à jour la quantité d'un produit spécifique déjà rattaché à l'abonnement. Les produits avec personnalisation (customization hash) ne sont pas modifiables.

Authorizations:
bearerAuth
path Parameters
id
required
string

UUID de l'abonnement

external_id
required
string

Identifiant externe du produit (exodus_id)

Request Body schema: application/json
required
quantity
required
integer [ 1 .. 9999 ]

Nouvelle quantité du produit

Responses

Request samples

Content type
application/json
{
  • "quantity": 3
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retirer un produit d'un abonnement

Retire un produit spécifique de l'abonnement. Impossible de retirer le dernier produit. Les produits avec personnalisation ne sont pas modifiables.

Authorizations:
bearerAuth
path Parameters
id
required
string

UUID de l'abonnement

external_id
required
string

Identifiant externe du produit (exodus_id)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Ajouter un produit à un abonnement

Ajoute un produit à l'abonnement ou met à jour la quantité si le produit est déjà rattaché (upsert). Si le produit existe déjà en base (via son external_id), il est simplement rattaché ; les champs price et tax du corps sont alors ignorés. Si le produit n'existe pas, il est créé automatiquement : price devient obligatoire, tax défaut à 0 si absent. Les produits avec personnalisation (customization hash) ne sont pas acceptés. Retourne 201 pour un nouvel attachement (nouveau produit créé ou produit existant nouvellement rattaché), 200 pour une mise à jour de quantité sur un produit déjà rattaché.

Authorizations:
bearerAuth
path Parameters
id
required
string

UUID de l'abonnement

Request Body schema: application/json
required
external_id
required
string <= 255 characters

Identifiant externe du produit (exodus_id)

name
required
string [ 1 .. 255 ] characters

Nom du produit (utilisé lors de la création automatique, ignoré si le produit existe déjà)

quantity
integer [ 1 .. 9999 ]
Default: 1

Quantité du produit (défaut 1)

price
number >= 0

Prix HT du produit. Obligatoire si le produit n'existe pas encore en base et doit être créé. Ignoré si le produit existe déjà.

tax
number [ 0 .. 1 ]

Taux de TVA (ex. 0.2 pour 20%). Utilisé uniquement lors de la création ; défaut à 0 si absent. Ignoré si le produit existe déjà.

Responses

Request samples

Content type
application/json
{
  • "external_id": "12345",
  • "name": "Produit mensuel",
  • "quantity": 2,
  • "price": 19.99,
  • "tax": 0.2
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Récupérer une liste d'abonnement

Permet de récupérer une liste d'abonnements avec différents filtres et options de tri. Sans paramètre sort, la liste est triée par id croissant (plus ancien en premier).

Authorizations:
bearerAuth
query Parameters
filter[activated]
boolean

Filtre par abonnements activés.

filter[canceled]
boolean

Filtre par abonnements annulés.

filter[created_at_before]
string <date>
Example: filter[created_at_before]=2023-01-01

Filtre par date de création avant la date spécifiée.

filter[created_at_after]
string <date>
Example: filter[created_at_after]=2023-01-01

Filtre par date de création après la date spécifiée.

filter[updated_at_before]
string <date>
Example: filter[updated_at_before]=2023-01-01

Filtre par date de mise à jour avant la date spécifiée.

filter[updated_at_after]
string <date>
Example: filter[updated_at_after]=2023-01-01

Filtre par date de mise à jour après la date spécifiée.

filter[canceled_since_before]
string <date>
Example: filter[canceled_since_before]=2023-01-01

Filtre par date d'annulation avant la date spécifiée.

filter[canceled_since_after]
string <date>
Example: filter[canceled_since_after]=2023-01-01

Filtre par date d'annulation après la date spécifiée.

filter[expired]
boolean

Filtre par abonnements expirés.

filter[in_grace_period]
boolean

Filtre par abonnements en période de grâce.

filter[engaged_before]
string <date>
Example: filter[engaged_before]=2023-01-01

Filtre par date d'engagement avant la date spécifiée.

filter[engaged_after]
string <date>
Example: filter[engaged_after]=2023-01-01

Filtre par date d'engagement après la date spécifiée.

filter[next_billing_before]
string <date>
Example: filter[next_billing_before]=2023-01-01

Filtre par date de prochaine facturation avant la date spécifiée.

filter[next_billing_after]
string <date>
Example: filter[next_billing_after]=2023-01-01

Filtre par date de prochaine facturation après la date spécifiée.

filter[end_date_before]
string <date>
Example: filter[end_date_before]=2023-01-01

Filtre par date de fin d'abonnement avant la date spécifiée.

filter[end_date_after]
string <date>
Example: filter[end_date_after]=2023-01-01

Filtre par date de fin d'abonnement après la date spécifiée.

filter[subscriptions_by_email]
string <email>
Example: filter[subscriptions_by_email]=user@example.com

Filtre par adresse e-mail.

filter[plan_id]
string <= 255 characters
Example: filter[plan_id]=12

Filtre par ID (numérique) du plan, correspondance exacte.

filter[customer_id]
string <= 255 characters
Example: filter[customer_id]=550e8400-e29b-41d4-a716-446655440000

Filtre par ID de client.

filter[interval]
string
Example: filter[interval]=month

Filtre par intervalle de facturation (correspondance partielle, insensible à la casse).

filter[interval_count]
integer
Example: filter[interval_count]=1

Filtre par nombre d'intervalles (correspondance exacte).

sort
string
Enum: "plan_id" "customer_id" "canceled_at" "active" "start_date" "first_renewal_date" "end_date" "created_at" "updated_at" "grace_period" "grace_months" "auto_pause_at" "engaged_date" "gift_activation_code" "update_transporter_at" "transporter_id" "next_transporter_id" "next_coupon_id" "next_billing" "interval" "interval_count" "-plan_id" "-customer_id" "-canceled_at" "-active" "-start_date" "-first_renewal_date" "-end_date" "-created_at" "-updated_at" "-grace_period" "-grace_months" "-auto_pause_at" "-engaged_date" "-gift_activation_code" "-update_transporter_at" "-transporter_id" "-next_transporter_id" "-next_coupon_id" "-next_billing" "-interval" "-interval_count"
Example: sort=-created_at

Trier les résultats (préfixer par - pour un tri descendant). Tri par défaut : id croissant.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

deliveries

Opérations liées aux bons de livraison

Liste des bons de livraison

Récupère la liste de tous les bons de livraison de l'application. Les filtres exacts acceptent plusieurs valeurs séparées par des virgules (filter[order_id]=12,13).

Authorizations:
bearerAuth
query Parameters
filter[uuid]
string

Filtrer par UUID du bon de livraison.

filter[subscription_uuid]
string

Filtrer par UUID de la souscription associée.

filter[address_id]
integer

Filtrer par ID de l'adresse.

filter[phone]
string

Filtrer par numéro de téléphone.

filter[tracking_number]
string

Filtrer par numéro de suivi.

filter[customer_id]
string

Filtrer par ID du client.

filter[transporter_reference]
string

Filtrer par référence du transporteur.

filter[transporter_id]
integer

Filtrer par ID du transporteur.

filter[first_name]
string

Filtrer par prénom.

filter[last_name]
string

Filtrer par nom de famille.

filter[postcode]
string

Filtrer par code postal.

filter[address1]
string

Filtrer par adresse ligne 1.

filter[address2]
string

Filtrer par adresse ligne 2.

filter[city]
string

Filtrer par ville.

filter[country]
string

Filtrer par pays.

filter[mail]
string <= 255 characters

Filtrer par adresse e-mail (correspondance exacte).

filter[transporter_name]
string

Filtrer par nom du transporteur.

filter[plan]
string

Filtrer par nom du plan.

filter[iso_code]
string

Filtrer par code ISO du pays.

filter[relay_id]
string

Filtrer par ID du relais (chaîne, les identifiants de point relais ne sont pas tous numériques).

filter[orderable_name]
string

Filtrer par nom de l'élément commandable.

filter[orderable_id]
string

Filtrer par ID de l'élément commandable.

filter[orderable_type]
string

Filtrer par type de l'élément commandable.

filter[order_id]
integer

Filtrer par ID de commande.

filter[tracking_url]
string

Filtrer par URL de suivi.

filter[quantity]
string

Filtrer par quantité.

filter[ref]
string

Filtrer par référence.

filter[status]
string

Filtrer par statut du bon de livraison.

filter[division]
string

Filtrer par état/province.

filter[company_name]
string

Filtrer par nom de l'entreprise.

filter[created_at_before]
string <date-time>

Filtrer par date de création antérieure.

filter[created_at_after]
string <date-time>

Filtrer par date de création ultérieure.

filter[updated_at_before]
string <date-time>

Filtrer par date de mise à jour antérieure.

filter[updated_at_after]
string <date-time>

Filtrer par date de mise à jour ultérieure.

filter[scheduled_at_before]
string <date-time>

Filtrer par date prévue antérieure.

filter[scheduled_at_after]
string <date-time>

Filtrer par date prévue ultérieure.

sort
string
Enum: "uuid" "subscription_uuid" "address_id" "phone" "tracking_number" "customer_id" "transporter_reference" "transporter_id" "created_at" "updated_at" "first_name" "last_name" "postcode" "address1" "address2" "city" "country" "mail" "transporter_name" "plan" "iso_code" "relay" "relay_id" "orderable_name" "orderable_id" "orderable_type" "order_id" "scheduled_at" "tracking_url" "quantity" "ref" "status" "division" "company_name" "-uuid" "-subscription_uuid" "-address_id" "-phone" "-tracking_number" "-customer_id" "-transporter_reference" "-transporter_id" "-created_at" "-updated_at" "-first_name" "-last_name" "-postcode" "-address1" "-address2" "-city" "-country" "-mail" "-transporter_name" "-plan" "-iso_code" "-relay" "-relay_id" "-orderable_name" "-orderable_id" "-orderable_type" "-order_id" "-scheduled_at" "-tracking_url" "-quantity" "-ref" "-status" "-division" "-company_name"
Example: sort=-created_at

Trier les résultats (préfixer par - pour un tri descendant)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Récupérer les détails d'un bon de livraison

Récupère les détails d'un bon de livraison. data est une liste (un bon de livraison peut porter plusieurs lignes partageant le même UUID).

Authorizations:
bearerAuth
path Parameters
id
required
string

UUID du bon de livraison (champ uuid, pas l'identifiant numérique id)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Mettre à jour un bon de livraison

Permet de le considérer comme expédié, et associer un numéro et un lien de suivi. Un tracking_number est enregistré sur le bon de livraison (et renvoyé dans tracking_number), le lien de suivi est construit à partir du transporteur et le statut passe à shipped. La réponse renvoie les lignes du bon relues après la mise à jour, dans une liste data.

Authorizations:
bearerAuth
path Parameters
id
required
string

UUID du bon de livraison (champ uuid, pas l'identifiant numérique id)

Request Body schema: application/json
required
tracking_number
string or null <= 255 characters

Numéro de suivi à associer au bon de livraison. Il est enregistré et renvoyé dans le champ tracking_number.

notification
boolean
Default: false

Facultatif. Envoyer au client la notification d'expédition avec le lien de suivi (faux par défaut). Lu uniquement avec tracking_number.

status
string or null
Enum: "created" "pending" "shipped" "delivered" "scheduled" "canceled"

Nouveau statut du BL

Responses

Request samples

Content type
application/json
{
  • "tracking_number": "string",
  • "notification": false,
  • "status": "created"
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Supprimer un élément d'un bon de livraison

Supprime un élément du bon de livraison en utilisant son identifiant numérique id (et non l'UUID utilisé par GET et POST).

Authorizations:
bearerAuth
path Parameters
id
required
integer

Identifiant numérique (id) de l'élément du bon de livraison à supprimer

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

kpis

Opérations liées aux indicateurs de performance

Récupérer les indicateurs de performance

Permet de récupérer les indicateurs de performance avec différents filtres.

Authorizations:
bearerAuth
query Parameters
filter[created_at_before]
string <date>
Example: filter[created_at_before]=2023-01-01

Filtre les KPIs créés avant cette date

filter[created_at_after]
string <date>
Example: filter[created_at_after]=2023-01-01

Filtre les KPIs créés après cette date

sort
string
Enum: "created_at" "-created_at"

Tri des résultats (prefix - pour ordre décroissant)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

addresses

Opérations liées aux adresses

Liste des adresses

Cette route permet de lister des adresses.

Authorizations:
bearerAuth
query Parameters
filter[created_at_before]
string <date>
Example: filter[created_at_before]=2023-01-01

Date de création avant laquelle filtrer.

filter[created_at_after]
string <date>
Example: filter[created_at_after]=2023-01-01

Date de création après laquelle filtrer.

filter[updated_at_before]
string <date>
Example: filter[updated_at_before]=2023-01-01

Date de mise à jour avant laquelle filtrer.

filter[updated_at_after]
string <date>
Example: filter[updated_at_after]=2023-01-01

Date de mise à jour après laquelle filtrer.

filter[by_customer_uuid]
string <= 255 characters
Example: filter[by_customer_uuid]=550e8400-e29b-41d4-a716-446655440000

Filtrer par UUID du client.

filter[region_id]
integer
Example: filter[region_id]=1

Filtrer par ID de la région.

filter[user_id]
integer
Example: filter[user_id]=123

Filtrer par ID de l'utilisateur.

filter[address]
string <= 32 characters
Example: filter[address]=123 Main St

Filtrer par adresse.

filter[address1]
string <= 32 characters
Example: filter[address1]=123 Main St

Filtrer par adresse 1.

filter[postcode]
string <= 255 characters
Example: filter[postcode]=75001

Filtrer par code postal.

filter[city]
string <= 255 characters
Example: filter[city]=Paris

Filtrer par ville.

filter[first_name]
string <= 255 characters
Example: filter[first_name]=John

Filtrer par prénom.

filter[last_name]
string <= 255 characters
Example: filter[last_name]=Doe

Filtrer par nom.

filter[company_name]
string <= 255 characters
Example: filter[company_name]=Acme Corp

Filtrer par nom de la société.

filter[division]
string <= 255 characters
Example: filter[division]=Ile-de-France

Filtrer par état.

filter[phone]
string <= 255 characters
Example: filter[phone]=+33123456789

Filtrer par numéro de téléphone.

sort
string
Enum: "region_id" "user_id" "address" "address1" "postcode" "city" "first_name" "last_name" "company_name" "division" "phone" "created_at" "updated_at" "-region_id" "-user_id" "-address" "-address1" "-postcode" "-city" "-first_name" "-last_name" "-company_name" "-division" "-phone" "-created_at" "-updated_at"
Example: sort=-created_at

Trier les résultats (préfixer par - pour un tri descendant)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Créer une adresse

Cette route permet de créer une adresse pour un client du site. Le client (user_id) doit appartenir au site du jeton et le pays (region_id) doit être ouvert sur le site. Le code postal est contrôlé selon le pays ; le téléphone doit être un mobile valide du pays si le contrôle des numéros est actif sur le site. Pour un pays que la bibliothèque de numérotation ne connaît pas (Terres australes françaises par exemple), le téléphone n'est pas contrôlé et il est enregistré tel que saisi. Les champs texte sont normalisés (majuscules, sans accents ni ponctuation). Tout champ non listé est ignoré. La création déclenche le webhook created_address.

Authorizations:
bearerAuth
Request Body schema: application/json
required
user_id
required
integer

ID du client (champ id du client), qui doit appartenir au site du jeton.

region_id
required
integer

ID du pays, parmi les pays ouverts sur le site.

address
required
string <= 32 characters
address1
string or null <= 32 characters

Complément d'adresse.

postcode
required
string <= 20 characters

Code postal, au format du pays.

city
required
string <= 255 characters
first_name
required
string <= 255 characters
last_name
required
string <= 255 characters
company_name
string or null <= 255 characters
phone
required
string <= 30 characters

Téléphone mobile, au format national ou international.

division
string or null <= 10 characters

Code de subdivision (état). Requis pour les États-Unis, parmi les codes d'État (par exemple NY).

Responses

Request samples

Content type
application/json
{
  • "user_id": 123,
  • "region_id": 1,
  • "address": "12 rue de la Paix",
  • "address1": "Bâtiment B",
  • "postcode": "75002",
  • "city": "Paris",
  • "first_name": "Jeanne",
  • "last_name": "Martin",
  • "company_name": "Acme",
  • "phone": "0612345678",
  • "division": "NY"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Mettre à jour une adresse

Cette route permet de mettre à jour une adresse.

Authorizations:
bearerAuth
path Parameters
id
required
integer

ID de l'adresse à mettre à jour.

Request Body schema: application/json
address
required
string <= 32 characters
address1
string or null <= 32 characters
postcode
required
string <= 20 characters
city
required
string <= 255 characters
first_name
required
string <= 255 characters
last_name
required
string <= 255 characters
company_name
string or null <= 255 characters
phone
required
string <= 30 characters
region_id
required
integer
division
string or null <= 10 characters

Code de subdivision (état/province). Requis pour les États-Unis.

Responses

Request samples

Content type
application/json
{
  • "address": "string",
  • "address1": "string",
  • "postcode": "string",
  • "city": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "company_name": "string",
  • "phone": "string",
  • "region_id": 0,
  • "division": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Récupérer les données d'une adresse

Cette route permet de récupérer une adresse.

Authorizations:
bearerAuth
path Parameters
id
required
integer

ID de l'adresse à récupérer.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Supprimer une adresse

Cette route permet de supprimer une adresse. Une adresse qui n'est pas supprimable (champ deletable à false) répond 403.

Authorizations:
bearerAuth
path Parameters
id
required
integer

ID de l'adresse à supprimer.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

customers

Opérations liées aux comptes utilisateurs

Liste des utilisateurs

Cette route permet de récupérer une liste d'utilisateurs.

Authorizations:
bearerAuth
query Parameters
filter[created_at_before]
string <date>
Example: filter[created_at_before]=2023-01-01

Date de création avant laquelle filtrer.

filter[created_at_after]
string <date>
Example: filter[created_at_after]=2023-01-01

Date de création après laquelle filtrer.

filter[updated_at_before]
string <date>
Example: filter[updated_at_before]=2023-01-01

Date de mise à jour avant laquelle filtrer.

filter[updated_at_after]
string <date>
Example: filter[updated_at_after]=2023-01-01

Date de mise à jour après laquelle filtrer.

filter[uuid]
string
Example: filter[uuid]=550e8400-e29b-41d4-a716-446655440000

Filtrer par UUID de l'utilisateur.

filter[id]
integer
Example: filter[id]=123

Filtrer par ID de l'utilisateur.

filter[email]
string
Example: filter[email]=user@example.com

Filtrer par adresse e-mail de l'utilisateur.

filter[external_id]
string
Example: filter[external_id]=ext_12345

Filtrer par ID externe de l'utilisateur.

filter[disabled]
boolean

Filtrer par statut de désactivation de l'utilisateur.

filter[referrer]
string
Example: filter[referrer]=referral_code_123

Filtrer par référent de l'utilisateur.

sort
string
Enum: "id" "uuid" "email" "created_at" "updated_at" "-id" "-uuid" "-email" "-created_at" "-updated_at"
Example: sort=-created_at

Trier les résultats (préfixer par - pour un tri descendant)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Créer un nouvel utilisateur

Cette route permet de créer un nouveau compte utilisateur. Si l'adresse email existe déjà sur le site, la réponse contient l'utilisateur associé (statut 200, external_id n'est pas modifié). Dans le cas contraire, le compte est créé et renvoyé (statut 201). Le client est enveloppé dans data.

Authorizations:
bearerAuth
Request Body schema: application/json
required
email
required
string <email>

Adresse e-mail de l'utilisateur

external_id
string or integer or null <= 255 characters

Identifiant externe facultatif à enregistrer (chaîne ou entier, 255 caractères max), utilisé seulement à la création

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "external_id": "some_external_id"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Récupérer les détails d'un utilisateur

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>

UUID de l'utilisateur (l'identifiant numérique n'est pas accepté)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

transactions

Opérations liées aux transactions

Récupérer la liste des transactions

Authorizations:
bearerAuth
query Parameters
filter[order_id]
integer
Example: filter[order_id]=456

Filtrer par ID de la commande.

filter[gateway]
string
Example: filter[gateway]=MollieCreditCard

Filtrer par moyen de paiement (clé de classe, correspondance exacte), par exemple StripeCreditCard, PayPlugCreditCard, MollieCreditCard, PaypalVault, GoCardlessDirectDebit.

filter[transaction_id]
string
Example: filter[transaction_id]=ch_123456

Filtrer par identifiant de la transaction.

filter[detail]
string

Filtrer par détail de la transaction (correspondance exacte).

filter[token]
string

Filtrer par jeton de la transaction.

filter[paid]
boolean
Example: filter[paid]=true

Filtrer par transactions payées.

filter[amount]
number
Example: filter[amount]=29.99

Filtrer par montant (correspondance exacte).

filter[refunded]
boolean

Filtrer par transactions remboursées.

filter[user_id]
integer
Example: filter[user_id]=123

Filtrer par ID de l'utilisateur.

filter[failure_code]
string <= 255 characters
Example: filter[failure_code]=mandate_revoked

Filtrer par code d'échec de la transaction (correspondance exacte). Le code est celui qu'écrit la passerelle : code de refus Stripe (card_declined, insufficient_funds...), motif de refus de Mollie (authentication_failed, card_expired...) ou code posé par Ciklik (mandate_revoked, merchant_forbidden, forbidden, payment_method_missing...).

filter[invoice_id]
integer
Example: filter[invoice_id]=100

Filtrer par ID de la facture.

filter[created_at_before]
string <date>
Example: filter[created_at_before]=2023-01-01

Filtrer par date de création avant.

filter[created_at_after]
string <date>
Example: filter[created_at_after]=2023-01-01

Filtrer par date de création après.

filter[updated_at_before]
string <date>
Example: filter[updated_at_before]=2023-01-01

Filtrer par date de mise à jour avant.

filter[updated_at_after]
string <date>
Example: filter[updated_at_after]=2023-01-01

Filtrer par date de mise à jour après.

filter[by_customer_uuid]
string <= 255 characters
Example: filter[by_customer_uuid]=550e8400-e29b-41d4-a716-446655440000

Filtrer par UUID du client.

filter[source_id]
string <= 255 characters
Example: filter[source_id]=src_12345

Filtrer par ID de la source.

filter[amount_refunded]
number
Example: filter[amount_refunded]=10.5

Filtrer par montant remboursé.

filter[payment_intent_id]
string <= 255 characters
Example: filter[payment_intent_id]=card_declined

Filtrer par ID de l'intention de paiement.

sort
string
Enum: "order_id" "gateway" "transaction_id" "detail" "token" "paid" "amount" "refunded" "source_id" "failure_code" "invoice_id" "amount_refunded" "user_id" "payment_intent_id" "created_at" "updated_at" "-order_id" "-gateway" "-transaction_id" "-detail" "-token" "-paid" "-amount" "-refunded" "-source_id" "-failure_code" "-invoice_id" "-amount_refunded" "-user_id" "-payment_intent_id" "-created_at" "-updated_at"
Example: sort=-created_at

Trier les résultats (préfixer par - pour un tri descendant)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Récupérer une transaction par ID

Authorizations:
bearerAuth
path Parameters
transaction_id
required
string

L'identifiant de la transaction à récupérer (champ transaction_id).

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Demander le remboursement d'une transaction par ID

Rembourse tout ou partie d'une transaction payée. La réponse renvoie la transaction, enveloppée dans data. Un remboursement refusé (transaction échouée, montant supérieur au restant, solde insuffisant, refus de Stripe) répond 422 avec le motif dans errors.error. Un refus d'une autre passerelle peut répondre 500.

Authorizations:
bearerAuth
path Parameters
transaction_id
required
string

L'identifiant de la transaction à rembourser.

Request Body schema: application/json
required
amount
required
number >= 0.01

Le montant à rembourser (numérique, minimum 0.01).

Responses

Request samples

Content type
application/json
{
  • "amount": 0.01
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

rebill-errors

Opérations liées aux erreurs de rebill

Récupérer la liste des erreurs de rebill

Permet de récupérer la liste des erreurs de rebill avec différents filtres.

Authorizations:
bearerAuth
query Parameters
filter[type]
string
Enum: "api" "partial" "failed"
Example: filter[type]=api

Filtrer par type d'erreur

filter[by_subscription_uuid]
string <= 255 characters
Example: filter[by_subscription_uuid]=550e8400-e29b-41d4-a716-446655440000

Filtrer par UUID de l'abonnement

filter[order_id]
integer
Example: filter[order_id]=456

Filtrer par ID de la commande

filter[error_code]
integer
Example: filter[error_code]=500

Filtrer par code d'erreur

filter[created_at_before]
string <date>
Example: filter[created_at_before]=2023-01-01

Filtrer par date de création avant

filter[created_at_after]
string <date>
Example: filter[created_at_after]=2023-01-01

Filtrer par date de création après

sort
string
Enum: "id" "-id" "type" "-type" "order_id" "-order_id" "error_code" "-error_code" "created_at" "-created_at" "updated_at" "-updated_at"

Trier les résultats (prefix - pour ordre décroissant)

page
integer

Numéro de la page pour la pagination

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Récupérer le détail d'une erreur de rebill

Permet de récupérer les détails d'une erreur de rebill spécifique.

Authorizations:
bearerAuth
path Parameters
id
required
integer

ID de l'erreur de rebill

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

orders

Opérations liées aux commandes

Récupérer la liste des commandes

Authorizations:
bearerAuth
query Parameters
filter[user_id]
integer
Example: filter[user_id]=123

Filtrer par ID de l'utilisateur

filter[address_id]
integer
Example: filter[address_id]=456

Filtrer par ID de l'adresse

filter[invoice_address_id]
integer
Example: filter[invoice_address_id]=789

Filtrer par ID de l'adresse de facturation

filter[transporter_id]
integer
Example: filter[transporter_id]=10

Filtrer par ID du transporteur

filter[status]
string
Enum: "canceled" "completed" "failed" "in_creation" "in_process" "pending" "need_action"
Example: filter[status]=pending

Filtrer par statut de la commande. in_process : paiement en attente de la réponse de la passerelle, par exemple un renouvellement Mollie dont l'issue n'est pas encore confirmée.

filter[subscription_uuid]
string <= 255 characters
Example: filter[subscription_uuid]=550e8400-e29b-41d4-a716-446655440000

Filtrer par UUID de l'abonnement

filter[invoice_id]
integer
Example: filter[invoice_id]=100

Filtrer par ID de la facture

filter[total_paid]
number
Example: filter[total_paid]=29.99

Filtrer par montant total payé

filter[next_try]
string <date>
Example: filter[next_try]=2023-01-01

Filtrer par prochaine tentative

filter[created_at_before]
string <date>
Example: filter[created_at_before]=2023-01-01

Filtrer par date de création avant

filter[created_at_after]
string <date>
Example: filter[created_at_after]=2023-01-01

Filtrer par date de création après

filter[updated_at_before]
string <date>
Example: filter[updated_at_before]=2023-01-01

Filtrer par date de mise à jour avant

filter[updated_at_after]
string <date>
Example: filter[updated_at_after]=2023-01-01

Filtrer par date de mise à jour après

filter[next_try_before]
string <date>
Example: filter[next_try_before]=2023-01-01

Filtrer par prochaine tentative avant

filter[next_try_after]
string <date>
Example: filter[next_try_after]=2023-01-01

Filtrer par prochaine tentative après

filter[by_customer_uuid]
string <= 255 characters
Example: filter[by_customer_uuid]=550e8400-e29b-41d4-a716-446655440000

Filtrer par UUID du client

filter[source]
string
Enum: "utm" "referral" "regain" "retry" "renew" "backend" "unsub_voucher" "unsub_postpone" "reactivation_offer" "followup" "gift_conversion"
Example: filter[source]=utm

Filtrer par source de la commande

sort
string
Enum: "user_id" "address_id" "invoice_address_id" "transporter_id" "status" "subscription_uuid" "invoice_id" "total_paid" "next_try" "source" "created_at" "updated_at" "-user_id" "-address_id" "-invoice_address_id" "-transporter_id" "-status" "-subscription_uuid" "-invoice_id" "-total_paid" "-next_try" "-source" "-created_at" "-updated_at"
Example: sort=-created_at

Trier les résultats (préfixer par - pour un tri descendant)

filter[prestashop_order_id]
integer
Example: filter[prestashop_order_id]=500

Filtrer par correspondance commande PrestaShop

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Récupérer le détail d'une commande

Authorizations:
bearerAuth
path Parameters
id
required
integer

ID de la commande à récupérer

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}