Overview
eInvoicing and eReceipt solution APIs are protected (with some exceptions) and made available only to relevant taxpayer representatives, their ERP systems.
This API is used to authenticate the ERP system calling and issue access token that allows ERP system to access those protected APIs. Note that each token issued is issued for a certain time period configured as part of eInvoicing solution, example can be found in expires_in. This means that compliant ERP 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 |
|---|---|---|---|
| Authorization | String | Must contain basic authorization string created using issued Client ID and Client Secret for the ERP system. The process of creating basic authorization string should follow RFC 2617 | Basic <Base64 encoded value> |
Login as intermediary
if you are trying to login as intermediary then you need to add an extra header parameter to your request, this header parameter that will be mapped to the taxpayer that you are trying to login on his behalf.
Note:
Note! when you login as intermediary, permissions that are granted by the taxpayer will be applied on your profile and this will control the functionalities that you'll be able to executed on behalf of the taxpayer you are representing.
| Header parameter | Type | Description | Value example |
|---|---|---|---|
| onbehalfof | String | Registration number. For business in Egypt must be registration number | 100015840 |
| Body parameter | Type | Description | Value example |
|---|---|---|---|
| grant_type | String | Must be “client_credentials” | client_credentials |
| scope | String | Optional parameter asking for a specific access scope. In case of external access to eInvoicing APIs this parameter can be omitted | InvoicingAPI |
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 | 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 | 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: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope | invalid_request |
| error_description | String | Optional human readable error message containing more details about error encountered. | User blocked |
| error_uri | URI | Optional URI containing more information about the error. Not uses in eInvoicing solution |
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.