API dla partnerów

Zintegruj swoją usługę z drukiem Zeccer

Linki do druku (GET)

GET /api/orders/new

Twórz linki do druku, które przekierują użytkowników bezpośrednio na stronę druku. Idealne do linków w emailach, przycisków na stronie, lub wszędzie gdzie potrzebujesz prostego URL.

Parametry

Nazwa	Typ	Wymagane	Opis
documentUrls	string	Tak	URL do pobrania pliku (powtórz parametr dla wielu plików)
format	"a4" \| "a3" \| "photo"	Nie	Format wydruku: "a4" dla dokumentów, "a3" dla dużego formatu (tylko delivery), "photo" dla zdjęć. Jeśli pominięto, użytkownik wybiera na stronie druku.
fulfillment.method	"express" \| "delivery"	Nie	Wstępnie wybiera metodę realizacji. Pomiń, aby użytkownik wybrał sam.
fulfillment.printerId	string	Nie	Kod drukarki samoobsługowej; wiąże zamówienie z tą drukarką. Tylko express.
partnerId	string	Nie	Identyfikator partnera do analityki
redirect	boolean	Nie	Ustaw na "true" aby przekierować bezpośrednio na stronę druku

Metoda realizacji

Opcjonalne. Wstępnie wybiera sposób realizacji zamówienia. Pomiń, aby użytkownik wybrał na stronie druku.

expressDrukarka samoobsługowa

methodstring= "express"wymagane

printerIdstringopcjonalne

Wiąże zamówienie z konkretną drukarką samoobsługową. Pomiń, aby użytkownik wybrał drukarkę.

Formaty: a4 · photo

deliveryDostawa kurierska

methodstring= "delivery"wymagane

Formaty: a4 · a3 · photo

Klucze URL / formularza multipart

fulfillment.method     = express | delivery
fulfillment.printerId  = <printer-code>   # express only

Przykład z jednym plikiem

https://start.zeccer.pl/api/orders/new?documentUrls=https://example.com/doc.pdf&format=a4&partnerId=your-partner-id&redirect=true

Przykład z wstępnym wyborem flow

https://start.zeccer.pl/api/orders/new?documentUrls=https://example.com/doc.pdf&format=a4&fulfillment.method=express&fulfillment.printerId=ABCD&partnerId=your-partner-id&redirect=true

Przykład z wieloma plikami

https://start.zeccer.pl/api/orders/new?documentUrls=https://example.com/doc1.pdf&documentUrls=https://example.com/doc2.pdf&format=a4&redirect=true

Dodaj redirect=true aby automatycznie przekierować na stronę druku. Bez tego parametru otrzymasz odpowiedź JSON z adresem przekierowania. Powtórz parametr documentUrls aby dołączyć wiele plików.

Integracja backendowa (POST)

POST /api/orders

Do integracji po stronie serwera, gdzie potrzebujesz przesyłać pliki bezpośrednio lub przetwarzać wiele dokumentów programowo.

Parametry

Nazwa	Typ	Wymagane	Opis
documentUrls	string[]	*	Lista URL-i do pobrania plików
files	File[]	*	Pliki do przesłania (multipart/form-data)
format	"a4" \| "a3" \| "photo"	Nie	Format wydruku: "a4" dla dokumentów, "a3" dla dużego formatu (tylko delivery), "photo" dla zdjęć. Jeśli pominięto, użytkownik wybiera na stronie druku.
fulfillment	object	Nie	Metoda realizacji (express / delivery). Szczegóły poniżej.
partnerId	string	Nie	Identyfikator partnera do analityki
redirect	boolean	Nie	Jeśli true, zwraca przekierowanie HTTP 302 zamiast JSON

* Wymagane jest podanie documentUrls lub files

Metoda realizacji

Opcjonalne. Wstępnie wybiera sposób realizacji zamówienia. Pomiń, aby użytkownik wybrał na stronie druku.

expressDrukarka samoobsługowa

methodstring= "express"wymagane

printerIdstringopcjonalne

Wiąże zamówienie z konkretną drukarką samoobsługową. Pomiń, aby użytkownik wybrał drukarkę.

Formaty: a4 · photo

deliveryDostawa kurierska

methodstring= "delivery"wymagane

Formaty: a4 · a3 · photo

Body JSON

"fulfillment": { "method": "express", "printerId": "ABCD" }
"fulfillment": { "method": "delivery" }

Wysyłka multipart używa płaskich kluczy powyżej (fulfillment.method, fulfillment.printerId).

Przykład z URL-ami (JSON)

curl -X POST https://start.zeccer.pl/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "documentUrls": [
      "https://example.com/doc1.pdf",
      "https://example.com/doc2.pdf"
    ],
    "partnerId": "your-partner-id",
    "format": "a4",
    "fulfillment": { "method": "express", "printerId": "ABCD" }
  }'

Przykład z przesyłaniem plików

curl -X POST https://start.zeccer.pl/api/orders \
  -F "files=@document1.pdf" \
  -F "files=@document2.pdf" \
  -F "partnerId=your-partner-id" \
  -F "format=a4" \
  -F "fulfillment.method=delivery"

Odpowiedź sukcesu (201)

{
  "sessionId": "abc123xyz",
  "redirectUrl": "https://start.zeccer.pl/abc123xyz"
}

Odpowiedź błędu (4xx / 5xx)

Wszystkie odpowiedzi błędów używają spójnego formatu z kodem do odczytu maszynowego i komunikatem czytelnym dla człowieka.

{
  "error": {
    "code": "NO_FILES_PROVIDED",
    "message": "No files provided"
  }
}

Kody błędów

Code	Opis
INVALID_CONTENT_TYPE	Content-Type żądania nie jest multipart/form-data ani application/json
NO_FILES_PROVIDED	Nie podano plików ani documentUrls
TOO_MANY_FILES	Liczba plików przekracza limit na żądanie
FILE_TYPE_NOT_ALLOWED	Rozszerzenie pliku nie jest na liście dozwolonych
FILE_TOO_LARGE	Plik przekracza limit rozmiaru na plik
FILE_DOWNLOAD_FAILED	Nie udało się pobrać pliku z documentUrl
INVALID_URL	documentUrl nie jest prawidłowym URL-em
INVALID_FORMAT	Parametr format nie jest jedną z akceptowanych wartości
INVALID_FLOW	Parametr flow nie jest jedną z akceptowanych wartości
FLOW_FORMAT_INCOMPATIBLE	Wybrany flow nie obsługuje wybranego formatu
INTERNAL_ERROR	Nieoczekiwany błąd po stronie serwera

Limity

Maksymalnie 10 plików na żądanie
Maksymalnie 50MB na plik
Obsługiwane: PDF, DOC, DOCX, ODT, XLS, XLSX, PPT, PPTX, TXT, RTF, PNG, JPG, WEBP

Pytania dotyczące integracji? wsparcie@zeccer.pl