API Shipping Partner Pigee

Guida rapida

Dal momento in cui crei l'account al tuo primo spedimento live in meno di un'ora. Segui questi cinque passaggi:

1. Crea un account Pigee gratuito su account.pigeepost.com e seleziona Shipping Partner come tipo di account.
2. Vai a Dashboard → Developer → API Keys e genera una chiave live e una chiave di test.
3. Scegli la modalità di pagamento: Pigee Pay oppure Saldo account Pigee.
4. Configura la tua commissione servizio in Pannello di controllo → Commissioni.
5. Importa la collezione Postman per lo sviluppo in staging.

Autenticazione

Ogni richiesta deve includere la tua API key nell' Authorization intestazione come token Bearer. Le chiavi sono associate al tuo account partner e includono la tua configurazione commissioni e la modalità di pagamento.

Authorization: Bearer pgk_live_YOUR_API_KEY_HERE

Tipi di chiave

Ambienti e URL di base

La sandbox è uno specchio completo 1:1 della produzione. Cambia ambiente scambiando il prefisso della tua chiave, oppure usa l'URL sandbox esplicito per maggiore chiarezza.

SDK e librerie

Gli SDK ufficiali incapsulano l'API REST con modelli tipizzati, tentativi automatici e helper sandbox.

Convalida Chiave API

Chiama questo endpoint per confermare che la tua chiave API è attiva e configurata correttamente prima di andare live.

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

Ottieni Tariffe di Spedizione

Recupera le tariffe live dei vettori per una spedizione. Restituisce tutti i servizi disponibili ordinati per prezzo, incluso il tempo di transito, il supporto del valore assicurato e il costo sbarcato.

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

Parametri della richiesta

Crea ordine

Crea un ordine Pigee utilizzando una carrier_request_id dall'endpoint tariffe. Pigee genera l'etichetta, la fattura commerciale e, se utilizzi Pigee Pay, un link di pagamento ospitato.

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

Evadi ordine

Invia i dettagli di evasione finale una volta confermato il pagamento. Pigee genera l'etichetta di spedizione, prenota il vettore e restituisce un numero di tracciamento.

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

Tracciamento

Recupera gli eventi di tracciamento in tempo reale per qualsiasi spedizione creata tramite 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"
    }
  ]
}

Modalità di pagamento

Pigee supporta due modalità di pagamento. La modalità attiva è impostata nel tuo pannello partner e si applica a tutti gli ordini.

Commissioni di servizio

Come Shipping Partner puoi aggiungere una commissione propria sulle tariffe base dei corrieri di Pigee. Le commissioni sono configurate nel tuo pannello e applicate automaticamente prima della restituzione delle tariffe.

• Commissione percentuale: Applicata come percentuale del costo del corriere base.
• Commissione fissa: Un importo fisso aggiunto per spedizione.
• Sovraccarichi per tratta: Sovrascrivi la commissione globale per coppie di origine/destinazione specifiche.

Liquidazioni e cambio

Pigee Pay raccoglie da clienti finali in 135+ valute e liquida sul tuo conto bancario nella tua valuta locale.

• Il ciclo di liquidazione è generalmente T+2 giorni lavorativi dopo la conferma di consegna della spedizione.
• Preleva dal tuo saldo Pigee tramite il pannello.
• I registri transazionali dettagliati sono disponibili in Finanza → Liquidazioni.
• Le fatture per le transazioni liquidate vengono generate automaticamente e sono disponibili in PDF.

Webhook

Pigee invia eventi in tempo reale al tuo endpoint HTTPS come richieste JSON POST Configura l'URL del tuo webhook in Pannello → Sviluppatore → Webhook.

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

Riferimento evento webhook

Firme webhook

Ogni richiesta webhook include un X-Pigee-Signature header, un digest HMAC-SHA256 del corpo della richiesta raw. Verificare sempre prima di elaborare.

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

Errori

Tutti gli errori restituiscono JSON con un error oggetto contenente un code e un message.

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

Limiti di velocità

I limiti di velocità vengono applicati per chiave API e scalano con il livello del tuo account.

Quando viene raggiunto un limite di velocità, l'API restituisce HTTP 429 con un Retry-After header.

Tipi di dati e convenzioni

• Date e orari - ISO 8601 UTC, ad es. 2026-05-06T14:22:07Z
• Valute - Codici ISO 4217 a tre lettere, ad es. GBP, USD, NGN
• Valori monetari - number con due decimali, sempre accoppiato a un currency field
• Nomi dei paesi - Nomi completi in inglese, ad es. "United Kingdom", "United States"
• Numeri di telefono - Formato E.164 consigliato, ad es. +447700900123
• Pesi - kg oppure lbs specificato per richiesta
• ID - Gli ID generati da Pigee utilizzano il formato con prefisso, ad es. po_78910, cr_abc123

Riferimento ID Vettore

Utilizzo pigee_carrier_id valori della risposta tariffaria durante la creazione degli ordini.

Cronologia modifiche

v1.3 - maggio 2026

• Aggiunto insurance_available e customs_included flag nella risposta tariffaria.
• La verifica della firma webhook ora utilizza HMAC-SHA256.
• Nuovo codice di errore RATE_EXPIRED.
• Endpoint di tracciamento aggiunto: GET /api/v1/tracking/{pigee_order_id}.

v1.2 - febbraio 2026

• Aggiunti override delle commissioni per corsia nel dashboard.
• I link di pagamento Pigee Pay ora includono un expires_at campo.
• Nuovi eventi webhook aggiunti per dogana e accordamenti.

v1.1 - Ottobre 2025

• Collezione Postman iniziale pubblicata.
• Ambiente sandbox lanciato.
• Modalità di pagamento Saldo conto rilasciata.

v1.0 - Giugno 2025

• Versione pubblica iniziale: Convalida, Ottieni tariffe, Crea ordine, Evadi ordine.