AutoCollect API is a REST-API pluss a SOAP-API for debt-collection.
\nThe API support a set of processes which constitutes a complete solution for a debt-collection service.
\nThis document describes these processes and API call connected.
\nFor a complete desciption of all API-endpoints and objects and fields see our Swagger. URL is descibed in section URLs.
\nThe documentation is constantly being maintained and expanded based on users feedback. Feel free to give us feedback if you are missing something in the documentation. It is important for us to give you the easiest experience possible when developing towards our API.
\nYou can send:
\nYou can request and receive:
\nThere are a set of processes where the API can be used. There is optional witch processes you implement.
\nNote that process for sending payments/credits is mandatory.
\nThe processes are:
\nRegister as a new creditor
\nHere the API is used to register a company as a new customer/creditor.
\nWhen the client is ready for the next process a e-mail is sent to the registered contact person.
\nSending invoices to reminding or debt-collection
\nWhen the company is confirmed as a new creditor from the above process, invoices can be sent to reminding/debt-collection. 1 or multiple invoices can be sent in the same API call.
\nSending payment or credits on invoices sent to reminding/debt-collection
\nIf a invoice is sent for reminding/debt-collection all payments or credits matched to invoice must be sent to the API endpoint. This process is mandatory.
\nSending change request and message to casehandler
\nA set of changes can be made to an invoice sent to reminding/debt-collection. Like setting a case on hold, closing a case.
\nAlso message can be sent to casehandler.
\nGetting case information
\nERP system can be updated with info from the reminding/debt-collection case. For example casenumer, status.
\nGetting settlements
\nWhen end-customer make a payment on a reminding/debt-collection case the payment infomation is availible using the API. The settlement has information so a accounting can be done in ERP. Amounts are split so the invoice can be paid, income and expenses can be accountet in GL.
\n","_postman_id":"5ef2d7bd-315e-485f-b234-417a9cd9bfa1"},{"name":"Recommended usage","item":[],"id":"f14d6c69-9760-43a3-9806-0d2615cd9606","description":"When sending invoices, payments or change-request a paramter can be set to flag if the API will do a check on all received items. By setting the paramter \"offline\" to \"true\" these checks will be skipped giving a much better response time.
\nWe recommend setting \"offline\"=\"true\" in a production environment and setting \"offline\"=\"false\" in test environment.
\nTo simplify our support we recommend that the parameter \"senderid\" should set to a value identifying what type of ERP-system is used and also a short form of the client-id/name/orgno. Example \"VBUS-234567887
\nWhen register a new creditor using the API the field \"sourceid\" should be set to correct value. See Swagger for values.
\nWe recommend that you set a text in field \"batchid\" identifying the process. Example \"Post Invoices\", \"Post Payments\".
\nIn a \"POST batch\" multiple invoices, payments or actions can be posted. For example the user can mark multiple invoices to send to AutoCollect in the client system. Here all marked invoices can be sent in 1 request to AutoCollect.
\nThe same for payments/credits. If the client system runs a job to get new payments/credits all can be sent in 1 request using POST batch
\n","_postman_id":"f14d6c69-9760-43a3-9806-0d2615cd9606"},{"name":"Design pattern","item":[],"id":"b8fa799d-cd16-4502-93ed-6aa3315da83c","description":"Used for connectivity tests.
\nMethod to send data and receive data. All data is collected in an envelope (batch) labeled with id (batchid) and submitted either as a JSON to WebApi or as a SOAP to WebService.
\nBatch is submitted as a JSON / SOAP.
\nWebApi/WebService GET
\nReceives a batch as a JSON/SOAP.
\nMethod to get attachment.
\nWebApi/WebService GET
\nReceives result as JSON/SOAP. Attachment filedata base 64 encoded.
\n","_postman_id":"b8fa799d-cd16-4502-93ed-6aa3315da83c"},{"name":"Return codes from service","item":[],"id":"474fe38e-81b1-463e-96d3-c229683316f2","description":"At POST Batch, a JSON / XML object will be returned that tells whether batch submission went ok or not.
\n{\n\"statuscode\": 0,\n\"errors\": [\n{\n\"objectname\": \"string\",\n\"objectindex\": 0,\n\"message\": \"string\"\n}\n],\n\"responses\": [\n{\n\"objectname\": \"string\",\n\"objectindex\": 0,\n\"ledgerref\": \"string\",\n\"status_statuscode\": \"string\"\n}\n]\n}\n\nTest
\nProduction
\n","_postman_id":"6bbe7e1a-5520-4265-b302-abd158777189"},{"name":"Register as an integration partner","item":[],"id":"364e4493-234d-461a-af9a-5ba408ba8d8e","description":"When you first register with us you have to registrer towards our test environment.
\nThe test environment implements a lot of safeguards and simulators allowing you to test most functions without the risk of sending a test reminder to a real supplier.
\nWhen your integration is ready for production you should request a new username and password to the production environment, and switch the base URL's to point to the production environment. This is explained in the chapter Ready for production.
\nTest environment is available on both WebApi (REST, JSON) and WebService (SOAP, XML).
\nSee section URLs for addresses
\nWe use swagger as an integrated API design and documentation platform.
\nThis is how you register as an integration partner
\n{\n \"batchid\": \"VBUS-12 2023-04-24 12:54:54.345\",\n \"offline\": false,\n \"creditor\": [\n {\n \"idnumber\": \"328454729\",\n \"parentidnumber\": \"\",\n \"onlydebtcollection\": false,\n \"vattype\": \"STANDARD\",\n \"fullname\": \"Ny test company\",\n \"street\": \"MyStreet 5\",\n \"city\": \"MyCity\",\n \"zipcode\": \"1000\",\n \"countrycode\": \"no\",\n \"emailinvoice\": \"me@testcompany.no\",\n \"bankaccountno\": \"11111111111\",\n \"swift\": \"\",\n \"iban\": \"\",\n \"message\": \"Just a test\",\n \"contact\": {\n \"fullname\": \"Anders Andersen\",\n \"workphone\": \"12345678\",\n \"email\": \"anders@testcompany.no\",\n \"isinvoicequery\": true,\n \"isremittancereport\": true,\n \"isorderconfirmation\": true,\n \"iscollectionlist\": true,\n \"isweb\": true\n },\n \"contact2\": {\n \"fullname\": \"Birger Bergersen\",\n \"workphone\": \"87654321\",\n \"email\": \"birger@accountant.no\",\n \"isinvoicequery\": true,\n \"isremittancereport\": true,\n \"isorderconfirmation\": true,\n \"iscollectionlist\": true,\n \"isweb\": true\n },\n \"password\": \"************\",\n \"sourceid\": 1,\n \"vismanetcompanyid\": \"12345678\",\n \"reminderflow\": 0,\n \"debtcollectiontransfer\": 0,\n \"invoicearchive\": 0,\n \"hasforeigndebtors\": true,\n \"hasforeigncurrency\": true,\n \"disabled\": false\n }\n ]\n}\n\n\nYou can register a creditor through the API once you have the connection as an integration partner.
\nRegister a creditor in our debt collection system by sending a XML/Json.
\nIt is possible to register a creditor as a child of an already registered creditor.
\nA principal creditor will then be able to submit invoices/payments/actions for all child creditors.
\nIf you want to define this you can use parentidnumber (See exemple below) and set the organization number of the parent.
\n","_postman_id":"01cea13a-d5e6-4919-b1f3-29a987cc6951"},{"name":"Sending invoices to reminding or debt-collection","item":[{"name":"Example","item":[],"id":"a62fcaf7-4407-4564-aeca-da6241b2cc08","description":"{\n \"batchid\": \"VBUS-12 2023-04-24 12:54:54.345\",\n \"offline\": true,\n \"invoice\": [\n {\n \"creditorid\": \"328454729\",\n \"collectiontype\": \"REMINDER\",\n \"collectionnoticedate\": \"\",\n \"debtor\": {\n \"idnumber\": \"344556677\",\n \"juridicaltype\": \"COMPANY\",\n \"customerref\": \"12345\",\n \"firstname\": \"ACME AS\",\n \"lastname\": \"\",\n \"street\": \"Svingen 11\",\n \"city\": \"Oslo\",\n \"zipcode\": \"0201\",\n \"countrycode\": \"no\",\n \"phone\": \"11334455\",\n \"email\": \"acme@acme.no\"\n },\n \"debt\": {\n \"ledgerref\": \"145678945\",\n \"referencenumber\": \"1201\",\n \"description\": \"\",\n \"currencycode\": \"NOK\",\n \"billdate\": \"2023-01-24\",\n \"duedate\": \"2023-02-09\",\n \"originalamount\": 1000,\n \"amount\": 1000\n }\n }\n ]\n}\n\n\nYou can send multiple invoices to us in a XML/Json. You can choose to mark it for reminding flow or directly to debt collection. All invoices submitted will go to a manual or automatic approval. When approved, it will be read into the debt collection system.
\nNote that when an invoice is sent to the debt collection company, any payments or creditnotes on the customer must also be sendt
\nBefore the invoice is approved the service description returned will be Wait Import.
\n","_postman_id":"60e0c682-869e-4916-bc7d-9c5eba252815"},{"name":"Sending payment or credits on invoices sent to reminding/debt-collection","item":[{"name":"Example","item":[],"id":"0a0e9bb6-9366-4299-a827-e1615f0b8d65","description":"{\n \"batchid\": \"VBUS-12 2023-04-24 12:54:54.345\",\n \"offline\": true,\n \"payment\": [\n {\n \"creditorid\": \"328454729\",\n \"ledgerref\": \"145678945\",\n \"paymenttype\": \"PAYMENT\",\n \"paymentref\": \"145678945-123\",\n \"amount\": 100,\n \"currencycode\": \"NOK\",\n \"paymentdate\": \"2023-04-24\",\n \"description\": \"\"\n }\n ]\n}\n\n\nIf an invoice is sent to the API for reminding or debt-collection, all payments and creditnotes must be sent to the API.
\nMultiple payments on multiple invoices can be sent to us in a XML/Json. Here it must be stated whether it is a payment or a credit. The debt collection system will process a payment different from a credit. Payments and credits may be manual approved by the us. It may therefore take some time before it will be displayed on the Get Batch method.
\nAll payments and creditnotes reported to us will be returned in Get batch as settlement.These will be marked with settlementtype = CLIENT_PAYMENT
\nAccounting on these settlements are already done in ERP so no action is required in ERP when receiving these.
\n","_postman_id":"0a19b104-99d8-4c5d-ab3a-54156f438fd2"},{"name":"Sending change request and message to casehandler","item":[{"name":"Example","item":[],"id":"3aa6636e-9c3b-447c-9cc3-6494a9590caa","description":"{\n \"batchid\": \"VBUS-12 2023-04-24 12:54:54.345\",\n \"offline\": false,\n \"action\": [\n {\n \"creditorid\": \"328454729\",\n \"ledgerref\": \"145678945\",\n \"actiontype\": \"DUEDDATE\",\n \"duedate\": \"2023-02-15\",\n \"message\": \"\"\n }\n ]\n}\n\nYou can request a change to a invoice registered with AutoCollect. These are the changes you can make:
\nAll of the changes will be done automatically in our debt collection system. Only messages will be read by one of our case handlers.
\n","_postman_id":"5b76c292-8059-4d99-9cc5-a350206234ed"},{"name":"Getting Case information","item":[{"name":"Example","item":[],"id":"d27f43cb-d079-4a77-8041-2161d55eb5bb","description":"{\n \"batchid\": \"VCS 2023-04-24T13:24:33\",\n \"offline\": false,\n \"creditor\": [\n {\n \"idnumber\": \"328454729\",\n \"parentidnumber\": \"\",\n \"onlydebtcollection\": false,\n \"vattype\": 0,\n \"fullname\": \"Ny test company\",\n \"street\": \"MyStreet 5\",\n \"city\": \"MyCity\",\n \"zipcode\": \"1000\",\n \"countrycode\": \"no\",\n \"bankaccountno\": \"11111111111\",\n \"contact\": {\n \"fullname\": \"Anders Andersen\",\n \"workphone\": \"\",\n \"email\": \"\",\n \"isinvoicequery\": false,\n \"isremittancereport\": false,\n \"isorderconfirmation\": false,\n \"iscollectionlist\": false,\n \"isweb\": false\n },\n \"casehandler\": {\n \"fullname\": \"Visma Inkasso Team 1\",\n \"workphone\": \"73206007\",\n \"email\": \"ac.vfs.no@visma.com\",\n \"isinvoicequery\": false,\n \"isremittancereport\": false,\n \"isorderconfirmation\": false,\n \"iscollectionlist\": false,\n \"isweb\": false\n },\n \"sourceid\": 0,\n \"reminderflow\": 0,\n \"debtcollectiontransfer\": 0,\n \"invoicearchive\": 0,\n \"hasforeigndebtors\": false,\n \"hasforeigncurrency\": false,\n \"disabled\": false,\n \"lastsettlementid\": \"0\"\n }\n ],\n \"case\": [\n {\n \"customerref\": \"12345\",\n \"ledgerref\": \"145678945\",\n \"referencenumber\": \"1201\",\n \"casenumber\": \"498527\",\n \"currencycode\": \"NOK\",\n \"regdate\": \"2023-04-24T00:00:00\",\n \"isdebtcollection\": false,\n \"originalsum\": 1065,\n \"paidsum\": 100,\n \"remainingsum\": 983.25,\n \"originalprincipal\": 1000,\n \"paidprincipal\": 100,\n \"remainingprincipal\": 900,\n \"originalfee\": 65,\n \"paidfee\": 0,\n \"remainingfee\": 65,\n \"originalinterest\": 0,\n \"paidinterest\": 0,\n \"remaininginterest\": 18.25,\n \"service_description\": \"Invoicing\",\n \"status_statuscode\": \"Purreinkasso\",\n \"reminders\": 1,\n \"debtcollectionlist\": 0\n }\n ]\n}\n\nWhen sending a request after information all cases are returned from our debt collection system. You can decide if you want to return only open cases.
\nInformation includes:
\n{\n \"batchid\": \"VCS 2023-04-24T13:24:33\",\n \"offline\": false,\n\n \"case\": [\n {\n \"customerref\": \"12345\",\n \"ledgerref\": \"145678945\",\n \"referencenumber\": \"1201\",\n \"casenumber\": \"498527\",\n \"currencycode\": \"NOK\",\n \"regdate\": \"2023-04-24T00:00:00\",\n \"isdebtcollection\": false,\n \"originalsum\": 1065,\n \"paidsum\": 100,\n \"remainingsum\": 983.25,\n \"originalprincipal\": 1000,\n \"paidprincipal\": 100,\n \"remainingprincipal\": 900,\n \"originalfee\": 65,\n \"paidfee\": 0,\n \"remainingfee\": 65,\n \"originalinterest\": 0,\n \"paidinterest\": 0,\n \"remaininginterest\": 18.25,\n \"service_description\": \"Invoicing\",\n \"status_statuscode\": \"Purreinkasso\",\n \"reminders\": 1,\n \"debtcollectionlist\": 1\n }\n ]\n}\n{\n \"batchid\": \"My test 2017-03-28 15:40:00\",\n \"action\": [\n {\n \"actiontype\": \"EXPORTDEBTCOLLECTION\",\n \"creditorid\": \"541834958\",\n \"ledgerref\": \"145678945\"\n }\n ]\n}\n\nWhen we have sent a debt collection warning regarding a invoice and the invoice is still not paid, the invoice is ready for debt collection.
\nWhen registering a creditor 3 values can be set here in field \"debtcollectiontransfer\":
\nEndFragment\"
\nWe always recommend using the value 10 or 20. If you do there is no need for extra coding around this.
\nIf you choose 30 - manual collection list the values returned in GET batch and \"case\" object must be processed as follows:
\nWhen a customer pays with the payment information on the reminder or debt collection letters there will be made a settlement in the debt collection system.
\nAfter this there are three steps:
\n1. We make a payment towards the bank account set in bankaccountno
\n2. A remittance report will be available in GET api/Attachment
\n3. Information about the settlement will be available in Get Batch - settlement. This is the basis to make a automatic bookkeeping of the settlement.
\nWhen requesting settlements a value in \"lastsettlementid\" should be set to keep track of settlement which has been booked in the GL ERP.
\nThe value must be kept on the ERP system, and provided in next GET batch request.
Value is set from field \"settlementid\" with highest value in the response.
The settlement will be marked with settlementtype = COLLECTOR_PAYMENT.
In the settlement object it will be reported:
We calculate VAT on the settlements. It is calculated from these values:
\n25% of this results in the value collectorvat.
\nIf the creditor is VAT registered, Visma Financial Solutions will set off or invoice VAT.
\nIf the creditor is not liable for VAT, no VAT will be charged on the fee, but this will be added to the fee paid by the debtor. In such cases, the creditor must only take the cost of VAT from the advance fee, commission on principal and interest.
\nVAT should be bookeept like this:
\ndebit = collectorprincipal + collectorinterest + collectorfee + collectorvat
credit = collectorprincipal + collectorinterest + collectorfee
What is paid to the creditor will be: Share creditor (creditorprincipal + creditor interest + creditor fee) minus VAT on income collection company (collector vat)
\nIn this exact example the bookeeping will be as follows:
\n","_postman_id":"e9c84cf4-61bc-47f6-9f57-4e7c61036892"},{"name":"Example","item":[],"id":"76c137f1-760b-4e9c-a7db-6633aa555cc2","description":"{\n \"batchid\": \"VCS 2023-04-24T13:29:32\",\n \"offline\": false,\n \"settlement\": [\n {\n \"creditorid\": \"328454729\",\n \"customerref\": \"12345\",\n \"ledgerref\": \"145678945\",\n \"referencenumber\": \"1201\",\n \"casenumber\": \"498527\",\n \"collectiontype\": 0,\n \"settlementid\": \"971926\",\n \"settlementtype\": 0,\n \"settlementdate\": \"2023-04-21T00:00:00\",\n \"settlementcurrencycode\": \"NOK\",\n \"settlementexchangerate\": 1,\n \"remittancedate\": \"2023-04-24T00:00:00\",\n \"currencycode\": \"NOK\",\n \"closuredate\": \"2023-04-21T00:00:00\",\n \"paidamount\": 982.58,\n \"creditorprincipal\": 900,\n \"creditorinterest\": 0,\n \"creditorfee\": 0,\n \"collectorprincipal\": 0,\n \"collectorinterest\": 17.58,\n \"collectorfee\": 65,\n \"collectorvat\": 20.65\n }\n ]\n}\n\nThere are two types of payment transactions that entail bookkeeping in the ERP system.
\n1. Direct payments - payment/credits received in the ERP
\nWe are using our payment information (accountnumber, CID) on both reminders and debt collection letters, but we know that some customers can still pay the original invoice. This means that the payments is registered in the ERP system. Direct payments must be reported to us so the invoice amount in our system can be adjusted. The same applies to credit notes.
\n2. Settlements - payments received in our debt-collection system
\nAs mentioned, we are using our payment information on both reminders and debt collection letters, so most of the customers pays directly to us. The payment will then be made to the debt collection system and this is reported as a settlement object in Get Batch. If the payment covers the entire claim (case.remainingsum) the case will be closed.
\nLet us know when you are ready for production.
\nIn advance of the switch to production, we want to have a final functionality test to make sure everything works with our systems.
\nYou will find the URL for production in the chapter URLs.
\n","_postman_id":"6af09559-4d6e-4417-83ad-12776e526e84"}],"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"834090f6-2df6-4966-8136-921376c696d1"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"f340d9a1-7858-47aa-af41-4d61b6b5554a"}}],"variable":[{"key":"baseUrl","value":"/webapi","type":"string"}]}