Skip to content

Latest commit

 

History

History
155 lines (102 loc) · 7 KB

guidelines.adoc

File metadata and controls

155 lines (102 loc) · 7 KB
Raw

PUF Invoice Response is a document type that is applicable to be exchanged between buyer/receiver and supplier/issuer to inform the issuer of an invoice about business decisions.

This is often referred to as business level response.

PUF Invoice Response is developed to be compliant to the UBL 2.3 schema.

In areas where support for certain information is available in the existing UBL 2.3 schema, PUF implements these elements.

In other areas where there are no suitable elements in the existing UBL 2.3 schema, PUF implements ext:UBLExtensions.

How to get started

In the following chapters you can see which elements and what type of information that PUF Invoice Response supports.

In some cases we provide longer snippets of code and implementation guidelines describing how to properly interpret the data.

There is also a section with [_examples] that can be useful when building support for PUF Invoice Response in various markets.

If your ERP system already can receive/issue documents in UBL 2.3 or if your ERP system can interpret/create another UBL 2.3 based format you can easily use this as stepping stone when moving towards PUF.

Namespaces

Target root name space - ApplicationResponse:

  • urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2

Example:
ApplicationResponse example for target namespace

<ApplicationResponse xmlns="urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2">
  <!-- Code omitted for clarity -->
</ApplicationResponse>

Customization and Profile ID

To indicate the correct PUF specification identifer and the profile identifier, the values in below table must be sent in cbc:CustomizationID and cbc:ProfileID.

Type Element cbc:CustomizationID Element cbc:ProfileID

Invoice Response

urn:pagero.com:puf:invoice_response:1.0

urn:pagero.com:puf:invoice_response:1.0

Example

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cbc:CustomizationID>urn:pagero.com:puf:invoice_response:1.0</cbc:CustomizationID>
  <cbc:ProfileID>urn:pagero.com:puf:invoice_response:1.0</cbc:ProfileID>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

Working with extensions

This chapter provides an overview the use of extensions.

In order to facilitate the use of PUF specific extensions, an additional XML schema is provided.

The PUF-ExtensionComponent.xsd can be found together with the other schemas in chapter [_xml_schemas].

To be able to use the PUF-ExtensionComponent, its namespace must be included in the document file.

Example
Example from ApplicationResponse

<ApplicationResponse ... xmlns:puf="urn:pagero:ExtensionComponent:1.0">
  <!-- Code omitted for clarity -->
</ApplicationResponse>

Depending on in which context the UBLExtensions are used, there are different options for what types of values that can be provided.

To identify which context the UBLExtensions is in, the element ExtensionURI is used.

When using these Pagero extensions, the URI always has the same base:

  • urn:pagero:ExtensionComponent:1.0:PageroExtension

After this URI, the specific resource name is added.

Example
UBLExtension used in the cac:Response structure.

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cac:Response>
    <ext:UBLExtensions>
      <ext:UBLExtension>
        <ext:ExtensionURI>urn:pagero:ExtensionComponent:1.0:PageroExtension:ResponseExtension</ext:ExtensionURI>
        <!-- Code omitted for clarity -->
  </cac:Response>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

For detailed examples and how to use possible values in each extension please see the chapters where PUF-specific elements are described.

Document reference matching

Below information is only applicable when sending PUF Invoice Response to Pagero.

An Invoice Response always corresponds to an Invoice document. When transmitting the PUF Invoice Response, there are several methods by which Pagero Online establishes a connection between the Invoice Response and its corresponding Invoice (assuming the Invoice is present within Pagero Online).

Pagero Online will attempt to match the response based on specific values. The xpaths for these are prioritized and used in the sequence listed below:

  1. cac:DocumentResponse/cac:Response/ext:UBLExtensions/ext:UBLExtension[ext:ExtensionURI = 'urn:pagero:ExtensionComponent:1.0:PageroExtension:ResponseExtension']/ext:ExtensionContent/puf:PageroExtension/puf:ResponseExtension/puf:DocumentMatchingID/cbc:ID

  2. cac:DocumentResponse/cac:Response/ext:UBLExtensions/ext:UBLExtension[ext:ExtensionURI = 'urn:pagero:ExtensionComponent:1.0:PageroExtension:ResponseExtension']/ext:ExtensionContent/puf:PageroExtension/puf:ResponseExtension/puf:DocumentMatchingID/cbc:UUID

  3. Combined segment information:

    • cac:DocumentResponse/cac:Response/cac:DocumentReference/cbc:ID

    • cac:DocumentResponse/cac:Response/cac:DocumentReference/cbc:IssueDate

    • cac:SenderParty/cac:PartyIdentification/cbc:ID

    • cac:ReceiverParty/cac:PartyIdentification/cbc:ID

For this last option, the identifiers (cac:PartyIdentification/cbc:ID) from both the sender and receiver parties must correspond to those present in the Invoice document within Pagero Online. Additionally, the invoice number and date should also align.

You can read more about DocumentMatchingID in [puf:ResponseExtension]

Note
 If Pagero Online is unable to match the referenced document, the identifiers provided in cac:ReceiverParty will be used for routing the response to the recipient.

Release management

PUF will be continuously updated to meet new market demands.

Minor release

A minor release will always be backward compatible and will take place without prior notice and will be implemented whenever needed.

Minor releases may include bugfixes, new elements, schematron updates and other features.

To be automatically notified of all releases, please "Watch" the project repository on GitHub.

Major release

A major release may include changes that are not backward compatible.

Such a release will be notified at least three months prior to date of implementation, to users who registered an account on Pagero validex or on GitHub.

To register for PUF major release notification you can create a free account on Pagero Validex.

But we strongly urge all interested parties to "Watch" the project repository on GitHub where all releases will trigger automatic notifications.