Artykuł techniczny · REST v1

Dokumentacja API Foliade

API na start: 5 udanych konwersji w ciągu 30 dni, jedna naraz; 50 MB i 100 stron na PDF, 250 MB przechowywanych pakietów API.

MCP jest dostępny od bezpłatnego planu. Pełne API, statystyki, przesyłanie zbiorcze i webhooki są dostępne od Pro. Samodzielny eksport HTML jest dostępny od Business.

Otwórz interaktywne odniesienie Pobierz OpenAPI

Uwierzytelnianie okaziciela

Utwórz klucz w Foliade → API, a następnie wyślij go w nagłówku Authorization. Klucz daje dostęp do katalogów jego konta: przechowuj go w menedżerze sekretów, a nigdy w kodzie źródłowym.

export FOLIADE_API_KEY="fl_live_your_key"
curl https://foliade.gekkode.com/v1/me \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}"

Kluczowy cykl życia

utwórz dedykowany klucz dla każdej integracji;
skopiuj jego wartość podczas jej tworzenia;
monitoruj jego ostatnią rozmowę;
wycofać je, gdy tylko przestaną być używane.

Odpowiedź na brakujący, nieznany lub unieważniony klucz 401.

Punkty końcowe v1

Metoda	Ścieżka	Wynik
`POST`	`/v1/catalogs`	Konwertuje plik PDF, wersję roboczą lub publikację.
`POST`	`/v1/catalogs/bulk`	Zaakceptuj źródło publiczne i rozpocznij partię.
`GET`	`/v1/catalogs`	Wyświetla listę katalogów konta.
`GET`	`/v1/catalogs/{id}`	Zwraca katalog i stan jego ostatniej konwersji.
`POST`	`/v1/catalogs/{id}/publish`	Publikuje istniejący szkic bez ponownej konwersji ani zmiany linku.
`GET`	`/v1/catalogs/{id}/stats?days=30`	Zwraca odczyty, czytelników, kontakty i odsłony stron.
`DELETE`	`/v1/catalogs/{id}`	Cofa publikację katalogu bez usuwania danych konta.
`GET`	`/v1/me`	Sprawdza klucz, ofertę i ilość katalogów.

Opublikuj plik PDF

Wyślij ciało multipart/form-data. Sam fichier jest obowiązkowe. publier=0 tworzy projekt; publier=1 powoduje, że link staje się publiczny. Z attendre=1, zapytanie czeka na konwersję do 300 sekund przed wyrenderowaniem 202.

curl -X POST https://foliade.gekkode.com/v1/catalogs \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}" \
  -F "[email protected];type=application/pdf" \
  -F "titre=Catalogue été 2026" \
  -F "langue=fr" \
  -F "publier=1" \
  -F "attendre=1"

Pole	Domyślne	Opis
`fichier`	—	API na start: 50 MB i 100 stron na PDF. Pełne API: 300 MB na PDF.
`remplace`	—	Identyfikator katalogu konta do zastąpienia bez zmiany linku lub ochrony. Udana konwersja zużywa jedną jednostkę limitu API na start.
`titre`	nazwa pliku	Widoczny tytuł katalogu.
`langue`	język konta	Kod języka obsługiwany przez odtwarzacz.
`publier`	`0`	`1` aby natychmiast otworzyć publiczny link.
`attendre`	`1`	`0` aby natychmiast otrzymać pracę asynchroniczną.

{
  "id": "abc123",
  "url": "https://foliade.gekkode.com/c/abc123",
  "etat": "public",
  "pages": 24,
  "duree_s": 8.4,
  "texte_indexe": true
}

Przetwarzanie masowe

Pełne API jest dostępne od Pro.

Zbiorczy punkt wejścia otrzymuje publiczny adres URL HTTP(S) w treści JSON. Element webhook jest opcjonalny. Odpowiedź 202 zawiera identyfikator przyjętej partii.

curl -X POST https://foliade.gekkode.com/v1/catalogs/bulk \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "https://exemple.fr/catalogues.zip",
    "webhook": "https://exemple.fr/webhooks/foliade"
  }'

