¶ Generic information
The RESTful webservices interface at Apix allows sending (and receiving) documents electronically from/to application.
Specifically the invoice sending service allows sending indvidual or a batch of invoices from the application to the Apix platform for conversion and routing to the channel defined by the receiver - either as an Networked einvoice or as a letter through a printing service.
The service does not have a setup fee, monthly fees or maintance fees. The service is billed either as PREPAID service or as normal monthly invoiced service.
¶ PREPAID model
All transactions are paid with Netstamps (credits) that are purchased in advance from a webshop. The current saldo of Netstamps is maintained at Apix servers.
Apix shares the income from used Netstamps with software vendor whose application was used to send/receive the transaction.
¶ INVOICED model
In invoiced model the service usage is either billed from the end-user or from the software vendor. In the case of software vendor the pricing is based on wholesale model allowing the vendor to price the service on his own.
¶ Suggested modifications and additions to the sending application
¶ 'Send'-button in invoice sending
It is recommeded that an additional 'Send'-functionality is added to the software parallel to the existing 'print'-functionality in 'Billing and salesledger (etc.)' part of the software. This functionality should be present in all the same areas as the 'print' functionallity - in menus, toolbars and functionareas.
Graphically the design of the 'Send' should look like the 'X' in Apix-logo.
| File | Modified | |
|---|---|---|
| 1 | PNG File Send_arrow_grey.png | Sep 03, 2010 by Veli-Matti Sahlberg |
| 2 | PNG File Send_arrow_grey_small.png | Sep 03, 2010 by Veli-Matti Sahlberg |
| 3 | PNG File Send_arrow_red_small.png | Sep 03, 2010 by Veli-Matti Sahlberg |
| 4 | PNG File Send_arrow_red.png | Sep 03, 2010 by Veli-Matti Sahlberg |
| 5 | PNG File Send_arrow_blue.png | Sep 03, 2010 by Veli-Matti Sahlberg |
| 6 | PNG File Send_arrow_blue_small.png | Sep 03, 2010 by Veli-Matti Sahlberg |
¶ Suggested operation at software when 'Send' is activated the first time
The application should open a new window with three choices:
- What does 'Send' mean ?
- Register and create ids
- Download settings to the application
The window can be closed using the windowing system's 'close' or by pressing the 'Älä kuorita vaan Lähetä'-button.
The details of the various functions (1.1,1.2 and 1.3) in the picture are explained in the following chapters.
¶ 1.1 What does 'Send' mean ?
When the user pushes the link a separate browser window is opened with the following URL:
http://www.apix.fi/?s=send (in Finland)
The web-page behind the link contains information about the 'Send' functionality and the benefits of using it.
¶ 1.2 Register and create ids
THIS APPLIES ONLY FOR THE PREPAID MODEL. In invoicing model the customer is established through API or through Servicedesk
When the user pushes the link a separate browser window is opened with the following URL:
PRODUCTION https://registration.apix.fi/
TEST https://test-registration.apix.fi/
The web-page contains a registration page after which the user is directed to the webshop.apix.fi/test-webshop.apix.fi (Webshop) for purchasing netstamps (credits).
In the registration the user gives the basic information about his company, generates an identification for himself based on email-addres (UserId) and chooses an password (Password) for it. This identification is used when the interactive services of Apix are accesed (Webshop, Online archive etc.). The application CAN store these internally for further use.
In addition of the personal identification the Apix system generates application specific id (TransferID) and a related key (TransferKey) as well as an unique identifier for the company (CompanyUniqueID).
¶ 1.3 Download the settings to application
When the user pushes the button the application generates a REST-call RetrieveTransferID which will return the generated ids for sending/receiving documents for the application. These are the TransferKey, TransferID and UniqueCompanyID. The application should automatically store these ids for further use.
REST-call is authenticated by requesting the UserID and Password generated in step 1.2
See the External REST-API for details on the call.
¶ Operation on subsequent invocations
It is recommended that the application opens a separate window for 'Send' with the contents and functions described in the aboce picture.
¶ 2.1 Saldo of Netstamps
THIS APPLIES ONLY FOR THE PREPAID MODEL. In invoicing model the saldo is always reported 99999.
The application should automatically retrieve the current saldo of netstamps from Apix servers using a REST-call GetSaldo.
See the External REST-API for details on the call.
¶ 2.2. Purchase Netstamps
THIS APPLIES ONLY FOR THE PREPAID MODEL. In invoicing model the Netstamps are not used
The button should open a new browser window with the following URL:
PRODUCTION https://webshop.apix.fi/
TEST https://test-webshop.apix.fi/
The webpage contains the webshop for purchasing the Netstamps.
¶ 2.3 Transfer/Purchase history
OPTION A:
The application can automatically retrieve the history information from Apix servers using a REST-call GetHistory and show the results using it's own mechanisms.
See the External REST-API for details on the call.
OPTION B:
The button should open a new browser window with the following URL:
PRODUCTION https://webshop.apix.fi/
TEST https://test-webshop.apix.fi/
The webpage contains the webshop for browsing usage/purchase history and for purchasing additional Netstamps.
¶ 2.4 Check the sendprice
The application generates a REST-call PricingInfo to the Apix platform, which contains the sender y-tunnus, receiver y-tunnus, documenttype (invoic for invoices) and the number of pages in associated PDF-image. The call returns the cost in Netstamps for sending the documents. It is recommeded that if the current saldo exceeds the returned cost the numbers are displayed in green and if the the cost exceeds the saldo it is displayed in red and the 'Send' button is disabled until the amount of documents is changed or additional stamps purchased.
For invoicing model the call should be implemented to DeliveryMethod instead.
See External REST-API for details
¶ 2.5 Send
The application produces a batch containing:
- The invoice datafile (can be Finvoice, Teapps-XML, CSV etc.) which is agreed between Apix and the software company
- PDF-file for each invoice as the image of the invoice (used also when the document is delivered as a normal letter).
- OPTIONALLY: for each invoice a separate zip file containing related attachments
The invoice datafile should contain references to the PDFs and to the optional attachment zip.
The sending is initiated by making REST-call SendInvoiceZIP. The call returns the status details of the processing.
For identification the TransferID and TransferKey are used (gotten in step 1.3)
See External REST-API for details
¶ Receiving functionality
NOTE: Receiving functionality requires that the customer has signed as an customer for Apix and has also activated the 'Lähetä'-service.
The receiving service allows the receiving of invoices from senders that use eInvoicing (verkkolasku) and through scanning operator the invoices received as paper transmissions.
For utilizing the scanning operator services each 'Vastaanota' service user is allocated a postal address (with unique identification code) at scanning operator. This address is given when the user activates the 'Vastaanota' service. Invoices sent to that address are scanned, interpreted and move to the service as eInvoices.
For receiving eInvoices, an eT@G based eInvoicing address, with OVT-id as the technical key is established and addresses are published in the eT@G-network as well as in the Tieke eInvoice registry.
The invoices in the service are stored for a limited time depending on the service agreement. The invoices can be retrieved from the service using the ReceiveInvoiceZIP-API and if the invoices are not retrieved within predetermined timeperiod an email is sent to the contact person containing internet link and associated password.
The timeframe when the email (and the email-address) is sent can be set using SetReceiveEmail-API.
Invoices stored in the service can be listed by using ListInvoiceZIPs-API.
¶ 'Receive' button in invoice receiving
The functionality for receiving invoices is left to the discretion of the application developer. However it is strongly recommended that there is a 'Vastaanota'-button in the application that starts the receiving process.
| File | Modified | |
|---|---|---|
| PNG File Receive_arrow_grey_small.png | Sep 03, 2010 by Veli-Matti Sahlberg | |
| PNG File Receive_arrow_grey.png | Sep 03, 2010 by Veli-Matti Sahlberg | |
| PNG File Receive_arrow_green.png | Sep 03, 2010 by Veli-Matti Sahlberg | |
| PNG File Receive_arrow_green_small.png | Sep 03, 2010 by Veli-Matti Sahlberg |
