Introduction

Comment utiliser l'API de First Delivery Group

Collection Postman

Suivez les étapes suivantes pour démarrer rapidement avec l'API de First Delivery Group

  1. Télécharger et installer l'application Postman
  2. Installer la collection Postman. Cliquez sur le bouton "Run in Postman" ci-dessous pour installer
  3. Veillez à mettre à jour les variables d'environnement:

    • {{env}} : https://www.firstdeliverygroup.com/api/v2

    • {{token}} : Le jeton d'accès fournit

How to use the First Delivery Group API

Postman Collection

Follow these steps to get started quickly with the First Delivery Group API

  1. Download and install the Postman application
  2. Install the Postman collection. Click the "Run in Postman" button below to install
  3. Make sure to update the environment variables:

    • {{env}} : https://www.firstdeliverygroup.com/api/v2

    • {{token}} : The access token provided

Commandes

Orders

Chez First Delivery Group, nous avons mis en place une API qui vous permet de créer des commandes et de consulter l'état de vos commandes.

IMPORTANT: L'utilisation du point de terminaison /localities deviendra obligatoire à partir du 1er juin 2026. Veuillez mettre à jour votre intégration pour utiliser locality_id.

NB: Toutes les requêtes nécessitent que le jeton fourni par nous soit le Berear token pour l'autorisation.

At First Delivery Group, we have implemented an API that allows you to create orders and check the status of your orders.

IMPORTANT: The use of the /localities endpoint will become mandatory starting June 1st, 2026. Please update your integration to use locality_id.

NB: All requests require the token provided by us to be the Bearer token for authorization.

Ajouter une commande Add an order

Pour ajouter une nouvelle commande en utilisant notre API To add a new order using our API

Méthode HTTP : POST HTTP Method : POST

Lien : {{env}}/create Link : {{env}}/create 


  {
    "Client": {
        "nom": "nom client",
        "locality_id": 1, // nouveau attribut
        "gouvernerat": "sousse",
        "ville": "medina",
        "adresse": "adresse client",
        "telephone": "00000000",
        "telephone2": ""
    },
    "Produit": {
        "prix": 20,
        "designation": "designation produit",
        "nombreArticle": 1,
        "commentaire": "commentaire",
        "article": "nom produit",
        "nombreEchange": 0
    }
  }


  {
    "status": 201,
    "isError": false,
    "message": "Produit ajouté avec succès",
    "result": {
        "barCode": "683375045049",
        "link": "{{env}}/print?q=eyji"
    }
  }

Paramètres d'entrées

Paramètre Type Requis Description
Client
nom String Oui / Yes Nom du clientClient's name
locality_id Number Non (Obligatoire 01/06/2026)No (Mandatory 06/01/2026) ID de la localité (récupéré via /localities)Locality ID (retrieved via /localities)
gouvernerat String Oui / Yes Gouvernorat du clientClient's governorate
ville String Oui / Yes Ville du clientClient's city
adresse String Oui / Yes Adresse du clientClient's address
telephone String Oui / Yes Numéro de téléphone du clientClient's phone number
telephone2 String Non / No Deuxième numéro de téléphone du clientClient's second phone number
Produit
prix Number Oui / Yes Prix TTC du produit (Entre 0 et 999 DT) Inclus les frais de livraisonTotal price of the product (Between 0 and 999 DT) Includes delivery fees
designation String Oui / Yes Désignation du produitProduct designation
nombreArticle Number Oui / Yes Nombre d'articleNumber of items
commentaire String Non / No CommentaireComment
article String Non / No Nom du produitProduct name
nombreEchange Number Non / No Nombre d'échangeNumber of exchanges

Ajouter plusieurs commandes Add multiple orders

Pour ajouter des commandes en utilisant notre API

NB:

  • Vous ne pouvez ajouter que 100 commandes à la fois.
  • Pour garantir la stabilité et la performance de notre API, nous avons mis en place une limitation du taux de requêtes. Chaque utilisateur peut effectuer une requête toutes les 10 secondes. Toute tentative d'exécution de requêtes plus fréquentes entrainera un rejet temporaire.

To add multiple orders using our API

NB:

  • You can only add 100 orders at a time.
  • To ensure the stability and performance of our API, we have implemented rate limiting. Each user can make one request every 10 seconds. Any attempt to execute requests more frequently will result in a temporary rejection.

Méthode HTTP : POST HTTP Method : POST

