API v1

Table of Contents

Getting Started

Master Data

Articles & Products

Webshop

Orders & Purchases

Invoicing - Debet

Invoicing - Credit

Payments

Synchronization

Forecasting

Changelog

Version Description Date Author
1.2.10 Reorganized document structure to match table of contents, added section headers 2026-01-08 DDH
1.2.9 Added table of contents, fixed duplicate version numbers, corrected descriptions, language consistency 2026-01-07 DDH
1.2.8 Added Prognoses endpoints 2026-01-06 DDH
1.2.7 Added TransportRegion 2025-11-17 DDH
1.2.6 Added Features to Purchase + Added MarkupCategory 2023-10-14 DDH
1.2.5 Added ListPreOrderGroupItem 2023-06-02 JJ
1.2.4 Added InvoiceSync 2022-12-09 JJ
1.2.3 Added RMAReason to Table 2022-11-14 JJ
1.2.2 Added PreOrderSync 2022-06-11 DDH
1.2.1 Added debtor remarks 2022-04-06 DDH
1.2.0 Added Shop endpoints 2022-03-29 JJ
1.1.11 Added RMA reasons to DistributedPurchaseSync 2022-03-24 DDH
1.1.10 Added QuantityPlates/QuantityAttachments to trolley 2022-03-24 DDH
1.1.9 Added more examples 2022-03-03 JJ
1.1.8 Added endpoints 2022-01-20 JJ
1.1.6 Added Location and Administration endpoints 2021-11-20 JJ
1.1.5 Added Sync requests 2021-11-03 JJ
1.1.4 Invoice documentation changed 2021-03-14 JJ
1.1.3 Added ManufacturerSupplierId 2021-03-14 JJ
1.1.2 Added DateFrom/DateTo endpoints 2021-03-08 DDH
1.1.1 Added JWT token authorization 2020-11-11 JJ
1.1.0 Deprecated entries 2020-10-21 DDH
1.0.12 Minor adjustments 2020-04-30 DDH
1.0.11 Added info about Date 2018-04-05 DDH
1.0.10 Added quantity to List 2017-12-03 DDH
1.0.9 Added priceDefault 2017-08-01 DDH
1.0.8 Added debtor PUT/PATCH (main level) 2017-07-10 DDH
1.0.7 Added purchase, invoice, invoice items and payments 2017-07-07 CB
1.0.6 Added OriginalPrice to ListArticleSort 2017-06-12 DDH
1.0.5 Added ListArticleSort array request 2017-06-08 DDH
1.0.4 Added articleSort documentation 2017-03-01 DDH
1.0.3 Minor changes 2017-02-08 DDH
1.0.2 MaxCancellationTime, Features, FeatureTypes 2017-01-12 DDH
1.0.1 Article id changed from int to string / invoices 2016-10-31 DDH
1.0.0 Authorization, distributed removed, status codes added 2016-10-12 DDH
0.9.1 Authorization, attachments, events 2016-09-07 DDH
0.9 Updated version 2016-06-07 DDH
0.4 Initial version for external use 2015-11-18 DDH

Getting Started

Introduction

You can use a varied amount of Get() commands that deliver JSON files, which you can then import into other databases and/or reporting tools. Please note that Get() commands to larger collections such as articles, invoice items and purchases can only be used outside of office hours (before 5AM UTC or after 6PM UTC).

In order to use the API you need to be authorized for each database (of a customer) you connect to. If you are not authorized, you'll receive a HTTP status 401 (Unauthorized). More details in API Authorization. Once you end your session, use the Unauthorize command.

In the section 'general' you'll find helpful information to build your application with.

The next sections of this document, are the API commands available. Each section contains:

  • a brief explanation of the type of record it houses
  • per put/get/post command:
    • the parameters you can use
    • the command syntax
    • the return output
    • an example

General

JSON

Information about specific types and how it's formatted in JSON.

DateTime format

Symbol Description Example
yyyy year 2015
MM month 01
dd day 31
HH hour 13
mm minute 01
ss seconds 22
tttttt timezone +02:00
Z UTC timezone Z

Date

  • Format: yyyy-MM-dd
  • Example: 2015-12-30

DateTime

  • Format: yyyy-MM-dd\THH:mm:ssttttttt
  • Example: 2015-12-30T13:40:20+02:00
  • Remarks: Use timezone of debtor

