Przejdź do treści

Faktury zamówienia

GET /order/checkout-forms/{checkoutFormId}/invoices

Allegro + rozszerzeniaallegro:api:orders:readlimit: read

Faktury dodane do zamówienia (pliki PDF i linki). Plik pobierzesz podpisanym adresem allee.downloadUrl (ważny 5 minut). Kupujący widzi „Pobierz fakturę” w swoim koncie.

Zamówieniami allee.pl sprzedawcy obsługuje jedna integracja naraz (wybór w panelu sprzedaży → Integracje); inna aplikacja dostaje 403 ORDERS_OWNED_BY_OTHER_INTEGRATION (details.owner: PANEL, OTHER_APP, BASELINKER).

Zgodność: zgodna z Allegro REST API, z rozszerzeniami allee (pola allee.*, alleeId) — GET /order/checkout-forms/{id}/invoices.
Uprawnienie: zakres allegro:api:orders:read.
Grupa limitu: read.

Parametry ścieżki

checkoutFormId string · uuid wymagany

Identyfikator zamówienia (UUID, checkoutForm.id).

Odpowiedzi

200 Faktury. · InvoiceList
invoices array<Invoice> zawsze
Pola obiektu
id string · uuid zawsze
invoiceNumber string · null zawsze
createdAt string · date-time zawsze
file object · null zawsze

Plik PDF (null dla faktury-linku albo przed wgraniem pliku).

Pola obiektu
id string zawsze
name string zawsze
uploadedAt string · date-time · null zawsze
securityVerification object zawsze

Kontrola bezpieczeństwa PDF (nagłówek, brak treści aktywnych, rozmiar).

Pola obiektu
status string zawsze
Wartości: ACCEPTED, REJECTED, PENDING
passedChecks array<string> zawsze
failedChecks array<string> zawsze
allee object zawsze
Pola obiektu
type string zawsze
Wartości: FILE, LINK
status string zawsze
Wartości: READY, WAITING_FOR_FILE
size integer · null zawsze
url string · null zawsze

Adres faktury-linku.

downloadUrl string · uri · null zawsze

Podpisany adres pobrania pliku (5 minut).

downloadUrlExpiresAt string · date-time · null zawsze
hasExternalInvoices boolean zawsze

Czy są faktury dodane przez integratora.

Błędy

HTTPKodZnaczenie
401invalid_tokenBrak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate).
403ACCOUNT_INACTIVEKonto sprzedawcy jest nieaktywne.
403AccessDeniedBrak zakresu albo zasób innego sprzedawcy.
403KEY_QUARANTINEDKwarantanna: działa tylko odczyt (wykryto nietypowe użycie).
403KEY_SUSPENDEDKlucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę).
403ORDERS_OWNED_BY_OTHER_INTEGRATIONZamówienia sprzedawcy obsługuje inna integracja (details.owner).
404NOT_FOUNDNie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama).
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
503NOT_DEPLOYEDFunkcja jeszcze nie uruchomiona (np. sandbox, wsady).
Przykład
curl -sS -X GET "${ALLEE_API_URL:-https://api.allee.pl}/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices" \
  -H "Authorization: Bearer $ALLEE_API_KEY" \
  -H "Accept: application/vnd.allegro.public.v1+json" \
  -w '\nHTTP %{http_code}\n'
