Skip to content

Latest commit

 

History

History
723 lines (590 loc) · 55.8 KB

invoicing_context.md

File metadata and controls

723 lines (590 loc) · 55.8 KB

Orders and Invoicing Context

Events

Type GARAIO REM REM Description
Invoicing.Order.Created ✅ ❌ An order has been created
Invoicing.Order.Accepted ✅ ❌ An order has been accepted by GARAIO REM
Invoicing.Order.Rejected ✅ ❌ An order has been rejected by GARAIO REM
Invoicing.Order.Updated ✅ ❌ An already published order has been updated
Invoicing.Order.Deleted ✅ ❌ An order created by a third party system has been deleted
Invoicing.Invoice.Created ✅ ❌ An invoice has been created
Invoicing.Invoice.Accepted ✅ ❌ An invoice has been accepted by GARAIO REM
Invoicing.Invoice.Rejected ✅ ❌ An invoice has been rejected by GARAIO REM
Invoicing.Invoice.Deleted ✅ ❌ An incomplete invoice has been deleted in GARAIO REM
Invoicing.Invoice.Booked ✅ ❌ An invoice was booked in GARAIO REM
Invoicing.Invoice.Cancelled ✅ ❌ An invoice has been cancelled in GARAIO REM (Storno)
Invoicing.Invoice.Payed ✅ ❌ An invoice has been payed by GARAIO REM

Invoicing.Order.Created

This message goes from the order provider to GARAIO REM. Set the recipient property in the headers, eg "grem_derham". All attributes are optional unless noted otherwise in the remarks.

Field Type Content / Remarks
eventType string Invoicing.Order.Created
data hash
  externalReference string external identifier / document number from the order provider; required
  reference longint For direct use by customers only. Use with caution and read notes first. Overrides generated GREM reference. (1)
  supplierReference string reference of the supplier (creditor); required
  masterdataReference string reference of a property / building / unit; required
  tenancyAgreementReference string reference of a tenancy agreement, eg '1234.01.0001.01'
  subject string Short description of the order
  description string Description of the order
  deliveryInfo string Free text for the delivery info, eg end of may
  discount decimal discount (percentage) the supplier is offering for the order
  discountDays integer number of days for the discount
  offeringDate string ISO 8601 encoded date, eg '2020-10-21'
  contactAddress string Address lines of the contact person, separated by CRLF
  deliveryAddress string Address lines for the delivery, separated by CRLF
  reimbursementNote string Note of reimbursement (Weiterverrechnungsvermerk)
  typeCode string Code value for type of order (see code table kreditorenauftrag_typ)
  languageCode string de, fr, it or en; will be used to send error reasons using the desired language; must be lower case
  backlinkUrl string optional url to navigate to the order on the sending system; must be a complete url that the local browser can resolve (including protocol), e.g. https://www.google.com
  clerkUsername string Username of clerk (Sachbearbeiter) to assign.
  orderItems array List of order items; may be empty
    itemNumber integer invoice item number to preserve order; required
    accountNumber string accounting account number, eg "10122"; must be valid for the accounting that belongs to the masterdataReference required
    costCenterNumber string cost center number; optional / required depending on the accountNumber
    taxCode string tax code known to GARAIO REM, eg 'NO'; optional / required depending on the accountNumber
    bookingAmount decimal amount to book (including taxes, if appropriate)
    bookingText string optional booking text
    amount decimal Quantity - optional / required depending on the accountNumber, eg. number of windows
    individualItemBalancingReference string optional reference used to individually reconcile the line item (Einzelpostensaldierend Referenz/EPSID)

Notes

Example

{"eventType":"Invoicing.Order.Created",
  "data":{
    "externalReference":"1234",
    "supplierReference":"5555",
    "subject":"this is the subject",
    "description":"this is the description",
    "deliveryInfo":"end of may",
    "masterdataReference":"4712.01.0001",
    "discount":"5.00",
    "discountDays":"10",
    "offeringDate":"2020-10-13",
    "contactAddress": "Garaio AG\r\nLaupenstrasse 45\r\n3001 Bern",
    "deliveryAddress": "Garaio AG\r\nLaupenstrasse 45\r\n3001 Bern",
    "languageCode":"fr",
    "backlinkUrl":"https://instance.external_system.ch/order/3",
    "clerkUsername": "clerk",
    "orderItems":[
      {"lineNumber":1,
       "accountNumber":"100001",
       "costCenterNumber":"700",
       "taxCode":"00",
       "bookingAmount":1200.50,
       "bookingText":"this goes into the booking movement",
       "amount":100.00,
       "individualItemBalancingReference":"A123-4"
      }
    ]
  }
}