Lien : {{env}}/bulk-create Link : {{env}}/bulk-create 


  [
    {
      "Client": {
          "nom": "nom du client 1",
          "locality_id": 1, // nouveau attribut
          "gouvernerat": "sousse",
          "ville": "medina",
          "adresse": "adresse client 1",
          "telephone": "88999000",
          "telephone2": ""
      },
      "Produit": {
          "prix": 50,
          "designation": "designation produit 1",
          "nombreArticle": 1,
          "commentaire": "",
          "article": "nom produit 1",
          "nombreEchange": 2
      }
    },
    {
      "Client": {
          "nom": "nom client",
          "locality_id": 123, // nouveau attribut
          "gouvernerat": "sousse",
          "ville": "medina",
          "adresse": "adresse client",
          "telephone": "00000000",
          "telephone2": "22000000"
      },
      "Produit": {
          "prix": 20,
          "designation": "designation produit 2",
          "nombreArticle": 1,
          "commentaire": "commentaire",
          "article": "nom produit 2",
      }
    }
  ]


  ====== Succès ======
  {
    "status": 201,
    "isError": false,
    "message": "3 produit(s) a/ont été ajoutés avec succès",
    "result": {
        "link": "{{env}}/bulk-print?q=eyji",
        "barCodes": [
           {
                "index": 0,
                "barCode": "111111111111"
            },
            {
                "index": 1,
                "barCode": "222222222222"
            },
            {
                "index": 2,
                "barCode": "333333333333"
            }
        ]
    }
  }
  ====== En cas d'erreur interceptée ======
  {
    "status": 207,
    "isError": false,
    "message": "Nous n'arrivons pas à ajouter 1 produit(s)",
    "result": {
        "link": "{{env}}/bulk-print?q=eyji",
        "barCodes": [
           {
                "index": 0,
                "barCode": "444444444444"
            },
            {
                "index": 2,
                "barCode": "555555555555"
            }
        ]
    };
    "errors": [
        {
            "Client": {
                "nom": "nom du client 1",
                "gouvernerat": "gouvernerat invalide",
                "ville": "ville 1",
                "adresse": "adresse client",
                "telephone": "11222333",
                "telephone2": ""
            },
            "Produit": {
                "article": "article",
                "prix": "999",
                "designation": "designation produit",
                "nombreArticle": "2",
                "commentaire": "commentaire"
            },
            "errors": {
                "isError": true,
                "message": "Le gouvernorat 'gouvernerat invalide' est invalide"
            }
        }
  }

Paramètres d'entrées

Paramètre Type Requis Description
Client
nom String Oui / Yes Nom du clientClient's name
locality_id Number Non (Obligatoire 01/06/2026) No (Mandatory 06/01/2026) ID de la localité (récupéré via /localities)
gouvernerat String Oui / Yes Gouvernorat du clientClient's governorate
ville String Oui / Yes Ville du clientClient's city
adresse String Oui / Yes Adresse du clientClient's address
telephone String Oui / Yes Numéro de téléphone du clientClient's phone number
telephone2 String Non / No Deuxième numéro de téléphone du clientClient's second phone number
Produit
prix Number Oui / Yes Prix TTC du produit (Entre 0 et 999 DT) Inclus les frais de livraisonTotal price of the product (Between 0 and 999 DT) Includes delivery fees
designation String Oui / Yes Désignation du produitProduct designation
nombreArticle Number Oui / Yes Nombre d'articleNumber of items
commentaire String Non / No CommentaireComment
article String Non / No Nom du produitProduct name
nombreEchange Number Non / No Nombre d'échangeNumber of exchanges

Récupérer les localités Get Localities

Pour récupérer la liste des localités (Gouvernorats, Villes,> Localités).

Méthode HTTP : GET

Lien : {{env}}/localities

To retrieve the list of localities (Governorates, Delegations, Localities).

HTTP Method: GET

Link: {{env}}/localities 


  {
    "status": 200,
    "isError": false,
    "message": "Localities retrieved successfully",
    "result": [
      {
        "locality_id": 1,
        "locality_name": "Ain Drahem",
        "delegation_name": "Ain Drahem",
        "governorate_name": "Jendouba"
      },
      {
        "locality_id": 2,
        "locality_name": "Sousse Medina",
        "delegation_name": "Sousse",
        "governorate_name": "Sousse"
      }
    ]
  }

Consulter l'état d'une commande Check order status

Méthode HTTP : POST HTTP Method : POST

Lien : {{env}}/etat Link : {{env}}/etat

NB:

  • Pour garantir la stabilité et la performance de notre API, nous avons mis en place une limitation du taux de requêtes. Chaque utilisateur peut effectuer une requête par seconde. Toute tentative d'exécution de requêtes plus fréquentes entrainera un rejet temporaire. 

    
    {  
      "barCode": "683377360858"
    }
  
  
    {
      "status": 200,
      "isError": false,
      "message": "Etat du produit récupéré avec succès",
      "result": {
          "state": "En attente",
          "barCode": "683377360858"
      }
    }

Paramètres d'entrées Input parameters

Paramètre Parameter Type Requis Required Description
barCode String OuiYes Code à barre du produitProduct barcode

Filtrer les commandes Filter orders

Méthode HTTP : POST HTTP Method : POST

Lien : {{env}}/filter Link : {{env}}/filter

NB:

  • Pour garantir la stabilité et la performance de notre API, nous avons mis en place une limitation du taux de requêtes. Chaque utilisateur peut effectuer 2 requêtes chaque 10 secondes. Toute tentative d'exécution de requêtes plus fréquentes entrainera un rejet temporaire.
  • Des validations strictes ont été introduites pour les paramètres de filtrage : Strict validations have been introduced for filtering parameters:
    • barCode : doit contenir exactement 12 chiffres s'il est renseigné.must contain exactly 12 digits if provided.
    • createdAtFrom / createdAtTo : doivent suivre le format yyyy-MM-dd.must follow the yyyy-MM-dd format.
    • pageNumber : doit être un entier >= 1.must be an integer >= 1.
    • limit : doit être un entier entre 1 et 100.must be an integer between 1 and 100.

  
  {
    "barCode": "",
    "createdAtFrom": "2021-01-02",
    "createdAtTo": "2022-01-02",
    "state": 0,
    "pagination": {
        "pageNumber": 1,
        "limit": 10
    }
  }


  {
    "status": 200,
    "isError": false,
    "message": "Commandes récupérées avec succès",
    "result": {
        "CurrentPage": 1,
        "TotalPages": 1,
        "TotalCount": 1,
        "PageSize": 10,
        "Items": [
            {
                "barCode": "xxxxxxxxxxxx",
                "createdAt": "2021-01-02T23:00:00.000Z",
                "pickupAt": "2021-01-04T18:51:38.000Z",
                "deliveredAt": "2021-01-05T18:49:32.000Z",
                "Client": {
                    "name": "***",
                    "address": "***",
                    "city": "***",
                    "state": "***",
                    "telephone": "********",
                    "telephone2": ""
                },
                "Product": {
                    "designation": "***",
                    "price": 20,
                    "message": "",
                    "itemNumber": "1"
                },
                "state": "**",
                "exchange": "0"
            }
        ]
    }
  }

Paramètres d'entrées Input parameters

Paramètre Parameter Type Requis Required Description
barCode String NonNo Code à barre du produitProduct barcode
createdAtFrom String NonNo Date de création de la commande (format : YYYY-MM-DD)Order creation date (format: YYYY-MM-DD)
createdAtTo String NonNo Date de création de la commande (format : YYYY-MM-DD)Order creation date (format: YYYY-MM-DD)
state Number NonNo Etat de la commande voir détailsOrder status see details
pagination NonNo Paramètres de paginationPagination parameters
pageNumber Number NonNo Numéro de la page (1 par défaut)Page number (default 1)
limit Number NonNo Nombre d'éléments par page (10 par défaut)Number of items per page (default 10)

Détails des états

Etat Status Code Description
En attentePending 0 Commande en attente de traitementOrder awaiting processing
En coursIn progress 1 Commande en cours de traitementOrder being processed
LivréDelivered 2 Commande livréOrder delivered
EchangeExchange 3 Commande en état d'échangeOrder in exchange state
Retour ExpéditeurReturned to Sender 5 Commande en retour expéditeurOrder returned to sender
SuppriméDeleted 6 Commande annulé par expéditeurOrder canceled by sender
Rtn client/agenceRtn client/agency 7 Retour client/agenceReturn client/agency
Au magasinAt store 8 Commande au magasinOrder at store
Rtn dépôtRtn warehouse 11 Commande retour dépôtOrder warehouse return
A vérifierTo verify 20 Commande à vérifierOrder to verify
Retour reçuReturn received 30 Retour reçuReturn received
Rtn définitifFinal return 31 Retour définitifFinal return
Demande d'enlèvementPickup request 100 Demande d'enlèvement crééePickup request created
Demande d'enlèvement assignéePickup request assigned 101 Demande d'enlèvement assignéePickup request assigned
En cours d'enlèvementPickup in progress 102 Pickup en cours d'enlèvementPickup in progress
EnlevéPicked up 103 Pickup enlevéPickup completed
Demande d'enlèvement annuléPickup request canceled 104 Demande d'enlèvement annuléPickup request canceled
Retour assignéReturn assigned 201 Retour assigné à un livreurReturn assigned to a driver
Retour en cours d'expéditionReturn in transit 202 Retour en cours d'expéditionReturn in transit
Retour enlevéReturn picked up 203 Retour enlevé par le livreurReturn picked up by the driver
Retour AnnuléReturn Canceled 204 Retour AnnuléReturn Canceled

Annuler des commandes Cancel orders

Méthode HTTP : POST HTTP Method : POST

Lien : {{env}}/cancel-orders Link : {{env}}/cancel-orders

NB:

  • Seules les commandes qui sont en attente peuvent être annulées.
  • Cette méthode accepte au maximum 100 commandes à la fois. 

  
  {
    "barCodes": [
      "1111111111", 
      "1111111112", 
      "1111111113", 
      "1111111114", 
    ]
  }


  {
    "status": 200,
    "isError": false,
    "message": "Succès",
    "result": [
      "1111111111",
      "1111111112",
      ]
    }
  }

  • Cette requête renvoie comme réponse la liste des code à barres traités

