Getting started

The Dinero API is REST based, which is easy to work with and familiar to developers.

To use the API, you need to apply as a developer through Visma Connect.

Please make sure to read this entire documentation, including the Visma Connect documentation, and all relevant endpoints. Most often, the answer can be found in these documentations. :-)

It's especially important that you read through this entire page, for information on:

  • Signing up and creating an application in Visma Connect and not getting rejected ;-)
  • Creating a test account in Dinero and making your first requests with Postman
  • Important debugging information, best pratices, the meaning of status- and errorcodes etc.

Base URL

https://api.dinero.dk

Technical support

For technical questions, you can write us an email at api@dinero.dk. Make sure to include your client_id and the organization id where you are having issues.

But please look through the entire documentation before you do so. Most questions can be answered by our documentation. If you cannot find the answer though, then feel free to reach out.

Authentication

The Dinero API uses Visma Connect for authentication, see more at https://oauth.developers.visma.com/service-registry/documentation/overview

Scopes

Upon approval the scopes you should request is:
dineropublicapi:read dineropublicapi:write offline_access

Apply

Dinero uses Visma Connect which is based on OAuth2 and supports OpenIdConnect. This means that you use a token on every request to authorize yourself.

Steps

  1. Sign in(or up) at Visma Connect
  2. Create an application in Applications. Make sure to use the application type "Web application" (Important, as this is the only supported application type at this moment)
    An example of the settings we used is available here: Application example settings

    Be sure to use a meaningful client id, that includes your company name, e.g. "your_companyname", and avoid acronyms.
    Rasmus_sole_proprietorship is a good example. RSP, Ras_Sol or Rasmus_SP would all be rejected.
  3. Application Policy can be left as is.
  4. In credentials you need to generate a Client Secret to authorize yourself.
  5. You can now apply for integration access to DineroPublicApi in the flow or here. You can request the scopes offline_access, read and write.
  6. Finally click save.

Important tips

  • For debugging error codes returned by Connect, head over to the Visma Connect application list (the debugger can be shown by clicking the More button)
  • Additional help regarding Visma Connect is available at the Visma Connect Documentation
  • Create a test account and test organization on dinero.dk and send your organization id and client_id to api@dinero.dk and we will upgrade you to a free test account.
    You only need to sign up for a regular account on Dinero and create a regular company through the normal start-up flow when you sign up. You can name your test company whatever you wish. Just note that this company is only for testing purposes. If you wish to integrate your own working company with our API, you need to purchase Pro for yourself.
  • If you get stuck or have any questions, feel free to write our API support at api@dinero.dk

Getting started using postman

We've created a postman collection, that should help you getting started. If you used our example settings this should be plug and play.

In order to use this, you should have your client_id and client_secret ready (which you got when you created your application in the steps above).
These need to be replaced in the "variable" section of the collection. Make sure to click save in the top right.
You can grab your organizationID directly from the test account you created above, or you can request it through the API with the List organizations endpoint, utilizing the name and id fields. Here you can also check if the organization is Pro, which is a prerequesite for the user, to use the API..

You also have to add https://oauth.pstmn.io/v1/callback for the desktop version of Postman, or https://oauth.pstmn.io/v1/browser-callback for the web version, as a redirect_uri in Visma Connect

An example of the settings we used is available here: Application example settings

Technical Review

Before you launch your integration, you are obligated to setup a technical review of your application. If your integration is only for self use and not a solution targetting multiple users, then you can skip this step entirely.

The review will be done over e-mail, when your integration is ready for production usage.

  • Make requests that will follow the normal flow of your integrations. If your integration will use synchronization of data, be sure to include those as well.
  • Write to api@dinero.dk that you are ready for review (Be sure to include your clientid).
  • You will then either get a go ahead or suggestions for improving the integration.
  • We'll help you get published on dinero.dk/integrationer.

This technical review is conducted to ensure optimal usage of the api and encourage for a close relation between Dinero and our integration partners.

If we recognize usage of your integration outside of the testing organization id entered in the signup form, we reserve the right to disable the credentials, until the interview has been held. We will try to reach out before any such measures is applied.

We retain the opportunity to reject applications for any of the following reasons:

  • Security issues
  • The service is too close to our business
  • Inefficient use of our API
  • The service is in violation with the law or
  • ...our terms of service

Best practice

Be sure to read the entire documentation for the endpoints you are using, this will make sure that you have a complete overview of all the possibilities of the endpoint

Always check the status code
Make sure you understand the HTTP Status code specification, how we apply it here at Dinero, and what some of the common issues is with the specific statuscodes

