API Partenaire Livraison Pigee

Démarrage rapide

De la création du compte à votre premier envoi en direct en moins d'une heure. Suivez ces cinq étapes :

1. Créez un compte Pigee gratuit sur account.pigeepost.com et sélectionnez Partenaire Livraison comme type de compte.
2. Accédez à Tableau de bord → Développeur → Clés API et générez une clé live et une clé de test.
3. Choisissez votre mode de paiement : Pigee Pay ou Solde du compte Pigee.
4. Configurez vos frais de service dans Tableau de bord → Frais.
5. Importez la collection Postman pour le développement en environnement de préproduction.

Authentification

Chaque requête doit inclure votre clé API dans l'en-tête Authorization sous forme de jeton Bearer. Les clés sont propres à votre compte partenaire et intègrent votre configuration de frais et votre mode de paiement.

Authorization: Bearer pgk_live_YOUR_API_KEY_HERE

Types de clés

Environnements et URL de base

Le bac à sable est une réplique fidèle et complète de la production. Changez d'environnement en modifiant le préfixe de votre clé, ou utilisez l'URL explicite du bac à sable pour plus de clarté.

SDK et bibliothèques

Les SDK officiels encapsulent l'API REST avec des modèles typés, des tentatives automatiques et des outils pour le bac à sable.

Valider la clé API

Appelez ce point de terminaison pour confirmer que votre clé API est active et correctement configurée avant la mise en production.

POST /api/v1/store/valid
Authorization: Bearer pgk_live_…
Content-Type: application/json

{
  "store_type": 2,
  "api_key": "pgk_live_YOUR_KEY"
}

{
  "valid": true,
  "account": {
    "id": "acc_7H4K",
    "type": "shipping_partner",
    "payment_mode": "pigee_pay",
    "service_fee_pct": 8.5,
    "balance_gbp": 240.00
  }
}

Obtenir les tarifs d'expédition

Récupérez les tarifs transporteurs en temps réel pour une expédition. Renvoie tous les services disponibles triés par prix, avec le délai de transit, la prise en charge de la valeur assurée et le coût rendu.

{
  "shop_url": "https://your-store.com",
  "currency": "GBP",
  "parcel": {
    "type": "Box",
    "boxsize": 4
  },
  "weight": { "value": 4, "units": "kg" },
  "dimension": {
    "length": 40,
    "width": 30,
    "height": 20,
    "units": "cms"
  },
  "address": {
    "pickup": {
      "address_line1": "10 High Street",
      "town": "London",
      "post_code": "SW1A 1AA",
      "country": "United Kingdom"
    },
    "destination": {
      "address_line1": "123 Ocean Drive",
      "town": "Miami",
      "post_code": "33101",
      "country": "United States"
    }
  }
}

{
  "rates": [
    {
      "carrier_request_id": "cr_abc123",
      "carrier_id": "dhl",
      "pigee_carrier_id": "DHL_EXPRESS_WORLDWIDE",
      "method_title": "DHL Express Worldwide",
      "price": 125.50,
      "currency": "GBP",
      "transit_days": 2,
      "insurance_available": true,
      "customs_included": true
    }
  ],
  "currency": "GBP",
  "request_id": "req_7H4K2026"
}

Paramètres de la requête

Créer une commande

Créez une commande Pigee en utilisant un carrier_request_id provenant du point de terminaison des tarifs. Pigee génère l'étiquette, la facture commerciale et, en cas d'utilisation de Pigee Pay, un lien de paiement hébergé.

{
  "order_from": "api",
  "shop_url": "https://your-store.com",
  "order_id": "ORDER-10001",
  "currency": "GBP",
  "items": [
    {
      "name": "Vintage leather jacket",
      "quantity": 1,
      "value": 600.00,
      "currency": "GBP",
      "hs_code": "4203100090"
    }
  ],
  "shippingData": {
    "method_title": "DHL Express Worldwide",
    "cost": 125.50,
    "currency": "GBP",
    "meta_data": {
      "carrier_request_id": "cr_abc123",
      "carrier_id": "dhl",
      "pigee_carrier_id": "DHL_EXPRESS_WORLDWIDE"
    }
  }
}

{
  "order_id": "po_78910",
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "status": "pending_payment",
  "payment_url": "https://pay.pigee.com/c/abc123",
  "label_url": null,
  "tracking_number": null
}

Traiter la commande

Envoyez les détails finaux de traitement une fois le paiement confirmé. Pigee génère l'étiquette d'expédition, réserve le transporteur et renvoie un numéro de suivi.

{
  "order_id": "po_78910",
  "status": "processing",
  "shop_id": "https://your-store.com",
  "currency": "GBP",
  "total": 725.50,
  "shipping_total": 125.50
}