Odpowiedź (środowisko testowe)
HTTP 200 application/vnd.allegro.public.v1+json
{
  "invoices": [
    {
      "id": "5551b5a7-3e2e-4cba-b80d-d34fd7e286ae",
      "invoiceNumber": "FV/1/11/2026",
      "createdAt": "2026-11-10T11:10:05.457Z",
      "file": {
        "id": "5551b5a7-3e2e-4cba-b80d-d34fd7e286ae",
        "name": "FV-1-11-2026.pdf",
        "uploadedAt": "2026-11-10T11:10:05.461Z",
        "securityVerification": {
          "status": "ACCEPTED",
          "passedChecks": [
            "PDF_HEADER",
            "PDF_EOF",
            "NO_ACTIVE_CONTENT",
            "COMPRESSED_STREAMS_SCANNED",
            "MAX_SIZE_3MB"
          ],
          "failedChecks": []
        }
      },
      "allee": {
        "type": "FILE",
        "status": "READY",
        "size": 622,
        "url": null,
        "downloadUrl": "https://api.allee.pl/allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file?expires=1794309305&mode=test&signature=…",
        "downloadUrlExpiresAt": "2026-11-10T11:15:05.000Z"
      }
    },
    {
      "id": "68df84ab-298c-4fa5-aaf9-30b90f3af67a",
      "invoiceNumber": "FK/1/11/2026",
      "createdAt": "2026-11-10T11:10:05.465Z",
      "file": {
        "id": "68df84ab-298c-4fa5-aaf9-30b90f3af67a",
        "name": "2026.pdf",
        "uploadedAt": "2026-11-10T11:10:05.465Z",
        "securityVerification": {
          "status": "ACCEPTED",
          "passedChecks": [
            "PDF_HEADER",
            "PDF_EOF",
            "NO_ACTIVE_CONTENT",
            "COMPRESSED_STREAMS_SCANNED",
            "MAX_SIZE_3MB"
          ],
          "failedChecks": []
        }
      },
      "allee": {
        "type": "FILE",
        "status": "READY",
        "size": 622,
        "url": null,
        "downloadUrl": "https://api.allee.pl/allee/billing-documents/68df84ab-298c-4fa5-aaf9-30b90f3af67a/file?expires=1794309305&mode=test&signature=…",
        "downloadUrlExpiresAt": "2026-11-10T11:15:05.000Z"
      }
    },
    {
      "id": "269a4823-f164-4ed9-8567-571fda81ad5d",
      "invoiceNumber": "FV/2/11/2026",
      "createdAt": "2026-11-10T11:10:05.468Z",
      "file": null,
      "allee": {
        "type": "LINK",
        "status": "READY",
        "size": null,
        "url": "https://faktury.example.com/fv/2-11-2026",
        "downloadUrl": null,
        "downloadUrlExpiresAt": null
      }
    }
  ],
  "hasExternalInvoices": true
}

Faktura — zapowiedź (krok 1 z 2)

POST /order/checkout-forms/{checkoutFormId}/invoices

zgodna z Allegroallegro:api:orders:writelimit: write

Jak Allegro: najpierw zapowiedź faktury (nazwa pliku, numer), potem plik PUT …/invoices/{invoiceId}/file. Najwyżej 10 faktur na zamówienie.

Zamówieniami allee.pl sprzedawcy obsługuje jedna integracja naraz (wybór w panelu sprzedaży → Integracje); inna aplikacja dostaje 403 ORDERS_OWNED_BY_OTHER_INTEGRATION (details.owner: PANEL, OTHER_APP, BASELINKER).

Zgodność: zgodna z Allegro REST API (ten sam kształt) — POST /order/checkout-forms/{id}/invoices.
Uprawnienie: zakres allegro:api:orders:write.
Grupa limitu: write.

Parametry ścieżki

checkoutFormId string · uuid wymagany

Identyfikator zamówienia (UUID, checkoutForm.id).

Nagłówki

Idempotency-Key string

Ochrona przed podwójnym wykonaniem (jak Stripe/Amazon): powtórzony POST z tym samym kluczem i tą samą treścią w ciągu 24 h zwraca zapisaną odpowiedź z nagłówkiem Idempotent-Replayed: true i niczego nie wykonuje drugi raz. Inna treść → 422 IDEMPOTENCY_KEY_REUSED; żądanie jeszcze trwa → 409 IDEMPOTENCY_KEY_IN_USE. 1–100 znaków ASCII (np. UUID).

Treść żądania application/vnd.allegro.public.v1+json

file object wymagane
Pola obiektu
name string wymagane

Nazwa pliku PDF.

invoiceNumber string

Numer faktury.

Odpowiedzi

201 Zapowiedziano — teraz wgraj plik. · InvoiceCreated
id string · uuid zawsze

Błędy

