Document

This chapter provides an in-depth overview of the Document business transaction message, which is published when a document is created or updated.

Business Transaction Overview

Headers of the Document Business Transaction Message

The following table lists the headers in the Document business transaction message:

Header Description Value

Header	Description	Value
X-Ocs-Io-transaction-id	ID of the transaction.
X-Ocs-Io-message-code	Code of the Message.	`document`
X-Ocs-Io-message-payload	Name (JAVA’s Simple Name) of the Message’s Payload.	`DocumentEx`

X-Ocs-Io-transaction-id

ID of the transaction.

X-Ocs-Io-message-code

Code of the Message.

document

X-Ocs-Io-message-payload

Name (JAVA’s Simple Name) of the Message’s Payload.

DocumentEx

Fields of the Document Business Transaction Payload

The following table lists and describes the fields in the Document business transaction payload:

Field	Description
refId	Ref ID of the Document.
documentSource	Source of the Document.
documentType	Type of the Document.
documentNo	Number of the Document (generated by RM module).
externalDocumentNo	External number of the Document (generated by external system, e.g. CRM).
customer	ID of the Customer.
account	ID of the Account.
currency	Currency.
documentCode	Code of the Document as configured in external Product Catalogue.
documentName	Name of the Document as configured in external Product Catalogue.
documentIssuedDate	Date when Document was issued.
documentTaxDate	Tax performance date of the Document.
documentDueDate	Due date of the Document.
recommendedPaymentDate	Recommended Payment Date.
totalAmount	Total Amount of the Document. Excluding Tax.
totalAmountNet	Net Total Amount of the Document including Tax. Not present for Customers with VAT Exemption.
totalAmountTax	Tax part of the Total Amount of the Document. Not present for Customers with VAT Exemption.
totalInvoiced	Invoiced Amount of the Document, after rounding. This amount may consider other due documents / over-payments. This is the amount which is expected to be paid by Payer in order to settle all debts.
roundingCompensation	Rounding Compensation, difference between Total Amount Net and Total Invoiced.
taxExemptionType	Tax Exemption Type.
taxResidence	Tax Residence of the Payment Responsible Account.
paymentRef1	Payment Reference No.1 associated with the Document.
paymentRef2	Payment Reference No.2 associated with the Document.
paymentRef3	Payment Reference No.3 associated with the Document.
paymentMethod	Payment Method.
deliveryMethod	Delivery Method.
paymentInfo	Information how Payment will be proceed.
documentCreatedDate	Date/Time when Document was created.
documentCreatedBy	Identification of the user who created this Document.
dueAmount	Due amount of the account receivable or liability including Tax.
dueAmountType	Type of the Due Amount. 'AR' = 'Provider receives, Payer is liable', 'LIABILITY' = 'Provider is liable, Payer will receive'.
documentPaidDate	Date/Time when Document was paid (criteria when Document is considered as paid have been met).
billCycle	Billing Cycle including Billing Period start and end. Applicable only for 'OCS Invoice' Documents.
correctiveTaxDocumentReason	Reason of corrective. Valid only for Corrective Tax document.
customAttributes	Custom attributes, Key - Value (String) Map
parentDocumentRefId	Foreign Key to ParentDocument. Valid only for Corrective Tax document.
documentCancelledDate	Date/Time when Document was cancelled.
documentCancelledBy	Identification of the user who cancelled this Document.
cancellationReason	Reason for Cancellation of the Document.
cancellationAmount	Cancellation amount of the account receivable or liability including Tax (= Due Amount at the time of Cancel).

Field

Description

refId

Ref ID of the Document.

documentSource

Source of the Document.

documentType

Type of the Document.

documentNo

Number of the Document (generated by RM module).

externalDocumentNo

External number of the Document (generated by external system, e.g. CRM).

customer

ID of the Customer.

account

ID of the Account.

currency

Currency.

documentCode

Code of the Document as configured in external Product Catalogue.

