SEselectpdf
Invoice

Create a ZUGFeRD / Factur-X hybrid electronic invoice

Changed on

Converts a URL or HTML into a ZUGFeRD / Factur-X hybrid electronic invoice: the visible invoice is produced by the normal conversion pipeline as a PDF/A-3 document, and the invoice XML is embedded into it as an associated file with the metadata invoice software looks for.

multipart/form-data only - the invoice XML is uploaded as a file part named zugferd_xml. Every /api2/convert parameter applies here as well, plus the zugferd_* fields.

pdf_standard must be a PDF/A-3 level and defaults to pdfa3a, the accessible level, which the standards recommend because it also makes the visible invoice readable by assistive technology. Because pdfa3a is a tagged standard, a request that does not specify an engine is promoted to Chromium and the engine used is returned in X-SelectPdf-Engine.

There is no variant that attaches the XML to an existing PDF you upload: the invoice XML can only be embedded into a document created as PDF/A-3.

post/api2/invoice

Request

  • Base URL
    https://selectpdf.com
  • Auth
    none declared

Request body multipart/form-data

keystring uuid required

License key. Required for /api2/convert; ignored on /api2/convert/demo.

asyncboolean

If true, submit asynchronously and return 202 + a Job-Id header. Poll /api2/asyncjob.

urlstring

Web URL to convert. Required if html is empty. Mutually exclusive with html.

htmlstring

Raw HTML string to convert. Required if url is empty.

base_urlstring

Base URL used to resolve relative paths inside html.

pdf_namestring

Filename suggested via Content-Disposition (default: Document.pdf).

page_size'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6' | 'A7' | 'A8' | 'Letter' | 'HalfLetter' | 'Ledger' | 'Legal'

Output page size.

page_orientation'Portrait' | 'Landscape'
page_widthinteger

Custom page width in points (1 pt = 1/72 in). Overrides page_size when both page_width and page_height are non-zero.

page_heightinteger

Custom page height in points.

margin_topinteger

Top margin in points.

margin_rightinteger

Right margin in points.

margin_bottominteger

Bottom margin in points.

margin_leftinteger

Left margin in points.

engine'WebKit' | 'Restricted' | 'Blink' | 'Chromium'

Rendering engine. WebKit (default) — broadest compatibility. Restricted — WebKit with limited JS. Blink — older Chromium fork. Chromium — modern Chromium/CEF (recommended for new integrations, required by the demo endpoint).

protocolinteger

TLS protocol selector for fetching url. 0 = default (negotiate).

web_page_widthinteger

Browser viewport width in pixels used while rendering.

web_page_heightinteger

Viewport height in pixels. 0 = automatic (engine picks based on content).

min_load_timeinteger

Minimum time (seconds) the engine waits after page load before producing the PDF (lets late-loading scripts settle).

max_load_timeinteger

Hard ceiling (seconds) for page load. On the demo endpoint this is clamped to 15.

use_css_printboolean

Honor CSS @media print rules instead of @media screen.

background_colorstring