HTTPKodZnaczenie
401invalid_tokenBrak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate).
403ACCOUNT_INACTIVEKonto sprzedawcy jest nieaktywne.
403AccessDeniedBrak zakresu albo zasób innego sprzedawcy.
403KEY_QUARANTINEDKwarantanna: działa tylko odczyt (wykryto nietypowe użycie).
403KEY_SUSPENDEDKlucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę).
403ORDERS_OWNED_BY_OTHER_INTEGRATIONZamówienia sprzedawcy obsługuje inna integracja (details.owner).
404NOT_FOUNDNie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama).
413PAYLOAD_TOO_LARGETreść żądania za duża (JSON 5 MB, faktura PDF 3 MB).
415UNSUPPORTED_MEDIA_TYPEZły Content-Type treści.
422ConstraintViolationException.MissingRequiredParametersBrak wymaganego parametru lub pola (details = id parametru).
422JsonMappingExceptionTreść nie jest poprawnym JSON albo ma zły kształt (np. images jako obiekty).
422TOO_MANY_INVOICESNajwyżej 10 faktur na zamówienie.
422UnknownJSONPropertyPole nieznane w tym miejscu (path wskazuje które).
422VALIDATION_ERRORZła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
503NOT_DEPLOYEDFunkcja jeszcze nie uruchomiona (np. sandbox, wsady).
Przykład
curl -sS -X POST "${ALLEE_API_URL:-https://api.allee.pl}/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices" \
  -H "Authorization: Bearer $ALLEE_API_KEY" \
  -H "Accept: application/vnd.allegro.public.v1+json" \
  -H "Content-Type: application/vnd.allegro.public.v1+json" \
  --data-binary @- \
  -w '\nHTTP %{http_code}\n' <<'JSON'
{
  "file": {
    "name": "FV-1-11-2026.pdf"
  },
  "invoiceNumber": "FV/1/11/2026"
}
JSON
Odpowiedź (środowisko testowe)
HTTP 201 application/vnd.allegro.public.v1+json
{
  "id": "5551b5a7-3e2e-4cba-b80d-d34fd7e286ae"
}

Faktura — plik PDF (krok 2 z 2)

PUT /order/checkout-forms/{checkoutFormId}/invoices/{invoiceId}/file

zgodna z Allegroallegro:api:orders:writelimit: write

Treść żądania = plik PDF (Content-Type: application/pdf, do 3 MB). Sprawdzamy nagłówek i zakończenie PDF oraz brak treści aktywnych (JavaScript, akcje) — wynik w file.securityVerification. Plik trafia do magazynu poza serwerem WWW.

Zamówieniami allee.pl sprzedawcy obsługuje jedna integracja naraz (wybór w panelu sprzedaży → Integracje); inna aplikacja dostaje 403 ORDERS_OWNED_BY_OTHER_INTEGRATION (details.owner: PANEL, OTHER_APP, BASELINKER).

Zgodność: zgodna z Allegro REST API (ten sam kształt) — PUT /order/checkout-forms/{id}/invoices/{invoiceId}/file.
Uprawnienie: zakres allegro:api:orders:write.
Grupa limitu: write.

Parametry ścieżki

checkoutFormId string · uuid wymagany

Identyfikator zamówienia (UUID, checkoutForm.id).

invoiceId string wymagany

Identyfikator faktury z kroku 1.

Treść żądania application/pdf

Plik PDF faktury.

Typ: string · binary

Odpowiedzi

200 Plik przyjęty. · Invoice
id string · uuid zawsze
invoiceNumber string · null zawsze
createdAt string · date-time zawsze
file object · null zawsze

Plik PDF (null dla faktury-linku albo przed wgraniem pliku).

Pola obiektu
id string zawsze
name string zawsze
uploadedAt string · date-time · null zawsze
securityVerification object zawsze

Kontrola bezpieczeństwa PDF (nagłówek, brak treści aktywnych, rozmiar).

Pola obiektu
status string zawsze
Wartości: ACCEPTED, REJECTED, PENDING
passedChecks array<string> zawsze
failedChecks array<string> zawsze
allee object zawsze
Pola obiektu
type string zawsze
Wartości: FILE, LINK
status string zawsze
Wartości: READY, WAITING_FOR_FILE
size integer · null zawsze
url string · null zawsze

Adres faktury-linku.

downloadUrl string · uri · null zawsze

Podpisany adres pobrania pliku (5 minut).

downloadUrlExpiresAt string · date-time · null zawsze

Błędy

HTTPKodZnaczenie
401invalid_tokenBrak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate).
403ACCOUNT_INACTIVEKonto sprzedawcy jest nieaktywne.
403AccessDeniedBrak zakresu albo zasób innego sprzedawcy.
403KEY_QUARANTINEDKwarantanna: działa tylko odczyt (wykryto nietypowe użycie).
403KEY_SUSPENDEDKlucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę).
403ORDERS_OWNED_BY_OTHER_INTEGRATIONZamówienia sprzedawcy obsługuje inna integracja (details.owner).
404NOT_FOUNDNie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama).
409INVOICE_FILE_ALREADY_UPLOADEDPlik tej faktury już wgrany.
413PAYLOAD_TOO_LARGETreść żądania za duża (JSON 5 MB, faktura PDF 3 MB).
415UNSUPPORTED_MEDIA_TYPEZły Content-Type treści.
422VALIDATION_ERRORZła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.
429BUSYTa sama operacja trwa równolegle.
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
503NOT_DEPLOYEDFunkcja jeszcze nie uruchomiona (np. sandbox, wsady).
503STORAGE_UNAVAILABLEMagazyn plików chwilowo niedostępny.
Przykład
curl -sS -X PUT "${ALLEE_API_URL:-https://api.allee.pl}/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file" \
  -H "Authorization: Bearer $ALLEE_API_KEY" \
  -H "Accept: application/vnd.allegro.public.v1+json" \
  -H "Content-Type: application/pdf" \
  --data-binary @faktura.pdf \
  -w '\nHTTP %{http_code}\n'