Invoicing.Order.Accepted

This message goes from GARAIO REM to the order provider and signals that GARAIO REM has stored the order

Field Type Content / Remarks
eventType string Invoicing.Order.Accepted
data hash
  reference longint unique identifier of the order
  externalReference string external identifier from the order provider

Example

{"eventType":"Invoicing.Order.Accepted",
  "data":{
    "reference":1234,
    "externalReference":"54820394-001",
  }
}

Invoicing.Order.Rejected

This message goes from GARAIO REM to the order provider and signals that GARAIO REM did not accept the order. GARAIO REM validation errors are mapped into the reasons array

Field Type Content / Remarks
eventType string Invoicing.Order.Rejected
data hash
  externalReference string external identifier from the order provider
  reference string unique identifier for the order
  reasons array
    attribute string name of the attribute, eg. "masterdataReference"; (1)
    reason string reason, eg. "ist nicht bekannt"

Notes

  • (1) might be null if the reason does not map to a specific attribute

Example

{"eventType":"Invoicing.Order.Rejected",
  "data":{
    "reference":null,
    "externalReference":"1234",
    "reasons":[
      {"attribute":"masterdataReference",
       "reason":"ist nicht bekannt"
      }
    ]
  }
}

Invoicing.Order.Updated

This message goes from the order provider to GARAIO REM. Set the recipient property in the headers, eg "grem_derham". All attributes are optional unless noted otherwise in the remarks. This message completely replaces an existing order in GARAIO REM; if you pass, for example, only one orderItem for an order that has two order items, the order will have one orderItem after the update

Field Type Content / Remarks
eventType string Invoicing.Order.Updated
data hash
  reference string unique identifier; maybe required, see (1)
  externalReference string external identifier from the order provider; maybe required, see (1)
  supplierReference string reference of the supplier (creditor); required
  masterdataReference string reference of a property / building / unit; required
  tenancyAgreementReference string reference of a tenancy agreement, eg '1234.01.0001.01'
  subject string Short description of the order
  description string Description of the order
  deliveryInfo string Free text for the delivery info, eg end of may
  discount decimal discount (percentage) the supplier is offering for the order
  discountDays integer number of days for the discount
  offeringDate string ISO 8601 encoded date, eg '2020-10-21'
  contactAddress string Address lines of the contact person, separated by CRLF
  deliveryAddress string Address lines for the delivery, separated by CRLF
  reimbursementNote string Note of reimbursement (Weiterverrechnungsvermerk)
  typeCode string Code value for type of order (see code table kreditorenauftrag_typ)
  languageCode string de, fr, it or en; determines error reasons language; must be lower case
  backlinkUrl string optional url to navigate to the order on the sending system; must be a complete url that the local browser can resolve (including protocol), e.g. https://www.google.com
  clerkUsername string Username of clerk (Sachbearbeiter) to assign.
  completedAt date|null The day the ordered work has been completed. If null, this means the work has not been completed yet.
  orderItems array List of order items; may be empty; orderItems that exists in the order but are not passed here will be deleted
    itemNumber integer invoice item number to preserve order; required
    accountNumber string accounting account number, eg "10122"; must be valid for the accounting that belongs to the masterdataReference required
    costCenterNumber string cost center number; optional / required depending on the accountNumber
    taxCode string tax code known to GARAIO REM, eg 'NO'; optional / required depending on the accountNumber
    bookingAmount decimal amount to book (including taxes, if appropriate)
    bookingText string optional booking text
    amount decimal Quantity - optional / required depending on the accountNumber, eg. number of windows
    individualItemBalancingReference string optional reference used to individually reconcile the line item (Einzelpostensaldierend Referenz/EPSID)

Notes:

  • (1) You have to provide either reference or externalReference. The reference you provide must be a reference that has previously been published in a Invoicing.Order.Created message.

Example

