Introduction

Welcome to the Offective API documentation.

The Offective API allows you to retreive and add data to the Offective cloud in a simple, programmatic way using the Offective REST API. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve or add information.

Are you missing functionalities in the Offective API? Please file a ticket from your Offective account and we are happy to discuss this and possibly put it on the roadmap for API development.

The API documentation will start with a general overview about the design and technology that has been implemented, followed by information about specific endpoints. Every endpoint includes an example CURL request and example responses.

Scroll down to read through the documentation, or directly jump to a specific endpoint using the navigation.

Request and request methods

Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI. Requests should be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required.

Method Usage
GET For retrieval of information from your Offective administration, you should use the GET method. The information you request will be returned to you as a JSON object. Any request using the GET method is read-only and will not affect any of the objects you are querying.
DELETE To delete data from your administration and remove it entirely from the Offective database, use the DELETE method. This will remove the specified object if it is found. If it is not found, the operation will return a response indicating that the object was not found. The final state will be the same regardless of its existence.
PUT To update existing information, the PUT method is available. You cannot create new data using the PUT method.
POST To create a new object, your request should specify the POST method. The POST request includes all of the attributes necessary to create a new object. When you wish to create a new object, send a POST request to the target endpoint.

Authentication

In order to interact with the Offective API, you or your application must authenticate.

The Offective API handles this through an API key which you can retreive from within your Offective dashboard.

The API key functions as the most important part in the authentication process. In effect, it acts as a substitute for a password.

Because of this, it is absolutely essential that you keep your API key secure. Upon generation from within Offective, the web interface will only display the token a single time in order to prevent the token from being compromised.

So, in order to authenticate you must make sure you have the API module enabled in your Offective account and you have an API key. To authenticate, Offective expects two header parameters within every request: Offective-ApiKey and Offective-Username. The username obviously is the username you login to Offective with.

An simple CURL example request can be found for every endpoint documentation on this website. The example includes the authentication headers.

Response

When a request is successful, a response body will typically be sent back in the form of a JSON object or an array of JSON objects.  Every endpoint description on this site includes an example response and explanation of all possible response parameters.

Offective maintains the following response policies:

For every request:

  • HTTP status 401 including an errorMessage JSON object will be returned if authentication fails or ratelimit is exceeded. More information about error messages below.
  • HTTP status 400 including an errorMessage JSON object will be returned if the request was not processed correctly due to for example an error in submitted data or validation errors.
  • HTTP status 500 including an errorMessage JSON object will be returned if a technical error has occurred.

For PUT and POST requests:

  • HTTP status 200 with an empty JSON object will be returned if the object was not updated or created.
  • HTTP status 400 will probably occur instead, which will contain detailed information as to why the request did not succeed.
  • HTTP status 200 with an JSON representation of the update or newly created object will be returned if the request succeeded.

For GET requests:

  • HTTP status 200 with an empty JSON response with will be returned if no objects are found.
  • HTTP status 200 with an JSON array of items will be returned if there are objects found.

In general, when an error occurs, the response will contain JSON information about the error. A typical JSON error message will look like this:

Most common errors are:

  • HTTP 401, UNAUTHORIZED: Ratelimit exceeded
    You have exceeded the maximum requests for the past hour.
  • HTTP 401, UNAUTHORIZED: Invalid authentication credentials
    Your API key or username is incorrect or the combination of both is incorrect.
  • HTTP 400, INVALID_JSON: JSON is incorrect
    You have requested with invalid JSON data. The details are usually in the ‘errorMessage’
  • HTTP 405, METHOD_NOT_ALLOWED: Invalid HTTP method
    The request method is invalid or incompatible with the destination endpoint. 
  • HTTP 500, SYSTEMERROR: An system error has occured within Offective
    If your call generates an technical error within Offective, this error will be returned. 
    • GET rest/listrelations/

      • Get a list of relations

This GET method allows you to retreive a list of relations including contact and address details from your administration.

  • Request
  • Response

Request body parameters

Parameters with an asterix (*) are required!
Parameters with a double asterix (**) means one of them is required!
RelationType String More info
(optional) Defines what type of relations to retreive. Value should be one of the following: All, Supplier, Customer
RelationNumber String More info
(optional) Filter the requested relations by number. This can be either the supplier number or the customer number
RelationName String More info
(optional) Filter the requested relations by the name of the business or private relation
RelationGUID Long More info
(optional) Retreive the relation with the specified GUID (unique identifier). This will always return 0 or 1 results.
RelationEmail String More info
(optional) Filter the requested relations by the e-mailadres of the relation
Limit Integer More info
Defines the limit of items to retreive
Offset Integer More info
Defines the offset for the retreive