Odpowiedź (środowisko testowe)
HTTP 200 application/vnd.allegro.public.v1+json
{
  "id": "5551b5a7-3e2e-4cba-b80d-d34fd7e286ae",
  "invoiceNumber": "FV/1/11/2026",
  "createdAt": "2026-11-10T11:10:05.457Z",
  "file": {
    "id": "5551b5a7-3e2e-4cba-b80d-d34fd7e286ae",
    "name": "FV-1-11-2026.pdf",
    "uploadedAt": "2026-11-10T11:10:05.461Z",
    "securityVerification": {
      "status": "ACCEPTED",
      "passedChecks": [
        "PDF_HEADER",
        "PDF_EOF",
        "NO_ACTIVE_CONTENT",
        "COMPRESSED_STREAMS_SCANNED",
        "MAX_SIZE_3MB"
      ],
      "failedChecks": []
    }
  },
  "allee": {
    "type": "FILE",
    "status": "READY",
    "size": 622,
    "url": null,
    "downloadUrl": "https://api.allee.pl/allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file?expires=1794309305&mode=test&signature=…",
    "downloadUrlExpiresAt": "2026-11-10T11:15:05.000Z"
  }
}

Faktura PDF jednym żądaniem

POST /order/{checkoutFormId}/billing-documents/files

tylko alleeallegro:api:orders:writelimit: write

Plik PDF jednym żądaniem: treść = PDF (Content-Type: application/pdf, numer w ?invoiceNumber=) albo multipart/form-data (pole file + invoiceNumber). Te same kontrole co w kroku 2.

Zamówieniami allee.pl sprzedawcy obsługuje jedna integracja naraz (wybór w panelu sprzedaży → Integracje); inna aplikacja dostaje 403 ORDERS_OWNED_BY_OTHER_INTEGRATION (details.owner: PANEL, OTHER_APP, BASELINKER).

Zgodność: tylko allee — Rozszerzenie allee (Allegro: dwa kroki).
Uprawnienie: zakres allegro:api:orders:write.
Grupa limitu: write.

Parametry ścieżki

checkoutFormId string · uuid wymagany

Identyfikator zamówienia (UUID, checkoutForm.id).

Parametry zapytania

invoiceNumber string

Numer faktury.

fileName string

Nazwa pliku. Domyślnie z numeru faktury, ale tylko ostatni człon po „/” (FK/1/11/2026 daje 2026.pdf) — przy numerach z ukośnikami podaj fileName.

Treść żądania application/pdf

Plik PDF (albo multipart/form-data z polem file).

Typ: string · binary

Odpowiedzi

201 Dodano. · Invoice
id string · uuid zawsze
invoiceNumber string · null zawsze
createdAt string · date-time zawsze
file object · null zawsze

Plik PDF (null dla faktury-linku albo przed wgraniem pliku).

Pola obiektu
id string zawsze
name string zawsze
uploadedAt string · date-time · null zawsze
securityVerification object zawsze

Kontrola bezpieczeństwa PDF (nagłówek, brak treści aktywnych, rozmiar).

Pola obiektu
status string zawsze
Wartości: ACCEPTED, REJECTED, PENDING
passedChecks array<string> zawsze
failedChecks array<string> zawsze
allee object zawsze
Pola obiektu
type string zawsze
Wartości: FILE, LINK
status string zawsze
Wartości: READY, WAITING_FOR_FILE
size integer · null zawsze
url string · null zawsze

Adres faktury-linku.

downloadUrl string · uri · null zawsze

Podpisany adres pobrania pliku (5 minut).

downloadUrlExpiresAt string · date-time · null zawsze

Błędy