{
  "eventType":"Invoicing.Order.Updated",
  "data":{
    "externalReference":"1234",
    "supplierReference":"100010",
    "masterdataReference":"10001.152.132",
    "subject":"Das ist ein Auftrag",
    "description":"und das ist die <b>Beschreibung</b> des Auftrags",
    "deliveryInfo":"end of may",
    "discount":"5.00",
    "discountDays":"10",
    "offeringDate":"2020-11-03",
    "contactAddress":"Garaio AG\\nLaupenstrasse 45\\n3001 Bern",
    "deliveryAddress":"Garaio AG\\nLaupenstrasse 45\\n3001 Bern",
    "languageCode":"fr",
    "clerkUsername":"Testuser_5",
    "completedAt": "2023-01-01",
    "orderItems":[
      {
        "lineNumber":1,
        "accountNumber":"400000",
        "costCenterNumber":"600",
        "bookingAmount":100,
        "amount":10,
        "taxCode":"00",
        "bookingText":"Regler defekt bei Heizkörper",
        "individualItemBalancingReference":"A123-4"
      }
    ]
  }
}

Responses

You will get back either a Invoicing.Order.Accepted or a Invoicing.Order.Rejected.

Invoicing.Order.Deleted

This message goes from the order provider to GARAIO REM. Set the recipient property in the headers, eg "grem_derham". GARAIO REM will the delete the referenced order, unless it is already connected to an invoice.

Field Type Content / Remarks
eventType string Invoicing.Order.Deleted
data hash
  reference string unique identifier for the order; maybe required, see (1)
  externalReference string external order identifier from the order provider; maybe required, see (1)

Notes

  • (1) You have to provide either a reference or an externalReference.

Example

{"eventType":"Invoicing.Order.Deleted",
  "data":{
    "externalReference":"54820394-001",
  }
}

Invoicing.Order.DeletedAccepted

The Accept message.

Additional data fields:

Field Type Content / Remarks
reference longint unique identifier for the order
externalReference string external reference

Invoicing.Order.DeletedRejected

The Reject message.

Field Type Content / Remarks
reference longint unique identifier for the order
externalReference string external reference

Invoicing.Invoice.Created

This message goes from the invoice provider to GARAIO REM. Set the recipient property in the headers, eg "grem_derham". Depending on the GARAIO REM configuration (AVK strict mode or relaxed mode), invoiceItems are mandatory or not.

You may want to set the source_app_id if the invoice origin does not correspond to the app_id.

