API Documentation v1.0.0

Tous les endpoints de l'API nécessitent une clé d'API, propre à votre compte. Elle se transmet dans le header Authorization de chaque requête, avec le schéma Bearer. Toutes les requêtes se font en POST, avec un body JSON (header Content-Type: application/json).

Authorization: Bearer YOUR_API_KEY

curl -X POST https://api.fantasticbook.co/me \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Gérez votre clé d'API sur votre compte fantasticbook, page Automatisation. Gardez-la secrète : elle donne accès à vos commandes et à votre crédit. Si elle fuite, régénérez-la depuis cette même page (l'ancienne clé est immédiatement révoquée).

Retourne la version actuelle de l'API.

{
    "status": "success",
    "version": "1.0.0"
}

Retourne les informations de l'utilisateur authentifié.

{
    "status": "success",
    "data": {
        "id": "user_public_id",
        "company": "Company Name",
        "email": "user@example.com"
    }
}

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

{
    "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": []
        }
    ]
}

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.

{
    "params": {
        "items_ids": [1, 2, 3],
        "status": "sent",
        "from_date": 1718236800,
        "to_date": 1718236800,
        "limit": 50,
        "offset": 0
    }
}

{
    "status": "success",
    "data": {
        "totalCount": 150,
        "inPageCount": 50,
        "limit": 50,
        "offset": 0,
        "hasNextPage": true,
        "orders": [
            // Array of order objects (voir structure ci-dessous)
        ]
    }
}

{
    "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
        }
    ]
}

Crée une nouvelle commande. Les paramètres sont à passer dans un objet params dans le body de la 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"
    }
}

{
    "status": "success",
    "order_id": "a68e-ve"
}

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).

{
    "params": {
        "id": "a68e-ve",
        "status": "archived"
    }
}

{
    "status": "success",
    "order_id": "a68e-ve"
}

Retourne le solde du crédit courriers du compte, en centimes HT. Ce crédit prépayé (rechargeable par carte bancaire depuis votre compte fantasticbook, section Crédit courriers) règle chaque courrier envoyé via /letter/add, et peut aussi régler vos campagnes.

{
    "status": "success",
    "data": {
        "balance_ht_cents": 4815,
        "balance": "48,15 € HT"
    }
}

Devis d'un courrier à l'unité : le prix qui serait débité de votre crédit pour un nombre de pages et une destination donnés. Ne crée aucun courrier et ne touche pas au crédit.

{
    "status": "success",
    "data": {
        "price_ht_cents": 260,
        "zone": "EUROPE",
        "country_iso_code": "BE",
        "sheets": 2,
        "weight_grams": 18.5
    }
}

Crée un courrier à l'unité : nous imprimons votre PDF (papier blanc, recto-verso), le mettons sous pli et l'expédions au destinataire. Le prix est débité de votre crédit prépayé à la création. Si le crédit est insuffisant, le courrier est enregistré avec le statut error_credit (HTTP 402) : il ne part pas, mais sera relancé automatiquement dès votre prochaine recharge de crédit.

{
    "params": {
        "first_name": "Jean",
        "last_name": "Dupont",
        "address": "4 rue des Lilas",
        "zipcode": "75011",
        "city": "Paris",
        "pdf_url": "https://example.com/mon-courrier.pdf"
    }
}

{
    "status": "success",
    "letter_id": "HLowYA",
    "letter_status": "pending",
    "price_ht_cents": 185,
    "balance_ht_cents": 4815
}

{
    "status": "error",
    "message": "Insufficient credit: the letter was recorded with status \"error_credit\" and will be sent automatically after a top-up.",
    "letter_id": "BsfvWQ",
    "letter_status": "error_credit",
    "price_ht_cents": 185,
    "balance_ht_cents": 100
}

Détail d'un courrier à l'unité du compte. Statuts possibles : pending (en attente de préparation), error_credit (crédit insuffisant), in_batch (en préparation), sent (envoyé), canceled (archivé, remettable en traitement par le client).

{
    "status": "success",
    "data": {
        "id": "HLowYA",
        "status": "pending",
        "status_label": "En attente de préparation",
        "recipient": {
            "first_name": "Jean",
            "last_name": "Dupont",
            "address": "4 rue des Lilas",
            "zipcode": "75011",
            "city": "Paris",
            "country_iso_code": "FR"
        },
        "pages": 1,
        "price_ht_cents": 185,
        "error_message": null,
        "tracking_number": null,
        "created_at": 1788281373,
        "sent_at": null
    }
}

Tous les courriers à l'unité du compte, du plus récent au plus ancien. Chaque élément a la même structure que la réponse de /letter/get.

{
    "status": "success",
    "data": [
        { "id": "HLowYA", "status": "pending", … },
        { "id": "BsfvWQ", "status": "sent", … }
    ]
}

Annule un courrier tant qu'il n'est pas parti en préparation (statut pending ou error_credit). Un courrier déjà débité est remboursé sur votre crédit. Un courrier en préparation ou envoyé n'est plus annulable.

{
    "status": "success",
    "letter_id": "HLowYA",
    "letter_status": "canceled",
    "refunded": true,
    "balance_ht_cents": 5000
}