{
  "order_id": "po_78910",
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "status": "booked",
  "label_url": "https://labels.pigeepost.com/PGE-7H4K-2026-0042.pdf",
  "tracking_number": "1234567890",
  "carrier": "DHL",
  "estimated_delivery": "2026-05-08"
}

Suivi

Récupérez les événements de suivi en temps réel pour toute expédition créée via l'API.

{
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "tracking_number": "1234567890",
  "carrier": "DHL",
  "status": "in_transit",
  "estimated_delivery": "2026-05-08",
  "events": [
    {
      "timestamp": "2026-05-06T08:14:00Z",
      "status": "in_transit",
      "location": "DHL Hub, Leipzig",
      "description": "Shipment in transit"
    }
  ]
}

Modes de paiement

Pigee prend en charge deux modes de paiement. Le mode actif est défini dans votre tableau de bord partenaire et s'applique à toutes les commandes.

Frais de service

En tant que partenaire d'expédition, vous pouvez ajouter vos propres frais en plus des tarifs transporteurs de base de Pigee. Les frais sont configurés dans votre tableau de bord et appliqués automatiquement avant que les tarifs ne soient renvoyés.

• Frais en pourcentage : Appliqués sous forme de pourcentage du coût transporteur de base.
• Frais fixes : Un montant forfaitaire ajouté par expédition.
• Dérogations par trajet : Remplacez les frais globaux pour des paires origine/destination spécifiques.

Règlements et change

Pigee Pay collecte les paiements des clients finaux en plus de 135 devises et les règle sur votre compte bancaire dans votre devise locale.

• Le cycle de règlement est généralement de J+2 jours ouvrés après la confirmation de livraison de l'expédition.
• Retirez des fonds de votre solde Pigee depuis le tableau de bord.
• Des journaux de transactions détaillés sont disponibles sous Finances → Règlements.
• Les factures des transactions réglées sont générées automatiquement et disponibles au format PDF.

Webhooks

Pigee envoie des événements en temps réel vers votre point de terminaison HTTPS au format JSON POST requêtes. Configurez l'URL de votre webhook dans Tableau de bord → Développeur → Webhooks.

{
  "event": "parcel.delivered",
  "created_at": "2026-05-08T14:22:07Z",
  "api_version": "v1",
  "data": {
    "pigee_order_id": "PGE-7H4K-2026-0042",
    "order_id": "ORDER-10001",
    "carrier": "DHL",
    "tracking_number": "1234567890",
    "delivered_at": "2026-05-08T14:18:00Z"
  }
}

Référence des événements Webhook

Signatures des webhooks

Chaque requête webhook inclut un X-Pigee-Signature en-tête, une empreinte HMAC-SHA256 du corps brut de la requête. Vérifiez toujours cette valeur avant tout traitement.

// Node.js
const crypto = require('crypto');

function verifyPigeeWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

Erreurs

Toutes les erreurs renvoient un JSON avec un objet error contenant un code et un message.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your Pigee partner balance is not sufficient to create this shipment.",
    "request_id": "req_7H4K2026"
  }
}

Limites de débit

Les limites de débit s'appliquent par clé API et varient selon votre palier de compte.

Lorsqu'une limite de débit est atteinte, l'API renvoie HTTP 429 avec un en-tête Retry-After .

Types de données et conventions

• Dates et heures - ISO 8601 UTC, par ex. 2026-05-06T14:22:07Z
• Devises - codes à trois lettres ISO 4217, par ex. GBP, USD, NGN
• Valeurs monétaires - number avec deux décimales, toujours associées à un currency champ
• Noms de pays - noms complets en anglais, par ex. "United Kingdom", "United States"
• Numéros de téléphone - format E.164 recommandé, par ex. +447700900123
• Graisses - kg ou lbs spécifié par requête
• Identifiants - les identifiants générés par Pigee utilisent un format à préfixe, par ex. po_78910, cr_abc123

Référence des identifiants transporteurs

Utilisation pigee_carrier_id valeurs issues de la réponse des tarifs lors de la création des commandes.

Journal des modifications

v1.3 - mai 2026

• Ajout insurance_available et customs_included d'indicateurs à la réponse des tarifs.
• La vérification de la signature du webhook utilise désormais HMAC-SHA256.
• Nouveau code d'erreur RATE_EXPIRED.
• Point de terminaison de suivi ajouté : GET /api/v1/tracking/{pigee_order_id}.

v1.2 - février 2026

• Ajout de la personnalisation des frais de service par ligne dans le tableau de bord.
• Les liens de paiement Pigee Pay incluent désormais un expires_at champ.
• Nouveaux événements webhook ajoutés pour les douanes et les règlements.

v1.1 - octobre 2025

• Publication initiale de la collection Postman.
• Lancement de l'environnement sandbox.
• Sortie du mode de paiement Solde du compte.

v1.0 - juin 2025

• Première version publique : Validation, Obtention des tarifs, Création de commande, Exécution de commande.