TimeSpan

  • Format: ((-)dd.)HH:mm:ss
  • Examples:
    • -01.13:50:01 (minus one day, at 13:50:01)
    • 01.13:50:01 (plus one day, at 13:50:01)
    • 13:50:01 (same day, at 13:50:01)
    • 00.13:50:01 (same as above)

LanguageValue

Object containing all available languages (ISO-639-1).

{
  "nl": "Nederlandse benaming",
  "de": "Deutsch-Bezeichnung",
  "fr": "titre francais"
}

Null value

Don't send parameters without value.

Wrong:

{
  "RequiredParameter": "text",
  "OptionalParameter": null
}

Right:

{
  "RequiredParameter": "text"
}

Encoding

UTF-8

Status codes

Code Description
200 OK - Request successful
400 BadRequest - Object containing error
401 Unauthorized - Authentication required or failed
500 ServerError - Error processing message, not fetched

Error response format:

{
  "error": "<error>",
  "message": "<human readable error>"
}

Known errors:

  • NoOrInvalidJson
  • NoOrInvalidRequest
  • ArgumentNotFound
  • DocumentNotFound
  • ApiOpeningHoursException (too large a request to process during office hours). May only be done before 5AM UTC or after 6PM UTC.

Tips

  • The API is built async, as such you can fire multiple commands simultaneously.
  • Order of properties available in the API is not guaranteed. Make sure that when parsing the file, you do so based on the property name - not on the position. JSON parsers should have this behavior by default.
  • This API documentation has been written from a C# perspective. If you're not familiar with C# coding, you should at least familiarize yourself with the IEnumerable and Dictionary data types, which are uncommon in other programming languages.
  • Any property that is not required, can have NULL as value.
  • If an IEnumerable is required, it means the list is initialized ([] value) but may still contain no record(s).

Authorization / logging in

Command: api/authorization

When successfully authorized, you will receive a cookie containing a session. Please append cookie this to any other call you'll make. Session is bound to the user. Session will expire when another call is made using the same username, in case of a valid login.

When receiving a HTTP Statuscode 401, please reauthorize.

Post parameters

Property name Description Data type Required
Username Username of a user within the database you want to connect to string yes
Password Password of a user within the database you want to connect to string yes
Database The database you want to connect to string yes

Post example

POST https://api.easyflor.eu/api/authorization

{
  "Username": "api",
  "Password": "wouldntyouliketoknow",
  "Database": "EasyFlor-Demo"
}

Returns: 200 OK / 401 Unauthorized

JWT Bearer Token based authorization

Command: api/authorizationtoken

When successfully authorized, you will receive a model containing a Token. To use this Token add a header with the token to any other calls you'll make. The Token is bound to the user and will expire after the expiration date and a new token will need to be generated.

When receiving a HTTP Statuscode 401, please reauthorize.

Post parameters

Property name Description Data type Required
Username Username of a user within the database you want to connect to string yes
Password Password of a user within the database you want to connect to string yes
Database The database you want to connect to string yes

Post example

POST https://api.easyflor.eu/api/authorizationtoken

{
  "Username": "api",
  "Password": "wouldntyouliketoknow",
  "Database": "EasyFlor-Demo"
}

Returns: 200 OK / 401 Unauthorized

Property name Description Data type
Token Token used for authentication with each request string
Expiration The expiration date of when the Token will no longer be valid DateTime

Authorized request example

curl --location --request GET 'https://api.easyflor.eu/api/debtor' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ##TOKEN##'

Unauthorization / logging out

Note: Unauthorization is only used for Cookie based authorization. When using the JWT Bearer Token based authorization the token will expire on its own after a set amount of time.

Command: api/unauthorization

Cookie based logging out. When sent, cookie that started session is made invalid and any further commands sent will receive a 401 unauthorized exception.

Post parameters: None

Post example:

POST http://api.easyflor.eu/api/unauthorization

Returns: Nothing

Master Data

Debtors

Commands:

  1. api/debtor
  2. api/debtor/id
  3. api/debtorsincedate/id (date being date the debtor is modified)

A company or person to which goods are delivered and invoices sent.

Get example

GET https://api.easyflor.eu/api/debtor
GET https://api.easyflor.eu/api/debtor/20

Debtor in JSON format