Request Example

Response body parameters

Email String More info
Relation e-mail address
Phone String More info
Relation phone number
Address_City String More info
City of the correspondence address
Address_Street String More info
Street of the correspondence address
Address_PostalCode String More info
Postalcode of the correspondence address
Address_CountryCode String More info
ISO 3166 (A2) country code of the correspondence address
Address_Unit String More info
Unit number of the correspondence address
Address_UnitAppendix String More info
Appendix (e.g. appartment/suite/floor) for the address unit
IsCustomer Boolean (true|false) More info
Whether the relation is marked as customer or not
IsSupplier Boolean (true|false) More info
Whether the relation is marked as supplier or not
IsOther Boolean (true|false) More info
Wheter the relation is marked as other customer or not
SupplierNumber Integer More info
If the relation is a supplier, this will be the suppliers number
CustomerNumber Integer More info
If the relation is a customer, this will be the relations customernumber
RegistrationNumber String More info
This is the national registration number of the company
TaxIdentificationNumber String More info
This is the VAT number of the company
Relation_Contact Array More info
An JSON array containing the relation contacts
Relation_Contact > Email String More info
Contact e-mail address
Relation_Contact > Phone String More info
Contact phonenumber
Relation_Contact > Sex String More info
Contact Sex (Man|Vrouw)
Relation_Contact > LastName String More info
Contact last name
Relation_Contact > FamilyName String More info
Deprecated, use LastName instead.
Relation_Contact > FirstName String More info
Contact first name
Relation_Contact > ContactNotes String More info
Notes to be added to the contact
Relation_Contact > Preposition String More info
The family name preposition (In Dutch: tussenvoegsel).
Relation_Contact > DefaultContact String More info
Whether this contact is the relations main / default contact or not
PrivateOrBusiness String More info
Wether the relation is a private (cunsumer) or business relation. (PrivateRelation|BusinessRelation)
RelationGUID Long More info
Unique identifier for this relation. This will never change and always stay unique.

Response JSON Example

The response order can vary from the parameter order above
    • POST rest/addbusinessrelation/

      • Add a business relation

This POST method allows you to create a new business relation including contact and address details.

Important!
It is very important to understand how your request will be interpreted since this is a specific process and the outcome of your request can be unexpected.

General
First of all, the mandatory parameters are appended with an asterix (*). The rest of the parameters are not mandatory. The response of this request will be the details of the relation. The response format can be found in the ‘ListRelations’ endpoint response description.

Also, the parameters customerNumber and supplierNumber may not be 0. Sending 0 as number will be interpreted as an empty value.

Parameters
Two parameters in this request needs some explanation: OnExistingRelationNumber and OnExistingRelationName. We will explain both parameters below.

OnExistingRelationName This field determines what should happen when the relation you POST already exist, based on the relation name. The default behaviour is that we will return the already existing relation. However, if you want the creation of the relation to be forced you can add this parameter in your POST. When set to CONTINUE we will continue creating the relation, resulting in you having multiple relations with exactly the same name.

OnExistingRelationNumber This field determines how we should behave when the relation you POST already exist, based on the customer or supplier number. The default behaviour is that we will return the already existing relation. However, if you want the creation of the relation to be forced you can add this parameter in your POST. When set to CONTINUE we will continue creating the relation, but with a new, unique number. When set to ABORT (default), we will abort the creation and return the already existing relation instead.

Please note that is is not required to post a relation or suppliernumber. If you leave both numbers empty, we will automatically generate a number for you and return the newly created relation with the automatic defined number.

  • Request
  • Response

Request body parameters