HTTPKodZnaczenie
401invalid_tokenBrak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate).
403ACCOUNT_INACTIVEKonto sprzedawcy jest nieaktywne.
403AccessDeniedBrak zakresu albo zasób innego sprzedawcy.
403KEY_QUARANTINEDKwarantanna: działa tylko odczyt (wykryto nietypowe użycie).
403KEY_SUSPENDEDKlucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę).
403ORDERS_OWNED_BY_OTHER_INTEGRATIONZamówienia sprzedawcy obsługuje inna integracja (details.owner).
404NOT_FOUNDNie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama).
413PAYLOAD_TOO_LARGETreść żądania za duża (JSON 5 MB, faktura PDF 3 MB).
415UNSUPPORTED_MEDIA_TYPEZły Content-Type treści.
422TOO_MANY_INVOICESNajwyżej 10 faktur na zamówienie.
422VALIDATION_ERRORZła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.
429BUSYTa sama operacja trwa równolegle.
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
503NOT_DEPLOYEDFunkcja jeszcze nie uruchomiona (np. sandbox, wsady).
503STORAGE_UNAVAILABLEMagazyn plików chwilowo niedostępny.
Przykład
curl -sS -X POST "${ALLEE_API_URL:-https://api.allee.pl}/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/files?invoiceNumber=FK%2F1%2F11%2F2026" \
  -H "Authorization: Bearer $ALLEE_API_KEY" \
  -H "Accept: application/vnd.allegro.public.v1+json" \
  -H "Content-Type: application/pdf" \
  --data-binary @faktura.pdf \
  -w '\nHTTP %{http_code}\n'
Odpowiedź (środowisko testowe)
HTTP 201 application/vnd.allegro.public.v1+json
{
  "id": "68df84ab-298c-4fa5-aaf9-30b90f3af67a",
  "invoiceNumber": "FK/1/11/2026",
  "createdAt": "2026-11-10T11:10:05.465Z",
  "file": {
    "id": "68df84ab-298c-4fa5-aaf9-30b90f3af67a",
    "name": "2026.pdf",
    "uploadedAt": "2026-11-10T11:10:05.465Z",
    "securityVerification": {
      "status": "ACCEPTED",
      "passedChecks": [
        "PDF_HEADER",
        "PDF_EOF",
        "NO_ACTIVE_CONTENT",
        "COMPRESSED_STREAMS_SCANNED",
        "MAX_SIZE_3MB"
      ],
      "failedChecks": []
    }
  },
  "allee": {
    "type": "FILE",
    "status": "READY",
    "size": 622,
    "url": null,
    "downloadUrl": "https://api.allee.pl/allee/billing-documents/68df84ab-298c-4fa5-aaf9-30b90f3af67a/file?expires=1794309305&mode=test&signature=…",
    "downloadUrlExpiresAt": "2026-11-10T11:15:05.000Z"
  }
}

POST /order/{checkoutFormId}/billing-documents/links

tylko alleeallegro:api:orders:writelimit: write

Faktura wystawiona w Twoim systemie — podajesz adres https; kupujący dostaje link.

Zamówieniami allee.pl sprzedawcy obsługuje jedna integracja naraz (wybór w panelu sprzedaży → Integracje); inna aplikacja dostaje 403 ORDERS_OWNED_BY_OTHER_INTEGRATION (details.owner: PANEL, OTHER_APP, BASELINKER).

Zgodność: tylko allee — Rozszerzenie allee.
Uprawnienie: zakres allegro:api:orders:write.
Grupa limitu: write.

Parametry ścieżki

checkoutFormId string · uuid wymagany

Identyfikator zamówienia (UUID, checkoutForm.id).

Nagłówki

Idempotency-Key string

Ochrona przed podwójnym wykonaniem (jak Stripe/Amazon): powtórzony POST z tym samym kluczem i tą samą treścią w ciągu 24 h zwraca zapisaną odpowiedź z nagłówkiem Idempotent-Replayed: true i niczego nie wykonuje drugi raz. Inna treść → 422 IDEMPOTENCY_KEY_REUSED; żądanie jeszcze trwa → 409 IDEMPOTENCY_KEY_IN_USE. 1–100 znaków ASCII (np. UUID).

Treść żądania application/vnd.allegro.public.v1+json

url string · uri wymagane

Adres https faktury u Ciebie.

invoiceNumber string

Odpowiedzi

201 Dodano. · Invoice
id string · uuid zawsze
invoiceNumber string · null zawsze
createdAt string · date-time zawsze
file object · null zawsze

Plik PDF (null dla faktury-linku albo przed wgraniem pliku).

Pola obiektu
id string zawsze
name string zawsze
uploadedAt string · date-time · null zawsze
securityVerification object zawsze

