Search results for ��SDK

# Introduction Welcome to the Passbase Verifications API docs. This documentation will help you understand our models and the Verification API with its endpoints. Based on this you can build your own system (i.e. verification) and hook it up to Passbase. In case of feedback or questions you can reach us under this email address: [[email protected]](mailto:[email protected]). A User submits a video selfie and valid identifying __Resources__ during a __Verification__ guided by the Passbase client-side integration. Once all the necessary __Resources__ are submitted, __Data points__ are extracted, digitized, and authenticated. These Data points then becomes part of the User's __Identity__. The User then consents to share __Resources__ and/or __Data points__ from their Identity with you. This information is passed to you and can be used to make decisions about a User (e.g. activate account). This table below explains our terminology further. | Term | Description | |-----------------------------------------|-------------| | [Identity](#tag/identity_model) | A set of Data points and Resources related to and owned by one single User. This data can be accessed by you through a Verification. | | Data points | Any data about a User extracted from a Resource (E.g. Passport Number, or Age). | | [Resource](#tag/resource_model) | A source document used to generate the Data points for a User (E.g. Passport). | | [User](#tag/user_model) | The owner of an email address associated with an Identity. | | Verification | A transaction through which a User consents to share Data points with you. If the Data points you request are not already available in the User's Identity, the Passbase client will ask the User to submit the necessary Resource required to extract them. | | Re-authentication (login) | A transaction through which a User can certify the ownership of Personal data previously shared through an Authentication. | # Authentication There are two forms of authentication for the API: • API Key • Bearer JWT Token

Go to Download