Parameters with an asterix (*) are required!
Parameters with a double asterix (**) means one of them is required!
Name* String More info
Relation name
OnExistingRelationNumber String More info
ABORT|CONTINUE (defaults to ABORT)
OnExistingRelationName String More info
ABORT|CONTINUE (defaults to ABORT)
Email String More info
Relation e-mail address
Phone String More info
Relation phone number
Address_City String More info
City of the correspondence address
Address_Street String More info
Street of the correspondence address
Address_PostalCode String More info
Postalcode of the correspondence address
Address_CountryCode String More info
ISO 3166 (A2) country code of the correspondence address
Address_Unit String More info
Unit number of the correspondence address
Address_UnitAppendix String More info
Unit number appendix. Examples: a, b, or suite c.
IsCustomer Boolean (true|false) More info
Whether the relation is marked as customer or not
IsSupplier Boolean (true|false) More info
Whether the relation is marked as supplier or not
IsOther Boolean (true|false) More info
Wheter the relation is marked as other relation or not
SupplierNumber Integer More info
If the relation is a supplier, this will be the suppliers number
CustomerNumber Integer More info
If the relation is a customer, this will be the relations customernumber
RegistrationNumber String More info
This is the national registration number of the company
TaxIdentificationNumber String More info
Tax/VAT number without country code. Example: 123456789 or 12345678B01
Relation_Contact Array More info
An JSON array of contacts for the relation. The first contact will be used as the relations main contact.
Relation_Contact > Email String More info
Contact e-mail address
Relation_Contact > Phone String More info
Contact phonenumber
Relation_Contact > Sex String More info
Contact Sex (Man|Vrouw)
Relation_Contact > LastName String More info
Contact last name
Relation_Contact > FirstName String More info
Contact first name
Relation_Contact > ContactNotes String More info
Notes to be added to the contact

Request Example

The response will be the just created relation, or the already existing relation. The response format will be the same as the response format for endpoint 'ListRelations'. Please view the 'ListRelations' endpoint for details.

Response body parameters

-

Response JSON Example

The response order can vary from the parameter order above
    • POST rest/addprivaterelation/

      • Add a private (consumer) relation

This POST method allows you to create a new private relation (consumer) including contact and address details.

Important!
It is very important to understand how your request will be interpreted since this is a specific process and the outcome of your request can be unexpected.

General
First of all, the mandatory parameters are appended with an asterix (*). The rest of the parameters are not mandatory. The response of this request will be the details of the relation. The response format can be found in the ‘ListRelations’ endpoint response description.

Also, the parameters customerNumber may not be 0. Sending 0 as number will be interpreted as an empty value for this parameter.

Parameters
Two parameters in this request needs some explanation: OnExistingRelationNumber and OnExistingRelationName. We will explain both parameters below.

OnExistingRelationName This field determines what should happen when the relation you POST already exist, based on the relation name. A match occurs when the relations first- and lastname match. The default behaviour is that we will return the already existing relation. However, if you want the creation of the relation to be forced you can add this parameter in your POST. When set to CONTINUE we will continue creating a new relation, which will result in multiple consumers with the same name existing in your administration.

OnExistingRelationNumber This field determines how we should behave when the relation you POST already exist, based on the customer number. The default behaviour is that we will return the already existing relation. However, if you want the creation of the relation to be forced you can add this parameter in your POST. When set to CONTINUE we will continue creating a new relation, but with a differtent, unique number. When set to ABORT (default), we will abort the creation and return the already existing relation instead.

Please note that is is not required to post a relation number. If you leave it empty, we will automatically generate a number for you and return the newly created relation with the automatic defined number.

  • Request
  • Response

Request body parameters

Parameters with an asterix (*) are required!
Parameters with a double asterix (**) means one of them is required!
OnExistingRelationNumber String More info
ABORT|CONTINUE (defaults to ABORT)
OnExistingRelationName String More info
ABORT|CONTINUE (defaults to ABORT)
Address_City String More info
City of the correspondence address
Address_Street String More info
Street of the correspondence address
Address_PostalCode String More info
Postalcode of the correspondence address
Address_CountryCode String More info
ISO 3166 (A2) country code of the correspondence address
Address_Unit String More info
Unit number of the correspondence address
Address_UnitAppendix String More info
Unit number appendix. Examples: a, b, or suite c.
IsCustomer Boolean (true|false) More info
Whether the relation is marked as customer or not
IsOther Boolean (true|false) More info
Wheter the relation is marked as other relation or not
CustomerNumber Integer More info
If the relation is a customer, this will be the relations customernumber
Relation_Contact * Array More info
An JSON array of contacts for the relation. The first contact will be used as the relations main contact.
Relation_Contact > Email String More info
Contact e-mail address
Relation_Contact > Phone String More info
Contact phonenumber
Relation_Contact > Sex String More info
Contact Sex (Man|Vrouw)
Relation_Contact > LastName * String More info
Contact last name
Relation_Contact > FirstName * String More info
Contact first name
Relation_Contact > ContactNotes String More info
Notes to be added to the contact

