Netbox - NetAPI
This documentation was last updated on 5.2.2020.
Netbox's NetAPI is a programming interface for partners. NetAPI is a private service that requires access to a user ID, customer ID, and password access token.
Partners have the opportunity to test the interface in a test environment by requesting IDs from Netbox customer service ([email protected]), for example.
In addition, you can also get a ready-made implementation in PHP and C # for your own use, which allows the partner to implement integration into his system more easily with the help of examples.
The services are REST-style service requests in nature.
Services are performed over an encrypted HTTPS connection.
The JSON format is used as the transmission format for data structures.
The success of service calls is indicated by standard http return codes (see HTTP status codes below).
NetAPI is backward compatible, which means maintaining or extending existing structures in a non-coercive way. Software using NetAPI should take this into account and avoid discarding responses that contain fields that were not yet known during the implementation phase. Similarly, backward compatibility means that NetAPI will not reject requests, even if the fields defined later are missing from the request. New services can be added with completely new structures.
The version of the service described in this document is 1.01. The purpose of version numbering is to express backward compatibility verification: MAJOR.MINOR; When the MAJOR version number changes (for example, 1.0 becomes 2.0), the service interface may not be fully compatible. When only the MINOR number changes, backward compatibility of the service interface is ensured.
API Service Requests:
Customers:GET service_address/customers?search=<pattern>
GET service_address/customers/<customer_identifier>
POST service_address/customers/<customer_identifier>
Messages:
GET service_address/messages/available
GET service_address/messages/headers
GET service_address/messages/headers/<type>
GET service_address/messages/<type>
GET service_address/messages/id/<id>
GET service_address/messages/statuses/<vat_identifier>
POST service_address/messages
POST service_address/messages (resend)
Company data:
GET service_address/companies/<vat_identifier>
GET service_address/companies?search=<company_name>
Here you can test NetAPI Demo IDs, queries and see what they return:
NetAPI Demo -portal
HTTP-status codes
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Authentication
The license record is created in two steps.Step 1:
Service invitations require an access token from the login.
Ticket generation
GET service_address/tickets/<username>[/<customer_identifier>]
username = NetAPI username
customer_identifier = customer ID (e.g. Business ID or option -any-)
Based on the username and customer ID, a ticket is generated for login. The request does not pass the password to the server at all.
A customer ID can be entered as a user ID pair. In the absence of a customer ID, act as if the value of the user ID had been used as the customer ID. The customer ID can also be " -any- " ("line any line").
Note that when creating a ticket with the “-any-” option (in the field <customer_identifier>) gives admin access to all materials of the companies under the ID (messages, data and storage and editing of customer data). by
Alternatively, when entering, for example, a business ID in the field <customer_identifier>, the rights are limited only to the materials, data and customer data of the company in question.
Parameters
| url | username | NetAPI username | |
| url | customer identifier | NetAPI customer ID associated with the username |
Data structure to be returned
Ticket for login. The ticket is valid for two minutes.
TicketRecord
| Field | Type | Description |
|---|---|---|
| version | string | structure versio:"1.01" |
| ticket | string | tiketti |
| expires | date-time | ticket period ends |
URL: https://<service_address>/tickets/NB1234DEMTEST/1234567-8
Return:
{
"version":"1.01",
"ticket":"a33fe7c61bd51ef7c510fdeb7d840f75a105acaf",
"expires":"Thu, 14 Dec 2017 14:05:18 EET"
}
Step 2:
Access token
GET service_address/tokens/<secured_hash>
An access token is generated based on the Secured hash. The request does not transmit a username, client ID, or password to the server at all.
Parameters
| url | secured_hash | Hexadecimal sha1-generated verified hash of consecutively concatenated password and Tiketti. |
Data structure
Käyttöoikeustietue ja lisätietoja. Käyttöoikeustietue on voimassa tunnin ajan.
TokenRecord
| Field | Type | Description |
|---|---|---|
| version | string | structure version:"1.01" |
| token | string | Käyttöoikeustietue |
| expires | date-time | Käyttöoikeustietueen voimassaolo päättyy |
URL: https://<service_address>/tokens/8ea7d2e8f5dd2260d225e563f04ba7afe956c7f2
Return:
{
"version":"1.01",
"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiTkI0MTA4QVNLVEVTVCIsImN1c3Rvb...f-Lds",
"expires":"Thu, 14 Dec 2017 16:36:26 EET"
}
Kaikki muut kutsut vaativat Returntun käyttöoikeustietueen (access token) Authorization headerinä:
Authorization header
Authorization: Bearer <käyttöoikeustietue>
The functions of the session are limited to the clientele expressed in the authentication. For example, message fetching only picks up messages coming to the customer.
When the customer ID is empty or the user ID itself, the functions are limited to the user ID information.
When the customer ID is " -any- ", operations are limited to all customer IDs.
Customer details
Searching for customers with the search factor
GET service_address/customers?search=<pattern>
Parameters
| url | pattern | Search by You can use the % sign, e.g., CompanyName%, to search for all customers whose name begins with the "CompanyName". |
Returnable data structure (list of found customers)
CustomerItemRecord
| Field | Type | Description |
|---|---|---|
| version | string | structure version:"1.01" |
| identifier | string | Customer id (in customers/HUB's software, generally VAT). |
| name | string | Customer name. |
| vat_identifier | string | Customer VAT. |
| edi_identifier | string | Customer EDI id. |
| free_text | string | Free text. |
| open_invoice_channels | string |
• If the value of open_invoice_channels is 0, then the sales invoice channel is OFF and the purchase invoice channel is OFF (both closed). • If the value of open_invoice_channels is 1, then the sales invoice channel is ON and the purchase invoice channel is OFF. • If the value of open_invoice_channels is 2, then the sales invoice channel is OFF and the purchase invoice channel is ON. • If the value of open_invoice_channels is 3, then the sales invoice channel is ON and the purchase invoice channel is ON (both open). If the purchase invoice channel is closed (OFF = value 0 or 1), then the operator of the e-invoice sender automatically receives an error message (negative ACK message) that the e-invoice cannot be delivered to the recipient. |
URL: https://<service_address>/customers?search=Yritys%20%Software%20%Oy
Return:
{
"version": "1.01",
"identifier": "1234567-8",
"name": "Yritys Software Oy",
"vat_identifier": "1234567-8",
"edi_identifier": "003712345678",
"free_text": "Vapaata lisätietoa",
"open_invoice_channels": "3"
}
Retrieving customer information with a customer ID.
GET service_address/customers/<customer_identifier>
Parameters
| url | customer_identifier | customer ID. |
Returnttava data structure (customer information except password)
CustomerItemRecord
| Field | Type | Description |
|---|---|---|
| version | string | structure version:"1.01" |
| identifier | string | Customer ID. |
| name | string | Customer name. |
| vat_identifier | string | Customer business ID. |
| edi_identifier | string | Customer EDI id. |
| eaddress_send | boolean | From address into the TIEKE's e-invoice address register |
| eaddress_receive | boolean | To address into the TIEKE's e-invoice address register |
| free_text | string | Free text. |
| open_invoice_channels | string |
• If the value of open_invoice_channels is 0, then the sales invoice channel is OFF and the purchase invoice channel is OFF (both closed). • If the value of open_invoice_channels is 1, then the sales invoice channel is ON and the purchase invoice channel is OFF. • If the value of open_invoice_channels is 2, then the sales invoice channel is OFF and the purchase invoice channel is ON. • If the value of open_invoice_channels is 3, then the sales invoice channel is ON and the purchase invoice channel is ON (both open). If the purchase invoice channel is closed (OFF = value 0 or 1), then the operator of the e-invoice sender automatically receives an error message (negative ACK message) that the e-invoice cannot be delivered to the recipient. |
URL: https://<service_address>/customers/1234567-8
Return:
{
"version": "1.01",
"identifier": "1234567-8",
"name": "Yritys Software Oy",
"vat_identifier": "1234567-8",
"edi_identifier": "003712345678",
"eaddress_send": true,
"eaddress_receive": true,
"free_text": "Vapaata lisätietoa"
"open_invoice_channels": "3",
"address": {
"street": [
"Valtatie 66",
null,
null
],
"zipcode": "09100",
"city": "Kalihvornia",
"district": "Pirkanmaa",
"country": "Finland",
"phone": "044-7660001"
}
}
Create a new customer or update customer information.
POST service_address/customers/<customer_identifier>
Parameters
| url | customer_identifier | Customer ID. If not provided, an attempt is made to create a customer, otherwise an attempt will be made to update the customer information. | |
| body | CustomerRecord | Customer data. When updating, the client ID must match the ID specified in the url parameter. |
Sending data structure
CustomerRecord
| Field | Type | Description |
|---|---|---|
| version | string | structure version:"1.01" |
| identifier | string | Customer ID (in the client / HUB software, usually the Business ID). |
| name | string | Customer name. |
| vat_identifier | string | Customer VAT |
| edi_identifier | string | Customer EDI id |
| eaddress_send | boolean | From address into the TIEKE's e-invoice address register |
| eaddress_receive | boolean | To address into the TIEKE's e-invoice address register |
| open_invoice_channels | string |
• If the value of open_invoice_channels is 0, then the sales invoice channel is OFF and the purchase invoice channel is OFF (both closed). • If the value of open_invoice_channels is 1, then the sales invoice channel is ON and the purchase invoice channel is OFF. • If the value of open_invoice_channels is 2, then the sales invoice channel is OFF and the purchase invoice channel is ON. • If the value of open_invoice_channels is 3, then the sales invoice channel is ON and the purchase invoice channel is ON (both open). If the purchase invoice channel is closed (OFF = value 0 or 1), then the operator of the e-invoice sender automatically receives an error message (negative ACK message) that the e-invoice cannot be delivered to the recipient. |
| secret | string | Customer password. The field is only used for customer data updates The mechanism allows a NetAPI user to provide their customers with a password associated with a customer ID if they wish. |
| address | CustomerRecord.Address | Address (see structure below) |
| contact | CustomerRecord.Contact | Contact information (see structure below) |
| support | CustomerRecord.Support | Support contact information (see structure below) |
| free_text | string | Free text. |
Customer details
CustomerRecord.Address
| Field | Type | Description |
|---|---|---|
| street | [string] | Street address. 1-4 riviä |
| zipcode | string | Post number |
| city | string | City |
| district | string | State |
| country | string | Coutry |
| phone | string | Phone |
Customer details
CustomerRecord.Support
| Field | Type | Description |
|---|---|---|
| string | Sähköpostiosoite |
URL: https://<service_address>/customers/1234567-8
body:
{
"version":"1.01",
"identifier":"1234567-8",
"name": "Yritys Software Oy",
"vat_identifier": "1234567-8",
"edi_identifier": "003712345678",
"secret": "valinnainen",
"eaddress_send": "true",
"eaddress_receive": "false",
"free_text": "Tuki klo 09-13",
"open_invoice_channels": "1",
"address": [
{
"street": "Yrityksen nimi",
"zipcode": "01-01-2018",
"city": "31-12-2080",
"district": false,
"country": "Finland",
"phone": "040123456789"
}
],
"contact": [
{
"first_name": "Matti",
"middle_name": "Masi",
"surname": "Meikäläinen",
"phone": "0401234567",
"email": "[email protected]"
}
],
"support": [
{
"email": "[email protected]"
}
]
}
MESSAGES
Retrieving information from available messages
GET service_address/messages/available
Parameters
| No parameters |
Incoming data structure
IncomingInfo
| Field | Type | Description |
|---|---|---|
| version | string | structure version:"1.01" |
| items | int | Count of incoming messages |
| details | [IncomingInfo.Details] | Details of incoming messages (under) |
URL: https://<service_address>/messages/available
Return:
{
"version": "1.01",
"items": 12
"details": [
{
"receiver": "003702823456",
"name": "Yritys Liikenne Ky",
"items": {
"messages": "12",
"acks": "11",
"errors": "1"
}
}
]
}
Retrieving header information as a list of available messages
GET service_address/messages/headers
Parameters
| No parameters |
Incoming data structure
IncomingInfo
| Field | Type | Description |
|---|---|---|
| version | string | structure version:"1.01" |
| items | int | Count of incoming messages |
| details | [IncomingInfo.Details] | Details of incoming messages (under) |
URL: https://<service_address>/messages/headers
Return:
[
{
"messageid": "1036",
"type": invoice,
"original_filename": "kollektor-Koll_20180410055506_0001",
"handled": "2018-05-04 12:11:17",
"sender": {
"address": "14756079",
"intermediator": "KOLLEKTORSCAN",
"name": "Laskuttaja Lex Oy",
"messageid": "75856097",
"timestamp": "2018-04-08T13:40:00+0000"
},
"receiver": {
"address": "003724563330",
"intermediator": "003726044706",
"name": "CRM House Oy"
}
}
Retrieving header information as a list of available messages by message type
GET service_address/messages/headers/<type>
Parameters
| url | type | Optional cropping to the desired messageType. Message types can be found in connection with the description of the MessageData structure. |
Incoming data structure
IncomingInfo
| Field | Type | Description |
|---|---|---|
| version | string | structure version:"1.01" |
| items | int | Count of incoming messages |
| details | [IncomingInfo.Details] | Details of incoming messages (under) |
URL: https://<service_address>/messages/headers/invoice
Return:
[
{
"messageid": "1036",
"type": invoice,
"original_filename": "kollektor-Koll_20180410055506_0001",
"handled": "2018-05-04 12:11:17",
"sender": {
"address": "14756079",
"intermediator": "KOLLEKTORSCAN",
"name": "Laskuttaja Lex Oy",
"messageid": "75856097",
"timestamp": "2018-04-08T13:40:00+0000"
},
"receiver": {
"address": "003724563330",
"intermediator": "003726044706",
"name": "CRM House Oy"
}
}
Retrieving the next available message or part of it (queue search)
The messages come according to fifo, i.e. the oldest message first.
GET service_address/messages/<type>
The messages come according to fifo, i.e. the oldest message first.
Parameters
| url | type | Optional cropping to the desired messageType. Message types can be found in connection with the description of the MessageData structure. |
Returnttava data structure (Details of message)
MessageData
| Field | Type | Description |
|---|---|---|
| version | string | structure version:"1.01" |
| identifier | string | Message id |
| type | enum | Sanoman Type |
| datafiles | [MessageData.DataFile] | Details of message (under) |
URL: https://<service_address>/messages
Return:
{
"version": "1.01",
"identifier": "xml",
"type": "ack",
"datafiles":
[
{
"data":"PFNPQVAtRU5WOkVudmV...2b2ljZWFjaz4K",
"filename":"ERR-171219150010860-52.xml",
"filesize":3684,
"filetime":"2017-12-19T15:03:55+0200",
"sha1":"d0357bd3543d322eb26cf04c8bc4094956390881"
}
]
}
Retrieving a specific message with an identifier
The search does not delete the message from the message queue, but is still retrievable by queue search.
GET service_address/messages/id/<id>
The search does not delete the message from the message queue, but is still retrievable by queue search.
Parameters
| url | id | Message ID for a specific message. You can retrieve the message tag with the / headers / call. |
Retrunable data structure (Message details)
MessageData
| Field | Type | Description |
|---|---|---|
| version | string | structure version:"1.01" |
| identifier | string | Message id |
| type | enum | Sanoman Type |
| datafiles | [MessageData.DataFile] | Details of messages (under) |
URL: https://<service_address>/id/123456
Return:
{
"version": "1.01",
"identifier": "1043",
"type": "ack",
"datafiles":
[
{
"data":"PFNPQVAtRU5WOkVudmV...2b2ljZWFjaz4K",
"filename":"ERR-171219150010860-52.xml",
"filesize":3684,
"filetime":"2017-12-19T15:03:55+0200",
"sha1":"d0357bd3543d322eb26cf04c8bc4094956390881"
}
]
}
SEND MESSAGE OR PART OF MESSAGE
It is recommended that the message be sent in its entirety as a ZIP file. The files can also be sent separately, as a single service call or as separate service calls. The message identifier is for reference only. Separate files are not attached to a message using a message tag, but only based on the contents. The message identifier must be permanently unique. File names must be unambiguous for 6 months.
POST service_address/messages
It is recommended that the message be sent in its entirety as a ZIP file. The files can also be sent separately, as a single service call or as separate service calls. The message identifier is for reference only. Separate files are not attached to a message using a message tag, but only based on the contents. The message identifier must be permanently unique. File names must be unambiguous for 6 months.
Parameters
| url | type | Optional cropping to the desired message type. |
Data structure to be sent (message details)
MessageData
| Field | Type | Description |
|---|---|---|
| version | string | structure version:"1.01" |
| identifier | string | Message Id |
| type | enum | Sanoman Type |
| datafiles | [MessageData.DataFile] | Message details (above) |
Resending message (resend)
An already sent message, such as an invoice"resend".
POST service_address/messages
An already sent message, such as an invoice"resend".
Parameters
| url | type | Optional cropping to the desired message type. |
Data structure to be sent (message details)
MessageData
| Field | Type | Description |
|---|---|---|
| version | string | structure version:"1.01" |
| identifier | string | Message Id |
| type | enum | Message Type |
| datafiles | [MessageData.DataFile] | Message details (above) |
URL: https://<service_address>/messages
Body:
{
"datafiles": [
{
"data": "...base64_encode...",
"filename": "invoice_543_1234567890.xml",
"filesize": 1122
},
{
"data": "...base64_encode...",
"filename": "invoice_543_1234567890.pdf",
"filesize": 10022
}
],
"resend": {
"receiver": {
"address": "receiver_eaddress",
"intermediator": "receiver_intermediator_address"
},
"sender": {
"address": "sender_eaddress",
"intermediator": "sender_intermediator_address",
"messageid": "sender_message_id"
}
},
"type": "invoice"
}
COMPANY DATA
Searching for public company information with a business ID
GET service_address/companies/<vat_identifier>
Parameters
| url | vat_identifier | Company business ID |
data structure (Yrityksen tiedot)
CompanyRecord
| Field | Type | Description |
|---|---|---|
| version | string | structure version:"1.01" |
| vat_identifier | string | Company business ID |
| names | [CompanyRecord.Name] | Company name (under) |
| addresses | [CompanyRecord.Address] | Company address details (under) |
| eaddresses | [CompanyRecord.Eaddress] | Company e-invoice addresses (under) |
URL: https://<service_address>/companies/1234567-8
Return:
{
"version": "1.01",
"vat_identifier": "2604470-6",
"names": [
{
"name": "Netbox Finland Oy",
"start_date": "2014-03-04",
"end_date": "",
"aux": "false"
}
],
"addresses": [
{
"street": "Rautatienkatu 21",
"zipcode": "33100",
"city": "TAMPERE",
"country": "",
"type": "postal",
"start_date": "2018-02-17",
"end_date": ""
},
{
"street": "Rautatienkatu 21",
"zipcode": "33100",
"city": "TAMPERE",
"country": "",
"type": "visiting",
"start_date": "2018-02-17",
"end_date": ""
}
],
"eaddresses": [
{
"type": "ovt",
"context": "einvoice",
"direction": "send",
"address": "003726044706",
"service_type": "ovt",
"service_identifier": "003726044706"
},
{
"type": "ovt",
"context": "einvoice",
"direction": "receive",
"address": "003726044706",
"service_type": "ovt",
"service_identifier": "003726044706"
}
]
}
Searching for company public information by business name
Keyword(s) must be encoded in urlencode in PHP ($keyword);
GET service_address/companies?search=<company_name>
Keyword(s) must be encoded in urlencode in PHP ($keyword);
Parameters
| url | ?search= | Company name or part of the name. The search is "case insensitive". |
Returnable data structure (Company details)
CompanyRecord
| Field | Type | Description |
|---|---|---|
| version | string | structure version:"1.01" |
URL: https://<service_address>/companies?search=netbox%20%finland
Return:
{
"version": "1.01",
"results": [
{
"vat_identifier": "2604470-6",
"name": "Netbox Finland Oy",
"street": "Rautatienkatu 21 ",
"zipcode": "33100",
"city": "TAMPERE",
"domicile": "TAMPERE"
},
{
"vat_identifier": "1306336-9",
"name": "Tmi Netbox",
"street": " ",
"zipcode": null,
"city": null,
"domicile": "PAIMIO"
},
{
"vat_identifier": "2938504-7",
"name": "NETBOX PL SP. Z O.O.",
"street": " ",
"zipcode": null,
"city": null,
"domicile": "ULKOMAAT"
}
]
}