Skip to main content

Use Cases

The following section illustrates common scenarios in the creation of CIUS-PT documents.

Document creation via data submission​

Payment terms​

payment_terms[note]: 30 days

Place of consumption (CPE) in document lines​

lines[0][additional_property][0][name]: CPE
lines[0][additional_property][0][value]: PT1234567890

Commitment number in document header​

commitment_number: 2021/451

Commitment number in document lines​

lines[0][commitment][number]: 2021/123
lines[0][commitment][line]: 1

Order number​

references[0][document_type]: order
references[0][number]: 1234

Sending attached PDF (UTF-8)​

file: (binary)

Other secondary attachments​

files[0]: (binary)
files[1]: (binary)

Note: The PDF representing the document must always be sent in the file field.

Header discount​

discounts_charges[0][type]: false // use true for charge
discounts_charges[0][reason]: commercial discount
discounts_charges[0][percent]: 23.00
discounts_charges[0][tax_code]: NOR
discounts_charges[0][amount]: 8.13 // refers to the amount before tax (i.e., this discount is 10.00 EUR after VAT)
discount_amount: 8.13 // total header discounts applied (EXCLUDES line-level discounts)

Line-level discount or charge​

lines[0][discounts_charges][0][type]: false // use true for charge
lines[0][discounts_charges][0][reason]: commercial discount // textual description of the discount
lines[0][discounts_charges][0][amount]: 5.00 // refers to the amount before VAT to deduct from the line
lines[0][quantity]: 2.000 // quantity of items in the line
lines[0][price]: 10.00000000 // unit price of the item
lines[0][amount]: 15.00000000 // line total affected by discount ( (10 * 2) - 5 = 15)
lines[0][taxes][0][tax_percent]: 23.000 // VAT rate
lines[0][taxes][0][tax_amount]: 3.45 // VAT value for the line (15 * 0.23)
discount_amount: 0.00 // total header discounts applied (EXCLUDES line-level discounts)

Item price discount​

lines[0][price_discount][base_amount]: 10.00 // original unit price before applying the discount
lines[0][price_discount][amount]: 5.00 // refers to the amount before VAT to deduct from the item price
lines[0][quantity]: 2.000 // quantity of items in the line
lines[0][price]: 5.00000000 // price after discount (10 - 5 = 5)
lines[0][amount]: 10.00000000 // line total is affected by discount ( (10 - 5) * 2 = 10)
lines[0][taxes][0][tax_percent]: 23.000 // VAT rate
lines[0][taxes][0][tax_amount]: 2.30 // VAT value for the linea (10 * 0.23)
discount_amount: 0.00 // total header discounts applied (EXCLUDES line-level discounts)

Withholding tax​

withholding_tax[0][type]: IRF
withholding_tax[0][tax_amount]: 10.00 // withholding amount
withholding_tax[0][description]: IRS withholding
withholding_tax_amount: 10.00 // ssum of all withholdings

Note: document totals are not affected by withholding

VAT exemption on line​

lines[0][quantity]: 2.000 // quantity
lines[0][price]: 5.00000000 // unit price
lines[0][amount]: 10.00000000 // line total without VAT
lines[0][taxes][0][tax_percent]: 0.00 // VAT rate
lines[0][taxes][0][tax_amount]: 0.00 // VAT value for the line
lines[0][taxes][0][tax_exemption_reason_code]: M08 // AT reason code
lines[0][taxes][0][tax_exemption_reason]: VAT - Reverse Charge // description of AT reason

VAT exemption on header discount or charge​

discounts_charges[0][type]: false // use true for charge
discounts_charges[0][reason]: commercial discount // textual description
discounts_charges[0][percent]: 0.00 // percentage (exempt)
discounts_charges[0][tax_code]: ISE // exempt
discounts_charges[0][amount]: 10.00 // discount amount
discounts_charges[0][tax_exemption_reason]: M08 // AT reason code
discounts_charges[0][tax_exemption_reason_code]: VAT - Reverse Charge // description of AT reason

Sending invoice by email to one or more addresses​

send_by_email: 1,
customer[email]: endereco1@email.com // always sent to the email specified in the customer
additional_emails[0]: endereco2@email.com // also sent to additional addresses
additional_emails[1]: endereco3@email.com

Sending QR code​

qr_code: A:500000000*B:123456789*C:PT*D:GT*E:N*F:20190720*G:GT G234CB/50987*H:GTVX4Y8B-50987*I1:0*N:0.00*O:0.00*Q:5uIg*R:9999