Request Example

The response will be the just created relation, or the already existing relation. The response format will be the same as the response format for endpoint 'ListRelations'. Please view the 'ListRelations' endpoint for details.

Response body parameters

-

Response JSON Example

The response order can vary from the parameter order above
    • PUT rest/updaterelation/

      • Update a CRM relation

This PUT method allows you to update information for a CRM relation. The relation to be updated is identified by the ‘RelationGUID’ parameter.

RelationGUID
Every relation has an unique identifier. Using the ListRelations endpoint you can extract the identifier for each relation.

  • Request
  • Response

Request body parameters

Parameters with an asterix (*) are required!
Parameters with a double asterix (**) means one of them is required!
RelationGUID * Long More info
The unique identifier of the relation to be update
Email String More info
Relation e-mail address
Phone String More info
Relation phone number
RegistrationNumber String More info
This is the national registration number of the company. Only applies to business relations.
TaxIdentificationNumber String More info
Tax/VAT number without country code. Example: 123456789 or 12345678B01. Only applies to business relations.
Name String More info
Relation name. Only applies to business relations.
Address_City String More info
City of the correspondence address
Address_Street String More info
Street of the correspondence address
Address_PostalCode String More info
Postalcode of the correspondence address
Address_CountryCode String More info
ISO 3166 (A2) country code of the correspondence address
Address_Unit String More info
Unit number of the correspondence address
Address_UnitAppendix String More info
Unit number appendix. Examples: a, b, or suite c.
SupplierNumber Integer More info
If the relation is a supplier, this will be the suppliers number.
CustomerNumber Integer More info
If the relation is a customer, this will be the relations customer number. Please note that this number must be unique in your administration.
Relation_Contact Array More info
An JSON array with contact information to update the relation main contact. At the moment only one contact is supported.
Relation_Contact > Email String More info
Contact e-mail address
Relation_Contact > Phone String More info
Contact phonenumber
Relation_Contact > Sex String More info
Contact Sex (Man|Vrouw)
Relation_Contact > LastName String More info
Contact last name
Relation_Contact > FirstName String More info
Contact first name
Relation_Contact > ContactNotes String More info
Contact notes

Request Example

The response will be the updated relation. The response format will be the same as the response format for endpoint 'ListRelations'. Please view the 'ListRelations' endpoint for details.

Response body parameters

-

Response JSON Example

The response order can vary from the parameter order above
    • GET rest/listproducts

      • Get a list of products

Retreive a list of products from your administration. A maximum of 100 products will be returned at once. Use offset and limit parameters to retrieve more products over multiple calls. It is also possible to retreive just one specific product by adding the ArticleNumber or EAN request parameter.

  • Request
  • Response

Request body parameters

Parameters with an asterix (*) are required!
Parameters with a double asterix (**) means one of them is required!
Category String More info
An optional parameter to only retreive products from one specific category
ArticleNumber String More info
An optional parameter to retreive only the product with exactly this articlenumber. The result will never be more than one item.
EAN String More info
An optional parameter to retrieve only the product with exactly this EAN code. The result will never be more than one item.
Limit Integer More info
Defines the limit of items to retreive
Offset Integer More info
Defines the offset for the retreive

Request Example

Response body parameters

Name String More info
The product name
ArticleNumber String More info
The article number (not nessecarily numeric)
SupplierArticleNumber String More info
The article number (not nessecarily numeric) that the supplier uses
Category String More info
Category name for this product
EAN String More info
Product EAN code
Description String More info
Product description, limited to 400 characters
StockQty Float More info
The actual stock quantity
PurchasePrice Float More info
The latest purchase price
Price Float More info
The default sale price excluding VAT
VATPercentage Float More info
The VAT percentage
Unit String More info
The product unit (example: 'piece' or 'hour')

Response JSON Example

The response order can vary from the parameter order above
    • POST rest/addproduct/

      • Add a product (article)

This POST method allows you to create a new product (catalog article).

Notes:

  • ArticleNumber, NewName and CategoryName are mandatory fields
  • You can set CategoryCreateIfMissing to true if you want the category to be created if it is not found.
  • The request and response parameters are the same as the request parameters for the endpoint ‘UpdateProduct’. Please see the endpoint updateproduct for more details.
  • Request
  • Response

