SendRegning Web Services implementation guide

Table of content

• SendRegning Web Services implementation guide
• Sending
• Queries
• Examples
• Overview of changes in the implementation guide
• Technical
• Login
• HTTP commands
• Explanation for HTTP parameters
• HTTP response codes
• HTTP response types (Content Type)
• XML
• XML in in requests and responses
• Actions
• Send invoices
• Queries - (Invoice)
• Queries - (Invoice status)
• Send dunning(s)
• Sales ledger
• Recipient
• Product
• Constants
• Data types
• Miscellaneous
• Uptime
• Timeout
• Maintenance window
• Implementation help
• Errors
• New functionality
• Terms/Glossary
• Programming tips

The following functionality is exposed via SWS:

Sending

• Send n invoices/credit notes on paper/e-mail.
• Send dunning with/without dunning fee/interest.

Queries

• Invoices
• Invoice status
• Constants
• Sales ledger
• Recipient

Examples

See our website for examples: http://www.sendregning.no/integrasjon/api.html

Overview of changes in the implementation guide

November 1, 2011

• Added documentation describing the new batchId attribute on the <invoices> element to prevent double submit.
• Added a section about client timeout

May 9, 2011

• Translated this guide to English

September 20, 2010

• Added documentation for sales ledger
• Added documentation for recipient
• Updated all urls in this document to link to https://www.sendregning/ws

March 10, 2009

• Removed sample code from the implementation guide, since we have created a source code file with Google Code
• Moved the implementation guide to Google Code
• Wrote a PHP client that is available from Google Code

January 14, 2009

• Removed <finalPayment> element from the response you get after you have sent invoice(s). This can be retrieved using SELECT -> INVOICE-STATUS

November 2, 2007

• Added <eventParams> element under the <invoice-status><invoice><history><entry> element.

August 28, 2008

• Added more information about the <recipientNo> element.

May 3, 2007

• Added description of query of invoice status.
• Updated code samples under programming tips
• Described the procedure for reporting errors
• Described the procedure for reporting requests for new featureRequest functionality

April 30, 2007

• Updated the description of XML in requests and responses.

April 25, 2007

• Updated the description of sending dunnings.

April 20, 2007

• Described sending of dunnings.

April 11, 2007

• Described the response when calling constants.

March 29, 2007

• Specified image size when retrieving JPG.

March 28, 2007

• Added HTTP response code 204
• Removed the condition draft from possible conditions. The reason for this is that it is not possible to save invoices as drafts via SWS.

March 26, 2007

• Changed the element description for the <email> element under the <optional> element.

March 12, 2007

• Added the <shipment> element under the <invoice> element.

Technical

Login

SendRegning Web Services supports BASIC authentication, so you add a user name and password in the query. Since there is forced https for SWS, all traffic is encrypted between your client and server.

HTTP commands

HTTP command matrix

A valid HTTP command may therefore look like this: https://www.sendregning.no/ws/butler.do?action=select&type=constant

- to get all constants back in xml format.

Explanation for HTTP parameters

action

This parameter must ALWAYS be specified.

• send
• Sends n instances of chosen type.
• select
• Returns n instances of chosen type.
• insert
• Creates n instances of chosen type.
• update
• Updates n instances of chosen type.
• delete
• Deletes one instance of chosen type.

type

This parameter must ALWAYS be specified.

• invoice
• Invoice
• dunning
• Dunning
• invoice-status
• Invoice status - payments, state, dunnings, etc..
• recipient
• Recipient
• product
• Product
• constant
• Constants - (VAT rates, default interest, dunning fee, etc.)

test

• true
• If test=true, the server will respond by validating the HTTP command and returning real test data and response codes.
• This parameter is only used during the implementation phase and testing, when you go into production, you cannot send test=false for each HTTP command.

HTTP response codes

SWS returns the following response codes on an HTTP command:

• 200 Ok
• The HTTP command was performed. The server will also return the result of the processing, usually in XML.
• 204 No response
• The HTTP command was performed, but there was no return data. May occur, for example, when you run a query that does not contain any return data.
• 400 Invalid HTTP command
• The HTTP parameters are incomplete and/or not in accordance with the HTTP command matrix. You can usually easily find out what the problem is by reading the error message that follows the response.
• 409 Conflict
• Conflict - The provided batchId on the <invoices> element has already been processed. Used for preventing double HTTP POST requests.
• 500 Internal error
• The server failed unexpectedly and the HTTP command was interrupted (not conducted).
• 501 Not implemented
• The HTTP command is not implemented on the server side.