Źródłem jest archiwum ZIP o rozmiarze do 2 GB, zawierające maksymalnie 500 plików PDF o rozmiarze 300 MB każdy. Powiadomienia korzystają z trwałej kolejki: po awarii protokołu HTTP planowanych jest pięć ponownych prób po 1 minucie, 5 minutach, 15 minutach, 1 godzinie i 6 godzinach.

Każde powiadomienie zawiera stabilny identyfikator i podpis HMAC-SHA256. Pobierz sekret podpisywania swojej przestrzeni za pomocą interfejsu Identity API. Weryfikuj surowy podpis treści HTTP, odrzucaj znaczniki czasu starsze niż pięć minut i deduplikuj już przetworzone zdarzenia. Obrót klucza aplikacji odnawia sekrety.

GET /v1/me → webhook_signing_secret
X-Foliade-Event-Id: event_id
X-Foliade-Signature: t=timestamp,v1=signature
signature = HMAC-SHA256(webhook_signing_secret, timestamp + "." + raw_body)

Statystyki

Statystyki wymagają Pro.

Okres jest przesyłany za pomocą days. Interfejs API REST i hostowany serwer MCP akceptują liczbę całkowitą od 1 do 3650 dni. Wartości spoza zakresu są odrzucane.

curl "https://foliade.gekkode.com/v1/catalogs/abc123/stats?days=30" \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}"

Odpowiedzi i błędy

Status	Znaczenie	Działanie
`201`	Konwersja zakończona.	Użyj `url` i `id`.
`202`	Konwersja lub partia zaakceptowana, nadal w toku.	Zachowaj zwrócony dokument tożsamości.
`400`	Źródło zbiorcze nie jest akceptowanym publicznym adresem URL.	Podaj dostępny adres URL HTTP(S).
`401`	Brak klucza, nieznany lub unieważniony.	Sprawdź nagłówek lub utwórz klucz.
`403`	Funkcja wymaga wyższego planu lub konto jest zawieszone.	Sprawdź uprawnienia konta.
`404`	Brak katalogu na uwierzytelnionym koncie.	Sprawdź identyfikator i klucz.
`409`	Konwersja trwa, miejsca są zajęte lub pamięć jest pełna.	Poczekaj lub zwolnij miejsce na koncie.
`413`	PDF przekracza limit rozmiaru lub stron planu.	Zmniejsz lub podziel dokument.
`422`	Plik PDF chroniony, uszkodzony lub konwersja nie powiodła się.	Wyeksportuj ponownie czytelny plik PDF bez hasła.
`429`	Osiągnięto limit API lub limit ochronny.	Sprawdź limity przed ponowną próbą.

Ochrona przed nadużyciami: 60 wywołań API na minutę i 10 prób przesłania na 24 godziny, wspólnych z witryną i MCP. Błędy wliczają się do limitu dziennego, nie miesięcznego.

Usunięcie lub wycofanie publikacji nie zwraca udanej konwersji. Pięć miejsc publikacji jest wspólnych z przesyłaniem przez stronę. Szkice i archiwa API wliczają się do 5 przechowywanych katalogów API i 250 MB miejsca.

Po odpowiedzi 202 pobierz katalog, aby śledzić konwersję. Odpowiedź tożsamości konta pokazuje pozostałe limity API na start; sekret webhooka jest udostępniany tylko w Pro i wyższych planach.

Serwer API czy MCP?

API jest odpowiednie dla aplikacji, backendu lub kanału redakcyjnego. Serwer MCP realizuje te same operacje za pomocą narzędzi, które Codex i Claude Code mogą wywoływać pod kontrolą użytkownika.

Zrozumienie różnicy między MCP a API

Plik wykonywalny

Dokumentacja Swagger i schemat OpenAPI są generowane na podstawie faktycznie wdrożonych tras.

Przetestuj w Swagger UI

Dziennik zmian

Wersja	Data	Zmiany
v1	28 sierpnia 2026 r	Publiczna dokumentacja konwersji, partii, statystyk, cofnięcia publikacji i tożsamości konta.