Request body parameters

Parameters with an asterix (*) are required!
Parameters with a double asterix (**) means one of them is required!
SEE ENDPOINT UpdateProduct String More info
Alle request parameters allowed for the endpoint UpdateProduct are allowed for this endpoint as well. The additional parameters are listed below.

Request Example

The response will be the just created product. The returned parameters are the same as the response parameters for the endpoint UpdateProduct.

Response body parameters

-

Response JSON Example

The response order can vary from the parameter order above
    • PUT rest/updateproduct/

      • Update information for a specific product

Update some product fields for a specific product. For example update product stock quantity or product price.

Note that it is not required to set all request parameters. For example, if you just want to update the stock value, there is no need to set the NewName parameter as well.

Updating the stock quantity for a grouped product ('verzamelproduct')?
  • Request
  • Response

Request body parameters

Parameters with an asterix (*) are required!
Parameters with a double asterix (**) means one of them is required!
ArticleNumber ** String More info
You can use either AirtcleNumber or EAN to select the product to be updated.
EAN ** String More info
You can use either AirtcleNumber or EAN to select the product to be updated.
CategoryName String More info
The name of the category to associate the product with.
CategoryCreateIfMissing String More info
Defaults to false. Whether to create the category or not if it does not exist. If set to false (default) the product will not be added if the category is not found.
NewName String More info
The updated productname
NewSupplierArticleNumber String More info
The updated articlenumber used by the product's supllier
NewDescription String More info
The updated product description
NewSalePrice Float More info
The update product sale price
NewStockQty Float More info
If you want to update the products stock quantity, enter the amount here.
StockUpdateMode String More info
Choose either Relative or Absolute (defaults to Relative). Relative means: add the specified amount in the 'NewStockQty' parameter to the product stock quantity. Absolute means: set the product stock quantity to the value of 'NewStockQty'
NewStockMutationComment String More info
An optional description for this stock mutation
NewStockMutationPurchasePrice Float More info
The purchase costs for this stock modification (only applicable if stock is added / if NewStockQty is a positive value).
NewVATPercentage Float More info
If you want to change the VAT percentage, use this parameter. Example value: 21 to update the VAT to 21%.
NewUnit String More info
The name of the product unit (for example: 'piece' or 'hour')
NewPurchasePrice Float More info
The purchase price / supplier price
NewPurchasePriceVATPercentage Float More info
The purchase price / supplier price VAT percentage

Request Example

Response body parameters

Name String More info
The updated product name
ArticleNumber String More info
The article number (not nessecarily numeric)
SupplierArticleNumber String More info
The article number (not nessecarily numeric) that the supplier uses
Category String More info
Category name for this product
EAN String More info
Product EAN code
Description String More info
Product description, limited to 400 characters
StockQty Float More info
The actual stock quantity
PurchasePrice Float More info
The latest purchase price
Price Float More info
The default sale price excluding VAT
VATPercentage Float More info
The VAT percentage
MinimalStockQty Float More info
The minimal required stock quantity for this product as configured in Offective.
UnitsPerPackage Float More info
The suppliers units per package. In Offective this is known as 'verpakkingseenheid'.
Unit String More info
The product unit (for example: 'piece' or 'hour')

Response JSON Example

The response order can vary from the parameter order above
    • GET rest/listorders/

      • Retrieve a list of sales orders

Retrieve a list of sales orders from your administration. A maximum of 50 orders will be returned at once. Use offset and limit parameters to retrieve more orders over multiple calls.

  • Request
  • Response

Request body parameters

Parameters with an asterix (*) are required!
Parameters with a double asterix (**) means one of them is required!
Limit Integer More info
Defines the limit of items to retreive
Offset Integer More info
Defines the offset for the retreive
DateFrom Date String (dd-MM-yyyy) More info
The order from date in format dd-MM-yyyy. (http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html). Default to no from date filter.
DateTill Date String (dd-MM-yyyy) More info
The order till date in format dd-MM-yyyy. (http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html) Defaults to no till date.
HtmlAsPlainText Boolean (true|false) More info
Whether the rich-text fields will be returned as plain text or not. Defaults to false.

Request Example

The response will be a list (JSON array) of retrieved orders. The returned are exactly the same as the returned parameters which are returned by the endpoint 'AddOrder'. Please check the response specifications for the endpoint 'AddOrder' for more info. For your convenience we have included a response example below.