documentName

Name of the Document as configured in external Product Catalogue.

documentIssuedDate

Date when Document was issued.

documentTaxDate

Tax performance date of the Document.

documentDueDate

Due date of the Document.

recommendedPaymentDate

Recommended Payment Date.

totalAmount

Total Amount of the Document. Excluding Tax.

totalAmountNet

Net Total Amount of the Document including Tax. Not present for Customers with VAT Exemption.

totalAmountTax

Tax part of the Total Amount of the Document. Not present for Customers with VAT Exemption.

totalInvoiced

Invoiced Amount of the Document, after rounding. This amount may consider other due documents / over-payments. This is the amount which is expected to be paid by Payer in order to settle all debts.

roundingCompensation

Rounding Compensation, difference between Total Amount Net and Total Invoiced.

taxExemptionType

Tax Exemption Type.

taxResidence

Tax Residence of the Payment Responsible Account.

paymentRef1

Payment Reference No.1 associated with the Document.

paymentRef2

Payment Reference No.2 associated with the Document.

paymentRef3

Payment Reference No.3 associated with the Document.

paymentMethod

Payment Method.

deliveryMethod

Delivery Method.

paymentInfo

Information how Payment will be proceed.

documentCreatedDate

Date/Time when Document was created.

documentCreatedBy

Identification of the user who created this Document.

dueAmount

Due amount of the account receivable or liability including Tax.

dueAmountType

Type of the Due Amount. 'AR' = 'Provider receives, Payer is liable', 'LIABILITY' = 'Provider is liable, Payer will receive'.

documentPaidDate

Date/Time when Document was paid (criteria when Document is considered as paid have been met).

billCycle

Billing Cycle including Billing Period start and end. Applicable only for 'OCS Invoice' Documents.

correctiveTaxDocumentReason

Reason of corrective. Valid only for Corrective Tax document.

customAttributes

Custom attributes, Key - Value (String) Map

parentDocumentRefId

Foreign Key to ParentDocument. Valid only for Corrective Tax document.

documentCancelledDate

Date/Time when Document was cancelled.

documentCancelledBy

Identification of the user who cancelled this Document.

cancellationReason

Reason for Cancellation of the Document.

cancellationAmount

Cancellation amount of the account receivable or liability including Tax (= Due Amount at the time of Cancel).

Detailed API documentation and endpoint specifics are available here.

Publish Document Business Transaction Example

{
  "refId": "nPtvbglRsmKV4E",
  "documentSource": {
    "refId": "nPkYteQTMWZEQd",
    "code": "crm",
    "name": "CRM"
  },
  "documentType": {
    "refId": "nPl2L5ynErwZQH",
    "code": "deposit",
    "name": "Deposit"
  },
  "documentNo": "840389f2-48a9-44e6-96b3-777a8ab4b693",
  "account": {
    "refId": "nPBjkidZsc2rUz",
    "externalId": "acc-test"
  },
  "currency": {
    "symbol": "€",
    "refId": "nPOB8vqoP67JNH",
    "code": "EUR",
    "name": "EURO"
  },
  "documentCode": "deposit",
  "documentName": "Deposit",
  "documentIssuedDate": "2020-10-01T22:00:00.000+02:00",
  "documentTaxDate": "2020-10-01T22:00:00.000+02:00",
  "documentDueDate": "2020-10-01T22:00:00.000+02:00",
  "totalAmount": 200000000,
  "totalAmountNet": 242000000,
  "totalAmountTax": 42000000,
  "totalInvoiced": 200000000,
  "roundingCompensation": 0,
  "vatExemption": false,
  "paymentRef1": "ref1",
  "paymentRef2": "ref2",
  "paymentRef3": "ref3",
  "documentCreatedDate": "2020-10-09T00:05:51.838+02:00",
  "documentCreatedBy": "usr01",
  "dueAmount": 200000000,
  "dueAmountType": "LIABILITY"
}