Invoice Integration
This guide will take you through creating and activating invoices.
Invoice API Endpoint Documentation
For resource definition see the API Documentation.
Create an Invoice​
Below guide assumes a Client or Client Service Account Token.
Client Shared ERP System
In the case of a Cloud SaaS ERP system or other multi-client ERP system a system-wide
configuration needs to be enabled to create an invoice.
Contact Quiddly support for this.
Then amend the client_id for whom the invoice will be issued to the payload.
Follow below guide with these adjustments and all should work as expected.
Invoice with Only Required Fields​
The below example contains the minimum data required to create an invoice in the Quiddly Platform. Note, that the invoice is a core concept and connects to a lot of functionality. As such there are several more fields (many listed in the next section) that you may wish to use in your integration when creating an invoice.
POST https://{alias}api.{domain}/invoices
Headers
Content-Type: application/json
Authorization: Bearer eyy...
Request
{
// atleast one article row is required
"articleRows": [{
"description": "This is a article",
"discountType": "PERCENTAGE", // Describes how the totalDiscount amount should be treated (can be either PERCENTAGE or CURRENCY)
"price": 100,
"quantity": "2,00", // Note that quantity is in string format. 1.00 and 1,00 are both valid
"total": 200.0,
"totalDiscount": 0.0, // e.g if discountType is PERCENTAGE and totalDiscount is 20, the discount is treated as 20% of the article price
"totalExclVat": 200,
"totalVat": 50,
"unit": "pcs", // can be anything
"vatPercentage": 25 // allow values are 0, 6, 12 and 25
}
],
"currency": {
"baseCurrency": "SEK",
"exchangeRate": 1.0,
"invoiceCurrency": "SEK"
},
"dates": {
"expireDate": "2021-06-01",
"invoiceDate": "2021-05-17"
},
"debtor": {
"cellPhone": "+46",
"customerNumber": "123", // value must be provided and is the unique ERP number for the debtor
"identificationNumber": "1234567890",
"invoiceAddress": {
"address": "Address", // value must be provided
"city": "City", // value must be provided
"countryCode": "SE", // required ISO 3166-1 alpha-2 format
"name": "Name", // value must be provided
"zip": "12345" // value must be provided
},
"name": "Name", // required name of the debtor
"type": "COMPANY" // can be either COMPANY or PERSON. If field is completly omitted our backend will try to resolve the proper type
},
"distributionCode": "LETTER", // can be either one of LETTER, EMAIL, ELECTRONIC_INVOICE, null. The invoice will be distributed based on selected value
"invoiceNumber": "123456", // required and unique invoice number
"productCode": "INVOICE_SERVICE", // decided what kind of product should be used for the invoice. E.g REMINDER_SERVICE, INVOICE_SERVICE, INVOICE_FACTORING_SELL
"totals": {
"taxReduction": 0.0, // in case any tax reduction is applied it can be put here
"total": 250.0,
"totalExclVat": 200,
"totalRoundOff": 0.0,
"totalToPay": 250.0,
"totalVat": 50.0
},
"type": "INVOICE", // Can be either INVOICE or CREDIT_INVOICE. In case the invoice is a credit invoice the CREDIT_INVOICE must be specified. Also all totals, amount and prices must be specified in negative values.
// vat declaration is mandatory and should always be provided. Even if the total vat is 0
"vats": [{
"percentage": 25,
"totalTaxable": 200,
"totalVat": 50
}
]
}
Additional Invoice Fields​
There are additional fields, beyond the required once seen above, that can be provided when creating an invoice. Although they are optional in terms of API schema they may be required for specific functionality. For instance, an email distribution cannot be sent without an email address. Some of these dependencies are included as comments in below list.
As fields are subject to validation in our backend-application, we advise starting with the minimal example above. And, when that functions correctly start adding additional fields as required.
{
"dates": {
"deliveryDate": "2021-06-01"
},
"debitInvoiceNumber": "123", // if the invoice type is CREDIT_INVOICE you need to make sure to connect the credit invoice to the debit. It's done with this field
"debtor": {
"FMI": "", // in case the debtor.type is PERSON and the invoice should be send as ELECTRONIC_INVOICE we need to know the FMI number for the person's bank to be able to send the invoice accordingly
"GLN": "1234567890123", // in case the debtor.type is a COMPANY and the invoice should be distributed as ELECTRONIC_INVOICE we need to know the GLN number of the receiving VAN provider
"identificationNumber": "1234567890",
"deliveryAddress": { // delivery address is optional
"address": "Address", // value must be provided
"city": "City", // value must be provided
"countryCode": "SE", // required ISO 3166-1 alpha-2 format
"name": "Name", // value must be provided
"zip": "12345" // value must be provided
},
"distributionChannel": "EMAIL", // in case you want to set debtor default distribution. Is used together with distributionChannelOverride
"distributionChannelOverride": true, // decided if the distribution channel should be overriden. Is used together with distributionChannel
"email": "[email protected]" // email to the debtor. In case you want to distributed the invoice with EMAIL this field must be provided with a valid email,
"phone": "+46",
"vatNumber": "SE123456789001",
"documentTemplateCode": "STANDARD", // decided invoice template used when generating the invoice. Can be either default STANDARD or STANDARD_MARKETING
"fees": {
"administration": 0.0,
"administrationVatPercentage": 25,
"freight": 0.0,
"freightVatPercentage": 25
},
"ourOrderNumber": "John",
"ourReference": "Jane",
"remark": "This is my invoice remark", // additional text on the invoice
"reverseCharge": false, // shows additional text on the invoice if the invoice has reverse charge handling
"serviceProviderCode": "A_VALID_SERVICE_PROVIDER", // in case a specific service provider should be used for the invoice. E.g a specific service provider for a specific product.
"terms": {
"delivery": "DHL",
"payment": "15 Days"
},
"yourContactPerson": "Your contact", // adds information about your contact person on the invoice. Is also in some cases used together with ELECTRONIC_INVOICE distributions. Tightly coupled with yourReference field
"yourReference": "Ref 123" // adds your reference info on invoice. Is tightly coupled with ELECTRONIC_INVOICE distributions. Where debtor system usually requires at least yourReference, but also in some cases yourContactPerson
},
}
Activate Invoice​
Basic Activation​
Ideally all invoice settings are added when the invoice is created. In this case an empty payload can be used to activate the invoice.
PUT https://{alias}api.{domain}/invoices/I.111222333/activate
Headers
Content-Type: application/json
Authorization: Bearer eyy...
Request
{}
Additional Fields​
As mentioned above, all invoice data would be set when the invoice is created. However, if there is a need we can set some fields when activating the invoice, these are listed below with details in the comments.
{
"productCode": "INVOICE_SERVICE", // decided what kind of product should be used for the invoice. E.g REMINDER_SERVICE, INVOICE_SERVICE, INVOICE_FACTORING_SELL
"distributionCode": "LETTER", // can be either one of LETTER, EMAIL, ELECTRONIC_INVOICE, null. The invoice will be distributed based on selected value
"documentTemplateCode": "STANDARD", // decided invoice template used when generating the invoice. Can be either default STANDARD or STANDARD_MARKETING
"serviceProviderCode": "A_VALID_SERVICE_PROVIDER", // in case a specific service provider should be used for the invoice. E.g a specific service provider for a specific product.
}