Response body parameters

-

Response JSON Example

The response order can vary from the parameter order above
    • POST rest/addorder/

      • Add a sales order

This POST method allows you to create a new order with multiple orderlines, associated to a customer.

Notes:

  • Maximum 100 orderlines per order allowed.
  • If CustomerNumber is used to identify the customer, the number must be larger then zero. A zero value will be interpreted as empty.
  • If CustomerName is used to identify the customer and you have multiple customers with exactly the same name, we will use the first found match.
  • Request
  • Response

Request body parameters

Parameters with an asterix (*) are required!
Parameters with a double asterix (**) means one of them is required!
CustomerNumber ** Integer More info
The customer, identified by its customer number, to be associated with the order
CustomerName ** String More info
The customer, identified by its name, to be associated with the order
OrderDate Date String (dd-MM-yyyy) More info
The order date in format dd-MM-yyyy. (http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html) Defaults to current date.
OrderNotes String More info
Custom order notes / order description
OrderDiscountPc Float More info
Discount % to be applied to the order
OrderReference String More info
Order reference number or text (max. 150 characters)
HtmlAsPlainText Boolean (true|false) More info
Whether the response rich-text fields will be returned as plain text or not. Defaults to false.
PackingSlipNotes String More info
Extra notes for the packing slip
Order_Orderline * Array More info
An JSON array of orderlines
Order_Orderline > ProductNumber ** String More info
The productnumber of the product to be associated with the orderline.
Order_Orderline > ProductEAN ** String More info
The product EAN code of the product to be associated with the orderline.
Order_Orderline > Quantity * Float More info
Quantity of items in this orderline
Order_Orderline > UnitPriceExclTax Float More info
Price per ordered unit
Order_Orderline > TaxPc * Float More info
Numeric representation of the tax % to be applied for this orderline. Please note that this percentage must be available within your Offective administration.
Order_Orderline > SubTotalInclTax Float More info
The orderline subtotal, including taxes. When this parameter is set, the price per unit will be ignored and automatically calculated.
Order_Orderline > Description String More info
Orderline description

Request Example

The response will be the just created order. All the parameters available with the AddOrder request will be returned. In addition, the parameters below will be returned (if applicable):

Response body parameters

OrderTotalInclTax Float More info
The order total value, including taxes and optional discounts.
OrderNumber Integer More info
The automatically determined ordernumber
Order_Address Array More info
A JSON array of order addresses. At the moment this will never contain more then one address, which is the address selected for the order.
Order_Address > Address_CountryCode String More info
ISO 3166 (A2) country code of the order address
Order_Address > Address_PostalCode String More info
Postal / zip code
Order_Address > Address_Street String More info
Order_Address > Address_Unit String More info
Order_Address > Address_City String More info
Order_Address > Address_UnitAppendix String More info
Appendix (e.g. appartment/suite/floor) for the address unit
Order_Address > AddressType String More info
At the moment this will always return "OrderAddress"
Order_Contact Array More info
A JSON array of order contacts. At the moment this will contain the main order contact and the packingslip contact (if applicable).
Order_Contact > ContactType String More info
Order|PackingSlip
Order_Contact > FirstName String More info
Order_Contact > Phone String More info
Order_Contact > Email String More info
Order_Contact > Sex String More info
Contact sex (Man|Vrouw)
Order_Contact > LastName String More info
Order_Contact > ContactNotes String More info
Custom CRM notes associated with the contact
Order_Contact > DefaultContact Boolean (true|false) More info
Whether the contact is the relations main (default) contact.

Response JSON Example

The response order can vary from the parameter order above
    • GET rest/listsalesinvoices/

      • Get a list of sales invoices including invoice details

This GET method allows you to retrieve a list of invoices from your administration. You can also retreive the details of a single invoice using the InvoiceNumber request parameter.

Notes:

  • Maximum 100 invoices will be returned per request
  • You can retrieve more invoices by doing multiple requests and using the offset parameter
  • The returned invoices will be sorted by invoice number (descending)
  • Request
  • Response

Request body parameters

Parameters with an asterix (*) are required!
Parameters with a double asterix (**) means one of them is required!
InvoiceNumber Integer More info
Optional parameter. Use this to retreive the details of a single invoice.
Limit Integer More info
Define an optional limit for the retrieve. Defaults to 100 which is also the maximum.
Offset Integer More info
Define an optional offset for the retrieve.

