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.
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.
url | username | NetAPI username | |
url | customer identifier | NetAPI customer ID associated with the username |
TicketRecord
Field | Type | Description |
---|---|---|
version | string | structure versio:"1.01" |
ticket | string | tiketti |
expires | date-time | ticket period ends |
Step 2:
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.
url | secured_hash | Hexadecimal sha1-generated verified hash of consecutively concatenated password and Tiketti. |
TokenRecord
Field | Type | Description |
---|---|---|
version | string | structure version:"1.01" |
token | string | Käyttöoikeustietue |
expires | date-time | Käyttöoikeustietueen voimassaolo päättyy |
Kaikki muut kutsut vaativat Returntun käyttöoikeustietueen (access token) Authorization headerinä:
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
GET service_address/customers?search=<pattern>
url | pattern | Search by You can use the % sign, e.g., CompanyName%, to search for all customers whose name begins with the "CompanyName". |
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. |
GET service_address/customers/<customer_identifier>
url | customer_identifier | customer ID. |
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. |
POST service_address/customers/<customer_identifier>
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. |
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. |
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 |
CustomerRecord.Support
Field | Type | Description |
---|---|---|
string | Sähköpostiosoite |
MESSAGES
GET service_address/messages/available
No parameters |
IncomingInfo
Field | Type | Description |
---|---|---|
version | string | structure version:"1.01" |
items | int | Count of incoming messages |
details | [IncomingInfo.Details] | Details of incoming messages (under) |
GET service_address/messages/headers
No parameters |
IncomingInfo
Field | Type | Description |
---|---|---|
version | string | structure version:"1.01" |
items | int | Count of incoming messages |
details | [IncomingInfo.Details] | Details of incoming messages (under) |
GET service_address/messages/headers/<type>
url | type | Optional cropping to the desired messageType. Message types can be found in connection with the description of the MessageData 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) |
GET service_address/messages/<type>
The messages come according to fifo, i.e. the oldest message first.
url | type | Optional cropping to the desired messageType. Message types can be found in connection with the description of the MessageData structure. |
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) |
GET service_address/messages/id/<id>
The search does not delete the message from the message queue, but is still retrievable by queue search.
url | id | Message ID for a specific message. You can retrieve the message tag with the / headers / call. |
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) |
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.
url | type | Optional cropping to the desired message type. |
MessageData
Field | Type | Description |
---|---|---|
version | string | structure version:"1.01" |
identifier | string | Message Id |
type | enum | Sanoman Type |
datafiles | [MessageData.DataFile] | Message details (above) |
POST service_address/messages
An already sent message, such as an invoice"resend".
url | type | Optional cropping to the desired message type. |
MessageData
Field | Type | Description |
---|---|---|
version | string | structure version:"1.01" |
identifier | string | Message Id |
type | enum | Message Type |
datafiles | [MessageData.DataFile] | Message details (above) |
COMPANY DATA
GET service_address/companies/<vat_identifier>
url | vat_identifier | Company business ID |
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) |
GET service_address/companies?search=<company_name>
Keyword(s) must be encoded in urlencode in PHP ($keyword);
url | ?search= | Company name or part of the name. The search is "case insensitive". |
CompanyRecord
Field | Type | Description |
---|---|---|
version | string | structure version:"1.01" |