Returns the associated company information associated by the user if user+password check validates.
PRODUCTION URL https://api.apix.fi/authuser?uid=<email>&t=<timestamp>&d=SHA-256:<digest>
TEST URL https://test-api.apix.fi/authuser?uid=<email>&t=<timestamp>&d=SHA-256:<digest>
HTTP Method:
GET
Authentication:
Yes. First SHA-256 digest is calculated from the user password. Then separate SHA-256 digest is calculated from all the parameters and digest version of password is used as the shared secret. The calculated digest is headed by string "SHA-256:".
See SHA-256 usage in APIX webservices API
Parameters:
| <email> | the userid in the form of email |
| <Timestamp> | the UTC time and date: CCYYMMDDHHMMSS |
| <digest> | SHA-256 digest, calculated from: email+timestamp+PasswordHash |
| PasswordHash | Sha-256 digest of the password. |
Request:
Only parameters
Response:
See Response message structure
| Value types: | Description |
|---|---|
| Ytunnus | Company's registered company id (Y-tunnus, Org.no) |
| Name | Company name |
| AdditionalName | Additional name |
| CustomerNumber | Internal customer number |
| UniqueCompanyID | Unique company id |
| Registered email | |
| Www | www-address |
| Phonenumber | Registered phone number |
| ContactPerson | Contact person's name |
| LanguageCoded | The culture i.e fi_FI, en_US, se_SE |
| IdCustomer | Internal customer id |
and for each addresstype found a group:
| AddressType | Official, Billing, Visiting |
| Street1 | Streetname |
| Street2 | Streetname |
| PostalOffice | Postal office |
| PostalCode | Postal code |
| Country | Country |
Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
<Status>OK</Status>
<StatusCode>5000</StatusCode>
<FreeText language="en">OK</FreeText>
<Content>
<Group>
<Value type="Ytunnus">2332748-7</Value>
<Value type="Name">Apix Messaging Oy</Value>
<Value type="CustomerNumber">1</Value>
<Value type="UniqueCompanyID">fdf09a47-5e99-4773-9379-3f26c8861eea</Value>
<Value type="Email">Veli-Matti.Sahlberg@apix.fi</Value>
<Value type="Www">www.apix.fi</Value>
<Value type="Phonenumber">+358453444401</Value>
<Value type="ContactPerson">Veli-Matti Sahlberg</Value>
<Value type="LanguageCoded">fi</Value>
</Group>
<Group>
<Value type="AddressType">Official</Value>
<Value type="Street1">Sinikalliontie 9</Value>
<Value type="PostalOffice">Espoo</Value>
<Value type="PostalCode">02630</Value>
<Value type="Country">Finland</Value>
</Group>
</Content>
</Response>
Retrieves the system generated TransferID,TransferKey and UniqueCompanyID. The application should store these internally.
PRODUCTION URL https://api.apix.fi/app-transferID?id=<company id>&idq=<id qualifier>&uid=<UserID>&ts=<timestamp>&d=SHA-256:<digest>
TEST URL https://test-api.apix.fi/app-transferID?id=<company id>&idq=<id qualifier>&uid=<UserID>&ts=<timestamp>&d=SHA-256:<digest>
HTTP Method:
GET
Authentication:
Yes. First SHA-256 digest is calculated from the user password. Then separate SHA-256 digest is calculated from all the parameters and digest version of password is used as the shared secret. The calculated digest is headed by string "SHA-256:".
See: SHA-256 usage in APIX webservices API
Parameters:
| <company id> | is the official id of the company (in Finland y-tunnus (www.ytj.fi), in Sweden Org.nr (http://www.bolagsverket.se) as used in the registration |
| <id qualifier> | qualifier for the identification; y-tunnus, orgnr etc. (usually y-tunnus) |
| <uid> | User ID for the user |
| <ts> | Current timestamp |
| <digest> | SHA-256 digest |
Response:
See Response message structure
| TransferID | The identification used for sending and receiving |
| TransferKey | The password used for sending and receiving |
| UniqueCompanyID | A unique identifier assigned to the company |
Example response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response version="1.0">
<Status>OK</Status>
<StatusCode>5000</StatusCode>
<FreeText language="en">OK</FreeText>
<Content>
<Group>
<Value type="TransferID">fdf09a47-5e99-4773-9379-3f26c8861eea</Value>
<Value type="TransferKey">de6b8d40-f81b-4d51-b977-c998510b51bb</Value>
<Value type="UniqueCompanyID">0f6aa87f-ce1d-44ce-b025-8b9801c8772c</Value>
</Group>
</Content>
</Response>
Retrieves infomation about the registered company; Username, saldos, unique id etc.
PRODUCTION URL https://api.apix.fi/getcompanyinfo?TraID=<TransferID>&t=<Timestamp>&d=SHA-256:<digest>
TEST URL https://test-api.apix.fi/getcompanyinfo?TraID=<TransferID>&t=<Timestamp>&d=SHA-256:<digest>
HTTP Method:
GET
Authentication:
Yes. Authentication with SHA-256 digest using the TransferKey as the 'shared secret'.
See SHA-256 usage in APIX webservices API
Parameters:
| TransferID | The TransferID identifying the owner of the storage |
| TimeStamp | In the format CCYYMMDDHHMMSS. All times are in UTC |
| Digest | The calculated SHA256 digest of the parameters and TransferKey (TRANSFERKEY) |
Response:
See Response message structure
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
<Status>OK</Status>
<StatusCode>5P00</StatusCode>
<Content>
<Group>
<Value type="Username">a@a.fi</Value>
<Value type="Email">a@a.fi</Value>
<Value type="UniqueID">oqyok-2euuq-1289200485-2gwzbf7fg</Value>
<Value type="TransferId">dfeaac7c-14f7-4983-acd3-afdaa7eb6b30</Value>
<Value type="TransferKey">51300348417</Value>
<Value type="y-tunnus">2066776-9</Value>
<Value type="Name">EsimerkkiFirma Oy</Value>
<Value type="Language">fi_FI</Value>
<Value type="AdditionalName">0</Value>
<Value type="WWW">www.aaaa.fi</Value>
<Value type="PhoneNumber">1234</Value>
<Value type="ContactPerson">Raija Tarkka</Value>
<Value type="EInvoiceAddress">003720667769</Value>
<Value type="Saldo">830.2 </Value>
</Group>
<Group>
<Value type="AddressType">Billing</Value>
<Value type="Street1">aaaa</Value>
<Value type="Street2">aaaa</Value>
<Value type="PostalOffice">aaaa</Value>
<Value type="PostalCode">3453</Value>
<Value type="Country">FI<Value>
</Group>
</Content>
</Response>
Allows sending of a ZIP-file containing one to several invoices (inhouse format) and their corresponding PDF-images (as single files) and optionally also attachments (as single zip-files) to the invoices.
Note: Usage of this service requires a valid contract of type 'Lähetä'.
PRODUCTION URL https://api.apix.fi/invoices?soft=<software>&ver=<version>&TraID=<TransferID>&t=<Timestamp>&d=SHA-256:<digest>
TEST URL https://test-api.apix.fi/invoices?soft=<software>&ver=<version>&TraID=<TransferID>&t=<Timestamp>&d=SHA-256:<digest>
HTTP Method:
PUT
Authentication:
Yes. Authentication with SHA-256 digest using the TransferKey as the 'shared secret'.
See SHA-256 usage in APIX webservices API
Parameters:
| <software> | the software used to generate the invoice inhouse. | NOTE: This is the "Interface" name agreed between Apix and the software company |
| <version> | the version of the software used to generate the invoice inhouse. | NOTE: This is the "Interface" version agreed between Apix and the software company |
| <TransferID> | the unique TransferID assigned to the customer | |
| <Timestamp> | the UTC time and date: CCYYMMDDHHMMSS | |
| <digest> | SHA-256 digest |
Response:
See Response message structure.
| BatchID | A unique identifier assigned to a batch of documents |
| Saldo | an integer representing the current credit saldo |
| CostInCredits | Total cost of processing in credits |
| NetworkedInvoices | number of Networked einvoices in request/response |
| Letters | number of letters in request/response |
| LetterPages | number of pages of letters in request/response |
| RejectedDocument | number of rejected documents (invoices) |
| AcceptedDocument | number of accepted documents (invoices) |
In addition there can be detailed information about the RejectedDocuments or AcceptedDocuments (one group / document) as follows:
| RejectedDocumentID | Either document number or position inside the invoice data file |
| ValidateText | Text describing reason for rejection (in english) |
| ValidateText:fi | Optional: Text describing reason for rejection (in finnish) |
| ValidateText:sv | Optional: Text describing reason for rejection (in swedish) |
| AcceptedDocumentID | Document number |
| ValidateText | Additional information about the document processing (in english) |
| ValidateText:fi | Optional: Additional information about the document processing (in finnish) |
| ValidateText:sv | Optional: Additional information about the document processing (in swedish) |
HTTP Request
PUT /invoices?soft=Economix&ver=1.0&TraID=e4fb42c4-2e72-4e8c-80aa-3724e402c0a8&t=20100605123412&d=SHA-256:398217e7a83e4e88fcc839b4566f7c897a1f8f09dffc8479513ffe26c6a3fb1a
HTTP/1.1
Content-Type: application/octet-stream
Content-Length: <length in bytes>
[The zip file as binary, containing datafile, image-pdf/invoice, attachment-zip/invoice]Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response version="1.0">
<Status>OK</Status>
<StatusCode>1000</StatusCode>
<FreeText language="en">OK</FreeText>
<Content>
<Group>
<Value type="BatchID">1633b003-0315-44ca-a687-a25f92bf6123</Value>
<Value type="Saldo">199</Value>
<Value type="CostInCredits">1</Value>
<Value type="NetworkedInvoices">1</Value>
<Value type="Letters">0</Value>
<Value type="LetterPages">0</Value>
<Value type="AcceptedDocument">1</Value>
</Group>
<Group>
<Value type="AcceptedDocumentID">1001</Value>
<Value type="ValidateText">Document InvoiceID 1001 Warning:BuyerOganisationTaxCode is missing</Value>
</Group>
</Content>
</Response>
Returns the delivery channel and price for individual documents for b2b messages. Contact us if you need the same kind of functionality for b2c messages.
Note Preferred way is to use DeliveryMethod instead of PricingInfo
PRODUCTION URL https://api.apix.fi/method?uid=<TransferID>&t=<timestamp>&d=SHA-256:<digest>
TEST URL https://test-api.apix.fi/method?uid=<TransferID>&t=<timestamp>&d=SHA-256:<digest>
HTTP Method:
PUT
Authentication:
Yes. Authentication with SHA-256 hash (<SHA-256:digest>) using the TransferKey as the 'shared secret'.
See SHA-256 usage in APIX webservices API
Parameters:
| <TransferID> | the unique TransferID assigned to the customer |
| <Timestamp> | the UTC time and date: CCYYMMDDHHMMSS |
| <digest> | SHA-256 digest |
Request:
See Request message structure
| DocumentID | Optional: Document identifier at sender |
| SenderName | Sender's official name |
| SenderYtunnus | Sender's official id of the company (in Finland y-tunnus (www.ytj.fi), in Sweden Org.nr (http://www.bolagsverket.se) |
| ReceiverName | Receiver's official name |
| ReceiverCountryCode | Optional: Receiver's country code, ISO 3166-1, default FI |
| ReceiverYtunnus | Optional: Receiver's BusinessID (ie. the official id) |
| ReceiverOVT | Optional: Receiver's OVT-id (any enchanced party identifier) |
| ReceivereInvoiceAddress | Optional: Receiver's eInvoiceAddress, eT@G or other specific electronic address |
| MessageType | Optional: Messagetype used (eInvoice,invoic,orders etc.) Default: eInvoice |
| LetterPages | Optional: Number of pages in letter |
Response:
See Response message structure
| Value types: | |
|---|---|
| DocumentID | Optional: Document identifier at sender |
| ChannelName | Delivery channel: "eInvoice","Paper","email","EDI","Netpost","e-lasku","Suoramaksu" |
| SenderName | Sender's official name |
| SenderYtunnus | Sender's BusinessID (ie. the official registered id) |
| ReceiverName | Receiver's official name |
| CostInCredits | The cost of delivery in credits |
| ReceiverYtunnus | Optional: Only for EINVOICE, EDI: Receiver's BusinessID |
| MessageType | Messagetype used (eInvoice,invoic,orders etc.) Default: eInvoice |
| LetterPages | Optional (only for Print channel):Number of pages in letter |
| LetterClass | Optional (only for Print channel):The letter class requested. '1' or '2'. Default 2 |
| LetterPrintColor | Optional (only for Print channel):If the letter should be printed in color or bw. COLOR/BW. Default BW |
| LetterCountry | Optional (only for Print channel):Countryclass where the letter is going. FI/EU/OTHER. Default FI |
Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Request version="1.0">
<Content>
<Group>
<Value type="DocumentID">1</Value>
<Value type="SenderName">Apix Messaging Oy</Value>
<Value type="SenderYtunnus">2332748-7</Value>
<Value type="ReceiverName">Big Company Oy</Value>
<Value type="LetterPages">12</Value>
<Value type="ReceiverCountryCode">FI</Value>
</Group>
<Group>
<Value type="DocumentID">2</Value>
<Value type="SenderName">Apix Messaging Oy</Value>
<Value type="SenderYtunnus">2332748-7</Value>
<Value type="ReceiverName">Wrong name</Value>
<Value type="ReceiverYtunnus">2332748-7</Value>
</Group>
<Group>
<Value type="DocumentID">3</Value>
<Value type="SenderName">Apix Messaging Oy</Value>
<Value type="SenderYtunnus">2332748-7</Value>
<Value type="ReceiverName">Wrong name</Value>
<Value type="ReceivereInvoiceAddress">FI3080000710163802</Value>
</Group>
<Group>
<Value type="DocumentID">3</Value>
<Value type="SenderName">Apix Messaging Oy</Value>
<Value type="SenderYtunnus">2332748-7</Value>
<Value type="ReceiverName">Wrong name</Value>
<Value type="ReceiverOVT">003723327487</Value>
</Group>
<Group>
<Value type="SenderName">Apix Messaging Oy</Value>
<Value type="SenderYtunnus">2332748-7</Value>
<Value type="ReceiverName">Apix Messaging Oy</Value>
</Group>
</Content>
</Request>Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
<Status>OK</Status>
<StatusCode>7G00</StatusCode>
<Content>
<Group>
<Value type="DocumentID">1</Value>
<Value type="LetterClass">1</Value>
<Value type="CostInCredits">2.75</Value>
<Value type="LetterPages">12</Value>
<Value type="AccountingCopy">YES</Value>
<Value type="SenderYtunnus">2332748-7</Value>
<Value type="LetterCountry">FI</Value>
<Value type="ChannelName">Paper</Value>
<Value type="LetterPrintColor">BW</Value>
<Value type="SenderName">Apix Messaging Oy</Value>
<Value type="ReceiverName">Big Company Oy</Value>
</Group>
<Group>
<Value type="DocumentID">2</Value>
<Value type="ReceiverYtunnus">2332748-7</Value>
<Value type="AccountingCopy">YES</Value>
<Value type="SenderYtunnus">2332748-7</Value>
<Value type="ChannelName">eInvoice</Value>
<Value type="SenderName">Apix Messaging Oy</Value>
<Value type="ReceiverName">Wrong name</Value>
</Group>
<Group>
<Value type="DocumentID">3</Value>
<Value type="ReceiverYtunnus">2332748-7</Value>
<Value type="AccountingCopy">YES</Value>
<Value type="SenderYtunnus">2332748-7</Value>
<Value type="ChannelName">eInvoice</Value>
<Value type="SenderName">Apix Messaging Oy</Value>
<Value type="ReceiverName">Wrong name</Value>
</Group>
<Group>
<Value type="DocumentID">3</Value>
<Value type="ReceiverYtunnus">2332748-7</Value>
<Value type="AccountingCopy">YES</Value>
<Value type="SenderYtunnus">2332748-7</Value>
<Value type="ChannelName">eInvoice</Value>
<Value type="SenderName">Apix Messaging Oy</Value>
<Value type="ReceiverName">Wrong name</Value>
</Group>
<Group>
<Value type="ReceiverYtunnus">2332748-7</Value>
<Value type="AccountingCopy">YES</Value>
<Value type="SenderYtunnus">2332748-7</Value>
<Value type="ChannelName">eInvoice</Value>
<Value type="SenderName">Apix Messaging Oy</Value>
<Value type="ReceiverName">Apix Messaging Oy</Value>
</Group>
</Content>
</Response>
Returns all of the einvoice addresses and operators for given company name and / or businessId.
PRODUCTION URL https://api.apix.fi/addressquery?uid=<TransferID>&t=<timestamp>&d=SHA-256:<digest>
TEST URL https://test-api.apix.fi/addressquery?uid=<TransferID>&t=<timestamp>&d=SHA-256:<digest>
HTTP Method:
PUT
Authentication:
Yes. Authentication with SHA-256 hash (<SHA-256:digest>) using the TransferKey as the 'shared secret'.
See SHA-256 usage in APIX webservices API
Parameters:
| <TransferID> | the unique TransferID assigned to the customer |
| <Timestamp> | the UTC time and date: CCYYMMDDHHMMSS |
| <digest> | SHA-256 digest |
Request:
See Request message structure
| ReceiverName | Receiver's official name, either this or receiver's business id must be defined. Recommended that you don't use this but use only ReceiverYtunnus instead. |
| ReceiverYtunnus | Receiver's BusinessID, either this or receiver's official name must be defined. |
Response:
See Response message structure
| Value types: | |
|---|---|
| ReceiverName | Returned if provided in request or found |
| ReceiverYtunnus | Returned if provided in request or found. |
| ReceivereInvoiceAddress | EInvoice address of receiver, returned if found |
| ReceiverOperator | Operator of this EInvoiceAddress, returned if found |
Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Request version="1.0">
<Content>
<Group>
<Value type="ReceiverName">Aalto Capital Oy</Value>
<Value type="ReceiverYtunnus">2262882-7</Value>
</Group>
</Content>
</Request>Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
<Status>OK</Status>
<StatusCode>2A00</StatusCode>
<Content>
<Group>
<Value type="ReceiverName">Aalto Capital Oy</Value>
<Value type="ReceiverYtunnus">2262882-7</Value>
<Value type="ReceivereInvoiceAddress">003722628827</Value>
<Value type="ReceiverOperator">Itella Information Oy</Value>
</Group>
<Group>
<Value type="ReceiverName">Aalto Capital Oy</Value>
<Value type="ReceiverYtunnus">2262882-7</Value>
<Value type="ReceivereInvoiceAddress">FI0913783000220315</Value>
<Value type="ReceiverOperator">Nordea</Value>
</Group>
</Content>
</Response>
Allows sending of a ZIP-file containing one to several documents in PDF format accompanied with an XML-metadata file. The letters are sent as defined in the agreements (customer settable options in the Apix management www-appliaction).
Note: Usage of this service requires a valid contract of type 'Lähetä'.
PRODUCTION URL https://api.apix.fi/print?soft=<software>&ver=<version>&TraID=<TransferID>&t=<Timestamp>&d=SHA-256:<digest>
TEST URL https://test-api.apix.fi/print?soft=<software>&ver=<version>&TraID=<TransferID>&t=<Timestamp>&d=SHA-256:<digest>
HTTP Method:
PUT
Authentication:
Yes. Authentication with SHA-256 digest using the TransferKey as the 'shared secret'.
See SHA-256 usage in APIX webservices API
Parameters:
| <software> | the software used to generate the invoice inhouse. | NOTE: This is the "Interface" name agreed between Apix and the software company |
| <version> | the version of the software used to generate the invoice inhouse. | NOTE: This is the "Interface" version agreed between Apix and the software company |
| <TransferID> | the unique TransferID assigned to the customer | |
| <Timestamp> | the UTC time and date: CCYYMMDDHHMMSS | |
| <digest> | SHA-256 digest |
Response:
See Response message structure.
| BatchID | A unique identifier assigned to a batch of documents |
| Saldo | an integer representing the current credit saldo |
| CostInCredits | Total cost of processing in credits |
| NetworkedInvoices | number of letters sent to Netposti |
| Letters | number of letters in request/response |
| LetterPages | number of pages of letters in request/response |
| RejectedDocument | number of rejected documents (invoices) |
| AcceptedDocument | number of accepted documents (invoices) |
In addition there can be detailed information about the RejectedDocuments or AcceptedDocuments (one group / document) as follows:
| RejectedDocumentID | Either document number or position inside the invoice data file |
| ValidateText | Text describing reason for rejection (in english) |
| ValidateText:fi | Optional: Text describing reason for rejection (in finnish) |
| ValidateText:sv | Optional: Text describing reason for rejection (in swedish) |
| AcceptedDocumentID | Document number |
| ValidateText | Additional information about the document processing (in english) |
| ValidateText:fi | Optional: Additional information about the document processing (in finnish) |
| ValidateText:sv | Optional: Additional information about the document processing (in swedish) |
Metadata:
Schema file Letters2.xsd
<?xml version="1.0" encoding="UTF-8"?>
<Letter Version="1.0">
<DocumentID>_UNIQUEID_FOR_DOCUMENT_</DocumentID>
<SenderPartyDetails>
<SenderPartyIdentifier>_BUSINESSID_</SenderPartyIdentifier>
<SenderOrganisationName>_NAME_</SenderOrganisationName>
<SenderOrganisationName>_NAME2_</SenderOrganisationName>
<SenderPostalAddressDetails>
<SenderStreetName>_STREETNAME1_</SenderStreetName>
<SenderStreetName>_STREETNAME2_</SenderStreetName>
<SenderTownName>_CITY_</SenderTownName>
<SenderPostCodeIdentifier>_POSTALCODE_</SenderPostCodeIdentifier>
<CountryCode>_COUNTRYCODE_ISO3361</CountryCode>
</SenderPostalAddressDetails>
</SenderPartyDetails>
<DeliveryPartyDetails>
<DeliveryPartyIdentifier>_IDENTIFIER_FOR_RECIPIENT_</DeliveryPartyIdentifier>
<DeliveryOrganisationName>_NAME_</DeliveryOrganisationName>
<DeliveryOrganisationName>_NAME2_</DeliveryOrganisationName>
<DeliveryPostalAddressDetails>
<DeliveryStreetName>_STREETNAME1_</DeliveryStreetName>
<DeliveryStreetName>_STREETNAME2_</DeliveryStreetName>
<DeliveryTownName>_CITY_</DeliveryTownName>
<DeliveryPostCodeIdentifier>_POSTALCODE_</DeliveryPostCodeIdentifier>
<CountryCode>_COUNTRYCODE_ISO3361_</CountryCode>
</DeliveryPostalAddressDetails>
</DeliveryPartyDetails>
<InvoiceUrlNameText>APIX_PDFFILE</InvoiceUrlNameText>
<InvoiceUrlText>file://_DOCUMENT_0.pdf</InvoiceUrlText>
</Letter>HTTP Request
PUT /print?soft=Standard&ver=1.0&TraID=e4fb42c4-2e72-4e8c-80aa-3724e402c0a8&t=20100605123412&d=SHA-256:398217e7a83e4e88fcc839b4566f7c897a1f8f09dffc8479513ffe26c6a3fb1a
HTTP/1.1
Content-Type: application/octet-stream
Content-Length: <length in bytes>
[The zip file as binary, containing datafile, image-pdf/invoice, attachment-zip/invoice]Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response version="1.0">
<Status>OK</Status>
<StatusCode>1000</StatusCode>
<FreeText language="en">OK</FreeText>
<Content>
<Group>
<Value type="BatchID">1633b003-0315-44ca-a687-a25f92bf6123</Value>
<Value type="Saldo">199</Value>
<Value type="CostInCredits">1</Value>
<Value type="NetworkedInvoices">0</Value>
<Value type="Letters">1</Value>
<Value type="LetterPages">2</Value>
<Value type="AcceptedDocument">1</Value>
</Group>
<Group>
<Value type="AcceptedDocumentID">1001</Value>
<Value type="ValidateText">Document InvoiceID OK</Value>
</Group>
</Content>
</Response>
Sends a payslip for delivery.
Apix expects to get a ZIP-file with exactly one XML file and at least 1 PDF (the image of the payslip). It is possible to include other pdf files as attachments. XML must contain a reference to all the pdf files. XML is described at https://www.tieke.fi/display/verkkopalkka/PayslipXML_v.2.0. To send other formats, please contact Apix to agree on details.
Note: Usage of this service requires a valid contract of type 'Lähetä'.
PRODUCTION URL https://api.apix.fi/sendpayslip?TraID=<TransferID>&t=<Timestamp>&d=SHA-256:<digest>
TEST URL https://test-api.apix.fi/sendpayslip?TraID=<TransferID>&t=<Timestamp>&d=SHA-256:<digest>
HTTP Method:
PUT
Authentication:
Yes. Authentication with SHA-256 digest using the TransferKey as the 'shared secret'.
See SHA-256 usage in APIX webservices API
Parameters:
| <TransferID> | the unique TransferID assigned to the customer | |
| <Timestamp> | the UTC time and date: CCYYMMDDHHMMSS | |
| <digest> | SHA-256 digest |
Response:
See Response message structure.
| BatchID | A unique identifier assigned to a batch of documents |
| Saldo | an integer representing the current credit saldo |
| CostInCredits | Total cost of processing in credits |
| NetworkedPayslips | number of letters sent electronically |
| Letters | number of letters in request/response |
| LetterPages | number of pages of letters in request/response |
| RejectedDocument | number of rejected documents (invoices) |
| AcceptedDocument | number of accepted documents (invoices) |
In addition there can be detailed information about the RejectedDocuments or AcceptedDocuments (one group / document) as follows:
| RejectedDocumentID | Either document number or position inside the invoice data file |
| ValidateText | Text describing reason for rejection (in english) |
| ValidateText:fi | Optional: Text describing reason for rejection (in finnish) |
| ValidateText:sv | Optional: Text describing reason for rejection (in swedish) |
Received invoices are kept available for download for 3 calendar months.
Note: Usage of this service requires a valid contract of type 'Vastaanota'.
Allows listing of incoming invoices in the service.
The service will return list of invoices and the "fetch status" of incoming invoices for current and previous month.
Information for up to 500 invoices are returned, those already marked to be received are dropped first if more than 500 are found.
PRODUCTION URL https://terminal.apix.fi/list2?TraID=<TransferID>&t=<Timestamp>&d=SHA-256:<digest>
TEST URL https://test-terminal.apix.fi/list2?TraID=<TransferID>&t=<Timestamp>&d=SHA-256:<digest>
HTTP Method:
GET
Authentication:
Yes. Authentication with SHA-256 digest using the TransferKey as the 'shared secret'.
See SHA-256 usage in APIX webservices API
Parameters:
| TransferID | The TransferID identifying the owner of the storage |
| TimeStamp | In the format CCYYMMDDHHMMSS. All times are in UTC |
| Digest | The calculated SHA256 digest of the parameters and TransferKey (TRANSFERKEY) |
Response:
See Response message structure
| Value types: | |
|---|---|
| StorageId | Id of the storage |
| Status | Received or Unreceived |
List2 StorageStatus/Transferstatus explanation
| StorageStatus | TransferStatus | Explanation |
|---|---|---|
| NEW | Still being created, do not fetch | |
| UNRECEIVED | NEW | Ready to be fetched |
| RECEIVED | RETRIEVED | Fetched at least once |
| DELETED | Scheduled to be removed |
HTTP Request
GET /list2?TraID=e4fb42c4-2e72-4e8c-80aa-3724e402c0a8&t=20100605123412&d=SHA-256:398217e7a83e4e88fcc839b4566f7c897a1f8f09dffc8479513ffe26c6a3fb1aResponse
<Response>
<Status>OK</Status>
<StatusCode>2700</StatusCode>
<Content>
<Group>
<Value type="DocumentID">1371</Value>
<Value type="DueDate">20150401</Value>
<Value type="SellerReference">N/A</Value>
<Value type="SenderVAT">104351234-6</Value>
<Value type="DocumentDate">20150322</Value>
<Value type="PaymentStatus">NOTPAID</Value>
<Value type="PaymentReference">1180050173</Value>
<Value type="SenderName">Testi Ohjelmat Oy</Value>
<Value type="TransferStatus">NEW</Value>
<Value type="ReceiverVAT">N/A</Value>
<Value type="DocumentName">invoice.xml</Value>
<Value type="ImageName">Lasku 1183.pdf</Value>
<Value type="AmountToPay">122.88</Value>
<Value type="ReceiverId">123451-2</Value>
<Value type="CreatedDate">20150323</Value>
<Value type="ApprovalStatus">NEUTRAL</Value>
<Value type="BankAccount">FI8529501800020574</Value>
<Value type="OrderReference">N/A</Value>
<Value type="Currency">EUR</Value>
<Value type="ReceiverName">Test Receiver</Value>
<Value type="StorageKey">185629244874</Value>
<Value type="StorageID">51974e79-feef-adsaf-b543-43adsf0fca</Value>
<Value type="StorageStatus">UNRECEIVED</Value>
<Value type="DocumentOrigin">eInvoice</Value>
</Group>
</Content>
</Response>
Note: Usage of this service requires a valid contract of type 'Vastaanota'.
Sets the email-address for sending the received invoices.
PRODUCTION URL https://api.apix.fi/email?uid=<TransferID>&t=<timestamp>&d=SHA-256:<digest>
TEST URL https://test-api.apix.fi/email?uid=<TransferID>&t=<timestamp>&d=SHA-256:<digest>
HTTP Method:
PUT
Authentication:
Yes. Authentication with SHA-256 hash (<SHA-256:digest>) using the TransferKey as the 'shared secret'.
See SHA-256 usage in APIX webservices API
Parameters:
| <TransferID> | the unique TransferID assigned to the customer |
| <Timestamp> | the UTC time and date: CCYYMMDDHHMMSS |
| <digest> | SHA-256 digest |
Request:
See Request message structure
| Valid email address for receiving the invoices. If empty - the default address given at registration time is used | |
| DaysBeforeEmail | 0-5. Where 0 means; do not send email (DEFAULT) and 1 means the same day, 2 next day and so on. |
Response:
See Response message structure
| Value types: | |
|---|---|
| PreviousEmail | The email used before the call |
Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Request version="1.0">
<Content>
<Group>
<Value type="Email">servicedesk@apix.fi</Value>
<Value type="DaysBeforeEmail">0</Value>
</Group>
</Content>
</Request>Response
<Response>
<Status>OK</Status>
<StatusCode>5000</StatusCode>
<FreeText language="en">OK</FreeText>
<Content>
<Group>
<Value type="PreviousEmail">invoicing@apix.fi</Value>
</Group>
</Content>
</Response>
| AUTHENTICATION for Download is through StorageID and StorageKEY. |
Retrieves the requested files from the storage. The return value is the contents of the file.
URL: https://terminal.apix.fi/download?SID=<StorageID>&t=TimeStamp&d=SHA-256:<Digest>
URL TEST: https://test-terminal.apix.fi/download?SID=<StorageID>&t=TimeStamp&d=SHA-256:<Digest>
HTTP Method:
GET
Returns contents of the whole storage with attachments.
Authentication:
Yes. The separate SHA-256 digest is calculated from all the parameters and addition with the StorageKey as the shared secret. The calculated digest is headed by string "SHA-256:".
Digest is calculated from: (MarkReceived+) StorageID+TimeStamp+StorageKey
Parameters:
| MarkReceived |
Optional parameter. Using this the storage status is marked as 'Received' when downloaded. Valid values are: 'markreceived=yes' and 'markreceived=no'. If this is not used and get request is done to receive whole storage, it is marked as received. |
| StorageID | The storageid to download the file from |
| TimeStamp | In the format CCYYMMDDHHMMSS. All times are in UTC |
| Digest | The calculated SHA256 digest of the parameters and storagekey (KEY) |
Response:
The requested file as payload in HTTP response body.
or in case of error (Wrong key, or storageid) nothing. Other errors returned at HTTP-response level.
Returns all stored metadata for given storage and all the files stored inside it.
URL https://terminal.apix.fi/metadata?TraID=<TransferID>&SID=<StorageID>&t=<Timestamp>&d=SHA-256:<digest>
URL TEST https://test-terminal.apix.fi/metadata?TraID=<TransferID>&SID=<StorageID>&t=<Timestamp>&d=SHA-256:<digest>
HTTP Method:
GET
Authentication:
Yes. The separate SHA-256 digest is calculated from all the parameters and addition with the TransferKey password as the shared secret. The calculated digest is headed by string "SHA-256:". Digest is calculated from: StorageID+TransferID+Timestamp+TransferKey
Parameters:
| TransferID | The TransferID identifying the owner of the storage |
| StorageID | The storageid to lock the file in |
| TimeStamp | In the format CCYYMMDDHHMMSS. All times are in UTC |
| Digest | The calculated SHA256 digest of the parameters and TransferKey (TRANSFERKEY) |
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
<Status>OK</Status>
<StatusCode>2A00</StatusCode>
<Content>
<Group>
<Value type="email">uusi-email</Value>
<Value type="saaaa">tämän jotain ylimääräinen informaatiota</Value>
</Group>
<Group>
<Value type="FileName">Lasku 1196.pdf</Value>
<Value type="email">tannelahtee@apix.fi</Value>
</Group>
</Content>
</Response>
Retrieves the company's current credit saldo (amount of netstamps)
PRODUCTION URL https://api.apix.fi/saldo?id=<company-unique-id>
TEST URL https://test-api.apix.fi/saldo?id=<company-unique-id>
HTTP Method:
GET
Authentication:
No.
Parameters:
| <company-unique-id> | the system assigned unique-id for the company. |
Response:
See Response message structure.
| Value types: | |
|---|---|
| Saldo | a decimal representing the current credit saldo |
Example:
<Response>
<Status>OK</Status>
<StatusCode>5000</StatusCode>
<FreeText language="en">OK</FreeText>
<Content>
<Group>
<Value type="Saldo">200</Value>
</Group>
</Content>
</Response>
Delete requested payslip
URL https://terminal.apix.fi/senderpayslip?TraID=<TransferID>&t=TimeStamp&hash=<ReceiverHash>&date=<DateID>&D=SHA-256:<Digest>
HTTP Method:
DELETE
Authentication:
Yes. The separate SHA-256 digest is calculated from all the parameters and addition with the TransferKey as the shared secret. The calculated digest is headed by string "SHA-256:".
Parameters:
| TraID | User transfer ID |
| TimeStamp | In the format CCYYMMDDHHMMSS. All times are in UTC |
| ReceiverHash | MD5 hex value of person id |
| DateID | Payslip date in the format of YYYYMMDD and payslip ID separated with "-" example: 20200515-7645849 |
| Digest | The calculated SHA256 digest of the parameters and transferKey (TraID+ReceiverHash+DateID+TimeStamp+Tkey) |
Response on successful delete:
<Response>
<Status>OK</Status>
<StatusCode>7PS00</StatusCode>
<Content>
<Group>
<Value type="StorageQuota">9999999</Value>
</Group>
</Content>
</Response>