StatusCode Http status meaning Common mistake
200 Ok Everything is fine
201 Created Everything is fine, and here is an empty body
400 Bad request This oftens occurs when the required fields are not supplied in the API call. E.g not having a contact on a Invoice when trying to book it, or not suppling the newest timestamp
401 Unauthorized Something is wrong with your token, often it has expired
403 Forbidden You do not have access to the requested resource. We also use this statuscode when the requested organization doesnt have a valid Pro subscription. The body will also return errorcode 90 if there is no active Pro subscription.
429 Rate limited You have exceeded the maximum amount of calls for a given timeperiod, wait a couple of minutes and continue
480 Brownout The endpoint you are using is deprecated and about to be removed and therefor your request has failed. This statuscode has a random chance of happening in the last days of the lifetime for an endpoint that has been marked for removal. This is used as a last chance notice for integrations that have missed our communication about removal of endpoints.
500 Server error This means that something is wrong on our end, and if it doesn't resolve within a couple of days please reach out to us

Use ChangesSince
We often experience integration partners doing complete syncs, day after day.
This is not the correct way to use the API.

Instead of fetching everything, most of our list endpoints have a parameter called ChangesSince.
ChangesSince is a datetime parameter which ensures that everything that have been created or updated since the specified time will be returned.

Have a maximum retry policy
Always implement a maximum of retires, depending on the returned statuscode

E.g: if we return 400, check the error response and update your integration to include the correct data. We reserve the right to disable credentials if integrations misuse our API
E.g: if we return 500 for a range of requests, please pause these requests for some time before trying again

Try to limit your daily request count
You should always try to reduce the amount of daily requests to a minimum, we supply our API as a free to use service, we therefore require integrations to use it as efficient as possible.

Always make sure that you have read the entire documentation for a specific endpoint, we may meantion good solutions and how to use the endpoints correctly.

Glossary

Organization

"Organization" is the term we use for the users "Firma" in Dinero. If you need a test organization, here is a guide to how you can create one.

Organization id

The organization id of the organization you want to access in Dinero. This will have to be provided by your customer/user of you integration. Here is a guide to where you can find the organization id on a Dinero organization

Ledger items

Equal to the danish "kassekladde linje".

Error codes

Code Message Description
40 Not found The URI requested is invalid or the resource requested, such as a voucher, does not exists. Also returned when the requested format is not supported by the requested method
41 Unauthorized The user has insufficient permissions to perform the request on the given resource.
42 Validation Error A validation error occurred
43 Limit Exceeded An upper or lower limit was exceeded
44 Invalid format The format of the specified value is incorrect
45 Invalid request The request is invalid
46 Invalid filter format The format of the filters are incorrect
47 An accounting year was not found The organization has not created the requested accounting year
49 Email rejected The email could not be send.
50 Error A server error occured. No more information about this error could be found.
51 EAN problems Could not send e-invoice.
52 No organization owner The organization don't have an owner.
53 No organization email The organization don't have an email.
54 Missing bank info The organization don't have any bank info.
55 No receiver email Invoice receiver don't have an email. Update the contact or supply and email with your request.
56 No EAN number Invoice receiver don't have an EAN number. Update the contact before trying to send an e-invoice.
57 Invalid EAN number Invoice receiver's EAN number is not valid.
58 Timestamp out of date The supplied timestamp is not the latest version of the entity. Get the latest version and try again.
59 Voucher not booked The voucher is not booked. The requested action requires the voucher to be booked.
60 No VAT number Organization don't have a VAT number
61 Invalid bank info The bank info is not valid.
62 E-invoice contact missing att. person The contact of an e-invoice must have an att. person.
63 No results The request gave no results.
64 No recepient email The request uses email, but the contact don't have an email.
65 Item is deleted You cannot make changes to a deleted item.
66 Ledger limit exceeded Your ledger has too many lines. There is a cap of 1000 lines per ledger.
67 File type not allowed File type not supported. Acceptable formats: JPEG, JPG, PNG, GIF, PDF
68 File type not present The file type was not found in the file name. Acceptable formats: JPEG, JPG, PNG, GIF, PDF
69 Must be MIME multi part content Must be MIME multi part content
70 Ledger items optimistic concurrency Multiple ledger item post request was send in a short time interval. Due to that we respect the order of the ledger items, this causes a concurrency issue. Ledger items for same organization should not be posted async.
71 Update concurrency error Update concurrency error
72 Duplicated entity error Duplicated entity error
73 Something went wrong while sending the email. Something went wrong while sending the email. The email might or might not have been sent.
74 Voucher not overdue. Pre-reminder mailout could not be send. The voucher is not overdue. The requested action requires the voucher to be overdue.
75 Date differs for same voucher number The date should be the same for items with the same voucher number.
76 FileGuid differs for same voucher number The FileGuid should be the same for items with the same voucher number.
77 Account does not exist The account does not exist for given account id.
78 Id differs for same voucher number The id should be the same for items with the same voucher number.
79 Invalid VAT number Organization don't have a valid VAT number
80 Can't claim free pro Can't claim free pro if already claimed or if already pro
81 Cannot create accounting year Cannot create accounting year
82 Dates not in single accounting year Cannot find a single accounting year from the dates. This means that the dates may be overlappin two accounting years
83 The specified end date is before the specified start date The specified end date is before the specified start date
84 The specified to and from dates spans too long time, you can at the most request 31 days at a time The specified to and from dates spans too long time, you can at the most request 31 days at a time
85 The tradeoffer cannot be edited when it is not in the draft status Tradeoffers cannot be edited when it has been accepected, rejected, or converted into an invoice
86 Deposit does not exist The deposit does not exist for given deposit account id.
87 Version differs for same voucher number The version should be the same for items with the same voucher number.
88 No booked reminder The voucher does not have a booked reminder. Reminder mailout could not be send.
89 Forbidden Can not access Total features without a Dinero Total License.
90 Forbidden The organization does not have access to this feature.

