Jak wysłać plik PDF do API jako Base64
API do e-faktur, podpisu elektronicznego albo wysyłki paczek oczekuje dokumentu w polu JSON. Zobacz, jak zamienić PDF na właściwy tekst, sprawdzić go i uniknąć błędów, przez które żądanie zostaje odrzucone.
Autor: Metin Ersoy · Zaktualizowano 10 listopada 2026
Czego zwykle oczekuje API
Większość API do dokumentów opisuje treść żądania w formacie JSON z polem o nazwie content, file, data lub document. Jego wartością jest kod Base64 pliku PDF, często razem z nazwą pliku i typem:
{
"fileName": "invoice-1024.pdf",
"mimeType": "application/pdf",
"content": "JVBERi0xLjcKJ..."
}
Zanim napiszesz kod, sprawdź w dokumentacji trzy rzeczy: nazwę pola, to, czy wymagany jest prefiks data: (zwykle nie), oraz limit rozmiaru.
1. Zamień PDF na Base64
Najszybciej uzyskasz wartość testową w narzędziu PDF na Base64. Wybierz plik PDF, zaznacz Sam kod Base64 (zaczyna się od JVBERi0) i skopiuj wynik. Jeśli chcesz mieć gotową treść żądania na start, wybierz JSON z nazwą pliku, typem i zawartością – nazwa pliku i typ zostaną dodane za Ciebie. Plik PDF jest kodowany w Twojej przeglądarce i nie jest nigdzie przesyłany, co ma znaczenie, gdy dokumentem testowym jest prawdziwa faktura.
Sprawdź wynik: powinien zaczynać się od JVBERi0, nie zawierać spacji i – poza jednym lub dwoma znakami = na końcu – składać się wyłącznie z liter, cyfr oraz znaków + i /.
2. Wyślij go ze swojego kodu
Ten sam krok w trzech popularnych językach programowania. Każdy przykład odczytuje plik, koduje go i wysyła JSON:
# curl (Linux / macOS): base64 -w 0 keeps it on one line
curl -X POST https://api.example.com/documents \
-H "Content-Type: application/json" \
-d "{\"fileName\":\"invoice.pdf\",\"content\":\"$(base64 -w 0 invoice.pdf)\"}"
// Node.js 18+
import { readFile } from 'node:fs/promises';
const content = (await readFile('invoice.pdf')).toString('base64');
await fetch('https://api.example.com/documents', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ fileName: 'invoice.pdf', content }),
});
# Python 3 with requests
import base64, requests
with open("invoice.pdf", "rb") as f:
content = base64.b64encode(f.read()).decode("ascii")
requests.post("https://api.example.com/documents",
json={"fileName": "invoice.pdf", "content": content})
Na macOS w poleceniu curl zamiast -w 0 użyj base64 -i invoice.pdf. Adres i nazwy pól to tylko przykłady – użyj tych z dokumentacji swojej usługi.
3. Sprawdź, czy dokument wraca bez zmian
Jeśli usługa zwraca dokument lub zapisaną kopię jako Base64, wklej odpowiedź do narzędzia Base64 na PDF. Podgląd pierwszej strony i liczba stron to najszybszy dowód, że po drodze nic nie zginęło. Szczegółowe kroki dla tego kierunku znajdziesz w poradniku Jak zapisać ciąg Base64 jako plik PDF.
Najczęstsze błędy
| Objaw | Prawdopodobna przyczyna | Rozwiązanie |
|---|---|---|
| „Invalid Base64” | Podziały wierszy (wiersze po 76 znaków) lub prefiks data: | Wyślij sam kod w jednym wierszu |
| „Payload too large” (413) | Plik PDF po zakodowaniu jest za duży | Zmniejsz go narzędziem Kompresuj PDF |
| PDF otwiera się pusty lub uszkodzony | Ciąg został ucięty | Zakoduj plik ponownie i wyślij całą wartość |
| Nazwy z polskimi znakami wyglądają źle | Nazwa pliku wysłana w złym kodowaniu | Wysyłaj treść JSON w kodowaniu UTF-8 |
Chcesz spróbować? To nic nie kosztuje, a plik zostaje na Twoim urządzeniu.
Otwórz narzędzie PDF na Base64