Demande d'enlèvements Pickup requests

NB: Toutes les requêtes nécessitent que le jeton fourni par nous soit le Berear token pour l'autorisation. All requests require the token provided by us to be the Bearer token for authorization.

Créer une demande d'enlèvement Create a pickup request

Pour créer une demande d'enlèvement en utilisant notre API To create a pickup request using our API

Méthode HTTP : POST HTTP Method : POST

Lien : {{env}}/pickup Link : {{env}}/pickup 


  {
    "barCodes": [
      "123456789012",
      "123456789013",
      "123456789014",
      "123456789015",
      "123456789016",
      "123456789017"
    ]
  }


  {
    "status": 201,
    "isError": false,
    "message": "Produit ajouté avec succès",
    "result": {
        "pickup": "683375045049",
        "link": "{{env}}/print-pickup?q=eyji"
    }
  }

Paramètres d'entrées

Paramètre Type Requis Description
barCodes Array <string> OuiYes Liste des codes à barreList of barcodes

Imprimer décharge Print pickup receipt

Méthode HTTP : POST HTTP Method : POST

Lien : {{env}}/request-print/{pickupId} Link : {{env}}/request-print/{pickupId} 

     
    Aucun corps  
  
  
  
    {
      "status": 200,
      "isError": false,
      "message": "Demande d'enlèvement trouvée avec succès",
      "result": {
          "pickup": "683377360858",
          "link": "{{env}}/print-pickup?q=eyji"
      }
    }

