Overview
eReceipt solution APIs are protected (with some exceptions) and made available only to relevant taxpayer POS systems.
This API is used to authenticate the POS system calling and issue access token that allows POS system to access those protected APIs. Note that each token issued is issued for a certain time period configured as part of eReceipt solution, example can be found in expires_in. This means that compliant POS systems integrating with the solution should expect that some calls can start returning not authorized error codes (see more on standard error responses) that mean that most likely token has expired and needs to be renewed (by another login).
Note! Authentication of the systems is done on identity service, not on the service hosting actual integration APIs. Use the Identity Service base address when creating the full URL to be called.
Signature
As described in the Getting started overview, solution is leveraging externalized standards based identity system for managing users and also systems that are accessing solution user interfaces and also APIs.
Therefore solution leverages OAuth 2.0 client credentials flow for authenticating systems and granting them access token that allows then to call other APIs described in this SDK that requires authorization.
Signature:
POST /connect/token
Inputs
| Header parameter | Type | Description | Value example |
|---|---|---|---|
| posserial | String (100) | This is POS Serial Number | 1234567899 |
| pososversion | String (50) | This is POS Version Number | os |
| posmodelframework | String (10) | This is POS Model Framework Number | 1 |
| presharedkey | String (200) | This is POS Pre shared key | 03ac674216f3e1… |
| Body parameter | Type | Description | Value example |
|---|---|---|---|
| grant_type | String (20) | Must be “client_credentials” | client_credentials |
| client_id | String (100) | Specific client_id | d0394a9f-0607-40de-a978-2d3eb8375b04 |
| client_secret | String (100) | specific client_secret | 6d62315e-d65a-4e41-9112-4195ea834edf |
Outputs
Successful Response
API returns HTTP status code 200.
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| access_token | JWT token | Encoded JWT token structure that contains the fields of the issued token, token protection attributes and TAGs assigned to the taxpayer, so that the system can access B2B or B2C features or both | Encoded token value |
| token_type | String (6) | Solution in this case returns only Bearer authentication tokens | Bearer |
| expires_in | Number | The lifetime of the access token defined in seconds | 3600 (means it is valid for one hour) |
| scope | String (200) | Optional if matches the requested scope. Otherwise contains information on scope granted to token. This defines the APIs that client will have access to using this token. | InvoicingAPI |
Error Responses: 400 Bad Request
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| error | String | Possible values: unauthorized_client, invalid_posserial, invalid_pososversion, invalid_posmodelframework, invalid_presharedkey unauthorized_client, unsupported_grant_type, invalid_scope | invalid_request , invalid_clientsecret |
Additional Considerations
Each token already includes information about the taxpayer that the system is going to represent, therefore when doing API calls afterwards the taxpayer information is available also to relying party APIs.
System authentication can be rejected if invalid client ID and secret is used to authenticate or the system user registered against the taxpayer is blocked or expired.
Tokens issued as a result of the login operation are valid only for a pre-configured limited time. It is configured to be 1 hour.
Note: Your system should be responsible to obtain a new access token using this endpoint before the expiry of the current valid token to continue calling the APIs.
Note: Only Taxpayers assigned with B2C tag will be allowed to submit receipts.