Field Type Content / Remarks
eventType string Invoicing.Invoice.Created
data hash
  externalReference string external identifier from the invoice provider (7)
  reference longint For direct use by customers only. Use with caution and read notes first. Overrides generated GREM reference. (1)
  orderReference longint optional reference of the associated order; must be an order reference generated by GARAIO REM; leave it empty if you pass an externalOrderReference
  externalOrderReference string optional external reference of the associated order generated by the orders provider
  preaccountingReference string optional preaccounting reference (max 255 characters)
  creditorReference string reference of the creditor (supplier) (7)
  accountingReference string reference of the accounting
  swissQrCode hash swissQrCode; optional (2)
  iban string ESR Payments are deprecated, use swissQrCode instead; when used also send esrReference. iban for the payment (optional); (3)
  esrReference string ESR Payments are deprecated, use swissQrCode instead; when used also send iban. reference number on the payment slip. (6)
  esrParticipantNumber string ESR Payments are deprecated, use swissQrCode instead. pass this number together with the esrReference if you don't have an iban or swissQrCode
  languageCode string de, fr, it or en; required to send error reasons using the desired language; must be lower case
  notes string ESR Payments are deprecated, use swissQrCode instead. up to four lines of text at up to 28 chars per line, separated by CRLF (optional)
  documentUrl string url to the invoice pdf; must be an url to a pdf that the local browser can resolve
  totalGrossAmount decimal ESR Payments are deprecated, use swissQrCode instead. total gross amount of the invoice; required if no invoiceItems are supplied, must be greater than 0
  externalUserName string optional name of the user that completed the invoice in the external process
  dmsReference string optional reference of the DMS document; must be unique
  invoiceDate string ISO 8601 encoded date, eg '2020-10-21'
  dueDate string ISO 8601 encoded date, eg '2020-10-21'; optional, defaults to today
  bookingDate string ISO 8601 encoded date, eg '2020-10-21'; optional, defaults to today
  transitoryDeferralPeriod string optional, ISO 8601 Time-Interval with restrictions, see (4); NOTE: this field may NOT be used with 'transitoryDeferralDates' within 'invoiceItems'
  invoiceItems array if AVK is configured for strict mode, at least one item is required; if strict mode is disabled, you may pass an empty array, null or omit the attribute
    itemNumber integer invoice item number to preserve order; required
    accountNumber string accounting account number, prefixed by the accounting reference, eg "6056.10122"
    costCenterNumber string cost center number; optional / required depending on the accountNumber
    taxCode string tax code known to GARAIO REM, eg 'NO'; optional / required depending on the accountNumber
    bookingAmount decimal amount to book (including taxes, if appropriate)
    bookingText string optional booking text
    masterdataReference string optional reference of a property / building / unit; might be required depending on the accountNumber
    additionalCostsDate string ISO 8601 encoded date, eg '2021-06-30' (NK-Periodedatum); optional or required depending on the accountNumber
    valueDate string ISO 8601 encoded date, eg '2020-10-21' (Valuta); optional, defaults to the invoiceDate
    amount decimal Quantity - optional / required depending on the accountNumber, eg. litres of oil
    transitoryDeferralDate string optional ISO 8601 encoded date, eg '2020-10-21', optional (transitorisches Abgrenzungsdatum)
    maintenanceLogText string optional uses bookingText if empty
    developmentCode string optional development code retrieved from a GraphQL query (codeTable developments); sometimes required see (5)
    developmentAccountingPlanCode string optional development accounting plan code retrieved from a GraphQL query (codeTable developmentAccountingPlans); sometimes required see (5)
    individualItemBalancingReference string optional reference used to individually reconcile the line item (Einzelpostensaldierend Referenz/EPSID)