Request Example

Below the parameters you can see an example JSON response, containing 2 sales invoices

Response body parameters

CustomerNumber Integer More info
The customernumber of the relation associated with this invoice.
CustomerName String More info
The customer name of the relation associated with this invoice.
InvoiceNumber Integer More info
The invoice number
InvoiceNotes String More info
Notes added to the invoice
InvoiceDate String Date (dd-MM-yyyy) More info
The invoice date in format dd-MM-yyyy. (http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html) Defaults to current date.
InvoiceReference String More info
If the invoice is created with the Invoicing module, this will return the (optional) invoice reference
InvoiceTotalExclTax Float More info
The total invoice amount excluding taxes
InvoiceTotalInclTax Float More info
The total invoice amount including taxes
InvoiceTaxAmount Float More info
The total VAT amount
InvoiceOutstandingAmount Float More info
The outstanding amount for this invoice (amount still to be payed)
InvoiceDueDate String Date (dd-MM-yyyy) More info
The invoice due date in format dd-MM-yyyy. (http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html) Defaults to current date.
PackingSlipNotes String More info
Packing slip notes
ProjectName String More info
If the invoice is associated with a project, the project name will be returned
ProjectNumber String More info
If the invoice is associated with a project, the project number will be returned
InvoiceType String More info
This will either return BOOKKEEPING or INVOICING. If BOOKKEEPING is returned then the invoice is created as a bookkeeping sale transaction. If INVOICING is returned then the invoice is created from the invoicing module of the software.
Invoice_Contact Array More info
This contains a JSON array of contacts associated with the invoice. At the moment this will return the main contact of the invoice and the packing slip contact
Invoice_Contact > ContactType String More info
Invoice|PackingSlip
Invoice_Contact > FirstName String More info
Invoice_Contact > Phone String More info
Invoice_Contact > Email String More info
Invoice_Contact > Sex String More info
Contact sex (Man|Vrouw)
Invoice_Contact > LastName String More info
Invoice_Contact > ContactNotes String More info
Invoice_Contact > DefaultContact Boolean (true|false) More info
Invoice_Address String More info
A JSON array of order addresses. At the moment this will never contain more then one address, which is the address selected for the invoice.
Invoice_Address > Address_CountryCode String More info
ISO 3166 (A2) country code of the order address
Invoice_Address > Address_PostalCode String More info
Postal / zip code
Invoice_Address > Address_Street String More info
Invoice_Address > Address_Unit String More info
Invoice_Address > Address_City String More info
Invoice_Address > Address_UnitAppendix String More info
Appendix (e.g. appartment/suite/floor) for the address unit
Invoice_Address > AddressType String More info
At the moment this will always return "InvoiceAddress"

Response JSON Example

The response order can vary from the parameter order above
    • POST rest/addsalestransaction/

      • Add a sales transaction

This POST method allows you to create a new sales invoice within the ‘Boekhouding’ (bookkeeping) module of our software.

Notes:

  • Maximum 50 invoice lines per invoice allowed.
  • If CustomerNumber is used to identify the customer, the number must be greater then zero. A zero value will be interpreted as empty.
  • If CustomerName is used to identify the customer and you have multiple customers with exactly the same name, we will use the first found match.
  • You must add at least one invoice line.
  • Request
  • Response

Request body parameters

Parameters with an asterix (*) are required!
Parameters with a double asterix (**) means one of them is required!
CustomerNumber ** Integer More info
The customer, identified by its customer number, to be associated with the invoice
CustomerName ** String More info
The customer, identified by its name, to be associated with the invoice
InvoiceNumber Long More info
An optional invoice number. Please note this number MUST be unique.
InvoiceDate Date String (dd-MM-yyyy) More info
The invoice date in format dd-MM-yyyy. (http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html) Defaults to current date.
InvoiceNotes String More info
The invoice description
InvoiceProject String More info
The project by either projectnumber or project name to be associated with the invoide
SelectProjectBy String More info
Allowed values: NAME or NUMBER. Determines wether the value in the parameter 'InvoiceProject' is the projectname or projectnumber.
Invoice_InvoiceLine * Array More info
An JSON array of invoice lines. At least one record must be present.
Invoice_InvoiceLine > TaxPc ** Float More info
Numeric representation of the tax % to be applied for this invoice line. Please note that this percentage must be available within your Offective administration.
Invoice_InvoiceLine > TaxCode ** String More info
The tax code to apply to this invoice line. For example if you have multiple tax codes with the same percentage, you can identify a specific tax code with this parameter.
Invoice_InvoiceLine > SubTotalInclTax * Float More info
The invoice line subtotal, including taxes. We will automatically calculate the totals excluding taxes based on the given tax percentage.
Invoice_InvoiceLine > Description String More info
Invoice line description