Kontrola bezpieczeństwa PDF (nagłówek, brak treści aktywnych, rozmiar).

Pola obiektu
status string zawsze
Wartości: ACCEPTED, REJECTED, PENDING
passedChecks array<string> zawsze
failedChecks array<string> zawsze
allee object zawsze
Pola obiektu
type string zawsze
Wartości: FILE, LINK
status string zawsze
Wartości: READY, WAITING_FOR_FILE
size integer · null zawsze
url string · null zawsze

Adres faktury-linku.

downloadUrl string · uri · null zawsze

Podpisany adres pobrania pliku (5 minut).

downloadUrlExpiresAt string · date-time · null zawsze

Błędy

HTTPKodZnaczenie
401invalid_tokenBrak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate).
403ACCOUNT_INACTIVEKonto sprzedawcy jest nieaktywne.
403AccessDeniedBrak zakresu albo zasób innego sprzedawcy.
403KEY_QUARANTINEDKwarantanna: działa tylko odczyt (wykryto nietypowe użycie).
403KEY_SUSPENDEDKlucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę).
403ORDERS_OWNED_BY_OTHER_INTEGRATIONZamówienia sprzedawcy obsługuje inna integracja (details.owner).
404NOT_FOUNDNie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama).
413PAYLOAD_TOO_LARGETreść żądania za duża (JSON 5 MB, faktura PDF 3 MB).
415UNSUPPORTED_MEDIA_TYPEZły Content-Type treści.
422INVALID_URLZły adres faktury-linku.
422JsonMappingExceptionTreść nie jest poprawnym JSON albo ma zły kształt (np. images jako obiekty).
422TOO_MANY_INVOICESNajwyżej 10 faktur na zamówienie.
422UnknownJSONPropertyPole nieznane w tym miejscu (path wskazuje które).
422VALIDATION_ERRORZła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce.
429TOO_MANY_REQUESTSPrzekroczony limit (minutowy, grupy operacji albo IP).
500INTERNAL_ERRORBłąd serwera allee.
503NOT_DEPLOYEDFunkcja jeszcze nie uruchomiona (np. sandbox, wsady).
Przykład
Odpowiedź (środowisko testowe)
HTTP 201 application/vnd.allegro.public.v1+json
{
  "id": "269a4823-f164-4ed9-8567-571fda81ad5d",
  "invoiceNumber": "FV/2/11/2026",
  "createdAt": "2026-11-10T11:10:05.468Z",
  "file": null,
  "allee": {
    "type": "LINK",
    "status": "READY",
    "size": null,
    "url": "https://faktury.example.com/fv/2-11-2026",
    "downloadUrl": null,
    "downloadUrlExpiresAt": null
  }
}

Pobranie pliku faktury (podpisany link)

GET /allee/billing-documents/{invoiceId}/file

tylko alleelimit: read

Adres z allee.downloadUrl (ważny 5 minut) — bez tokenu; podpis jest przepustką. Po terminie → 403 LINK_EXPIRED_OR_INVALID (pobierz nowy adres z GET …/invoices).

Link z sandboxu (klucz testowy) ma dodatkowo mode=test — znacznik jest objęty podpisem, więc pobierasz go tak samo, bez tokenu; nie zmieniaj ani nie usuwaj parametrów adresu (zmiana → 403).

Zgodność: tylko allee — Rozszerzenie allee.
Uwierzytelnienie: podpis w adresie (link ważny 5 minut) — bez tokenu.

Parametry ścieżki

invoiceId string wymagany

Identyfikator faktury.

Parametry zapytania

expires string wymagany

Z podpisanego adresu.

mode string

Z podpisanego adresu — tylko linki z sandboxu (objęte podpisem).

Wartości: test
signature string wymagany

Z podpisanego adresu.

Odpowiedzi

200 Plik PDF (Content-Disposition: attachment). · string · binary

Błędy

HTTPKodZnaczenie
403LINK_EXPIRED_OR_INVALIDPodpisany link wygasł (5 min) albo jest zmieniony.
404NOT_FOUNDNie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama).
500INTERNAL_ERRORBłąd serwera allee.
Przykład
curl -sS -X GET "${ALLEE_API_URL:-https://api.allee.pl}/allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file?expires=1794309305&mode=test&signature=…" \
  -H "Accept: application/pdf" \
  -o pobrana-faktura.pdf -w 'HTTP %{http_code}\n'
Odpowiedź (środowisko testowe)
HTTP 200 application/pdf
(plik pobrana-faktura.pdf: 622 B, application/pdf)