Pigee Shipping Partner API

Anza Haraka

Kutoka kuunda akaunti hadi shehena yako ya kwanza halisi kwa chini ya saa moja. Fuata hatua hizi tano:

1. Fungua akaunti ya bure ya Pigee kwenye account.pigeepost.com na chagua Shipping Partner kama aina ya akaunti yako.
2. Nenda kwenye Dashboard → Developer → API Keys na tengeneza ufunguo halisi na ufunguo wa majaribio.
3. Chagua mfumo wako wa malipo: Pigee Pay au Pigee Account Balance.
4. Sanidi ada yako ya huduma katika Dashboard → Fees.
5. Ingiza mkusanyiko wa Postman kwa ajili ya maendeleo ya majaribio.

Uthibitishaji

Kila ombi lazima liwe na ufunguo wako wa API katika Authorization header kama Bearer token. Funguo hizo zimefungwa kwa akaunti yako ya mshirika na hubeba mipangilio yako ya ada na mfumo wa malipo.

Authorization: Bearer pgk_live_YOUR_API_KEY_HERE

Aina za funguo

Mazingira & Anwani za Msingi (Base URLs)

Sandbox ni nakala kamili ya 1:1 ya mazingira ya uzalishaji. Badilisha mazingira kwa kubadilisha kiambishi awali cha funguo yako, au tumia anwani ya sandbox ya wazi kwa uwazi zaidi.

SDKs & Maktaba

SDK rasmi zinafunika REST API na miundo iliyoandikwa (typed models), majaribio ya kiotomatiki na visaidizi vya sandbox.

Thibitisha Funguo ya API

Piga simu kwenye kituo hiki cha huduma ili kuthibitisha funguo yako ya API inatumika na imesanidiwa vizuri kabla ya kuanza rasmi.

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
  }
}

Pata Viwango vya Usafirishaji

Pata viwango halisi vya wasafirishaji kwa shehena. Inarudisha huduma zote zinazopatikana zikipangwa kwa bei, ikijumuisha muda wa usafirishaji, uwezo wa kuhakikisha thamani na gharama ya jumla ya bidhaa ilipofika (landed cost).

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

Vigezo vya ombi

Tengeneza Oda

Unda oda ya Pigee kwa kutumia carrier_request_id kutoka kwa endpoint ya viwango. Pigee huzalisha lebo, ankara ya kibiashara na, ikiwa unatumia Pigee Pay, kiungo cha malipo kilichowekwa mtandaoni.

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

Timiza Oda

Tuma maelezo ya mwisho ya utekelezaji mara malipo yatakapothibitishwa. Pigee huzalisha lebo ya usafirishaji, hufanya uhifadhi na kampuni ya usafirishaji na kurejesha namba ya ufuatiliaji.

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

Ufuatiliaji

Pata matukio ya ufuatiliaji wa moja kwa moja kwa shehena yoyote iliyoundwa kupitia 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"
    }
  ]
}

Njia za Malipo

Pigee inasaidia hali mbili za malipo. Hali inayotumika huwekwa kwenye dashibodi yako ya mshirika na hutumika kwa oda zote.

Ada za Huduma

Kama Mshirika wa Usafirishaji unaweza kuongeza ada yako mwenyewe juu ya viwango vya msingi vya Pigee vya kampuni za usafirishaji. Ada huwekwa kwenye dashibodi yako na kutumika kiotomatiki kabla ya viwango kurejeshwa.

• Ada ya asilimia: Hutumika kama asilimia ya gharama ya msingi ya kampuni ya usafirishaji.
• Ada thabiti: Kiasi kisichobadilika kinachoongezwa kwa kila shehena.
• Mabadiliko kwa njia mahususi: Badilisha ada ya jumla kwa jozi mahususi za asili/marudio.

Malipo ya Mwisho & Ubadilishaji Fedha

Pigee Pay hukusanya malipo kutoka kwa wateja wa mwisho kwa sarafu zaidi ya 135 na kulipa kwenye akaunti yako ya benki kwa sarafu yako ya nchi.

• Mzunguko wa malipo kwa kawaida ni siku 2 za kazi (T+2) baada ya uthibitisho wa uwasilishaji wa shehena.
• Toa fedha kutoka kwenye salio lako la Pigee kupitia dashibodi.
• Kumbukumbu za kina za miamala zinapatikana chini ya Fedha → Malipo Yaliyokamilika.
• Ankara za miamala iliyokamilika hutengenezwa kiotomatiki na zinapatikana kama PDF.

Webhooks

Pigee hutuma matukio ya wakati halisi kwenye sehemu yako ya mwisho ya HTTPS kama JSON POST maombi. Sanidi URL yako ya webhook katika Dashibodi → Mtengenezaji → 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"
  }
}

Rejeleo la Matukio ya Webhook

Saini za Webhook

Kila ombi la webhook linajumuisha X-Pigee-Signature kichwa, ambacho ni muhtasari wa HMAC-SHA256 wa maudhui ghafi ya ombi. Daima thibitisha hili kabla ya kuchakata.

// 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')
  );
}

Makosa

Makosa yote hurejesha JSON yenye error kitu chenye msimbo unaosomeka na mashine code na ujumbe unaosomeka na binadamu message.

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

Mipaka ya Kiwango

Kikomo cha maombi hutumika kwa kila ufunguo wa API na hutofautiana kulingana na ngazi ya akaunti yako.

Kikomo cha maombi kikifikiwa, API hurejesha HTTP 429 pamoja na Retry-After kichwa cha habari.

Aina za Data na Kanuni Zake

• Tarehe na saa - ISO 8601 UTC, mfano 2026-05-06T14:22:07Z
• Sarafu - misimbo ya herufi tatu ya ISO 4217, mfano GBP, USD, NGN
• Thamani za fedha - number zenye tarakimu mbili za desimali, na daima huambatana na sehemu ya currency sehemu
• Majina ya nchi - majina kamili kwa Kiingereza, mfano "United Kingdom", "United States"
• Namba za simu - muundo wa E.164 unapendekezwa, mfano +447700900123
• Uzito - kg au lbs unaobainishwa kwa kila ombi
• Vitambulisho - Vitambulisho vinavyotengenezwa na Pigee hutumia muundo wa kiambishi awali, mfano po_78910, cr_abc123

Rejea ya Vitambulisho vya Wasafirishaji

Tumia pigee_carrier_id thamani kutoka kwa jibu la bei wakati wa kuunda oda.

Kumbukumbu za Mabadiliko

v1.3 - Mei 2026

• Imeongezwa insurance_available na customs_included alama kwenye jibu la bei.
• Uthibitishaji wa sahihi ya webhook sasa unatumia HMAC-SHA256.
• Msimbo mpya wa hitilafu RATE_EXPIRED.
• Njia ya ufuatiliaji imeongezwa: GET /api/v1/tracking/{pigee_order_id}.

v1.2 - Februari 2026

• Imeongezwa uwezo wa kubadilisha ada za huduma kwa kila njia (lane) kwenye dashibodi.
• Viungo vya malipo vya Pigee Pay sasa vinajumuisha uga wa expires_at .
• Matukio mapya ya webhook yameongezwa kwa forodha na malipo ya mwisho (settlements).

v1.1 - Oktoba 2025

• Mkusanyiko wa awali wa Postman umechapishwa.
• Mazingira ya majaribio (Sandbox) yamezinduliwa.
• Njia ya malipo ya Salio la Akaunti imetolewa.

v1.0 - Juni 2025

• Toleo la kwanza la umma: Thibitisha, Pata Bei, Unda Oda, Timiza Oda.