PL/PDF FACTUR-X / ZUGFERD EXAMPLES
===================================

This example package demonstrates the main PLPDF_FACTUR workflows for creating
Factur-X 1.09.2 / ZUGFeRD 2.5.2 hybrid electronic invoices with PL/PDF 5.32.

The examples are intentionally based on the final regression and external
acceptance fixtures used during development. They are standalone
CREATE OR REPLACE PROCEDURE programs and use named PL/SQL parameters.

Generated XML and PDF files are stored in PLPDF_FACTUR_EXAMPLE_STORE. The
optional export_outputs.sql script writes those BLOBs to an Oracle DIRECTORY.

PREREQUISITES
-------------

  * PL/PDF 5.32 or later.
  * PLPDF_FACTUR installed and VALID.
  * The PL/PDF TrueType font setup used by the bundled reference renderer:
    PLPDF_TTF.GetTTF(1) must return the prepared DejaVuSans font.
  * No network access is required.
  * An Oracle DIRECTORY such as PLPDF_WORK is required only when using
    export_outputs.sql.

The bundled PLPDF_FACTUR_INVOICE_EXAMPLE package is the accepted reference
renderer used during development. It demonstrates how a visual invoice renderer
reads the canonical PLPDF_FACTUR model and how PREPAREPDFCARRIER /
RELEASEPDFCARRIER are used around normal PL/PDF output generation.


EXAMPLES
--------

01_minimum_invoice.prc
  Data-first MINIMUM profile. The canonical model still contains rich visual
  invoice information, while the embedded MINIMUM XML intentionally carries a
  reduced structured data set.

02_basic_wl_invoice.prc
  Data-first BASIC WL profile. Structured header and settlement data are
  included while structured line items are omitted by the profile.

03_basic_invoice.prc
  Simple data-first BASIC invoice with one line, VAT, payment and totals.

04_en16931_invoice.prc
  EN 16931 data-first invoice with party identifiers, electronic addresses,
  references, item identifier and standard payment data.

05_extended_invoice.prc
  EXTENDED profile example using the accepted profile-specific code-list
  fixture: party identifier scheme 0245 and VAT category B.

06_xml_first_invoice.prc
  XML-first workflow. It loads the EN 16931 XML produced by example 04 through
  PLPDF_FACTUR.LOADXML, validates the parsed canonical model and generates a
  new hybrid PDF.

07_credit_note.prc
  EN 16931 credit note (type 381) with BG-3 preceding-invoice reference
  including BT-25 and BT-26.

08_negative_invoice.prc
  Negative commercial invoice (type 380). The unit price stays positive while
  quantity, line total, VAT and document totals are negative.

09_extended_rich_invoice.prc
  Rich EXTENDED invoice with trading names, references, payment details,
  multiple lines, line/document allowances and charges, item identifiers,
  periods and accounting-currency tax total.

10_validation_error.prc
  Demonstrates fail-fast code-list validation. The example intentionally uses
  BGN and expects PLPDF_FACTUR validation rule FX-CODE-BT-5.


FILES
-----

install.sql
  Creates PLPDF_FACTUR_EXAMPLE_STORE, compiles the bundled reference renderer,
  helper package and all example procedures.

compile_examples.sql
  Recompiles all ten example procedures.

run_all.sql
  Runs the full example sequence and verifies that all nine invoice examples
  generated one non-empty XML and one non-empty PDF output.

list_outputs.sql
  Lists generated example outputs stored in PLPDF_FACTUR_EXAMPLE_STORE.

export_outputs.sql
  Writes all generated OUTPUT rows to an Oracle DIRECTORY. The default
  DIRECTORY object is PLPDF_WORK.

uninstall.sql
  Removes the example procedures, helper/reference renderer and example table.

helper/plpdf_factur_invoice_example.pck
  Reference visual invoice renderer used in the accepted PLPDF_FACTUR tests.
  It validates the canonical model, prepares the Factur-X PDF/A-3 carrier,
  generates the visible invoice with PL/PDF and releases the carrier state.

helper/plpdf_factur_example_util.pck
  Small demonstration-only store helper used to persist XML/PDF output BLOBs.

outputs/
  Placeholder directory for exported files. Oracle writes to the server-side
  filesystem configured by the selected Oracle DIRECTORY object, not directly
  into this ZIP directory.


INSTALL AND RUN
---------------

From SQL*Plus or SQLcl in the extracted demo directory:

  @install.sql
  @run_all.sql

Expected final markers:

  PLPDF_FACTUR_EXAMPLE_INSTALL=PASS
  PLPDF_FACTUR_EXAMPLE_XML_OUTPUT_COUNT=9
  PLPDF_FACTUR_EXAMPLE_PDF_OUTPUT_COUNT=9
  PLPDF_FACTUR_EXAMPLE_OUTPUT_CHECK=PASS
  PLPDF_FACTUR_EXAMPLES=PASS

To export the generated XML and PDF files:

  @export_outputs.sql

Press Enter to use PLPDF_WORK, or enter another Oracle DIRECTORY object name.

To remove the demo objects:

  @uninstall.sql


OUTPUT OWNERSHIP
----------------

PLPDF_FACTUR.GETXML returns a caller-owned temporary CLOB. The example
procedures release it after the XML has been copied into the example store.

PLPDF_FACTUR_INVOICE_EXAMPLE.GENERATE returns the generated PDF BLOB to the
caller. The example procedures release temporary output BLOBs after storing
their contents.

Input BLOBs passed to PLPDF_FACTUR.LOADXML are treated as borrowed/read-only.


IMPORTANT
---------

These examples demonstrate API usage. They are not an invoice-template engine
and the bundled visual renderer is intentionally simple. Production invoice
layouts should use the same PLPDF_FACTUR canonical model/read-only renderer API
with the application's own PL/PDF layout.

The examples follow the accepted PLPDF_FACTUR 0.11.0 development baseline:
Factur-X 1.09.2, ZUGFeRD 2.5.2, EN 16931 code lists v17b and PL/PDF 5.32.