PDF page background color (e.g. #FFFFFF).

draw_html_backgroundboolean

If false, the HTML's own backgrounds are stripped (transparent PDF).

disable_javascriptboolean
disable_internal_linksboolean

Suppress in-document anchor hyperlinks.

disable_external_linksboolean

Suppress hyperlinks pointing outside the document.

render_on_timeoutboolean

If max_load_time expires, render whatever loaded instead of failing.

keep_images_togetherboolean

Avoid splitting images across page breaks.

scale_imagesboolean
single_page_pdfboolean

Produce a single tall page sized to fit the entire content.

page_breaks_enhanced_algorithmboolean
doc_titlestring

PDF metadata: title.

doc_subjectstring
doc_keywordsstring
doc_authorstring
doc_add_creation_dateboolean
doc_languagestring

Natural language of the document (e.g. "en-US", "de-DE"), written as the PDF /Lang entry and onto tagged structure elements. Defaults to en-US.

taggedboolean

Produce a tagged, accessible PDF: a logical structure tree covering headings, paragraphs, lists, tables, figures with alternate text, links and reading order. Requires engine=Blink or engine=Chromium - the WebKit engines cannot produce a structure tree. When the engine is not specified it is promoted to Chromium automatically and reported in the X-SelectPdf-Engine response header. Also forces viewer_display_doc_title, which accessible PDF requires.

pdf_standard'full' | 'pdfa' | 'pdfa2b' | 'pdfa3a' | 'pdfa3b' | 'pdfa3u' | 'pdfx' | 'pdfsiqq_a' | 'pdfsiqq_b'

PDF conformance target. full (default) uses the complete PDF feature set. pdfa/pdfa2b/pdfa3b/pdfa3u are archival levels; pdfa3a is the accessible level of PDF/A-3 and implies a tagged document, so it carries the same engine requirement as tagged. pdfx is for graphics exchange; pdfsiqq_a and pdfsiqq_b are the digital-signature profiles.

viewer_page_layout0 | 1 | 2 | 3 | 4 | 5

PDF viewer page layout: 0=SinglePage, 1=OneColumn (default), 2=TwoColumnLeft, 3=TwoColumnRight, 4=TwoPageLeft, 5=TwoPageRight.

viewer_page_mode0 | 1 | 2 | 3 | 4 | 5

PDF viewer page mode: 0=UseNone (default), 1=UseOutlines, 2=UseThumbs, 3=FullScreen, 4=UseOC, 5=UseAttachments.

viewer_center_windowboolean
viewer_display_doc_titleboolean
viewer_fit_windowboolean
viewer_hide_menu_barboolean
viewer_hide_toolbarboolean
viewer_hide_window_uiboolean
show_headerboolean

Render a header band on each page sourced from header_url or header_html.

header_display_on_first_pageboolean
header_display_on_odd_pagesboolean
header_display_on_even_pagesboolean
header_heightinteger

Header band height in points.

header_urlstring

URL whose rendered output becomes the page header.

header_htmlstring

Inline HTML used as the page header (alternative to header_url).

header_base_urlstring
header_web_page_widthinteger
header_web_page_heightinteger
show_footerboolean
footer_display_on_first_pageboolean
footer_display_on_odd_pagesboolean
footer_display_on_even_pagesboolean
footer_display_on_last_pageboolean
footer_heightinteger
footer_urlstring
footer_htmlstring
footer_base_urlstring
footer_web_page_widthinteger
footer_web_page_heightinteger
page_numbersboolean

Render page numbers in the footer band.

page_numbers_firstinteger

Page number assigned to the first page (lets you offset numbering).

page_numbers_offsetinteger

Number of leading pages to suppress numbering on.

page_numbers_templatestring

Template using {page_number} and {total_pages} placeholders.

page_numbers_font_namestring
page_numbers_font_sizeinteger
page_numbers_alignment1 | 2 | 3

1=Left, 2=Center, 3=Right.

page_numbers_colorstring

Hex color for the page numbers (e.g. #000000).

page_numbers_pos_yinteger

Vertical position of page numbers in points from the bottom.

pdf_bookmarks_selectorsstring

Semicolon-separated CSS selectors. Matched elements become PDF bookmarks.

pdf_hide_elementsstring

Semicolon-separated CSS selectors. Matched elements are hidden before rendering.

pdf_show_only_element_idstring

Render only the element with this id (everything else hidden).

pdf_web_elements_selectorsstring

Semicolon-separated CSS selectors whose bounding boxes are reported back via X-SelectPdf-Web-Elements (sync) or /api2/webelements (async).

user_passwordstring

Password required to open the PDF. Rejected by the demo endpoint.

owner_passwordstring

Password required to modify / print the PDF. Rejected by the demo endpoint.

auth_usernamestring

HTTP Basic-Auth username used when fetching url.

auth_passwordstring
cookiesobject

Cookie name → value map sent when fetching url (JSON body only).

cookies_stringstring

Query-string-encoded cookies (form / GET equivalent of cookies).

startup_modestring

Engine startup mode hint (automatic, manual).

skip_decodingboolean

If true, treat the URL as already-decoded (do not re-percent-decode). Internal default for forwarded calls.

raw_parametersstring

Optional JSON blob containing this entire object. When present, the receiver deserializes it and ignores all other form fields. Used by the SDK's remote-worker proxy.

response_content_type0 | 1

0 = binary/octet-stream (default, makes browsers download). 1 = application/pdf (browsers may render inline).

zugferd_profile'minimum' | 'basic_wl' | 'basic' | 'en16931' | 'extended' | 'xrechnung' required

Required. How much of the EN 16931 semantic model the embedded XML carries. minimum and basic_wl are not complete invoices. xrechnung is the German public-sector profile, and its embedded file is named xrechnung.xml rather than factur-x.xml.

zugferd_relationship'data' | 'alternative' | 'source' | 'supplement'

How the XML relates to the visible invoice page. Defaults per profile: alternative for minimum and basic_wl (the page carries more than the XML), data for the rest (the XML and the page carry the same content, which is mandatory in Germany for basic, en16931, extended and xrechnung). minimum or basic_wl combined with data is rejected.

zugferd_schema'facturx10' | 'zugferd20'

Metadata schema identifying the invoice. zugferd20 is deprecated and only for recipients that still require it.

Example request

{
  "key": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "url": "https://selectpdf.com",
  "html": "<b>test html string</b>"
}

Response

Hybrid invoice PDF returned in the response body.

Changes