Document creation via CIUS-PT submission​

Note that the order of XML elements is relevant and affects validations in the UBL format. It is recommended to consult the CIUS-PT semantic data model guide here.

Commitment number in document header​

<Invoice>
  ...
  <cbc:AccountingCost>2021/156</cbc:AccountingCost>
</Invoice>

Supplier share capital​

<Invoice>
  ...
  <cac:AccountingSupplierParty>
    <cac:PartyLegalEntity>
      <cbc:CompanyLegalForm>2.000.000 EUR</cbc:CompanyLegalForm>
    </cac:PartyLegalEntity>
  </cac:AccountingSupplierParty>
</Invoice>

Customer GLN (use schemeID 0088)​

<Invoice>
  ...
  <cac:AccountingCustomerParty>
    <cbc:EndpointID schemeID="0088">123456789</cbc:EndpointID>
  </cac:AccountingCustomerParty>
</Invoice>

ATCUD and QRCODE​

<Invoice>
  ...
  <cac:AdditionalDocumentReference>
    <cbc:ID schemeID="ANG">AFHOFX-22</cbc:ID> <!-- ATCUD value -->
    <cbc:DocumentDescription>QR_CODE</cbc:DocumentDescription>
    <cac:Attachment> <!-- QRCODE text, base64 encoded (character sequence, not image) -->
        <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain" filename="QR_CODE.txt">UVJDT0RF=</cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
  </cac:AdditionalDocumentReference>
</Invoice>

Payment method​

<Invoice>
  ...
  <cac:PaymentMeans>
    <cbc:PaymentMeansCode>NU</cbc:PaymentMeansCode>
  </cac:PaymentMeans>
</Invoice>

Allowed values:

CodeDescription
CCCredit card
CDDebit card
CHBank cheque
CIInternational documentary credit
COGift cheque or card
CSAccount balance offset
DEElectronic cash (e.g., loyalty cards or points)
LCCommercial paper
MBATM (Multibanco) payment references
NUCash
OUOther unspecified means
PRGoods barter
TBBank transfer or authorised direct debit
TRExtramural compensation titles (e.g., meal, education, etc.)

Debit or credit card payment information​

<Invoice>
  ...
  <cac:PaymentMeans>
    <cbc:PaymentMeansCode>CC</cbc:PaymentMeansCode>
    <cac:CardAccount>
      <cbc:PrimaryAccountNumberID>4211456651233545687</cbc:PrimaryAccountNumberID> <!-- Account number -->
      <cbc:NetworkID>04256</cbc:NetworkID> <!-- Bank network ID -->
      <cbc:HolderName>João Ferreira</cbc:HolderName> <!-- Cardholder name -->
    </cac:CardAccount>
  </cac:PaymentMeans>
</Invoice>

Bank transfer payment method​

<Invoice>
  ...
  <cac:PaymentMeans>
    <cbc:PaymentMeansCode>TB</cbc:PaymentMeansCode>
    <cac:PayeeFinancialAccount>
      <cbc:ID>PT50000700230012345667899</cbc:ID> <!-- IBAN-->
      <cbc:Name>João</cbc:Name> <!-- Account holder -->
      <cac:FinancialInstitutionBranch>
        <cbc:ID>NBxxxx</cbc:ID> <!--SWIFT -->
      </cac:FinancialInstitutionBranch>
    </cac:PayeeFinancialAccount>
  </cac:PaymentMeans>
</Invoice>

ATM (Multibanco) reference payment method​

<Invoice>
  ...
  <cac:PaymentMeans>
    <cbc:PaymentMeansCode name="#DESCRIPTION@ATMPAYMENT#156.22#">#ENTITY@ATMPAYMENT#15652</cbc:PaymentMeansCode> <!-- Entity and value -->
    <cbc:PaymentID>#REFERENCE@ATMPAYMENT#156555145#</cbc:PaymentID> <!-- Reference -->
  </cac:PaymentMeans>
</Invoice>

Second ATM (Multibanco) reference​

<Invoice>
  ...
  <cbc:Note>#ENTITY@ATMPAYMENT-001#12345#</cbc:Note> <!-- 2nd entity -->
  <cbc:Note>#REFERENCE@ATMPAYMENT-001#012345678#</cbc:Note> <!-- 2nd reference -->
  <cbc:Note>#AMOUNT@ATMPAYMENT-001#3264.10#</cbc:Note> <!--2nd reference amount -->
  <cbc:Note>#DESCRIPTION@ATMPAYMENT-001#Total invoice amount, including outstanding amounts#</cbc:Note> <!-- 2nd reference description -->
