API de Parceiros de Envio Pigee

Início rápido

Da criação da conta ao seu primeiro envio em produção em menos de uma hora. Siga estes cinco passos:

1. Crie uma conta Pigee Post gratuita em account.pigeepost.com e selecione Parceiro de Envios como tipo de conta.
2. Vá para Dashboard → Developer → API Keys e gere uma chave em produção e uma chave de teste.
3. Escolha o seu modo de pagamento: Pigee Pay ou Saldo de Conta Pigee.
4. Configure a sua taxa de serviço em Dashboard → Fees.
5. Importe a coleção Postman para desenvolvimento em staging.

Autenticação

Cada pedido deve incluir a sua chave API no Authorization cabeçalho como um token Bearer. As chaves têm âmbito na sua conta de parceiro e contêm a configuração da sua taxa e modo de pagamento.

Authorization: Bearer pgk_live_YOUR_API_KEY_HERE

Tipos de chave

Ambientes e URLs Base

O sandbox é um espelho completo 1:1 da produção. Alterne entre ambientes trocando o prefixo da sua chave, ou use a URL sandbox explícita para maior clareza.

SDKs e Bibliotecas

Os SDKs oficiais encapsulam a API REST com modelos tipados, tentativas automáticas e auxiliares de sandbox.

Validar Chave API

Chame este endpoint para confirmar que a sua chave API está ativa e corretamente configurada antes de entrar em produção.

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

Obter Tarifas de Envio

Obtenha tarifas de transportadoras em tempo real para um envio. Devolve todos os serviços disponíveis ordenados por preço, incluindo prazo de entrega, suporte a valor seguro e custo final.

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

Parâmetros de pedido

Criar Encomenda

Criar uma encomenda Pigee usando um carrier_request_id do endpoint de preços. A Pigee gera a etiqueta, a fatura comercial e, se utilizar Pigee Pay, uma ligação de pagamento alojada.

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

Executar Encomenda

Envie os dados finais de cumprimento assim que o pagamento for confirmado. A Pigee gera a etiqueta de envio, marca a transportadora e devolve um número de rastreamento.

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

Rastreamento

Recupere eventos de rastreamento em tempo real para qualquer encomenda criada através da 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"
    }
  ]
}

Modos de Pagamento

A Pigee suporta dois modos de pagamento. O modo ativo é configurado no seu painel de parceiro e aplica-se a todas as encomendas.

Taxas de Serviço

Como Parceiro de Envio, pode adicionar a sua própria taxa aos preços base da transportadora da Pigee. As taxas são configuradas no seu painel de controlo e aplicadas automaticamente antes dos preços serem devolvidos.

• Taxa percentual: Aplicada como uma percentagem do custo base da transportadora.
• Taxa fixa: Um montante fixo adicionado por encomenda.
• Substituições por rota: Substituir a taxa global para pares de origem/destino específicos.

Liquidações e Câmbio

Pigee Pay cobra dos clientes finais em 135+ moedas e efectua os pagamentos na sua conta bancária na sua moeda local.

• O ciclo de liquidação é tipicamente T+2 dias úteis após a confirmação da entrega.
• Levante fundos do seu saldo Pigee através do painel de controlo.
• Registos de transações detalhados estão disponíveis em Finanças → Liquidações.
• As facturas para transações liquidadas são geradas automaticamente e disponibilizadas em PDF.

Webhooks

Pigee envia eventos em tempo real para o seu endpoint HTTPS como pedidos JSON. POST Configure o seu URL de webhook em Painel de Controlo → Programador → 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"
  }
}

Referência de Eventos Webhook

Assinaturas de Webhook

Cada pedido de webhook inclui um X-Pigee-Signature cabeçalho, um resumo HMAC-SHA256 do corpo do pedido bruto. Sempre verifique isto antes de processar.

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

Erros

Todos os erros devolvem JSON com um error objeto contendo um code e um message.

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

Limites de Taxa

Limites de taxa são aplicados por chave de API e aumentam com o seu nível de conta.

Quando um limite de taxa é atingido, a API devolve HTTP 429 com um Retry-After cabeçalho.

Tipos de Dados e Convenções

• Datas e horas - ISO 8601 UTC, p.ex. 2026-05-06T14:22:07Z
• Moedas - Códigos ISO 4217 de três letras, p.ex. GBP, USD, NGN
• Valores monetários - number com duas casas decimais, sempre associado a um currency campo
• Nomes de países - Nomes completos em inglês, p.ex. "United Kingdom", "United States"
• Números de telefone - Formato E.164 recomendado, p.ex. +447700900123
• Pesos - kg ou lbs especificado por pedido
• IDs - IDs gerados pela Pigee usam formato de prefixo, p.ex. po_78910, cr_abc123

Referência de IDs de Transportadoras

Utilização pigee_carrier_id valores da resposta de tarifas ao criar encomendas.

Changelog

v1.3 - Maio 2026

• Adicionado insurance_available e customs_included sinalizadores à resposta de tarifas.
• Verificação de assinatura de webhook agora usa HMAC-SHA256.
• Novo código de erro RATE_EXPIRED.
• Endpoint de rastreamento adicionado: GET /api/v1/tracking/{pigee_order_id}.

v1.2 - Fevereiro 2026

• Adicionadas substituições de taxa de serviço por corredor no painel.
• Os links de pagamento do Pigee Pay agora incluem um expires_at campo.
• Novos eventos de webhook adicionados para aduanas e liquidações.

v1.1 - Outubro 2025

• Coleção inicial do Postman publicada.
• Ambiente sandbox lançado.
• Modo de pagamento Saldo da Conta lançado.

v1.0 - Junho 2025

• Lançamento público inicial: Validar, Obter Tarifas, Criar Pedido, Cumprir Pedido.