Paramètres d'entrées Input parameters

Paramètre Parameter Type Requis Required Description
pickupId String OuiYes Le numéro de lot de pickupThe pickup batch number

Journal des modifications Changelog

Découvrez les nouveautés ajoutées, modifiées, corrigées, améliorées ou mises à jour dans les dernières versions. Discover the new features added, modified, corrected, improved, or updated in the latest versions.
Version Description
v2.5.1 26 Mars, 2026

Localités & Validations des Filtres Localities & Filters Validations

Nouveautés (2) New (2)
  • Nouvel endpoint GET /localities récupère toutes les localité supportées par l'API New endpoint GET /localities retrieves all localities supported by the API
  • Nouvel attribut optionnel jusqu'au 1 JUIN 2026 locality_id sur POST /order/create & POST /order/bulk-create pour cibler une localité précise New optional locality_id field until 1st of Juin 2026 on POST /order/create & POST /order/bulk-create to target a precise locality
Améliorations (1) Improvements (1)
  • Introduction de validations strictes pour l'endpoint POST /filter (Code-barres, Formats de date, Pagination) Introduction of strict validations for the POST /filter endpoint (Barcodes, Date formats, Pagination)
v2.4 30 Juillet, 2024

Annulation en masse Bulk Cancellation

Améliorations (1) Improvements (1)
  • Annulation multiples des commandes Bulk cancellation of orders
v2.3 07 Juillet, 2024

Opérations en masse Bulk Operations

Améliorations (2) Improvements (2)
  • Creation multiples des commandes Bulk creation of orders
  • Impression multiples des bordeaux Bulk printing of barcodes
v2.2 20 Juin, 2024

Demandes d'enlèvements Pickup Requests

Améliorations (2) Improvements (2)
  • Creation des demandes d'enlèvements Creation of pickup requests
  • Impression des décharges des demandes d'enlèvements Printing of pickup request receipts

Journal des modifications Changelog

View docs Follow us on X