</Invoice>

Payment terms:​

<Invoice>
  ...
  <PaymentTerms>
    <cbc:Note>30 dias</cbc:Note>
  </PaymentTerms>
</Invoice>

Textual note in document header​

<Invoice>
  ...
  <cbc:Note>Nota cabeçalho</cbc:Note>
</Invoice>

Textual note in document lines​

<Invoice>
  ...
  <InvoiceLine>
    <cbc:Note>Nota linha</cbc:Note>
  </InvoiceLine>
</Invoice>

Additional property in document​

<Invoice>
  ...
  <cbc:Note>#ADDITIONALPROPERTY#VOUCHER#123#</cbc:Note>
<Invoice>

Place of consumption (CPE) in document lines​

<cac:InvoiceLine>
  ...
  <cac:AdditionalItemProperty>
    <cbc:Name>CPE</cbc:Name>
    <cbc:Value>PT1234567890</cbc:Value>
  </cac:AdditionalItemProperty>
</cac:InvoiceLine>

Order / request number​

<Invoice>
  ...
  <cac:OrderReference>
    <cbc:ID>20159854587</cbc:ID>
  </cac:OrderReference>
</Invoice>

Commitment number in document lines​

<cac:InvoiceLine>
  <cbc:AccountingCost>2020/123</cbc:AccountingCost> <!-- line commitment number -->
  ...
  <cac:Item>
    <cac:AdditionalItemProperty>
      <cbc:Name>#LINEID@COMMITMENTLINEREFERENCE#</cbc:Name>
      <cbc:Value>1</cbc:Value> <!-- line number -->
    </cac:AdditionalItemProperty>
  </cac:Item>
</cac:InvoiceLine>

Attached PDF​

Note: content must bebase64 encoded

<Invoice>
  ...
  <cac:AdditionalDocumentReference>
    <cbc:ID>1</cbc:ID>
    <cbc:DocumentDescription>INVOICE_REPRESENTATION</cbc:DocumentDescription>
    <cac:Attachment>
      <cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="document">JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGIvTGF==
      </cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
  </cac:AdditionalDocumentReference>
</Invoice>

See example

Multiple attached PDFs​

<Invoice>
  ...
  <cac:AdditionalDocumentReference>
    <cbc:ID>1</cbc:ID> <!-- Main attachment must have description INVOICE_REPRESENTATION', or 'CREDITNOTE_REPRESENTATION' -->
    <cbc:DocumentDescription>INVOICE_REPRESENTATION</cbc:DocumentDescription>
    <cac:Attachment>
      <cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="document.pdf">JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGIvTGF==
      </cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
  </cac:AdditionalDocumentReference>

  <cac:AdditionalDocumentReference>
    <cbc:ID>2</cbc:ID> <!-- Secondary attachments (e.g., order notes, payment slips, etc.) should have description 'ATTACHMENT'. Multiple ATTACHMENTs can be included in a document. -->
    <cbc:DocumentDescription>ATTACHMENT</cbc:DocumentDescription>
    <cac:Attachment>
      <cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="document2.pdf">jUNCiW1tbW1DQoJVBERi0xLjUNCiW1tbW1DQo8PC9UeXBlL0NhUGIvTGF==
      </cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
  </cac:AdditionalDocumentReference>
</Invoice>

Other attachments (QR Code, etc.)​

Note: content must be base64 encoded

<Invoice>
  ...
  <cac:AdditionalDocumentReference>
    <cbc:ID>2</cbc:ID>
    <cbc:DocumentDescription>ATTACHMENT</cbc:DocumentDescription> <!-- use QR_CODE for QR Code -->
    <cac:Attachment>
      <cbc:EmbeddedDocumentBinaryObject mimeCode="application/txt" filename="document">JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGIvTGF==
      </cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
  </cac:AdditionalDocumentReference>
</Invoice>

Header document discount or charge​

See example

Line document discount or charge​

See example

Item price discount or charge​

See example

Withholding tax​

See example

VAT exemption in document line​

See example

VAT exemption in document header discount​

See example

Multiple exemptions in document​

See example

Multiple discounts in line​

See example

Consult the complet list of CIUS-PT use cases pela eSPap.