API Documentation v1.0.0

Intégrez FantasticBook à vos outils grâce à notre API REST.

Authentification — Tous les endpoints nécessitent une clé API, transmise dans le header Authorization de chaque requête :
Authorization: Bearer YOUR_API_KEY

Endpoints

POST /version

Version Check

Retourne la version actuelle de l'API.

Réponse
{
    "status": "success",
    "version": "1.0.0"
}
POST /me

User Information

Retourne les informations de l'utilisateur authentifié.

Réponse
{
    "status": "success",
    "data": {
        "id": "user_public_id",
        "company": "Company Name",
        "email": "user@example.com"
    }
}
POST /items/list

Items List

Retourne l'inventaire de l'utilisateur. Aucun paramètre requis.

Réponse
{
    "status": "success",
    "data": [
        {
            "id": "ab54def",
            "name": "Item Name 01",
            "sku": "ITEM-NAME-01",
            "current_stock": 10,          // stock en temps réel
            "damaged_stock": 1,           // stock abîmé (ex: retours clients)
            "weight": 140,                // en grammes
            "category": "book",
            "status": "published",
            "automation_matches": ["Item Name 02", "Item Name 03"]
        },
        {
            "id": "ij35mn",
            "name": "Item Name 02",
            "sku": "ITEM-NAME-02",
            "current_stock": 14,
            "damaged_stock": 0,
            "weight": 504,
            "category": "pack",
            "status": "published",
            "automation_matches": []
        }
    ]
}
POST /orders/list

List Orders

Retourne une liste de commandes avec pagination et options de filtrage. Les paramètres sont à passer dans un objet params dans le body de la requête.

Paramètres
Paramètre Type Requis Description
items_ids array Optionnel Filtrer par IDs d'items
défaut : tous les items
id string | array Optionnel Filtrer par ID de commande (string) ou IDs (array)
"id": "a68e-ve" ou "id": ["a68evZ", "BX67ea"]
défaut : toutes les commandes
status string Optionnel Filtrer par statut
archived sent waiting disabled suspect

défaut : tous les statuts
from_date integer Optionnel Date de début (UNIX timestamp)
défaut : 0
to_date integer Optionnel Date de fin (UNIX timestamp)
défaut : now
limit integer Optionnel Nombre de résultats par page
défaut : 300 · max : 300
offset integer Optionnel Décalage de pagination
défaut : 0
Exemple de requête
{
    "params": {
        "items_ids": [1, 2, 3],
        "status": "sent",
        "from_date": 1718236800,
        "to_date": 1718236800,
        "limit": 50,
        "offset": 0
    }
}
Exemple de réponse
{
    "status": "success",
    "data": {
        "totalCount": 150,
        "inPageCount": 50,
        "limit": 50,
        "offset": 0,
        "hasNextPage": true,
        "orders": [
            // Array of order objects (voir structure ci-dessous)
        ]
    }
}
Structure d'un objet Order
{
    "id": "string",                 // ID public de la commande
    "timestamp": integer,            // Date de création (UNIX timestamp)
    "date": "string",               // Date formatée (Y-m-d h:i:s)
    "canal": "string",              // Source / canal de la commande
    "last_name": "string",           // Nom du client
    "first_name": "string",          // Prénom du client
    "mail": "string",               // Email du client
    "address": "string",            // Adresse de livraison
    "zipcode": "string",            // Code postal
    "city": "string",               // Ville
    "country_iso_code": "string",   // Code ISO du pays
    "country": "string",            // Nom du pays
    "status": "string",             // Statut de la commande
    "tracking_number": "string",    // Numéro de suivi
    "date_sent": integer,           // Date d'expédition (UNIX timestamp)
    "items": [                      // Articles commandés
        {
            "item": "string",           // Nom de l'article
            "item_sku": "string",       // SKU de l'article
            "quantity": integer,        // Quantité commandée
            "current_stock": integer   // Stock actuel
        }
    ],
    "suspect_flags": [              // Drapeaux de suspicion (si applicable)
        {
            "code": "string",          // Code du drapeau
            "details": "string"        // Description
        }
    ]
}
Codes de drapeaux suspects
Code Description
BAD_NAME Le nom du destinataire est douteux
BAD_ADDRESS L'adresse du destinataire est douteuse
IS_TEST Cette commande semble être un test
IS_SIMILAR Cette commande semble être un doublon
ITEM_DOUBLON Un item semble en doublon dans la commande
BAD_PHONENUMBER Le numéro de téléphone semble invalide
POST /order/add

Add Order

Crée une nouvelle commande. Les paramètres sont à passer dans un objet params dans le body de la requête.

Paramètres
Paramètre Type Requis Description
items array Requis Tableau d'articles. Chaque article doit contenir "item" (string — son SKU ou l'un de ses SKU alternatifs) et "quantity" (integer)
last_name string Requis Nom du client
first_name string Requis Prénom du client
address string Requis Adresse de livraison
zipcode string Requis Code postal
city string Requis Ville
country_iso_code string Requis Code ISO du pays (ex : "FR")
phone string Optionnel Numéro de téléphone
mail string Optionnel Adresse email
canal string Optionnel Canal de la commande
défaut : "api"
Exemple de requête
{
    "params": {
        "items": [
            {
                "item": "MON-LIVRE-SKU-7489",
                "quantity": 1
            }
        ],
        "last_name": "Dupont",
        "first_name": "Jean",
        "address": "123 Rue de la Paix",
        "zipcode": "75000",
        "city": "Paris",
        "country_iso_code": "FR",
        "phone": "0606060606",
        "mail": "jean.dupont@example.com"
    }
}
Exemple de réponse
{
    "status": "success",
    "order_id": "a68e-ve"
}
POST /order/update

Update Order

Met à jour une commande existante. Pour l'instant, seul le status peut être mis à jour.

Attention : une commande ne peut pas être modifiée si son statut actuel est tosend (en cours de préparation) ou sent (déjà expédiée).

Paramètres
Paramètre Type Requis Description
id string Requis ID public de la commande à mettre à jour
status string Optionnel Nouveau statut de la commande. Valeurs autorisées :
waiting archived disabled
Exemple de requête
{
    "params": {
        "id": "a68e-ve",
        "status": "archived"
    }
}
Exemple de réponse
{
    "status": "success",
    "order_id": "a68e-ve"
}
Codes d'erreur
Code HTTP Message Signification
400 Missing parameters. Le body ne contient pas d'objet params.
400 Missing or invalid order id. Le champ id est absent ou n'est pas une string.
400 Invalid status. Le status fourni n'est pas l'une des valeurs autorisées (waiting, archived, disabled).
403 Order cannot be edited anymore. La commande n'est plus modifiable (statut tosend ou sent).
404 Order not found. Aucune commande ne correspond à l'id fourni, ou elle n'appartient pas à l'utilisateur authentifié.
© 2026 fantasticbook.