You can read more about it here HTTP respons codes.

HTTP response types (Content Type)

SWS returns the following response content types:

• text/html
• A response that returns text/html has failed, and a human must interpret the error message that follows.
• text/xml
• The response contains XML.
• application/json
• The response contains JSON.
• application/pdf
• The response contains a PDF document.
• image/jpeg
• The response contains an JPG image.

XML

When you are going to send out invoices via SWS, you send us a XML document over HTTPS, when you are sending us an HTTP command about account-related data, you get XML back that your client program must interpret correctly.

PLEASE READ VERY CAREFULLY!

There is NO official or unofficial DTD that you can use to validate a XML document that you receive from SWS. The reason for this is that we have designed our XML documents in such a way that changes in the XML documents do not require changes in the SWS clients, i.e. your data program. This is a great help to both you and us.

We reserve the right to add new elements and attributes to all XML, independent of the delivery time and without notice. However, we will NOT remove existing elements or attributes without notice. There is no guarantee that all elements or attributes are present for all XML formats that SWS returns. When information is delivered in XML format, there is no guarantee that XML elements of the same level are always returned in the same order, the order may even be different for two equal HTTP commands. This is not unique to our service. This is because the XML format does not set requirements for the properties mentioned, the same thing basically applies to Web Services in all programming languages.

Please be aware of this, and do NOT perform strict validation on received XML. Do not expect elements or attributes to come in a particular order, always check the contents of these. All elements have a label that tells what kind of information it contains. If you come across an unknown element/attribute in an XML file, you must ignore this in your data program.

We take no responsibility for external systems that crash, freeze up, or fail because we added a new XML element and/or attribute, or have changed the order of these.

XML in in requests and responses

All xml that SWS returns will be UTF-8: <?xml version="1.0" encoding="UTF-8"?>

All xml that is sent in to SWS will be interpreted in UTF-8

The maximum file size for transfer of xml files to SWS is set to 2MB (2097152 bytes)

Actions

Send invoices

In order to send n number of invoices via SWS, the XML document may look like this:

<?xml version="1.0" encoding="UTF-8"?>
<invoices batchId="yourUniqueBatchId>
    <invoice>
        <name>Ola Nordmann</name>
        <zip>0010</zip>
        <city>OSLO</city>
        <lines>
            <line>
                <itemNo>1</itemNo>
                <qty>100.00</qty>
                <prodCode>1</prodCode>
                <desc>Description</desc>
                <unitPrice>100.00</unitPrice>
                <discount>0.00</discount>
                <tax>25</tax>
            <line>
        <lines>
        <optional>
            <orderNo>Order number</orderNo>
            <invoiceDate>29.11.06</invoiceDate>
            <dueDate>13.12.06</dueDate>
            <orderDate>29.11.06</orderDate>
            <recipientNo>10</recipientNo>
            <address1>Drammensveien 1</address1>
            <country>NORGE</country>
            <email>ola@nordmann.no</email>
            <ourRef>Our reference</ourRef>
            <yourRef>Your reference</yourRef>
            <comment>Comment</comment>
            <invoiceText>Invoice Text</invoiceText>
        </optional>
    </invoice>
    <invoice>
        <name>Kari Nordmann</name>
        <zip>0010</zip>
        <city>OSLO</city>
        <lines>
            <line>
                <itemNo>1</itemNo>
                <qty>100.00</qty>
                <prodCode>1</prodCode>
                <desc>Description</desc>
                <unitPrice>100.00</unitPrice>
                <discount>0.00</discount>
                <tax>25</tax>
            <line>
        <lines>
        <optional>
            <orderNo>Order number</orderNo>
            <invoiceDate>29.11.06</invoiceDate>
            <dueDate>13.12.06</dueDate>
            <orderDate>29.11.06</orderDate>
            <recipientNo>10</recipientNo>
            <address1>Drammensveien 1</address1>
            <country>NORGE</country>
            <email>kari@nordmann.no</email>
            <ourRef>Our reference</ourRef>
            <yourRef>Your reference</yourRef>
            <comment>Comment</comment>
            <invoiceText>Invoice Text</invoiceText>
        </optional>
    </invoice>
</invoices>

batchId

To prevent double submits from the client, the client must provide us with an unique batchId when sending invoices. This is an attribute on the <invoices> element, e.g. <invoices batchId="yourUniqueBatchId">