Notes

  • (1) See about reference and externalReference.
  • (2) When swissQrCode is used, the following top-level fields must be empty or omitted: iban, esrReference, esrParticipantNumber, totalGrossAmount and notes; see the SwissQRCode Section at the end of this page to understand Garaio REM Invoicing with SwissQrCodes. Do not pass a swissQrCode.iban if you do not pass a creditorReference; GARAIO REM will reply with a rejected message since it cannot handle an iban without a creditor
  • (3) Deprecated; use swissQrCode instead; if you pass the iban, esr attributes and swissQrCode must be empty or omitted. Do not pass an iban or swissQrCode.iban if you do not pass a creditorReference; GARAIO REM will reply with a rejected message since it cannot handle an iban without a creditor
  • (4) We only support the start/end format using ISO 8601 encoded dates (no time inclusion is supported) using the separator '/' or '--', eg '2020-01-31/2020-06-30' or '2020-01-31--2020-06-30' (https://en.wikipedia.org/wiki/ISO_8601#Time_intervals)
  • (5) If you apply a development code, a development accounting plan code is required as well
  • (6) Pass this number together with the esrParticipantNumber if you don't have an iban or swissQrCodeText.
  • (7) creditorReference + externalReference combo must be unique

Example of a complete invoice with IBAN

{"eventType":"Invoicing.Invoice.Created",
  "data":{
    "externalReference":"1234",
    "externalOrderReference":"5678",
    "creditorReference":"5555",
    "accountingReference":"4711",
    "iban":"CH0209000000100013997",
    "languageCode":"fr",
    "notes":"line 1\r\nline 2\r\nline 3\r\nline 4",
    "documentUrl":"https://path/to/the/scan.pdf",
    "totalGrossAmount":1200.50,
    "externalUserName":"External User",
    "dmsReference":"5678",
    "invoiceDate":"2020-10-21",
    "dueDate":"2020-11-21",
    "bookingDate":"2020-10-21",
    "invoiceItems":[
      {"lineNumber":1,
       "accountNumber":"4712.100001",
       "costCenterNumber":"700",
       "taxCode":"00",
       "bookingAmount":1200.50,
       "bookingText":"this goes into the booking movement",
       "masterdataReference":"4712.01",
       "additionalCostsDate":"2021-06-30",
       "valueDate":"2020-10-21",
       "amount":100.00,
       "transitoryDeferralDate":"2020-12-31",
       "maintenanceLogText":"kitchen sink replaced",
       "developmentCode":"001",
       "developmentAccountingPlanCode":"100"
      }
    ]
  }
}

Example of a minimal invoice (relaxed mode)

{"eventType":"Invoicing.Invoice.Created",
  "data":{
    "externalReference":"1234",
    "creditorReference":"5555",
    "accountingReference":"4711",
    "totalGrossAmount":1200.50,
    "invoiceDate":"2020-10-21"
  }
}

Invoicing.Invoice.Accepted

The Accept message.

Additional data fields:

Field Type Content / Remarks
reference longint unique identifier of the invoice
externalReference string external identifier from the invoice provider
orderReference longint|null unique identifier of the associated order
externalOrderReference string|null external identifier of the associated order

Example

{"eventType":"Invoicing.Invoice.Accepted",
  "data":{
    "reference":1234,
    "externalReference":"54820394-001",
    "orderReference": null,
    "externalOrderReference": null
  }
}

Invoicing.Invoice.Rejected

This message goes from GARAIO REM to the invoice provider and signals that GARAIO REM did not accept the invoice. GARAIO REM validation errors are mapped into the reasons array

Field Type Content / Remarks
eventType string Invoicing.Invoice.Rejected
data hash
  externalReference string external identifier from the invoice provider
  reference string unique invoice identifier
  reasons array
    attribute string name of the attribute, eg. "accountingReference"; (1)
    lineNumber integer Invoice line number if the problem is on an invoice line or null, if not
    reason string reason, eg. "ist nicht bekannt"

Notes

  • (1) Might be null if the reason does not map to a specific attribute.

Example

{"eventType":"Invoicing.Invoice.Rejected",
  "data":{
    "reference":null,
    "externalReference":"1234",
    "reasons":[
      {"attribute":"accountingReference",
       "lineNumber":null,
       "reason":"ist nicht bekannt"
      }
    ]
  }
}

Invoicing.Invoice.Deleted

This message goes from GARAIO REM to the invoice provider and signals that a user has deleted the incomplete (not yet booked) invoice in GARAIO REM

Field Type Content / Remarks
eventType string Invoicing.Invoice.Deleted
data hash
  reference string unique invoice identifier
  externalReference string external identifier from the invoice provider
  orderReference longint|null unique identifier of the associated order
  externalOrderReference string|null external identifier of the associated
  reason string optional description why the invoice has been deleted

Example

{"eventType":"Invoicing.Invoice.Deleted",
  "data":{
    "reference": 1234,
    "externalReference":"54820394-001",
    "orderReference": null,
    "externalOrderReference": null,
    "reason":"will not be payed because of reasons"
  }
}

Invoicing.Invoice.Booked

This message goes from GARAIO REM to the invoice provider and signals that GARAIO REM has booked the invoice. This may happen immediately after receiving a Invoicing.Invoice.Created message (if the invoice data is valid and complete) or it may happen after a user has completed an incomplete invoice. This message goes from GARAIO REM to the invoice provider and signals that GARAIO REM has booked the invoice. This may happen immediately after receiving a Invoicing.Invoice.Created message (if the invoice data is valid and complete) or it may happen after a user has completed an incomplete invoice.

In any case, this message follows a Invoicing.Invoice.Accepted message, immediately or later (in case of an invoice that needs user interaction)

Field Type Content / Remarks
eventType string Invoicing.Invoice.Booked
data hash
  reference longint unique identifier for the invoice, generated by GARAIO REM
  externalReference string external identifier from the invoice provider
  orderReference longint|null unique identifier of the associated order
  externalOrderReference string|null external identifier of the associated order
  accountingReference string reference of the accounting
  invoiceItems array at least one invoice item is guaranteed
    itemNumber integer invoice item number to preserve order
    accountNumber string accounting account number, prefixed by the accounting reference, eg "6056.10122"
    costCenterNumber string cost center number
    taxCode string tax code known to GARAIO REM, eg 'NO'
    masterdataReference string optional reference of a property / building / unit

Example

{"eventType":"Invoicing.Invoice.Booked",
  "data":{
    "reference":1234,
    "externalReference":"54820394-001",
    "orderReference": null,
    "externalOrderReference": null,
    "accountingReference":"4711",
    "invoiceItems":[
      {"lineNumber":1,
       "accountNumber":"4712.100001",
       "costCenterNumber":"700",
       "taxCode":"00",
       "masterdataReference":"4712.01"
      }
    ]

  }
}

Invoicing.Invoice.Cancelled

This message goes from GARAIO REM to the invoice provider and signals that a user has cancelled the booked invoice in GARAIO REM (Storno)

Field Type Content / Remarks
eventType string Invoicing.Invoice.Cancelled
data hash
  reference longint unique identifier for the invoice, generated by GARAIO REM
  externalReference string external identifier from the invoice provider
  orderReference longint|null unique identifier of the associated order
  externalOrderReference string|null external identifier of the associated
  reason string optional description why the invoice has been cancelled

Example

{"eventType":"Invoicing.Invoice.Cancelled",
  "data":{
    "reference":1234,
    "externalReference":"54820394-001",
    "orderReference": null,
    "externalOrderReference": null,
    "reason":"will not be payed because of reasons"
  }
}

Invoicing.Invoice.Payed

This message goes from GARAIO REM to the invoice provider and signals that GARAIO REM has payed the invoice

Field Type Content / Remarks
eventType string Invoicing.Invoice.Payed
data hash
  reference longint unique identifier for the invoice, generated by GARAIO REM
  externalReference string external identifier from the invoice provider
  orderReference longint|null unique identifier of the associated order
  externalOrderReference string|null external identifier of the associated
  paymentDate date Date when the payment was triggered in GARAIO REM

Example

{"eventType":"Invoicing.Invoice.Payed",
  "data":{
    "reference":1234,
    "externalReference":"54820394-001",
    "orderReference": null,
    "externalOrderReference": null,
    "paymentDate":"2021-03-10"
  }
}

Message Flows

Invoice submission happy path

GARAIO REM receives an invoice that passes all validations, stores the invoice, creates the booking and sends the InvoiceAccepted message back to the invoice provider with the external invoice reference

Alt text

Invoice validation errors

GARAIO REM receives an invoice that does not pass the validations, does NOT store the invoice and sends the InvoiceRejected message back to the invoice provider with the external invoice reference and the reasons (validation errors)

Alt text

Incomplete invoice

GARAIO REM receives an incomplete invoice that passes the basic validations but is not complete, stores the invoice, does NOT create the booking and sends the InvoiceAccepted message back to the invoice provider with the external invoice reference

Later, a user completes the invoice, GARAIO REM creates the booking and sends the InvoiceBooked message back to the invoice provider with the internal GARAIO REM reference and the external invoice reference

Alt text

Invoice deleted

GARAIO REM receives an invoice that passes the basic validations but needs completion, stores the invoice and sends the InvoiceAccepted message back to the invoice provider with the external invoice reference

Later, a user deletes the invoice and GARAIO REM sends the InvoiceDeleted message back to the invoice provider with the external invoice reference

Alt text

Invoice cancelled

GARAIO REM receives an invoice that passes the validations, stores the invoice, creates the booking and sends the InvoiceAccepted message back to the invoice provider with the external invoice reference

Later, a user cancels the invoice and GARAIO REM sends the InvoiceCancelled message back to the invoice provider with the external invoice reference

Alt text

Invoice payed

GARAIO REM receives an invoice that passes the validations, stores the invoice, creates the booking and sends the InvoiceAccepted message back to the invoice provider with the external invoice reference

Later, GARAIO REM pays the invoice and GARAIO REM sends the InvoicePayed message back to the invoice provider with the external invoice reference

Alt text

Order and invoice message flow with incomplete invoices

GARAIO REM receives an order and stores the order.

Later, The invoice provider finds the order through a GraphQL query and sends an InvoiceCreated message to GARAIO REM including the order number. GARAIO REM validates the invoice data, stores the invoice, links it to the order and sends an InvoiceAccepted message to the invoice provider.

Later, a user completes the invoice in GARAIO REM and the invoice is booked.

Later, GARAIO REM pays the invoice and GARAIO REM sends the InvoicePayed message back to the invoice provider with the external invoice reference

Alt text

Minimal Swiss QR Code when creating an Invoice

This documentation describes the minimum data Garaio REM needs to process an incoming Swiss QR Code. We do not require all the information for a valid Swiss QR Code, however, what we do accept, MUST be conform with the Swiss QR Code Specification v2.2 - for your convenience we have copied this specification here: SwissQR Code Specification v2.2.

Unlike the SwissQRCode Specification, we do not require: header-qrType, header-version, header-coding, payment-currency or the "creditor" (name and address information).

Attributes we currently process when using a Swiss QR Code to create an invoice:

GaraioREM SwissQR Key SwissQRCode Group Key SwissQRCode Input Key Garaio REM Data Type Description
swissQrCode { hash swissQrCode; optional
  cdtrInf { hash Creditor Account Information; required data group
    iban string fixed length:21 alphanumeric characters ('CH' or 'LI' must start SwissQRCodes; QR-IBANs must have the ESR-Reference-Type (rmtInf.tp) of 'QRR'); required
  }
  ccyAmt { hash Payment Information; required data group
    amt decimal Payment Amount (maximum 12 characters allowed, including the decimal point); required
    ccy string Currency (we only accept 'CHF' for processing); Optional
  rmtInf { hash Payment Reference Information; required data group
    tp string Reference Type (valid options are: QRR (QR-Reference), SCOR (Swiss Creditor-Reference ISO 11649), NON (no reference) - this is used to validate that the IBAN and ESR-Reference are valid compared to the QR Type); required
    ref string Reference string; required for QRR or SCOR types
    addInf { hash Additional Information; optional data group
      ustrd string Processing Message; Optional
    }
  }
}

NOTE:

  • When payment-currency is given we validate that it is ONLY 'CHF'
  • When header-qrType, header-version, header-coding is given it will be validated to against the SwissQRCode Specification Version 0200

Sample Invoice Data to be created when minimal Swiss QR Code values are given:

{"eventType":"Invoicing.Invoice.Created",
  "data":{
    "externalReference":"1234",
    "creditorReference":"100010",
    "accountingReference":"1",
    "invoiceDate":"2020-10-21",
    "dueDate":"2020-11-21",
    "bookingDate":"2020-10-21",
    "languageCode":"de",
    "documentUrl":"https://path/to/the/scan.pdf",
    "invoiceItems":[
      { "lineNumber":1,
        "accountNumber":"1.400000",
        "bookingAmount":1200.5,
        "bookingText":"this goes into the booking movement"
      }
    ],
    "swissQrCode":{
      "cdtrInf":{
        "iban":"CH4431999123000889012"
      },
      "ccyAmt":{
        "amt":"1200.50"
      },
      "rmtInf":{
        "tp":"QRR",
        "ref":"210000000003139471430009017",
        "addInf":{
          "ustrd": "Optional Payment Info"
        }
      }
    }
  }
}

NOTE: the original SwissQR Code Standards can be found at: https://www.paymentstandards.ch/dam/downloads/ig-qr-bill-en.pdf

About reference and externalReference in the context of Invoicing.*

While a reference is unique, an externalReference does not have to be. This has some implications for tracking state change notifications in later messages, e.g. being able to map a Invoicing.Invoice.Booked to the correct preceding Invoicing.Invoice.Created.

The intended use of the field externalReference is for the supplier document reference. As two suppliers might both send you an Invoice with reference "1", you can end up with duplicate externalReferences.

You have the following options to track state change notifications:

  • (Recommended) When tracking responses (Accepted and Rejected messages), use the correlation id (see result messages).
  • (Recommended) To track state changes (e.g. Invoicing.Order.Deleted or Invoicing.Invoice.Booked), use the reference. When creating an Invoice or Order, keep of track the returned reference. Look at the reference field of subsequent messages to identify their subject.
  • As an alternative for state change tracking, you can choose to set unique externalReferences and compare these with the externalReference field of subsequent messages. It is your responsability to make sure externalReference is unique (remember your users might be allowed to set these manually in GREM).
  • Only for customers, don't write partner services that integrate this way: You can choose to set reference yourself when creating. This makes sense if you have an upstream system that coordinates document reference assignment. reference will override the reference generated by GREM by default. If you use reference, it is your responsability to prevent clashes with the database sequences used by GREM to generate references (e.g. by making sure no documents are created in GREM). The reference must be unique.