Request Example

The response will a JSON array containing 1 record (the just created invoice). For information on the response parameters we refer to the endpoint 'ListSalesInvoices' since that will give exactly the same response. Or see below for a quick example reference.

Response body parameters

-

Response JSON Example

The response order can vary from the parameter order above
    • POST rest/addsalesinvoice/

      • Add a sales invoice

This POST method allows you to create a new sales invoice and automatically mutate the invoiced products stock levels based on the invoice line quantities. This method will create an invoice within the ‘Facturatie’ (Invoicing) module of our software.

Notes:

  • Maximum 50 invoice lines per invoice allowed.
  • If CustomerNumber is used to identify the customer, the number must be greater then zero. A zero value will be interpreted as empty.
  • If CustomerName is used to identify the customer and you have multiple customers with exactly the same name, we will use the first found match.
  • You are required to add at least one invoice line. The invoice line must either contain a parameter ‘ProductNumber’ or ‘ProductEAN’. The value entered in either of those fields must refer to an existing product in your Offective administration.
  • A stock mutation for the selected product will be automatically created.
  • Request
  • Response

Request body parameters

Parameters with an asterix (*) are required!
Parameters with a double asterix (**) means one of them is required!
CustomerNumber ** Integer More info
The customer, identified by its customer number, to be associated with the invoice
CustomerName ** String More info
The customer, identified by its name, to be associated with the invoice
AddAsDraft Boolean (true|false) More info
Defaults to false. If set to true, the invoice will we added as a draft ('concept' invoice)
InvoiceDate Date String (dd-MM-yyyy) More info
The invoice date in format dd-MM-yyyy. (http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html) Defaults to current date.
InvoiceNumber Long More info
An optional invoice number. Please note this number MUST be unique.
InvoiceNotes String More info
The invoice description
InvoiceDiscountPc Float More info
Discount % to be applied to the invoice
InvoiceReference String More info
Invoice reference number or text (max. 150 characters)
InvoiceDueDays Integer More info
In how much days must the invoice be payed? Leave empty or set to 0 to ignore.
PackingSlipNotes String More info
Extra notes for the packing slip
InvoiceProject String More info
The project by either projectnumber or project name to be associated with the invoide
SelectProjectBy String More info
Allowed values: NAME or NUMBER. Determines wether the value in the parameter 'InvoiceProject' is the projectname or projectnumber.
HtmlAsPlainText Boolean (true|false) More info
Whether the response rich-text fields (notes and packing slip notes) will be returned as plain text or not. Defaults to false.
Invoice_InvoiceLine * Array More info
An JSON array of invoice lines. At least one record must be present.
Invoice_InvoiceLine > ProductNumber ** String More info
The productnumber of the product to be associated with the invoice line.
Invoice_InvoiceLine > ProductEAN ** String More info
The product EAN code of the product to be associated with the invoice line.
Invoice_InvoiceLine > Quantity * Float More info
Quantity of units of the product for this invoice line
Invoice_InvoiceLine > UnitPriceExclTax Float More info
Price per ordered unit
Invoice_InvoiceLine > TaxPc ** Float More info
Numeric representation of the tax % to be applied for this invoice line. Please note that this percentage must be available within your Offective administration.
Invoice_InvoiceLine > TaxCode ** String More info
The tax code to apply to this invoice line. For example if you have multiple tax codes with the same percentage, you can identify a specific tax code with this parameter.
Invoice_InvoiceLine > SubTotalInclTax Float More info
The invoice line subtotal, including taxes. When this parameter is set, the price per unit will be ignored and automatically calculated.
Invoice_InvoiceLine > Description String More info
Invoice line description

Request Example

The response will a JSON array containing 1 record (the just created invoice). For information on the response parameters we refer to the endpoint 'ListSalesInvoices' since that will give exactly the same response. Or see below for a quick example reference.

Response body parameters

-

Response JSON Example

The response order can vary from the parameter order above