Filters

Filters are not available on all properties, so be sure to check the endpoints queryFilter URI parameter description to see which. If the endpoint do not contain a queryFilter URI parameter, then it does not support filtering.

Each filter command is built after the structure: [PropertyName] [Operator] '[Value]'

Be aware that the [Value] is not case sensitive. And remember the ' around it.

Each filter command should be separated with: ;

Name Types Operator Example
Equals string, int, bool eq Name eq ’John Doe’
Contains string contains Name contains ’John D’

Example

https://api.dinero.dk/v1/{organizationId}/contacts?queryFilter=Name+contains+'a';IsPerson+eq+'False'

Throttling

There are no hard limit on the number of API requests per day but we enforce a fair use limit and requests will be rate-limited if too many calls are made within a short period of time. Rate limiting is considered on a per client_id basis.

If you hit the rate limit, this is the body of the HTTP 429 message that you will see: API calls quota exceeded! (...)

We constantly monitor the usage of our API to ensure that it is used as efficient as possible. If we detect that the API can be used more efficient or that the API resources are being exhausted by a single client integration and it is evaluated by Dinero to hurt the general service of the API to other customers, Dinero can decide to revoke the access for single clients. Dinero will always strive to solve such issues in dialog with the integrating partner before any counter measures are taken.

Posting image

An example of how a post call to our files service could look like:

Example

POST https://api.dinero.dk/v1/[organization_id]/files/?fileName=sample-invoice.jpg HTTP/1.1
    Authorization: Bearer eyJ0eXAiOiJKV1QiLC....
    Accept: application/json
    Content-Type: multipart/form-data; boundary="-------abcdefg1234"
    Host: api.dinero.dk
    Content-Length: 313036
    Expect: 100-continue
    Connection: Keep-Alive

    ---------abcdefg1234
    Content-Type: image/jpeg
    Content-Disposition: form-data; name=image; filename=sample-invoice.jpg; filename*=utf-8''sample-invoice.jpg
    [ReplaceWithYourImage]
    ---------abcdefg1234--

Change log

30/09/2021 - The following endpoints were deprecated:

Add ledger item V1

Deprecated in favor of "Add Ledger item V1.2" The new endpoint has the same functionality, the only difference is that items has to be added to the lines array, and returns the id of the created item.

Add Ledger item V1.1

Deprecated in favor of "Add Ledger item V1.2" The new endpoint has the same functionality, the only difference is that items has to be added to the lines array.

Next voucher number V1

Removed because it is no longer needed.

Update invoice V1

Deprecated in favor of "Update Invoice V1.2" Same functionality exists in the new endpoint.

Update invoice V1.1

Deprecated in favor of "Update Invoice V1.2" Same functionality exists in the new endpoint.

Send invoice with EAN V1

Deprecated in favor of "Send invoice with EAN V2" Same functionality exists in the new endpoint.

Get payments for invoice V1

Deprecated in favor of "Get payments for invoice V2" Same functionality exists in the new endpoint.

Create Purchase voucher V1

Deprecated in favor of "Create purchase voucher v1.1" The new endpoint has the same functionality, but Notes must be send in the lines array, and an amount should be specified.