API docs by Redocly

API d'intégration de commandes à FluidIT (1.0.0)

Download OpenAPI specification:

Équipe FluidIT: support@fluid-it.fr License: Propriétaire FluidIT

API REST pour la création et gestion des commandes clients avec livraison et services additionnels (reprise, leasing, etc.).

Cette API permet de:

  • Créer des commandes clients avec informations complètes
  • Gérer les adresses de livraison avec contraintes logistiques
  • Spécifier les types de livraison (pas de porte (pavillon), pied d'immeuble, dépose pièce du choix, installation / montage)
  • Ajouter des services optionnels (reprise, leasing, etc.) (Inversion gicleur, changement de porte, etc.)
  • Ajouter des commentaires de livraison (visibles par le client et le livreur)
  • Ajouter des commentaires internes (visibles uniquement par le livreur)
  • Modifier l'adresse email ou le N° de téléphone du client
  • Modifier les commentaires de livraison
  • Annuler une commande (planifiée ou non)
  • S'abonner aux événements pour recevoir des notifications en temps réel via webhook

Événements webhook disponibles:

  • ORDER_CREATED: Déclenché lors de la création d'une nouvelle commande
  • ORDER_VALIDATED: Déclenché lors de la validation d'une commande
  • ORDER_TO_CLIENT_WAITING: Déclenché quand une commande passe en attente client
  • ORDER_SHIFT_TIME_PASSED: Déclenché quand l'heure de cut dépassée (plus possible de modifier)
  • ORDER_DATE_CHANGED: Déclenché lors du changement de date de livraison
  • ORDER_ASSIGNED_TO_ROUND: Déclenché lors de l'assignation à une tournée
  • PICKING_DONE: Déclenché quand le picking est terminé
  • DELIVERY_STARTED: Déclenché au début de la livraison
  • DELIVERY_COMPLIANT: Déclenché pour une livraison conforme
  • DELIVERY_NOT_COMPLIANT: Déclenché pour une livraison non conforme
  • DELIVERY_WITH_MISSING_PRODUCT: Déclenché pour une livraison avec produit manquant
  • DELIVERY_PARTIALLY_RETURNED_TO_STORE: Déclenché pour un retour partiel en magasin
  • ORDER_CANCELLED: Déclenché lors de l'annulation d'une commande
  • ORDER_CANCELLED_WITH_REASON: Déclenché lors de l'annulation avec motif
  • ORDER_CUSTOMER_ABSENT: Déclenché quand le client est absent
  • ORDER_DELIVERY_FAILED: Déclenché en cas d'échec de livraison
  • CLIENT_PORTAL_LINK_SENT: Déclenché quand le lien portail client est envoyé
  • INCOMING_DELIVERY: SMS de livraison imminente envoyé

Types de livraison supportés:

  • lv1: Livraison pas de porte (pavillon), pied d'immeuble
  • lv2: Livraison dépose pièce du choix
  • lv3: Livraison avec installation ou montage

Informations importantes:

  • Tous les poids sont en kilogrammes
  • Tous les volumes sont en mètres cubes
  • Les codes postaux doivent être français (5 chiffres)
  • Les numéros de téléphone doivent être au format français (ex: 0689046819)

Commandes

Opérations de création et gestion des commandes clients

Créer une nouvelle commande

Crée une nouvelle commande avec livraison et services additionnels. Cette API permet de:

  • Enregistrer les informations client et adresse de livraison
  • Spécifier les articles commandés avec leurs caractéristiques logistiques
  • Ajouter des services optionnels (reprise, leasing, etc.) (Inversion gicleur, changement de porte, etc.)
  • Ajouter des commentaires de livraison (visibles par le client et le livreur)
  • Ajouter des commentaires internes (visibles uniquement par le livreur)
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Données complètes de la commande à créer

id
required
string

Identifiant unique de la commande généré par le système

transporter
required
string

Nom du transporteur ou de l'entreprise de livraison

invoice_id
required
string

Numéro de facture associé à la commande

store_id
required
string

Identifiant du magasin émetteur de la commande

required
object (Client)

Informations personnelles du client destinataire de la commande

required
object (DeliveryAddress)

Adresse complète de livraison avec informations logistiques détaillées

required
Array of objects (OrderArticle)

Liste des articles commandés avec leurs caractéristiques

Array of objects (ExtraService)

Services additionnels optionnels liés à la commande (LLD, Afterwork, etc.)

delivery_comment
string

Commentaire de livraison visible par le livreur et le client

internal_comment
string

Commentaire interne visible uniquement par le livreur, non accessible au client

client_price
number <float>

Montant à payer par le client directement au livreur lors de la livraison (paiement en espèces, chèque, etc.)

store_settle
number <float>

Montant restant à collecter pour le magasin le jour de la livraison (solde à régler)

financing
boolean

Indique si la commande est associée à un dossier de financement (crédit, leasing, etc.)

Responses

Request samples

Content type
application/json

Exemple d'une commande avec livraison pas de porte (pavillon), pied d'immeuble (lv1)

{
  • "id": "YOUR-ID-123456789",
  • "invoice_id": "223.202/0033759",
  • "store_id": "001",
  • "transporter": "Limon",
  • "client": {
    },
  • "delivery_address": {
    },
  • "articles": [
    ],
  • "extra_service": [
    ],
  • "delivery_comment": "Sonner à l'interphone, code d'accès 1234A. Livraison préférée le matin.",
  • "internal_comment": "Attention: escalier étroit au 3ème étage, prévoir sangles supplémentaires.",
  • "client_price": 50,
  • "store_settle": 25.5,
  • "financing": false
}

Response samples

Content type
application/json
{
  • "message": "Le payload a été accepté et va être pris en charge par le service, vous pourrez suivre son statut via l'API /requests/{request_id}",
  • "request_id": "req_87EC7791d7AdD24D29D1792577F977FDE7",
  • "order_id": "YOUR-ID-123456789"
}

Modifier une commande existante

Met à jour partiellement les informations d'une commande existante. Cette opération permet de modifier:

  • L'adresse email du client
  • Le numéro de téléphone du client
  • Les commentaires de livraison (visibles par le client et le livreur)
  • Les commentaires internes (visibles uniquement par le livreur)
Authorizations:
ApiKeyAuth
path Parameters
order_id
required
string
Example: YOUR-ID-123456789

Identifiant de la commande à modifier ou annuler

Request Body schema: application/json
required

Champs à modifier dans la commande. Seuls les champs fournis seront mis à jour.

object
delivery_comment
string

Commentaire de livraison visible par le livreur et le client

internal_comment
string

Commentaire interne visible uniquement par le livreur, non accessible au client

Responses

Request samples

Content type
application/json
Example
{
  • "client": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Requête acceptée, mise en file d'attente vous pourrez suivre son statut via l'API /requests/{request_id}",
  • "request_id": "req_87EC7791d7AdD24D29D1792577F977FDE7",
  • "order_id": "YOUR-ID-123456789"
}

Annuler une commande

Annule une commande existante. Cette action est irréversible.

Authorizations:
ApiKeyAuth
path Parameters
order_id
required
string
Example: YOUR-ID-123456789

Identifiant de la commande à modifier ou annuler

Responses

Response samples

Content type
application/json
{
  • "message": "L'annulation a été acceptée, mise en file d'attente vous pourrez suivre son statut via l'API /requests/{request_id}",
  • "request_id": "req_87EC7791d7AdD24D29D1792577F977FDE7",
  • "order_id": "YOUR-ID-123456789"
}

Suivi des requêtes

Opérations de suivi et monitoring des requêtes

Récupérer le statut d'une requête

Permet de récupérer les informations de statut et de traitement d'une requête asynchrone. Cet endpoint est utile pour suivre l'état d'une opération (création, modification, annulation) après avoir reçu un code de réponse 202.

Statuts possibles:

  • PENDING: Requête en cours de traitement
  • SUCCESS: Requête traitée avec succès
  • FAILED: Requête échouée
  • TIMEOUT: Requête expirée

Types d'actions:

  • CREATE: Création de commande
  • UPDATE: Modification de commande
  • DELETE: Annulation de commande
Authorizations:
ApiKeyAuth
path Parameters
request_id
required
string
Example: req_87EC7791d7AdD24D29D1792577F977FDE7

Identifiant de la requête dont on veut connaître le statut

Responses

Response samples

Content type
application/json
Example

Exemple d'une requête qui a échoué lors du traitement

{
  • "status": "FAILED",
  • "response_status": 502,
  • "response_body": null,
  • "error_message": "HTTPConnectionPool(host='api.example.com', port=80): Max retries exceeded",
  • "last_attempt": "2025-07-01T14:47:19.487436+00:00",
  • "order_id": "YOUR-ID-123456789",
  • "invoice_id": "002.205/0026273",
  • "action_type": "CREATE",
  • "response_id": null
}

Abonnements

Gestion des abonnements aux événements pour recevoir des notifications en temps réel

Créer un abonnement aux événements

Crée un nouvel abonnement pour recevoir des notifications en temps réel lors d'événements spécifiques sur les commandes et livraisons.

Workflow des événements webhook

Événements disponibles:

  • ORDER_CREATED: Nouvelle commande créée
  • ORDER_VALIDATED: Commande validée
  • ORDER_TO_CLIENT_WAITING: Commande en attente client
  • ORDER_SHIFT_TIME_PASSED: Heure de cut dépassée (plus possible de modifier)
  • ORDER_DATE_CHANGED: Date de livraison modifiée
  • ORDER_ASSIGNED_TO_ROUND: Commande assignée à une tournée
  • PICKING_DONE: Picking terminé
  • DELIVERY_STARTED: Livraison démarrée
  • DELIVERY_COMPLIANT: Livraison conforme
  • DELIVERY_NOT_COMPLIANT: Livraison non conforme
  • DELIVERY_WITH_MISSING_PRODUCT: Livraison avec produit manquant
  • DELIVERY_PARTIALLY_RETURNED_TO_STORE: Retour partiel en magasin
  • ORDER_CANCELLED: Commande annulée
  • ORDER_CANCELLED_WITH_REASON: Commande annulée avec motif
  • ORDER_CUSTOMER_ABSENT: Client absent
  • ORDER_DELIVERY_FAILED: Échec de livraison
  • CLIENT_PORTAL_LINK_SENT: Lien portail client envoyé
  • INCOMING_DELIVERY: Livraison entrante

Filtrage avancé: Vous pouvez filtrer les événements par instance FluidIT spécifique ou par magasin, et ajouter des conditions de filtrage personnalisées sur les données d'événement.

Format des notifications: Les notifications sont envoyées via POST avec un payload JSON contenant les détails de l'événement et les données associées.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Configuration de l'abonnement aux événements

Any of
event_type
required
string
Enum: "ORDER_CREATED" "ORDER_VALIDATED" "ORDER_TO_CLIENT_WAITING" "ORDER_SHIFT_TIME_PASSED" "ORDER_DATE_CHANGED" "ORDER_ASSIGNED_TO_ROUND" "PICKING_DONE" "DELIVERY_STARTED" "DELIVERY_COMPLIANT" "DELIVERY_NOT_COMPLIANT" "DELIVERY_WITH_MISSING_PRODUCT" "DELIVERY_PARTIALLY_RETURNED_TO_STORE" "ORDER_CANCELLED" "ORDER_CANCELLED_WITH_REASON" "ORDER_CUSTOMER_ABSENT" "ORDER_DELIVERY_FAILED" "CLIENT_PORTAL_LINK_SENT" "INCOMING_DELIVERY"

Type d'événement auquel s'abonner (pour un seul événement)

event_types
Array of strings
Items Enum: "ORDER_CREATED" "ORDER_VALIDATED" "ORDER_TO_CLIENT_WAITING" "ORDER_SHIFT_TIME_PASSED" "ORDER_DATE_CHANGED" "ORDER_ASSIGNED_TO_ROUND" "PICKING_DONE" "DELIVERY_STARTED" "DELIVERY_COMPLIANT" "DELIVERY_NOT_COMPLIANT" "DELIVERY_WITH_MISSING_PRODUCT" "DELIVERY_PARTIALLY_RETURNED_TO_STORE" "ORDER_CANCELLED" "ORDER_CANCELLED_WITH_REASON" "ORDER_CUSTOMER_ABSENT" "ORDER_DELIVERY_FAILED" "CLIENT_PORTAL_LINK_SENT" "INCOMING_DELIVERY"

Types d'événements auxquels s'abonner (pour plusieurs événements)

transporteur
string or null

Nom du transporteur (instance FluidIT) spécifique (optionnel, laisser null pour toutes les instances)

store_id
string or null

Identifiant du magasin utilisé par cet expéditeur (optionnel, laisser null pour tous les magasins)

is_active
boolean
Default: true

Statut actif/inactif de l'abonnement

webhook_url_override
string or null <uri>

URL webhook spécifique pour ce type d'événement (optionnel)

object

Conditions de filtrage supplémentaires au format JSON

Responses

Request samples

Content type
application/json
Example

Exemple d'abonnement pour recevoir les notifications de création et modification de commandes

{}

Response samples

Content type
application/json
{
  • "message": "Abonnement créé avec succès",
  • "subscription_id": 42,
  • "event_type": "ORDER_CREATED",
  • "is_active": true
}

Lister les abonnements aux événements

Récupère la liste de tous les abonnements aux événements actifs et inactifs pour l'expéditeur authentifié.

Authorizations:
ApiKeyAuth
query Parameters
event_type
string
Enum: "ORDER_CREATED" "ORDER_VALIDATED" "ORDER_TO_CLIENT_WAITING" "ORDER_SHIFT_TIME_PASSED" "ORDER_DATE_CHANGED" "ORDER_ASSIGNED_TO_ROUND" "PICKING_DONE" "DELIVERY_STARTED" "DELIVERY_COMPLIANT" "DELIVERY_NOT_COMPLIANT" "DELIVERY_WITH_MISSING_PRODUCT" "DELIVERY_PARTIALLY_RETURNED_TO_STORE" "ORDER_CANCELLED" "ORDER_CANCELLED_WITH_REASON" "ORDER_CUSTOMER_ABSENT" "ORDER_DELIVERY_FAILED" "CLIENT_PORTAL_LINK_SENT" "INCOMING_DELIVERY"
Example: event_type=ORDER_CREATED

Filtrer par type d'événement

is_active
boolean
Example: is_active=true

Filtrer par statut actif/inactif

Responses

Response samples

Content type
application/json
{
  • "subscriptions": [
    ],
  • "count": 2
}

Récupérer un abonnement aux événements

Récupère les détails d'un abonnement aux événements spécifique par son identifiant.

Authorizations:
ApiKeyAuth
path Parameters
subscription_id
required
integer
Example: 42

Identifiant de l'abonnement aux événements

Responses

Response samples

Content type
application/json
{
  • "id": 42,
  • "event_type": "ORDER_CREATED",
  • "event_type_display": "Commande créée",
  • "transporteur": null,
  • "store_id": null,
  • "is_active": true,
  • "webhook_url_override": "https://mon-api.example.com/webhooks/orders",
  • "filter_conditions": { },
  • "created_at": "2025-07-07T10:30:00Z",
  • "updated_at": "2025-07-07T10:30:00Z"
}

Modifier un abonnement aux événements

Met à jour un abonnement aux événements existant. Permet de modifier le type d'événement, l'instance, le magasin, l'URL webhook, les conditions de filtrage ou le statut actif/inactif.

Authorizations:
ApiKeyAuth
path Parameters
subscription_id
required
integer
Example: 42

Identifiant de l'abonnement aux événements

Request Body schema: application/json
required

Champs à modifier dans l'abonnement aux événements

event_type
string
Enum: "ORDER_CREATED" "ORDER_VALIDATED" "ORDER_TO_CLIENT_WAITING" "ORDER_SHIFT_TIME_PASSED" "ORDER_DATE_CHANGED" "ORDER_ASSIGNED_TO_ROUND" "PICKING_DONE" "DELIVERY_STARTED" "DELIVERY_COMPLIANT" "DELIVERY_NOT_COMPLIANT" "DELIVERY_WITH_MISSING_PRODUCT" "DELIVERY_PARTIALLY_RETURNED_TO_STORE" "ORDER_CANCELLED" "ORDER_CANCELLED_WITH_REASON" "ORDER_CUSTOMER_ABSENT" "ORDER_DELIVERY_FAILED" "CLIENT_PORTAL_LINK_SENT" "INCOMING_DELIVERY"

Nouveau type d'événement auquel s'abonner

transporteur
string or null

Nouveau nom du transporteur (instance FluidIT) spécifique (null pour toutes les instances)

store_id
string or null

Nouvel identifiant du magasin utilisé par cet expéditeur (null pour tous les magasins)

is_active
boolean

Nouveau statut actif/inactif de l'abonnement

webhook_url_override
string or null <uri>

Nouvelle URL webhook spécifique pour ce type d'événement

object or null

Nouvelles conditions de filtrage supplémentaires au format JSON

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
{
  • "message": "Abonnement mis à jour avec succès",
  • "subscription_id": 42,
  • "event_type": "DELIVERY_COMPLIANT",
  • "is_active": false
}

Supprimer un abonnement aux événements

Supprime définitivement un abonnement aux événements. Cette action est irréversible. Aucune notification ne sera plus envoyée après la suppression.

Authorizations:
ApiKeyAuth
path Parameters
subscription_id
required
integer
Example: 42

Identifiant de l'abonnement aux événements

Responses

Response samples

Content type
application/json
{
  • "message": "Abonnement supprimé avec succès",
  • "subscription_id": 42,
  • "event_type": "ORDER_CREATED"
}

Créneaux

Opérations de gestion des créneaux de livraison (timeslots)

Récupérer les créneaux disponibles

Récupère la liste des créneaux de livraison disponibles pour une adresse et une période données.

Cette opération est synchrone et retourne directement la réponse de l'instance FluidIT.

Identification du magasin: Le champ store_id est utilisé pour identifier le magasin (contractor) via la table ContractorIdentifier.

Réponse: La réponse est transmise directement depuis FluidIT sans modification, avec le code de statut HTTP original.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Paramètres de recherche des créneaux disponibles

store_id
required
string

Identifiant du magasin utilisé pour identifier le contractor via ContractorIdentifier

start
string <date-time>

Date et heure de début de la période de recherche (format ISO 8601)

stop
string <date-time>

Date et heure de fin de la période de recherche (format ISO 8601)

type
string

Type de service (par exemple "delivery" pour livraison)

object (DeliveryAddress)

Adresse complète de livraison avec informations logistiques détaillées

Array of objects (OrderArticle)

Liste des articles à livrer

Responses

Request samples

Content type
application/json
{
  • "store_id": "001",
  • "start": "2025-11-20T00:00:00+0100",
  • "stop": "2025-11-27T23:59:59+0100",
  • "type": "delivery",
  • "delivery_address": {
    },
  • "articles": [
    ]
}

Response samples

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

Réserver un créneau de livraison

Réserve un créneau de livraison spécifique identifié par son timeslotId.

Cette opération est synchrone et retourne directement la réponse de l'instance FluidIT.

Identification du magasin: Le champ store_id est utilisé pour identifier le magasin (contractor) via la table ContractorIdentifier.

Réponse: La réponse est transmise directement depuis FluidIT sans modification, avec le code de statut HTTP original. En cas de succès, la réponse contient généralement un reservationId à utiliser pour annuler la réservation.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Données de réservation du créneau

store_id
required
string

Identifiant du magasin utilisé pour identifier le contractor via ContractorIdentifier

timeslotId
required
string

Identifiant du créneau à réserver (obtenu via l'endpoint GET timeslots)

Responses

Request samples

Content type
application/json
{
  • "store_id": "001",
  • "timeslotId": "b6cfecbf-d55b-43e3-8e94-5575cef1dd36"
}

Response samples

Content type
application/json
{
  • "reservationId": "res_789012",
  • "timeslotId": "slot_123456",
  • "status": "confirmed",
  • "start": "2025-01-20T09:00:00Z",
  • "end": "2025-01-20T12:00:00Z"
}

Annuler une réservation de créneau

Annule une réservation de créneau de livraison existante identifiée par son reservationId.

Cette opération est synchrone et retourne directement la réponse de l'instance FluidIT.

Identification du magasin: Le champ store_id est utilisé pour identifier le magasin (contractor) via la table ContractorIdentifier.

Réponse: La réponse est transmise directement depuis FluidIT sans modification, avec le code de statut HTTP original.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Données d'annulation de la réservation

store_id
required
string

Identifiant du magasin utilisé pour identifier le contractor via ContractorIdentifier

reservationId
required
string

Identifiant de la réservation à annuler (obtenu lors de la réservation)

Responses

Request samples

Content type
application/json
{
  • "store_id": "001",
  • "reservationId": "res_789012"
}

Response samples

Content type
application/json
{
  • "reservationId": "res_789012",
  • "status": "cancelled",
  • "message": "Réservation annulée avec succès"
}

Endpoint expediteur

Les appels lancés depuis FluidIT vers l'expéditeur (webhook & retour async des request)

Structure des notifications webhook reçues

⚠️ IMPORTANT : Ceci N'EST PAS un endpoint à appeler !

Cette documentation décrit la structure des notifications webhook que votre système recevra de la part de FluidIT lorsque des événements se produisent sur les commandes et livraisons.

Comment cela fonctionne :

  1. Vous créez un abonnement aux événements via l'endpoint /subscriptions
  2. Vous spécifiez votre webhook_url dans l'abonnement
  3. Quand un événement se produit, FluidIT envoie automatiquement une requête POST à votre URL
  4. Votre endpoint doit accepter et traiter le payload JSON décrit ci-dessous

Implémentation côté client :

  • Votre endpoint webhook doit accepter les requêtes POST
  • Votre endpoint doit répondre avec un code de statut HTTP 2xx pour confirmer la réception
  • Le payload JSON contiendra toujours la structure décrite dans les exemples ci-dessous
  • Utilisez le champ event_type pour déterminer le type d'événement et traiter en conséquence

Gestion des erreurs :

  • Si votre endpoint répond avec un code d'erreur (4xx, 5xx), FluidIT retentera l'envoi
  • Assurez-vous que votre endpoint est idempotent (peut traiter le même événement plusieurs fois)

Sécurité :

  • Validez toujours les données reçues
  • Considérez l'ajout d'une authentification sur votre endpoint webhook
  • Vérifiez que les requêtes proviennent bien de FluidIT (par IP ou signature si disponible)

Description du workflow

Le système d'événements webhook fonctionne selon le principe suivant :

  1. Déclenchement : Un événement est déclenché suite à une action côté transporteur (instance FluidIT)
  2. Envoi automatique : Le payload de l'événement est automatiquement envoyé au webhook_url configuré lors de la souscription à ce type d'événement
  3. Structure standardisée : Tous les événements utilisent la même structure de payload standardisée pour garantir la cohérence

Structure du payload d'événement

Chaque événement webhook envoyé à votre endpoint contient un payload JSON avec la structure définis dans WebhookPayload

Champs spécifiques

  • articles : Array contenant chaque article individuel de la commande (pas de quantité car chaque élément représente une unité)
  • failure_reason : Raison d'échec de livraison (voir énumération ci-dessous)
  • pickup_incident_reason : Raison d'incident lors du chargement (voir énumération ci-dessous)

Énumérations des raisons d'échec

failure_reason - Raisons d'échec de livraison globale :

  • absent : Client absent
  • customerCancellation : Annulation client
  • addressNotFound : Adresse non trouvée
  • wrongAddress : Adresse incorrecte
  • breakdown : Panne véhicule
  • unknown : Personne inconnue
  • strike : Impossible : grève
  • weather : Impossible : conditions météo

failure_reason - Raisons d'échec de livraison à l'article :

  • damaged : Produit abîmé
  • refused : Produit refusé par le client
  • partialDelivery : Colis manquant
  • missingInfo : Information ou document manquant
  • closed : Impossible de livrer dans la pièce de destination

failure_reason - Raisons d'échec de reprise :

  • notready : Produit non prêt (enlèvement)
  • customerRequest : Produit non repris à la demande du client
  • noProductToPickup : Il n'y a plus de produit à reprendre
  • notUninstalled : Le produit n'est pas désinstallé
  • badHygiene : Mauvais état hygiénique
  • dismantledProduct : Appareil / produit désossé
  • other : Autre…

pickup_incident_reason - Raisons d'incident lors du chargement :

  • DAMAGED_PACKAGING_OR_PRODUCT : Emballage/produit abîmé
  • MISSING_PRODUCT : Produit manquant
  • PRODUCT_OR_EAN_DOES_NOT_MATCH : Produit/EAN ne correspond pas
  • FORCED : Forcé
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Payload JSON que FluidIT envoie à votre endpoint webhook lors d'un événement. Cette structure est standardisée pour tous les types d'événements.

timestamp
required
string <date-time>

Horodatage de l'événement au format ISO 8601

fluidit_id
required
string

Identifiant unique FluidIT de la commande

fluidit_url
string

URL de la commande dans FluidIT

contractor_id
required
string

Identifiant du contractant/magasin

order_id
required
string

Identifiant de la commande

store_id
required
string

Identifiant du magasin

api_sender
required
string

Identifiant de l'expéditeur API

event_type
required
string
Enum: "ORDER_CREATED" "ORDER_VALIDATED" "ORDER_TO_CLIENT_WAITING" "ORDER_SHIFT_TIME_PASSED" "ORDER_DATE_CHANGED" "ORDER_ASSIGNED_TO_ROUND" "PICKING_DONE" "DELIVERY_STARTED" "DELIVERY_COMPLIANT" "DELIVERY_NOT_COMPLIANT" "DELIVERY_WITH_MISSING_PRODUCT" "DELIVERY_PARTIALLY_RETURNED_TO_STORE" "ORDER_CANCELLED" "ORDER_CANCELLED_WITH_REASON" "ORDER_CUSTOMER_ABSENT" "ORDER_DELIVERY_FAILED" "CLIENT_PORTAL_LINK_SENT" "INCOMING_DELIVERY"

Type d'événement déclenché

order_status
required
string

Statut actuel de la commande

delivered_at
string or null <date-time>

Date et heure de livraison effective (null si pas encore livrée)

arrival_time
string or null

Heure d'arrivée du livreur (format HH:MM)

failure_reason
string or null
Enum: "absent" "customerCancellation" "addressNotFound" "wrongAddress" "breakdown" "unknown" "strike" "weather"

Raison d'échec de livraison

sav_comment
string or null

Commentaire du service après-vente

object

Informations sur le rendez-vous de livraison

required
Array of objects (WebhookArticle)

Liste des articles de la commande avec leur statut individuel

Responses

Request samples

Content type
application/json
Example

Exemple de payload reçu lors de la création d'une commande

{
  • "timestamp": "2025-01-15T14:30:00Z",
  • "fluidit_id": "202505200163409",
  • "fluidit_url": "https://fluidit.com/orders/recap/202505200163409",
  • "contractor_id": "d3b6e5bc-f8d1-4d43-8fcd-456558c67f27",
  • "order_id": "YOUR-ID-123456789",
  • "store_id": "001",
  • "api_sender": "SKARA",
  • "event_type": "ORDER_CREATED",
  • "order_status": "WAITING_FOR_CUSTOMER",
  • "delivered_at": null,
  • "arrival_time": null,
  • "failure_reason": null,
  • "sav_comment": null,
  • "delivery_appointment": {
    },
  • "articles": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "message": "OK"
}

Réception des résultats de traitement asynchrone (Response URL)

⚠️ IMPORTANT : Ceci N'EST PAS un endpoint à appeler !

Cette documentation décrit la structure des notifications de résultat que votre système recevra de la part de FluidIT lorsque le traitement asynchrone d'une requête est terminé.

Fonctionnement du Response URL

Lorsque vous effectuez une opération asynchrone (création, modification ou annulation de commande), vous recevez immédiatement une réponse 202 avec un request_id. Le traitement réel de votre requête se fait ensuite en arrière-plan.

Si vous avez configuré un "response_url" dans votre configuration d'expéditeur, FluidIT poussera automatiquement le résultat du traitement vers cette URL dès que le traitement sera terminé.

Comment cela fonctionne :

  1. Vous effectuez une requête POST/PATCH/DELETE sur /orders ou /orders/{order_id}
  2. Vous recevez une réponse 202 avec un request_id
  3. FluidIT traite votre requête de manière asynchrone
  4. Une fois le traitement terminé (succès ou échec), FluidIT envoie automatiquement le résultat à votre response_url
  5. Vous recevez le payload complet avec tous les détails du traitement

Avantages du Response URL :

  • Pas besoin de faire du polling sur /request/{request_id}
  • Notification immédiate dès que le traitement est terminé
  • Réduction de la charge sur vos systèmes et sur l'API FluidIT
  • Meilleure réactivité de votre application

Implémentation côté client :

  • Votre endpoint response_url doit accepter les requêtes POST
  • Votre endpoint doit répondre avec un code de statut HTTP 2xx pour confirmer la réception
  • Le payload JSON contiendra toujours la structure décrite dans les exemples ci-dessous
  • Utilisez le champ processing_status pour déterminer si le traitement a réussi ou échoué
  • Le champ success indique rapidement si l'opération a réussi (true) ou échoué (false)

Gestion des erreurs :

  • Si votre endpoint répond avec un code d'erreur (4xx, 5xx), FluidIT retentera l'envoi
  • Assurez-vous que votre endpoint est idempotent (peut traiter le même résultat plusieurs fois)

Sécurité :

  • Validez toujours les données reçues
  • Considérez l'ajout d'une authentification sur votre endpoint response_url
  • Vérifiez que les requêtes proviennent bien de FluidIT (par IP ou signature si disponible)

Statuts de traitement possibles

  • FINISHED: Le traitement s'est terminé avec succès
  • FAILED: Le traitement a échoué (erreur serveur FluidIT, timeout, etc.)
  • INVALID: La requête était invalide (magasin introuvable, données incorrectes, etc.)

Structure du payload

Le payload envoyé à votre response_url contient toujours les champs suivants :

  • request_id: Identifiant de la requête (correspond au request_id reçu dans la réponse 202)
  • original_order_id: Identifiant de commande que vous avez fourni
  • processing_status: Statut du traitement (FINISHED, FAILED, INVALID)
  • timestamp: Date et heure de création de la requête
  • last_attempt: Date et heure de la dernière tentative de traitement
  • action_type: Type d'action (CREATE, UPDATE, DELETE, MODIFY)
  • success: Booléen indiquant si l'opération a réussi
  • store_id ou store_name: Identifiant ou nom du magasin (selon disponibilité)

En cas de succès :

  • response_status: Code HTTP de la réponse FluidIT (200, 201, etc.)
  • fluidit_id: Identifiant FluidIT de la commande créée/modifiée
  • order_status: Statut de la commande dans FluidIT
  • response_data: Données complètes de la réponse FluidIT

En cas d'échec :

  • error.message: Message d'erreur descriptif
  • error.failure_reason: Raison détaillée de l'échec (si disponible)
  • response_status: Code HTTP de l'erreur (si applicable)
  • response_data: Données d'erreur de FluidIT (si disponibles)
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Payload JSON que FluidIT envoie à votre response_url lorsque le traitement d'une requête est terminé. Cette structure varie selon le résultat du traitement (succès, échec, invalide).

request_id
required
integer

Identifiant unique de la requête (correspond au request_id reçu dans la réponse 202)

original_order_id
required
string

Identifiant de commande que vous avez fourni lors de la création/modification

processing_status
required
string
Enum: "FINISHED" "FAILED" "INVALID"

Statut du traitement de la requête

timestamp
required
string <date-time>

Date et heure de création de la requête au format ISO 8601

last_attempt
string or null <date-time>

Date et heure de la dernière tentative de traitement (null si requête invalide)

action_type
required
string
Enum: "CREATE" "UPDATE" "DELETE" "MODIFY"

Type d'action effectuée

store_id
string or null

Identifiant du magasin (présent si disponible)

store_name
string or null

Nom du magasin (présent si store_id non disponible)

success
required
boolean

Indique si l'opération a réussi (true) ou échoué (false)

response_status
integer or null

Code de statut HTTP de la réponse FluidIT (null si requête invalide avant envoi)

fluidit_id
string or null

Identifiant FluidIT de la commande (présent uniquement en cas de succès)

order_status
string or null

Statut de la commande dans FluidIT (présent uniquement en cas de succès)

response_data
object or null

Données complètes de la réponse FluidIT (structure variable selon l'opération)

object or null

Informations d'erreur (présent uniquement en cas d'échec)

Responses

Request samples

Content type
application/json
Example

Exemple d'une requête de création traitée avec succès avec toutes les informations disponibles

{
  • "request_id": 12345,
  • "original_order_id": "ORDER-2024-001",
  • "processing_status": "FINISHED",
  • "timestamp": "2024-01-15T10:30:00.123456Z",
  • "last_attempt": "2024-01-15T10:30:05.789012Z",
  • "action_type": "CREATE",
  • "store_id": "STORE_001",
  • "success": true,
  • "response_status": 200,
  • "fluidit_id": "FL-789456",
  • "order_status": "VALIDATED",
  • "response_data": {
    }
}

Response samples

Content type
application/json
Example
{
  • "message": "OK"
}