API PDF/A-3b dla archiwizacji i e-faktur
Generuj wyjście PDF/A-3b w gPdf i rozróżnij, kiedy PDF/A-3b jest tylko profilem archiwalnym, a kiedy opakowaniem e-faktury.
/api/v1/pdf/render Generuj dokumenty PDF/A-3b dla procesów archiwizacji i wybieraj endpoint e-faktur, gdy PDF/A-3b ma przenosić osadzony XML EN 16931 dla Factur-X albo ZUGFeRD.
Kiedy użyć tej API
- Potrzebujesz profilu archiwalnego PDF/A-3b dla renderowanego dokumentu.
- Musisz jasno wyjaśnić granicę między zwykłym PDF/A a pakowaniem e-faktur.
- Twój proces obsługi wymagań sprawdza wygenerowane PDF-y za pomocą veraPDF albo innego silnika referencyjnego.
- Potrzebujesz publicznej strony, która kieruje intencję wyszukiwania PDF/A-3b do właściwego endpointu.
Czego nie zastępuje
- Potrzebujesz dowolnych procesów załączania plików, które nie są opisane w publicznym API.
- Potrzebujesz e-faktur Factur-X albo ZUGFeRD przez JSON Render. Użyj E-Invoice Render.
- Potrzebujesz API walidatora. Obecna publiczna powierzchnia walidatora to strona /validator/.
Który endpoint wywołać
/api/v1/pdf/render
JSON Render to domyślna ścieżka dla tego procesu.
/api/v1/e-invoice/render
Użyj, gdy proces wymaga powiązanej ścieżki API, kontraktu szablonu albo sprawdzenia capabilities.
Minimalny request
POST /api/v1/pdf/render - żądanie wyjścia PDF/A-3b dla renderowanego dokumentu.
{
"settings": {
"profile": "pdfa-3b"
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Archive copy",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
Co obsługuje gPdf
- Wybór profilu PDF/A przez ustawienia JSON Render.
- Pakowanie e-faktur PDF/A-3b przy użyciu POST /api/v1/e-invoice/render.
- Renderowalne wyjście PDF odpowiednie do zewnętrznej walidacji silnikiem referencyjnym.
- Jasne rozdzielenie profilu archiwalnego od prawnego procesu e-faktury.
Co kontroluje Twój system
- Politykę retencji i powód, dla którego wymagany jest PDF/A-3b.
- Dane biznesowe, semantykę XML i zewnętrzne kryteria akceptacji wymagań.
- Dowody walidacji, zapisy audytowe i długoterminowe przechowywanie po renderowaniu.
Checklist produkcyjny
- Wybierz JSON Render dla zwykłego wyjścia PDF/A-3b.
- Wybierz E-Invoice Render, gdy wymagany jest osadzony XML EN 16931.
- Sprawdź wyjście PDF/A przez /validator/ albo własny proces z veraPDF.
- Zapisz żądany profil i request ID razem z przechowywanym dokumentem.
- Unikaj deklarowania obsługi dowolnych załączników, jeśli publiczna dokumentacja jej nie wymienia.
Granice deklaracji
- PDF/A-3b jest profilem archiwalnym; pakowanie e-faktur to węższy proces zbudowany na nim.
- Nie sugeruj obsługi każdego dowolnego procesu z osadzonym plikiem.
- Ścieżka e-faktur jest wymagana dla pakietów Factur-X i ZUGFeRD PDF/A-3b.
PDF/A-3b to opakowanie, nie cały proces
PDF/A-3b jest archiwalnym profilem PDF. Ma znaczenie, ponieważ może działać jako opakowanie dla hybrydowych e-faktur, ale sam profil nie czyni dokumentu prawną e-fakturą. Zwykły dokument archiwalny może używać PDF/A-3b bez osadzonego XML faktury.
Dla Factur-X i ZUGFeRD użyj POST /api/v1/e-invoice/render. Ten endpoint
odpowiada za metadane właściwe dla e-faktury i powiązanie pliku towarzyszącego.
Wybierz endpoint według intencji
Użyj JSON Render, gdy celem jest: “wyrenderuj ten dokument jako PDF/A-3b”. Użyj E-Invoice Render, gdy celem jest: “spakuj tę fakturę jako Factur-X albo ZUGFeRD z XML CII EN 16931”. To rozróżnienie utrzymuje kod w czytelnej strukturze i chroni zwykłe zadania archiwalne przed przypadkowym przejęciem założeń dotyczących e-faktur.
Weryfikuj zewnętrznie
PDF/A należy sprawdzać silnikiem referencyjnym, a nie deklaracją marketingową. Użyj publicznego walidatora albo własnego procesu walidacji i przechowuj raport razem z dowodami audytowymi.
FAQ
- Czy PDF/A-3b zawsze oznacza e-fakturę?
- Nie. PDF/A-3b jest archiwalnym profilem PDF. E-faktury Factur-X i ZUGFeRD używają PDF/A-3b jako opakowania dla osadzonego XML EN 16931.
- Który endpoint tworzy PDF/A-3b?
- Do zwykłego PDF/A-3b użyj POST /api/v1/pdf/render z settings.profile. Użyj POST /api/v1/e-invoice/render, gdy wynik musi być e-fakturą Factur-X albo ZUGFeRD.
- Czy przez tę stronę mogę dołączać dowolne pliki?
- Nie zakładaj obsługi dowolnych załączników, jeśli publiczna dokumentacja API nie opisuje takiego procesu. Ta strona dotyczy udokumentowanego użycia PDF/A-3b i e-faktur.
- Jak zweryfikować wyjście PDF/A?
- Użyj /validator/ albo własnego procesu opartego na silniku referencyjnym. Dla e-faktur sprawdzaj zarówno warstwę PDF/A, jak i osadzoną warstwę XML.