RESTful API for Account Information Services (AIS) and Payment Initiation Services (PIS) Application Version: 2.29.4 The following pages give you some general information on how to use our APIs. The actual API services documentation then follows further below. You can use the menu to jump between API sections. This page has a built-in HTTP(S) client, so you can test the services directly from within this page, by filling in the request parameters and/or body in the respective services, and then hitting the TRY button. Note that you need to be authorized to make a successful API call. To authorize, refer to the 'Authorization' section of the API, or just use the OAUTH button that can be found near the TRY button. General information Error Responses When an API call returns with an error, then in general it has the structure shown in the following example: { "errors": [ { "message": "Interface 'FINTS_SERVER' is not supported for this operation.", "code": "BAD_REQUEST", "type": "TECHNICAL" } ], "date": "2020-11-19T16:54:06.854+01:00", "requestId": "selfgen-312042e7-df55-47e4-bffd-956a68ef37b5", "endpoint": "POST /api/v2/bankConnections/import", "authContext": "1/21", "bank": "DEMO0002 - finAPI Test Redirect Bank (id: 280002, location: none)" } If an API call requires an additional authentication by the user, HTTP code 510 is returned and the error response contains the additional "multiStepAuthentication" object, see the following example: { "errors": [ { "message": "Es ist eine zusätzliche Authentifizierung erforderlich. Bitte geben Sie folgenden Code an: 123456", "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "678b13f4be9ed7d981a840af8131223a", "status": "CHALLENGE_RESPONSE_REQUIRED", "challengeMessage": "Es ist eine zusätzliche Authentifizierung erforderlich. Bitte geben Sie folgenden Code an: 123456", "answerFieldLabel": "TAN", "redirectUrl": null, "redirectContext": null, "redirectContextField": null, "twoStepProcedures": null, "photoTanMimeType": null, "photoTanData": null, "opticalData": null, "opticalDataAsReinerSct": false } } ], "date": "2019-11-29T09:51:55.931+01:00", "requestId": "selfgen-45059c99-1b14-4df7-9bd3-9d5f126df294", "endpoint": "POST /api/v2/bankConnections/import", "authContext": "1/18", "bank": "DEMO0001 - finAPI Test Bank" } An exception to this error format are API authentication errors, where the following structure is returned: { "error": "invalid_token", "error_description": "Invalid access token: cccbce46-xxxx-xxxx-xxxx-xxxxxxxxxx" } Paging API services that may potentially return a lot of data implement paging. They return a limited number of entries within a "page". Further entries must be fetched with subsequent calls. Any API service that implements paging provides the following input parameters: • "page": the number of the page to be retrieved (starting with 1). • "perPage": the number of entries within a page. The default and maximum value is stated in the documentation of the respective services. A paged response contains an additional "paging" object with the following structure: { ... , "paging": { "page": 1, "perPage": 20, "pageCount": 234, "totalCount": 4662 } } Internationalization The finAPI services support internationalization which means you can define the language you prefer for API service responses. The following languages are available: German, English, Czech, Slovak. The preferred language can be defined by providing the official HTTP Accept-Language header. finAPI reacts on the official iso language codes "de", "en", "cs" and "sk" for the named languages. Additional subtags supported by the Accept-Language header may be provided, e.g. "en-US", but are ignored. If no Accept-Language header is given, German is used as the default language. Exceptions: • Bank login hints and login fields are only available in the language of the bank and not being translated. • Direct messages from the bank systems typically returned as BUSINESS errors will not be translated. • BUSINESS errors created by finAPI directly are available in German and English. • TECHNICAL errors messages meant for developers are mostly in English, but also may be translated. Request IDs With any API call, you can pass a request ID via a header with name "X-Request-Id". The request ID can be an arbitrary string with up to 255 characters. Passing a longer string will result in an error. If you don't pass a request ID for a call, finAPI will generate a random ID internally. The request ID is always returned back in the response of a service, as a header with name "X-Request-Id". We highly recommend to always pass a (preferably unique) request ID, and include it into your client application logs whenever you make a request or receive a response (especially in the case of an error response). finAPI is also logging request IDs on its end. Having a request ID can help the finAPI support team to work more efficiently and solve tickets faster. Overriding HTTP methods Some HTTP clients do not support the HTTP methods PATCH or DELETE. If you are using such a client in your application, you can use a POST request instead with a special HTTP header indicating the originally intended HTTP method. The header's name is X-HTTP-Method-Override. Set its value to either PATCH or DELETE. POST Requests having this header set will be treated either as PATCH or DELETE by the finAPI servers. Example: X-HTTP-Method-Override: PATCH POST /api/v2/label/51 {"name": "changed label"} will be interpreted by finAPI as: PATCH /api/v2/label/51 {"name": "changed label"} User metadata With the migration to PSD2 APIs, a new term called "User metadata" (also known as "PSU metadata") has been introduced to the API. This user metadata aims to inform the banking API if there was a real end-user behind an HTTP request or if the request was triggered by a system (e.g. by an automatic batch update). In the latter case, the bank may apply some restrictions such as limiting the number of HTTP requests for a single consent. Also, some operations may be forbidden entirely by the banking API. For example, some banks do not allow issuing a new consent without the end-user being involved. Therefore, it is certainly necessary and obligatory for the customer to provide the PSU metadata for such operations. As finAPI does not have direct interaction with the end-user, it is the client application's responsibility to provide all the necessary information about the end-user. This must be done by sending additional headers with every request triggered on behalf of the end-user. At the moment, the following headers are supported by the API: • "PSU-IP-Address" - the IP address of the user's device. It has to be an IPv4 address, as some banks cannot work with IPv6 addresses. If a non-IPv4 address is passed, we will replace the value with our own IPv4 address as a fallback. • "PSU-Device-OS" - the user's device and/or operating system identification. • "PSU-User-Agent" - the user's web browser or other client device identification. FAQ Is there a finAPI SDK? Currently we do not offer a native SDK, but there is the option to generate an SDK for almost any target language via OpenAPI. Use the 'Download SDK' button on this page for SDK generation. How can I enable finAPI's automatic batch update? Currently there is no way to set up the batch update via the API. Please contact [email protected] for this. Why do I need to keep authorizing when calling services on this page? This page is a "one-page-app". Reloading the page resets the OAuth authorization context. There is generally no need to reload the page, so just don't do it and your authorization will persist.

Go to Download

Landed Cost API providing duty rates, calculation, and item harmonization. A set of sample requests are available as a [Postman Collection](https://www.getpostman.com/collections/ad308f6c9351a18c2c12). ## Basics ### Timestamps Timestamps should be formatted using ISO-8601 to the nearest second, in UTC e.g `2015-06-12T09:17:37Z` ### Expiries All Requests will have an associated timestamp. The validity for any request is 1 minute to account for any clock-skew. ## Authorization All API requests require an http header that contains your account ID and your account API Key. During account provisioning, you will be issued an API Key which you must supply with every request. ### Authorization Header To make an authorized API request, set the following HTTP header: `authorization: avalaraapikey id: key:`

Go to Download

RESTful API for Account Information Services (AIS) and Payment Initiation Services (PIS) The following pages give you some general information on how to use our APIs. The actual API services documentation then follows further below. You can use the menu to jump between API sections. This page has a built-in HTTP(S) client, so you can test the services directly from within this page, by filling in the request parameters and/or body in the respective services, and then hitting the TRY button. Note that you need to be authorized to make a successful API call. To authorize, refer to the 'Authorization' section of the API, or just use the OAUTH button that can be found near the TRY button. General information Error Responses When an API call returns with an error, then in general it has the structure shown in the following example: { "errors": [ { "message": "Interface 'FINTS_SERVER' is not supported for this operation.", "code": "BAD_REQUEST", "type": "TECHNICAL" } ], "date": "2020-11-19 16:54:06.854", "requestId": "selfgen-312042e7-df55-47e4-bffd-956a68ef37b5", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/21", "bank": "DEMO0002 - finAPI Test Redirect Bank" } If an API call requires an additional authentication by the user, HTTP code 510 is returned and the error response contains the additional "multiStepAuthentication" object, see the following example: { "errors": [ { "message": "Es ist eine zusätzliche Authentifizierung erforderlich. Bitte geben Sie folgenden Code an: 123456", "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "678b13f4be9ed7d981a840af8131223a", "status": "CHALLENGE_RESPONSE_REQUIRED", "challengeMessage": "Es ist eine zusätzliche Authentifizierung erforderlich. Bitte geben Sie folgenden Code an: 123456", "answerFieldLabel": "TAN", "redirectUrl": null, "redirectContext": null, "redirectContextField": null, "twoStepProcedures": null, "photoTanMimeType": null, "photoTanData": null, "opticalData": null } } ], "date": "2019-11-29 09:51:55.931", "requestId": "selfgen-45059c99-1b14-4df7-9bd3-9d5f126df294", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/18", "bank": "DEMO0001 - finAPI Test Bank" } An exception to this error format are API authentication errors, where the following structure is returned: { "error": "invalid_token", "error_description": "Invalid access token: cccbce46-xxxx-xxxx-xxxx-xxxxxxxxxx" } Paging API services that may potentially return a lot of data implement paging. They return a limited number of entries within a "page". Further entries must be fetched with subsequent calls. Any API service that implements paging provides the following input parameters: • "page": the number of the page to be retrieved (starting with 1). • "perPage": the number of entries within a page. The default and maximum value is stated in the documentation of the respective services. A paged response contains an additional "paging" object with the following structure: { ... , "paging": { "page": 1, "perPage": 20, "pageCount": 234, "totalCount": 4662 } } Internationalization The finAPI services support internationalization which means you can define the language you prefer for API service responses. The following languages are available: German, English, Czech, Slovak. The preferred language can be defined by providing the official HTTP Accept-Language header. finAPI reacts on the official iso language codes "de", "en", "cs" and "sk" for the named languages. Additional subtags supported by the Accept-Language header may be provided, e.g. "en-US", but are ignored. If no Accept-Language header is given, German is used as the default language. Exceptions: • Bank login hints and login fields are only available in the language of the bank and not being translated. • Direct messages from the bank systems typically returned as BUSINESS errors will not be translated. • BUSINESS errors created by finAPI directly are available in German and English. • TECHNICAL errors messages meant for developers are mostly in English, but also may be translated. Request IDs With any API call, you can pass a request ID via a header with name "X-Request-Id". The request ID can be an arbitrary string with up to 255 characters. Passing a longer string will result in an error. If you don't pass a request ID for a call, finAPI will generate a random ID internally. The request ID is always returned back in the response of a service, as a header with name "X-Request-Id". We highly recommend to always pass a (preferably unique) request ID, and include it into your client application logs whenever you make a request or receive a response (especially in the case of an error response). finAPI is also logging request IDs on its end. Having a request ID can help the finAPI support team to work more efficiently and solve tickets faster. Overriding HTTP methods Some HTTP clients do not support the HTTP methods PATCH or DELETE. If you are using such a client in your application, you can use a POST request instead with a special HTTP header indicating the originally intended HTTP method. The header's name is X-HTTP-Method-Override. Set its value to either PATCH or DELETE. POST Requests having this header set will be treated either as PATCH or DELETE by the finAPI servers. Example: X-HTTP-Method-Override: PATCH POST /api/v1/label/51 {"name": "changed label"} will be interpreted by finAPI as: PATCH /api/v1/label/51 {"name": "changed label"} User metadata With the migration to PSD2 APIs, a new term called "User metadata" (also known as "PSU metadata") has been introduced to the API. This user metadata aims to inform the banking API if there was a real end-user behind an HTTP request or if the request was triggered by a system (e.g. by an automatic batch update). In the latter case, the bank may apply some restrictions such as limiting the number of HTTP requests for a single consent. Also, some operations may be forbidden entirely by the banking API. For example, some banks do not allow issuing a new consent without the end-user being involved. Therefore, it is certainly necessary and obligatory for the customer to provide the PSU metadata for such operations. As finAPI does not have direct interaction with the end-user, it is the client application's responsibility to provide all the necessary information about the end-user. This must be done by sending additional headers with every request triggered on behalf of the end-user. At the moment, the following headers are supported by the API: • "PSU-IP-Address" - the IP address of the user's device. • "PSU-Device-OS" - the user's device and/or operating system identification. • "PSU-User-Agent" - the user's web browser or other client device identification. FAQ Is there a finAPI SDK? Currently we do not offer a native SDK, but there is the option to generate a SDK for almost any target language via OpenAPI. Use the 'Download SDK' button on this page for SDK generation. How can I enable finAPI's automatic batch update? Currently there is no way to set up the batch update via the API. Please contact [email protected] for this. Why do I need to keep authorizing when calling services on this page? This page is a "one-page-app". Reloading the page resets the OAuth authorization context. There is generally no need to reload the page, so just don't do it and your authorization will persist.

Go to Download

# Summary The **NextGenPSD2** *Framework Version 1.3.6* (with errata) offers a modern, open, harmonised and interoperable set of Application Programming Interfaces (APIs) as the safest and most efficient way to provide data securely. The NextGenPSD2 Framework reduces XS2A complexity and costs, addresses the problem of multiple competing standards in Europe and, aligned with the goals of the Euro Retail Payments Board, enables European banking customers to benefit from innovative products and services ('Banking as a Service') by granting TPPs safe and secure (authenticated and authorised) access to their bank accounts and financial data. The possible Approaches are: * Redirect SCA Approach * OAuth SCA Approach * Decoupled SCA Approach * Embedded SCA Approach without SCA method * Embedded SCA Approach with only one SCA method available * Embedded SCA Approach with Selection of a SCA method Not every message defined in this API definition is necessary for all approaches. Furthermore this API definition does not differ between methods which are mandatory, conditional, or optional. Therefore for a particular implementation of a Berlin Group PSD2 compliant API it is only necessary to support a certain subset of the methods defined in this API definition. **Please have a look at the implementation guidelines if you are not sure which message has to be used for the approach you are going to use.** ## Some General Remarks Related to this version of the OpenAPI Specification: * **This API definition is based on the Implementation Guidelines of the Berlin Group PSD2 API.** It is not a replacement in any sense. The main specification is (at the moment) always the Implementation Guidelines of the Berlin Group PSD2 API. * **This API definition contains the REST-API for requests from the PISP to the ASPSP.** * **This API definition contains the messages for all different approaches defined in the Implementation Guidelines.** * According to the OpenAPI-Specification [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md] "If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored." The element "Accept" will not be defined in this file at any place. The elements "Content-Type" and "Authorization" are implicitly defined by the OpenApi tags "content" and "security". * There are several predefined types which might occur in payment initiation messages, but are not used in the standard JSON messages in the Implementation Guidelines. Therefore they are not used in the corresponding messages in this file either. We added them for the convenience of the user. If there is a payment product, which needs these fields, one can easily use the predefined types. But the ASPSP need not to accept them in general. * **We omit the definition of all standard HTTP header elements (mandatory/optional/conditional) except they are mentioned in the Implementation Guidelines.** Therefore the implementer might add these in his own realisation of a PSD2 comlient API in addition to the elements defined in this file. ## General Remarks on Data Types The Berlin Group definition of UTF-8 strings in context of the PSD2 API has to support at least the following characters a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 / - ? : ( ) . , ' + Space

Go to Download

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API. Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls. # Errors The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format: ``` { "message": "page not found" } ``` # Versioning The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned. If you omit the version-prefix, the current version of the API (v1.44) is used. For example, calling `/info` is the same as calling `/v1.44/info`. Using the API without a version-prefix is deprecated and will be removed in a future release. Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine. The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons. # Authentication Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure: ``` { "username": "string", "password": "string", "email": "string", "serveraddress": "string" } ``` The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required. If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials: ``` { "identitytoken": "9cbaf023786cd7..." } ```

Go to Download

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API. Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls. # Errors The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format: ``` { "message": "page not found" } ``` # Versioning The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned. If you omit the version-prefix, the current version of the API (v1.40) is used. For example, calling `/info` is the same as calling `/v1.40/info`. Using the API without a version-prefix is deprecated and will be removed in a future release. Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine. The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons. # Authentication Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a Base64 encoded (JSON) string with the following structure: ``` { "username": "string", "password": "string", "email": "string", "serveraddress": "string" } ``` The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required. If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials: ``` { "identitytoken": "9cbaf023786cd7..." } ```

Go to Download

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API. Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls. # Errors The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format: ``` { "message": "page not found" } ``` # Versioning The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned. If you omit the version-prefix, the current version of the API (v1.40) is used. For example, calling `/info` is the same as calling `/v1.40/info`. Using the API without a version-prefix is deprecated and will be removed in a future release. Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine. The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons. # Authentication Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a Base64 encoded (JSON) string with the following structure: ``` { "username": "string", "password": "string", "email": "string", "serveraddress": "string" } ``` The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required. If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials: ``` { "identitytoken": "9cbaf023786cd7..." } ```

Go to Download

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API. Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls. # Errors The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format: ``` { "message": "page not found" } ``` # Versioning The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned. If you omit the version-prefix, the current version of the API (v1.43) is used. For example, calling `/info` is the same as calling `/v1.43/info`. Using the API without a version-prefix is deprecated and will be removed in a future release. Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine. The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons. # Authentication Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure: ``` { "username": "string", "password": "string", "email": "string", "serveraddress": "string" } ``` The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required. If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials: ``` { "identitytoken": "9cbaf023786cd7..." } ```

Go to Download

Document describes the API description for partners in order to create and track delivery requests. ## Revision history |Date|Author|Description|Version| |-|-|-|-| |2022-09-22|Šmolík, J.|Add accepted-to-locker parcel event |1.40| |2022-09-08|Šmolík J.| Add support for user to choose partner they want to work with |1.39| |2022-08-10|Šmolík J.| Add /labels:search to download PDF labels for defined criteria |1.38| |2022-08-08|Azizov. J.| Add `region` field to /destinations and /origins endpoints |1.37| |2022-07-27|Vala J.| Add EP for listing shipping label data of parcels order /api/v1/delivery-requests/{orderNumber}/label |1.36| |2022-07-27|Vala J.| Add EP for listing shipping label data of parcel /api/v1/parcels/{id}/label |1.35| |2022-07-22|Vala J.| Add destination_public_id column to csv export of parcels |1.34| |2022-07-08|Vala J.| Add exportCsvUrl to headers ['X-export-url-csv'] to response from /api/v1/parcelsAdd endpoint to export parcels to csv file /ui/v1/parcels.csv |1.33| |2022-06-27|Vala J.| Add width and printerModel query parameters for zpl shipping labels for /api/v1/delivery-requests/{orderNumber}/label.{type} and /api/v1/parcels/{id}/label.{type} |1.32| |2022-06-17|Šmolík, J.| Allow to select return location for delivery request |1.31| |2022-05-25|Vala, J.| Add single labelUrlPdf to headers ['X-labels-url-pdf'] in response from /api/v1/delivery-requests:fromCsv |1.30| |2022-05-25|Vala, J.| Add EP to handle csv import orders printing of shipping label /ui/v1/delivery-requests/{orderImportsNumber}/label.pdf |1.29| |2022-05-20|Vala, J.| Add possibility to overwrite 4 rows in shipping label sender info to /api/v1/delivery-requests endpoint |1.28| |2022-05-04|Azizov, J.| Add state and created filters to to /api/v1/parcels endpoint |1.27| |2022-05-03|Azizov, J.| Add possibility to search parcels to /api/v1/parcels endpoint |1.26| |2022-04-27|Azizov, J.| Add /api/v1/delivery-requests:customerReturns for customer returns delivery requests |1.25| |2022-04-26|Vala, J.| Add createTime, updateTime to parcel list response |1.24| |2022-04-21|Šmolík, J.| Add payment info to parcels |1.23| |2022-02-22|Azizov, J.| Add P408 and P409 error codes |1.22| |2022-02-22|Azizov, J.| Add notifySMSOnAccepted to DeliveryRequest |1.21| |2022-02-01|Šmolík, J.| Add check address delivery endpointAdd /api/v1/simple-delivery-requests for simpler delivery creation |1.20| |2022-01-20|Šmolík, J.| Add P405, P406 and P407 error codes |1.19| |2022-01-10|Šmolík, J.| Add CSV import endpointAdd JWT custom claims descriptionMove 403 error codes to own section |1.18| |2021-12-23|Šmolík, J.| Add new endpoint to confirm AnyAPM delivery of a parcelPartition error codes by HTTP status response |1.17| |2021-12-16|Šmolík, J.| Add new error code P403 |1.16| |2021-12-09|Šmolík, J.| Add new error codes P401, P402 |1.15| |2021-11-30|Šmolík, J.| Add delivery request origin, destination and items fields description |1.14| |2021-11-11|Šmolík, J.| Add endpoint for parcel delivery cancellation |1.13| |2021-11-09|Šmolík, J.| Add X403 error code spec |1.12| |2021-10-14|Šmolík, J.| Add Accepted for return event |1.11| |2021-10-05|Šmolík, J.| Make DeliveryRequest.items required |1.10| |2021-09-22|Šmolík, J.| Add canceled event state and event|1.9| |2021-09-17|Šmolík, J.| Add PDF label URLs to parcels response |1.8 |2021-09-13|Šmolík, J.| Update parcel state enum valuesRemove history event displayName, add type|1.7 |2021-08-25|Azizov, J.| Add possibility to print labels for all parcels in orderMake contact information of origin optional in delivery request|1.6 |2021-08-02|Azizov, J.| Add items metadata to parcel |1.5| |2021-07-15|Šmolík, J.| Add destination expected delivery time |1.4| |2021-06-23|Šmolík, J.| Update money value fields description |1.3| |2021-06-21|Šmolík, J.| Update Requesting a delivery textAdd `name` filter to origins and destinations Rename delivery request code of description to plain descriptionAdd more specific info to value amount fieldsUpdate address country to match ISO CodeUpdate address postal code formattingUpdate origin/destination for delivery requestRemove height, length, width from order itemAdd events to parcel infoUpdate delivery request responseUpdate order number descriptionAdd parcel id filter to /parcelsAdd message to errorMake contact name requiredAdd delivery partner parcel idsRemove order items' code and status |1.2| |2021-06-14|Šmolík, J.| Add a todo to specify client notification type after accepting the order. Let the partner choose to receive an email when successful delivery request is made. Remove `typeOfOrder` from delivery request.Add option to select delivery partner for pickupMake item weight in the order optionalMake origin contact email requiredAdd support to add sender's name when making delivery requestRemove landmark and code from addressAdd new error code or partners not eligible to create COD delivery requestsAdd support to filter destinations/origins by typeAdd support to send compartment size for order item, required for APM originMake `typeOfService` optional |1.1| |2021-06-09|Šmolík, J.|Initial version|1.0| # Setup Register your company through our support. We are going to need - Company name - List of Phone numbers for SMS OTP authentication of people who'll you want to have access to the Partner CMS - List of addresses for pickup points - where do we pickup your order for delivery You will get in return - `OAUTH_CLIENT_ID` - OAuth2 Client ID for authenticating with the Partner API. Keep it safe. Value may vary for each environment. - `OAUTH_CLIENT_SECRET` - OAuth2 Client Secret for authenticating with the Partner API. Keep it safe. Value may vary for each environment. - `API_URL` - Base URL for Partner API ## Environments Product offers multiple environments - Sandbox - For you to test the integration. Limited functionality. - Production - Connected to real end-users. Use with care. Environment setting summary: | Value \ Env | Sandbox | Production | |---|---|---| | `API_URL` | N/A | N/A | | `OAUTH_CLIENT_SECRET` | Contact Support | Contact Support | | `OAUTH_CLIENT_ID` | Contact Support | Contact Support | # API ## Authentication Authentication is based on OAuth2 standard, Client Credentials grant. Token endpoint `/auth-sessions`, see examples below. Client ID and Secret MUST be passed to you from BoxNow support in advance. In order to use the API, you MUST attach the access token to Authorization header as a Bearer token. ### Custom JWT claims You can find additional user information in custom claims under namespace key `https://boxnow.gr`. For example ```json { "iat": 1641980553, "exp": 1641984153, "https://boxnow.gr": { "permission": { "warehouseAsOrigin": true, "anyApmAsOrigin": true, "anyApmToSameApmDelivery": true, "anyApmToSameApmDeliveryWithoutConfirmation": true, "depotAsOrigin": true } } } ``` ## Listing available destinations You can skip this if you don't want to deliver your order to one of our APMs. Use `/destinations` to list available APM locations we can deliver the goods to. You will refer to these records by `id` when requesting delivery later on. ## Requesting a delivery Create a delivery request to delivery your order to the client. Use `/delivery-requests` endpoint for this operation. Once a successful request delivery is made - (optional) we send you an email notifying about successful delivery request creation, if you choose to receive this email - you should fetch the PDF label for each of the parcel from `/parcels/{id}/label.pdf`, print it and stick it to the parcel/s - we send a courier to pick up the labeled parcel/s - we notify the client via email that we have accepted the order from you and its being delivered by us ## Modifying a delivery request After a delivery request is successfully made, you can alter some parts of it later on. Use `/delivery-requests/{id}` endpoint for these modifications. ## Checking on the deliveries You can list parcel related to your delivery requests via `/parcels` endpoint. ## Error codes ### Description of codes for `400 Unprocessable entity` responses - `P400` - Invalid request data. Make sure are sending the request according to this documentation. - `P401` - Invalid request origin location reference. Make sure you are referencing a valid location ID from Origins endpoint or valid address. - `P402` - Invalid request destination location reference. Make sure you are referencing a valid location ID from Destinations endpoint or valid address. - `P403` - You are not allowed to use AnyAPM-SameAPM delivery. Contact support if you believe this is a mistake. - `P404` - Invalid import CSV. See error contents for additional info. - `P405` - Invalid phone number. Make sure you are sending the phone number in full international format, e.g. +30 xx x xxx xxxx. - `P406` - Invalid compartment/parcel size. Make sure you are sending one of required sizes 1, 2 or 3. Size is required when sending from AnyAPM directly. - `P407` - Invalid country code. Make sure you are sending country code in ISO 3166-1 alpha-2 format, e.g. GR. - `P408` - Invalid amountToBeCollected amount. Make sure you are sending amount in the valid range of (0, 5000> - `P409` - Invalid delivery partner reference. Make sure you are referencing a valid delivery partner ID from Delivery partners endpoint. - `P410` - Order number conflict. You are trying to create a delivery request for order ID that has already been created. Choose another order id. - `P411` - You are not eligible to use Cash-on-delivery payment type. Use another payment type or contact our support. - `P412` - You are not allowed to create customer returns deliveries. Contact support if you believe this is a mistake. - `P413` - Invalid return location reference. Make sure you are referencing a valid location warehouse ID from Origins endpoint or valid address. - `P420` - Parcel not ready for cancel. You can cancel only new, undelivered, or parcels that are not returned or lost. Make sure parcel is in transit and try again. - `P430` - Parcel not ready for AnyAPM confirmation. Parcel is probably already confirmed or being delivered. Contact support if you believe this is a mistake. ### Description of codes for `403 Forbidden` responses - `X403` - Account disabled. Your account had been disabled, contact support. - `P414` - Unauthorized parcel access. You are trying to access information to parcel/s that don't belong to you. Make sure you are requesting information for parcels you have access to. ### Description of codes for `503 Service Unavailable` responses | Code | Description | |---|---| | `P600` | Locker bridge communication failed. There has been some error when communicating with the locker bridge. Try again later or contact support. | | `P610` | Geolocation API failed. There has been some error when translating address to gps coordinates. Try again later or contact support. |

Go to Download

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API. Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls. # Errors The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format: ``` { "message": "page not found" } ``` # Versioning The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned. If you omit the version-prefix, the current version of the API (v1.41) is used. For example, calling `/info` is the same as calling `/v1.41/info`. Using the API without a version-prefix is deprecated and will be removed in a future release. Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine. The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons. # Authentication Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure: ``` { "username": "string", "password": "string", "email": "string", "serveraddress": "string" } ``` The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required. If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials: ``` { "identitytoken": "9cbaf023786cd7..." } ```

Go to Download

The Inter TT REST API is described using OpenAPI 3.0. The descriptor for the api can be downloaded in both [YAML](http://localhost:8080/cyclos/api/openapi.yaml) or [JSON](http://localhost:8080/cyclos/api/openapi.json) formats. These files can be used in tools that support the OpenAPI specification, such as the [OpenAPI Generator](https://openapi-generator.tech). In the API, whenever some data is referenced, for example, a group, or payment type, either id or internal name can be used. When an user is to be referenced, the special word 'self' (sans quotes) always refers to the currently authenticated user, and any identification method (login name, e-mail, mobile phone, account number or custom field) that can be used on keywords search (as configured in the products) can also be used to identify users. Some specific data types have other identification fields, like accounts can have a number and payments can have a transaction number. This all depends on the current configuration. ----------- Most of the operations that return data allow selecting which fields to include in the response. This is useful to avoid calculating data that finally won't be needed and also for reducing the transfer over the network. If nothing is set, all object fields are returned. Fields are handled in 3 modes. Given an example object `{"a": {"x": 1, "y": 2, "z": 3}, "b": 0}`, the modes are: - **Include**: the field is unprefixed or prefixed with `+`. All fields which are not explicitly included are excluded from the result. Examples: - `["a"]` results in `{"a": {"x": 1, "y": 2, "z": 3}}` - `["+b"]` results in `{"b": 0}` - `["a.x"]` results in `{"a": {"x": 1}}`. This is a nested include. At root level, includes only `a` then, on `a`'s level, includes only `x`. - **Exclude**: the field is prefixed by `-` (or, for compatibility purposes, `!`). Only explicitly excluded fields are excluded from the result. Examples: - `["-a"]` results in `{"b": 0}` - `["-b"]` results in `{"a": {"x": 1, "y": 2, "z": 3}}` - `["a.-x"]` results in `{"a": {"y": 2, "z": 3}}`. In this example, `a` is actually an include at the root level, hence, excludes `b`. - **Nested only**: when a field is prefixed by `*` and has a nested path, it only affects includes / excludes for the nested fields, without affecting the current level. Only nested fields are configured. Examples: - `["*a.x"]` results in `{"a": {"x": 1}, "b": 0}`. In this example, `a` is configured to include only `x`. `b` is also included because, there is no explicit includes at root level. - `["*a.-x"]` results in `{"a": {"y": 2, "z": 3}, "b": 0}`. In this example, `a` is configured to exclude only `x`. `b` is also included because there is no explicit includes at the root level. For backwards compatibility, this can also be expressed in a special syntax `-a.x`. Also, keep in mind that `-x.y.z` is equivalent to `*x.*y.-z`. You cannot have the same field included and excluded at the same time - a HTTP `422` status will be returned. Also, when mixing nested excludes with explicit includes or excludes, the nested exclude will be ignored. For example, using `["*a.x", "a.y"]` will ignore the `*a.x` definition, resulting in `{"a": {"y": 2}}`. ----------- For details of the deprecated elements (operations and model) please visit the [deprecation notes page](https://documentation.cyclos.org/4.16.3/api-deprecation.html) for this version.

Go to Download

# Authentication Requests made to our APIs must be authenticated, there are two ways to do this: 1. Authenticating using your API apiUsername and apiPassword - `Basic Auth` 2. Authenticating using an Auth Token - `Bearer Token` ## Method 1: Basic Auth Basic Authentication is a method for an HTTP user agent (e.g., a web browser) to provide a apiUsername and apiPassword when making a request. When employing Basic Authentication, users include an encoded string in the Authorization header of each request they make. The string is used by the request’s recipient to verify users’ identity and rights to access a resource. The Authorization header follows this format: > Authorization: Basic base64(apiUsername:apiPassword) So if your apiUsername and apiPassword are `onfon` and `!@pas123`, the combination is `onfon:!@pas123`, and when base64 encoded, this becomes `b25mb246IUBwYXMxMjM=`. So requests made by this user would be sent with the following header: > Authorization: Basic b25mb246IUBwYXMxMjM= | Description | | ---------------------------------------------------------------------------------------------- | | **apiUsername** `String` `Required` Your onfon account apiUsername, retrieved from portal | | **apiPassword** `String` `Required` Your onfon account apiPassword, retrieved from portal | ## Method 2: Bearer Tokens This authentication stategy allows you to authenticate using JSON Web Token ``JWT` that will expire after given duration. Each Access Token is a `JWT`, an encoded JSON object with three parts: the `header`, the `payload`, and the `signature`. The following is an example Access Token generated for Conversations > Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c ### Getting the token To generate the token, make a `POST` request to `/v1/authorization` endpoint with your `apiUsername` and `apiPassword` This request should be made from your server and not on the client side such as browser or mobile environment. You will receive a JSON similar to below: `{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", "validDurationSeconds": 3600}` You can use the token received to make API calls. The token will be valid for value of `validDurationSeconds`, before which you should generate a new token. #### Request Body ``` { "apiUsername": "root", "apiPassword": "hakty11" } ``` #### Response Body ``` { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", "validDurationSeconds": 3600 } ``` #### Example Curl ``` curl --location --request POST 'https://apis.onfonmedia.co.ke/v1/authorization' \ --data-raw '{ "apiUsername": "correctapiUsername", "apiPassword": "correctapiPassword" } ``` #### Making an API call You will be required to pass the token in `Authorization` header prefixed by `Bearer` when calling other endpoints. Example `Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c`

Go to Download