PostCargo REST API

Creeaza un cont nou + tenant + prima cheie API. Returneaza JWT + cheia API (afisata o singura data).

Body

{
  "tenant_name": "Magazinul Meu SRL",
  "email": "owner@magazin.ro",
  "password": "parola_min_8",
  "name": "Ion Popescu"
}

Response 201

{
  "success": true,
  "data": {
    "user": { "id": 1, "email": "owner@magazin.ro", "name": "Ion Popescu" },
    "tenant": { "id": 1, "name": "Magazinul Meu SRL", "plan": "free" },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "rfk_...",
    "api_key": "pcg_live_a1b2c3d4e5..."
  }
}

Login cu email + parola. Returneaza JWT + refresh token.

curl -X POST https://api.postcargo.ro/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"owner@magazin.ro","password":"parola"}'

Reinnoieste JWT folosind refresh token.

{ "refresh_token": "rfk_..." }

Listeaza toate cheile API ale tenant-ului — cu request_count + last_used_at + last_used_ip.

{
  "success": true,
  "data": [
    {
      "id": 1,
      "key_prefix": "pcg_live_a1b2",
      "label": "WooCommerce - Magazin principal",
      "permissions": ["*"],
      "is_active": true,
      "last_used_at": "2026-05-03T20:30:12+03:00",
      "last_used_ip": "82.77.123.45",
      "request_count": 1432,
      "expires_at": null,
      "created_at": "2026-05-01T18:00:00+03:00"
    }
  ]
}

Genereaza o cheie noua. Cheia complet apare o singura data in raspuns; salveaza-o.

// Body
{
  "label": "WooCommerce - magazin nou",
  "permissions": ["pricing:read", "shipments:create", "awb:create"],
  "expires_in_days": 365
}

// Response
{
  "success": true,
  "data": {
    "id": 5,
    "label": "WooCommerce - magazin nou",
    "api_key": "pcg_live_xxxxxxxxxxxxxxxxxxxx",
    "key_prefix": "pcg_live_xxxx"
  }
}

Loguri detaliate pe o cheie. Filtre disponibile: ?page=1&per_page=50&status=200&platform=woocommerce&from=2026-05-01&to=2026-05-31

{
  "success": true,
  "data": {
    "key": { "id": 1, "label": "...", "request_count": 1432 },
    "stats_24h": { "total": 245, "success": 240, "errors": 5, "avg_ms": 187 },
    "logs": [
      {
        "id": 9876, "method": "POST", "endpoint": "/v1/pricing/quote",
        "status_code": 200, "duration_ms": 215, "ip": "82.77.x",
        "source_platform": "woocommerce", "created_at": "..."
      }
    ]
  },
  "meta": { "page": 1, "per_page": 50, "total": 1432, "total_pages": 29 }
}

Stats agregate (toate cheile, ultimele 7-90 zile). ?days=7

{
  "data": {
    "totals": { "total": 12450, "success": 12200, "errors": 250, "avg_ms": 195 },
    "by_day": [{ "day": "2026-05-01", "total": 1820, "success": 1810, "errors": 10 }],
    "by_platform": [{ "platform": "woocommerce", "total": 11230 }],
    "top_endpoints": [{ "endpoint": "/v1/pricing/quote", "total": 6420 }]
  }
}

Revoca cheia. Integrarea care o foloseste va inceta sa functioneze imediat.

{ "success": true, "data": { "status": "ok", "version": "1.0.0", "php": "8.3.30" } }

Lista publica a celor 12 curieri integrati (logo, descriere, pret pornire, features).

Calculeaza pretul pentru toti curierii activi simultan. Recomandat pentru checkout in WooCommerce/Shopify.

Body

{
  "from": { "city": "Bucuresti", "county": "Bucuresti", "postcode": "010101" },
  "to":   { "city": "Cluj-Napoca", "county": "Cluj", "postcode": "400001" },
  "package": {
    "type": "colet",
    "weight": 2.5,
    "length": 30, "width": 20, "height": 15,
    "value_declared": 250,
    "cod_amount": 0
  },
  "options": {
    "saturday_delivery": false,
    "open_on_delivery": false,
    "insurance": true
  }
}

Response

{
  "success": true,
  "data": [
    {
      "courier": "fan-courier",
      "courier_name": "FAN Courier",
      "price": 28.50,
      "price_with_vat": 33.92,
      "estimated_days": "1-2 zile",
      "logo": "https://api.postcargo.ro/assets/couriers/fan-courier.svg"
    },
    {
      "courier": "cargus",
      "courier_name": "Urgent Cargus",
      "price": 25.20,
      "price_with_vat": 30.50,
      "estimated_days": "1-3 zile"
    }
  ]
}

Pret pentru un singur curier specific. Body identic cu /quote, plus "courier": "fan-courier".

Creeaza expediere fara generare AWB (status: draft). AWB se genereaza separat (vezi /v1/awb).

{
  "courier_code": "fan-courier",
  "external_id": "wc_order_1234",
  "sender": {
    "name": "Magazinul Meu", "phone": "0712345678",
    "city": "Bucuresti", "county": "Bucuresti",
    "address": "Str Exemplu 10", "postcode": "010101"
  },
  "recipient": {
    "name": "Maria Popescu", "phone": "0723456789",
    "city": "Cluj-Napoca", "county": "Cluj",
    "address": "Str Aurel Vlaicu 25", "postcode": "400001"
  },
  "package": {
    "type": "colet", "weight": 2.5,
    "length": 30, "width": 20, "height": 15,
    "value_declared": 250,
    "cod_amount": 0,
    "content": "Carti, articole personale"
  }
}

Filtre: ?status=delivered&courier=fan-courier&page=1&per_page=50&from=2026-05-01

Detaliile complete (sender, recipient, package, awb, tracking history).

Anuleaza la curier (daca AWB nu e inca preluat). Body optional: {"reason": "Cumparator a anulat"}

Tracking events live de la curier.

{
  "data": {
    "awb_number": "1234567890",
    "status": "in_transit",
    "events": [
      { "date": "2026-05-03T09:15:00", "status": "preluat", "location": "Bucuresti" },
      { "date": "2026-05-03T18:30:00", "status": "in_tranzit", "location": "Cluj-Napoca" }
    ]
  }
}

Genereaza AWB la curierul ales. Returneaza numarul AWB + URL PDF.

{
  "data": {
    "awb_number": "1234567890",
    "courier": "fan-courier",
    "pdf_url": "https://api.postcargo.ro/v1/awb/1234567890/pdf",
    "tracking_url": "https://www.fancourier.ro/awb-tracking/?awb=1234567890"
  }
}

Returneaza PDF binar al AWB-ului. Headers: Content-Type: application/pdf.

Lista celor 12 curieri PostCargo cu detalii (logo, descriere, features, pret pornire) si flag is_enabled pentru tenant.

Activeaza/dezactiveaza un curier pentru contul tau. Body: {"is_active": true}

Stats agregate: total expedieri, by status, by courier, ultimele 5.

Lista webhook-urilor configurate.

Configureaza un webhook care primeste evenimente (shipment.created, shipment.delivered, awb.generated, etc).

{
  "url": "https://magazin.ro/postcargo-webhook",
  "events": ["shipment.delivered", "shipment.cancelled"],
  "secret": "secret_pentru_HMAC"
}

Lista pluginurilor disponibile (WooCommerce activ; Shopify, PrestaShop in lucru).

Versiune curenta plugin, cerinte WP/WooCommerce, marime, data ultimului build.

Descarca postcargo-shipping.zip direct. Auto-build cand sursa devine mai noua decat .zip-ul cached.