Faktury
Faktury do zamówień: plik PDF albo link.
- GET
/order/checkout-forms/{checkoutFormId}/invoices— Faktury zamówienia - POST
/order/checkout-forms/{checkoutFormId}/invoices— Faktura — zapowiedź (krok 1 z 2) - PUT
/order/checkout-forms/{checkoutFormId}/invoices/{invoiceId}/file— Faktura — plik PDF (krok 2 z 2) - POST
/order/{checkoutFormId}/billing-documents/files— Faktura PDF jednym żądaniem - POST
/order/{checkoutFormId}/billing-documents/links— Faktura jako link - GET
/allee/billing-documents/{invoiceId}/file— Pobranie pliku faktury (podpisany link)
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 wymaganyIdentyfikator zamówienia (UUID, checkoutForm.id).
Odpowiedzi
200 Faktury. · InvoiceList
invoices array<Invoice> zawszePola obiektu
id string · uuid zawszeinvoiceNumber string · null zawszecreatedAt string · date-time zawszefile object · null zawszePlik PDF (null dla faktury-linku albo przed wgraniem pliku).
Pola obiektu
id string zawszename string zawszeuploadedAt string · date-time · null zawszesecurityVerification object zawszeKontrola bezpieczeństwa PDF (nagłówek, brak treści aktywnych, rozmiar).
Pola obiektu
status string zawszeACCEPTED, REJECTED, PENDINGpassedChecks array<string> zawszefailedChecks array<string> zawszeallee object zawszePola obiektu
type string zawszeFILE, LINKstatus string zawszeREADY, WAITING_FOR_FILEsize integer · null zawszeurl string · null zawszeAdres faktury-linku.
downloadUrl string · uri · null zawszePodpisany adres pobrania pliku (5 minut).
downloadUrlExpiresAt string · date-time · null zawszehasExternalInvoices boolean zawszeCzy są faktury dodane przez integratora.
Błędy
| HTTP | Kod | Znaczenie |
|---|---|---|
| 401 | invalid_token | Brak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate). |
| 403 | ACCOUNT_INACTIVE | Konto sprzedawcy jest nieaktywne. |
| 403 | AccessDenied | Brak zakresu albo zasób innego sprzedawcy. |
| 403 | KEY_QUARANTINED | Kwarantanna: działa tylko odczyt (wykryto nietypowe użycie). |
| 403 | KEY_SUSPENDED | Klucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę). |
| 403 | ORDERS_OWNED_BY_OTHER_INTEGRATION | Zamówienia sprzedawcy obsługuje inna integracja (details.owner). |
| 404 | NOT_FOUND | Nie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama). |
| 429 | TOO_MANY_REQUESTS | Przekroczony limit (minutowy, grupy operacji albo IP). |
| 500 | INTERNAL_ERROR | Błąd serwera allee. |
| 503 | NOT_DEPLOYED | Funkcja jeszcze nie uruchomiona (np. sandbox, wsady). |
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'<?php
// allee API: GET /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices (PHP 8, rozszerzenie curl)
$base = getenv('ALLEE_API_URL') ?: 'https://api.allee.pl';
$ch = curl_init($base . '/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('ALLEE_API_KEY'),
'Accept: application/vnd.allegro.public.v1+json',
],
CURLOPT_RETURNTRANSFER => true,
]);
$odp = curl_exec($ch);
echo 'HTTP ', curl_getinfo($ch, CURLINFO_RESPONSE_CODE), "\n", $odp, "\n";# allee API: GET /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices (Python 3, biblioteka requests)
import os
import requests
BASE = os.environ.get("ALLEE_API_URL", "https://api.allee.pl")
headers = {
"Authorization": "Bearer " + os.environ["ALLEE_API_KEY"],
"Accept": "application/vnd.allegro.public.v1+json",
}
r = requests.request("GET", BASE + "/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices", headers=headers, timeout=60, allow_redirects=False)
print("HTTP", r.status_code)
print(r.text)// allee API: GET /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices (Node.js 18+, wbudowany fetch; plik .mjs)
const BASE = process.env.ALLEE_API_URL ?? "https://api.allee.pl";
const res = await fetch(`${BASE}/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.ALLEE_API_KEY}`,
"Accept": "application/vnd.allegro.public.v1+json",
},
redirect: "manual",
});
console.log("HTTP", res.status);
console.log(await res.text());// allee API: GET /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices (C#, .NET 8+, HttpClient)
using System.Net.Http.Headers;
using System.Text;
var baseUrl = Environment.GetEnvironmentVariable("ALLEE_API_URL") ?? "https://api.allee.pl";
using var http = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false });
using var req = new HttpRequestMessage(new HttpMethod("GET"), baseUrl + "/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("ALLEE_API_KEY"));
req.Headers.Accept.ParseAdd("application/vnd.allegro.public.v1+json");
using var res = await http.SendAsync(req);
Console.WriteLine($"HTTP {(int)res.StatusCode}");
Console.WriteLine(await res.Content.ReadAsStringAsync());// allee API: GET /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices (Java 11+, java.net.http; uruchom: java Main.java)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String base = System.getenv().getOrDefault("ALLEE_API_URL", "https://api.allee.pl");
HttpRequest req = HttpRequest.newBuilder(URI.create(base + "/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices"))
.header("Authorization", "Bearer " + System.getenv("ALLEE_API_KEY"))
.header("Accept", "application/vnd.allegro.public.v1+json")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpClient http = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
HttpResponse<String> res = http.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println("HTTP " + res.statusCode());
System.out.println(res.body());
}
}// allee API: GET /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices (Go 1.20+, net/http; uruchom: go run main.go)
package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
base := os.Getenv("ALLEE_API_URL")
if base == "" {
base = "https://api.allee.pl"
}
req, err := http.NewRequest("GET", base+"/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("ALLEE_API_KEY"))
req.Header.Set("Accept", "application/vnd.allegro.public.v1+json")
klient := &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
res, err := klient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
dane, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println("HTTP", res.StatusCode)
fmt.Println(string(dane))
}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 wymaganyIdentyfikator zamówienia (UUID, checkoutForm.id).
Nagłówki
Idempotency-Key stringOchrona 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 wymaganePola obiektu
name string wymaganeNazwa pliku PDF.
invoiceNumber stringNumer faktury.
Odpowiedzi
201 Zapowiedziano — teraz wgraj plik. · InvoiceCreated
id string · uuid zawszeBłędy
| HTTP | Kod | Znaczenie |
|---|---|---|
| 401 | invalid_token | Brak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate). |
| 403 | ACCOUNT_INACTIVE | Konto sprzedawcy jest nieaktywne. |
| 403 | AccessDenied | Brak zakresu albo zasób innego sprzedawcy. |
| 403 | KEY_QUARANTINED | Kwarantanna: działa tylko odczyt (wykryto nietypowe użycie). |
| 403 | KEY_SUSPENDED | Klucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę). |
| 403 | ORDERS_OWNED_BY_OTHER_INTEGRATION | Zamówienia sprzedawcy obsługuje inna integracja (details.owner). |
| 404 | NOT_FOUND | Nie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama). |
| 413 | PAYLOAD_TOO_LARGE | Treść żądania za duża (JSON 5 MB, faktura PDF 3 MB). |
| 415 | UNSUPPORTED_MEDIA_TYPE | Zły Content-Type treści. |
| 422 | ConstraintViolationException.MissingRequiredParameters | Brak wymaganego parametru lub pola (details = id parametru). |
| 422 | JsonMappingException | Treść nie jest poprawnym JSON albo ma zły kształt (np. images jako obiekty). |
| 422 | TOO_MANY_INVOICES | Najwyżej 10 faktur na zamówienie. |
| 422 | UnknownJSONProperty | Pole nieznane w tym miejscu (path wskazuje które). |
| 422 | VALIDATION_ERROR | Zła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce. |
| 429 | TOO_MANY_REQUESTS | Przekroczony limit (minutowy, grupy operacji albo IP). |
| 500 | INTERNAL_ERROR | Błąd serwera allee. |
| 503 | NOT_DEPLOYED | Funkcja jeszcze nie uruchomiona (np. sandbox, wsady). |
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<?php
// allee API: POST /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices (PHP 8, rozszerzenie curl)
$base = getenv('ALLEE_API_URL') ?: 'https://api.allee.pl';
$body = [
'file' => [
'name' => 'FV-1-11-2026.pdf',
],
'invoiceNumber' => 'FV/1/11/2026',
];
$ch = curl_init($base . '/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('ALLEE_API_KEY'),
'Accept: application/vnd.allegro.public.v1+json',
'Content-Type: application/vnd.allegro.public.v1+json',
],
CURLOPT_POSTFIELDS => json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
CURLOPT_RETURNTRANSFER => true,
]);
$odp = curl_exec($ch);
echo 'HTTP ', curl_getinfo($ch, CURLINFO_RESPONSE_CODE), "\n", $odp, "\n";# allee API: POST /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices (Python 3, biblioteka requests)
import os
import requests
BASE = os.environ.get("ALLEE_API_URL", "https://api.allee.pl")
headers = {
"Authorization": "Bearer " + os.environ["ALLEE_API_KEY"],
"Accept": "application/vnd.allegro.public.v1+json",
"Content-Type": "application/vnd.allegro.public.v1+json",
}
body = {
"file": {
"name": "FV-1-11-2026.pdf",
},
"invoiceNumber": "FV/1/11/2026",
}
r = requests.request("POST", BASE + "/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices", headers=headers, json=body, timeout=60, allow_redirects=False)
print("HTTP", r.status_code)
print(r.text)// allee API: POST /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices (Node.js 18+, wbudowany fetch; plik .mjs)
const BASE = process.env.ALLEE_API_URL ?? "https://api.allee.pl";
const body = {
"file": {
"name": "FV-1-11-2026.pdf"
},
"invoiceNumber": "FV/1/11/2026"
};
const res = await fetch(`${BASE}/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ALLEE_API_KEY}`,
"Accept": "application/vnd.allegro.public.v1+json",
"Content-Type": "application/vnd.allegro.public.v1+json",
},
body: JSON.stringify(body),
redirect: "manual",
});
console.log("HTTP", res.status);
console.log(await res.text());// allee API: POST /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices (C#, .NET 8+, HttpClient)
using System.Net.Http.Headers;
using System.Text;
var baseUrl = Environment.GetEnvironmentVariable("ALLEE_API_URL") ?? "https://api.allee.pl";
using var http = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false });
using var req = new HttpRequestMessage(new HttpMethod("POST"), baseUrl + "/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("ALLEE_API_KEY"));
req.Headers.Accept.ParseAdd("application/vnd.allegro.public.v1+json");
var json = """
{
"file": {
"name": "FV-1-11-2026.pdf"
},
"invoiceNumber": "FV/1/11/2026"
}
""";
req.Content = new StringContent(json, Encoding.UTF8);
req.Content.Headers.ContentType = new MediaTypeHeaderValue("application/vnd.allegro.public.v1+json");
using var res = await http.SendAsync(req);
Console.WriteLine($"HTTP {(int)res.StatusCode}");
Console.WriteLine(await res.Content.ReadAsStringAsync());// allee API: POST /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices (Java 11+, java.net.http; uruchom: java Main.java)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String base = System.getenv().getOrDefault("ALLEE_API_URL", "https://api.allee.pl");
String body = """
{
"file": {
"name": "FV-1-11-2026.pdf"
},
"invoiceNumber": "FV/1/11/2026"
}
""";
HttpRequest req = HttpRequest.newBuilder(URI.create(base + "/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices"))
.header("Authorization", "Bearer " + System.getenv("ALLEE_API_KEY"))
.header("Accept", "application/vnd.allegro.public.v1+json")
.header("Content-Type", "application/vnd.allegro.public.v1+json")
.method("POST", HttpRequest.BodyPublishers.ofString(body))
.build();
HttpClient http = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
HttpResponse<String> res = http.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println("HTTP " + res.statusCode());
System.out.println(res.body());
}
}// allee API: POST /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices (Go 1.20+, net/http; uruchom: go run main.go)
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
base := os.Getenv("ALLEE_API_URL")
if base == "" {
base = "https://api.allee.pl"
}
body := `{
"file": {
"name": "FV-1-11-2026.pdf"
},
"invoiceNumber": "FV/1/11/2026"
}`
req, err := http.NewRequest("POST", base+"/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices", strings.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("ALLEE_API_KEY"))
req.Header.Set("Accept", "application/vnd.allegro.public.v1+json")
req.Header.Set("Content-Type", "application/vnd.allegro.public.v1+json")
klient := &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
res, err := klient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
dane, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println("HTTP", res.StatusCode)
fmt.Println(string(dane))
}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 wymaganyIdentyfikator zamówienia (UUID, checkoutForm.id).
invoiceId string wymaganyIdentyfikator faktury z kroku 1.
Treść żądania application/pdf
Plik PDF faktury.
Typ: string · binary
Odpowiedzi
200 Plik przyjęty. · Invoice
id string · uuid zawszeinvoiceNumber string · null zawszecreatedAt string · date-time zawszefile object · null zawszePlik PDF (null dla faktury-linku albo przed wgraniem pliku).
Pola obiektu
id string zawszename string zawszeuploadedAt string · date-time · null zawszesecurityVerification object zawszeKontrola bezpieczeństwa PDF (nagłówek, brak treści aktywnych, rozmiar).
Pola obiektu
status string zawszeACCEPTED, REJECTED, PENDINGpassedChecks array<string> zawszefailedChecks array<string> zawszeallee object zawszePola obiektu
type string zawszeFILE, LINKstatus string zawszeREADY, WAITING_FOR_FILEsize integer · null zawszeurl string · null zawszeAdres faktury-linku.
downloadUrl string · uri · null zawszePodpisany adres pobrania pliku (5 minut).
downloadUrlExpiresAt string · date-time · null zawszeBłędy
| HTTP | Kod | Znaczenie |
|---|---|---|
| 401 | invalid_token | Brak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate). |
| 403 | ACCOUNT_INACTIVE | Konto sprzedawcy jest nieaktywne. |
| 403 | AccessDenied | Brak zakresu albo zasób innego sprzedawcy. |
| 403 | KEY_QUARANTINED | Kwarantanna: działa tylko odczyt (wykryto nietypowe użycie). |
| 403 | KEY_SUSPENDED | Klucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę). |
| 403 | ORDERS_OWNED_BY_OTHER_INTEGRATION | Zamówienia sprzedawcy obsługuje inna integracja (details.owner). |
| 404 | NOT_FOUND | Nie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama). |
| 409 | INVOICE_FILE_ALREADY_UPLOADED | Plik tej faktury już wgrany. |
| 413 | PAYLOAD_TOO_LARGE | Treść żądania za duża (JSON 5 MB, faktura PDF 3 MB). |
| 415 | UNSUPPORTED_MEDIA_TYPE | Zły Content-Type treści. |
| 422 | VALIDATION_ERROR | Zła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce. |
| 429 | BUSY | Ta sama operacja trwa równolegle. |
| 429 | TOO_MANY_REQUESTS | Przekroczony limit (minutowy, grupy operacji albo IP). |
| 500 | INTERNAL_ERROR | Błąd serwera allee. |
| 503 | NOT_DEPLOYED | Funkcja jeszcze nie uruchomiona (np. sandbox, wsady). |
| 503 | STORAGE_UNAVAILABLE | Magazyn plików chwilowo niedostępny. |
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'<?php
// allee API: PUT /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file (PHP 8, rozszerzenie curl)
$base = getenv('ALLEE_API_URL') ?: 'https://api.allee.pl';
$ch = curl_init($base . '/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('ALLEE_API_KEY'),
'Accept: application/vnd.allegro.public.v1+json',
'Content-Type: application/pdf',
],
CURLOPT_POSTFIELDS => file_get_contents('faktura.pdf'),
CURLOPT_RETURNTRANSFER => true,
]);
$odp = curl_exec($ch);
echo 'HTTP ', curl_getinfo($ch, CURLINFO_RESPONSE_CODE), "\n", $odp, "\n";# allee API: PUT /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file (Python 3, biblioteka requests)
import os
import requests
BASE = os.environ.get("ALLEE_API_URL", "https://api.allee.pl")
headers = {
"Authorization": "Bearer " + os.environ["ALLEE_API_KEY"],
"Accept": "application/vnd.allegro.public.v1+json",
"Content-Type": "application/pdf",
}
with open("faktura.pdf", "rb") as f:
plik = f.read()
r = requests.request("PUT", BASE + "/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file", headers=headers, data=plik, timeout=60, allow_redirects=False)
print("HTTP", r.status_code)
print(r.text)// allee API: PUT /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file (Node.js 18+, wbudowany fetch; plik .mjs)
import { readFile, writeFile } from "node:fs/promises";
const BASE = process.env.ALLEE_API_URL ?? "https://api.allee.pl";
const res = await fetch(`${BASE}/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file`, {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.ALLEE_API_KEY}`,
"Accept": "application/vnd.allegro.public.v1+json",
"Content-Type": "application/pdf",
},
body: await readFile("faktura.pdf"),
redirect: "manual",
});
console.log("HTTP", res.status);
console.log(await res.text());// allee API: PUT /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file (C#, .NET 8+, HttpClient)
using System.Net.Http.Headers;
using System.Text;
var baseUrl = Environment.GetEnvironmentVariable("ALLEE_API_URL") ?? "https://api.allee.pl";
using var http = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false });
using var req = new HttpRequestMessage(new HttpMethod("PUT"), baseUrl + "/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("ALLEE_API_KEY"));
req.Headers.Accept.ParseAdd("application/vnd.allegro.public.v1+json");
req.Content = new ByteArrayContent(File.ReadAllBytes("faktura.pdf"));
req.Content.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
using var res = await http.SendAsync(req);
Console.WriteLine($"HTTP {(int)res.StatusCode}");
Console.WriteLine(await res.Content.ReadAsStringAsync());// allee API: PUT /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file (Java 11+, java.net.http; uruchom: java Main.java)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;
public class Main {
public static void main(String[] args) throws Exception {
String base = System.getenv().getOrDefault("ALLEE_API_URL", "https://api.allee.pl");
HttpRequest req = HttpRequest.newBuilder(URI.create(base + "/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file"))
.header("Authorization", "Bearer " + System.getenv("ALLEE_API_KEY"))
.header("Accept", "application/vnd.allegro.public.v1+json")
.header("Content-Type", "application/pdf")
.method("PUT", HttpRequest.BodyPublishers.ofFile(Path.of("faktura.pdf")))
.build();
HttpClient http = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
HttpResponse<String> res = http.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println("HTTP " + res.statusCode());
System.out.println(res.body());
}
}// allee API: PUT /order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file (Go 1.20+, net/http; uruchom: go run main.go)
package main
import (
"bytes"
"fmt"
"io"
"net/http"
"os"
)
func main() {
base := os.Getenv("ALLEE_API_URL")
if base == "" {
base = "https://api.allee.pl"
}
plik, err := os.ReadFile("faktura.pdf")
if err != nil {
panic(err)
}
req, err := http.NewRequest("PUT", base+"/order/checkout-forms/432810d0-4d26-4f39-ba5f-b89def4d4f92/invoices/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file", bytes.NewReader(plik))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("ALLEE_API_KEY"))
req.Header.Set("Accept", "application/vnd.allegro.public.v1+json")
req.Header.Set("Content-Type", "application/pdf")
klient := &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
res, err := klient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
dane, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println("HTTP", res.StatusCode)
fmt.Println(string(dane))
}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 wymaganyIdentyfikator zamówienia (UUID, checkoutForm.id).
Parametry zapytania
invoiceNumber stringNumer faktury.
fileName stringNazwa 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 zawszeinvoiceNumber string · null zawszecreatedAt string · date-time zawszefile object · null zawszePlik PDF (null dla faktury-linku albo przed wgraniem pliku).
Pola obiektu
id string zawszename string zawszeuploadedAt string · date-time · null zawszesecurityVerification object zawszeKontrola bezpieczeństwa PDF (nagłówek, brak treści aktywnych, rozmiar).
Pola obiektu
status string zawszeACCEPTED, REJECTED, PENDINGpassedChecks array<string> zawszefailedChecks array<string> zawszeallee object zawszePola obiektu
type string zawszeFILE, LINKstatus string zawszeREADY, WAITING_FOR_FILEsize integer · null zawszeurl string · null zawszeAdres faktury-linku.
downloadUrl string · uri · null zawszePodpisany adres pobrania pliku (5 minut).
downloadUrlExpiresAt string · date-time · null zawszeBłędy
| HTTP | Kod | Znaczenie |
|---|---|---|
| 401 | invalid_token | Brak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate). |
| 403 | ACCOUNT_INACTIVE | Konto sprzedawcy jest nieaktywne. |
| 403 | AccessDenied | Brak zakresu albo zasób innego sprzedawcy. |
| 403 | KEY_QUARANTINED | Kwarantanna: działa tylko odczyt (wykryto nietypowe użycie). |
| 403 | KEY_SUSPENDED | Klucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę). |
| 403 | ORDERS_OWNED_BY_OTHER_INTEGRATION | Zamówienia sprzedawcy obsługuje inna integracja (details.owner). |
| 404 | NOT_FOUND | Nie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama). |
| 413 | PAYLOAD_TOO_LARGE | Treść żądania za duża (JSON 5 MB, faktura PDF 3 MB). |
| 415 | UNSUPPORTED_MEDIA_TYPE | Zły Content-Type treści. |
| 422 | TOO_MANY_INVOICES | Najwyżej 10 faktur na zamówienie. |
| 422 | VALIDATION_ERROR | Zła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce. |
| 429 | BUSY | Ta sama operacja trwa równolegle. |
| 429 | TOO_MANY_REQUESTS | Przekroczony limit (minutowy, grupy operacji albo IP). |
| 500 | INTERNAL_ERROR | Błąd serwera allee. |
| 503 | NOT_DEPLOYED | Funkcja jeszcze nie uruchomiona (np. sandbox, wsady). |
| 503 | STORAGE_UNAVAILABLE | Magazyn plików chwilowo niedostępny. |
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'<?php
// allee API: POST /order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/files (PHP 8, rozszerzenie curl)
$base = getenv('ALLEE_API_URL') ?: 'https://api.allee.pl';
$ch = curl_init($base . '/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/files?invoiceNumber=FK%2F1%2F11%2F2026');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('ALLEE_API_KEY'),
'Accept: application/vnd.allegro.public.v1+json',
'Content-Type: application/pdf',
],
CURLOPT_POSTFIELDS => file_get_contents('faktura.pdf'),
CURLOPT_RETURNTRANSFER => true,
]);
$odp = curl_exec($ch);
echo 'HTTP ', curl_getinfo($ch, CURLINFO_RESPONSE_CODE), "\n", $odp, "\n";# allee API: POST /order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/files (Python 3, biblioteka requests)
import os
import requests
BASE = os.environ.get("ALLEE_API_URL", "https://api.allee.pl")
headers = {
"Authorization": "Bearer " + os.environ["ALLEE_API_KEY"],
"Accept": "application/vnd.allegro.public.v1+json",
"Content-Type": "application/pdf",
}
with open("faktura.pdf", "rb") as f:
plik = f.read()
r = requests.request("POST", BASE + "/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/files?invoiceNumber=FK%2F1%2F11%2F2026", headers=headers, data=plik, timeout=60, allow_redirects=False)
print("HTTP", r.status_code)
print(r.text)// allee API: POST /order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/files (Node.js 18+, wbudowany fetch; plik .mjs)
import { readFile, writeFile } from "node:fs/promises";
const BASE = process.env.ALLEE_API_URL ?? "https://api.allee.pl";
const res = await fetch(`${BASE}/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/files?invoiceNumber=FK%2F1%2F11%2F2026`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ALLEE_API_KEY}`,
"Accept": "application/vnd.allegro.public.v1+json",
"Content-Type": "application/pdf",
},
body: await readFile("faktura.pdf"),
redirect: "manual",
});
console.log("HTTP", res.status);
console.log(await res.text());// allee API: POST /order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/files (C#, .NET 8+, HttpClient)
using System.Net.Http.Headers;
using System.Text;
var baseUrl = Environment.GetEnvironmentVariable("ALLEE_API_URL") ?? "https://api.allee.pl";
using var http = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false });
using var req = new HttpRequestMessage(new HttpMethod("POST"), baseUrl + "/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/files?invoiceNumber=FK%2F1%2F11%2F2026");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("ALLEE_API_KEY"));
req.Headers.Accept.ParseAdd("application/vnd.allegro.public.v1+json");
req.Content = new ByteArrayContent(File.ReadAllBytes("faktura.pdf"));
req.Content.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
using var res = await http.SendAsync(req);
Console.WriteLine($"HTTP {(int)res.StatusCode}");
Console.WriteLine(await res.Content.ReadAsStringAsync());// allee API: POST /order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/files (Java 11+, java.net.http; uruchom: java Main.java)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;
public class Main {
public static void main(String[] args) throws Exception {
String base = System.getenv().getOrDefault("ALLEE_API_URL", "https://api.allee.pl");
HttpRequest req = HttpRequest.newBuilder(URI.create(base + "/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/files?invoiceNumber=FK%2F1%2F11%2F2026"))
.header("Authorization", "Bearer " + System.getenv("ALLEE_API_KEY"))
.header("Accept", "application/vnd.allegro.public.v1+json")
.header("Content-Type", "application/pdf")
.method("POST", HttpRequest.BodyPublishers.ofFile(Path.of("faktura.pdf")))
.build();
HttpClient http = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
HttpResponse<String> res = http.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println("HTTP " + res.statusCode());
System.out.println(res.body());
}
}// allee API: POST /order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/files (Go 1.20+, net/http; uruchom: go run main.go)
package main
import (
"bytes"
"fmt"
"io"
"net/http"
"os"
)
func main() {
base := os.Getenv("ALLEE_API_URL")
if base == "" {
base = "https://api.allee.pl"
}
plik, err := os.ReadFile("faktura.pdf")
if err != nil {
panic(err)
}
req, err := http.NewRequest("POST", base+"/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/files?invoiceNumber=FK%2F1%2F11%2F2026", bytes.NewReader(plik))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("ALLEE_API_KEY"))
req.Header.Set("Accept", "application/vnd.allegro.public.v1+json")
req.Header.Set("Content-Type", "application/pdf")
klient := &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
res, err := klient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
dane, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println("HTTP", res.StatusCode)
fmt.Println(string(dane))
}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"
}
}Faktura jako link
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 wymaganyIdentyfikator zamówienia (UUID, checkoutForm.id).
Nagłówki
Idempotency-Key stringOchrona 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 wymaganeAdres https faktury u Ciebie.
invoiceNumber stringOdpowiedzi
201 Dodano. · Invoice
id string · uuid zawszeinvoiceNumber string · null zawszecreatedAt string · date-time zawszefile object · null zawszePlik PDF (null dla faktury-linku albo przed wgraniem pliku).
Pola obiektu
id string zawszename string zawszeuploadedAt string · date-time · null zawszesecurityVerification object zawszeKontrola bezpieczeństwa PDF (nagłówek, brak treści aktywnych, rozmiar).
Pola obiektu
status string zawszeACCEPTED, REJECTED, PENDINGpassedChecks array<string> zawszefailedChecks array<string> zawszeallee object zawszePola obiektu
type string zawszeFILE, LINKstatus string zawszeREADY, WAITING_FOR_FILEsize integer · null zawszeurl string · null zawszeAdres faktury-linku.
downloadUrl string · uri · null zawszePodpisany adres pobrania pliku (5 minut).
downloadUrlExpiresAt string · date-time · null zawszeBłędy
| HTTP | Kod | Znaczenie |
|---|---|---|
| 401 | invalid_token | Brak, zły, wygasły albo odwołany token lub klucz (format OAuth, nagłówek WWW-Authenticate). |
| 403 | ACCOUNT_INACTIVE | Konto sprzedawcy jest nieaktywne. |
| 403 | AccessDenied | Brak zakresu albo zasób innego sprzedawcy. |
| 403 | KEY_QUARANTINED | Kwarantanna: działa tylko odczyt (wykryto nietypowe użycie). |
| 403 | KEY_SUSPENDED | Klucz albo dostęp aplikacji wstrzymany (przez sprzedawcę albo ochronę). |
| 403 | ORDERS_OWNED_BY_OTHER_INTEGRATION | Zamówienia sprzedawcy obsługuje inna integracja (details.owner). |
| 404 | NOT_FOUND | Nie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama). |
| 413 | PAYLOAD_TOO_LARGE | Treść żądania za duża (JSON 5 MB, faktura PDF 3 MB). |
| 415 | UNSUPPORTED_MEDIA_TYPE | Zły Content-Type treści. |
| 422 | INVALID_URL | Zły adres faktury-linku. |
| 422 | JsonMappingException | Treść nie jest poprawnym JSON albo ma zły kształt (np. images jako obiekty). |
| 422 | TOO_MANY_INVOICES | Najwyżej 10 faktur na zamówienie. |
| 422 | UnknownJSONProperty | Pole nieznane w tym miejscu (path wskazuje które). |
| 422 | VALIDATION_ERROR | Zła wartość parametru zapytania (400) albo pola treści (422); path wskazuje miejsce. |
| 429 | TOO_MANY_REQUESTS | Przekroczony limit (minutowy, grupy operacji albo IP). |
| 500 | INTERNAL_ERROR | Błąd serwera allee. |
| 503 | NOT_DEPLOYED | Funkcja jeszcze nie uruchomiona (np. sandbox, wsady). |
curl -sS -X POST "${ALLEE_API_URL:-https://api.allee.pl}/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/links" \
-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'
{
"url": "https://faktury.example.com/fv/2-11-2026",
"invoiceNumber": "FV/2/11/2026"
}
JSON<?php
// allee API: POST /order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/links (PHP 8, rozszerzenie curl)
$base = getenv('ALLEE_API_URL') ?: 'https://api.allee.pl';
$body = [
'url' => 'https://faktury.example.com/fv/2-11-2026',
'invoiceNumber' => 'FV/2/11/2026',
];
$ch = curl_init($base . '/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/links');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('ALLEE_API_KEY'),
'Accept: application/vnd.allegro.public.v1+json',
'Content-Type: application/vnd.allegro.public.v1+json',
],
CURLOPT_POSTFIELDS => json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
CURLOPT_RETURNTRANSFER => true,
]);
$odp = curl_exec($ch);
echo 'HTTP ', curl_getinfo($ch, CURLINFO_RESPONSE_CODE), "\n", $odp, "\n";# allee API: POST /order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/links (Python 3, biblioteka requests)
import os
import requests
BASE = os.environ.get("ALLEE_API_URL", "https://api.allee.pl")
headers = {
"Authorization": "Bearer " + os.environ["ALLEE_API_KEY"],
"Accept": "application/vnd.allegro.public.v1+json",
"Content-Type": "application/vnd.allegro.public.v1+json",
}
body = {
"url": "https://faktury.example.com/fv/2-11-2026",
"invoiceNumber": "FV/2/11/2026",
}
r = requests.request("POST", BASE + "/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/links", headers=headers, json=body, timeout=60, allow_redirects=False)
print("HTTP", r.status_code)
print(r.text)// allee API: POST /order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/links (Node.js 18+, wbudowany fetch; plik .mjs)
const BASE = process.env.ALLEE_API_URL ?? "https://api.allee.pl";
const body = {
"url": "https://faktury.example.com/fv/2-11-2026",
"invoiceNumber": "FV/2/11/2026"
};
const res = await fetch(`${BASE}/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/links`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ALLEE_API_KEY}`,
"Accept": "application/vnd.allegro.public.v1+json",
"Content-Type": "application/vnd.allegro.public.v1+json",
},
body: JSON.stringify(body),
redirect: "manual",
});
console.log("HTTP", res.status);
console.log(await res.text());// allee API: POST /order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/links (C#, .NET 8+, HttpClient)
using System.Net.Http.Headers;
using System.Text;
var baseUrl = Environment.GetEnvironmentVariable("ALLEE_API_URL") ?? "https://api.allee.pl";
using var http = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false });
using var req = new HttpRequestMessage(new HttpMethod("POST"), baseUrl + "/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/links");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("ALLEE_API_KEY"));
req.Headers.Accept.ParseAdd("application/vnd.allegro.public.v1+json");
var json = """
{
"url": "https://faktury.example.com/fv/2-11-2026",
"invoiceNumber": "FV/2/11/2026"
}
""";
req.Content = new StringContent(json, Encoding.UTF8);
req.Content.Headers.ContentType = new MediaTypeHeaderValue("application/vnd.allegro.public.v1+json");
using var res = await http.SendAsync(req);
Console.WriteLine($"HTTP {(int)res.StatusCode}");
Console.WriteLine(await res.Content.ReadAsStringAsync());// allee API: POST /order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/links (Java 11+, java.net.http; uruchom: java Main.java)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String base = System.getenv().getOrDefault("ALLEE_API_URL", "https://api.allee.pl");
String body = """
{
"url": "https://faktury.example.com/fv/2-11-2026",
"invoiceNumber": "FV/2/11/2026"
}
""";
HttpRequest req = HttpRequest.newBuilder(URI.create(base + "/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/links"))
.header("Authorization", "Bearer " + System.getenv("ALLEE_API_KEY"))
.header("Accept", "application/vnd.allegro.public.v1+json")
.header("Content-Type", "application/vnd.allegro.public.v1+json")
.method("POST", HttpRequest.BodyPublishers.ofString(body))
.build();
HttpClient http = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
HttpResponse<String> res = http.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println("HTTP " + res.statusCode());
System.out.println(res.body());
}
}// allee API: POST /order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/links (Go 1.20+, net/http; uruchom: go run main.go)
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
base := os.Getenv("ALLEE_API_URL")
if base == "" {
base = "https://api.allee.pl"
}
body := `{
"url": "https://faktury.example.com/fv/2-11-2026",
"invoiceNumber": "FV/2/11/2026"
}`
req, err := http.NewRequest("POST", base+"/order/432810d0-4d26-4f39-ba5f-b89def4d4f92/billing-documents/links", strings.NewReader(body))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("ALLEE_API_KEY"))
req.Header.Set("Accept", "application/vnd.allegro.public.v1+json")
req.Header.Set("Content-Type", "application/vnd.allegro.public.v1+json")
klient := &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
res, err := klient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
dane, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println("HTTP", res.StatusCode)
fmt.Println(string(dane))
}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 wymaganyIdentyfikator faktury.
Parametry zapytania
expires string wymaganyZ podpisanego adresu.
mode stringZ podpisanego adresu — tylko linki z sandboxu (objęte podpisem).
testsignature string wymaganyZ podpisanego adresu.
Odpowiedzi
200 Plik PDF (Content-Disposition: attachment). · string · binary
Błędy
| HTTP | Kod | Znaczenie |
|---|---|---|
| 403 | LINK_EXPIRED_OR_INVALID | Podpisany link wygasł (5 min) albo jest zmieniony. |
| 404 | NOT_FOUND | Nie ma takiego zasobu (albo należy do innego sprzedawcy — dla wątków, zwrotów i spraw odpowiedź jest ta sama). |
| 500 | INTERNAL_ERROR | Błąd serwera allee. |
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'<?php
// allee API: GET /allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file (PHP 8, rozszerzenie curl)
$base = getenv('ALLEE_API_URL') ?: 'https://api.allee.pl';
$ch = curl_init($base . '/allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file?expires=1794309305&mode=test&signature=…');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Accept: application/pdf',
],
CURLOPT_RETURNTRANSFER => true,
]);
$odp = curl_exec($ch);
$kod = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($kod === 200) file_put_contents('pobrana-faktura.pdf', $odp);
echo 'HTTP ', $kod, "\n";# allee API: GET /allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file (Python 3, biblioteka requests)
import os
import requests
BASE = os.environ.get("ALLEE_API_URL", "https://api.allee.pl")
headers = {
"Accept": "application/pdf",
}
r = requests.request("GET", BASE + "/allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file?expires=1794309305&mode=test&signature=…", headers=headers, timeout=60, allow_redirects=False)
if r.status_code == 200:
with open("pobrana-faktura.pdf", "wb") as f:
f.write(r.content)
print("HTTP", r.status_code)// allee API: GET /allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file (Node.js 18+, wbudowany fetch; plik .mjs)
import { readFile, writeFile } from "node:fs/promises";
const BASE = process.env.ALLEE_API_URL ?? "https://api.allee.pl";
const res = await fetch(`${BASE}/allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file?expires=1794309305&mode=test&signature=…`, {
method: "GET",
headers: {
"Accept": "application/pdf",
},
redirect: "manual",
});
if (res.status === 200) await writeFile("pobrana-faktura.pdf", Buffer.from(await res.arrayBuffer()));
console.log("HTTP", res.status);// allee API: GET /allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file (C#, .NET 8+, HttpClient)
using System.Net.Http.Headers;
using System.Text;
var baseUrl = Environment.GetEnvironmentVariable("ALLEE_API_URL") ?? "https://api.allee.pl";
using var http = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false });
using var req = new HttpRequestMessage(new HttpMethod("GET"), baseUrl + "/allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file?expires=1794309305&mode=test&signature=…");
req.Headers.Accept.ParseAdd("application/pdf");
using var res = await http.SendAsync(req);
if ((int)res.StatusCode == 200) File.WriteAllBytes("pobrana-faktura.pdf", await res.Content.ReadAsByteArrayAsync());
Console.WriteLine($"HTTP {(int)res.StatusCode}");// allee API: GET /allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file (Java 11+, java.net.http; uruchom: java Main.java)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;
public class Main {
public static void main(String[] args) throws Exception {
String base = System.getenv().getOrDefault("ALLEE_API_URL", "https://api.allee.pl");
HttpRequest req = HttpRequest.newBuilder(URI.create(base + "/allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file?expires=1794309305&mode=test&signature=…"))
.header("Accept", "application/pdf")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpClient http = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
HttpResponse<Path> res = http.send(req, HttpResponse.BodyHandlers.ofFile(Path.of("pobrana-faktura.pdf")));
System.out.println("HTTP " + res.statusCode());
}
}// allee API: GET /allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file (Go 1.20+, net/http; uruchom: go run main.go)
package main
import (
"fmt"
"net/http"
"os"
)
func main() {
base := os.Getenv("ALLEE_API_URL")
if base == "" {
base = "https://api.allee.pl"
}
req, err := http.NewRequest("GET", base+"/allee/billing-documents/5551b5a7-3e2e-4cba-b80d-d34fd7e286ae/file?expires=1794309305&mode=test&signature=…", nil)
if err != nil {
panic(err)
}
req.Header.Set("Accept", "application/pdf")
klient := &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
res, err := klient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
if res.StatusCode == 200 {
f, err := os.Create("pobrana-faktura.pdf")
if err != nil {
panic(err)
}
defer f.Close()
if _, err := f.ReadFrom(res.Body); err != nil {
panic(err)
}
}
fmt.Println("HTTP", res.StatusCode)
}application/pdf(plik pobrana-faktura.pdf: 622 B, application/pdf)