NAME
SelectPdf::InvoiceClient - Create ZUGFeRD / Factur-X hybrid electronic invoices with SelectPdf Online API.
SYNOPSIS
Create a hybrid electronic invoice from an HTML string and save it into a file on disk.
use SelectPdf;
print "This is SelectPdf-$SelectPdf::VERSION\n";
my $apiKey = "Your API key here";
my $invoiceHtml = "<html><body><h1>Invoice INV-2026-001</h1></body></html>";
my $invoiceXml = "factur-x.xml";
my $local_file = "Invoice.pdf";
eval {
my $client = SelectPdf::InvoiceClient->new($apiKey);
$client
->setInvoiceXmlFile($invoiceXml)
->setZugferdProfile(SelectPdf::ZugferdProfile::En16931)
->setDocTitle("Invoice INV-2026-001")
;
$client->createFromHtmlStringToFile($invoiceHtml, $local_file);
print "Finished! Number of pages: " . $client->getNumberOfPages() . ".\n";
};
if ($@) {
print "An error occurred: $@\n";
}DESCRIPTION
A hybrid electronic invoice is one PDF/A-3 file carrying both halves of the invoice: the page a human reads, and the XML a recipient's accounting system reads. This client converts a URL or an HTML string into the visible invoice and embeds the XML into it as an associated file, with the metadata invoice software looks for.
It derives from SelectPdf::HtmlToPdfClient, so every conversion setting - page size, margins, headers, footers, rendering engine - applies here too. Use the createFrom* methods rather than the inherited convert* methods: the invoice endpoint takes a multipart request, because the XML is uploaded as a file part.
The carrier document must be PDF/A-3. The default is PdfA3A, the accessible level, which the standards recommend because it makes the visible invoice readable by assistive technology as well as archivable. Because PdfA3A is a tagged standard, a request that does not set a rendering engine is promoted to Chromium by the API, which reports the engine used in the X-SelectPdf-Engine response header.
There is no way to attach an invoice XML to an existing PDF you already have: the XML can only be embedded into a document created as PDF/A-3.
For more details and full list of parameters see Html To Pdf API Parameters.
METHODS
new( $apiKey )
Construct the Invoice Client.
my $client = SelectPdf::InvoiceClient->new($apiKey);Unlike SelectPdf::HtmlToPdfClient, this client has no demo mode - the keyless demo endpoint does not produce electronic invoices - so an API key is required. The constructor dies when no API key is supplied.
Parameters:
- $apiKey API Key.
setInvoiceXmlFile( $invoiceXmlFile )
Set the invoice XML from a local file.
Only the content of the file is used - the name recorded inside the PDF is the one the standard prescribes ("factur-x.xml", or "xrechnung.xml" for the XRECHNUNG profile), because recipients look it up by name.
Parameters:
- $invoiceXmlFile: Path to the local invoice XML file.
Returns:
- Reference to the current object.
setInvoiceXml( $invoiceXml )
Set the invoice XML from memory.
A character string (with the UTF-8 flag on) is encoded as UTF-8 before it is sent; any other string is sent as-is, as bytes.
Parameters:
- $invoiceXml: The invoice XML content.
Returns:
- Reference to the current object.
setZugferdProfile( $profile )
Set the data profile of the invoice XML - how much of the EN 16931 semantic model it carries. Required.
Parameters:
- $profile: Invoice profile. Possible values: Minimum, Basic_WL, Basic, En16931, Extended, XRechnung (see SelectPdf::ZugferdProfile constants).
Returns:
- Reference to the current object.
setZugferdRelationship( $relationship )
Set how the embedded invoice XML relates to the visible invoice page.
Optional. When not set, the API derives it from the profile: Alternative for Minimum and Basic_WL, and Data for the rest. Minimum and Basic_WL combined with Data are rejected, because those profiles do not carry a complete invoice.
Parameters:
- $relationship: Relationship. Possible values: Data, Alternative, Source, Supplement (see SelectPdf::ZugferdRelationship constants).
Returns:
- Reference to the current object.
setZugferdSchema( $schema )
Set the metadata schema used to identify the hybrid invoice inside the PDF. Default is FacturX10.
Parameters:
- $schema: Schema. Possible values: FacturX10, Zugferd20 (see SelectPdf::ZugferdSchema constants).
Returns:
- Reference to the current object.
createFromUrl( $url )
Create the hybrid invoice from the specified url. The page at the url becomes the visible invoice.
$content = $client->createFromUrl($url);Parameters:
- $url Address of the web page with the visible invoice.
Returns:
- Byte array containing the resulted PDF.
createFromUrlToFile( $url, $filePath )
Create the hybrid invoice from the specified url and write it to a local file.
$client->createFromUrlToFile($url, $filePath);Parameters:
- $url Address of the web page with the visible invoice.
- $filePath Local file including path if necessary.
createFromUrlAsync( $url )
Create the hybrid invoice from the specified url, using an asynchronous call.
$content = $client->createFromUrlAsync($url);Parameters:
- $url Address of the web page with the visible invoice.
Returns:
- Byte array containing the resulted PDF.
createFromUrlToFileAsync( $url, $filePath )
Create the hybrid invoice from the specified url, using an asynchronous call, and write it to a local file.
$client->createFromUrlToFileAsync($url, $filePath);Parameters:
- $url Address of the web page with the visible invoice.
- $filePath Local file including path if necessary.
createFromHtmlString( $htmlString )
Create the hybrid invoice from the specified HTML string, which becomes the visible invoice.
$content = $client->createFromHtmlString($htmlString);Parameters:
- $htmlString HTML string with the visible invoice.
Returns:
- Byte array containing the resulted PDF.
createFromHtmlStringWithBaseUrl( $htmlString, $baseUrl )
Create the hybrid invoice from the specified HTML string. Use a base url to resolve relative paths to resources.
$content = $client->createFromHtmlStringWithBaseUrl($htmlString, $baseUrl);Parameters:
- $htmlString HTML string with the visible invoice.
- $baseUrl Base url used to resolve relative paths to resources (css, images, javascript, etc). Must be a http:// or https:// publicly available url.
Returns:
- Byte array containing the resulted PDF.
createFromHtmlStringToFile( $htmlString, $filePath )
Create the hybrid invoice from the specified HTML string and write it to a local file.
$client->createFromHtmlStringToFile($htmlString, $filePath);Parameters:
- $htmlString HTML string with the visible invoice.
- $filePath Local file including path if necessary.
createFromHtmlStringWithBaseUrlToFile( $htmlString, $baseUrl, $filePath )
Create the hybrid invoice from the specified HTML string and write it to a local file. Use a base url to resolve relative paths to resources.
$client->createFromHtmlStringWithBaseUrlToFile($htmlString, $baseUrl, $filePath);Parameters:
- $htmlString HTML string with the visible invoice.
- $baseUrl Base url used to resolve relative paths to resources (css, images, javascript, etc). Must be a http:// or https:// publicly available url.
- $filePath Local file including path if necessary.
createFromHtmlStringAsync( $htmlString )
Create the hybrid invoice from the specified HTML string, using an asynchronous call.
$content = $client->createFromHtmlStringAsync($htmlString);Parameters:
- $htmlString HTML string with the visible invoice.
Returns:
- Byte array containing the resulted PDF.
createFromHtmlStringWithBaseUrlAsync( $htmlString, $baseUrl )
Create the hybrid invoice from the specified HTML string, using an asynchronous call. Use a base url to resolve relative paths to resources.
$content = $client->createFromHtmlStringWithBaseUrlAsync($htmlString, $baseUrl);Parameters:
- $htmlString HTML string with the visible invoice.
- $baseUrl Base url used to resolve relative paths to resources (css, images, javascript, etc). Must be a http:// or https:// publicly available url.
Returns:
- Byte array containing the resulted PDF.
createFromHtmlStringToFileAsync( $htmlString, $filePath )
Create the hybrid invoice from the specified HTML string, using an asynchronous call, and write it to a local file.
$client->createFromHtmlStringToFileAsync($htmlString, $filePath);Parameters:
- $htmlString HTML string with the visible invoice.
- $filePath Local file including path if necessary.
createFromHtmlStringWithBaseUrlToFileAsync( $htmlString, $baseUrl, $filePath )
Create the hybrid invoice from the specified HTML string, using an asynchronous call, and write it to a local file. Use a base url to resolve relative paths to resources.
$client->createFromHtmlStringWithBaseUrlToFileAsync($htmlString, $baseUrl, $filePath);Parameters:
- $htmlString HTML string with the visible invoice.
- $baseUrl Base url used to resolve relative paths to resources (css, images, javascript, etc). Must be a http:// or https:// publicly available url.
- $filePath Local file including path if necessary.