It is crucial that your unique batch id is created once before doing the HTTP request, so you don't retry with another batchId if the client fails after the HTTP POST request.

The provided batchId will be present in the xml response.

If the given batchId has already been processed, SWS will return HTTP status code 409 - conflict.

Description of the various XML elements when you are sending invoices via SWS

• <invoices batchId="yourUniqueBatchId>
• <invoice>
• <lines>
• <line>
• <optional>
• <shipment>

Example of absolutely the smallest XML document that can be transferred for sending out an invoice on paper

In this case, an invoice will be printed out on paper and sent to Ola Nordmann, where most of the standard values are used.

<?xml version="1.0" encoding="UTF-8"?>
<invoices batchId="yourUniqueBatchId>
    <invoice>
        <name>Ola Nordmann</name>
        <zip>0010</zip>
        <city>OSLO</city>
        <lines>
            <line>
                <qty>1</qty>
                <desc>Description</desc>
                <unitPrice>100.00</unitPrice>
            </line>
        </lines>
    </invoice>
</invoices>

Example of absolutely the smallest XML document that can be transferred for sending out an invoice through e-mail

In this case, an invoice will be sent through e-mail to ola@nordmann.no, with a copy to kari@nordmann.no, where most of the standard values are used.

<?xml version="1.0" encoding="UTF-8"?>
<invoices batchId="yourUniqueBatchId>
    <invoice>
        <name>Ola Nordmann</name>
        <zip>0010</zip>
        <city>OSLO</city>
        <lines>
            <line>
                <qty>1</qty>
                <desc>Description</desc>
                <unitPrice>100.00</unitPrice>
            </line>
        </lines>
	<shipment>
		EMAIL
		<emailaddresses>
			<email>ola@nordmann.no</email>
		</emailaddresses>
		<copyaddresses>
			<email>kari@nordmann.no</email>
		</copyaddresses>
	</shipment>
    </invoice>
</invoices>

Response

When you retrieve one or more invoices from SWS, you may get the following XML back as a response:

<?xml version="1.0" encoding="UTF-8"?>
<invoices batchId="yourUniqueBatchId>
    <invoice>
        <name>Ola Nordmann</name>
        <zip>0010</zip>
        <city>OSLO</city>
        <lines>
            <line>
                <itemNo>1</itemNo>
                <qty>100.00</qty>
                <prodCode>1</prodCode>
                <desc>Description</desc>
                <unitPrice>100.00</unitPrice>
                <discount>0.00</discount>
                <tax>25</tax>
                <lineTaxAmount>2500.00</lineTaxAmount>
                <lineTotal>12500.00</lineTotal>
            </line>
        </lines>
        <optional>
            <invoiceType>ordinary</invoiceType>
            <invoiceNo>82</invoiceNo>
            <orderNo>Order number</orderNo>
            <invoiceDate>29.11.06</invoiceDate>
            <dueDate>13.12.06</dueDate>
            <orderDate>29.11.06</orderDate>
            <state>sent</state>
            <recipientNo>10</recipientNo>
            <address1>Drammensveien 1</address1>
            <country>NORGE</country>
            <email>ola@nordmann.no</email>
            <ourRef>Our reference</ourRef>
            <yourRef>Your reference</yourRef>
            <tax>2500.00</tax>
            <total>12500.00</total>
            <comment>Comments</comment>
            <invoiceText>Invoice Text</invoiceText>
            <orgNrSuffix>false</orgNrSuffix>
            <accountNo>16071990021</accountNo>
            <orgNo>980489698</orgNo>
            <dunningFee>55.00</dunningFee>
            <interestRate>9.75</interestRate>
        </optional>
    </invoice>
    <invoice>
        <name>Kari Nordmann</name>
        <zip>0010</zip>
        <city>OSLO</city>
        <lines>
            <line>
                <itemNo>1</itemNo>
                <qty>100.00</qty>
                <prodCode>1</prodCode>
                <desc>Description</desc>
                <unitPrice>100.00</unitPrice>
                <discount>0.00</discount>
                <tax>25</tax>
                <lineTaxAmount>2500.00</lineTaxAmount>
                <lineTotal>12500.00</lineTotal>
            </line>
        </lines>
        <optional>
            <invoiceType>ordinary</invoiceType>
            <invoiceNo>83</invoiceNo>
            <orderNo>Order number</orderNo>
            <invoiceDate>29.11.06</invoiceDate>
            <dueDate>13.12.06</dueDate>
            <orderDate>29.11.06</orderDate>
            <state>sent</state>
            <recipientNo>10</recipientNo>
            <address1>Drammensveien 1</address1>
            <country>NORGE</country>
            <email>kari@nordmann.no</email>
            <ourRef>Our reference</ourRef>
            <yourRef>Your reference</yourRef>
            <tax>2500.00</tax>
            <total>12500.00</total>
            <comment>Comments</comment>
            <invoiceText>Invoice Text</invoiceText>
            <orgNrSuffix>false</orgNrSuffix>
            <accountNo>16071990021</accountNo>
            <orgNo>980489698</orgNo>
            <dunningFee>55.00</dunningFee>
            <interestRate>9.75</interestRate>
        </optional>
    </invoice>
