Paczuszka.com API — dokumentacja

Jak się połączyć

Jak uzyskać klucz API?

Dostęp do API nie jest włączany automatycznie. Napisz na biuro@adgenius.pl i podaj nazwę firmy, adres swojej strony lub sklepu, planowany sposób użycia API oraz informację, czy potrzebujesz tylko wycen, czy również tworzenia przesyłek. Po akceptacji otrzymasz osobny klucz testowy i odpowiednie uprawnienia. Klucz produkcyjny zostanie wydany po poprawnym zakończeniu testów integracji.

1. Adres API

Wszystkie zapytania wysyłaj pod adres bazowy:

https://api.paczuszka.com/v1

Przykład wyceny:
POST /v1/quotes

2. Klucz dostępu

Klucz otrzymasz po kontakcie z biuro@adgenius.pl. Wysyłaj go w nagłówku każdego zapytania:

X-API-Key: pacz_test_...

Nie umieszczaj klucza w adresie URL ani w kodzie strony internetowej.

3. Format danych

Dane wejściowe i odpowiedzi mają format JSON i kodowanie UTF-8.

Dla zapytań POST dodaj:

Content-Type: application/json

Daty: ISO 8601, kraje: dwuliterowe kody ISO, np. PL.

Typowa kolejność integracji:

Pobierz kraje, usługi i opcje z GET /resources.
Wykonaj wycenę przez POST /quotes.
W ciągu 15 minut użyj otrzymanych quote_id i offer_id do utworzenia zamówienia.
Sprawdzaj status przez GET /orders/{order_id}.
Po przygotowaniu przesyłki pobierz etykietę z GET /orders/{order_id}/label.

Pierwsze zapytanie — wycena

curl -X POST "https://api.paczuszka.com/v1/quotes" \
  -H "X-API-Key: pacz_test_TUTAJ_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment_type": "parcel",
    "origin": {"country_code": "PL", "postal_code": "62-045"},
    "destination": {"country_code": "PL", "postal_code": "00-001"},
    "packages": [{
      "weight_kg": 5,
      "length_cm": 40,
      "width_cm": 30,
      "height_cm": 20,
      "quantity": 1,
      "non_standard": false,
      "insurance_amount": 500
    }],
    "cash_on_delivery": {"amount": 0},
    "options": []
  }'

Środowisko testowe

Klucze zaczynające się od pacz_test_ nie zamawiają prawdziwego kuriera i nie pobierają pieniędzy. Służą do bezpiecznych prób integracji.

Środowisko produkcyjne

Klucze pacz_live_ wykonują prawdziwe operacje. Przechowuj je wyłącznie po stronie serwera i nigdy nie pokazuj klientom sklepu.

Bezpieczne ponawianie

Dla zamówień i anulowania wymagany jest nagłówek Idempotency-Key. Ponowienie tej samej operacji z tym samym kluczem nie utworzy duplikatu.

Ważne: odpowiedź błędu zawsze zawiera request_id, error_code, opis oraz listę błędnych pól. Przy zgłoszeniu problemu podaj nam request_id.