[{
  "Id": 417,
  "ParentId": null,
  "Name": "test debiteur",
  "PaysVAT": true,
  "Language": "nl",
  "Config": {
    "Id": "ShopWhyDebtorConfigs/debtors/417",
    "DebtorId": "debtors/417",
    "SalesUnits": [],
    "DirectPay": false
  },
  "Addresses": null,
  "Numbers": null,
  "Contacts": [{
    "Initials": "m",
    "FirstName": "marco",
    "MiddleName": null,
    "LastName": "kleine",
    "PlaceOfBirth": null,
    "DateOfBirth": "1970-12-10T00:00:00Z",
    "Function": null,
    "Gender": "Man",
    "Nationality": "Nederlandse",
    "MailAddresses": [{
      "Category": "MAIL_1",
      "Value": "testje@hotmail.nl"
    }],
    "Numbers": null,
    "Users": [{
      "Username": "Testje",
      "Password": "+TEkLGxMMyknX6ZcN6BRg8MTlyeWOzphnXXQQUZDm8E=",
      "PasswordSalt": "hCJjTLQJchM=",
      "CanOrder": true
    }]
  }],
  "MailAddresses": null,
  "CurrencyISOCode": "EUR",
  "CreatedOn": "DateTime",
  "OrderDays": [{
    "Id": "orderdays/1",
    "Name": "Levering dinsdag",
    "Day": 2,
    "MaxDefaultOrderTime": "-1.15:30:00",
    "Lists": [{
      "Id": 73,
      "MaxOrderTime": "-1.15:30:00",
      "MinOrderTime": "00:00:00"
    }, {
      "Id": 98,
      "MaxOrderTime": "-1.15:30:00",
      "MinOrderTime": "00:00:00"
    }]
  }]
}]

Get returns

Property name Description Data type Required
Code Code to reference debtor with. Used mainly for easier searching. string yes
ParentDebtorCode Code of the debtor that this debtor is a subdebtor of string no
Administration Each debtor belongs to an administration string yes
Name Name of the debtor string yes
SecondName A second name for the debtor string no
Category The name of the category to which the debtor belongs string yes
Country Country code 3 of the country that the debtor resides in string no
Currency ISO code of the currency the debtor uses (Deprecated: equals CurrencyISOCode) string yes
Language Name of the language the debtor uses string yes
TransporterCode Code of the transporter that is used to make deliveries to this debtor. string no
TransporterName Name of the transporter that is used to make deliveries to this debtor. string no
TransportRegion Name of the region, for transport purposes string no
Employees The employees that may place orders for this debtor. IEnumerable<string> no
OrderDayNames List of ids to the order days collection, which is a collection detailing when the debtor may order from the webshop. IEnumerable<string> no
ToInvoice List of ids of debtors that this debtor is invoiced for. I.e. we deliver to various subcompanies, but the main company pays for it. IEnumerable<string> no
Locations IEnumerable<string> no
InvoiceCreditTemplate Template that is used to create credit invoices. string no
InvoiceDebetTemplate Template that is used to create debet invoices. string no
InvoiceCSVTemplate Template that is used to create debet CSV invoices string no
InvoiceEventsTodo The default events that must be done for an invoice after creation. IEnumerable<string> no
Price Name of the default price settings that this debtor uses string no
PriceUseMarkupCategories Whether the markup categories in the default price settings are used to calculate the prices for debtor. bool? no
PriceUseOriginalPrice Whether the buying price is used when applying markup categories to calculate the prices for debtor. bool? no
MarkupCategories Which markup categories (contains the ids of the actual markupcategories) are to be used when calculating the prices for debtor. IEnumerable<string> no
DistributionPackagingVATRate Code of the VAT rate to be used for packaging (NL: fust) invoiced to this debtor. string no
DistributionTrolleyVATRate Code of the VAT rate to be used for trolleys (NL: karren) invoiced to this debtor. string no
DistributionSellingLocation When items are sold to this debtor, the items can be added to the stock of a certain location. This field contains the name of that location if that option is enabled. string no
Block Block debtor from making purchases in webshop bool yes
Id Int part of the debtor id int yes
ParentId Int part of the debtor id that this debtor is nested under int no
PaysVAT If enabled, VAT is added to the invoice bool yes
CurrencyISOCode ISO code of the currency the debtor uses string yes
CreatedOn DateTime created DateTime yes

The remainder of this document contains the same technical API specifications as the Dutch source version. All endpoint definitions, parameter tables, JSON examples, and code samples are identical as they were already written in English.

Do you have questions or need help? Feel free to contact us by phone at +31 (0)71 30 20 310 or send an email to support@easyflor.nl.