</invoices>

Description of the various XML elements in a response from SWS when you have sent out invoices

These elements may come as additional elements in the response from the server after you have sent invoice(s).

NOTE: These elements are only readable for the client, which means that they will be ignored when transferring XML from client to server.

Queries - (Invoice)

In order to run a query on registered invoices, you post an XML file to SWS that interprets the query and returns the result in XML/JSON.

Description of the various XML elements when you are running a query on registered invoices

Matrix for queries (invoices)

x = one instance n = multiple instances

Examples of queries (invoice)

Get all paid invoices:

<?xml version="1.0" encoding="UTF-8"?>
<select>
    ALL
    <where>
        <states>
            <state>paid</state>
        </states>
    </where>
</select>

Get the last 10 invoices sent to recipient with recipient number 1

<?xml version="1.0" encoding="UTF-8"?>
<select>
    LAST 10
    <where>
        <recipientNumbers>
            <recipientNumber>1</recipientNumber>
        </recipientNumbers>
    </where>
</select>

Get invoice numbers 1, 2, and 5 in a PDF file

<?xml version="1.0" encoding="UTF-8"?>
<select>
    <invoiceNumbers>
        <invoiceNumber>1</invoiceNumber>
        <invoiceNumber>2</invoiceNumber>
        <invoiceNumber>5</invoiceNumber>
    </invoiceNumbers>
    <format>pdf</format>
</select>

Get 1st dunning for invoice number 1 as JPG

<?xml version="1.0" encoding="UTF-8"?>
<select>
    <invoiceNumbers>
        <invoiceNumber>1</invoiceNumber>
    </invoiceNumbers>
    <format>jpg</format>
    <dunningType>1Dunning</dunningType>
</select>

Queries - (Invoice status)

In order to run a query on invoice status, you post an XML file to SWS that interprets the query and returns the result in XML.

Description of the various XML elements when you are running a query on invoice status

Matrix for queries (invoice status)

n = multiple instances

Examples of queries (invoice)

Get status for all paid invoices:

<?xml version="1.0" encoding="UTF-8"?>
<select-status>
    ALL
    <where>
        <states>
            <state>paid</state>
        </states>
    </where>
</select-status>

Get status for the last 10 invoices sent to recipient with recipient number 1

<?xml version="1.0" encoding="UTF-8"?>
<select-status>
    LAST 10
    <where>
        <recipientNumbers>
            <recipientNumber>1</recipientNumber>
        </recipientNumbers>
    </where>
</select-status>

Get status for invoice numbers 1, 2, and 5

<?xml version="1.0" encoding="UTF-8"?>
<select-status>
    <invoiceNumbers>
        <invoiceNumber>1</invoiceNumber>
        <invoiceNumber>2</invoiceNumber>
        <invoiceNumber>5</invoiceNumber>
    </invoiceNumbers>
</select-status>

Responses - invoice status

<invoice-status>
    <invoice number="10">
        <state>dueDecide</state>
        <payments>
            <payment id="1234567">
                <paymentDate>04.20.07</paymentDate>
                <amount>625.00</amount>
                <paymentType>PMTM</paymentType>
            </payment>
        </payments>
        <history>
            <entry>
                <timestamp>01.31.06 09:51:11</timestamp>
                <fromState>start</fromState>
                <toState>sent</toState>
                <event>createComplete</event>
                <eventParams>snailMail,</eventParams>
                <action>send</action>
            </entry>
        </history>
        <dunnings>
            <entry dunningNo="1">
                <dunningDate>04.19.07</dunningDate>
                <dunningType>1Dunning</dunningType>
                <dunningText>We unfortunately do not seem to have received your payment for this invoice.</dunningText>
                <dunningFeeValue>53.00</dunningFeeValue>
                <interestRate>8.75</interestRate>
                <dunningDays>14</dunningDays>
            </entry>
        </dunnings>
    </invoice>
</invoice-status>

Description of the various XML elements in a response from SWS when you have queried the invoice status

Send dunning(s)

In order to send out a dunning, the original invoice you want to dun must be sent out via SendRegning.no. The original invoice must also be in the state dueDecide.

You can also find more information about when you can add to dunning fee/interest here

Delivery method

A dunning must be printed out and sent to the recipient by paper mail.

The reason for this is the wording in the Act relating to overdue payments, which says:

Demand can be sent electronically if the debtor has expressly accepted the use of such communication.

The Norwegian Consumer Council says the following about this:

The Norwegian Consumer Council is in doubt whether it is desirable that demands can be sent electronically, even if the debtor has expressly accepted this.

The lawyers/auditors we have had contact with regarding this, say quite clearly that if there is to be some weight to the demand, a dunning should be sent on paper.

Description of the various XML elements when sending out dunning(s) ====

You will get the same response from SWS as if you had sent the dunning as a regular invoice.

Sales ledger

Sales ledger

Recipient

Recipient

Product

HTTP command

<<< - Not implemented - >>>

Responses

<<< - Not implemented - >>>

Constants

HTTP command

https://www.sendregning.no/ws/butler.do?action=select&type=constant

Responses

March 17, 2009

<?xml version="1.0" encoding="UTF-8"?>
<constants>
    <dunningFee>59.00</dunningFee>
    <interestRate>10</interesRate>
    <firstInvoiceNo>1</firstInvoiceNo>
    <taxRates>
        <taxRate fromDate="01.01.00" toDate="01.01.99">0</taxRate>
        <taxRate fromDate="01.01.06" toDate="01.01.99">8</taxRate>
        <taxRate fromDate="01.01.07" toDate="01.01.99">14</taxRate>
        <taxRate fromDate="12.15.04" toDate="01.01.99">25</taxRate>
        <defaultTaxRate>25</defaultTaxRate>
    </taxRates>
</constants>

Description of the various XML elements when querying constants

Data types

In XML documents that SWS generates, or in XML documents that you send in, the following data types are used.

Miscellaneous

Uptime

www.SendRegning.no does not have guaranteed uptime, which means that you MUST program your client to allow for time out, etc. The connection between client and server due to circumstances outside the area of responsibility of www.SendRegning.no.

www.SendRegning.no takes no responsibility for clients that crash, freeze up, or fail because the connection between the client and SWS is down.

Timeout

A common mistake when implementing SWS is ignoring your HTTP client library timeout setting. In some libraries this is sometimes set as low as a couple of seconds, and when you execute the requests with the test flag set to true that is not a problem since the test response is already generated. Then you go into production and send your first couple of hundred invoices, which can take our server several minutes to process, so you will not get the response since your client has timed out. To avoid this please set your HTTP client library timeout to at least 600 seconds.

If you do get an error you should always check whether the invoices were processed or not before you retry, either by doing another request for select last to see what the last used invoiceNo is, or by logging in manually to SendRegning and having a look at the invoices in the sent state.

Remember that invoices that are sent can't be deleted according to the Norwegian book keeping regulations. If invoices are sent twice you must issue credit invoices for the extra invoices.

Maintenance window

www.SendRegning.no reserves the right to upgrade the server/service, which means that we may stop the service such that is unavailable each night between 2 and 3 a.m. Please respect this, and add a check for this in your client.

Implementation help

For help implementing SWS, you can make direct contact with the developer of SWS at the following e-mail address sws@sendregning.no. We can also provide consulting assistance in the implementation.

Please read this document carefully before you ask the developer directly.

Errors

If you experience errors with SWS, you can register these at her.

New functionality

If you want new functionality in SWS, you can register this at her.

Terms/Glossary

We mean the following when we use these words:

• SWS
• SendRegning.no Web Services
• client
• Your data program that talks to SWS over the internet
• invoice
• An invoice
• recipient
• Recipient of invoice
• originator
• Originator of invoice

Programming tips

We have collected all source code at Google Code. Here you can download clients written in different languages, including Java, PHP, and Perl.

This document was converted from HTML to Google Wiki-code using http://beavercreekconsulting.com/blog/2008/05/html-to-google-code-wiki-converter/_