diff --git a/lib/gen-utils.ts b/lib/gen-utils.ts index 3a9e376..7ac7b18 100644 --- a/lib/gen-utils.ts +++ b/lib/gen-utils.ts @@ -113,16 +113,19 @@ export function toBasicChars(text: string, firstNonDigit = false): string { /** * Returns the TypeScript comments for the given schema description, in a given indentation level */ -export function tsComments(description: string | undefined, level: number) { +export function tsComments(description: string | undefined, level: number, deprecated?: boolean) { const indent = ' '.repeat(level); if (description == undefined || description.length === 0) { - return indent; + return indent + (deprecated ? '/** @deprecated */' : ''); } const lines = description.trim().split('\n'); let result = '\n' + indent + '/**\n'; lines.forEach(line => { result += indent + ' *' + (line === '' ? '' : ' ' + line.replace(/\*\//g, '* / ')) + '\n'; }); + if (deprecated) { + result += indent + ' *\n' + indent + ' * @deprecated\n'; + } result += indent + ' */\n' + indent; return result; } diff --git a/lib/model.ts b/lib/model.ts index 3b9897a..0748542 100644 --- a/lib/model.ts +++ b/lib/model.ts @@ -32,7 +32,7 @@ export class Model extends GenType { super(name, unqualifiedName, options); const description = schema.description || ''; - this.tsComments = tsComments(description, 0); + this.tsComments = tsComments(description, 0, schema.deprecated); const type = schema.type || 'any'; diff --git a/lib/operation-variant.ts b/lib/operation-variant.ts index 119afd1..2d1380c 100644 --- a/lib/operation-variant.ts +++ b/lib/operation-variant.ts @@ -42,8 +42,8 @@ export class OperationVariant { if (description !== '') { description += '\n\n'; } - this.responseMethodTsComments = tsComments(this.responseMethodDescription(), 1); - this.bodyMethodTsComments = tsComments(this.bodyMethodDescription(), 1); + this.responseMethodTsComments = tsComments(this.responseMethodDescription(), 1, operation.deprecated); + this.bodyMethodTsComments = tsComments(this.bodyMethodDescription(), 1, operation.deprecated); } private inferResponseType(mediaType: string): string { diff --git a/lib/operation.ts b/lib/operation.ts index ce22146..ae3f11f 100644 --- a/lib/operation.ts +++ b/lib/operation.ts @@ -20,6 +20,7 @@ export class Operation { hasParameters: boolean; parametersRequired = false; security: Security[][] = []; + deprecated: boolean; tsComments: string; requestBody?: RequestBody; @@ -39,7 +40,7 @@ export class Operation { this.path = this.path.replace(/\'/g, '\\\''); this.tags = spec.tags || []; - this.tsComments = tsComments(spec.description || '', 1); + this.tsComments = tsComments(spec.description || '', 1, spec.deprecated); this.pathVar = `${upperFirst(id)}Path`; this.methodName = spec['x-operation-name'] || this.id; @@ -71,6 +72,8 @@ export class Operation { this.allResponses = responses.all; this.pathExpression = this.toPathExpression(); + this.deprecated = !!spec.deprecated; + // Now calculate the variants: request body content x success response content this.calculateVariants(); } diff --git a/lib/parameter.ts b/lib/parameter.ts index 13b33f8..33c3e20 100644 --- a/lib/parameter.ts +++ b/lib/parameter.ts @@ -17,7 +17,7 @@ export class Parameter { constructor(public spec: ParameterObject, options: Options) { this.name = spec.name; this.var = methodName(this.name); - this.tsComments = tsComments(spec.description || '', 2); + this.tsComments = tsComments(spec.description || '', 2, spec.deprecated); this.in = spec.in || 'query'; this.required = this.in === 'path' || spec.required || false; this.type = tsType(spec.schema, options); diff --git a/lib/property.ts b/lib/property.ts index a5093e0..bab126b 100644 --- a/lib/property.ts +++ b/lib/property.ts @@ -18,6 +18,6 @@ export class Property { this.type = tsType(this.schema, options); const description = (schema as SchemaObject).description || ''; - this.tsComments = tsComments(description, 1); + this.tsComments = tsComments(description, 1, (schema as SchemaObject).deprecated); } } diff --git a/test/cyclos.json b/test/cyclos.json index 9537d23..17cac90 100644 --- a/test/cyclos.json +++ b/test/cyclos.json @@ -1,12 +1,12 @@ { "openapi" : "3.0.0", "info" : { - "title" : "Cyclos 4.12 API", - "description" : "The Cyclos REST API is described using OpenAPI 3.0. The descriptor for the api can be downloaded in both [YAML](https://demo.cyclos.org/api/cyclos-openapi.yaml) or [JSON](https://demo.cyclos.org/api/cyclos-openapi.json) formats. These files can be used in tools that support the OpenAPI specification, such as the [Swagger Generator](https://generator.swagger.io/).\n\nIn 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.\n\nFor details of the deprecated elements (operations and model) please visit the [deprecation notes page](https://documentation.cyclos.org/4.12/api-deprecation.html) for this version.", - "version" : "4.12" + "title" : "Cyclos 4.13 API", + "description" : "The Cyclos REST API is described using OpenAPI 3.0. The descriptor for the api can be downloaded in both [YAML](http://localhost:8888/api/cyclos-openapi.yaml) or [JSON](http://localhost:8888/api/cyclos-openapi.json) formats. These files can be used in tools that support the OpenAPI specification, such as the [Swagger Generator](https://generator.swagger.io/).\n\nIn 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.\n\nMost of the operations that return data allow selecting which fields to include in the response. This is useful for reducing the data to be download over the network. If nothing is set, all object fields are returned. Unprefixed field names will be handled like a whitelist (only listed fields will be included), while names starting with a minus (-) or exclamation mark (!) will be handled as blacklist (listed fields will not be included). This works for nesting as well. For example: `a,b.b1,c.-c1,c.-c2` will return the fields `a`, `b` (containing only the `b1` field) and `c` (containing all its fields except for `c1` or `c2`).\n\nFor details of the deprecated elements (operations and model) please visit the [deprecation notes page](https://documentation.cyclos.org/4.13/api-deprecation.html) for this version.", + "version" : "4.13" }, "servers" : [ { - "url" : "https://demo.cyclos.org/api" + "url" : "http://localhost:8888/api" } ], "tags" : [ { "name" : "Auth", @@ -17,6 +17,9 @@ }, { "name" : "Captcha", "description" : "Generate new captcha challenges, which are required for some operations performed as guest, in order to make it harder for bots to abuse the api." + }, { + "name" : "IdentityProviders", + "description" : "Provides access operations using identity providers such as Google or Facebook. The operations involving the user consent cannot be implemented solely with this API, because a browser window must be opened for the user to consent with the operation. Such operations need first to be prepared, which will store validate and store all the context in Cyclos, and then the popup must be opened. After finishing, the resulting data is sent via push notifications. For more information, see the corresponding section in the [Cyclos Wiki](https://wiki4.cyclos.org/index.php/External_identity_providers#Using_identity_providers_together_with_the_REST_API)." }, { "name" : "Users", "description" : "User searching, registration and profile modification. Also provides access to the user map directory." @@ -95,6 +98,9 @@ }, { "name" : "ScheduledPayments", "description" : "Provides actions specific to scheduled payments and installments. Performing a scheduled payment is done via `Payments`, while searching or viewing details, via `Transactions`." + }, { + "name" : "Installments", + "description" : "Provides search and actions over specific to scheduled payment installments and recurring payment occurrences. Both are generically treated as `Installments`." }, { "name" : "RecurringPayments", "description" : "Provides actions specific to recurring payments and their occurrences. Performing a recurring payment is done via `Payments`, while searching or viewing details, via `Transactions`." @@ -128,12 +134,33 @@ }, { "name" : "Records", "description" : "Provides access to custom records" + }, { + "name" : "Tokens", + "description" : "Provides access to tokens, which are commonly used as cards, but are more generic. Tokens are user identifications whose status can be managed." }, { "name" : "Operations", "description" : "Provides access to custom operations" }, { "name" : "Marketplace", - "description" : "Provides access to the marketplace, that is, searching or managing advertisements, questions, shopping cart support and searching orders.\n\nCurrently both `simple` and `webshop` have support for searching, but only simple advertisements can be managed via this API. Also only order creation through the shopping cart check-out but not as sales (i.e orders created by seller)." + "description" : "Provides access to the marketplace, that is, searching or managing advertisements. The name `marketplace` is used on paths instead of `ads` or `advertisements` because one of the use cases of this API is to be used directly by pages from the browser, and ad-blocking browser extensions would normally deny such requests." + }, { + "name" : "AdQuestions", + "description" : "Provides access to advertisement questions." + }, { + "name" : "ShoppingCarts", + "description" : "Provides access to shopping carts. Users can add webshop advertisements to the shopping cart, and then check-out them, performing the payment. For each user, one shopping cart is created per currency and seller. A shopping cart is an early stage or an `Order`. once checked out, use the operations in the `Orders` tag to access it." + }, { + "name" : "Orders", + "description" : "An order contains a set of items from a seller, to a buyer in a certain currency. Orders can be created in 2 ways: either via a shopping cart checkout (by the buyer, using the operations in the `ShoppingCarts` tag to access it. ) or directly by the seller. Once created, the order must be approved by the other party until its payment is finally performed." + }, { + "name" : "DeliveryMethods", + "description" : "Provides access to webshop delivery methods, which must be selected for an order to be created. A delivery method can have either a fixed amount or be negotiated between the seller and the buyer." + }, { + "name" : "WebshopSettings", + "description" : "Provides access to general webshop settings for sellers." + }, { + "name" : "AdInterests", + "description" : "Provides access to advertisement interests, which are criteria registered by users to be notified when new matching advertisements are published." }, { "name" : "NFC", "description" : "Contains operations regarding NFC tags" @@ -152,6 +179,12 @@ }, { "name" : "Alerts", "description" : "Provides access to alerts generated in the system. Currently only user alerts are supported (system alerts are not)." + }, { + "name" : "References", + "description" : "Provides access to (general) references, which are given from a user to another to show the satisfaction level." + }, { + "name" : "OIDC", + "description" : "Provides the delegation of data and operations via OAuth2 / OpenID Connect. These are standard protocols which enables logging-in on other services with Cyclos, as well as allowing external services to perform operations in behalf of users." } ], "security" : [ { "basic" : [ ] @@ -359,6 +392,14 @@ "schema" : { "type" : "string" } + }, { + "name" : "identityProviderRequestId", + "in" : "query", + "required" : false, + "description" : "When using an [external identity provider](https://wiki4.cyclos.org/index.php/External_identity_providers), this is the request id used to automatically link the user to the provider. Is only needed when no user was matched, either by being previously linked to the provider or by having the same e-mail.", + "schema" : { + "type" : "string" + } } ], "responses" : { "200" : { @@ -1060,6 +1101,357 @@ } } }, + "/oidc/authorize" : { + "get" : { + "operationId" : "oidcAuthorize", + "summary" : "The standard OAuth2 / OpenID Connect authorization endpoint.", + "description" : "Creates a new authorization request. A redirect in HTML format is returne, which should be followed for the user to identify himself and grant the consent to the requested resources.\nFor more information, see also:\n\n- [OAuth 2.0 authorization endpoint](http://tools.ietf.org/html/rfc6749#section-3.1)\n- [OIDC authentication request](http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)\n- [OIDC successful authentication response](http://openid.net/specs/openid-connect-core-1_0.html#AuthResponse)\n- [OIDC authentication error response](http://openid.net/specs/openid-connect-core-1_0.html#AuthError)\n\nThe following standard optional parameters are not supported by Cyclos, and thus, ignored:\n\n- `claims`\n- `claims_locales`\n- `max_age`\n- `id_token_hint`\n- `ui_locales`\n- `acr_value`.", + "tags" : [ "OIDC" ], + "parameters" : [ { + "name" : "scope", + "in" : "query", + "required" : true, + "description" : "A space-delimited list of requested scopes. Scopes are permissions to view user data and to perform operations in behalf of the user.\n\nThe OpenID standard scopes are supported:\n- `openid` for enabling the OpenID Connect id tokens. When not\n requested, standard OAuth2 will be used;\n\n- `profile` for basic profile data access;\n- `email` for e-mail access;\n- `phone` for phone number access;\n- `address` for address access;\n- `offline_access` for refresh tokens to be issued.\n\nOther scopes are defined in Cyclos which represent permissions. These scopes are listed in http://localhost:8888/.well-known/openid-configuration.", + "schema" : { + "type" : "string" + } + }, { + "name" : "response_type", + "in" : "query", + "required" : true, + "description" : "A space-delimited list of response types for this authentication. Accepted avalues are:\n\n- `code`: returing the Authorization code\n- `id_token`: returns the Id token\n- `token`: returns the access token", + "schema" : { + "type" : "string" + } + }, { + "name" : "client_id", + "in" : "query", + "required" : true, + "description" : "The client id as registered in the Cyclos, in OpenID Connect client.", + "schema" : { + "type" : "string" + } + }, { + "name" : "redirect_uri", + "in" : "query", + "required" : true, + "description" : "The URI to which users will be redirected after authentication. Must match one of the registered redirect URIs in Cyclos, in OpenID Connect client.\n", + "schema" : { + "type" : "string" + } + }, { + "name" : "state", + "in" : "query", + "required" : false, + "description" : "A client-state string, which is opaque to the server. Will be passed back to the redirect URL as well as in the generated tokens. Can be used to prevent CSRF attacks by clients.\n", + "schema" : { + "type" : "string" + } + }, { + "name" : "response_mode", + "in" : "query", + "required" : false, + "description" : "How to pass parameters in the redirect URL. Accepted values are:\n\n- `query`: Uses the query string, such as `https://example.com/result?param1=value1¶m2=value2`\n- `fragment`: Uses fragments / hash, such as `https://example.com/result#param1=value1¶m2=value2`\n- `form_post`: Renders an HTML that immediately performs a FORM POST with the parameters\n", + "schema" : { + "type" : "string" + } + }, { + "name" : "nonce", + "in" : "query", + "required" : false, + "description" : "A nonce provided by the client, which will be included in any ID token generated for this session. This is a opaque string for the server, but clients should use it to mitigate replay attacks.\n", + "schema" : { + "type" : "string" + } + }, { + "name" : "display", + "in" : "query", + "required" : false, + "description" : "How the consent page should be displayed. Though currently the consent page is responsive, and as such, doesn't depend on this value, the accepted values are the standard `page`, `popup` and `touch`.\n", + "schema" : { + "type" : "string" + } + }, { + "name" : "prompt", + "in" : "query", + "required" : false, + "description" : "Space-delimited string that determines how the consent page is displayed to the end user.\n\nCyclos currently presents the login and consent page together, so any value other than `none` will actually present the page to the end user to login and consent. There is no such state as a 'previously logged-in' user that would only consent, or first login and then consent. As such, whenever `prompt=none`, Cyclos always replies with `login_required`.\n", + "schema" : { + "type" : "string" + } + }, { + "name" : "login_hint", + "in" : "query", + "required" : false, + "description" : "A principal value (username, e-mail, phone number) for the user that will be initially presented in the authentication page.\n", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "302" : { + "description" : "Either the request succeeded and the referred location is the user login / consent page, or an error was found, and the referred location is the requested `redirect_uri` with the `error` parameter.", + "headers" : { + "Location" : { + "description" : "The URI to follow", + "schema" : { + "type" : "string" + } + } + } + }, + "400" : { + "description" : "Either the `client_id` parameter was invalid, the `redirect_uri` parameter was not set or doesn't match a valid redirect URI as defined in Cyclos. In this case, both `error` and `error_description` are sent encoded in the response body.", + "content" : { + "application/x-www-form-urlencoded" : { + "schema" : { + "type" : "string" + } + } + } + } + } + } + }, + "/oidc/token" : { + "post" : { + "operationId" : "oidcToken", + "summary" : "The standard OAuth2 / OpenID Connect token endpoint.", + "description" : "Exchanges an authorization code for an id token and / or access token. The client id / secret can either be passed in via a basic authentication or via the `client_id` and `client_secret` parameters.\n\nAlthough the OpenID Connect Core specification doesn't mandate a format for access tokens, Cyclos issues them as signed JSON Web Tokens (JWTs). So, clients can, for instance, check for the expiration date in advance, without having to attempt using an expired token. Clients can verify the signature, which makes it easy to detect whether the token has been tampered with.\n\nFor more information, see also:\n\n- [OAuth 2.0 access token request](https://tools.ietf.org/html/rfc6749#section-4.1.3)\n- [OIDC token request](https://openid.net/specs/openid-connect-core-1_0.html#TokenRequest)\n- [OIDC successful token response](https://openid.net/specs/openid-connect-core-1_0.html#TokenResponse)\n- [OIDC token error response](https://openid.net/specs/openid-connect-core-1_0.html#TokenErrorResponse)", + "tags" : [ "OIDC" ], + "requestBody" : { + "required" : true, + "content" : { + "application/x-www-form-urlencoded" : { + "schema" : { + "type" : "object", + "required" : [ "grant_type" ], + "properties" : { + "client_id" : { + "description" : "The client id when not using an HTTP Basic authentication.", + "type" : "string" + }, + "client_secret" : { + "description" : "The client secret when not using an HTTP Basic authentication.", + "type" : "string" + }, + "grant_type" : { + "description" : "The supported values are `authorization_code` and `refresh_token`.", + "type" : "string" + }, + "code" : { + "description" : "The authorization code received in the authorize endpoint. Required when `grant_type` is `authorization_code`.", + "type" : "string" + }, + "redirect_uri" : { + "description" : "The same `redirect_uri` passed in the `authorize` request. Required when `grant_type` is `authorization_code`.", + "type" : "string" + }, + "refresh_token" : { + "description" : "The refresh token requested authorization code received in the authorize endpoint. Required when `grant_type` is `refresh_token`.", + "type" : "string" + } + } + } + } + } + }, + "responses" : { + "200" : { + "description" : "The object containing the access token and the ID token", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/OidcTokenResult" + } + } + } + }, + "400" : { + "description" : "Error validating the request", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/OidcError" + } + } + } + }, + "500" : { + "description" : "Internal server error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/OidcError" + } + } + } + } + } + } + }, + "/oidc/revoke" : { + "post" : { + "operationId" : "oidcRevoke", + "summary" : "The standard OAuth2 token revocation endpoint.", + "description" : "Revokes a refresh token or access token.\nFor more information, see also:\n\n- [OAuth 2.0 token revocation](https://tools.ietf.org/html/rfc7009#section-2)", + "tags" : [ "OIDC" ], + "requestBody" : { + "required" : true, + "content" : { + "application/x-www-form-urlencoded" : { + "schema" : { + "type" : "object", + "required" : [ "token" ], + "properties" : { + "client_id" : { + "description" : "The client id when not using an HTTP Basic authentication.", + "type" : "string" + }, + "client_secret" : { + "description" : "The client secret when not using an HTTP Basic authentication.", + "type" : "string" + }, + "token" : { + "description" : "The token to revoke. May correspond to either a refresh token or an access token.", + "type" : "string" + } + } + } + } + } + }, + "responses" : { + "200" : { + "description" : "Either the token was successfully revoked or the token isn't valid. As per spec, errors shouldn't be returned on either case." + } + } + } + }, + "/oidc/userinfo" : { + "get" : { + "operationId" : "oidcUserInfoGet", + "summary" : "The standard OpenID Connect UserInfo endpoint, using the `GET` method.", + "description" : "Returns all granted claims about the identified user. The OpenID Connect specification requires both `GET` and `POST` methods to be available for this endpoint. This is the implementation via `GET` method.\n\nFor more information, see also:\n\n- [OIDC UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)", + "tags" : [ "OIDC" ], + "security" : [ { + "oidc" : [ "openid" ] + } ], + "responses" : { + "200" : { + "description" : "The user claims encoded as JSON", + "content" : { + "application/json" : { + "schema" : { + "type" : "object" + } + } + } + }, + "401" : { + "description" : "The provided access token is invalid", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/OidcError" + } + } + } + }, + "403" : { + "description" : "The `openid` scope was not granted for this access token", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/OidcError" + } + } + } + }, + "500" : { + "description" : "Internal server error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/OidcError" + } + } + } + } + } + }, + "post" : { + "operationId" : "oidcUserInfoPost", + "summary" : "The standard OpenID Connect UserInfo endpoint, using the `POST` method.", + "description" : "Returns all granted claims about the identified user. The OpenID Connect specification requires both `GET` and `POST` methods to be available for this endpoint. This is the implementation via `POST` method.\n\nFor more information, see also:\n\n- [OIDC UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)", + "tags" : [ "OIDC" ], + "security" : [ { + "oidc" : [ "openid" ] + } ], + "responses" : { + "200" : { + "description" : "The user claims encoded as JSON", + "content" : { + "application/json" : { + "schema" : { + "type" : "object" + } + } + } + }, + "401" : { + "description" : "The provided access token is invalid", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/OidcError" + } + } + } + }, + "403" : { + "description" : "The `openid` scope was not granted for this access token", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/OidcError" + } + } + } + }, + "500" : { + "description" : "Internal server error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/OidcError" + } + } + } + } + } + } + }, + "/oidc/jwks" : { + "get" : { + "operationId" : "oidcJwks", + "summary" : "The standard OpenID Connect JWKS endpoint.", + "description" : "Returns the keys used to sign issued JSON Web Tokens (JWT).\n\n- [JSON Web Key (JWK)](https://tools.ietf.org/html/draft-ietf-jose-json-web-key-41)", + "tags" : [ "OIDC" ], + "responses" : { + "200" : { + "description" : "The object describing the JWKS", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/JWKSResponse" + } + } + } + } + } + } + }, "/sessions/data-for-search" : { "get" : { "operationId" : "getSessionDataForSearch", @@ -1150,7 +1542,6 @@ "in" : "query", "required" : false, "description" : "Internal names of the sessions channels that can be returned.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -1197,13 +1588,20 @@ "in" : "query", "required" : false, "description" : "The role of the logged user in the sessions.", - "style" : "simple", "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/RoleEnum" } } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } }, { "name" : "user", "in" : "query", @@ -1717,30 +2115,32 @@ } } }, - "/users/data-for-search" : { + "/{user}/identity-providers/list-data" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], "get" : { - "operationId" : "getUserDataForSearch", - "summary" : "Get configuration data for searching users", - "description" : "Returns data with the current configuration regarding the user search", - "tags" : [ "Users" ], + "operationId" : "getUserIdentityProvidersListData", + "summary" : "Returns data for identity providers links of the given user.", + "description" : "Returns data for identity providers links of the given user, plus additional data related to them.", + "tags" : [ "IdentityProviders" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" - }, { - "name" : "broker", - "in" : "query", - "required" : false, - "description" : "When set, will be data for searching assigned members of the given broker (id, identification method or `self`)", - "schema" : { - "type" : "string" - } } ], "responses" : { "200" : { - "description" : "The configuration data for user search", + "description" : "The data for listing identity provider links", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/UserDataForSearch" + "$ref" : "#/components/schemas/UserIdentityProvidersListData" } } } @@ -1788,289 +2188,49 @@ } } }, - "/users" : { - "get" : { - "operationId" : "searchUsers", - "summary" : "Search for users", - "description" : "Returns a page of users that match a given criteria. The fields returned depend on the products, in the profile fields of other users setting. Only fields (both basic or custom) marked to be returned on user list are returned. If no fields are set to be returned, or if the `ignoreProfileFieldsInList` flag is true in the given query then the resulting objects will have the `display` and `shortDisplay` filled in. However, those fields are not returned when another profile field is returned, preventing duplicated data to be returned.", - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "name" : "activationPeriod", - "in" : "query", - "required" : false, - "description" : "The minimum / maximum user activation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string", - "format" : "date-time" - } - } - }, { - "name" : "addressResult", - "in" : "query", - "required" : false, - "schema" : { - "$ref" : "#/components/schemas/UserAddressResultEnum" - } - }, { - "name" : "brokers", - "in" : "query", - "required" : false, - "description" : "Either id or a principal (login name, e-mail, etc) for brokers", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "creationPeriod", - "in" : "query", - "required" : false, - "description" : "The minimum / maximum user creation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string", - "format" : "date-time" - } - } - }, { - "name" : "excludeContacts", - "in" : "query", - "required" : false, - "description" : "When set to `true` will not return any user that is already a contact of the currently authenticated user.", - "schema" : { - "type" : "boolean" - } - }, { - "name" : "groups", - "in" : "query", - "required" : false, - "description" : "Either id or internal names of groups / group sets", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "ignoreProfileFieldsInList", - "in" : "query", - "required" : false, - "description" : "When set to `true`, instead of returning users with corresponding profile fields set on list, will return them with `display` and `shortDisplay`.", - "schema" : { - "type" : "boolean" - } - }, { - "name" : "includeGroup", - "in" : "query", - "required" : false, - "description" : "When set to `true` and the logged user has permission to view user groups, will return the `group` property on users.", - "schema" : { - "type" : "boolean" - } - }, { - "name" : "includeGroupSet", - "in" : "query", - "required" : false, - "description" : "When set to `true` and the logged user has permission to view user group sets, will return the `groupSet` property on users.", - "schema" : { - "type" : "boolean" - } - }, { - "name" : "keywords", - "in" : "query", - "required" : false, - "description" : "Textual search keywords. Sometimes, like in user search, the fields matched depends on what is configured on the products.", - "schema" : { - "type" : "string" - } - }, { - "name" : "lastLoginPeriod", - "in" : "query", - "required" : false, - "description" : "The minimum / maximum user last login date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string", - "format" : "date-time" - } - } - }, { - "name" : "latitude", - "in" : "query", - "required" : false, - "description" : "The reference latitude for distance searches", - "schema" : { - "type" : "number", - "format" : "double" - } + "/{user}/identity-providers/{identityProvider}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + }, { + "name" : "identityProvider", + "in" : "path", + "required" : true, + "description" : "Either the id or internal name of the identity provider", + "schema" : { + "type" : "string" + } + } ], + "delete" : { + "operationId" : "deleteUserIdentityProvider", + "summary" : "Removes the link between a user and an identity provider, optionally disabling it", + "description" : "The link between the user and identity provider is removed. If the user attempts to login with the same provider again and the same e-mail address is used a new link will be automatically create. However, if the `disable` parameter is set to `true`, the provider will be disabled for the user, meaning that any subsequent attempts to login the user with that provider will fail, even if the e-mail addres match.", + "tags" : [ "IdentityProviders" ], + "security" : [ { + "basic" : [ ] }, { - "name" : "longitude", - "in" : "query", - "required" : false, - "description" : "The reference longitude for distance searches", - "schema" : { - "type" : "number", - "format" : "double" - } + "session" : [ ] }, { - "name" : "mainBrokerOnly", + "accessClient" : [ ] + } ], + "parameters" : [ { + "name" : "disable", "in" : "query", "required" : false, - "description" : "When set to `true`, will match only users that have the brokers as set in the `brokers` parameter as main broker.", + "description" : "When set to true will disable the link between the user and the provider, preventing a new link to be created on login even if the regitered e-mail address matches the on in the identity provider.", "schema" : { "type" : "boolean" } - }, { - "name" : "maxDistance", - "in" : "query", - "required" : false, - "description" : "Maximum straight-line distance between the informed location and the resulting address. Is measured either in kilometers or miles, depending on the configuration. Only accepted if both `longitude` and `latitude` parameters are passed with the actual reference position.", - "schema" : { - "type" : "number", - "format" : "double" - } - }, { - "name" : "orderBy", - "in" : "query", - "required" : false, - "schema" : { - "$ref" : "#/components/schemas/UserOrderByEnum" - } - }, { - "name" : "page", - "in" : "query", - "required" : false, - "description" : "The page number (zero-based) of the search. The default value is zero.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - }, { - "name" : "pageSize", - "in" : "query", - "required" : false, - "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - }, { - "name" : "profileFields", - "in" : "query", - "required" : false, - "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "roles", - "in" : "query", - "required" : false, - "description" : "", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/RoleEnum" - } - } - }, { - "name" : "statuses", - "in" : "query", - "required" : false, - "description" : "", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/UserStatusEnum" - } - } - }, { - "name" : "usersToExclude", - "in" : "query", - "required" : false, - "description" : "Indicated the users to be excluded from the result", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "usersToInclude", - "in" : "query", - "required" : false, - "description" : "Indicated the users to be included in the result. Any other user not present in this list will be excluded from the result.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } } ], - "tags" : [ "Users" ], "responses" : { - "200" : { - "description" : "The users matching the criteria", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, + "204" : { + "description" : "The link between the user and the identity provider was removed and optionally disabled." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/UserResult" - } + "$ref" : "#/components/schemas/ConflictError" } } } @@ -2105,16 +2265,6 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { "description" : "Unexpected error", "content" : { @@ -2126,28 +2276,30 @@ } } } - }, + } + }, + "/identity-providers/{identityProvider}/login" : { + "parameters" : [ { + "name" : "identityProvider", + "in" : "path", + "required" : true, + "description" : "Either the id or internal name of the identity provider", + "schema" : { + "type" : "string" + } + } ], "post" : { - "operationId" : "createUser", - "summary" : "Registers a new user", - "description" : "Can either be a public registration, requiring no authorization, or a user registration by an administrator or broker. The public registration normally requires a CAPTCHA challenge to prevent bots. On user registration the following data is also created:\n* Address;\n* Mobile phone;\n* Landline phone;\n* Images.\n\nAfter the registration those data are managed separately than the user profile data.", - "parameters" : [ ], - "tags" : [ "Users" ], + "operationId" : "prepareIdentityProviderLogin", + "summary" : "Prepares an operation to login a user from an identity provider.", + "description" : "Prepares an operation to login a user from an identity provider. Several validations are performed, and the result contains the URL which should be used to open a browser window to get the user consent.", + "tags" : [ "IdentityProviders" ], "responses" : { - "201" : { - "description" : "The result of the registration", - "headers" : { - "Location" : { - "description" : "URL for viewing the registered user's profile", - "schema" : { - "type" : "string" - } - } - }, + "200" : { + "description" : "Contains both the request identifier and the URL.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/UserRegistrationResult" + "$ref" : "#/components/schemas/IdentityProviderRequestResult" } } } @@ -2182,16 +2334,6 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { "description" : "Unexpected error", "content" : { @@ -2202,73 +2344,44 @@ } } } - }, - "requestBody" : { - "description" : "The user to be registered", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/UserNew" - } - } - } } } }, - "/users/validate/{group}/{field}" : { - "get" : { - "operationId" : "validateUserRegistrationField", - "summary" : "Validates the value of a single field for user registration", - "description" : "Validates the value of a field which will be used for registering a user, returning either `204 No Content` if the field is valid or `200` with the error description if the field is invalid. Notice that the result is the validation error. If a `422` status code is returned it means that either the given `field` is invalid or the given `value` is empty.", + "/identity-providers/{identityProvider}/register" : { + "parameters" : [ { + "name" : "identityProvider", + "in" : "path", + "required" : true, + "description" : "Either the id or internal name of the identity provider", + "schema" : { + "type" : "string" + } + } ], + "post" : { + "operationId" : "prepareIdentityProviderRegistration", + "summary" : "Prepares an operation to register a user from an identity provider.", + "description" : "Prepares an operation to register a user from an identity provider. Several validations are performed, and the result contains the URL which should be used to open a browser window to get the user consent. The channel configuration in Cyclos determines whether registration with identity providers is allowed, and if so, whether a direct registration will be attempted or will just return the profile data to fill-in the registration form.", + "tags" : [ "IdentityProviders" ], "parameters" : [ { "name" : "group", - "required" : true, - "in" : "path", - "description" : "The internal name or id of the group in which the user is being registered", - "schema" : { - "type" : "string" - } - }, { - "name" : "field", - "required" : true, - "in" : "path", - "description" : "One of: `name` (full name), `username` (login name), `email`, `mobilePhone`, `landLinePhone` or the internal name of a custom field.", - "schema" : { - "type" : "string" - } - }, { - "name" : "value", - "required" : true, "in" : "query", - "description" : "The value to be validated", + "required" : true, + "description" : "The group in which the registration is being requested", "schema" : { "type" : "string" } - }, { - "name" : "asMember", - "required" : false, - "in" : "query", - "description" : "Flag required only when the authenticated user is a member and a broker, in that case we need to distingish between both. If true then the groups returned will be those allowed as member, otherwise will return the goups allowed as broker.", - "schema" : { - "type" : "boolean" - } } ], - "tags" : [ "Users" ], "responses" : { "200" : { - "description" : "The validation error if the field is invalid", + "description" : "Contains both the request identifier and the URL.", "content" : { - "text/plain" : { + "application/json" : { "schema" : { - "type" : "string" + "$ref" : "#/components/schemas/IdentityProviderRequestResult" } } } }, - "204" : { - "description" : "No content if the field is valid" - }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", "content" : { @@ -2299,16 +2412,6 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { "description" : "Unexpected error", "content" : { @@ -2322,33 +2425,31 @@ } } }, - "/users/groups-for-registration" : { - "get" : { - "operationId" : "getGroupsForUserRegistration", - "summary" : "Returns the groups the authenticated user or guest can register on", - "description" : "Returns the list of groups the authenticated user can use to perform a new user registration. If authenticated as guest, will return the groups currently set for public registration. When there is an authenticated administrator, broker or member, will be the configured groups for new users.", - "tags" : [ "Users" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "name" : "asMember", - "required" : false, - "in" : "query", - "description" : "Flag required only when the authenticated user is a member and a broker, in that case we need to distingish between both. If true then the groups returned will be those allowed as member, otherwise will return the goups allowed as broker.", - "schema" : { - "type" : "boolean" - } + "/identity-providers/{identityProvider}/link" : { + "parameters" : [ { + "name" : "identityProvider", + "in" : "path", + "required" : true, + "description" : "Either the id or internal name of the identity provider", + "schema" : { + "type" : "string" + } + } ], + "post" : { + "operationId" : "prepareIdentityProviderLink", + "summary" : "Prepares an operation to link the authenticated user to an identity provider.", + "description" : "Prepares an operation to link the authenticated user to an identity provider. Must be authenticated with a session token (via `Session-Token` request header). Several validations are performed, and the result contains the URL which should be used to open a browser window to get the user consent.", + "tags" : [ "IdentityProviders" ], + "security" : [ { + "session" : [ ] } ], "responses" : { "200" : { - "description" : "The list of groups", + "description" : "Contains both the request identifier and the URL.", "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/GroupForRegistration" - } + "$ref" : "#/components/schemas/IdentityProviderRequestResult" } } } @@ -2396,32 +2497,38 @@ } } }, - "/users/validate/registration/{key}" : { - "post" : { - "deprecated" : true, - "x-remove-version" : 4.14, - "operationId" : "validateUserRegistration", - "summary" : "Validates an user registration via a key sent by e-mail", - "description" : "Use `POST /validate/registration/{key}`\n\n\nWhen a user is registered, and the configuration enables the validation, an e-mail is sent to user e-mail, with a link to verify it. In this case, only after verifying the e-mail the user is activated. This operation effectively verifies the e-mail and performs the user activation. However, depending on the settings, the initial user status might be blocked or inactive.", + "/users/data-for-search" : { + "get" : { + "operationId" : "getUserDataForSearch", + "summary" : "Get configuration data for searching users", + "description" : "Returns data with the current configuration regarding the user search", + "tags" : [ "Users" ], "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "name" : "key", - "required" : true, - "in" : "path", - "description" : "The validation key sent via e-mail", + "name" : "broker", + "in" : "query", + "required" : false, + "description" : "When set, will be data for searching assigned members of the given broker (id, identification method or `self`)", "schema" : { "type" : "string" } + }, { + "name" : "fromMenu", + "in" : "query", + "required" : false, + "description" : "Set to true if you want to use as group filters those defined in the 'User search in menu' configuration setting. Otherwise the group filters would be those defined in the 'Search users on groups' product setting (or in the configuration in case of guests).", + "schema" : { + "type" : "boolean" + } } ], - "tags" : [ "Users" ], "responses" : { "200" : { - "description" : "Returns details about the verified user", + "description" : "The configuration data for user search", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/UserRegistrationResult" + "$ref" : "#/components/schemas/UserDataForSearch" } } } @@ -2469,30 +2576,303 @@ } } }, - "/users/validate/email-change/{key}" : { - "post" : { - "deprecated" : true, - "x-remove-version" : 4.14, - "operationId" : "validateEmailChange", - "summary" : "Validates an e-mail via a validation key", - "description" : "Use `POST /validate/email-change/{key}`\n\n\nWhen the user e-mail is changed, and the configuration enables the validation, an e-mail is sent to the new user e-mail, with a link to verify it. In this case, only after verifying the new e-mail it is effectively set as the new e-mail. This operation effectively verifies the new e-mail.", + "/users" : { + "get" : { + "operationId" : "searchUsers", + "summary" : "Search for users", + "description" : "Returns a page of users that match a given criteria. The fields returned depend on the products, in the profile fields of other users setting. Only fields (both basic or custom) marked to be returned on user list are returned. If no fields are set to be returned, or if the `ignoreProfileFieldsInList` flag is true in the given query then the resulting objects will have the `display` and `shortDisplay` filled in. However, those fields are not returned when another profile field is returned, preventing duplicated data to be returned.", "parameters" : [ { - "name" : "key", - "required" : true, - "in" : "path", - "description" : "The validation key sent via e-mail", + "$ref" : "#/components/parameters/fields" + }, { + "name" : "activationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum user activation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "addressResult", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/UserAddressResultEnum" + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Either id or a principal (login name, e-mail, etc) for brokers", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "contactsOwner", + "in" : "query", + "required" : false, + "description" : "Indicates the (managed) user to exclude contacts when `excludecontacts` is set. Defaults to the logged user.", + "schema" : { + "type" : "string" + } + }, { + "name" : "creationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum user creation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "excludeContacts", + "in" : "query", + "required" : false, + "description" : "When set to `true` will not return any user that is already a contact of the user indicated on `contactsOwner` (the logged user if not set).", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "fromMenu", + "in" : "query", + "required" : false, + "description" : "When set to true the search will be restricted to those groups defined for the user search menu, if false then for those defined in the 'Search users on groups' product setting (or in the configuration in case of guests).", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Either id or internal names of groups / group sets", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "ignoreProfileFieldsInList", + "in" : "query", + "required" : false, + "description" : "When set to `true`, instead of returning users with corresponding profile fields set on list, will return them with `display` and `shortDisplay`.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "includeGroup", + "in" : "query", + "required" : false, + "description" : "When set to `true` and the logged user has permission to view user groups, will return the `group` property on users.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "includeGroupSet", + "in" : "query", + "required" : false, + "description" : "When set to `true` and the logged user has permission to view user group sets, will return the `groupSet` property on users.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "keywords", + "in" : "query", + "required" : false, + "description" : "Textual search keywords. Sometimes, like in user search, the fields matched depends on what is configured on the products.", "schema" : { "type" : "string" } + }, { + "name" : "lastLoginPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum user last login date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "latitude", + "in" : "query", + "required" : false, + "description" : "The reference latitude for distance searches", + "schema" : { + "type" : "number", + "format" : "double" + } + }, { + "name" : "longitude", + "in" : "query", + "required" : false, + "description" : "The reference longitude for distance searches", + "schema" : { + "type" : "number", + "format" : "double" + } + }, { + "name" : "mainBrokerOnly", + "in" : "query", + "required" : false, + "description" : "When set to `true`, will match only users that have the brokers as set in the `brokers` parameter as main broker.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "maxDistance", + "in" : "query", + "required" : false, + "description" : "Maximum straight-line distance between the informed location and the resulting address. Is measured either in kilometers or miles, depending on the configuration. Only accepted if both `longitude` and `latitude` parameters are passed with the actual reference position.", + "schema" : { + "type" : "number", + "format" : "double" + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/UserOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "profileFields", + "in" : "query", + "required" : false, + "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "roles", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/RoleEnum" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "statuses", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/UserStatusEnum" + } + } + }, { + "name" : "usersToExclude", + "in" : "query", + "required" : false, + "description" : "Indicated the users to be excluded from the result", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "usersToInclude", + "in" : "query", + "required" : false, + "description" : "Indicated the users to be included in the result. Any other user not present in this list will be excluded from the result.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } } ], "tags" : [ "Users" ], "responses" : { "200" : { - "description" : "Returns the id of the user that had the e-mail verified", + "description" : "The users matching the criteria", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, "content" : { - "text/plain" : { + "application/json" : { "schema" : { - "type" : "string" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/UserResult" + } } } } @@ -2527,6 +2907,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -2538,40 +2928,28 @@ } } } - } - }, - "/users/data-for-new" : { - "get" : { - "operationId" : "getUserDataForNew", - "summary" : "Get configuration data for registering new users", - "description" : "Almost every aspect of a user profile is configurable in Cyclos, such as enabled basic profile fields, custom profile fields, address fields, phone configuration and so on. As such, if a front-end needs to be robust to such a dynamic nature, it should get this information in order to create a correct registration form.", - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "name" : "group", - "required" : true, - "in" : "query", - "description" : "The intial group for the new user", - "schema" : { - "type" : "string" - } - }, { - "name" : "asMember", - "required" : false, - "in" : "query", - "description" : "Flag required only when the authenticated user is a member and a broker, in that case we need to distingish between both. If true then the configuration data for registering new users as member will be returned, otherwise will return the configuration data for registering as broker.", - "schema" : { - "type" : "boolean" - } - } ], - "tags" : [ "Users" ], - "responses" : { - "200" : { - "description" : "An object containing the data", + }, + "post" : { + "operationId" : "createUser", + "summary" : "Registers a new user", + "description" : "Can either be a public registration, requiring no authorization, or a user registration by an administrator or broker. The public registration normally requires a CAPTCHA challenge to prevent bots. On user registration the following data is also created:\n* Address;\n* Mobile phone;\n* Landline phone;\n* Images.\n\nAfter the registration those data are managed separately than the user profile data.", + "parameters" : [ ], + "tags" : [ "Users" ], + "responses" : { + "201" : { + "description" : "The result of the registration", + "headers" : { + "Location" : { + "description" : "URL for viewing the registered user's profile", + "schema" : { + "type" : "string" + } + } + }, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/UserDataForNew" + "$ref" : "#/components/schemas/UserRegistrationResult" } } } @@ -2606,6 +2984,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -2616,28 +3004,290 @@ } } } + }, + "requestBody" : { + "description" : "The user to be registered", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UserNew" + } + } + } } } }, - "/users/{user}" : { + "/users/export/{format}" : { "parameters" : [ { - "$ref" : "#/components/parameters/user" + "$ref" : "#/components/parameters/format" } ], "get" : { - "operationId" : "viewUser", - "summary" : "View a user / operator details", - "description" : "Returns the profile information of either a user or operator.", + "operationId" : "exportUsers", + "summary" : "Exports the user search results to a file", + "description" : "Generates a file containing the search results. The available export formats are returned in `GET /users/data-for-search`.", "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "name" : "activationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum user activation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "addressResult", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/UserAddressResultEnum" + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Either id or a principal (login name, e-mail, etc) for brokers", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "contactsOwner", + "in" : "query", + "required" : false, + "description" : "Indicates the (managed) user to exclude contacts when `excludecontacts` is set. Defaults to the logged user.", + "schema" : { + "type" : "string" + } + }, { + "name" : "creationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum user creation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "excludeContacts", + "in" : "query", + "required" : false, + "description" : "When set to `true` will not return any user that is already a contact of the user indicated on `contactsOwner` (the logged user if not set).", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "fromMenu", + "in" : "query", + "required" : false, + "description" : "When set to true the search will be restricted to those groups defined for the user search menu, if false then for those defined in the 'Search users on groups' product setting (or in the configuration in case of guests).", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Either id or internal names of groups / group sets", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "ignoreProfileFieldsInList", + "in" : "query", + "required" : false, + "description" : "When set to `true`, instead of returning users with corresponding profile fields set on list, will return them with `display` and `shortDisplay`.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "includeGroup", + "in" : "query", + "required" : false, + "description" : "When set to `true` and the logged user has permission to view user groups, will return the `group` property on users.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "includeGroupSet", + "in" : "query", + "required" : false, + "description" : "When set to `true` and the logged user has permission to view user group sets, will return the `groupSet` property on users.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "keywords", + "in" : "query", + "required" : false, + "description" : "Textual search keywords. Sometimes, like in user search, the fields matched depends on what is configured on the products.", + "schema" : { + "type" : "string" + } + }, { + "name" : "lastLoginPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum user last login date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "latitude", + "in" : "query", + "required" : false, + "description" : "The reference latitude for distance searches", + "schema" : { + "type" : "number", + "format" : "double" + } + }, { + "name" : "longitude", + "in" : "query", + "required" : false, + "description" : "The reference longitude for distance searches", + "schema" : { + "type" : "number", + "format" : "double" + } + }, { + "name" : "mainBrokerOnly", + "in" : "query", + "required" : false, + "description" : "When set to `true`, will match only users that have the brokers as set in the `brokers` parameter as main broker.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "maxDistance", + "in" : "query", + "required" : false, + "description" : "Maximum straight-line distance between the informed location and the resulting address. Is measured either in kilometers or miles, depending on the configuration. Only accepted if both `longitude` and `latitude` parameters are passed with the actual reference position.", + "schema" : { + "type" : "number", + "format" : "double" + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/UserOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "profileFields", + "in" : "query", + "required" : false, + "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "roles", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/RoleEnum" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "statuses", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/UserStatusEnum" + } + } + }, { + "name" : "usersToExclude", + "in" : "query", + "required" : false, + "description" : "Indicated the users to be excluded from the result", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "usersToInclude", + "in" : "query", + "required" : false, + "description" : "Indicated the users to be included in the result. Any other user not present in this list will be excluded from the result.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } } ], "tags" : [ "Users" ], "responses" : { "200" : { - "description" : "User / operator details", + "description" : "The file content", "content" : { - "application/json" : { + "*/*" : { "schema" : { - "$ref" : "#/components/schemas/UserView" + "type" : "string", + "format" : "binary" } } } @@ -2672,6 +3322,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -2683,36 +3343,61 @@ } } } - }, - "put" : { - "operationId" : "updateUser", - "summary" : "Save a user / operator profile fields", - "description" : "Saves the user / operator profile felds. Only the basic fields (full name, login name, e-mail) and custom fields can be saved with this operation. Addresses, phones and images must be managed either via the full profile (`GET /users/{user}/data-for-edit-profile` / `PUT /users/{user}/profile`) or through their own paths.", + } + }, + "/users/validate/{group}/{field}" : { + "get" : { + "operationId" : "validateUserRegistrationField", + "summary" : "Validates the value of a single field for user registration", + "description" : "Validates the value of a field which will be used for registering a user, returning either `204 No Content` if the field is valid or `200` with the error description if the field is invalid. Notice that the result is the validation error. If a `422` status code is returned it means that either the given `field` is invalid or the given `value` is empty.", "parameters" : [ { - "$ref" : "#/components/parameters/confirmationPassword" - } ], - "tags" : [ "Users" ], - "security" : [ { - "basic" : [ ] + "name" : "group", + "required" : true, + "in" : "path", + "description" : "The internal name or id of the group in which the user is being registered", + "schema" : { + "type" : "string" + } }, { - "session" : [ ] + "name" : "field", + "required" : true, + "in" : "path", + "description" : "One of: `name` (full name), `username` (login name), `email`, `mobilePhone`, `landLinePhone` or the internal name of a custom field.", + "schema" : { + "type" : "string" + } }, { - "accessClient" : [ ] + "name" : "value", + "required" : true, + "in" : "query", + "description" : "The value to be validated", + "schema" : { + "type" : "string" + } + }, { + "name" : "asMember", + "required" : false, + "in" : "query", + "description" : "Flag required only when the authenticated user is a member and a broker, in that case we need to distingish between both. If true then the groups returned will be those allowed as member, otherwise will return the goups allowed as broker.", + "schema" : { + "type" : "boolean" + } } ], + "tags" : [ "Users" ], "responses" : { - "204" : { - "description" : "If the save is correct, nothing is returned" - }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", + "200" : { + "description" : "The validation error if the field is invalid", "content" : { - "application/json" : { + "text/plain" : { "schema" : { - "$ref" : "#/components/schemas/ConflictError" + "type" : "string" } } } }, + "204" : { + "description" : "No content if the field is valid" + }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", "content" : { @@ -2763,41 +3448,36 @@ } } } - }, - "requestBody" : { - "description" : "The user / operator to be saved", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/UserEdit" - } - } - } } - }, - "delete" : { - "operationId" : "deletePendingUser", - "summary" : "Permanently removes a pending user", - "description" : "This operation physically removes user pending registration validation, that is, the user `status` is `pending`. If the user registration was ever validated, this operation will fail.", + } + }, + "/users/groups-for-registration" : { + "get" : { + "operationId" : "getGroupsForUserRegistration", + "summary" : "Returns the groups the authenticated user or guest can register on", + "description" : "Returns the list of groups the authenticated user can use to perform a new user registration. If authenticated as guest, will return the groups currently set for public registration. When there is an authenticated administrator, broker or member, will be the configured groups for new users.", "tags" : [ "Users" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] + "parameters" : [ { + "$ref" : "#/components/parameters/fields" }, { - "accessClient" : [ ] + "name" : "asMember", + "required" : false, + "in" : "query", + "description" : "Flag required only when the authenticated user is a member and a broker, in that case we need to distingish between both. If true then the groups returned will be those allowed as member, otherwise will return the goups allowed as broker.", + "schema" : { + "type" : "boolean" + } } ], "responses" : { - "204" : { - "description" : "The pending user was deleted" - }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", + "200" : { + "description" : "The list of groups", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ConflictError" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/GroupForRegistration" + } } } } @@ -2845,31 +3525,32 @@ } } }, - "/users/{user}/data-for-edit" : { - "get" : { - "operationId" : "getUserDataForEdit", - "summary" : "Get configuration data to edit a user / operator profile", - "description" : "Returns data to edit a user / operator profile fields.", + "/users/validate/registration/{key}" : { + "post" : { + "deprecated" : true, + "x-remove-version" : 4.14, + "operationId" : "validateUserRegistrationDeprecated", + "summary" : "Validates an user registration via a key sent by e-mail", + "description" : "Use `POST /validate/registration/{key}`\n\n\nWhen a user is registered, and the configuration enables the validation, an e-mail is sent to user e-mail, with a link to verify it. In this case, only after verifying the e-mail the user is activated. This operation effectively verifies the e-mail and performs the user activation. However, depending on the settings, the initial user status might be blocked or inactive.", "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/user" + "name" : "key", + "required" : true, + "in" : "path", + "description" : "The validation key sent via e-mail", + "schema" : { + "type" : "string" + } } ], "tags" : [ "Users" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], "responses" : { "200" : { - "description" : "User / operator profile fields details", + "description" : "Returns details about the verified user", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/UserDataForEdit" + "$ref" : "#/components/schemas/UserRegistrationResult" } } } @@ -2917,24 +3598,30 @@ } } }, - "/users/{user}/data-for-edit-profile" : { - "get" : { - "operationId" : "getDataForEditFullProfile", - "summary" : "Returns data for editing the full profile of a user / operator", - "description" : "The returned data contains all profile-related elements of a user or operator - profile fields, phones, addresses, images and additional contact information. Operators cannot have addresses, images or additional contact information, so these will not be sent.", + "/users/validate/email-change/{key}" : { + "post" : { + "deprecated" : true, + "x-remove-version" : 4.14, + "operationId" : "validateEmailChangeDeprecated", + "summary" : "Validates an e-mail via a validation key", + "description" : "Use `POST /validate/email-change/{key}`\n\n\nWhen the user e-mail is changed, and the configuration enables the validation, an e-mail is sent to the new user e-mail, with a link to verify it. In this case, only after verifying the new e-mail it is effectively set as the new e-mail. This operation effectively verifies the new e-mail.", "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/user" + "name" : "key", + "required" : true, + "in" : "path", + "description" : "The validation key sent via e-mail", + "schema" : { + "type" : "string" + } } ], "tags" : [ "Users" ], "responses" : { "200" : { - "description" : "The data for editing the full profile of the user / operator", + "description" : "Returns the id of the user that had the e-mail verified", "content" : { - "application/json" : { + "text/plain" : { "schema" : { - "$ref" : "#/components/schemas/DataForEditFullProfile" + "type" : "string" } } } @@ -2982,26 +3669,487 @@ } } }, - "/users/{user}/profile" : { - "post" : { - "operationId" : "saveUserFullProfile", - "summary" : "Saves the full profile at once", - "description" : "Saves in a single, transactional operation, the full user / operator profile: edition of the profile fields and creating / modifying / removing phones, addresses, additional contacts and images. Operators can never have addresses, additional contacts or images, so they don't apply to operators.", + "/users/data-for-new" : { + "get" : { + "operationId" : "getUserDataForNew", + "summary" : "Get configuration data for registering new users", + "description" : "Almost every aspect of a user profile is configurable in Cyclos, such as enabled basic profile fields, custom profile fields, address fields, phone configuration and so on. As such, if a front-end needs to be robust to such a dynamic nature, it should get this information in order to create a correct registration form.", "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/user" + "name" : "group", + "required" : true, + "in" : "query", + "description" : "The intial group for the new user", + "schema" : { + "type" : "string" + } }, { - "$ref" : "#/components/parameters/confirmationPassword" + "name" : "broker", + "required" : false, + "in" : "query", + "description" : "The broker for the new user. Only used if the authenticated user is an administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "asMember", + "required" : false, + "in" : "query", + "description" : "Flag required only when the authenticated user is a member and a broker, in that case we need to distingish between both. If true then the configuration data for registering new users as member will be returned, otherwise will return the configuration data for registering as broker.", + "schema" : { + "type" : "boolean" + } } ], "tags" : [ "Users" ], - "security" : [ { + "responses" : { + "200" : { + "description" : "An object containing the data", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UserDataForNew" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/users/{user}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], + "get" : { + "operationId" : "viewUser", + "summary" : "View a user / operator details", + "description" : "Returns the profile information of either a user or operator.", + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], + "tags" : [ "Users" ], + "responses" : { + "200" : { + "description" : "User / operator details", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UserView" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + }, + "put" : { + "operationId" : "updateUser", + "summary" : "Save a user / operator profile fields", + "description" : "Saves the user / operator profile felds. Only the basic fields (full name, login name, e-mail) and custom fields can be saved with this operation. Addresses, phones and images must be managed either via the full profile (`GET /users/{user}/data-for-edit-profile` / `PUT /users/{user}/profile`) or through their own paths.", + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + } ], + "tags" : [ "Users" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "responses" : { + "204" : { + "description" : "If the save is correct, nothing is returned" + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConflictError" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + }, + "requestBody" : { + "description" : "The user / operator to be saved", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UserEdit" + } + } + } + } + }, + "delete" : { + "operationId" : "deletePendingUser", + "summary" : "Permanently removes a pending user", + "description" : "This operation physically removes user pending registration validation, that is, the user `status` is `pending`. If the user registration was ever validated, this operation will fail.", + "tags" : [ "Users" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "responses" : { + "204" : { + "description" : "The pending user was deleted" + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConflictError" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/users/{user}/data-for-edit" : { + "get" : { + "operationId" : "getUserDataForEdit", + "summary" : "Get configuration data to edit a user / operator profile", + "description" : "Returns data to edit a user / operator profile fields.", + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/user" + } ], + "tags" : [ "Users" ], + "security" : [ { "basic" : [ ] }, { "session" : [ ] }, { "accessClient" : [ ] } ], + "responses" : { + "200" : { + "description" : "User / operator profile fields details", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UserDataForEdit" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/users/{user}/data-for-edit-profile" : { + "get" : { + "operationId" : "getDataForEditFullProfile", + "summary" : "Returns data for editing the full profile of a user / operator", + "description" : "The returned data contains all profile-related elements of a user or operator - profile fields, phones, addresses, images and additional contact information. Operators cannot have addresses, images or additional contact information, so these will not be sent.", + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/user" + } ], + "tags" : [ "Users" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + }, { + "oidc" : [ "profile_write" ] + } ], + "responses" : { + "200" : { + "description" : "The data for editing the full profile of the user / operator", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DataForEditFullProfile" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/users/{user}/profile" : { + "post" : { + "operationId" : "saveUserFullProfile", + "summary" : "Saves the full profile at once", + "description" : "Saves in a single, transactional operation, the full user / operator profile: edition of the profile fields and creating / modifying / removing phones, addresses, additional contacts and images. Operators can never have addresses, additional contacts or images, so they don't apply to operators.", + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/user" + }, { + "$ref" : "#/components/parameters/confirmationPassword" + } ], + "tags" : [ "Users" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + }, { + "oidc" : [ "profile_write" ] + } ], "responses" : { "200" : { "description" : "The generated identifiers for created entities", @@ -3113,7 +4261,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum user activation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -3134,7 +4281,6 @@ "in" : "query", "required" : false, "description" : "Either id or a principal (login name, e-mail, etc) for brokers", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -3142,12 +4288,19 @@ "type" : "string" } } + }, { + "name" : "contactsOwner", + "in" : "query", + "required" : false, + "description" : "Indicates the (managed) user to exclude contacts when `excludecontacts` is set. Defaults to the logged user.", + "schema" : { + "type" : "string" + } }, { "name" : "creationPeriod", "in" : "query", "required" : false, "description" : "The minimum / maximum user creation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -3160,7 +4313,15 @@ "name" : "excludeContacts", "in" : "query", "required" : false, - "description" : "When set to `true` will not return any user that is already a contact of the currently authenticated user.", + "description" : "When set to `true` will not return any user that is already a contact of the user indicated on `contactsOwner` (the logged user if not set).", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "fromMenu", + "in" : "query", + "required" : false, + "description" : "When set to true the search will be restricted to those groups defined for the user search menu, if false then for those defined in the 'Search users on groups' product setting (or in the configuration in case of guests).", "schema" : { "type" : "boolean" } @@ -3169,7 +4330,6 @@ "in" : "query", "required" : false, "description" : "Either id or internal names of groups / group sets", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -3214,7 +4374,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum user last login date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -3288,7 +4447,6 @@ "in" : "query", "required" : false, "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -3301,19 +4459,25 @@ "in" : "query", "required" : false, "description" : "", - "style" : "simple", "schema" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/RoleEnum" } } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } }, { "name" : "statuses", "in" : "query", "required" : false, "description" : "", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -3325,7 +4489,6 @@ "in" : "query", "required" : false, "description" : "Indicated the users to be excluded from the result", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -3338,7 +4501,6 @@ "in" : "query", "required" : false, "description" : "Indicated the users to be included in the result. Any other user not present in this list will be excluded from the result.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -3525,7 +4687,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum user creation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -3547,7 +4708,6 @@ "in" : "query", "required" : false, "description" : "An array of operator group ids", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -3573,12 +4733,19 @@ "type" : "integer", "format" : "int32" } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } }, { "name" : "statuses", "in" : "query", "required" : false, "description" : "", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -3588,7 +4755,7 @@ } ], "responses" : { "200" : { - "description" : "The users matching the criteria", + "description" : "The operators matching the criteria", "headers" : { "X-Total-Count" : { "schema" : { @@ -3620,7 +4787,7 @@ "schema" : { "type" : "array", "items" : { - "$ref" : "#/components/schemas/UserResult" + "$ref" : "#/components/schemas/OperatorResult" } } } @@ -3929,7 +5096,7 @@ "schema" : { "type" : "array", "items" : { - "$ref" : "#/components/schemas/UserResult" + "$ref" : "#/components/schemas/OperatorResult" } } } @@ -9291,281 +10458,6 @@ } } }, - "/contactInfos/{id}/image" : { - "post" : { - "operationId" : "uploadContactInfoImageDeprecated", - "deprecated" : true, - "summary" : "This operation is deprecated, use `POST /contact-infos/{id}/image` instead.", - "x-remove-version" : 4.13, - "description" : "Use `POST /contact-infos/{id}/image`\n\n\nSaves the given image for the additional contact information. If the given additional contact information already has an image, the old one is removed, and the current image is saved in its place.", - "tags" : [ "Images" ], - "parameters" : [ { - "$ref" : "#/components/parameters/id" - }, { - "name" : "name", - "description" : "The name for the new image. If not informed will fall back to the original file name in the form data", - "in" : "query", - "required" : false, - "schema" : { - "type" : "string" - } - } ], - "responses" : { - "201" : { - "description" : "The image is saved, its id is returned in the body and the URL to get the content is returned in the `Location` header", - "headers" : { - "Location" : { - "description" : "URL for obtaining the image content", - "schema" : { - "type" : "string" - } - } - }, - "content" : { - "text/plain" : { - "schema" : { - "type" : "string" - } - } - } - }, - "401" : { - "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/UnauthorizedError" - } - } - } - }, - "403" : { - "description" : "Permission denied for such operation", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ForbiddenError" - } - } - } - }, - "404" : { - "description" : "An expected data was not found", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/NotFoundError" - } - } - } - }, - "500" : { - "description" : "Unexpected error", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Error" - } - } - } - } - }, - "requestBody" : { - "content" : { - "multipart/form-data" : { - "schema" : { - "type" : "object", - "properties" : { - "image" : { - "type" : "string", - "format" : "binary", - "description" : "The image being uploaded" - } - } - } - } - } - } - } - }, - "/images/{kind}/{file}" : { - "get" : { - "operationId" : "getImageContentDeprecated", - "summary" : "Returns an image content", - "description" : "Use `GET /images/{idOrKey}/content` instead. Generally clients should use the `Image.url` property, which is always correct.\n\n\nReturns the content of an image, given the image kind and key. When neither `width` nor `height` are specified, returns the original content. The original ratio is always maintained. When only of one of the dimensions is specified, it is used as maximum, and the other is calculated. When both are informed, the maximum size with the original ratio that fits both dimensions is used.", - "tags" : [ "Images" ], - "deprecated" : true, - "x-remove-version" : 4.13, - "parameters" : [ { - "name" : "kind", - "in" : "path", - "required" : false, - "schema" : { - "$ref" : "#/components/schemas/ImageKind" - } - }, { - "name" : "file", - "in" : "path", - "required" : true, - "description" : "The file name. This is not the original uploaded file name, but a generated one.", - "x-dotInPath" : true, - "schema" : { - "type" : "string" - } - }, { - "name" : "width", - "in" : "query", - "required" : false, - "description" : "The requested image width", - "schema" : { - "type" : "integer" - } - }, { - "name" : "height", - "in" : "query", - "required" : false, - "description" : "The requested file height", - "schema" : { - "type" : "integer" - } - } ], - "responses" : { - "200" : { - "description" : "The image content", - "content" : { - "image/*" : { - "schema" : { - "type" : "string", - "format" : "binary" - } - } - } - }, - "401" : { - "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/UnauthorizedError" - } - } - } - }, - "403" : { - "description" : "Permission denied for such operation", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ForbiddenError" - } - } - } - }, - "404" : { - "description" : "An expected data was not found", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/NotFoundError" - } - } - } - }, - "500" : { - "description" : "Unexpected error", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/images/{id}/content" : { - "get" : { - "operationId" : "getImageContentById", - "summary" : "Returns an image content by id", - "description" : "Use `GET /images/{idOrKey}/content` instead. Generally clients should use the `Image.url` property, which is always correct.\n\n\nReturns the content of an image, given the image id. When neither `width` nor `height` are specified, returns the original content. The original ratio is always maintained. When only of one of the dimensions is specified, it is used as maximum, and the other is calculated. When both are informed, the maximum size with the original ratio that fits both dimensions is used.", - "tags" : [ "Images" ], - "deprecated" : true, - "x-remove-version" : 4.13, - "parameters" : [ { - "$ref" : "#/components/parameters/id" - }, { - "name" : "width", - "in" : "query", - "required" : false, - "description" : "The requested image width", - "schema" : { - "type" : "integer" - } - }, { - "name" : "height", - "in" : "query", - "required" : false, - "description" : "The requested file height", - "schema" : { - "type" : "integer" - } - } ], - "responses" : { - "200" : { - "description" : "The image content", - "content" : { - "image/*" : { - "schema" : { - "type" : "string", - "format" : "binary" - } - } - } - }, - "401" : { - "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/UnauthorizedError" - } - } - } - }, - "403" : { - "description" : "Permission denied for such operation", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ForbiddenError" - } - } - } - }, - "404" : { - "description" : "An expected data was not found", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/NotFoundError" - } - } - } - }, - "500" : { - "description" : "Unexpected error", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Error" - } - } - } - } - } - } - }, "/files/{id}/content" : { "get" : { "operationId" : "getRawFileContent", @@ -10060,7 +10952,6 @@ "in" : "query", "required" : false, "description" : "Either the ids or identification methods of individual document owners' brokers", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -10073,7 +10964,6 @@ "in" : "query", "required" : false, "description" : "The shared document categories", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -10094,7 +10984,6 @@ "in" : "query", "required" : false, "description" : "Either the ids or internal names of individual document owners' group", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -10102,6 +10991,14 @@ "type" : "string" } } + }, { + "name" : "keywords", + "in" : "query", + "required" : false, + "description" : "Used to filter documents containing that keywords in the the name or description (case insensitive)", + "schema" : { + "type" : "string" + } }, { "name" : "page", "in" : "query", @@ -10127,6 +11024,14 @@ "schema" : { "$ref" : "#/components/schemas/DocumentRangeEnum" } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } }, { "name" : "user", "in" : "query", @@ -11305,7 +12210,6 @@ "in" : "query", "required" : false, "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -11313,6 +12217,14 @@ "type" : "string" } } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } } ], "tags" : [ "Contacts" ], "security" : [ { @@ -11419,7 +12331,6 @@ "in" : "query", "required" : false, "description" : "Concat custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=tradeType:offer|search,extraDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `tradeType` is either `offer` or `search`, and whose `extraDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customValues=extraDate:|2001-12-31`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -11460,6 +12371,14 @@ "type" : "integer", "format" : "int32" } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } } ], "tags" : [ "Contacts" ], "security" : [ { @@ -13612,15 +14531,7 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "name" : "code", - "description" : "The device activation code.", - "in" : "query", - "required" : true, - "schema" : { - "type" : "string" - } - } ], + "parameters" : [ ], "responses" : { "200" : { "description" : "Successful activation.", @@ -13682,6 +14593,17 @@ } } } + }, + "requestBody" : { + "description" : "The parameters for activating a device.", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DeviceActivation" + } + } + } } } }, @@ -13757,11 +14679,11 @@ } } }, - "/devices/{id}" : { - "put" : { - "operationId" : "updateDevice", - "summary" : "Updates a device.", - "description" : "Updates a device. The device's owner and administrators / brokers with permissions can update a device. In case a PIN was already defined for the device then it's name will be updated too.", + "/devices/{id}/password-for-remove" : { + "get" : { + "operationId" : "getPasswordInputForRemoveDevice", + "summary" : "Returns a confirmation `PasswordInput` for removing a device, if any", + "description" : "If a confirmation password is required to remove a device, clients should invoke this operation prior to effectively removing the device, which will return the data regarding the confirmation password.", "tags" : [ "Devices" ], "security" : [ { "basic" : [ ] @@ -13771,18 +14693,17 @@ "accessClient" : [ ] } ], "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { "$ref" : "#/components/parameters/id" } ], "responses" : { - "204" : { - "description" : "The device was updated." - }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", + "200" : { + "description" : "The confirmation password input, or null", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ConflictError" + "$ref" : "#/components/schemas/PasswordInput" } } } @@ -13817,16 +14738,6 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { "description" : "Unexpected error", "content" : { @@ -13837,23 +14748,14 @@ } } } - }, - "requestBody" : { - "description" : "The parameters for saving a device.", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/DeviceEdit" - } - } - } } - }, - "delete" : { - "operationId" : "deleteDevice", - "summary" : "Removes a device.", - "description" : "Removes a device. The device's owner and administrators / brokers with permissions can remove a device.", + } + }, + "/devices/{id}" : { + "put" : { + "operationId" : "updateDevice", + "summary" : "Updates a device.", + "description" : "Updates a device. The device's owner and administrators / brokers with permissions can update a device. In case a PIN was already defined for the device then it's name will be updated too.", "tags" : [ "Devices" ], "security" : [ { "basic" : [ ] @@ -13867,7 +14769,7 @@ } ], "responses" : { "204" : { - "description" : "The device was removed." + "description" : "The device was updated." }, "409" : { "description" : "This operation expected an entity state, but it has resulted in a conflict", @@ -13909,136 +14811,6 @@ } } }, - "500" : { - "description" : "Unexpected error", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/device-confirmations/data-for-approval" : { - "get" : { - "operationId" : "dataForDeviceConfirmationApproval", - "summary" : "Return data for approve / reject device confirmations.", - "description" : "Can be invoked by guests to know if authentication is required for approve / reject pending device confirmations.", - "tags" : [ "DeviceConfirmations" ], - "parameters" : [ ], - "responses" : { - "200" : { - "description" : "The data for approval.", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/DataForDeviceConfirmationApproval" - } - } - } - }, - "401" : { - "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/UnauthorizedError" - } - } - } - }, - "403" : { - "description" : "Permission denied for such operation", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ForbiddenError" - } - } - } - }, - "404" : { - "description" : "An expected data was not found", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/NotFoundError" - } - } - } - }, - "500" : { - "description" : "Unexpected error", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/device-confirmations" : { - "post" : { - "operationId" : "createDeviceConfirmation", - "summary" : "Creates a pending device confirmation for the authenticated user.", - "description" : "Creates a device confirmation for an operation that must be confirmed. The confirmation will have a QR code that can be read (e.g with the Mobile App) to be approved / rejected by the device owner.", - "tags" : [ "DeviceConfirmations" ], - "parameters" : [ ], - "responses" : { - "201" : { - "description" : "Returns the identifier of the new confirmation.", - "headers" : { - "Location" : { - "description" : "URL for viewing the confirmation details", - "schema" : { - "type" : "string" - } - } - }, - "content" : { - "text/plain" : { - "schema" : { - "type" : "string" - } - } - } - }, - "401" : { - "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/UnauthorizedError" - } - } - } - }, - "403" : { - "description" : "Permission denied for such operation", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ForbiddenError" - } - } - } - }, - "404" : { - "description" : "An expected data was not found", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/NotFoundError" - } - } - } - }, "422" : { "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", "content" : { @@ -14061,24 +14833,22 @@ } }, "requestBody" : { - "description" : "The parameters for creating the confirmation.", + "description" : "The parameters for saving a device.", "required" : true, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/CreateDeviceConfirmation" + "$ref" : "#/components/schemas/DeviceEdit" } } } } - } - }, - "/device-confirmations/{id}" : { - "get" : { - "operationId" : "viewDeviceConfirmation", - "summary" : "Shows the details of a device confirmation for the authenticated user.", - "description" : "Shows the details of a device confirmation for the authenticated user.", - "tags" : [ "DeviceConfirmations" ], + }, + "delete" : { + "operationId" : "deleteDevice", + "summary" : "Removes a device.", + "description" : "Removes a device. The device's owner and administrators / brokers with permissions can remove a device.", + "tags" : [ "Devices" ], "security" : [ { "basic" : [ ] }, { @@ -14088,14 +14858,19 @@ } ], "parameters" : [ { "$ref" : "#/components/parameters/id" + }, { + "$ref" : "#/components/parameters/confirmationPassword" } ], "responses" : { - "200" : { - "description" : "The device confirmation details.", + "204" : { + "description" : "The device was removed." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/DeviceConfirmationView" + "$ref" : "#/components/schemas/ConflictError" } } } @@ -14141,32 +14916,261 @@ } } } - }, - "delete" : { - "operationId" : "deleteDeviceConfirmation", - "summary" : "Deletes a device confirmation for the authenticated user.", - "description" : "Deletes a device confirmation for the authenticated user.", + } + }, + "/device-confirmations/data-for-approval" : { + "get" : { + "operationId" : "dataForDeviceConfirmationApproval", + "summary" : "Return data for approve / reject device confirmations.", + "description" : "Can be invoked by guests to know if authentication is required for approve / reject pending device confirmations.", "tags" : [ "DeviceConfirmations" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], "parameters" : [ { - "$ref" : "#/components/parameters/id" + "name" : "deviceId", + "in" : "query", + "required" : true, + "description" : "The id of the device used to confirm operations.", + "schema" : { + "type" : "string" + } } ], "responses" : { - "204" : { - "description" : "The device confirmation was removed." - }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", + "200" : { + "description" : "The data for approval.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ConflictError" + "$ref" : "#/components/schemas/DataForDeviceConfirmationApproval" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/device-confirmations" : { + "post" : { + "operationId" : "createDeviceConfirmation", + "summary" : "Creates a pending device confirmation for the authenticated user.", + "description" : "Creates a device confirmation for an operation that must be confirmed. The confirmation will have a QR code that can be read (e.g with the Mobile App) to be approved / rejected by the device owner.", + "tags" : [ "DeviceConfirmations" ], + "parameters" : [ ], + "responses" : { + "201" : { + "description" : "Returns the identifier of the new confirmation.", + "headers" : { + "Location" : { + "description" : "URL for viewing the confirmation details", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "text/plain" : { + "schema" : { + "type" : "string" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + }, + "requestBody" : { + "description" : "The parameters for creating the confirmation.", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/CreateDeviceConfirmation" + } + } + } + } + } + }, + "/device-confirmations/{id}" : { + "get" : { + "operationId" : "viewDeviceConfirmation", + "summary" : "Shows the details of a device confirmation for the authenticated user.", + "description" : "Shows the details of a device confirmation for the authenticated user.", + "tags" : [ "DeviceConfirmations" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], + "responses" : { + "200" : { + "description" : "The device confirmation details.", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DeviceConfirmationView" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + }, + "delete" : { + "operationId" : "deleteDeviceConfirmation", + "summary" : "Deletes a device confirmation for the authenticated user.", + "description" : "Deletes a device confirmation for the authenticated user.", + "tags" : [ "DeviceConfirmations" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], + "responses" : { + "204" : { + "description" : "The device confirmation was removed." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConflictError" } } } @@ -15034,7 +16038,6 @@ "in" : "query", "required" : false, "description" : "References to access clients (id or token) used to perform / receive the transfer.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15047,7 +16050,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15060,10 +16062,22 @@ "name" : "broker", "in" : "query", "required" : false, - "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "description" : "DEPRECATED: Use `brokers` instead.\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", "schema" : { "type" : "string" } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } }, { "name" : "by", "in" : "query", @@ -15077,7 +16091,6 @@ "in" : "query", "required" : false, "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15098,7 +16111,6 @@ "in" : "query", "required" : false, "description" : "Transaction custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=rank:bronze|silver,documentDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `rank` is either `bronze` or `silver`, and whose `documentDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=documentDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a partial-match search using the dynamic value label. In this case a single value, prefixed or enclosed by single quotes should be used. For example: `customFields=dynamic:'business` or `customFields=dynamic:'business'`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15111,7 +16123,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15132,7 +16143,6 @@ "in" : "query", "required" : false, "description" : "List of transfers ids to be excluded from the result.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15153,7 +16163,6 @@ "in" : "query", "required" : false, "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15169,6 +16178,17 @@ "schema" : { "type" : "boolean" } + }, { + "name" : "kinds", + "in" : "query", + "required" : false, + "description" : "The kind of transfers to return", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransferKind" + } + } }, { "name" : "page", "in" : "query", @@ -15187,12 +16207,19 @@ "type" : "integer", "format" : "int32" } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } }, { "name" : "statuses", "in" : "query", "required" : false, "description" : "Transfer statuses used as search criteria. Each array element should be either the identifier or the status qualified internal name, composed by flow internal name, a dot, and the status internal name. For example, `loan.open` would be a valid internal name.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15213,7 +16240,6 @@ "in" : "query", "required" : false, "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15225,8 +16251,7 @@ "name" : "transferKinds", "in" : "query", "required" : false, - "description" : "", - "style" : "simple", + "description" : "DEPRECATED: Use `kinds` instead", "schema" : { "type" : "array", "items" : { @@ -15238,7 +16263,6 @@ "in" : "query", "required" : false, "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15409,7 +16433,6 @@ "in" : "query", "required" : false, "description" : "References to access clients (id or token) used to perform / receive the transfer.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15422,7 +16445,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15435,10 +16457,22 @@ "name" : "broker", "in" : "query", "required" : false, - "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "description" : "DEPRECATED: Use `brokers` instead.\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", "schema" : { "type" : "string" } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } }, { "name" : "by", "in" : "query", @@ -15452,7 +16486,6 @@ "in" : "query", "required" : false, "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15473,7 +16506,6 @@ "in" : "query", "required" : false, "description" : "Transaction custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=rank:bronze|silver,documentDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `rank` is either `bronze` or `silver`, and whose `documentDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=documentDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a partial-match search using the dynamic value label. In this case a single value, prefixed or enclosed by single quotes should be used. For example: `customFields=dynamic:'business` or `customFields=dynamic:'business'`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15486,7 +16518,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15507,7 +16538,6 @@ "in" : "query", "required" : false, "description" : "List of transfers ids to be excluded from the result.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15528,7 +16558,6 @@ "in" : "query", "required" : false, "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15544,12 +16573,23 @@ "schema" : { "type" : "boolean" } + }, { + "name" : "kinds", + "in" : "query", + "required" : false, + "description" : "The kind of transfers to return", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransferKind" + } + } }, { "name" : "orderBy", "in" : "query", "required" : false, "schema" : { - "$ref" : "#/components/schemas/AccountHistoryOrderByEnum" + "$ref" : "#/components/schemas/TransOrderByEnum" } }, { "name" : "page", @@ -15569,12 +16609,19 @@ "type" : "integer", "format" : "int32" } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } }, { "name" : "statuses", "in" : "query", "required" : false, "description" : "Transfer statuses used as search criteria. Each array element should be either the identifier or the status qualified internal name, composed by flow internal name, a dot, and the status internal name. For example, `loan.open` would be a valid internal name.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15595,7 +16642,6 @@ "in" : "query", "required" : false, "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15607,8 +16653,7 @@ "name" : "transferKinds", "in" : "query", "required" : false, - "description" : "", - "style" : "simple", + "description" : "DEPRECATED: Use `kinds` instead", "schema" : { "type" : "array", "items" : { @@ -15620,7 +16665,6 @@ "in" : "query", "required" : false, "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15720,16 +16764,18 @@ } } }, - "/{owner}/accounts/{accountType}/balances-history" : { + "/{owner}/accounts/{accountType}/export/{format}" : { "parameters" : [ { "$ref" : "#/components/parameters/owner" }, { "$ref" : "#/components/parameters/accountType" + }, { + "$ref" : "#/components/parameters/format" } ], "get" : { - "operationId" : "getAccountBalanceHistory", - "summary" : "Returns the account balances over time", - "description" : "Receives a period and an interval, returning the balance over each corresponding date. The maximum number of data points is 60, so it is possible to get the balances per day over 2 months. For larger periods, use weeks or months. When no period is given, assumes the beginning of current year or the account creation date, whichever is newer. When no interval is given, one is assumed. Also returns status of the given account", + "operationId" : "exportAccountHistory", + "summary" : "Exports the accounts history entries as file", + "description" : "Generates a file containing the search results. The available export formats are returned in `GET /{owner}/accounts/{accountType}/data-for-history`.", "tags" : [ "Accounts" ], "security" : [ { "basic" : [ ] @@ -15739,7 +16785,90 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "name" : "accessClients", + "in" : "query", + "required" : false, + "description" : "References to access clients (id or token) used to perform / receive the transfer.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "amountRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" + } + } + }, { + "name" : "broker", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `brokers` instead.\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "by", + "in" : "query", + "required" : false, + "description" : "Reference to the user that was authenticated when the transfer was performed. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "channels", + "in" : "query", + "required" : false, + "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "chargedBack", + "in" : "query", + "required" : false, + "description" : "When set to either `true` will only return transfers that were charged-back. When set to `false`, will only return transfers that were not charged-back. When left blank will not filter by this creterion.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "customFields", + "in" : "query", + "required" : false, + "description" : "Transaction custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=rank:bronze|silver,documentDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `rank` is either `bronze` or `silver`, and whose `documentDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=documentDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a partial-match search using the dynamic value label. In this case a single value, prefixed or enclosed by single quotes should be used. For example: `customFields=dynamic:'business` or `customFields=dynamic:'business'`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } }, { "name" : "datePeriod", "in" : "query", @@ -15748,34 +16877,287 @@ "schema" : { "type" : "array", "items" : { + "description" : "", "type" : "string", "format" : "date-time" } } }, { - "name" : "intervalUnit", + "name" : "direction", "in" : "query", "required" : false, - "description" : "The time unit for the data point interval", "schema" : { - "$ref" : "#/components/schemas/TimeFieldEnum" + "$ref" : "#/components/schemas/TransferDirectionEnum" } }, { - "name" : "intervalCount", + "name" : "excludedIds", "in" : "query", "required" : false, - "description" : "A data point every X units. For example, it is possible to request the balance every 3 days. Defaults to 1.", + "description" : "List of transfers ids to be excluded from the result.", "schema" : { - "type" : "integer" + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "fromCurrentAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include only transfers by the current access client.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "includeGeneratedByAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include or not the generated transfer. Only valid if there is at least one access client specified. For example if a `ticket` or `paymentRequest` was processed then a new transfer will be generated.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "kinds", + "in" : "query", + "required" : false, + "description" : "The kind of transfers to return", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransferKind" + } + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "statuses", + "in" : "query", + "required" : false, + "description" : "Transfer statuses used as search criteria. Each array element should be either the identifier or the status qualified internal name, composed by flow internal name, a dot, and the status internal name. For example, `loan.open` would be a valid internal name.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transactionNumber", + "in" : "query", + "required" : false, + "description" : "The transaction number of the matching transfer", + "schema" : { + "type" : "string" + } + }, { + "name" : "transferFilters", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transferKinds", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `kinds` instead", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransferKind" + } + } + }, { + "name" : "transferTypes", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Reference a user that should have either received / performed the transfer.", + "schema" : { + "type" : "string" } } ], "responses" : { "200" : { - "description" : "The account balances over each datapoint", + "description" : "The file content", "content" : { - "application/json" : { + "*/*" : { "schema" : { - "$ref" : "#/components/schemas/AccountBalanceHistoryResult" + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/{owner}/accounts/{accountType}/balances-history" : { + "parameters" : [ { + "$ref" : "#/components/parameters/owner" + }, { + "$ref" : "#/components/parameters/accountType" + } ], + "get" : { + "operationId" : "getAccountBalanceHistory", + "summary" : "Returns the account balances over time", + "description" : "Receives a period and an interval, returning the balance over each corresponding date. The maximum number of data points is 60, so it is possible to get the balances per day over 2 months. For larger periods, use weeks or months. When no period is given, assumes the beginning of current year or the account creation date, whichever is newer. When no interval is given, one is assumed. Also returns status of the given account", + "tags" : [ "Accounts" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "datePeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "intervalUnit", + "in" : "query", + "required" : false, + "description" : "The time unit for the data point interval", + "schema" : { + "$ref" : "#/components/schemas/TimeFieldEnum" + } + }, { + "name" : "intervalCount", + "in" : "query", + "required" : false, + "description" : "A data point every X units. For example, it is possible to request the balance every 3 days. Defaults to 1.", + "schema" : { + "type" : "integer" + } + } ], + "responses" : { + "200" : { + "description" : "The account balances over each datapoint", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/AccountBalanceHistoryResult" } } } @@ -15921,7 +17303,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum user activation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15942,7 +17323,6 @@ "in" : "query", "required" : false, "description" : "The minimum and / or maximum balance for users to be returned. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15956,7 +17336,6 @@ "in" : "query", "required" : false, "description" : "Either id or a principal (login name, e-mail, etc) for brokers", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15969,7 +17348,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum user creation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -15983,7 +17361,6 @@ "in" : "query", "required" : false, "description" : "Either id or internal names of groups / group sets", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16020,7 +17397,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum date of the last incoming transfer for users to be returned. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16034,7 +17410,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum user last login date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16048,7 +17423,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum date of the last outgoing transfer for users to be returned. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16097,7 +17471,6 @@ "in" : "query", "required" : false, "description" : "An array with 2 elements, describing the lower and upper medium balance bounds. If not specified, the range defined in the account type will be used. If that one is also not defined, there will be no definitions for balance levels. Both bounds need to be set as 2 element in the array, or it won't be considered.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16111,7 +17484,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum negative-since date for users to be returned. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16143,7 +17515,6 @@ "in" : "query", "required" : false, "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16151,12 +17522,19 @@ "type" : "string" } } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } }, { "name" : "usersToExclude", "in" : "query", "required" : false, "description" : "Indicated the users to be excluded from the result", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16169,7 +17547,6 @@ "in" : "query", "required" : false, "description" : "Indicated the users to be included in the result. Any other user not present in this list will be excluded from the result.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16260,7 +17637,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum user activation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16281,7 +17657,6 @@ "in" : "query", "required" : false, "description" : "The minimum and / or maximum balance for users to be returned. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16295,7 +17670,6 @@ "in" : "query", "required" : false, "description" : "Either id or a principal (login name, e-mail, etc) for brokers", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16308,7 +17682,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum user creation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16322,7 +17695,6 @@ "in" : "query", "required" : false, "description" : "Either id or internal names of groups / group sets", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16359,7 +17731,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum date of the last incoming transfer for users to be returned. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16373,7 +17744,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum user last login date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16387,7 +17757,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum date of the last outgoing transfer for users to be returned. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16436,7 +17805,6 @@ "in" : "query", "required" : false, "description" : "An array with 2 elements, describing the lower and upper medium balance bounds. If not specified, the range defined in the account type will be used. If that one is also not defined, there will be no definitions for balance levels. Both bounds need to be set as 2 element in the array, or it won't be considered.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16450,7 +17818,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum negative-since date for users to be returned. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16489,7 +17856,6 @@ "in" : "query", "required" : false, "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16497,12 +17863,19 @@ "type" : "string" } } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } }, { "name" : "usersToExclude", "in" : "query", "required" : false, "description" : "Indicated the users to be excluded from the result", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16515,7 +17888,6 @@ "in" : "query", "required" : false, "description" : "Indicated the users to be included in the result. Any other user not present in this list will be excluded from the result.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16607,15 +17979,15 @@ } } }, - "/{user}/accounts/data-for-limits" : { + "/accounts/{accountType}/user-balances/export/{format}" : { "parameters" : [ { - "$ref" : "#/components/parameters/user" + "$ref" : "#/components/parameters/format" } ], "get" : { - "operationId" : "getDataForUserBalanceLimits", - "summary" : "Returns data regarding the limits of all accounts of a given user.", - "description" : "Returns data regarding the limits of all accounts of a given user.", - "tags" : [ "BalanceLimits" ], + "operationId" : "exportUsersWithBalances", + "summary" : "Exports the user listing together with their balances as file", + "description" : "Generates a file containing the search results. The available export formats are returned in `GET /accounts/data-for-user-balances`.", + "tags" : [ "Accounts" ], "security" : [ { "basic" : [ ] }, { @@ -16624,15 +17996,368 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "name" : "accountType", + "in" : "path", + "required" : true, + "description" : "The account type", + "schema" : { + "type" : "string" + } + }, { + "name" : "activationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum user activation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "addressResult", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/UserAddressResultEnum" + } + }, { + "name" : "balanceRange", + "in" : "query", + "required" : false, + "description" : "The minimum and / or maximum balance for users to be returned. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "integer", + "format" : "int32" + } + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Either id or a principal (login name, e-mail, etc) for brokers", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "creationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum user creation date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Either id or internal names of groups / group sets", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "includeGroup", + "in" : "query", + "required" : false, + "description" : "When set to `true` and the logged user has permission to view user groups, will return the `group` property on users.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "includeGroupSet", + "in" : "query", + "required" : false, + "description" : "When set to `true` and the logged user has permission to view user group sets, will return the `groupSet` property on users.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "keywords", + "in" : "query", + "required" : false, + "description" : "Textual search keywords. Sometimes, like in user search, the fields matched depends on what is configured on the products.", + "schema" : { + "type" : "string" + } + }, { + "name" : "lastIncomingTransferPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum date of the last incoming transfer for users to be returned. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "lastLoginPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum user last login date. Only taken into account if searching as administrator or managing broker. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "lastOutgoingTransferPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum date of the last outgoing transfer for users to be returned. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "latitude", + "in" : "query", + "required" : false, + "description" : "The reference latitude for distance searches", + "schema" : { + "type" : "number", + "format" : "double" + } + }, { + "name" : "longitude", + "in" : "query", + "required" : false, + "description" : "The reference longitude for distance searches", + "schema" : { + "type" : "number", + "format" : "double" + } + }, { + "name" : "mainBrokerOnly", + "in" : "query", + "required" : false, + "description" : "When set to `true`, will match only users that have the brokers as set in the `brokers` parameter as main broker.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "maxDistance", + "in" : "query", + "required" : false, + "description" : "Maximum straight-line distance between the informed location and the resulting address. Is measured either in kilometers or miles, depending on the configuration. Only accepted if both `longitude` and `latitude` parameters are passed with the actual reference position.", + "schema" : { + "type" : "number", + "format" : "double" + } + }, { + "name" : "mediumBalanceRange", + "in" : "query", + "required" : false, + "description" : "An array with 2 elements, describing the lower and upper medium balance bounds. If not specified, the range defined in the account type will be used. If that one is also not defined, there will be no definitions for balance levels. Both bounds need to be set as 2 element in the array, or it won't be considered.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "integer", + "format" : "int32" + } + } + }, { + "name" : "negativeSincePeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum negative-since date for users to be returned. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/UsersWithBalanceOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "profileFields", + "in" : "query", + "required" : false, + "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "usersToExclude", + "in" : "query", + "required" : false, + "description" : "Indicated the users to be excluded from the result", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "usersToInclude", + "in" : "query", + "required" : false, + "description" : "Indicated the users to be included in the result. Any other user not present in this list will be excluded from the result.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } } ], "responses" : { "200" : { - "description" : "The user account limits data", + "description" : "The file content", "content" : { - "application/json" : { + "*/*" : { "schema" : { - "$ref" : "#/components/schemas/UserAccountBalanceLimitsListData" + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/{user}/accounts/data-for-limits" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], + "get" : { + "operationId" : "getDataForUserBalanceLimits", + "summary" : "Returns data regarding the limits of all accounts of a given user.", + "description" : "Returns data regarding the limits of all accounts of a given user.", + "tags" : [ "BalanceLimits" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], + "responses" : { + "200" : { + "description" : "The user account limits data", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UserAccountBalanceLimitsListData" } } } @@ -16933,10 +18658,22 @@ "name" : "broker", "in" : "query", "required" : false, - "description" : "Either the ids or identification methods of users' broker", + "description" : "DEPRECATED: Use `brokers` instead. Will be removed in 4.14. Either the ids or identification methods of users' broker", "schema" : { "type" : "string" } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Either the ids or identification methods of users' broker", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } }, { "name" : "by", "in" : "query", @@ -16966,7 +18703,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum customized limit. Is only used when `customLimit` is set to true. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -16988,7 +18724,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum customized upper limit. Is only used when `customUpperLimit` is set to true. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -17002,7 +18737,6 @@ "in" : "query", "required" : false, "description" : "Either the ids or internal names of user group", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -17035,6 +18769,14 @@ "type" : "integer", "format" : "int32" } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } }, { "name" : "user", "in" : "query", @@ -17127,12 +18869,15 @@ } } }, - "/transfers/{key}" : { + "/accounts/limits/export/{format}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/format" + } ], "get" : { - "operationId" : "viewTransfer", - "summary" : "Returns details about a transfer", - "description" : "Returns details about a transfer.", - "tags" : [ "Transfers" ], + "operationId" : "exportAccountBalanceLimits", + "summary" : "Exports the account balance limits results as file.", + "description" : "Generates a file containing the search results. The available export formats are returned in `GET /accounts/data-for-limits`.", + "tags" : [ "BalanceLimits" ], "security" : [ { "basic" : [ ] }, { @@ -17141,102 +18886,153 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "name" : "accountType", + "in" : "query", + "required" : false, + "description" : "Either id or internal name of the account type", + "schema" : { + "type" : "string" + } }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number", + "name" : "broker", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `brokers` instead. Will be removed in 4.14. Either the ids or identification methods of users' broker", "schema" : { "type" : "string" } - } ], - "responses" : { - "200" : { - "description" : "Transaction details", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/TransferView" - } - } - } - }, - "401" : { - "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/UnauthorizedError" - } - } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Either the ids or identification methods of users' broker", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" } - }, - "403" : { - "description" : "Permission denied for such operation", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ForbiddenError" - } - } + } + }, { + "name" : "by", + "in" : "query", + "required" : false, + "description" : "Either the id or identifier of the user that performed the change", + "schema" : { + "type" : "string" + } + }, { + "name" : "currency", + "in" : "query", + "required" : false, + "description" : "Either id or internal name of the currency", + "schema" : { + "type" : "string" + } + }, { + "name" : "customLimit", + "in" : "query", + "required" : false, + "description" : "When set, returns only accounts that have a custom (if true) or have default (false) lower limit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "customLimitRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum customized limit. Is only used when `customLimit` is set to true. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" } - }, - "404" : { - "description" : "An expected data was not found", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/NotFoundError" - } - } + } + }, { + "name" : "customUpperLimit", + "in" : "query", + "required" : false, + "description" : "When set, returns only accounts that have a custom (if true) or have default (false) upper limit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "customUpperLimitRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum customized upper limit. Is only used when `customUpperLimit` is set to true. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" } - }, - "500" : { - "description" : "Unexpected error", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Error" - } - } + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Either the ids or internal names of user group", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" } } - } - } - }, - "/transfers/{key}/chargeback" : { - "post" : { - "operationId" : "chargebackTransfer", - "summary" : "Perform the chargeback of a transfer", - "description" : "The chargeback generates a new transaction with `kind` = `chargeback`. A new transfer is generated with the same from / to, and negative amount. This will effectively return the amount to the original account. Only top-level transfers can be charged back. For example, a transfer used to charge a fee cannot be charged back. Also, the hability to chargeback a transfer depends on permissions and configuration like the maximum allowed time for the chargeback.", - "tags" : [ "Transfers" ], - "parameters" : [ { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number", + }, { + "name" : "kind", + "in" : "query", + "required" : false, "schema" : { - "type" : "string" + "$ref" : "#/components/schemas/BalanceLimitKind" } }, { - "$ref" : "#/components/parameters/confirmationPassword" + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Either the id or identifier of the account owner", + "schema" : { + "type" : "string" + } } ], "responses" : { - "201" : { - "description" : "The chargeback id", - "headers" : { - "Location" : { - "description" : "URL for viewing the created chargeback", - "schema" : { - "type" : "string" - } - } - }, + "200" : { + "description" : "The file content", "content" : { - "text/plain" : { + "*/*" : { "schema" : { - "type" : "string" + "type" : "string", + "format" : "binary" } } } @@ -17271,12 +19067,22 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { - "description" : "There was an error while creating the chargeback payment", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentError" + "$ref" : "#/components/schemas/Error" } } } @@ -17287,8 +19093,8 @@ "/transfers/data-for-search" : { "get" : { "operationId" : "getTransferDataForSearch", - "summary" : "Returns data for searching transfers over multiple accounts", - "description" : "Returns configuration data for searching transfers over multiple accounts. This operation can only be performed by administrators or brokers over managed users.", + "summary" : "Returns configuration data for searching transfers over multiple accounts.", + "description" : "Returns configuration data for searching transfers over multiple accounts.", "tags" : [ "Transfers" ], "security" : [ { "basic" : [ ] @@ -17357,8 +19163,8 @@ "/transfers" : { "get" : { "operationId" : "searchTransfers", - "summary" : "Searches for transfers over multiple accounts", - "description" : "Searches for transfers over multiple accounts. This operation can only be performed by administrators or brokers over managed users.", + "summary" : "Searches for transfers over multiple accounts.", + "description" : "Searches for transfers over multiple accounts. Only transfers which can really be seen are returned. So, admins can search over any visible member / system accounts. Brokers can search over their managed members or themselves, and regular members can only search own transfers.", "tags" : [ "Transfers" ], "security" : [ { "basic" : [ ] @@ -17374,7 +19180,6 @@ "in" : "query", "required" : false, "description" : "References to access clients (id or token) used to perform / receive the transfer.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -17387,7 +19192,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -17400,10 +19204,415 @@ "name" : "broker", "in" : "query", "required" : false, + "description" : "DEPRECATED: Use `brokers` instead.\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "by", + "in" : "query", + "required" : false, + "description" : "Reference to the user that was authenticated when the transfer was performed. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "channels", + "in" : "query", + "required" : false, + "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "chargedBack", + "in" : "query", + "required" : false, + "description" : "When set to either `true` will only return transfers that were charged-back. When set to `false`, will only return transfers that were not charged-back. When left blank will not filter by this creterion.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "currencies", + "in" : "query", + "required" : false, + "description" : "Either ids or internal names of the currency", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "currency", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `currencies` instead.\nEither id or internal name of the currency", + "schema" : { + "type" : "string" + } + }, { + "name" : "datePeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "excludedIds", + "in" : "query", + "required" : false, + "description" : "List of transfers ids to be excluded from the result.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "fromAccountType", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `fromAccountTypes` instead.\nEither ids or internal names of the origin account type", + "schema" : { + "type" : "string" + } + }, { + "name" : "fromAccountTypes", + "in" : "query", + "required" : false, + "description" : "Either ids or internal names of the origin account type", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "fromCurrentAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include only transfers by the current access client.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "includeGeneratedByAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include or not the generated transfer. Only valid if there is at least one access client specified. For example if a `ticket` or `paymentRequest` was processed then a new transfer will be generated.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "kinds", + "in" : "query", + "required" : false, + "description" : "The kind of transfers to return", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransferKind" + } + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "statuses", + "in" : "query", + "required" : false, + "description" : "Transfer statuses used as search criteria. Each array element should be either the identifier or the status qualified internal name, composed by flow internal name, a dot, and the status internal name. For example, `loan.open` would be a valid internal name.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "toAccountType", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `toAccountTypes` instead.\nEither ids or internal names of the destination account type", + "schema" : { + "type" : "string" + } + }, { + "name" : "toAccountTypes", + "in" : "query", + "required" : false, + "description" : "Either ids or internal names of the destination account type", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transactionNumber", + "in" : "query", + "required" : false, + "description" : "The transaction number of the matching transfer", + "schema" : { + "type" : "string" + } + }, { + "name" : "transferFilters", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transferKinds", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `kinds` instead", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransferKind" + } + } + }, { + "name" : "transferTypes", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Reference a user that should have either received / performed the transfer.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The users together with their balances", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransferResult" + } + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/transfers/export/{format}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/format" + } ], + "get" : { + "operationId" : "exportTransfers", + "summary" : "Exports the transfers search results as file", + "description" : "Generates a file containing the search results. The available export formats are returned in `GET /transfers/data-for-search`.", + "tags" : [ "Transfers" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "name" : "accessClients", + "in" : "query", + "required" : false, + "description" : "References to access clients (id or token) used to perform / receive the transfer.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "amountRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" + } + } + }, { + "name" : "broker", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `brokers` instead.\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", "schema" : { "type" : "string" } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } }, { "name" : "by", "in" : "query", @@ -17417,7 +19626,6 @@ "in" : "query", "required" : false, "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -17433,11 +19641,23 @@ "schema" : { "type" : "boolean" } + }, { + "name" : "currencies", + "in" : "query", + "required" : false, + "description" : "Either ids or internal names of the currency", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } }, { "name" : "currency", "in" : "query", "required" : false, - "description" : "Either id or internal name of the currency", + "description" : "DEPRECATED: Use `currencies` instead.\nEither id or internal name of the currency", "schema" : { "type" : "string" } @@ -17446,7 +19666,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -17460,7 +19679,6 @@ "in" : "query", "required" : false, "description" : "List of transfers ids to be excluded from the result.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -17472,10 +19690,22 @@ "name" : "fromAccountType", "in" : "query", "required" : false, - "description" : "Either id or internal name of the origin account type", + "description" : "DEPRECATED: Use `fromAccountTypes` instead.\nEither ids or internal names of the origin account type", "schema" : { "type" : "string" } + }, { + "name" : "fromAccountTypes", + "in" : "query", + "required" : false, + "description" : "Either ids or internal names of the origin account type", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } }, { "name" : "fromCurrentAccessClient", "in" : "query", @@ -17489,7 +19719,6 @@ "in" : "query", "required" : false, "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -17505,12 +19734,23 @@ "schema" : { "type" : "boolean" } + }, { + "name" : "kinds", + "in" : "query", + "required" : false, + "description" : "The kind of transfers to return", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransferKind" + } + } }, { "name" : "orderBy", "in" : "query", "required" : false, "schema" : { - "$ref" : "#/components/schemas/AccountHistoryOrderByEnum" + "$ref" : "#/components/schemas/TransOrderByEnum" } }, { "name" : "page", @@ -17530,12 +19770,19 @@ "type" : "integer", "format" : "int32" } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } }, { "name" : "statuses", "in" : "query", "required" : false, "description" : "Transfer statuses used as search criteria. Each array element should be either the identifier or the status qualified internal name, composed by flow internal name, a dot, and the status internal name. For example, `loan.open` would be a valid internal name.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -17547,10 +19794,22 @@ "name" : "toAccountType", "in" : "query", "required" : false, - "description" : "Either id or internal name of the destination account type", + "description" : "DEPRECATED: Use `toAccountTypes` instead.\nEither ids or internal names of the destination account type", "schema" : { "type" : "string" } + }, { + "name" : "toAccountTypes", + "in" : "query", + "required" : false, + "description" : "Either ids or internal names of the destination account type", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } }, { "name" : "transactionNumber", "in" : "query", @@ -17563,85 +19822,9007 @@ "name" : "transferFilters", "in" : "query", "required" : false, - "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", - "style" : "simple", + "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transferKinds", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `kinds` instead", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransferKind" + } + } + }, { + "name" : "transferTypes", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Reference a user that should have either received / performed the transfer.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The file content", + "content" : { + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/transfers/{key}" : { + "get" : { + "operationId" : "viewTransfer", + "summary" : "Returns details about a transfer", + "description" : "Returns details about a transfer.", + "tags" : [ "Transfers" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "Transaction details", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransferView" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/transfers/{key}/export/{format}" : { + "parameters" : [ { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number", + "schema" : { + "type" : "string" + } + }, { + "$ref" : "#/components/parameters/format" + } ], + "get" : { + "operationId" : "exportTransfer", + "summary" : "Exports the transfer details to a file.", + "description" : "Exports the transfer details to a file. The available formats are available in `TransferView`", + "tags" : [ "Transfers" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "responses" : { + "200" : { + "description" : "The file content", + "content" : { + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/transfers/{key}/chargeback" : { + "post" : { + "operationId" : "chargebackTransfer", + "summary" : "Perform the chargeback of a transfer", + "description" : "The chargeback generates a new transaction with `kind` = `chargeback`. A new transfer is generated with the same from / to, and negative amount. This will effectively return the amount to the original account. Only top-level transfers can be charged back. For example, a transfer used to charge a fee cannot be charged back. Also, the hability to chargeback a transfer depends on permissions and configuration like the maximum allowed time for the chargeback.", + "tags" : [ "Transfers" ], + "parameters" : [ { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number", + "schema" : { + "type" : "string" + } + }, { + "$ref" : "#/components/parameters/confirmationPassword" + } ], + "responses" : { + "201" : { + "description" : "The chargeback id", + "headers" : { + "Location" : { + "description" : "URL for viewing the created chargeback", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "text/plain" : { + "schema" : { + "type" : "string" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "There was an error while creating the chargeback payment", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentError" + } + } + } + } + } + } + }, + "/{owner}/transactions/data-for-search" : { + "get" : { + "operationId" : "getTransactionsDataForSearch", + "summary" : "Returns data for searching transactions of an account owner", + "description" : "Returns data which can be used to filter a transaction search", + "tags" : [ "Transactions" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/owner" + } ], + "responses" : { + "200" : { + "description" : "Data for searching transactions of an account owner", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransactionDataForSearch" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/{owner}/transactions" : { + "parameters" : [ { + "$ref" : "#/components/parameters/owner" + } ], + "get" : { + "operationId" : "searchTransactions", + "summary" : "Searches transactions of an account owner", + "description" : "Returns the transactions of a given account owner that match the specified criteria. Each result will will be relative to this owner. The amount may be positive or negative, depending on whether this owner has performed or received the transaction.", + "tags" : [ "Transactions" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "accessClients", + "in" : "query", + "required" : false, + "description" : "References to access clients (id or token) used to perform / receive the transfer.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "accountTypes", + "in" : "query", + "required" : false, + "description" : "The account types", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "amountRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" + } + } + }, { + "name" : "authorizationPerformedBy", + "in" : "query", + "required" : false, + "description" : "Id or other identifier (login name, email, etc) of the user that performed an authorization action (authorize, deny or cancel).", + "schema" : { + "type" : "string" + } + }, { + "name" : "authorizationStatuses", + "in" : "query", + "required" : false, + "description" : "Authorization statuses used as search criteria. When set, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionAuthorizationStatusEnum" + } + } + }, { + "name" : "authorized", + "in" : "query", + "required" : false, + "description" : "When set, will only return transactions that went through the authorization process (if true) or that never went through it (when false). In either case, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "broker", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `brokers` instead.\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "by", + "in" : "query", + "required" : false, + "description" : "Reference to the user that was authenticated when the transfer was performed. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "channels", + "in" : "query", + "required" : false, + "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "datePeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "direction", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransferDirectionEnum" + } + }, { + "name" : "excludedIds", + "in" : "query", + "required" : false, + "description" : "List of transfers ids to be excluded from the result.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "externalPaymentStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `externalPayment`.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExternalPaymentStatusEnum" + } + } + }, { + "name" : "fromCurrentAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include only transfers by the current access client.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "includeGeneratedByAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include or not the generated transfer. Only valid if there is at least one access client specified. For example if a `ticket` or `paymentRequest` was processed then a new transfer will be generated.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "kinds", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionKind" + } + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "paymentRequestExpiration", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum date for payment request expiration. Only affects payment requests. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "paymentRequestStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `paymentRequest`.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/PaymentRequestStatusEnum" + } + } + }, { + "name" : "recurringPaymentStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `recurringPayment`. If this filter is not empty then pending recurring payments will be excluded from the result. Pending recurring payments does not have a status.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/RecurringPaymentStatusEnum" + } + } + }, { + "name" : "scheduledPaymentStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `scheduledPayment`. If this filter is not empty then pending scheduled payments will be excluded from the result. Pending scheduled payments does not have a status.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ScheduledPaymentStatusEnum" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "ticketStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `ticket`.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TicketStatusEnum" + } + } + }, { + "name" : "transactionNumber", + "in" : "query", + "required" : false, + "description" : "The transaction number of the matching transfer", + "schema" : { + "type" : "string" + } + }, { + "name" : "transferFilters", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transferTypes", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Reference a user that should have either received / performed the transfer.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The transaction entries matching the criteria", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionResult" + } + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/{owner}/transactions/export/{format}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/owner" + }, { + "$ref" : "#/components/parameters/format" + } ], + "get" : { + "operationId" : "exportTransactions", + "summary" : "Exports the owner transactions search results as file", + "description" : "Generates a file containing the search results. The available export formats are returned in `GET /{owner}/transactions/data-for-search`.", + "tags" : [ "Transactions" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "name" : "accessClients", + "in" : "query", + "required" : false, + "description" : "References to access clients (id or token) used to perform / receive the transfer.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "accountTypes", + "in" : "query", + "required" : false, + "description" : "The account types", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "amountRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" + } + } + }, { + "name" : "authorizationPerformedBy", + "in" : "query", + "required" : false, + "description" : "Id or other identifier (login name, email, etc) of the user that performed an authorization action (authorize, deny or cancel).", + "schema" : { + "type" : "string" + } + }, { + "name" : "authorizationStatuses", + "in" : "query", + "required" : false, + "description" : "Authorization statuses used as search criteria. When set, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionAuthorizationStatusEnum" + } + } + }, { + "name" : "authorized", + "in" : "query", + "required" : false, + "description" : "When set, will only return transactions that went through the authorization process (if true) or that never went through it (when false). In either case, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "broker", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `brokers` instead.\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "by", + "in" : "query", + "required" : false, + "description" : "Reference to the user that was authenticated when the transfer was performed. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "channels", + "in" : "query", + "required" : false, + "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "datePeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "direction", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransferDirectionEnum" + } + }, { + "name" : "excludedIds", + "in" : "query", + "required" : false, + "description" : "List of transfers ids to be excluded from the result.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "externalPaymentStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `externalPayment`.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExternalPaymentStatusEnum" + } + } + }, { + "name" : "fromCurrentAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include only transfers by the current access client.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "includeGeneratedByAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include or not the generated transfer. Only valid if there is at least one access client specified. For example if a `ticket` or `paymentRequest` was processed then a new transfer will be generated.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "kinds", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionKind" + } + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "paymentRequestExpiration", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum date for payment request expiration. Only affects payment requests. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "paymentRequestStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `paymentRequest`.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/PaymentRequestStatusEnum" + } + } + }, { + "name" : "recurringPaymentStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `recurringPayment`. If this filter is not empty then pending recurring payments will be excluded from the result. Pending recurring payments does not have a status.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/RecurringPaymentStatusEnum" + } + } + }, { + "name" : "scheduledPaymentStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `scheduledPayment`. If this filter is not empty then pending scheduled payments will be excluded from the result. Pending scheduled payments does not have a status.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ScheduledPaymentStatusEnum" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "ticketStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `ticket`.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TicketStatusEnum" + } + } + }, { + "name" : "transactionNumber", + "in" : "query", + "required" : false, + "description" : "The transaction number of the matching transfer", + "schema" : { + "type" : "string" + } + }, { + "name" : "transferFilters", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transferTypes", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Reference a user that should have either received / performed the transfer.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The file content", + "content" : { + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/transactions/data-for-search" : { + "get" : { + "operationId" : "getTransactionsOverviewDataForSearch", + "summary" : "Returns data for searching transactions regardless of a owner", + "description" : "Returns data which can be used to filter a transaction search", + "tags" : [ "Transactions" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "pendingMyAuthorization", + "in" : "query", + "required" : false, + "schema" : { + "type" : "boolean" + }, + "description" : "When set to true will search for transactions which are currently pending authorization, and the authenticated user can authorize." + } ], + "responses" : { + "200" : { + "description" : "Data for searching transactions of an account owner", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransactionOverviewDataForSearch" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/transactions" : { + "get" : { + "operationId" : "searchTransactionsOverview", + "summary" : "Searches transactions regardless of a owner", + "description" : "Searches transactions regardless of a owner that match the specified criteria.", + "tags" : [ "Transactions" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "accessClients", + "in" : "query", + "required" : false, + "description" : "References to access clients (id or token) used to perform / receive the transfer.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "amountRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" + } + } + }, { + "name" : "authorizationPerformedBy", + "in" : "query", + "required" : false, + "description" : "Id or other identifier (login name, email, etc) of the user that performed an authorization action (authorize, deny or cancel).", + "schema" : { + "type" : "string" + } + }, { + "name" : "authorizationStatuses", + "in" : "query", + "required" : false, + "description" : "Authorization statuses used as search criteria. When set, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionAuthorizationStatusEnum" + } + } + }, { + "name" : "authorized", + "in" : "query", + "required" : false, + "description" : "When set, will only return transactions that went through the authorization process (if true) or that never went through it (when false). In either case, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "broker", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `brokers` instead.\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "by", + "in" : "query", + "required" : false, + "description" : "Reference to the user that was authenticated when the transfer was performed. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "channels", + "in" : "query", + "required" : false, + "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "currencies", + "in" : "query", + "required" : false, + "description" : "The currencies internal names or ids.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "datePeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "excludedIds", + "in" : "query", + "required" : false, + "description" : "List of transfers ids to be excluded from the result.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "externalPaymentStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `externalPayment`.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExternalPaymentStatusEnum" + } + } + }, { + "name" : "fromAccountTypes", + "in" : "query", + "required" : false, + "description" : "The source account types internal names or ids.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "fromCurrentAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include only transfers by the current access client.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "includeGeneratedByAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include or not the generated transfer. Only valid if there is at least one access client specified. For example if a `ticket` or `paymentRequest` was processed then a new transfer will be generated.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "kinds", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionKind" + } + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "paymentRequestExpiration", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum date for payment request expiration. Only affects payment requests. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "paymentRequestStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `paymentRequest`.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/PaymentRequestStatusEnum" + } + } + }, { + "name" : "pendingMyAuthorization", + "in" : "query", + "required" : false, + "description" : "When set to true will only return transactions (`payment`, `recurringPayment` or `scheduledPayment`) in pending authorization state that the logged user can authorize", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "recurringPaymentStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `recurringPayment`. If this filter is not empty then pending recurring payments will be excluded from the result. Pending recurring payments does not have a status.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/RecurringPaymentStatusEnum" + } + } + }, { + "name" : "scheduledPaymentStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `scheduledPayment`. If this filter is not empty then pending scheduled payments will be excluded from the result. Pending scheduled payments does not have a status.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ScheduledPaymentStatusEnum" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "ticketStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `ticket`.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TicketStatusEnum" + } + } + }, { + "name" : "toAccountTypes", + "in" : "query", + "required" : false, + "description" : "The source account types internal names or ids.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transactionNumber", + "in" : "query", + "required" : false, + "description" : "The transaction number of the matching transfer", + "schema" : { + "type" : "string" + } + }, { + "name" : "transferFilters", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transferTypes", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Reference a user that should have either received / performed the transfer.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The transaction entries matching the criteria", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionOverviewResult" + } + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/transactions/export/{format}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/format" + } ], + "get" : { + "operationId" : "exportTransactionsOverview", + "summary" : "Exports the transactions overview search results as file", + "description" : "Generates a file containing the search results. The available export formats are returned in `GET /transactions/data-for-search`.", + "tags" : [ "Transactions" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "name" : "accessClients", + "in" : "query", + "required" : false, + "description" : "References to access clients (id or token) used to perform / receive the transfer.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "amountRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" + } + } + }, { + "name" : "authorizationPerformedBy", + "in" : "query", + "required" : false, + "description" : "Id or other identifier (login name, email, etc) of the user that performed an authorization action (authorize, deny or cancel).", + "schema" : { + "type" : "string" + } + }, { + "name" : "authorizationStatuses", + "in" : "query", + "required" : false, + "description" : "Authorization statuses used as search criteria. When set, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionAuthorizationStatusEnum" + } + } + }, { + "name" : "authorized", + "in" : "query", + "required" : false, + "description" : "When set, will only return transactions that went through the authorization process (if true) or that never went through it (when false). In either case, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "broker", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `brokers` instead.\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "by", + "in" : "query", + "required" : false, + "description" : "Reference to the user that was authenticated when the transfer was performed. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "channels", + "in" : "query", + "required" : false, + "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "currencies", + "in" : "query", + "required" : false, + "description" : "The currencies internal names or ids.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "datePeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "excludedIds", + "in" : "query", + "required" : false, + "description" : "List of transfers ids to be excluded from the result.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "externalPaymentStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `externalPayment`.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExternalPaymentStatusEnum" + } + } + }, { + "name" : "fromAccountTypes", + "in" : "query", + "required" : false, + "description" : "The source account types internal names or ids.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "fromCurrentAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include only transfers by the current access client.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "includeGeneratedByAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include or not the generated transfer. Only valid if there is at least one access client specified. For example if a `ticket` or `paymentRequest` was processed then a new transfer will be generated.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "kinds", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionKind" + } + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "paymentRequestExpiration", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum date for payment request expiration. Only affects payment requests. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "paymentRequestStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `paymentRequest`.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/PaymentRequestStatusEnum" + } + } + }, { + "name" : "pendingMyAuthorization", + "in" : "query", + "required" : false, + "description" : "When set to true will only return transactions (`payment`, `recurringPayment` or `scheduledPayment`) in pending authorization state that the logged user can authorize", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "recurringPaymentStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `recurringPayment`. If this filter is not empty then pending recurring payments will be excluded from the result. Pending recurring payments does not have a status.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/RecurringPaymentStatusEnum" + } + } + }, { + "name" : "scheduledPaymentStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `scheduledPayment`. If this filter is not empty then pending scheduled payments will be excluded from the result. Pending scheduled payments does not have a status.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ScheduledPaymentStatusEnum" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "ticketStatuses", + "in" : "query", + "required" : false, + "description" : "Statuses used as search criteria applied only to transactions of kind `ticket`.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TicketStatusEnum" + } + } + }, { + "name" : "toAccountTypes", + "in" : "query", + "required" : false, + "description" : "The source account types internal names or ids.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transactionNumber", + "in" : "query", + "required" : false, + "description" : "The transaction number of the matching transfer", + "schema" : { + "type" : "string" + } + }, { + "name" : "transferFilters", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transferTypes", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Reference a user that should have either received / performed the transfer.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The file content", + "content" : { + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/transactions/{key}" : { + "get" : { + "operationId" : "viewTransaction", + "summary" : "Returns details about a transaction", + "description" : "Returns details about a transaction.", + "tags" : [ "Transactions" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "Transaction details", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransactionView" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/transactions/{key}/export/{format}" : { + "parameters" : [ { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number", + "schema" : { + "type" : "string" + } + }, { + "$ref" : "#/components/parameters/format" + } ], + "get" : { + "operationId" : "exportTransaction", + "summary" : "Exports the transaction details to a file.", + "description" : "Exports the transaction details to a file. The available formats are available in `TransactionView`", + "tags" : [ "Transactions" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "responses" : { + "200" : { + "description" : "The file content", + "content" : { + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/{owner}/installments/data-for-search" : { + "parameters" : [ { + "$ref" : "#/components/parameters/owner" + } ], + "get" : { + "operationId" : "getInstallmentsDataForSearch", + "summary" : "Returns data for searching installments of an account owner", + "description" : "Returns data which can be used to filter a installment search", + "tags" : [ "Installments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], + "responses" : { + "200" : { + "description" : "Data for searching installments of an account owner", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InstallmentDataForSearch" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/{owner}/installments" : { + "parameters" : [ { + "$ref" : "#/components/parameters/owner" + } ], + "get" : { + "operationId" : "searchInstallments", + "summary" : "Searches installments of an account owner", + "description" : "Returns the installments of a given account owner that match the specified criteria. Each result will will be relative to this owner. The amount may be positive or negative, depending on whether this owner has performed or received the transaction.", + "tags" : [ "Installments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "accessClients", + "in" : "query", + "required" : false, + "description" : "References to access clients (id or token) used to perform / receive the transfer.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "accountTypes", + "in" : "query", + "required" : false, + "description" : "The account types", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "amountRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" + } + } + }, { + "name" : "authorizationPerformedBy", + "in" : "query", + "required" : false, + "description" : "Id or other identifier (login name, email, etc) of the user that performed an authorization action (authorize, deny or cancel).", + "schema" : { + "type" : "string" + } + }, { + "name" : "authorizationStatuses", + "in" : "query", + "required" : false, + "description" : "Authorization statuses used as search criteria. When set, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionAuthorizationStatusEnum" + } + } + }, { + "name" : "authorized", + "in" : "query", + "required" : false, + "description" : "When set, will only return transactions that went through the authorization process (if true) or that never went through it (when false). In either case, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "broker", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `brokers` instead.\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "by", + "in" : "query", + "required" : false, + "description" : "Reference to the user that was authenticated when the transfer was performed. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "channels", + "in" : "query", + "required" : false, + "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "datePeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "direction", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransferDirectionEnum" + } + }, { + "name" : "excludedIds", + "in" : "query", + "required" : false, + "description" : "List of transfers ids to be excluded from the result.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "fromCurrentAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include only transfers by the current access client.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "includeGeneratedByAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include or not the generated transfer. Only valid if there is at least one access client specified. For example if a `ticket` or `paymentRequest` was processed then a new transfer will be generated.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "kinds", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionKind" + } + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "statuses", + "in" : "query", + "required" : false, + "description" : "Possible statuses for installments.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/InstallmentStatusEnum" + } + } + }, { + "name" : "transactionNumber", + "in" : "query", + "required" : false, + "description" : "The transaction number of the matching transfer", + "schema" : { + "type" : "string" + } + }, { + "name" : "transferFilters", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transferTypes", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Reference a user that should have either received / performed the transfer.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The installment entries matching the criteria", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/InstallmentResult" + } + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/{owner}/installments/export/{format}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/owner" + }, { + "$ref" : "#/components/parameters/format" + } ], + "get" : { + "operationId" : "exportInstallments", + "summary" : "Exports the owner installments search results as file", + "description" : "Generates a file containing the search results. The available export formats are returned in `GET /{owner}/installments/data-for-search`.", + "tags" : [ "Installments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "name" : "accessClients", + "in" : "query", + "required" : false, + "description" : "References to access clients (id or token) used to perform / receive the transfer.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "accountTypes", + "in" : "query", + "required" : false, + "description" : "The account types", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "amountRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" + } + } + }, { + "name" : "authorizationPerformedBy", + "in" : "query", + "required" : false, + "description" : "Id or other identifier (login name, email, etc) of the user that performed an authorization action (authorize, deny or cancel).", + "schema" : { + "type" : "string" + } + }, { + "name" : "authorizationStatuses", + "in" : "query", + "required" : false, + "description" : "Authorization statuses used as search criteria. When set, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionAuthorizationStatusEnum" + } + } + }, { + "name" : "authorized", + "in" : "query", + "required" : false, + "description" : "When set, will only return transactions that went through the authorization process (if true) or that never went through it (when false). In either case, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "broker", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `brokers` instead.\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "by", + "in" : "query", + "required" : false, + "description" : "Reference to the user that was authenticated when the transfer was performed. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "channels", + "in" : "query", + "required" : false, + "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "datePeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "direction", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransferDirectionEnum" + } + }, { + "name" : "excludedIds", + "in" : "query", + "required" : false, + "description" : "List of transfers ids to be excluded from the result.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "fromCurrentAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include only transfers by the current access client.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "includeGeneratedByAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include or not the generated transfer. Only valid if there is at least one access client specified. For example if a `ticket` or `paymentRequest` was processed then a new transfer will be generated.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "kinds", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionKind" + } + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "statuses", + "in" : "query", + "required" : false, + "description" : "Possible statuses for installments.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/InstallmentStatusEnum" + } + } + }, { + "name" : "transactionNumber", + "in" : "query", + "required" : false, + "description" : "The transaction number of the matching transfer", + "schema" : { + "type" : "string" + } + }, { + "name" : "transferFilters", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transferTypes", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Reference a user that should have either received / performed the transfer.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The file content", + "content" : { + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/installments/data-for-search" : { + "get" : { + "operationId" : "getInstallmentsOverviewDataForSearch", + "summary" : "Returns data for searching installments regardless of a owner", + "description" : "Returns data which can be used to filter a installment search", + "tags" : [ "Installments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], + "responses" : { + "200" : { + "description" : "Data for searching installments of an account owner", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InstallmentOverviewDataForSearch" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/installments" : { + "get" : { + "operationId" : "searchInstallmentsOverview", + "summary" : "Searches installments regardless of a owner", + "description" : "Searches installments regardless of a owner that match the specified criteria.", + "tags" : [ "Installments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "accessClients", + "in" : "query", + "required" : false, + "description" : "References to access clients (id or token) used to perform / receive the transfer.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "amountRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" + } + } + }, { + "name" : "authorizationPerformedBy", + "in" : "query", + "required" : false, + "description" : "Id or other identifier (login name, email, etc) of the user that performed an authorization action (authorize, deny or cancel).", + "schema" : { + "type" : "string" + } + }, { + "name" : "authorizationStatuses", + "in" : "query", + "required" : false, + "description" : "Authorization statuses used as search criteria. When set, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionAuthorizationStatusEnum" + } + } + }, { + "name" : "authorized", + "in" : "query", + "required" : false, + "description" : "When set, will only return transactions that went through the authorization process (if true) or that never went through it (when false). In either case, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "broker", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `brokers` instead.\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "by", + "in" : "query", + "required" : false, + "description" : "Reference to the user that was authenticated when the transfer was performed. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "channels", + "in" : "query", + "required" : false, + "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "currencies", + "in" : "query", + "required" : false, + "description" : "The currencies internal names or ids.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "datePeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "excludedIds", + "in" : "query", + "required" : false, + "description" : "List of transfers ids to be excluded from the result.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "fromAccountTypes", + "in" : "query", + "required" : false, + "description" : "The source account types internal names or ids.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "fromCurrentAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include only transfers by the current access client.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "includeGeneratedByAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include or not the generated transfer. Only valid if there is at least one access client specified. For example if a `ticket` or `paymentRequest` was processed then a new transfer will be generated.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "kinds", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionKind" + } + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "statuses", + "in" : "query", + "required" : false, + "description" : "Possible statuses for installments.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/InstallmentStatusEnum" + } + } + }, { + "name" : "toAccountTypes", + "in" : "query", + "required" : false, + "description" : "The source account types internal names or ids.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transactionNumber", + "in" : "query", + "required" : false, + "description" : "The transaction number of the matching transfer", + "schema" : { + "type" : "string" + } + }, { + "name" : "transferFilters", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transferTypes", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Reference a user that should have either received / performed the transfer.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The installment entries matching the criteria", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/InstallmentOverviewResult" + } + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/installments/export/{format}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/format" + } ], + "get" : { + "operationId" : "exportInstallmentsOverview", + "summary" : "Exports the installments overview search results as file", + "description" : "Generates a file containing the search results. The available export formats are returned in `GET /installments/data-for-search`.", + "tags" : [ "Installments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "name" : "accessClients", + "in" : "query", + "required" : false, + "description" : "References to access clients (id or token) used to perform / receive the transfer.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "amountRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" + } + } + }, { + "name" : "authorizationPerformedBy", + "in" : "query", + "required" : false, + "description" : "Id or other identifier (login name, email, etc) of the user that performed an authorization action (authorize, deny or cancel).", + "schema" : { + "type" : "string" + } + }, { + "name" : "authorizationStatuses", + "in" : "query", + "required" : false, + "description" : "Authorization statuses used as search criteria. When set, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionAuthorizationStatusEnum" + } + } + }, { + "name" : "authorized", + "in" : "query", + "required" : false, + "description" : "When set, will only return transactions that went through the authorization process (if true) or that never went through it (when false). In either case, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "broker", + "in" : "query", + "required" : false, + "description" : "DEPRECATED: Use `brokers` instead.\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "by", + "in" : "query", + "required" : false, + "description" : "Reference to the user that was authenticated when the transfer was performed. Is only taken into account if authenticated as administrator.", + "schema" : { + "type" : "string" + } + }, { + "name" : "channels", + "in" : "query", + "required" : false, + "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "currencies", + "in" : "query", + "required" : false, + "description" : "The currencies internal names or ids.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "datePeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "excludedIds", + "in" : "query", + "required" : false, + "description" : "List of transfers ids to be excluded from the result.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "fromAccountTypes", + "in" : "query", + "required" : false, + "description" : "The source account types internal names or ids.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "fromCurrentAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include only transfers by the current access client.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "includeGeneratedByAccessClient", + "in" : "query", + "required" : false, + "description" : "Flag indicating whether to include or not the generated transfer. Only valid if there is at least one access client specified. For example if a `ticket` or `paymentRequest` was processed then a new transfer will be generated.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "kinds", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionKind" + } + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/TransOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "statuses", + "in" : "query", + "required" : false, + "description" : "Possible statuses for installments.", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/InstallmentStatusEnum" + } + } + }, { + "name" : "toAccountTypes", + "in" : "query", + "required" : false, + "description" : "The source account types internal names or ids.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transactionNumber", + "in" : "query", + "required" : false, + "description" : "The transaction number of the matching transfer", + "schema" : { + "type" : "string" + } + }, { + "name" : "transferFilters", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "transferTypes", + "in" : "query", + "required" : false, + "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Reference a user that should have either received / performed the transfer.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The file content", + "content" : { + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/installments/{key}/process" : { + "parameters" : [ { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or a string in the form `number@transaction`, beging transaction either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "post" : { + "operationId" : "processInstallment", + "summary" : "Processes a installment, generating its corresponding transfer.", + "description" : "Processes an installment. The installment status must be either `scheduled`, `failed` or `blocked`. This action must be performed by the payer or manager.", + "tags" : [ "Installments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/confirmationPassword" + } ], + "responses" : { + "201" : { + "description" : "The installment is processed and the transfer is returned", + "headers" : { + "Location" : { + "description" : "URL for viewing the transfer details", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Transfer" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/installments/{key}/settle" : { + "parameters" : [ { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or a string in the form `number@transaction`, beging transaction either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "post" : { + "operationId" : "settleInstallment", + "summary" : "Settles a scheduled payment installment.", + "description" : "Settles a single installment. It must be a scheduled payment installment (not recurring payment), and the status must be either `scheduled`, `failed` or `blocked`. This action must be performed by the payment receiver or manager.", + "tags" : [ "Installments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + } ], + "responses" : { + "204" : { + "description" : "The installment is unblocked and nothing is returned." + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/{owner}/payments/data-for-perform" : { + "get" : { + "operationId" : "dataForPerformPayment", + "summary" : "Returns configuration data for performing a payment", + "description" : "Returns configuration data for performing a payment", + "tags" : [ "Payments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + }, { + "oidc" : [ "payment" ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/owner" + }, { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "to", + "in" : "query", + "required" : false, + "description" : "The payment destination. Either the string `system` for a payment to system or a user identification.", + "schema" : { + "type" : "string" + } + }, { + "name" : "type", + "in" : "query", + "required" : false, + "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). If no payment type is provided, the possible types will be returned, so the payer can choose.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The data for performing a payment", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DataForTransaction" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/{owner}/payments" : { + "post" : { + "operationId" : "performPayment", + "summary" : "Performs a payment from the given owner", + "description" : "Performs either a direct, scheduled or recurring payment from the owner indicated on the path to the owner specified on the body. The destination user should be informed in the `subject` parameter. If the `subject` is `system`, it will be a payment to a system account. The payment id is returned on the response, and a link to the transaction details is returned on the `Location` header.", + "tags" : [ "Payments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + }, { + "oidc" : [ "payment" ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/owner" + }, { + "$ref" : "#/components/parameters/confirmationPassword" + } ], + "responses" : { + "201" : { + "description" : "The created payment", + "headers" : { + "Location" : { + "description" : "URL for viewing the transaction details", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Transaction" + } + } + } + }, + "500" : { + "description" : "If a payment error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentError" + } + } + } + } + }, + "requestBody" : { + "description" : "The perform payment parameters", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PerformPayment" + } + } + } + } + } + }, + "/{owner}/payments/preview" : { + "post" : { + "operationId" : "previewPayment", + "summary" : "Previews a payment before performing it", + "description" : "Previews a payment, scheduled or recurring payment. The actual balance checking is not performed in the preview.", + "tags" : [ "Payments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + }, { + "oidc" : [ "payment" ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/owner" + }, { + "$ref" : "#/components/parameters/fields" + } ], + "responses" : { + "200" : { + "description" : "The payment preview", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentPreview" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + }, + "requestBody" : { + "description" : "The perform payment parameters", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PerformPayment" + } + } + } + } + } + }, + "/{owner}/payments/installments" : { + "get" : { + "operationId" : "calculatePerformPaymentInstallments", + "summary" : "Calculates the default installments for a scheduled payment", + "description" : "Used to calculate installments for a scheduled payment. Will return an installment every month. When later performing the payment, these can be (optionally) customized (such as changing some due dates or amounts) and used on the payment installments.", + "tags" : [ "Payments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + }, { + "oidc" : [ "payment" ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/owner" + }, { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "to", + "in" : "query", + "required" : true, + "description" : "The payment destination", + "schema" : { + "type" : "string" + } + }, { + "name" : "count", + "in" : "query", + "required" : true, + "description" : "The number of installments", + "schema" : { + "type" : "integer" + } + }, { + "name" : "amount", + "in" : "query", + "required" : true, + "description" : "The total scheduled payment amount", + "schema" : { + "type" : "string", + "format" : "number" + } + }, { + "name" : "currency", + "in" : "query", + "required" : false, + "description" : "The payment currency. Used when no `type` is not provided, to narrow the possible payment types by currency.", + "schema" : { + "type" : "string" + } + }, { + "name" : "type", + "in" : "query", + "required" : false, + "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). If not provided, will use the first possible type (possibly narrowed by the `currency` parameter). However, if more than one type is available, a validation error will be raised.", + "schema" : { + "type" : "string" + } + }, { + "name" : "firstDate", + "in" : "query", + "required" : false, + "description" : "The due date of the first installment. If none is provided, it is assumed that the first installment is paid immediately, and others will be with regular 1 month interval", + "schema" : { + "type" : "string", + "format" : "date-time" + } + } ], + "responses" : { + "200" : { + "description" : "The calculated installments", + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/PerformInstallment" + } + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/easy-invoices/qr-code/{to}" : { + "get" : { + "operationId" : "getEasyInvoiceQrCode", + "summary" : "Returns the QR-code image for the given easy invoice's parameters", + "description" : "The generated image could be scanned (e.g by the mobile application) to create a payment ready to be confirmed. The `easyInvoice` channel will be used to perform this operation, i.e the access and perform payment configurations of that channel will be applied.", + "tags" : [ "EasyInvoices" ], + "parameters" : [ { + "name" : "to", + "in" : "path", + "x-dotInPath" : true, + "required" : true, + "description" : "The user which will receive the easy invoice. Unlike other cases of user reference, in this case `self` cannot be used, because the URL may be shared with others, hence, `self` makes no sense.", + "schema" : { + "type" : "string" + } + }, { + "name" : "amount", + "in" : "query", + "required" : false, + "description" : "The easy invoice amount. If provided and the user has multiple currencies, either `type` or `currency` is required.", + "schema" : { + "type" : "string", + "format" : "number" + } + }, { + "name" : "currency", + "in" : "query", + "required" : false, + "description" : "The currency id or internal name. Either this or `type` should be informed if an `amount` was given and the user has multiple currencies.", + "schema" : { + "type" : "string" + } + }, { + "name" : "description", + "in" : "query", + "required" : false, + "description" : "The payment description", + "schema" : { + "type" : "string" + } + }, { + "name" : "type", + "in" : "query", + "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). Either this or `currency` should be informed if an `amount` was given and the user has multiple currencies.", + "schema" : { + "type" : "string" + } + }, { + "$ref" : "#/components/parameters/customFields" + }, { + "name" : "size", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/ImageSizeEnum" + } + } ], + "responses" : { + "200" : { + "description" : "The image content", + "content" : { + "image/png" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/easy-invoices/data-for-perform/{to}" : { + "get" : { + "operationId" : "dataForPerformEasyInvoice", + "summary" : "Returns data for an easy invoice to the given user.", + "description" : "An easy invoice is a pre-filled payment from the authenticated user to another user. Other users can use this for a payment template to that user, with pre-filled data. If an amount is specified, then either there must be only payment types of a single currency to the given user, or either a payment type or currency must be informed. The `easyInvoice` channel will be used to perform this operation, i.e the access and perform payment configurations of that channel will be applied.", + "tags" : [ "EasyInvoices" ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "to", + "in" : "path", + "x-dotInPath" : true, + "required" : true, + "description" : "The user which will receive the easy invoice. Unlike other cases of user reference, in this case `self` cannot be used, because the URL may be shared with others, hence, `self` makes no sense.", + "schema" : { + "type" : "string" + } + }, { + "name" : "amount", + "in" : "query", + "required" : false, + "description" : "The easy invoice amount. If provided and the user has multiple currencies, either `type` or `currency` is required.", + "schema" : { + "type" : "string", + "format" : "number" + } + }, { + "name" : "type", + "in" : "query", + "required" : false, + "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). Either this or `currency` should be informed if an `amount` was given and the user has multiple currencies.", + "schema" : { + "type" : "string" + } + }, { + "name" : "currency", + "in" : "query", + "required" : false, + "description" : "The currency id or internal name. Either this or `type` should be informed if an `amount` was given and the user has multiple currencies.", + "schema" : { + "type" : "string" + } + }, { + "$ref" : "#/components/parameters/customFields" + } ], + "responses" : { + "200" : { + "description" : "The data for easy invoice", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DataForEasyInvoice" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/easy-invoices" : { + "post" : { + "operationId" : "performEasyInvoice", + "summary" : "Performs a direct payment from an easy invoice.", + "description" : "Performs a direct payment from the authenticated user to the owner specified on the body. The destination user should be informed in the `subject` parameter (the subject `system` is not allowed). The payment id is returned on the response, and a link to the transaction details is returned on the `Location` header. The `easyInvoice` channel will be used to perform this operation, i.e the access and perform payment configurations of that channel will be applied.", + "tags" : [ "EasyInvoices" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/confirmationPassword" + } ], + "responses" : { + "201" : { + "description" : "The created payment", + "headers" : { + "Location" : { + "description" : "URL for viewing the transaction details", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Transaction" + } + } + } + }, + "500" : { + "description" : "If a payment error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentError" + } + } + } + } + }, + "requestBody" : { + "description" : "The perform payment parameters", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PerformPayment" + } + } + } + } + } + }, + "/easy-invoices/preview" : { + "post" : { + "operationId" : "previewEasyInvoice", + "summary" : "Previews a direct payment from an easy invoice before performing it.", + "description" : "Previews a direct payment from the logged created from an easy invoice. The actual balance checking is not performed in the preview. The `easyInvoice` channel will be used to perform this operation, i.e the access and perform payment configurations of that channel will be applied.", + "tags" : [ "EasyInvoices" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], + "responses" : { + "200" : { + "description" : "The payment preview", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentPreview" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + }, + "requestBody" : { + "description" : "The perform payment parameters", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PerformPayment" + } + } + } + } + } + }, + "/scheduled-payments/{key}/block" : { + "post" : { + "operationId" : "blockScheduledPayment", + "summary" : "Blocks a scheduled payment.", + "description" : "Blocks a scheduled payment, preventing its installments from being automatically processed. The scheduled payment status must be `open`. This action is to be performed by the scheduled payment payer.", + "tags" : [ "ScheduledPayments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "204" : { + "description" : "The scheduled payment is blocked and nothing is returned." + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/scheduled-payments/{key}/unblock" : { + "post" : { + "operationId" : "unblockScheduledPayment", + "summary" : "Unblocks a scheduled payment.", + "description" : "Unblocks a previously blocked scheduled payment The scheduled payment status must be `blocked`. This action is to be performed by the scheduled payment payer.", + "tags" : [ "ScheduledPayments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "204" : { + "description" : "The scheduled payment is unblocked and nothing is returned." + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/scheduled-payments/{key}/cancel" : { + "post" : { + "operationId" : "cancelScheduledPayment", + "summary" : "Cancels a scheduled payment.", + "description" : "Permanently cancels a scheduled payment. The scheduled payment status must be either `open` or `blocked`. This action is to be performed by the scheduled payment payer.", + "tags" : [ "ScheduledPayments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "204" : { + "description" : "The scheduled payment is canceled and nothing is returned." + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/scheduled-payments/{key}/settle-remaining" : { + "post" : { + "operationId" : "settleScheduledPayment", + "summary" : "Settles all remaining installments in a scheduled payment.", + "description" : "Settles all remaining installments, closing the scheduled payment. The scheduled payment status must be either `open` or `blocked`. This action is to be performed by the scheduled payment payee.", + "tags" : [ "ScheduledPayments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "204" : { + "description" : "The scheduled payment is closed and nothing is returned." + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/scheduled-payments/installments/{id}/process" : { + "post" : { + "operationId" : "processScheduledPaymentInstallment", + "deprecated" : true, + "x-remove-version" : 4.15, + "summary" : "DEPRECATED: Use `POST /installments/{key}/process` instead.\nProcesses a single scheduled payment installment.", + "description" : "Processes a single installment. The installment status must be either `scheduled`, `failed` or `blocked`. This action is to be performed by the scheduled payment payer.", + "tags" : [ "ScheduledPayments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "$ref" : "#/components/parameters/id" + } ], + "responses" : { + "201" : { + "description" : "The installment is processed and the transfer is returned", + "headers" : { + "Location" : { + "description" : "URL for viewing the transfer details", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Transfer" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/scheduled-payments/installments/{id}/settle" : { + "post" : { + "operationId" : "settleScheduledPaymentInstallment", + "deprecated" : true, + "x-remove-version" : 4.15, + "summary" : "DEPRECATED: Use `POST /installments/{key}/process` instead.\nSettles a single scheduled payment installment.", + "description" : "Settles a single installment. The installment status must be either `scheduled`, `failed` or `blocked`. This action is to be performed by the scheduled payment payee.", + "tags" : [ "ScheduledPayments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "$ref" : "#/components/parameters/id" + } ], + "responses" : { + "204" : { + "description" : "The installment is unblocked and nothing is returned." + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/recurring-payments/{key}/cancel" : { + "post" : { + "operationId" : "cancelRecurringPayment", + "summary" : "Cancels a recurring payment.", + "description" : "Permanently cancels a recurring payment. The recurring payment status must be `open`.", + "tags" : [ "RecurringPayments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "204" : { + "description" : "The recurring payment is canceled and nothing is returned." + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/recurring-payments/occurrences/{id}/process-failed" : { + "post" : { + "operationId" : "processFailedRecurringPaymentOccurrence", + "deprecated" : true, + "x-remove-version" : 4.15, + "summary" : "DEPRECATED: Use `POST /installments/{key}/process` instead.\nProcesses a failed recurring payment occurrence.", + "description" : "Processes a failed recurring payment occurrence. The occurrence status must be `failed`.", + "tags" : [ "RecurringPayments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "$ref" : "#/components/parameters/id" + } ], + "responses" : { + "201" : { + "description" : "The occurrence is processed and the transfer is returned", + "headers" : { + "Location" : { + "description" : "URL for viewing the transfer details", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Transfer" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/{owner}/payment-requests/data-for-send" : { + "get" : { + "operationId" : "dataForSendPaymentRequest", + "summary" : "Returns configuration data for sending a payment request", + "description" : "Returns configuration data for sending a payment request", + "tags" : [ "PaymentRequests" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/owner" + }, { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "to", + "in" : "query", + "required" : false, + "description" : "The payment request destination, which is either string `system` for a payment request to system or a user identification. The payment request destination is the one that performs the payment once it is accepted.", + "schema" : { + "type" : "string" + } + }, { + "name" : "type", + "in" : "query", + "required" : false, + "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). If no payment type is provided, the possible types will be returned, so the payer can choose.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The data for sending a payment request", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DataForTransaction" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/{owner}/payment-requests" : { + "post" : { + "operationId" : "sendPaymentRequest", + "summary" : "Sends a payment request from the given owner", + "description" : "Sends a payment request from the owner indicated on the path (which will receive the payment once the request is accepted) to the owner specified on the body (which will perform the payment once the request is accepted). The destination user should be informed in the `subject` parameter. If the `subject` is `system`, the payment request is sent to a system account, and has to be accepted by an administrator. The payment request id is returned on the response, and a link to the transaction details is returned on the `Location` header.", + "tags" : [ "PaymentRequests" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/owner" + } ], + "responses" : { + "201" : { + "description" : "The created payment request", + "headers" : { + "Location" : { + "description" : "URL for viewing the transaction details", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Transaction" + } + } + } + }, + "500" : { + "description" : "If a payment error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentError" + } + } + } + } + }, + "requestBody" : { + "description" : "The send payment request parameters", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/SendPaymentRequest" + } + } + } + } + } + }, + "/payment-requests/{key}/accept" : { + "post" : { + "operationId" : "acceptPaymentRequest", + "summary" : "Accepts a payment request.", + "description" : "Accepts a payment request in status `open`. After accepting the payment request its resultant status could be `processed` (and the corresponding sheduled or direct payment was generated) or `scheduled`. This can be done only by managers or the payer (i.e the request's recipient) with permission to accept.", + "tags" : [ "PaymentRequests" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "201" : { + "description" : "The performed payment. Only if the process date was not given (i.e the request was processed immediately).", + "headers" : { + "Location" : { + "description" : "URL for viewing the payment details", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Transaction" + } + } + } + }, + "204" : { + "description" : "The payment request was accepted and scheduled for processing at the given date. Nothing is returned." + }, + "500" : { + "description" : "If a payment error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentError" + } + } + } + } + }, + "requestBody" : { + "description" : "The parameters to accept a payment request", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/AcceptOrReschedulePaymentRequest" + } + } + } + } + } + }, + "/payment-requests/{key}/reschedule" : { + "post" : { + "operationId" : "reschedulePaymentRequest", + "summary" : "Reschedules a payment request.", + "description" : "Reschedules an already accepted and scheduled payment request (i.e with status `scheduled`). If the new processing date is null then the payment request will be processed immediately generating the corresponding payment. Otherwise it will be scheduled to be processed at the given date. This can be done only by managers or the payer (i.e the request's recipient) with permission to accept.", + "tags" : [ "PaymentRequests" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "201" : { + "description" : "The performed payment. Only if the process date was not given (i.e the request was processed immediately).", + "headers" : { + "Location" : { + "description" : "URL for viewing the payment details", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Transaction" + } + } + } + }, + "204" : { + "description" : "The payment request was rescheduled. Nothing is returned." + }, + "500" : { + "description" : "If a payment error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentError" + } + } + } + } + }, + "requestBody" : { + "description" : "The parameters to reschedule a payment request.", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/AcceptOrReschedulePaymentRequest" + } + } + } + } + } + }, + "/payment-requests/{key}/preview" : { + "get" : { + "operationId" : "previewPaymentRequest", + "summary" : "Previews the payment performed when accepting the given payment request.", + "description" : "Previews the payment ony if the payment request status is `open` or `scheduled`.", + "tags" : [ "PaymentRequests" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The payment preview", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentPreview" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/payment-requests/{key}/change-expiration" : { + "post" : { + "operationId" : "changePaymentRequestExpirationDate", + "summary" : "Changes the payment request expiration.", + "description" : "Change the expiration date of a payment request in status `open` or `expired`. This can be done only by managers or the payee (i.e the request's sender) with permission to change the expiration.", + "tags" : [ "PaymentRequests" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "204" : { + "description" : "The payment request expiration date was changed. Nothing is returned." + }, + "500" : { + "description" : "If a payment error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentError" + } + } + } + } + }, + "requestBody" : { + "description" : "The parameters to change the payment request's expiration date", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ChangePaymentRequestExpirationDate" + } + } + } + } + } + }, + "/payment-requests/{key}/reject" : { + "post" : { + "operationId" : "rejectPaymentRequest", + "summary" : "Rejects a payment request.", + "description" : "Rejects a payment request in status `open`. This can be done only by managers or the payer (i.e the request's recipient) with permission to accept.", + "tags" : [ "PaymentRequests" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "204" : { + "description" : "The payment request was rejected. Nothing is returned." + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + }, + "requestBody" : { + "description" : "A comment for the reject action the payer can set.", + "content" : { + "text/plain" : { + "schema" : { + "type" : "string" + } + } + } + } + } + }, + "/payment-requests/{key}/cancel" : { + "post" : { + "operationId" : "cancelPaymentRequest", + "summary" : "Cancels a payment request.", + "description" : "Cancels a payment request in status `open`. This can be done only by managers or the payee with permission to cancel.", + "tags" : [ "PaymentRequests" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "204" : { + "description" : "The payment request was cancelled. Nothing is returned." + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + }, + "requestBody" : { + "description" : "A comment for the cancel action the payee/manager can set.", + "content" : { + "text/plain" : { + "schema" : { + "type" : "string" + } + } + } + } + } + }, + "/pending-payments/{key}/authorize" : { + "post" : { + "operationId" : "authorizePendingPayment", + "summary" : "Authorizes a pending payment.", + "description" : "Authorizes a payment / scheduled payment / recurring payment whose authorization status is `pending`.", + "tags" : [ "PendingPayments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The payment is authorized. The next authorization level is returned, in case the payment is still pending another authorization, or returns a no-content when the payment is authorized.", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransactionAuthorizationLevelData" + } + } + } + }, + "204" : { + "description" : "Nothing is returned if the transaction authorization process is finished, and the transaction is processed." + }, + "500" : { + "description" : "If a payment error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentError" + } + } + } + } + }, + "requestBody" : { + "description" : "Contains the action comments", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PendingPaymentActionParams" + } + } + } + } + } + }, + "/pending-payments/{key}/deny" : { + "post" : { + "operationId" : "denyPendingPayment", + "summary" : "Denies a pending payment.", + "description" : "Denies a payment / scheduled payment / recurring payment whose authorization status is `pending`.", + "tags" : [ "PendingPayments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "204" : { + "description" : "The payment is denied. Nothing is returned." + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + }, + "requestBody" : { + "description" : "Contains the action comments", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PendingPaymentActionParams" + } + } + } + } + } + }, + "/pending-payments/{key}/cancel" : { + "post" : { + "operationId" : "cancelPendingPayment", + "summary" : "Cancels the authorization process of a pending payment.", + "description" : "Cancels a payment / scheduled payment / recurring payment whose authorization status is `pending`. This action is performed by the payer.", + "tags" : [ "PendingPayments" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "204" : { + "description" : "The payment is canceled. Nothing is returned." + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + }, + "requestBody" : { + "description" : "Contains the action comments", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PendingPaymentActionParams" + } + } + } + } + } + }, + "/pos/data-for-pos" : { + "get" : { + "operationId" : "dataForReceivePayment", + "summary" : "Returns configuration data for receiving a payment (POS)", + "description" : "Returns configuration data for receiving a payment in POS operation", + "tags" : [ "POS" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "from", + "in" : "query", + "required" : false, + "description" : "Identification of the payer user", + "schema" : { + "type" : "string" + } + }, { + "name" : "type", + "in" : "query", + "required" : false, + "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). If no payment type is provided, the possible types will be returned, so the payer can choose.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The data for receiving a payment", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DataForTransaction" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "If a POS error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PosError" + } + } + } + } + } + } + }, + "/pos" : { + "post" : { + "operationId" : "receivePayment", + "summary" : "Receives a payment (POS)", + "description" : "Receives either a direct or scheduled payment in a POS operation for the authenticated user. The payer user should be informed in the `subject` parameter. The payment id is returned on the response, and a link to the transaction details is returned on the `Location` header.", + "tags" : [ "POS" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/confirmationPassword" + } ], + "responses" : { + "201" : { + "description" : "The created payment", + "headers" : { + "Location" : { + "description" : "URL for viewing the transaction details", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Transaction" + } + } + } + }, + "500" : { + "description" : "If a payment error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentError" + } + } + } + } + }, + "requestBody" : { + "description" : "The receive payment parameters", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PerformPayment" + } + } + } + } + } + }, + "/pos/preview" : { + "post" : { + "operationId" : "previewReceivePayment", + "summary" : "Previews a POS payment before receiving it", + "description" : "Previews a payment or scheduled payment. The actual balance checking is not performed in the preview.", + "tags" : [ "POS" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], + "responses" : { + "200" : { + "description" : "The payment preview", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentPreview" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "If a POS error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PosError" + } + } + } + } + }, + "requestBody" : { + "description" : "The receive payment parameters", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PerformPayment" + } + } + } + } + } + }, + "/pos/installments" : { + "get" : { + "operationId" : "calculateReceivePaymentInstallments", + "summary" : "Calculates the default installments for a scheduled payment", + "description" : "Used to calculate installments for a scheduled payment. Will return an installment every month. When later receiving the payment, these can be (optionally) customized (such as changing some due dates or amounts) and used on the payment installments.", + "tags" : [ "POS" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "from", + "in" : "query", + "required" : true, + "description" : "The payment origin", + "schema" : { + "type" : "string" + } + }, { + "name" : "count", + "in" : "query", + "required" : true, + "description" : "The number of installments", + "schema" : { + "type" : "integer" + } + }, { + "name" : "amount", + "in" : "query", + "required" : true, + "description" : "The total scheduled payment amount", + "schema" : { + "type" : "string", + "format" : "number" + } + }, { + "name" : "currency", + "in" : "query", + "required" : false, + "description" : "The payment currency. Used when no `type` is not provided, to narrow the possible payment types by currency.", + "schema" : { + "type" : "string" + } + }, { + "name" : "type", + "in" : "query", + "required" : false, + "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). If not provided, will use the first possible type (possibly narrowed by the `currency` parameter). However, if more than one type is available, a validation error will be raised.", + "schema" : { + "type" : "string" + } + }, { + "name" : "firstDate", + "in" : "query", + "required" : false, + "description" : "The due date of the first installment. If none is provided, it is assumed that the first installment is paid immediately, and others will be with regular 1 month interval", + "schema" : { + "type" : "string", + "format" : "date-time" + } + } ], + "responses" : { + "200" : { + "description" : "The calculated installments", + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/PerformInstallment" + } + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "If a POS error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PosError" + } + } + } + } + } + } + }, + "/pos/otp" : { + "post" : { + "operationId" : "receivePaymentOtp", + "summary" : "Generates a new One-Time-Password (OTP) for a pos payment", + "description" : "Sends a new OTP for the customer of the POS for a payment. The OTP belongs to the payer, not the authenticated user. The entire payment object must be sent on the request body. This is the same object which is sent both either preview or actually receive the payment.", + "tags" : [ "POS" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "name" : "medium", + "in" : "query", + "required" : true, + "description" : "The medium the user wants to receive the otp", + "schema" : { + "$ref" : "#/components/schemas/SendMediumEnum" + } + } ], + "responses" : { + "204" : { + "description" : "The OTP is sent to the user, and no content is returned" + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "There was an error when generating the OTP", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/OtpError" + } + } + } + } + }, + "requestBody" : { + "description" : "The receive payment parameters", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PerformPayment" + } + } + } + } + } + }, + "/pos/device-confirmations" : { + "post" : { + "operationId" : "receivePaymentCreateDeviceConfirmation", + "summary" : "Creates a pending device confirmation for a pos payment.", + "description" : "Creates a device confirmation to confirm a pos payment. The confirmation will have a QR code that can be read (e.g with the Mobile App) to be approved / rejected by the payer. The confirmation belongs to the payer, not the authenticated user. The entire payment object must be sent on the request body. This is the same object which is sent both either preview or actually receive the payment.", + "tags" : [ "POS" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ ], + "responses" : { + "201" : { + "description" : "Returns the identifier of the new confirmation.", + "content" : { + "text/plain" : { + "schema" : { + "type" : "string" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + }, + "requestBody" : { + "description" : "The receive payment parameters", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PerformPayment" + } + } + } + } + } + }, + "/pos/device-confirmations/{id}" : { + "get" : { + "operationId" : "receivePaymentViewDeviceConfirmation", + "summary" : "Shows the details of a device confirmation for a POS payer.", + "description" : "Shows the details of a device confirmation for POS payer. The confirmation belongs to the payer but must had been created by the authenticated user. The entire payment object must be sent on the request body. This is the same object which is sent both either preview or actually receive the payment", + "tags" : [ "POS" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/id" + }, { + "name" : "payer", + "in" : "query", + "required" : true, + "description" : "A user identification value, such as id, username, e-mail, phone, etc. Id is always allowed, others depend on Cyclos configuration. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`;", + "schema" : { + "type" : "string" + } + }, { + "name" : "currency", + "in" : "query", + "required" : false, + "description" : "The currency id or internal name. Only used when not specifying a payment type. In this case, will narrow the search for the payment type.", + "schema" : { + "type" : "string" + } + }, { + "name" : "type", + "in" : "query", + "required" : false, + "description" : "The payment type, either the id or qualified internal name (in the form `fromAccountType.paymentType`). If no payment type is specified, if a single one is possible, it will be used. If a currency is specified, it will be taken into account in order to find the payment type. If, however, there would be multiple possibilities, a validation error is returned.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The device confirmation details.", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DeviceConfirmationView" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + }, + "delete" : { + "operationId" : "receivePaymentDeleteDeviceConfirmation", + "summary" : "Deletes a device confirmation for a POS payer.", + "description" : "Deletes a device confirmation for the payer of pos payment. The confirmation belongs to the payer, not the authenticated user. The entire payment object must be sent on the request body. This is the same object which is sent both either preview or actually receive the payment.", + "tags" : [ "POS" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/id" + }, { + "name" : "payer", + "in" : "query", + "required" : true, + "description" : "A user identification value, such as id, username, e-mail, phone, etc. Id is always allowed, others depend on Cyclos configuration. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`;", + "schema" : { + "type" : "string" + } + }, { + "name" : "currency", + "in" : "query", + "required" : false, + "description" : "The currency id or internal name. Only used when not specifying a payment type. In this case, will narrow the search for the payment type.", + "schema" : { + "type" : "string" + } + }, { + "name" : "type", + "in" : "query", + "required" : false, + "description" : "The payment type, either the id or qualified internal name (in the form `fromAccountType.paymentType`). If no payment type is specified, if a single one is possible, it will be used. If a currency is specified, it will be taken into account in order to find the payment type. If, however, there would be multiple possibilities, a validation error is returned.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "204" : { + "description" : "The device confirmation was removed." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConflictError" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/pos/device-confirmations/{id}/qr-code" : { + "get" : { + "operationId" : "receivePaymentDeviceConfirmationQrCode", + "summary" : "Returns the QR-code image for the given device confirmation only if it was not yet approved / rejected", + "description" : "This request will return the image contents as expected but our api documentation page (or any other usage of an <img> tag), created using swagger-ui, generates a second request to include the image in the page. This new (GET) request won't send the authentication parameters and as this path requires authentication the image will be shown as broken. Optionally, to solve the problem described above and to allow authenticate the user when using sessions, a `sessionToken` or `accessClientToken` query parameter could be specified.", + "tags" : [ "POS" ], + "parameters" : [ { + "$ref" : "#/components/parameters/id" + }, { + "name" : "payer", + "description" : "The payer, either a user principal (id, login name, etc) or the word `system` when the payment is to be performed to / from a system account. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`.", + "in" : "query", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "name" : "size", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/ImageSizeEnum" + } + } ], + "responses" : { + "200" : { + "description" : "The image content", + "content" : { + "image/png" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/{user}/client-types" : { + "get" : { + "operationId" : "listClientTypesForUser", + "summary" : "Returns the list of access clients types for a user", + "description" : "Returns the access client types for a given user that the authenticated user has access.", + "tags" : [ "Clients" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/user" + }, { + "name" : "channel", + "in" : "query", + "description" : "If a channel id or internal name is specified, will only list access client types that can be used to access that channel", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The list of access clients types, with permissions, for the user", + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/UserClientTypePermissions" + } + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/clients/activate" : { + "post" : { + "operationId" : "activateClient", + "summary" : "Activates an access client", + "description" : "Activates an access client belonging to the currently authenticated user.", + "tags" : [ "Clients" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "name" : "code", + "required" : true, + "in" : "query", + "description" : "The activation code. Must match the activation code obtained in Cyclos, which belongs to the authenticated user.", + "schema" : { + "type" : "string" + } + }, { + "name" : "prefix", + "required" : false, + "in" : "query", + "description" : "A prefix to be added to the generated access client token. Can be used to increase the size of the generated token, and to increase the security on clients that have to store the token. This can be accomplished by using some sort of client application hash or identifier, which should be stable. The prefix is not returned by this method. When later passing in the full token, the prefix should prepend the returned token without any separator.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "Returns the token to be used on subsequent requests", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ActivateClientResult" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/clients/{key}" : { + "get" : { + "operationId" : "viewClient", + "summary" : "Returns details of an access client", + "description" : "Returns the access client details, together with permissions", + "tags" : [ "Clients" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "The access client id or token", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The access client details", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ClientView" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/clients/{key}/unassign" : { + "post" : { + "operationId" : "unassignClient", + "summary" : "Unassign (disconnects) an access client", + "description" : "Unassigns an access client by id or token. It must be currently assigned. After this call, the client can be assigned again if needed.", + "tags" : [ "Clients" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "The access client id or token", + "schema" : { + "type" : "string" + } + }, { + "$ref" : "#/components/parameters/confirmationPassword" + } ], + "responses" : { + "204" : { + "description" : "Nothing is returned, and the access client is unassigned" + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/mobile/data-for-guest" : { + "get" : { + "operationId" : "dataForMobileGuest", + "summary" : "Returns data the mobile application uses while in guest mode", + "description" : "The data returned can be controlled with a cache key. Each data type has a parameter, such as `headerIf`, which returns the data only if it has changed since the last request.", + "tags" : [ "Mobile" ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/cyclosVersion" + }, { + "$ref" : "#/components/parameters/headerIf" + }, { + "$ref" : "#/components/parameters/footerIf" + }, { + "$ref" : "#/components/parameters/themeIf" + }, { + "name" : "translationsIf", + "in" : "query", + "required" : false, + "description" : "Controls the translations cache. If is a boolean value (`true` or `false`) will forcibly return or skip the content. Otherwise, it should be a string in the form `id|version`. In this case, the content will be returned only when changed. When blank will always return it.", + "schema" : { + "type" : "string" + } + }, { + "name" : "deviceId", + "in" : "query", + "required" : false, + "description" : "Trusted device identification. If given and the device is active then a pending device confirmation will be created that will be validated\n after the user logs-in. If the validation passes then no confirmation\npassword will be used only for that session.", + "schema" : { + "type" : "string" + } + }, { + "name" : "pinId", + "in" : "query", + "required" : false, + "description" : "Device PIN identification. If given then the information about whether it is active or not will be given in the returned `dataForLogin`.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The data for the mobile guest page", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DataForMobileGuest" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/mobile/data-for-user" : { + "get" : { + "operationId" : "dataForMobileUser", + "summary" : "Returns data the mobile application uses in either user or POS mode", + "description" : "The data returned can be controlled with a cache key. Each data type has a parameter, such as `helpIf`, which returns the data only if it has changed since the last request.", + "tags" : [ "Mobile" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/cyclosVersion" + }, { + "$ref" : "#/components/parameters/themeIf" + }, { + "name" : "translationsIf", + "in" : "query", + "required" : false, + "description" : "Controls the translations cache. If is a boolean value (`true` or `false`) will forcibly return or skip the content. Otherwise, it should be a string in the form `id|version`. In this case, the content will be returned only when changed. When blank will always return it.", + "schema" : { + "type" : "string" + } + }, { + "name" : "mobileHelpIf", + "in" : "query", + "required" : false, + "description" : "Controls the mobile help cache. If is a boolean value (`true` or `false`) will forcibly return or skip the content. Otherwise, it should be a string in the form `id|version`. In this case, the content will be returned only when changed. When blank will always return it. Only taken into account when not accessing as access client (not in POS mode).", + "schema" : { + "type" : "string" + } + }, { + "name" : "posHelpIf", + "in" : "query", + "required" : false, + "description" : "Controls the POS help cache. If is a boolean value (`true` or `false`) will forcibly return or skip the content. Otherwise, it should be a string in the form `id|version`. In this case, the content will be returned only when changed. When blank will always return it. Only taken into account when accessing as access client (POS mode).", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The data for the mobile user page", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DataForMobileUser" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/mobile/page/{id}" : { + "get" : { + "operationId" : "mobilePageContent", + "summary" : "Returns the content of a mobile page", + "description" : "Returns the content of a mobile page, either by id or internal name", + "tags" : [ "Mobile" ], + "parameters" : [ { + "name" : "id", + "in" : "path", + "required" : true, + "description" : "The mobile page id", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The page content", + "content" : { + "text/html" : { + "schema" : { + "type" : "string" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/notifications" : { + "get" : { + "operationId" : "searchNotifications", + "summary" : "Searches for the notifications the authenticated user has received.", + "description" : "Returns an ordered page of notifications the authenticated user has received (newest first).", + "tags" : [ "Notifications" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "onlyNew", + "in" : "query", + "required" : false, + "description" : "Boolean value indicating wether return only the new notifications received after the last view date tracked using `POST /notifications/viewed`", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "onlyUnread", + "in" : "query", + "required" : false, + "description" : "Boolean value indicating wether return only the unread notifications", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + } ], + "responses" : { + "200" : { + "description" : "The notifications page", + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Notification" + } + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/notifications/{id}" : { + "get" : { + "operationId" : "viewNotification", + "summary" : "Returns the notification details.", + "description" : "Returns the notification details.", + "tags" : [ "Notifications" ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/id" + } ], + "responses" : { + "200" : { + "description" : "The notification details", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Notification" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + }, + "delete" : { + "operationId" : "deleteNotification", + "summary" : "Removes a notification by id.", + "description" : "Removes a notification for the authenticated user by id.", + "tags" : [ "Notifications" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], + "responses" : { + "204" : { + "description" : "The notification was removed" + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConflictError" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/notifications/mark-as-read" : { + "post" : { + "operationId" : "markNotificationsAsRead", + "summary" : "Marks a list of notifications as read.", + "description" : "Marks a list of notifications, given by id, as read.", + "tags" : [ "Notifications" ], + "parameters" : [ { + "name" : "ids", + "description" : "The notifications (comma-separated list of identifiers) to mark as read.", + "in" : "query", + "required" : true, + "schema" : { + "type" : "array", + "items" : { + "type" : "string" + } + } + } ], + "responses" : { + "204" : { + "description" : "The notifications were marked as read." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConflictError" + } + } + } + } + } + } + }, + "/notifications/status" : { + "get" : { + "operationId" : "notificationsStatus", + "summary" : "Return information about the received notifications.", + "description" : "Return information about the status of the received notifications (unread, new, etc).", + "tags" : [ "Notifications" ], + "responses" : { + "200" : { + "description" : "The notifications status information", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotificationsStatus" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/notifications/viewed" : { + "post" : { + "operationId" : "markAsViewed", + "summary" : "Update the last view date for the notifications.", + "description" : "Update the last view date for the notifications. This will be used to calculate the number of new notifications returned by the `POST /notifications/status` operation.", + "tags" : [ "Notifications" ], + "responses" : { + "204" : { + "description" : "The last view date was updated." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConflictError" + } + } + } + } + } + } + }, + "/{user}/notification-settings" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], + "get" : { + "operationId" : "viewNotificationSettings", + "summary" : "Returns the notification settings for a given user.", + "description" : "Returns the notification settings for a given operator / user / administrator.", + "tags" : [ "NotificationSettings" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], + "responses" : { + "200" : { + "description" : "The notification settings", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotificationSettingsView" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + }, + "post" : { + "operationId" : "saveNotificationSettings", + "summary" : "Saves the notification settings for a given user.", + "description" : "Saves the notification settings for a given operator / user / administrator.", + "tags" : [ "NotificationSettings" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "requestBody" : { + "description" : "The parameters to save", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotificationSettingsEdit" + } + } + } + }, + "responses" : { + "204" : { + "description" : "The notification settings are saved and nothing is returned" + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + } + } + } + }, + "/{user}/notification-settings/data-for-edit" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], + "get" : { + "operationId" : "getNotificationSettingsDataForEdit", + "summary" : "Returns configuration data to edit the notification settings of a user.", + "description" : "Returns data to edit the nofitication settings od a given operator / user / administrator.", + "tags" : [ "NotificationSettings" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], + "responses" : { + "200" : { + "description" : "The notification settings", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotificationSettingsDataForEdit" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/vouchers/data-for-search" : { + "get" : { + "operationId" : "getVouchersDataForSearch", + "summary" : "Returns data for searching vouchers as admin", + "description" : "Returns configuration data used to search vouchers as admin", + "tags" : [ "Vouchers" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], + "responses" : { + "200" : { + "description" : "The configuration data for searching a vouchers as admin", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/VouchersDataForSearch" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/vouchers" : { + "get" : { + "operationId" : "searchVouchers", + "summary" : "Searches for vouchers as admin", + "description" : "Returns the list of matching vouchers the authenticated admin can view", + "tags" : [ "Vouchers" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "amountRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum voucher amount", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" + } + } + }, { + "name" : "buyer", + "in" : "query", + "required" : false, + "description" : "The buyer of the voucher. A user identification value, such as id, username, e-mail, phone, etc. Id is always allowed, others depend on Cyclos configuration. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`;", + "schema" : { + "type" : "string" + } + }, { + "name" : "buyerGroups", + "in" : "query", + "required" : false, + "description" : "The ids or internal names of buyers groups", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "creationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum voucher creation date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "creationType", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/VoucherCreationTypeEnum" + } + }, { + "name" : "expirationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum voucher expiration date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/VoucherOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "printed", + "in" : "query", + "required" : false, + "description" : "If it is passed, filter if the voucher was printed or not.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "redeemPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum voucher redeem date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "redeemer", + "in" : "query", + "required" : false, + "description" : "The redeemer of the voucher. A user identification value, such as id, username, e-mail, phone, etc. Id is always allowed, others depend on Cyclos configuration. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`;", + "schema" : { + "type" : "string" + } + }, { + "name" : "redeemerGroups", + "in" : "query", + "required" : false, + "description" : "The ids or internal names of redeemers groups", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "statuses", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/VoucherStatusEnum" + } + } + }, { + "name" : "token", + "in" : "query", + "required" : false, + "description" : "The voucher token (with or without mask)", + "schema" : { + "type" : "string" + } + }, { + "name" : "types", + "in" : "query", + "required" : false, + "description" : "The ids or internal names of voucher types", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + } ], + "responses" : { + "200" : { + "description" : "The list of matching vouchers.", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/VoucherResult" + } + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/vouchers/export/{format}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/format" + } ], + "get" : { + "operationId" : "exportVouchers", + "summary" : "Exports the vouchers search results as file.", + "description" : "Generates a file containing the search results. The available export formats are returned in `GET /vouchers/data-for-search`.", + "tags" : [ "Vouchers" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "name" : "amountRange", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum voucher amount", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "number" + } + } + }, { + "name" : "buyer", + "in" : "query", + "required" : false, + "description" : "The buyer of the voucher. A user identification value, such as id, username, e-mail, phone, etc. Id is always allowed, others depend on Cyclos configuration. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`;", + "schema" : { + "type" : "string" + } + }, { + "name" : "buyerGroups", + "in" : "query", + "required" : false, + "description" : "The ids or internal names of buyers groups", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "creationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum voucher creation date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "creationType", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/VoucherCreationTypeEnum" + } + }, { + "name" : "expirationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum voucher expiration date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "orderBy", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/VoucherOrderByEnum" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "printed", + "in" : "query", + "required" : false, + "description" : "If it is passed, filter if the voucher was printed or not.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "redeemPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum voucher redeem date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "redeemer", + "in" : "query", + "required" : false, + "description" : "The redeemer of the voucher. A user identification value, such as id, username, e-mail, phone, etc. Id is always allowed, others depend on Cyclos configuration. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`;", + "schema" : { + "type" : "string" + } + }, { + "name" : "redeemerGroups", + "in" : "query", + "required" : false, + "description" : "The ids or internal names of redeemers groups", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "statuses", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/VoucherStatusEnum" + } + } + }, { + "name" : "token", + "in" : "query", + "required" : false, + "description" : "The voucher token (with or without mask)", + "schema" : { + "type" : "string" + } + }, { + "name" : "types", + "in" : "query", + "required" : false, + "description" : "The ids or internal names of voucher types", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "markAsPrinted", + "in" : "query", + "required" : false, + "schema" : { + "type" : "boolean" + }, + "description" : "Should the exported vouchers be marked as printed? By default doesn't mark vouchers as printed." + } ], + "responses" : { + "200" : { + "description" : "The file content", + "content" : { + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/vouchers/{key}" : { + "get" : { + "operationId" : "viewVoucher", + "summary" : "Returns data for a particular voucher", + "description" : "Returns details about a particular voucher, as well as the transactions used to buy and redeem, and the permissions for authenticated over it.", + "tags" : [ "Vouchers" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "key", + "description" : "The voucher `id` or `token`. When the token is fully numeric, it must be preceded by a single quote (`'`).", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The voucher details", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/VoucherView" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/vouchers/{key}/export/{format}" : { + "parameters" : [ { + "name" : "key", + "description" : "The voucher `id` or `token`. When the token is fully numeric, it must be preceded by a single quote (`'`).", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "$ref" : "#/components/parameters/format" + } ], + "get" : { + "operationId" : "exportVoucher", + "summary" : "Exports a voucher details as file.", + "description" : "Generates a file containing the voucher details. The available export formats are returned in `VoucherView`.", + "parameters" : [ { + "name" : "markAsPrinted", + "in" : "query", + "required" : false, "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } + "type" : "boolean" + }, + "description" : "Should the exported voucher be marked as printed? By default doesn't mark vouchers as printed." + } ], + "tags" : [ "Vouchers" ], + "security" : [ { + "basic" : [ ] }, { - "name" : "transferKinds", - "in" : "query", - "required" : false, - "description" : "", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/TransferKind" + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "responses" : { + "200" : { + "description" : "The file content", + "content" : { + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } } } - }, { - "name" : "transferTypes", - "in" : "query", - "required" : false, - "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", - "style" : "simple", + } + } + }, + "/vouchers/{key}/qr-code" : { + "get" : { + "operationId" : "getVoucherQrCode", + "summary" : "Returns the QR-code image for the given voucher", + "description" : "The api documentation page, using swagger-ui (or any direct usage of an image tag), generates a second request to show the image contents on the preview. This is a new GET request, without passing-in the authentication parameters. As this path requires authentication, the image is shown broken, but the first request works as expected, returning the image content. Optionally, to solve the problem described above and allow to authenticate the user when using sessions, a `sessionToken` or `accessClientToken` plus a `channel` query parameters could be specified.", + "tags" : [ "Vouchers" ], + "parameters" : [ { + "name" : "key", + "description" : "The voucher `id` or `token`. When the token is fully numeric, it must be preceded by a single quote (`'`).", + "in" : "path", + "required" : true, "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } + "type" : "string" } }, { - "name" : "user", + "name" : "size", "in" : "query", "required" : false, - "description" : "Reference a user that should have either received / performed the transfer.", "schema" : { - "type" : "string" + "$ref" : "#/components/schemas/ImageSizeEnum" } } ], "responses" : { "200" : { - "description" : "The users together with their balances", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, + "description" : "The image content", "content" : { - "application/json" : { + "image/png" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/TransferResult" - } + "type" : "string", + "format" : "binary" } } } @@ -17689,12 +28870,105 @@ } } }, - "/{owner}/transactions/data-for-search" : { + "/vouchers/{key}/change-expiration" : { + "post" : { + "operationId" : "changeVoucherExpirationDate", + "summary" : "Changes the voucher expiration.", + "description" : "Change the expiration date of a voucher in status `open` or `expired`. This can be done only by admin with permission to change the expiration.", + "tags" : [ "Vouchers" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or token.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "204" : { + "description" : "The voucher expiration date was changed. Nothing is returned." + }, + "500" : { + "description" : "If a payment error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentError" + } + } + } + } + }, + "requestBody" : { + "description" : "The parameters to change the voucher's expiration date", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ChangeVoucherExpirationDate" + } + } + } + } + } + }, + "/vouchers/{key}/cancel" : { + "post" : { + "operationId" : "cancelVoucher", + "summary" : "Cancels the voucher", + "description" : "Cancels a voucher in status `open`, `expired` or `pending`. If its creation type is `bought` also refund the buyer. This can be done by users with permission to refund over its open or expired vouchers, or by admins with permission to cancel/refund for generated/bought vouchers respectively.", + "tags" : [ "Vouchers" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" + }, { + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or token.", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "204" : { + "description" : "The voucher was canceled. Nothing is returned." + }, + "500" : { + "description" : "If a payment error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentError" + } + } + } + } + } + } + }, + "/{user}/vouchers/data-for-search" : { "get" : { - "operationId" : "getTransactionsDataForSearch", - "summary" : "Returns data for searching transactions of an account owner", - "description" : "Returns data which can be used to filter a transaction search", - "tags" : [ "Transactions" ], + "operationId" : "getUserVouchersDataForSearch", + "summary" : "Returns data for searching vouchers a user has bought or redeemed", + "description" : "Returns configuration data used to search vouchers the user has either bought (default) or redeemed (if `relation` is `redeemed`)", + "tags" : [ "Vouchers" ], "security" : [ { "basic" : [ ] }, { @@ -17705,15 +28979,22 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/owner" + "$ref" : "#/components/parameters/user" + }, { + "name" : "relation", + "in" : "query", + "description" : "Indicates the relation used to filter the vouchers.", + "schema" : { + "$ref" : "#/components/schemas/VoucherRelationEnum" + } } ], "responses" : { "200" : { - "description" : "Data for searching transactions of an account owner", + "description" : "The configuration data for searching a user's vouchers", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/TransactionDataForSearch" + "$ref" : "#/components/schemas/UserVouchersDataForSearch" } } } @@ -17761,12 +29042,12 @@ } } }, - "/{owner}/transactions" : { + "/{user}/vouchers" : { "get" : { - "operationId" : "searchTransactions", - "summary" : "Searches transactions of an account owner", - "description" : "Returns the transactions of a given account owner that match the specified criteria. Each result will will be relative to this owner. The amount may be positive or negative, depending on whether this owner has performed or received the transaction.", - "tags" : [ "Transactions" ], + "operationId" : "searchUserVouchers", + "summary" : "Searches for vouchers a user has bought or redeemed", + "description" : "Returns the list of matching vouchers the given user has either bought (default) or redeemed (if `type` is `redeemed`)", + "tags" : [ "Vouchers" ], "security" : [ { "basic" : [ ] }, { @@ -17775,41 +29056,14 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/owner" - }, { "$ref" : "#/components/parameters/fields" }, { - "name" : "accessClients", - "in" : "query", - "required" : false, - "description" : "References to access clients (id or token) used to perform / receive the transfer.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "accountTypes", - "in" : "query", - "required" : false, - "description" : "The account types", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } + "$ref" : "#/components/parameters/user" }, { "name" : "amountRange", "in" : "query", "required" : false, - "description" : "The minimum / maximum amount. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", + "description" : "The minimum / maximum voucher amount", "schema" : { "type" : "array", "items" : { @@ -17819,52 +29073,10 @@ } } }, { - "name" : "authorizationStatuses", - "in" : "query", - "required" : false, - "description" : "Authorization statuses used as search criteria", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/TransactionAuthorizationStatusEnum" - } - } - }, { - "name" : "broker", - "in" : "query", - "required" : false, - "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", - "schema" : { - "type" : "string" - } - }, { - "name" : "by", - "in" : "query", - "required" : false, - "description" : "Reference to the user that was authenticated when the transfer was performed. Is only taken into account if authenticated as administrator.", - "schema" : { - "type" : "string" - } - }, { - "name" : "channels", - "in" : "query", - "required" : false, - "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "datePeriod", + "name" : "creationPeriod", "in" : "query", "required" : false, - "description" : "The minimum / maximum transfer date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", + "description" : "The minimum / maximum voucher creation date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", "schema" : { "type" : "array", "items" : { @@ -17874,76 +29086,16 @@ } } }, { - "name" : "direction", - "in" : "query", - "required" : false, - "schema" : { - "$ref" : "#/components/schemas/TransferDirectionEnum" - } - }, { - "name" : "excludedIds", - "in" : "query", - "required" : false, - "description" : "List of transfers ids to be excluded from the result.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "externalPaymentStatuses", - "in" : "query", - "required" : false, - "description" : "Statuses used as search criteria applied only to transactions of kind `externalPayment`.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/ExternalPaymentStatusEnum" - } - } - }, { - "name" : "fromCurrentAccessClient", - "in" : "query", - "required" : false, - "description" : "Flag indicating whether to include only transfers by the current access client.", - "schema" : { - "type" : "boolean" - } - }, { - "name" : "groups", + "name" : "expirationPeriod", "in" : "query", "required" : false, - "description" : "Reference to the user group used to perform / receive the transfer. Only taken into account if authenticated as administrator.", - "style" : "simple", + "description" : "The minimum / maximum voucher expiration date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", "schema" : { "type" : "array", "items" : { "description" : "", - "type" : "string" - } - } - }, { - "name" : "includeGeneratedByAccessClient", - "in" : "query", - "required" : false, - "description" : "Flag indicating whether to include or not the generated transfer. Only valid if there is at least one access client specified. For example if a `ticket` or `paymentRequest` was processed then a new transfer will be generated.", - "schema" : { - "type" : "boolean" - } - }, { - "name" : "kinds", - "in" : "query", - "required" : false, - "description" : "", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/TransactionKind" + "type" : "string", + "format" : "date-time" } } }, { @@ -17965,80 +29117,65 @@ "format" : "int32" } }, { - "name" : "paymentRequestStatuses", + "name" : "redeemBy", "in" : "query", "required" : false, - "description" : "Statuses used as search criteria applied only to transactions of kind `paymentRequest`.", - "style" : "simple", + "description" : "The user who perform the redeem action. A user identification value, such as id, username, e-mail, phone, etc. Id is always allowed, others depend on Cyclos configuration. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`;", "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/PaymentRequestStatusEnum" - } + "type" : "string" } }, { - "name" : "recurringPaymentStatuses", + "name" : "redeemPeriod", "in" : "query", "required" : false, - "description" : "Statuses used as search criteria applied only to transactions of kind `recurringPayment`.", - "style" : "simple", + "description" : "The minimum / maximum voucher redeem date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", "schema" : { "type" : "array", "items" : { - "$ref" : "#/components/schemas/RecurringPaymentStatusEnum" + "description" : "", + "type" : "string", + "format" : "date-time" } } }, { - "name" : "scheduledPaymentStatuses", + "name" : "relation", "in" : "query", "required" : false, - "description" : "Statuses used as search criteria applied only to transactions of kind `scheduledPayment`.", - "style" : "simple", "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/ScheduledPaymentStatusEnum" - } + "$ref" : "#/components/schemas/VoucherRelationEnum" } }, { - "name" : "ticketStatuses", + "name" : "skipTotalCount", "in" : "query", "required" : false, - "description" : "Statuses used as search criteria applied only to transactions of kind `ticket`.", - "style" : "simple", + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/TicketStatusEnum" - } + "type" : "boolean" } }, { - "name" : "transactionNumber", + "name" : "statuses", "in" : "query", "required" : false, - "description" : "The transaction number of the matching transfer", + "description" : "", "schema" : { - "type" : "string" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/VoucherStatusEnum" + } } }, { - "name" : "transferFilters", + "name" : "token", "in" : "query", "required" : false, - "description" : "Reference to the transfer filters, which filters transfers by type. May be either the internal id or qualified transfer filter internal name, in the format `accountType.transferFilter`.", - "style" : "simple", + "description" : "The voucher token (with or without mask)", "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } + "type" : "string" } }, { - "name" : "transferTypes", + "name" : "types", "in" : "query", "required" : false, - "description" : "Reference to the transfer types for filter. May be either the internal id or qualified transfer type internal name, in the format `accountType.transferType`.", - "style" : "simple", + "description" : "The ids or internal names of voucher types", "schema" : { "type" : "array", "items" : { @@ -18046,18 +29183,10 @@ "type" : "string" } } - }, { - "name" : "user", - "in" : "query", - "required" : false, - "description" : "Reference a user that should have either received / performed the transfer.", - "schema" : { - "type" : "string" - } } ], "responses" : { "200" : { - "description" : "The transaction entries matching the criteria", + "description" : "The list of matching vouchers. The `buyer` and `redeemer` fields will not be returned when searching for bought and redeemed vouchers (respectively), because they are always the user passed as parameter.", "headers" : { "X-Total-Count" : { "schema" : { @@ -18089,7 +29218,7 @@ "schema" : { "type" : "array", "items" : { - "$ref" : "#/components/schemas/TransactionResult" + "$ref" : "#/components/schemas/VoucherResult" } } } @@ -18138,12 +29267,14 @@ } } }, - "/transactions/{key}" : { + "/{user}/vouchers/types-for-buy" : { "get" : { - "operationId" : "viewTransaction", - "summary" : "Returns details about a transaction", - "description" : "Returns details about a transaction.", - "tags" : [ "Transactions" ], + "operationId" : "listVoucherTypesForBuy", + "deprecated" : true, + "x-remove-version" : 4.15, + "summary" : "Returns the voucher types the authenticated user can buy vouchers to the given user", + "description" : "Instead use \"/{user}/vouchers/data-for-buy\" without passing a type.\n\nList the voucher types the user can buy to another user (or himself)", + "tags" : [ "Vouchers" ], "security" : [ { "basic" : [ ] }, { @@ -18154,21 +29285,18 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number", - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/user" } ], "responses" : { "200" : { - "description" : "Transaction details", + "description" : "The list with the voucher types", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/TransactionView" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/VoucherTypeDetailed" + } } } } @@ -18216,12 +29344,12 @@ } } }, - "/{owner}/payments/data-for-perform" : { + "/{user}/vouchers/data-for-buy" : { "get" : { - "operationId" : "dataForPerformPayment", - "summary" : "Returns configuration data for performing a payment", - "description" : "Returns configuration data for performing a payment", - "tags" : [ "Payments" ], + "operationId" : "getVoucherDataForBuy", + "summary" : "Returns data for buying a voucher of a specified type or the list of types to buy.", + "description" : "If a type is passed it returns the data for buying vouchers, otherwise it returns the list of types the atuhenticated user can buy to the given user (or himself).", + "tags" : [ "Vouchers" ], "security" : [ { "basic" : [ ] }, { @@ -18230,33 +29358,24 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/owner" - }, { "$ref" : "#/components/parameters/fields" }, { - "name" : "to", - "in" : "query", - "required" : false, - "description" : "The payment destination. Either the string `system` for a payment to system or a user identification.", - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/user" }, { "name" : "type", + "description" : "Either the `id` or `internalName` of the voucher type. Left empty to get the list of available types for buy.", "in" : "query", - "required" : false, - "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). If no payment type is provided, the possible types will be returned, so the payer can choose.", "schema" : { "type" : "string" } } ], "responses" : { "200" : { - "description" : "The data for performing a payment", + "description" : "The data for buying vouchers", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/DataForTransaction" + "$ref" : "#/components/schemas/VoucherDataForBuy" } } } @@ -18304,12 +29423,12 @@ } } }, - "/{owner}/payments" : { + "/{user}/vouchers/buy" : { "post" : { - "operationId" : "performPayment", - "summary" : "Performs a payment from the given owner", - "description" : "Performs either a direct, scheduled or recurring payment from the owner indicated on the path to the owner specified on the body. The destination user should be informed in the `subject` parameter. If the `subject` is `system`, it will be a payment to a system account. The payment id is returned on the response, and a link to the transaction details is returned on the `Location` header.", - "tags" : [ "Payments" ], + "operationId" : "buyVouchers", + "summary" : "Buys one or more vouchers for the given user", + "description" : "Buys vouchers. If the payment type has custom fields, the values should be passed as well. This service only returns the vouchers list, if you need information about the voucher status please use /{user}/vouchers/buy-with-status.", + "tags" : [ "Vouchers" ], "security" : [ { "basic" : [ ] }, { @@ -18318,61 +29437,84 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/owner" + "$ref" : "#/components/parameters/user" }, { "$ref" : "#/components/parameters/confirmationPassword" } ], "responses" : { - "201" : { - "description" : "The created payment", - "headers" : { - "Location" : { - "description" : "URL for viewing the transaction details", + "200" : { + "description" : "The identifiers of all generated vouchers", + "content" : { + "application/json" : { "schema" : { - "type" : "string" + "type" : "array", + "items" : { + "type" : "string" + } } } - }, + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Transaction" + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" } } } }, "500" : { - "description" : "If a payment error has occurred", + "description" : "An error occurred while buying the voucher(s)", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentError" + "$ref" : "#/components/schemas/BuyVoucherError" } } } } }, "requestBody" : { - "description" : "The perform payment parameters", + "description" : "The buy voucher parameters", "required" : true, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PerformPayment" + "$ref" : "#/components/schemas/BuyVoucher" } } } } } }, - "/{owner}/payments/preview" : { + "/{user}/vouchers/buy-with-status" : { "post" : { - "operationId" : "previewPayment", - "summary" : "Previews a payment before performing it", - "description" : "Previews a payment, scheduled or recurring payment. The actual balance checking is not performed in the preview.", - "tags" : [ "Payments" ], + "operationId" : "buyVouchersWithStatus", + "summary" : "Buys one or more vouchers for the given user returning the status.", + "description" : "Buys vouchers. If the payment type has custom fields, the values should be passed as well. The status returned in the result is shared by all vouchers.", + "tags" : [ "Vouchers" ], "security" : [ { "basic" : [ ] }, { @@ -18381,17 +29523,17 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/owner" + "$ref" : "#/components/parameters/user" }, { - "$ref" : "#/components/parameters/fields" + "$ref" : "#/components/parameters/confirmationPassword" } ], "responses" : { "200" : { - "description" : "The payment preview", + "description" : "The status of all bougth vouchers and their identifiers.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentPreview" + "$ref" : "#/components/schemas/VoucherBoughtResult" } } } @@ -18426,46 +29568,36 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { - "description" : "Unexpected error", + "description" : "An error occurred while buying the voucher(s)", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Error" + "$ref" : "#/components/schemas/BuyVoucherError" } } } } }, "requestBody" : { - "description" : "The perform payment parameters", + "description" : "The buy voucher parameters", "required" : true, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PerformPayment" + "$ref" : "#/components/schemas/BuyVoucher" } } } } } }, - "/{owner}/payments/installments" : { + "/{user}/vouchers/data-for-redeem" : { "get" : { - "operationId" : "calculatePerformPaymentInstallments", - "summary" : "Calculates the default installments for a scheduled payment", - "description" : "Used to calculate installments for a scheduled payment. Will return an installment every month. When later performing the payment, these can be (optionally) customized (such as changing some due dates or amounts) and used on the payment installments.", - "tags" : [ "Payments" ], + "operationId" : "getVoucherInitialDataForRedeem", + "summary" : "Returns initial data for redeeming vouchers", + "description" : "Returns initial data for redeeming vouchers", + "tags" : [ "Vouchers" ], "security" : [ { "basic" : [ ] }, { @@ -18474,70 +29606,17 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/owner" - }, { "$ref" : "#/components/parameters/fields" }, { - "name" : "to", - "in" : "query", - "required" : true, - "description" : "The payment destination", - "schema" : { - "type" : "string" - } - }, { - "name" : "count", - "in" : "query", - "required" : true, - "description" : "The number of installments", - "schema" : { - "type" : "integer" - } - }, { - "name" : "amount", - "in" : "query", - "required" : true, - "description" : "The total scheduled payment amount", - "schema" : { - "type" : "string", - "format" : "number" - } - }, { - "name" : "currency", - "in" : "query", - "required" : false, - "description" : "The payment currency. Used when no `type` is not provided, to narrow the possible payment types by currency.", - "schema" : { - "type" : "string" - } - }, { - "name" : "type", - "in" : "query", - "required" : false, - "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). If not provided, will use the first possible type (possibly narrowed by the `currency` parameter). However, if more than one type is available, a validation error will be raised.", - "schema" : { - "type" : "string" - } - }, { - "name" : "firstDate", - "in" : "query", - "required" : false, - "description" : "The due date of the first installment. If none is provided, it is assumed that the first installment is paid immediately, and others will be with regular 1 month interval", - "schema" : { - "type" : "string", - "format" : "date-time" - } + "$ref" : "#/components/parameters/user" } ], "responses" : { "200" : { - "description" : "The calculated installments", + "description" : "The data for redeeming vouchers", "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/PerformScheduledPaymentInstallment" - } + "$ref" : "#/components/schemas/VoucherInitialDataForRedeem" } } } @@ -18572,16 +29651,6 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { "description" : "Unexpected error", "content" : { @@ -18595,71 +29664,39 @@ } } }, - "/easy-invoices/qr-code/{to}" : { + "/{user}/vouchers/{token}/data-for-redeem" : { "get" : { - "operationId" : "getEasyInvoiceQrCode", - "summary" : "Returns the QR-code image for the given easy invoice's parameters", - "description" : "The generated image could be scanned (e.g by the mobile application) to create a payment ready to be confirmed. The `easyInvoice` channel will be used to perform this operation, i.e the access and perform payment configurations of that channel will be applied.", - "tags" : [ "EasyInvoices" ], - "parameters" : [ { - "name" : "to", - "in" : "path", - "x-dotInPath" : true, - "required" : true, - "description" : "The user which will receive the easy invoice. Unlike other cases of user reference, in this case `self` cannot be used, because the URL may be shared with others, hence, `self` makes no sense.", - "schema" : { - "type" : "string" - } + "operationId" : "getVoucherDataForRedeem", + "summary" : "Returns data for redeeming a voucher by token", + "description" : "Data for redeeming a specific voucher", + "tags" : [ "Vouchers" ], + "security" : [ { + "basic" : [ ] }, { - "name" : "amount", - "in" : "query", - "required" : false, - "description" : "The easy invoice amount. If provided and the user has multiple currencies, either `type` or `currency` is required.", - "schema" : { - "type" : "string", - "format" : "number" - } + "session" : [ ] }, { - "name" : "currency", - "in" : "query", - "required" : false, - "description" : "The currency id or internal name. Either this or `type` should be informed if an `amount` was given and the user has multiple currencies.", - "schema" : { - "type" : "string" - } + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" }, { - "name" : "description", - "in" : "query", - "required" : false, - "description" : "The payment description", - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/user" }, { - "name" : "type", - "in" : "query", - "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). Either this or `currency` should be informed if an `amount` was given and the user has multiple currencies.", + "name" : "token", + "description" : "The voucher token to be redeemed", + "in" : "path", + "required" : true, "schema" : { "type" : "string" } - }, { - "$ref" : "#/components/parameters/customFields" - }, { - "name" : "size", - "in" : "query", - "required" : false, - "schema" : { - "$ref" : "#/components/schemas/ImageSizeEnum" - } } ], "responses" : { "200" : { - "description" : "The image content", + "description" : "The data for redeeming vouchers", "content" : { - "image/png" : { + "application/json" : { "schema" : { - "type" : "string", - "format" : "binary" + "$ref" : "#/components/schemas/VoucherDataForRedeem" } } } @@ -18695,11 +29732,11 @@ } }, "500" : { - "description" : "Unexpected error", + "description" : "An error occurred while retrieving data for redeeming the voucher", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Error" + "$ref" : "#/components/schemas/RedeemVoucherError" } } } @@ -18707,58 +29744,45 @@ } } }, - "/easy-invoices/data-for-perform/{to}" : { - "get" : { - "operationId" : "dataForPerformEasyInvoice", - "summary" : "Returns data for an easy invoice to the given user.", - "description" : "An easy invoice is a pre-filled payment from the authenticated user to another user. Other users can use this for a payment template to that user, with pre-filled data. If an amount is specified, then either there must be only payment types of a single currency to the given user, or either a payment type or currency must be informed. The `easyInvoice` channel will be used to perform this operation, i.e the access and perform payment configurations of that channel will be applied.", - "tags" : [ "EasyInvoices" ], + "/{user}/vouchers/{token}/redeem" : { + "post" : { + "operationId" : "redeemVoucher", + "summary" : "Redeems a voucher for the given user", + "description" : "Redeems a voucher", + "tags" : [ "Vouchers" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "$ref" : "#/components/parameters/user" }, { - "name" : "to", + "name" : "token", + "description" : "The voucher token to be redeemed", "in" : "path", - "x-dotInPath" : true, "required" : true, - "description" : "The user which will receive the easy invoice. Unlike other cases of user reference, in this case `self` cannot be used, because the URL may be shared with others, hence, `self` makes no sense.", - "schema" : { - "type" : "string" - } - }, { - "name" : "amount", - "in" : "query", - "required" : false, - "description" : "The easy invoice amount. If provided and the user has multiple currencies, either `type` or `currency` is required.", - "schema" : { - "type" : "string", - "format" : "number" - } - }, { - "name" : "type", - "in" : "query", - "required" : false, - "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). Either this or `currency` should be informed if an `amount` was given and the user has multiple currencies.", - "schema" : { - "type" : "string" - } - }, { - "name" : "currency", - "in" : "query", - "required" : false, - "description" : "The currency id or internal name. Either this or `type` should be informed if an `amount` was given and the user has multiple currencies.", "schema" : { "type" : "string" } - }, { - "$ref" : "#/components/parameters/customFields" } ], "responses" : { - "200" : { - "description" : "The data for easy invoice", + "201" : { + "description" : "The identifiers of the voucher and the generated payment for redeem", + "headers" : { + "Location" : { + "description" : "URL for viewing the redeemed voucher", + "schema" : { + "type" : "string" + } + } + }, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/DataForEasyInvoice" + "$ref" : "#/components/schemas/VoucherRedeemResult" } } } @@ -18794,102 +29818,59 @@ } }, "500" : { - "description" : "Unexpected error", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/easy-invoices" : { - "post" : { - "operationId" : "performEasyInvoice", - "summary" : "Performs a direct payment from an easy invoice.", - "description" : "Performs a direct payment from the authenticated user to the owner specified on the body. The destination user should be informed in the `subject` parameter (the subject `system` is not allowed). The payment id is returned on the response, and a link to the transaction details is returned on the `Location` header. The `easyInvoice` channel will be used to perform this operation, i.e the access and perform payment configurations of that channel will be applied.", - "tags" : [ "EasyInvoices" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/confirmationPassword" - } ], - "responses" : { - "201" : { - "description" : "The created payment", - "headers" : { - "Location" : { - "description" : "URL for viewing the transaction details", - "schema" : { - "type" : "string" - } - } - }, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Transaction" - } - } - } - }, - "500" : { - "description" : "If a payment error has occurred", + "description" : "An error occurred while redeeming the voucher", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentError" + "$ref" : "#/components/schemas/RedeemVoucherError" } } } } }, "requestBody" : { - "description" : "The perform payment parameters", - "required" : true, + "description" : "Additional redeem data", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PerformPayment" + "$ref" : "#/components/schemas/RedeemVoucher" } } } } } }, - "/easy-invoices/preview" : { - "post" : { - "operationId" : "previewEasyInvoice", - "summary" : "Previews a direct payment from an easy invoice before performing it.", - "description" : "Previews a direct payment from the logged created from an easy invoice. The actual balance checking is not performed in the preview. The `easyInvoice` channel will be used to perform this operation, i.e the access and perform payment configurations of that channel will be applied.", - "tags" : [ "EasyInvoices" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + "/tickets/data-for-new" : { + "get" : { + "operationId" : "dataForNewTicket", + "summary" : "Returns data for create a new ticket for the logged user.", + "tags" : [ "Tickets" ], "parameters" : [ { "$ref" : "#/components/parameters/fields" + }, { + "name" : "type", + "in" : "query", + "required" : false, + "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). If no payment type is provided, the possible types will be returned, so the payer can choose.", + "schema" : { + "type" : "string" + } + }, { + "name" : "payer", + "in" : "query", + "required" : false, + "description" : "Will only be used if no specific payment type is given. An identification for the user which will pay the ticket. Is optional, and in most cases, should be left empty. If specified, the returned payment types will take into account those that can be paid by the given user.", + "schema" : { + "type" : "string" + } } ], "responses" : { "200" : { - "description" : "The payment preview", + "description" : "The data for creating a ticket", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentPreview" + "$ref" : "#/components/schemas/DataForTransaction" } } } @@ -18924,16 +29905,6 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { "description" : "Unexpected error", "content" : { @@ -18944,47 +29915,36 @@ } } } - }, - "requestBody" : { - "description" : "The perform payment parameters", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/PerformPayment" - } - } - } } } }, - "/scheduled-payments/{key}/block" : { - "post" : { - "operationId" : "blockScheduledPayment", - "summary" : "Blocks a scheduled payment.", - "description" : "Blocks a scheduled payment, preventing its installments from being automatically processed. The scheduled payment status must be `open`. This action is to be performed by the scheduled payment payer.", - "tags" : [ "ScheduledPayments" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + "/tickets/{ticket}" : { + "get" : { + "operationId" : "viewTicket", + "summary" : "Returns details about a ticket by ticket number", + "description" : "Returns details about a ticket by ticket number.", + "tags" : [ "Tickets" ], "parameters" : [ { - "$ref" : "#/components/parameters/confirmationPassword" + "$ref" : "#/components/parameters/fields" }, { - "name" : "key", + "name" : "ticket", "in" : "path", "required" : true, - "description" : "Either the id or transaction number.", + "description" : "The ticket number", "schema" : { "type" : "string" } } ], "responses" : { - "204" : { - "description" : "The scheduled payment is blocked and nothing is returned." + "200" : { + "description" : "Transaction details", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TransactionView" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -19029,12 +29989,12 @@ } } }, - "/scheduled-payments/{key}/unblock" : { + "/tickets" : { "post" : { - "operationId" : "unblockScheduledPayment", - "summary" : "Unblocks a scheduled payment.", - "description" : "Unblocks a previously blocked scheduled payment The scheduled payment status must be `blocked`. This action is to be performed by the scheduled payment payer.", - "tags" : [ "ScheduledPayments" ], + "operationId" : "newTicket", + "summary" : "Creates a new ticket with status `open` for the logged user.", + "description" : "The logged user will be the ticket's owner and then the receiver of the payment generated after processing the ticket only if was previously approved by the payer.", + "tags" : [ "Tickets" ], "security" : [ { "basic" : [ ] }, { @@ -19043,19 +30003,26 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/confirmationPassword" - }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number.", - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/fields" } ], "responses" : { - "204" : { - "description" : "The scheduled payment is unblocked and nothing is returned." + "201" : { + "description" : "The created ticket", + "headers" : { + "Location" : { + "description" : "URL for viewing the ticket details", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Transaction" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -19087,6 +30054,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -19097,36 +30074,53 @@ } } } + }, + "requestBody" : { + "description" : "The data to create the new ticket", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TicketNew" + } + } + } } } }, - "/scheduled-payments/{key}/cancel" : { - "post" : { - "operationId" : "cancelScheduledPayment", - "summary" : "Cancels a scheduled payment.", - "description" : "Permanently cancels a scheduled payment. The scheduled payment status must be either `open` or `blocked`. This action is to be performed by the scheduled payment payer.", - "tags" : [ "ScheduledPayments" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + "/tickets/{ticket}/qr-code" : { + "get" : { + "operationId" : "getTicketQrCode", + "summary" : "Returns the QR-code image for the given ticket only if its status is `open`", + "description" : "This request will return the image contents as expected but our api documentation page (or any other usage of an <img> tag), created using swagger-ui, generates a second request to include the image in the page. This new (GET) request won't send the authentication parameters and as this path requires authentication the image will be shown as broken. Optionally, to solve the problem described above and to allow authenticate the user when using sessions, a `sessionToken` or `accessClientToken` query parameter could be specified.", + "tags" : [ "Tickets" ], "parameters" : [ { - "$ref" : "#/components/parameters/confirmationPassword" - }, { - "name" : "key", + "name" : "ticket", + "description" : "The ticket number.", "in" : "path", "required" : true, - "description" : "Either the id or transaction number.", "schema" : { "type" : "string" } + }, { + "name" : "size", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/ImageSizeEnum" + } } ], "responses" : { - "204" : { - "description" : "The scheduled payment is canceled and nothing is returned." + "200" : { + "description" : "The image content", + "content" : { + "image/png" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -19171,12 +30165,12 @@ } } }, - "/scheduled-payments/{key}/settle-remaining" : { + "/tickets/{ticket}/preview" : { "post" : { - "operationId" : "settleScheduledPayment", - "summary" : "Settles all remaining installments in a scheduled payment.", - "description" : "Settles all remaining installments, closing the scheduled payment. The scheduled payment status must be either `open` or `blocked`. This action is to be performed by the scheduled payment payee.", - "tags" : [ "ScheduledPayments" ], + "operationId" : "previewTicket", + "summary" : "Previews the payment generated by the ticket.", + "description" : "Previews the payment that will be generated if the ticket is approved by a user (i.e the payer). The ticket status must be `open` and `successUrl` null or `approved`. The actual balance checking is not performed in the preview.", + "tags" : [ "Tickets" ], "security" : [ { "basic" : [ ] }, { @@ -19185,19 +30179,26 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/confirmationPassword" + "$ref" : "#/components/parameters/fields" }, { - "name" : "key", + "name" : "ticket", + "description" : "The ticket number", "in" : "path", "required" : true, - "description" : "Either the id or transaction number.", "schema" : { "type" : "string" } } ], "responses" : { - "204" : { - "description" : "The scheduled payment is closed and nothing is returned." + "200" : { + "description" : "The approval preview", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TicketPreview" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -19229,6 +30230,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -19242,12 +30253,12 @@ } } }, - "/scheduled-payments/installments/{id}/process" : { + "/tickets/{ticket}/cancel" : { "post" : { - "operationId" : "processScheduledPaymentInstallment", - "summary" : "Processes a single scheduled payment installment.", - "description" : "Processes a single installment. The installment status must be either `scheduled`, `failed` or `blocked`. This action is to be performed by the scheduled payment payer.", - "tags" : [ "ScheduledPayments" ], + "operationId" : "cancelTicket", + "summary" : "Cancels a ticket by the receiver.", + "description" : "Cancels a ticket by the receiver before being approved by the payer. The logged user must be the ticket's owner.", + "tags" : [ "Tickets" ], "security" : [ { "basic" : [ ] }, { @@ -19256,30 +30267,17 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/confirmationPassword" - }, { - "$ref" : "#/components/parameters/id" + "name" : "ticket", + "description" : "The ticket number", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } } ], "responses" : { - "201" : { - "description" : "The installment is processed and the transfer is returned", - "headers" : { - "Location" : { - "description" : "URL for viewing the transfer details", - "schema" : { - "type" : "string" - } - } - }, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Transfer" - } - } - } + "204" : { + "description" : "The ticket was canceled. Nothing is returned." }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -19324,12 +30322,12 @@ } } }, - "/scheduled-payments/installments/{id}/settle" : { + "/tickets/{ticket}/approve" : { "post" : { - "operationId" : "settleScheduledPaymentInstallment", - "summary" : "Settles a single scheduled payment installment.", - "description" : "Settles a single installment. The installment status must be either `scheduled`, `failed` or `blocked`. This action is to be performed by the scheduled payment payee.", - "tags" : [ "ScheduledPayments" ], + "operationId" : "approveTicket", + "summary" : "Approves a ticket by the payer.", + "description" : "After a successful approval, a new direct payment from the logged user (i.e the payer) to the user who created the ticket will be generated ONLY if the ticket doesn't have a defined `successUrl` nor `successWebhook`, in that case the ticket goes to `processed` status. Otherwise the ticket just goes to the `approved` status and the corresponding payment will be generated only after the ticket is processed by the receiver.", + "tags" : [ "Tickets" ], "security" : [ { "basic" : [ ] }, { @@ -19338,50 +30336,99 @@ "accessClient" : [ ] } ], "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { "$ref" : "#/components/parameters/confirmationPassword" }, { - "$ref" : "#/components/parameters/id" + "name" : "ticket", + "description" : "The ticket number", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } } ], "responses" : { - "204" : { - "description" : "The installment is unblocked and nothing is returned." - }, - "401" : { - "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "200" : { + "description" : "The approval result.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/UnauthorizedError" + "$ref" : "#/components/schemas/TicketApprovalResult" } } } }, - "403" : { - "description" : "Permission denied for such operation", + "500" : { + "description" : "If a payment error has occurred", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ForbiddenError" + "$ref" : "#/components/schemas/PaymentError" } } } - }, - "404" : { - "description" : "An expected data was not found", + } + } + } + }, + "/tickets/{ticket}/process" : { + "post" : { + "operationId" : "processTicket", + "summary" : "Processes a ticket by the receiver.", + "description" : "Processes an already approved ticket generating a new direct payment from the user who approve the ticket to the logged user (i.e the ticket's creator). A ticket can be processed only if its status is `approved` and the `orderId` (if any) matches the one given at ticket creation. After successfully processing it goes to the final status: `processed`.", + "tags" : [ "Tickets" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "ticket", + "description" : "The ticket number", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "name" : "orderId", + "description" : "The order id given at ticket creation. Must be specified only if an `orderId` was given when the ticket was created.", + "in" : "query", + "required" : false, + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "The process result", + "headers" : { + "Location" : { + "description" : "URL for viewing the payment details", + "schema" : { + "type" : "string" + } + } + }, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/NotFoundError" + "$ref" : "#/components/schemas/TicketProcessResult" } } } }, "500" : { - "description" : "Unexpected error", + "description" : "If a payment error has occurred", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Error" + "$ref" : "#/components/schemas/PaymentError" } } } @@ -19389,12 +30436,12 @@ } } }, - "/recurring-payments/{key}/cancel" : { - "post" : { - "operationId" : "cancelRecurringPayment", - "summary" : "Cancels a recurring payment.", - "description" : "Permanently cancels a recurring payment. The recurring payment status must be `open`.", - "tags" : [ "RecurringPayments" ], + "/{owner}/record-types" : { + "get" : { + "operationId" : "listRecordTypesByOwner", + "summary" : "Lists the record types over a user or system", + "description" : "Returns the record types the authenticated user can view over the given user or system if the `system` owner is used.", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -19403,19 +30450,23 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/confirmationPassword" + "$ref" : "#/components/parameters/fields" }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number.", - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/owner" } ], "responses" : { - "204" : { - "description" : "The recurring payment is canceled and nothing is returned." + "200" : { + "description" : "The list of visible record types", + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/OwnerRecordPermissions" + } + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -19460,12 +30511,12 @@ } } }, - "/recurring-payments/occurrences/{id}/process-failed" : { - "post" : { - "operationId" : "processFailedRecurringPaymentOccurrence", - "summary" : "Processes a failed recurring payment occurrence.", - "description" : "Processes a failed recurring payment occurrence. The occurrence status must be `failed`.", - "tags" : [ "RecurringPayments" ], + "/{owner}/record-types/{type}" : { + "get" : { + "operationId" : "getRecordTypeByOwner", + "summary" : "Returns a single record type over a user or system", + "description" : "Returns the a specific record type the authenticated user can view over the given user or system if the `system` owner is used.", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -19476,25 +30527,23 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/confirmationPassword" + "$ref" : "#/components/parameters/owner" }, { - "$ref" : "#/components/parameters/id" + "name" : "type", + "description" : "Either the identifier or internal name of the record type", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } } ], "responses" : { - "201" : { - "description" : "The occurrence is processed and the transfer is returned", - "headers" : { - "Location" : { - "description" : "URL for viewing the transfer details", - "schema" : { - "type" : "string" - } - } - }, + "200" : { + "description" : "The record type details", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Transfer" + "$ref" : "#/components/schemas/OwnerRecordPermissions" } } } @@ -19542,12 +30591,12 @@ } } }, - "/{owner}/payment-requests/data-for-send" : { + "/{owner}/records/{type}/data-for-search" : { "get" : { - "operationId" : "dataForSendPaymentRequest", - "summary" : "Returns configuration data for sending a payment request", - "description" : "Returns configuration data for sending a payment request", - "tags" : [ "PaymentRequests" ], + "operationId" : "getRecordDataForOwnerSearch", + "summary" : "Returns data for searching records of a specific type and owner", + "description" : "Returns data for searching records of a specific type, either for system or user records, depending on the `owner` parameter.", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -19556,33 +30605,25 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/owner" - }, { "$ref" : "#/components/parameters/fields" }, { - "name" : "to", - "in" : "query", - "required" : false, - "description" : "The payment request destination, which is either string `system` for a payment request to system or a user identification. The payment request destination is the one that performs the payment once it is accepted.", - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/owner" }, { "name" : "type", - "in" : "query", - "required" : false, - "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). If no payment type is provided, the possible types will be returned, so the payer can choose.", + "description" : "Either the identifier or internal name of the record type", + "in" : "path", + "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { - "description" : "The data for sending a payment request", + "description" : "The configuration data for searching records", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/DataForTransaction" + "$ref" : "#/components/schemas/RecordDataForSearch" } } } @@ -19630,12 +30671,12 @@ } } }, - "/{owner}/payment-requests" : { - "post" : { - "operationId" : "sendPaymentRequest", - "summary" : "Sends a payment request from the given owner", - "description" : "Sends a payment request from the owner indicated on the path (which will receive the payment once the request is accepted) to the owner specified on the body (which will perform the payment once the request is accepted). The destination user should be informed in the `subject` parameter. If the `subject` is `system`, the payment request is sent to a system account, and has to be accepted by an administrator. The payment request id is returned on the response, and a link to the transaction details is returned on the `Location` header.", - "tags" : [ "PaymentRequests" ], + "/{owner}/records/{type}" : { + "get" : { + "operationId" : "searchOwnerRecords", + "summary" : "Searches for records of a specific type and owner", + "description" : "Returns records matching the search criteria, for a specific type, either for system or user records, depending on the `owner` parameter. The custom fields returned on each record depend on the field configuration, which needs to be enabled to return on list. The profile fields available as search filters for records are assigned in the products (or admin group permissions).", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -19647,225 +30688,207 @@ "$ref" : "#/components/parameters/fields" }, { "$ref" : "#/components/parameters/owner" - } ], - "responses" : { - "201" : { - "description" : "The created payment request", - "headers" : { - "Location" : { - "description" : "URL for viewing the transaction details", - "schema" : { - "type" : "string" - } - } - }, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Transaction" - } - } - } - }, - "500" : { - "description" : "If a payment error has occurred", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/PaymentError" - } - } + }, { + "name" : "type", + "description" : "Either the identifier or internal name of the record type", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "name" : "createdBy", + "in" : "query", + "required" : false, + "description" : "Either the id or identifier of the user that created the record", + "schema" : { + "type" : "string" + } + }, { + "name" : "creationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum record creation date", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" } } - }, - "requestBody" : { - "description" : "The send payment request parameters", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/SendPaymentRequest" - } + }, { + "name" : "customFields", + "in" : "query", + "required" : false, + "description" : "Record custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=tradeType:offer|search,extraDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `tradeType` is either `offer` or `search`, and whose `extraDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=extraDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `customFields=dynamic:'business`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" } } - } - } - }, - "/payment-requests/{key}/accept" : { - "post" : { - "operationId" : "acceptPaymentRequest", - "summary" : "Accepts a payment request.", - "description" : "Accepts a payment request in status `open`. After accepting the payment request its resultant status could be `processed` (and the corresponding sheduled or direct payment was generated) or `scheduled`. This can be done only by managers or the payer (i.e the request's recipient) with permission to accept.", - "tags" : [ "PaymentRequests" ], - "security" : [ { - "basic" : [ ] }, { - "session" : [ ] + "name" : "keywords", + "in" : "query", + "required" : false, + "description" : "Textual search keywords. Sometimes, like in user search, the fields matched depends on what is configured on the products.", + "schema" : { + "type" : "string" + } }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } }, { - "$ref" : "#/components/parameters/confirmationPassword" + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number.", + "name" : "profileFields", + "in" : "query", + "required" : false, + "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", "schema" : { - "type" : "string" + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" } } ], "responses" : { - "201" : { - "description" : "The performed payment. Only if the process date was not given (i.e the request was processed immediately).", + "200" : { + "description" : "The records matching the search filters.", "headers" : { - "Location" : { - "description" : "URL for viewing the payment details", + "X-Total-Count" : { "schema" : { - "type" : "string" - } + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." } }, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Transaction" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/RecordResult" + } } } } }, - "204" : { - "description" : "The payment request was accepted and scheduled for processing at the given date. Nothing is returned." - }, - "500" : { - "description" : "If a payment error has occurred", + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentError" + "$ref" : "#/components/schemas/UnauthorizedError" } } } - } - }, - "requestBody" : { - "description" : "The parameters to accept a payment request", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/AcceptOrReschedulePaymentRequest" - } - } - } - } - } - }, - "/payment-requests/{key}/reschedule" : { - "post" : { - "operationId" : "reschedulePaymentRequest", - "summary" : "Reschedules a payment request.", - "description" : "Reschedules an already accepted and scheduled payment request (i.e with status `scheduled`). If the new processing date is null then the payment request will be processed immediately generating the corresponding payment. Otherwise it will be scheduled to be processed at the given date. This can be done only by managers or the payer (i.e the request's recipient) with permission to accept.", - "tags" : [ "PaymentRequests" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/confirmationPassword" - }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number.", - "schema" : { - "type" : "string" - } - } ], - "responses" : { - "201" : { - "description" : "The performed payment. Only if the process date was not given (i.e the request was processed immediately).", - "headers" : { - "Location" : { - "description" : "URL for viewing the payment details", + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { "schema" : { - "type" : "string" + "$ref" : "#/components/schemas/ForbiddenError" } } - }, + } + }, + "404" : { + "description" : "An expected data was not found", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Transaction" + "$ref" : "#/components/schemas/NotFoundError" } } } }, - "204" : { - "description" : "The payment request was rescheduled. Nothing is returned." - }, "500" : { - "description" : "If a payment error has occurred", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentError" + "$ref" : "#/components/schemas/Error" } } } } - }, - "requestBody" : { - "description" : "The parameters to reschedule a payment request.", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/AcceptOrReschedulePaymentRequest" - } - } - } } - } - }, - "/payment-requests/{key}/preview" : { - "get" : { - "operationId" : "previewPaymentRequest", - "summary" : "Previews the payment performed when accepting the given payment request.", - "description" : "Previews the payment ony if the payment request status is `open` or `scheduled`.", - "tags" : [ "PaymentRequests" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + }, + "post" : { + "operationId" : "createRecord", + "summary" : "Creates a new record for the given owner and type", + "description" : "Creates a new record for the given owner and type. If the owner is `system` will be a system record. Otherwise will be a user record.", + "tags" : [ "Records" ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "$ref" : "#/components/parameters/owner" }, { - "name" : "key", + "name" : "type", + "description" : "Either the identifier or internal name of the record type", "in" : "path", "required" : true, - "description" : "Either the id or transaction number.", "schema" : { "type" : "string" } } ], "responses" : { - "200" : { - "description" : "The payment preview", + "201" : { + "description" : "Returns the identifier of the new record", + "headers" : { + "Location" : { + "description" : "URL for viewing the record details", + "schema" : { + "type" : "string" + } + } + }, "content" : { - "application/json" : { + "text/plain" : { "schema" : { - "$ref" : "#/components/schemas/PaymentPreview" + "type" : "string" } } } @@ -19920,69 +30943,39 @@ } } } - } - } - }, - "/payment-requests/{key}/change-expiration" : { - "post" : { - "operationId" : "changePaymentRequestExpirationDate", - "summary" : "Changes the payment request expiration.", - "description" : "Change the expiration date of a payment request in status `open` or `expired`. This can be done only by managers or the payee (i.e the request's sender) with permission to change the expiration.", - "tags" : [ "PaymentRequests" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/confirmationPassword" - }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number.", - "schema" : { - "type" : "string" - } - } ], - "responses" : { - "204" : { - "description" : "The payment request expiration date was changed. Nothing is returned." - }, - "500" : { - "description" : "If a payment error has occurred", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/PaymentError" - } - } - } - } }, "requestBody" : { - "description" : "The parameters to change the payment request's expiration date", + "description" : "The record to be created", "required" : true, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ChangePaymentRequestExpirationDate" + "$ref" : "#/components/schemas/RecordNew" } } } } } }, - "/payment-requests/{key}/reject" : { - "post" : { - "operationId" : "rejectPaymentRequest", - "summary" : "Rejects a payment request.", - "description" : "Rejects a payment request in status `open`. This can be done only by managers or the payer (i.e the request's recipient) with permission to accept.", - "tags" : [ "PaymentRequests" ], + "/{owner}/records/{type}/export/{format}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/owner" + }, { + "name" : "type", + "description" : "Either the identifier or internal name of the record type", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "$ref" : "#/components/parameters/format" + } ], + "get" : { + "operationId" : "exportOwnerRecords", + "summary" : "Exports the records search results as file", + "description" : "Generates a file containing the search results. The available export formats are returned in `GET /{owner}/records/{type}/data-for-search`.", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -19991,19 +30984,96 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/confirmationPassword" + "name" : "createdBy", + "in" : "query", + "required" : false, + "description" : "Either the id or identifier of the user that created the record", + "schema" : { + "type" : "string" + } }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number", + "name" : "creationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum record creation date", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "customFields", + "in" : "query", + "required" : false, + "description" : "Record custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=tradeType:offer|search,extraDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `tradeType` is either `offer` or `search`, and whose `extraDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=extraDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `customFields=dynamic:'business`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "keywords", + "in" : "query", + "required" : false, + "description" : "Textual search keywords. Sometimes, like in user search, the fields matched depends on what is configured on the products.", "schema" : { "type" : "string" } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "profileFields", + "in" : "query", + "required" : false, + "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } } ], "responses" : { - "204" : { - "description" : "The payment request was rejected. Nothing is returned." + "200" : { + "description" : "The file content", + "content" : { + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -20045,25 +31115,15 @@ } } } - }, - "requestBody" : { - "description" : "A comment for the reject action the payer can set.", - "content" : { - "text/plain" : { - "schema" : { - "type" : "string" - } - } - } } } }, - "/payment-requests/{key}/cancel" : { - "post" : { - "operationId" : "cancelPaymentRequest", - "summary" : "Cancels a payment request.", - "description" : "Cancels a payment request in status `open`. This can be done only by managers or the payee with permission to cancel.", - "tags" : [ "PaymentRequests" ], + "/{owner}/records/{type}/data-for-new" : { + "get" : { + "operationId" : "getRecordDataForNew", + "summary" : "Returns data to create a new record", + "description" : "Returns configuration data for creating a record for the given owner and type. If the owner is `system` will be a system record. Otherwise will be a user record.", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -20072,19 +31132,28 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/confirmationPassword" + "$ref" : "#/components/parameters/fields" }, { - "name" : "key", - "in" : "path", + "$ref" : "#/components/parameters/owner" + }, { + "name" : "type", "required" : true, - "description" : "Either the id or transaction number", + "in" : "path", + "description" : "The record type to be created", "schema" : { "type" : "string" } } ], "responses" : { - "204" : { - "description" : "The payment request was cancelled. Nothing is returned." + "200" : { + "description" : "The data for creating a record", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/RecordDataForNew" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -20126,25 +31195,15 @@ } } } - }, - "requestBody" : { - "description" : "A comment for the cancel action the payee/manager can set.", - "content" : { - "text/plain" : { - "schema" : { - "type" : "string" - } - } - } } } }, - "/pending-payments/{key}/authorize" : { - "post" : { - "operationId" : "authorizePendingPayment", - "summary" : "Authorizes a pending payment.", - "description" : "Authorizes a payment / scheduled payment / recurring payment whose authorization status is `pending`.", - "tags" : [ "PendingPayments" ], + "/records/{id}/data-for-edit" : { + "get" : { + "operationId" : "getRecordDataForEdit", + "summary" : "Returns data to edit an existing record", + "description" : "Returns configuration data for editing a record, plus the current `RecordEdit` object that can be altered and sent back", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -20155,81 +31214,18 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/confirmationPassword" - }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number.", - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/id" } ], "responses" : { "200" : { - "description" : "The payment is authorized. The next authorization level is returned, in case the payment is still pending another authorization, or returns a no-content when the payment is authorized.", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/TransactionAuthorizationLevelData" - } - } - } - }, - "204" : { - "description" : "Nothing is returned if the transaction authorization process is finished, and the transaction is processed." - }, - "500" : { - "description" : "If a payment error has occurred", + "description" : "The data for editing a record", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentError" + "$ref" : "#/components/schemas/RecordDataForEdit" } } } - } - }, - "requestBody" : { - "description" : "Contains the action comments", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/PendingPaymentActionParams" - } - } - } - } - } - }, - "/pending-payments/{key}/deny" : { - "post" : { - "operationId" : "denyPendingPayment", - "summary" : "Denies a pending payment.", - "description" : "Denies a payment / scheduled payment / recurring payment whose authorization status is `pending`.", - "tags" : [ "PendingPayments" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "$ref" : "#/components/parameters/confirmationPassword" - }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number.", - "schema" : { - "type" : "string" - } - } ], - "responses" : { - "204" : { - "description" : "The payment is denied. Nothing is returned." }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -20271,26 +31267,15 @@ } } } - }, - "requestBody" : { - "description" : "Contains the action comments", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/PendingPaymentActionParams" - } - } - } } } }, - "/pending-payments/{key}/cancel" : { - "post" : { - "operationId" : "cancelPendingPayment", - "summary" : "Cancels the authorization process of a pending payment.", - "description" : "Cancels a payment / scheduled payment / recurring payment whose authorization status is `pending`. This action is performed by the payer.", - "tags" : [ "PendingPayments" ], + "/records/{id}" : { + "get" : { + "operationId" : "viewRecord", + "summary" : "Returns details of a specific record", + "description" : "Returns information about a record, located by id", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -20299,19 +31284,20 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/confirmationPassword" + "$ref" : "#/components/parameters/fields" }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number.", - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/id" } ], "responses" : { - "204" : { - "description" : "The payment is canceled. Nothing is returned." + "200" : { + "description" : "The record data", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/RecordView" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -20353,26 +31339,13 @@ } } } - }, - "requestBody" : { - "description" : "Contains the action comments", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/PendingPaymentActionParams" - } - } - } } - } - }, - "/pos/data-for-pos" : { - "get" : { - "operationId" : "dataForReceivePayment", - "summary" : "Returns configuration data for receiving a payment (POS)", - "description" : "Returns configuration data for receiving a payment in POS operation", - "tags" : [ "POS" ], + }, + "put" : { + "operationId" : "updateRecord", + "summary" : "Updates an existing record", + "description" : "Updates an existing record", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -20381,31 +31354,18 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "name" : "from", - "in" : "query", - "required" : false, - "description" : "Identification of the payer user", - "schema" : { - "type" : "string" - } - }, { - "name" : "type", - "in" : "query", - "required" : false, - "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). If no payment type is provided, the possible types will be returned, so the payer can choose.", - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/id" } ], "responses" : { - "200" : { - "description" : "The data for receiving a payment", + "204" : { + "description" : "The record was updated" + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/DataForTransaction" + "$ref" : "#/components/schemas/ConflictError" } } } @@ -20440,86 +31400,44 @@ } } }, - "500" : { - "description" : "If a POS error has occurred", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/PosError" - } - } - } - } - } - } - }, - "/pos" : { - "post" : { - "operationId" : "receivePayment", - "summary" : "Receives a payment (POS)", - "description" : "Receives either a direct or scheduled payment in a POS operation for the authenticated user. The payer user should be informed in the `subject` parameter. The payment id is returned on the response, and a link to the transaction details is returned on the `Location` header.", - "tags" : [ "POS" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/confirmationPassword" - } ], - "responses" : { - "201" : { - "description" : "The created payment", - "headers" : { - "Location" : { - "description" : "URL for viewing the transaction details", - "schema" : { - "type" : "string" - } - } - }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Transaction" + "$ref" : "#/components/schemas/InputError" } } } }, "500" : { - "description" : "If a payment error has occurred", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentError" + "$ref" : "#/components/schemas/Error" } } } } }, "requestBody" : { - "description" : "The receive payment parameters", + "description" : "The record to be edited", "required" : true, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PerformPayment" + "$ref" : "#/components/schemas/RecordEdit" } } } } - } - }, - "/pos/preview" : { - "post" : { - "operationId" : "previewReceivePayment", - "summary" : "Previews a POS payment before receiving it", - "description" : "Previews a payment or scheduled payment. The actual balance checking is not performed in the preview.", - "tags" : [ "POS" ], + }, + "delete" : { + "operationId" : "deleteRecord", + "summary" : "Removes a record", + "description" : "Removes a record", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -20528,15 +31446,18 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "$ref" : "#/components/parameters/id" } ], "responses" : { - "200" : { - "description" : "The payment preview", + "204" : { + "description" : "The record was deleted" + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentPreview" + "$ref" : "#/components/schemas/ConflictError" } } } @@ -20571,46 +31492,25 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { - "description" : "If a POS error has occurred", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PosError" + "$ref" : "#/components/schemas/Error" } } } } - }, - "requestBody" : { - "description" : "The receive payment parameters", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/PerformPayment" - } - } - } } } }, - "/pos/installments" : { + "/general-records/record-types" : { "get" : { - "operationId" : "calculateReceivePaymentInstallments", - "summary" : "Calculates the default installments for a scheduled payment", - "description" : "Used to calculate installments for a scheduled payment. Will return an installment every month. When later receiving the payment, these can be (optionally) customized (such as changing some due dates or amounts) and used on the payment installments.", - "tags" : [ "POS" ], + "operationId" : "listRecordTypesForGeneralSearch", + "summary" : "Lists the record types for general search", + "description" : "Returns the record types the authenticated user can use to search records in general, that is, without being of a particular user, but any managed user.", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -20620,66 +31520,16 @@ } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" - }, { - "name" : "from", - "in" : "query", - "required" : true, - "description" : "The payment origin", - "schema" : { - "type" : "string" - } - }, { - "name" : "count", - "in" : "query", - "required" : true, - "description" : "The number of installments", - "schema" : { - "type" : "integer" - } - }, { - "name" : "amount", - "in" : "query", - "required" : true, - "description" : "The total scheduled payment amount", - "schema" : { - "type" : "string", - "format" : "number" - } - }, { - "name" : "currency", - "in" : "query", - "required" : false, - "description" : "The payment currency. Used when no `type` is not provided, to narrow the possible payment types by currency.", - "schema" : { - "type" : "string" - } - }, { - "name" : "type", - "in" : "query", - "required" : false, - "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). If not provided, will use the first possible type (possibly narrowed by the `currency` parameter). However, if more than one type is available, a validation error will be raised.", - "schema" : { - "type" : "string" - } - }, { - "name" : "firstDate", - "in" : "query", - "required" : false, - "description" : "The due date of the first installment. If none is provided, it is assumed that the first installment is paid immediately, and others will be with regular 1 month interval", - "schema" : { - "type" : "string", - "format" : "date-time" - } } ], "responses" : { "200" : { - "description" : "The calculated installments", + "description" : "The list of visible record types", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { - "$ref" : "#/components/schemas/PerformScheduledPaymentInstallment" + "$ref" : "#/components/schemas/RecordTypeWithMenu" } } } @@ -20715,22 +31565,12 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { - "description" : "If a POS error has occurred", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PosError" + "$ref" : "#/components/schemas/Error" } } } @@ -20738,12 +31578,12 @@ } } }, - "/pos/otp" : { - "post" : { - "operationId" : "receivePaymentOtp", - "summary" : "Generates a new One-Time-Password (OTP) for a pos payment", - "description" : "Sends a new OTP for the customer of the POS for a payment. The OTP belongs to the payer, not the authenticated user. The entire payment object must be sent on the request body. This is the same object which is sent both either preview or actually receive the payment.", - "tags" : [ "POS" ], + "/general-records/{type}/data-for-search" : { + "get" : { + "operationId" : "getRecordDataForGeneralSearch", + "summary" : "Returns data for searching records of a type over any owner", + "description" : "Returns data for searching records of a specific type over any owner. Is not tied to a particular owner (user or system), hence, is considered a general search.", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -20752,17 +31592,26 @@ "accessClient" : [ ] } ], "parameters" : [ { - "name" : "medium", - "in" : "query", + "$ref" : "#/components/parameters/fields" + }, { + "name" : "type", + "description" : "Either the identifier or internal name of the record type", + "in" : "path", "required" : true, - "description" : "The medium the user wants to receive the otp", "schema" : { - "$ref" : "#/components/schemas/SendMediumEnum" + "type" : "string" } } ], "responses" : { - "204" : { - "description" : "The OTP is sent to the user, and no content is returned" + "200" : { + "description" : "The configuration data for searching records of this type", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/GeneralRecordsDataForSearch" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -20795,35 +31644,24 @@ } }, "500" : { - "description" : "There was an error when generating the OTP", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/OtpError" + "$ref" : "#/components/schemas/Error" } } } } - }, - "requestBody" : { - "description" : "The receive payment parameters", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/PerformPayment" - } - } - } } } }, - "/pos/device-confirmations" : { - "post" : { - "operationId" : "receivePaymentCreateDeviceConfirmation", - "summary" : "Creates a pending device confirmation for a pos payment.", - "description" : "Creates a device confirmation to confirm a pos payment. The confirmation will have a QR code that can be read (e.g with the Mobile App) to be approved / rejected by the payer. The confirmation belongs to the payer, not the authenticated user. The entire payment object must be sent on the request body. This is the same object which is sent both either preview or actually receive the payment.", - "tags" : [ "POS" ], + "/general-records/{type}" : { + "get" : { + "operationId" : "searchGeneralRecords", + "summary" : "Searches for records of a specific type over any owner", + "description" : "Returns records matching the search criteria, for a specific type. The custom fields returned on each record depend on the field configuration, which needs to be enabled to return on list. The profile fields available as search filters for records are assigned in the products (or admin group permissions).", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -20831,14 +31669,164 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "type", + "description" : "Either the identifier or internal name of the record type", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Either the ids or identification methods of record owners' brokers", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "createdBy", + "in" : "query", + "required" : false, + "description" : "Either the id or identifier of the user that created the record", + "schema" : { + "type" : "string" + } + }, { + "name" : "creationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum record creation date", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "customFields", + "in" : "query", + "required" : false, + "description" : "Record custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=tradeType:offer|search,extraDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `tradeType` is either `offer` or `search`, and whose `extraDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=extraDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `customFields=dynamic:'business`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Either the ids or internal names of record owners' groups", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "keywords", + "in" : "query", + "required" : false, + "description" : "Textual search keywords. Sometimes, like in user search, the fields matched depends on what is configured on the products.", + "schema" : { + "type" : "string" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "profileFields", + "in" : "query", + "required" : false, + "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Either the id or identifier of the record owner", + "schema" : { + "type" : "string" + } + } ], "responses" : { - "201" : { - "description" : "Returns the identifier of the new confirmation.", + "200" : { + "description" : "The configuration data for searching records", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, "content" : { - "text/plain" : { + "application/json" : { "schema" : { - "type" : "string" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/RecordWithOwnerResult" + } } } } @@ -20873,16 +31861,6 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { "description" : "Unexpected error", "content" : { @@ -20893,26 +31871,26 @@ } } } - }, - "requestBody" : { - "description" : "The receive payment parameters", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/PerformPayment" - } - } - } } } }, - "/pos/device-confirmations/{id}" : { + "/general-records/{type}/export/{format}" : { + "parameters" : [ { + "name" : "type", + "description" : "Either the identifier or internal name of the record type", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "$ref" : "#/components/parameters/format" + } ], "get" : { - "operationId" : "receivePaymentViewDeviceConfirmation", - "summary" : "Shows the details of a device confirmation for a POS payer.", - "description" : "Shows the details of a device confirmation for POS payer. The confirmation belongs to the payer but must had been created by the authenticated user. The entire payment object must be sent on the request body. This is the same object which is sent both either preview or actually receive the payment", - "tags" : [ "POS" ], + "operationId" : "exportGeneralRecords", + "summary" : "Exports the general records search results as file", + "description" : "Generates a file containing the search results. The available export formats are returned in `GET /general-records/{type}/data-for-search`.", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -20921,39 +31899,125 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/id" + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Either the ids or identification methods of record owners' brokers", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "createdBy", + "in" : "query", + "required" : false, + "description" : "Either the id or identifier of the user that created the record", + "schema" : { + "type" : "string" + } + }, { + "name" : "creationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum record creation date", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "customFields", + "in" : "query", + "required" : false, + "description" : "Record custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=tradeType:offer|search,extraDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `tradeType` is either `offer` or `search`, and whose `extraDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=extraDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `customFields=dynamic:'business`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Either the ids or internal names of record owners' groups", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "keywords", + "in" : "query", + "required" : false, + "description" : "Textual search keywords. Sometimes, like in user search, the fields matched depends on what is configured on the products.", + "schema" : { + "type" : "string" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } }, { - "name" : "payer", + "name" : "profileFields", "in" : "query", - "required" : true, - "description" : "A user identification value, such as id, username, e-mail, phone, etc. Id is always allowed, others depend on Cyclos configuration. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`;", + "required" : false, + "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", "schema" : { - "type" : "string" + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } } }, { - "name" : "currency", + "name" : "skipTotalCount", "in" : "query", "required" : false, - "description" : "The currency id or internal name. Only used when not specifying a payment type. In this case, will narrow the search for the payment type.", + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", "schema" : { - "type" : "string" + "type" : "boolean" } }, { - "name" : "type", + "name" : "user", "in" : "query", "required" : false, - "description" : "The payment type, either the id or qualified internal name (in the form `fromAccountType.paymentType`). If no payment type is specified, if a single one is possible, it will be used. If a currency is specified, it will be taken into account in order to find the payment type. If, however, there would be multiple possibilities, a validation error is returned.", + "description" : "Either the id or identifier of the record owner", "schema" : { "type" : "string" } } ], "responses" : { "200" : { - "description" : "The device confirmation details.", + "description" : "The file content", "content" : { - "application/json" : { + "*/*" : { "schema" : { - "$ref" : "#/components/schemas/DeviceConfirmationView" + "type" : "string", + "format" : "binary" } } } @@ -20999,12 +32063,14 @@ } } } - }, - "delete" : { - "operationId" : "receivePaymentDeleteDeviceConfirmation", - "summary" : "Deletes a device confirmation for a POS payer.", - "description" : "Deletes a device confirmation for the payer of pos payment. The confirmation belongs to the payer, not the authenticated user. The entire payment object must be sent on the request body. This is the same object which is sent both either preview or actually receive the payment.", - "tags" : [ "POS" ], + } + }, + "/shared-records/data-for-search" : { + "get" : { + "operationId" : "getRecordDataForSharedSearch", + "summary" : "Returns data for searching records with shared fields", + "description" : "Returns data for searching records from multiple types, using shared fields. Only user records can be shared this way.", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -21013,42 +32079,15 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/id" - }, { - "name" : "payer", - "in" : "query", - "required" : true, - "description" : "A user identification value, such as id, username, e-mail, phone, etc. Id is always allowed, others depend on Cyclos configuration. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`;", - "schema" : { - "type" : "string" - } - }, { - "name" : "currency", - "in" : "query", - "required" : false, - "description" : "The currency id or internal name. Only used when not specifying a payment type. In this case, will narrow the search for the payment type.", - "schema" : { - "type" : "string" - } - }, { - "name" : "type", - "in" : "query", - "required" : false, - "description" : "The payment type, either the id or qualified internal name (in the form `fromAccountType.paymentType`). If no payment type is specified, if a single one is possible, it will be used. If a currency is specified, it will be taken into account in order to find the payment type. If, however, there would be multiple possibilities, a validation error is returned.", - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/fields" } ], "responses" : { - "204" : { - "description" : "The device confirmation was removed." - }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", + "200" : { + "description" : "The configuration data for searching records with shared fields", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ConflictError" + "$ref" : "#/components/schemas/SharedRecordsDataForSearch" } } } @@ -21096,38 +32135,181 @@ } } }, - "/pos/device-confirmations/{id}/qr-code" : { + "/shared-records" : { "get" : { - "operationId" : "receivePaymentDeviceConfirmationQrCode", - "summary" : "Returns the QR-code image for the given device confirmation only if it was not yet approved / rejected", - "description" : "This request will return the image contents as expected but our api documentation page (or any other usage of an <img> tag), created using swagger-ui, generates a second request to include the image in the page. This new (GET) request won't send the authentication parameters and as this path requires authentication the image will be shown as broken. Optionally, to solve the problem described above and to allow authenticate the user when using sessions, a `sessionToken` or `accessClientToken` query parameter could be specified.", - "tags" : [ "POS" ], + "operationId" : "searchSharedRecords", + "summary" : "Searches for records with shared fields", + "description" : "Returns records matching the search criteria, using shared fields. This allows searching over multiple record types that use shared fields. The custom fields returned on each record depend on the field configuration, which needs to be enabled to return on list. The profile fields available as search filters for records are assigned in the products (or admin group permissions).", + "tags" : [ "Records" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], "parameters" : [ { - "$ref" : "#/components/parameters/id" + "$ref" : "#/components/parameters/fields" }, { - "name" : "payer", - "description" : "The payer, either a user principal (id, login name, etc) or the word `system` when the payment is to be performed to / from a system account. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`.", + "name" : "brokers", "in" : "query", - "required" : true, + "required" : false, + "description" : "Either the ids or identification methods of record owners' brokers", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "createdBy", + "in" : "query", + "required" : false, + "description" : "Either the id or identifier of the user that created the record", "schema" : { "type" : "string" } }, { - "name" : "size", + "name" : "creationPeriod", "in" : "query", "required" : false, + "description" : "The minimum / maximum record creation date", "schema" : { - "$ref" : "#/components/schemas/ImageSizeEnum" + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "customFields", + "in" : "query", + "required" : false, + "description" : "Record custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=tradeType:offer|search,extraDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `tradeType` is either `offer` or `search`, and whose `extraDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=extraDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `customFields=dynamic:'business`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Either the ids or internal names of record owners' groups", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "keywords", + "in" : "query", + "required" : false, + "description" : "Textual search keywords. Sometimes, like in user search, the fields matched depends on what is configured on the products.", + "schema" : { + "type" : "string" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "profileFields", + "in" : "query", + "required" : false, + "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "types", + "in" : "query", + "required" : false, + "description" : "Either the ids or identification methods of record types", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Either the id or identifier of the record owner", + "schema" : { + "type" : "string" } } ], "responses" : { "200" : { - "description" : "The image content", + "description" : "The configuration data for searching records", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, "content" : { - "image/png" : { + "application/json" : { "schema" : { - "type" : "string", - "format" : "binary" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/RecordWithOwnerResult" + } } } } @@ -21175,12 +32357,15 @@ } } }, - "/{user}/client-types" : { + "/shared-records/export/{format}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/format" + } ], "get" : { - "operationId" : "listClientTypesForUser", - "summary" : "Returns the list of access clients types for a user", - "description" : "Returns the access client types for a given user that the authenticated user has access.", - "tags" : [ "Clients" ], + "operationId" : "exportSharedRecords", + "summary" : "Exports the shared fields records search results as file", + "description" : "Generates a file containing the search results. The available export formats are returned in `GET /transfers/data-for-search`.", + "tags" : [ "Records" ], "security" : [ { "basic" : [ ] }, { @@ -21189,27 +32374,137 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Either the ids or identification methods of record owners' brokers", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } }, { - "$ref" : "#/components/parameters/user" + "name" : "createdBy", + "in" : "query", + "required" : false, + "description" : "Either the id or identifier of the user that created the record", + "schema" : { + "type" : "string" + } }, { - "name" : "channel", + "name" : "creationPeriod", "in" : "query", - "description" : "If a channel id or internal name is specified, will only list access client types that can be used to access that channel", + "required" : false, + "description" : "The minimum / maximum record creation date", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "customFields", + "in" : "query", + "required" : false, + "description" : "Record custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=tradeType:offer|search,extraDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `tradeType` is either `offer` or `search`, and whose `extraDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=extraDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `customFields=dynamic:'business`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Either the ids or internal names of record owners' groups", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "keywords", + "in" : "query", + "required" : false, + "description" : "Textual search keywords. Sometimes, like in user search, the fields matched depends on what is configured on the products.", + "schema" : { + "type" : "string" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "profileFields", + "in" : "query", + "required" : false, + "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "types", + "in" : "query", + "required" : false, + "description" : "Either the ids or identification methods of record types", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Either the id or identifier of the record owner", "schema" : { "type" : "string" } } ], "responses" : { "200" : { - "description" : "The list of access clients types, with permissions, for the user", + "description" : "The file content", "content" : { - "application/json" : { + "*/*" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/UserClientTypePermissions" - } + "type" : "string", + "format" : "binary" } } } @@ -21257,12 +32552,15 @@ } } }, - "/clients/activate" : { - "post" : { - "operationId" : "activateClient", - "summary" : "Activates an access client", - "description" : "Activates an access client belonging to the currently authenticated user.", - "tags" : [ "Clients" ], + "/{user}/token-types" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], + "get" : { + "operationId" : "listUserTokenTypes", + "summary" : "Returns the permissions over token types of the given user.", + "description" : "Returns the permissions the authenticated user can perform over the tokens of the given user.", + "tags" : [ "Tokens" ], "security" : [ { "basic" : [ ] }, { @@ -21271,29 +32569,18 @@ "accessClient" : [ ] } ], "parameters" : [ { - "name" : "code", - "required" : true, - "in" : "query", - "description" : "The activation code. Must match the activation code obtained in Cyclos, which belongs to the authenticated user.", - "schema" : { - "type" : "string" - } - }, { - "name" : "prefix", - "required" : false, - "in" : "query", - "description" : "A prefix to be added to the generated access client token. Can be used to increase the size of the generated token, and to increase the security on clients that have to store the token. This can be accomplished by using some sort of client application hash or identifier, which should be stable. The prefix is not returned by this method. When later passing in the full token, the prefix should prepend the returned token without any separator.", - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/fields" } ], "responses" : { "200" : { - "description" : "Returns the token to be used on subsequent requests", + "description" : "The tokens", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ActivateClientResult" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TokenPermissions" + } } } } @@ -21341,12 +32628,23 @@ } } }, - "/clients/{key}" : { + "/{user}/tokens/{type}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + }, { + "name" : "type", + "description" : "Either the identifier or internal name of the token type", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + } ], "get" : { - "operationId" : "viewClient", - "summary" : "Returns details of an access client", - "description" : "Returns the access client details, together with permissions", - "tags" : [ "Clients" ], + "operationId" : "getUserTokens", + "summary" : "Returns the tokens of a type and user", + "description" : "Returns data containing the tokens of a given type and user, along with the tokens themselves. If the authenticated user is the requested user, will only return tokens whose `status` are either `active` or `blocked`.", + "tags" : [ "Tokens" ], "security" : [ { "basic" : [ ] }, { @@ -21356,22 +32654,14 @@ } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" - }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "The access client id or token", - "schema" : { - "type" : "string" - } } ], "responses" : { "200" : { - "description" : "The access client details", + "description" : "The tokens matching the search filters", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ClientView" + "$ref" : "#/components/schemas/UserTokensListData" } } } @@ -21417,14 +32707,12 @@ } } } - } - }, - "/clients/{key}/unassign" : { + }, "post" : { - "operationId" : "unassignClient", - "summary" : "Unassign (disconnects) an access client", - "description" : "Unassigns an access client by id or token. It must be currently assigned. After this call, the client can be assigned again if needed.", - "tags" : [ "Clients" ], + "operationId" : "activateToken", + "summary" : "Activates a pending / unassigned token.", + "description" : "If the token status is `unassigned`, the token will be assigned to the given user, and activated. Otherwise, if the token status is `pending`, just activates the token, checking that the user matches. In both cases the token status is set to `active`.", + "tags" : [ "Tokens" ], "security" : [ { "basic" : [ ] }, { @@ -21432,20 +32720,16 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "The access client id or token", - "schema" : { - "type" : "string" - } - }, { - "$ref" : "#/components/parameters/confirmationPassword" - } ], "responses" : { - "204" : { - "description" : "Nothing is returned, and the access client is unassigned" + "200" : { + "description" : "Returns the id of the assigned token", + "content" : { + "text/plain" : { + "schema" : { + "type" : "string" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -21477,6 +32761,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -21487,57 +32781,45 @@ } } } - } - } - }, - "/mobile/data-for-guest" : { - "get" : { - "operationId" : "dataForMobileGuest", - "summary" : "Returns data the mobile application uses while in guest mode", - "description" : "The data returned can be controlled with a cache key. Each data type has a parameter, such as `headerIf`, which returns the data only if it has changed since the last request.", - "tags" : [ "Mobile" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/cyclosVersion" - }, { - "$ref" : "#/components/parameters/headerIf" - }, { - "$ref" : "#/components/parameters/footerIf" - }, { - "$ref" : "#/components/parameters/themeIf" - }, { - "name" : "translationsIf", - "in" : "query", - "required" : false, - "description" : "Controls the translations cache. If is a boolean value (`true` or `false`) will forcibly return or skip the content. Otherwise, it should be a string in the form `id|version`. In this case, the content will be returned only when changed. When blank will always return it.", - "schema" : { - "type" : "string" - } - }, { - "name" : "deviceId", - "in" : "query", - "required" : false, - "description" : "Trusted device identification. If given and the device is active then a pending device confirmation will be created that will be validated\n after the user logs-in. If the validation passes then no confirmation\npassword will be used only for that session.", - "schema" : { - "type" : "string" + }, + "requestBody" : { + "description" : "The token value to activate", + "content" : { + "text/plain" : { + "schema" : { + "type" : "string" + } + } } + } + } + }, + "/tokens/{id}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], + "get" : { + "operationId" : "viewToken", + "summary" : "Returns details of a specific token", + "description" : "Returns information about a token, located by either id or number", + "tags" : [ "Tokens" ], + "security" : [ { + "basic" : [ ] }, { - "name" : "pinId", - "in" : "query", - "required" : false, - "description" : "Device PIN identification. If given then the information about whether it is active or not will be given in the returned `dataForLogin`.", - "schema" : { - "type" : "string" - } + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" } ], "responses" : { "200" : { - "description" : "The data for the mobile guest page", + "description" : "The token data", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/DataForMobileGuest" + "$ref" : "#/components/schemas/TokenView" } } } @@ -21585,12 +32867,15 @@ } } }, - "/mobile/data-for-user" : { - "get" : { - "operationId" : "dataForMobileUser", - "summary" : "Returns data the mobile application uses in either user or POS mode", - "description" : "The data returned can be controlled with a cache key. Each data type has a parameter, such as `helpIf`, which returns the data only if it has changed since the last request.", - "tags" : [ "Mobile" ], + "/tokens/{id}/activate" : { + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], + "post" : { + "operationId" : "activatePendingToken", + "summary" : "Activates a token.", + "description" : "Activates a token, which must be assigned to a user managed by the authenticated user. The token status must be `pending`.", + "tags" : [ "Tokens" ], "security" : [ { "basic" : [ ] }, { @@ -21598,47 +32883,9 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/cyclosVersion" - }, { - "$ref" : "#/components/parameters/themeIf" - }, { - "name" : "translationsIf", - "in" : "query", - "required" : false, - "description" : "Controls the translations cache. If is a boolean value (`true` or `false`) will forcibly return or skip the content. Otherwise, it should be a string in the form `id|version`. In this case, the content will be returned only when changed. When blank will always return it.", - "schema" : { - "type" : "string" - } - }, { - "name" : "mobileHelpIf", - "in" : "query", - "required" : false, - "description" : "Controls the mobile help cache. If is a boolean value (`true` or `false`) will forcibly return or skip the content. Otherwise, it should be a string in the form `id|version`. In this case, the content will be returned only when changed. When blank will always return it. Only taken into account when not accessing as access client (not in POS mode).", - "schema" : { - "type" : "string" - } - }, { - "name" : "posHelpIf", - "in" : "query", - "required" : false, - "description" : "Controls the POS help cache. If is a boolean value (`true` or `false`) will forcibly return or skip the content. Otherwise, it should be a string in the form `id|version`. In this case, the content will be returned only when changed. When blank will always return it. Only taken into account when accessing as access client (POS mode).", - "schema" : { - "type" : "string" - } - } ], "responses" : { - "200" : { - "description" : "The data for the mobile user page", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/DataForMobileUser" - } - } - } + "204" : { + "description" : "The token is activated and nothing is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -21683,31 +32930,25 @@ } } }, - "/mobile/page/{id}" : { - "get" : { - "operationId" : "mobilePageContent", - "summary" : "Returns the content of a mobile page", - "description" : "Returns the content of a mobile page, either by id or internal name", - "tags" : [ "Mobile" ], - "parameters" : [ { - "name" : "id", - "in" : "path", - "required" : true, - "description" : "The mobile page id", - "schema" : { - "type" : "string" - } + "/tokens/{id}/block" : { + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], + "post" : { + "operationId" : "blockToken", + "summary" : "Blocks a token.", + "description" : "Blocks a token, which remains blocked until being unblocked again. The token status must be `active`.", + "tags" : [ "Tokens" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] } ], "responses" : { - "200" : { - "description" : "The page content", - "content" : { - "text/html" : { - "schema" : { - "type" : "string" - } - } - } + "204" : { + "description" : "The token is blocked and nothing is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -21752,12 +32993,15 @@ } } }, - "/notifications" : { - "get" : { - "operationId" : "searchNotifications", - "summary" : "Searches for the notifications the authenticated user has received.", - "description" : "Returns an ordered page of notifications the authenticated user has received (newest first).", - "tags" : [ "Notifications" ], + "/tokens/{id}/unblock" : { + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], + "post" : { + "operationId" : "unblockToken", + "summary" : "Unlocks a token.", + "description" : "Unlocks a token, returning its status to `active`. The token status must be `blocked`.", + "tags" : [ "Tokens" ], "security" : [ { "basic" : [ ] }, { @@ -21765,56 +33009,9 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "name" : "onlyNew", - "in" : "query", - "required" : false, - "description" : "Boolean value indicating wether return only the new notifications received after the last view date tracked using `POST /notifications/viewed`", - "schema" : { - "type" : "boolean" - } - }, { - "name" : "onlyUnread", - "in" : "query", - "required" : false, - "description" : "Boolean value indicating wether return only the unread notifications", - "schema" : { - "type" : "boolean" - } - }, { - "name" : "page", - "in" : "query", - "required" : false, - "description" : "The page number (zero-based) of the search. The default value is zero.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - }, { - "name" : "pageSize", - "in" : "query", - "required" : false, - "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - } ], "responses" : { - "200" : { - "description" : "The notifications page", - "content" : { - "application/json" : { - "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/Notification" - } - } - } - } + "204" : { + "description" : "The token is unblocked and nothing is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -21859,27 +33056,25 @@ } } }, - "/notifications/{id}" : { - "get" : { - "operationId" : "viewNotification", - "summary" : "Returns the notification details.", - "description" : "Returns the notification details.", - "tags" : [ "Notifications" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "/tokens/{id}/cancel" : { + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], + "post" : { + "operationId" : "cancelToken", + "summary" : "Permanently cancels a token.", + "description" : "Permanently cancels a token. The token status must be any but `canceled`.", + "tags" : [ "Tokens" ], + "security" : [ { + "basic" : [ ] }, { - "$ref" : "#/components/parameters/id" + "session" : [ ] + }, { + "accessClient" : [ ] } ], "responses" : { - "200" : { - "description" : "The notification details", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Notification" - } - } - } + "204" : { + "description" : "The token is canceled and nothing is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -21922,12 +33117,19 @@ } } } - }, - "delete" : { - "operationId" : "deleteNotification", - "summary" : "Removes a notification by id.", - "description" : "Removes a notification for the authenticated user by id.", - "tags" : [ "Notifications" ], + } + }, + "/tokens/{id}/assign/{user}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/id" + }, { + "$ref" : "#/components/parameters/user" + } ], + "post" : { + "operationId" : "assignToken", + "summary" : "Assigns a token to a given user.", + "description" : "Assigns a token to a given user. The token status must be `unassigned`. After assigning, the token status will be `pending`.", + "tags" : [ "Tokens" ], "security" : [ { "basic" : [ ] }, { @@ -21935,22 +33137,9 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "$ref" : "#/components/parameters/id" - } ], "responses" : { "204" : { - "description" : "The notification was removed" - }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ConflictError" - } - } - } + "description" : "The token is assigned to the user and nothing is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -21995,57 +33184,35 @@ } } }, - "/notifications/mark-as-read" : { + "/tokens/{id}/set-expiry-date" : { + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], "post" : { - "operationId" : "markNotificationsAsRead", - "summary" : "Marks a list of notifications as read.", - "description" : "Marks a list of notifications, given by id, as read.", - "tags" : [ "Notifications" ], + "operationId" : "setTokenExpiryDate", + "summary" : "Sets the expiry date of a specific token.", + "description" : "Updates the token expiry date. The token status must be either `active`, `blocked` or `expired`.", + "tags" : [ "Tokens" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], "parameters" : [ { - "name" : "ids", - "description" : "The notifications (comma-separated list of identifiers) to mark as read.", + "name" : "date", "in" : "query", - "required" : true, + "required" : false, + "description" : "The new expiry date. If not specified, the token will never expire.", "schema" : { - "type" : "array", - "items" : { - "type" : "string" - } + "type" : "string", + "format" : "date-time" } } ], "responses" : { "204" : { - "description" : "The notifications were marked as read." - }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ConflictError" - } - } - } - } - } - } - }, - "/notifications/status" : { - "get" : { - "operationId" : "notificationsStatus", - "summary" : "Return information about the received notifications.", - "description" : "Return information about the status of the received notifications (unread, new, etc).", - "tags" : [ "Notifications" ], - "responses" : { - "200" : { - "description" : "The notifications status information", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/NotificationsStatus" - } - } - } + "description" : "The token expiry date is changed and nothing is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -22090,38 +33257,15 @@ } } }, - "/notifications/viewed" : { - "post" : { - "operationId" : "markAsViewed", - "summary" : "Update the last view date for the notifications.", - "description" : "Update the last view date for the notifications. This will be used to calculate the number of new notifications returned by the `POST /notifications/status` operation.", - "tags" : [ "Notifications" ], - "responses" : { - "204" : { - "description" : "The last view date was updated." - }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ConflictError" - } - } - } - } - } - } - }, - "/{user}/notification-settings" : { + "/tokens/{id}/set-activation-deadline" : { "parameters" : [ { - "$ref" : "#/components/parameters/user" + "$ref" : "#/components/parameters/id" } ], - "get" : { - "operationId" : "viewNotificationSettings", - "summary" : "Returns the notification settings for a given user.", - "description" : "Returns the notification settings for a given operator / user / administrator.", - "tags" : [ "NotificationSettings" ], + "post" : { + "operationId" : "setTokenActivationDeadline", + "summary" : "Sets the activation deadline date of a specific token.", + "description" : "Updates the token activation deadline date. The token status must be `pending` or `activationExpired`.", + "tags" : [ "Tokens" ], "security" : [ { "basic" : [ ] }, { @@ -22130,18 +33274,18 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "name" : "date", + "in" : "query", + "required" : false, + "description" : "The new activation deadline date. If not specified, there will be no deadline.", + "schema" : { + "type" : "string", + "format" : "date-time" + } } ], "responses" : { - "200" : { - "description" : "The notification settings", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/NotificationSettingsView" - } - } - } + "204" : { + "description" : "The token activation deadline date is changed and nothing is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -22184,12 +33328,23 @@ } } } - }, - "post" : { - "operationId" : "saveNotificationSettings", - "summary" : "Saves the notification settings for a given user.", - "description" : "Saves the notification settings for a given operator / user / administrator.", - "tags" : [ "NotificationSettings" ], + } + }, + "/tokens/{type}/data-for-new" : { + "parameters" : [ { + "name" : "type", + "description" : "Either the identifier or internal name of the token type", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + } ], + "get" : { + "operationId" : "getTokenDataForNew", + "summary" : "Returns data to create a new token for the given type.", + "description" : "Returns data to create a new token for the given type.", + "tags" : [ "Tokens" ], "security" : [ { "basic" : [ ] }, { @@ -22197,20 +33352,27 @@ }, { "accessClient" : [ ] } ], - "requestBody" : { - "description" : "The parameters to save", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/NotificationSettingsEdit" + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "user", + "in" : "query", + "required" : false, + "schema" : { + "type" : "string" + }, + "description" : "Either id or identification of the user to have the token initially assigned" + } ], + "responses" : { + "200" : { + "description" : "The data for creating a new token", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TokenDataForNew" + } } } - } - }, - "responses" : { - "204" : { - "description" : "The notification settings are saved and nothing is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -22242,12 +33404,12 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "500" : { + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/InputError" + "$ref" : "#/components/schemas/Error" } } } @@ -22255,15 +33417,21 @@ } } }, - "/{user}/notification-settings/data-for-edit" : { + "/tokens/{type}/new" : { "parameters" : [ { - "$ref" : "#/components/parameters/user" + "name" : "type", + "description" : "Either the identifier or internal name of the token type", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } } ], - "get" : { - "operationId" : "getNotificationSettingsDataForEdit", - "summary" : "Returns configuration data to edit the notification settings of a user.", - "description" : "Returns data to edit the nofitication settings od a given operator / user / administrator.", - "tags" : [ "NotificationSettings" ], + "post" : { + "operationId" : "createToken", + "summary" : "Creates a new token of the given type.", + "description" : "Creates a new token of the given type. If a user is specified, the token will be initially assigned to that user, and the initial status will be `pending`.", + "tags" : [ "Tokens" ], "security" : [ { "basic" : [ ] }, { @@ -22271,16 +33439,21 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - } ], "responses" : { - "200" : { - "description" : "The notification settings", + "201" : { + "description" : "Returns the identifier of the new record", + "headers" : { + "Location" : { + "description" : "URL for viewing the record details", + "schema" : { + "type" : "string" + } + } + }, "content" : { - "application/json" : { + "text/plain" : { "schema" : { - "$ref" : "#/components/schemas/NotificationSettingsDataForEdit" + "type" : "string" } } } @@ -22315,6 +33488,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -22325,15 +33508,35 @@ } } } + }, + "requestBody" : { + "description" : "Details of the token to be created", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/TokenNew" + } + } + } } } }, - "/{user}/vouchers/data-for-search" : { + "/general-tokens/{type}/data-for-search" : { + "parameters" : [ { + "name" : "type", + "description" : "Either the identifier or internal name of the token type", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + } ], "get" : { - "operationId" : "getUserVouchersDataForSearch", - "summary" : "Returns data for searching vouchers a user has bought or redeemed", - "description" : "Returns configuration data used to search vouchers the user has either bought (default) or redeemed (if `relation` is `redeemed`)", - "tags" : [ "Vouchers" ], + "operationId" : "getGeneralTokensDataForSearch", + "summary" : "Returns data for searching tokens of a specific type.", + "description" : "Returns data for searching tokens of a specific type, regardless of the user.", + "tags" : [ "Tokens" ], "security" : [ { "basic" : [ ] }, { @@ -22343,23 +33546,14 @@ } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/user" - }, { - "name" : "relation", - "in" : "query", - "description" : "Indicates the relation used to filter the vouchers.", - "schema" : { - "$ref" : "#/components/schemas/VoucherRelationEnum" - } } ], "responses" : { "200" : { - "description" : "The configuration data for searching a user's vouchers", + "description" : "The configuration data for searching tokens", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/UserVouchersDataForSearch" + "$ref" : "#/components/schemas/TokenDataForSearch" } } } @@ -22407,12 +33601,21 @@ } } }, - "/{user}/vouchers" : { + "/general-tokens/{type}" : { + "parameters" : [ { + "name" : "type", + "description" : "Either the identifier or internal name of the token type", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + } ], "get" : { - "operationId" : "searchUserVouchers", - "summary" : "Searches for vouchers a user has bought or redeemed", - "description" : "Returns the list of matching vouchers the given user has either bought (default) or redeemed (if `type` is `redeemed`)", - "tags" : [ "Vouchers" ], + "operationId" : "searchGeneralTokens", + "summary" : "Searches for tokens of a specific type, regardless of the user.", + "description" : "Returns tokens matching the search criteria, for a specific type.", + "tags" : [ "Tokens" ], "security" : [ { "basic" : [ ] }, { @@ -22423,41 +33626,35 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/user" - }, { - "name" : "amountRange", + "name" : "activationPeriod", "in" : "query", "required" : false, - "description" : "The minimum / maximum voucher amount", - "style" : "simple", + "description" : "The minimum / maximum token activation date.", "schema" : { "type" : "array", "items" : { "description" : "", "type" : "string", - "format" : "number" + "format" : "date-time" } } }, { - "name" : "creationPeriod", + "name" : "brokers", "in" : "query", "required" : false, - "description" : "The minimum / maximum voucher creation date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", + "description" : "Either id or a principal (login name, e-mail, etc) for brokers", "schema" : { "type" : "array", "items" : { "description" : "", - "type" : "string", - "format" : "date-time" + "type" : "string" } } }, { - "name" : "expirationPeriod", + "name" : "expiryPeriod", "in" : "query", "required" : false, - "description" : "The minimum / maximum voucher expiration date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", + "description" : "The minimum / maximum token expiry date.", "schema" : { "type" : "array", "items" : { @@ -22466,6 +33663,18 @@ "format" : "date-time" } } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Either id or internal names of groups / group sets", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } }, { "name" : "page", "in" : "query", @@ -22485,63 +33694,44 @@ "format" : "int32" } }, { - "name" : "redeemPeriod", - "in" : "query", - "required" : false, - "description" : "The minimum / maximum voucher redeem date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string", - "format" : "date-time" - } - } - }, { - "name" : "relation", + "name" : "skipTotalCount", "in" : "query", "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", "schema" : { - "$ref" : "#/components/schemas/VoucherRelationEnum" + "type" : "boolean" } }, { "name" : "statuses", "in" : "query", "required" : false, - "description" : "", - "style" : "simple", + "description" : "The desired token statuses", "schema" : { "type" : "array", "items" : { - "$ref" : "#/components/schemas/VoucherStatusEnum" + "$ref" : "#/components/schemas/TokenStatusEnum" } } }, { - "name" : "token", + "name" : "user", "in" : "query", "required" : false, - "description" : "The voucher token (with or without mask)", + "description" : "Either id or a principal (login name, e-mail, etc) for the token owner user", "schema" : { "type" : "string" } }, { - "name" : "types", + "name" : "value", "in" : "query", "required" : false, - "description" : "The ids or internal names of voucher types", - "style" : "simple", + "description" : "The token value", "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } + "type" : "string" } } ], "responses" : { "200" : { - "description" : "The list of matching vouchers. The `buyer` and `redeemer` fields will not be returned when searching for bought and redeemed vouchers (respectively), because they are always the user passed as parameter.", + "description" : "The tokens matching the search filters", "headers" : { "X-Total-Count" : { "schema" : { @@ -22573,7 +33763,7 @@ "schema" : { "type" : "array", "items" : { - "$ref" : "#/components/schemas/VoucherResult" + "$ref" : "#/components/schemas/TokenResult" } } } @@ -22622,12 +33812,12 @@ } } }, - "/vouchers/{key}" : { + "/{owner}/operations" : { "get" : { - "operationId" : "viewVoucher", - "summary" : "Returns data for a particular voucher", - "description" : "Returns details about a particular voucher, as well as the transactions used to buy and redeem, and the permissions for authenticated over it.", - "tags" : [ "Vouchers" ], + "operationId" : "listOperationsByOwner", + "summary" : "Lists the custom operations over the system or user", + "description" : "Returns the custom operations the authenticated user can run over the given user or system if the `system` owner is used.", + "tags" : [ "Operations" ], "security" : [ { "basic" : [ ] }, { @@ -22638,8 +33828,85 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "name" : "key", - "description" : "The voucher `id` or `token`. When the token is fully numeric, it must be preceded by a single quote (`'`).", + "$ref" : "#/components/parameters/owner" + } ], + "responses" : { + "200" : { + "description" : "The list of custom operations", + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Operation" + } + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/{owner}/operations/{operation}/data-for-run" : { + "get" : { + "operationId" : "getOwnerOperationDataForRun", + "summary" : "Returns configuration data for running a custom operation over an owner", + "description" : "Returns data to run a specific custom operation over a given user or system if the `system` owner is used. The operation scope must match, being either `system` or `user`.", + "tags" : [ "Operations" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/owner" + }, { + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", "in" : "path", "required" : true, "schema" : { @@ -22648,11 +33915,11 @@ } ], "responses" : { "200" : { - "description" : "The voucher details", + "description" : "The data used to run the operation", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/VoucherView" + "$ref" : "#/components/schemas/OperationDataForRun" } } } @@ -22700,31 +33967,67 @@ } } }, - "/vouchers/{key}/qr-code" : { - "get" : { - "operationId" : "getVoucherQrCode", - "summary" : "Returns the QR-code image for the given voucher", - "description" : "The api documentation page, using swagger-ui (or any direct usage of an image tag), generates a second request to show the image contents on the preview. This is a new GET request, without passing-in the authentication parameters. As this path requires authentication, the image is shown broken, but the first request works as expected, returning the image content. Optionally, to solve the problem described above and allow to authenticate the user when using sessions, a `sessionToken` or `accessClientToken` plus a `channel` query parameters could be specified.", - "tags" : [ "Vouchers" ], + "/{owner}/operations/{operation}/run" : { + "post" : { + "operationId" : "runOwnerOperation", + "summary" : "Runs a custom operation either for system or user", + "description" : "Runs a specific custom operation over a given user or system if the `system` owner is used. The operation scope must match, being either `system` or `user`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], "parameters" : [ { - "name" : "key", - "description" : "The voucher `id` or `token`. When the token is fully numeric, it must be preceded by a single quote (`'`).", + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/owner" + }, { + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", "in" : "path", "required" : true, "schema" : { "type" : "string" } - }, { - "name" : "size", - "in" : "query", - "required" : false, - "schema" : { - "$ref" : "#/components/schemas/ImageSizeEnum" - } } ], "responses" : { "200" : { - "description" : "The image content" + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/RunOperationResult" + } + }, + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -22766,37 +34069,77 @@ } } } + }, + "requestBody" : { + "description" : "The custom operation parameters", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/RunOperation" + } + } + } } } }, - "/{user}/vouchers/types-for-buy" : { - "get" : { - "operationId" : "listVoucherTypesForBuy", - "summary" : "Returns the voucher types the authenticated user can buy vouchers to the given user", - "description" : "List the voucher types the user can buy to another user (or himself)", - "tags" : [ "Vouchers" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + "/{owner}/operations/{operation}/run-upload" : { + "post" : { + "operationId" : "runOwnerOperationWithUpload", + "summary" : "Runs a custom operation either for system or user while uploading a file", + "description" : "Runs a specific custom operation over a given user or system if the `system` owner is used. The operation scope must match, being either `system` or `user`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/user" + "$ref" : "#/components/parameters/owner" + }, { + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } } ], "responses" : { "200" : { - "description" : "The list with the voucher types", + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/VoucherTypeDetailed" - } + "$ref" : "#/components/schemas/RunOperationResult" + } + }, + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" } } } @@ -22841,15 +34184,37 @@ } } } + }, + "requestBody" : { + "content" : { + "multipart/form-data" : { + "schema" : { + "type" : "object", + "properties" : { + "params" : { + "description" : "The custom operation parameters.", + "allOf" : [ { + "$ref" : "#/components/schemas/RunOperation" + } ] + }, + "file" : { + "type" : "string", + "format" : "binary", + "description" : "The file being uploaded" + } + } + } + } + } } } }, - "/{user}/vouchers/data-for-buy" : { + "/operations/{operation}/data-for-run" : { "get" : { - "operationId" : "getVoucherDataForBuy", - "summary" : "Returns data for buying a voucher of a specified type", - "description" : "Data for buying a voucher", - "tags" : [ "Vouchers" ], + "operationId" : "getOperationDataForRun", + "summary" : "Returns configuration data for running a custom operation without additional scope", + "description" : "Returns data to run a specific custom operation, which must not have any additional scope to run, such as user, contact, record or advertisement. Hence, this path is suitable for custom operations with scope `system` or `internal`.", + "tags" : [ "Operations" ], "security" : [ { "basic" : [ ] }, { @@ -22860,11 +34225,9 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/user" - }, { - "name" : "type", - "description" : "Either the `id` or `internalName` of the voucher type", - "in" : "query", + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", + "in" : "path", "required" : true, "schema" : { "type" : "string" @@ -22872,11 +34235,11 @@ } ], "responses" : { "200" : { - "description" : "The data for buying vouchers", + "description" : "The data used to run the operation", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/VoucherDataForBuy" + "$ref" : "#/components/schemas/OperationDataForRun" } } } @@ -22924,34 +34287,62 @@ } } }, - "/{user}/vouchers/buy" : { + "/operations/{operation}/run" : { "post" : { - "operationId" : "buyVouchers", - "summary" : "Buys one or more vouchers for the given user", - "description" : "Buys vouchers. If the payment type has custom fields, the values should be passed as well. This service only returns the vouchers list, if you need information about the voucher status please use /{user}/vouchers/buy-with-status.", - "tags" : [ "Vouchers" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + "operationId" : "runOperation", + "summary" : "Runs a custom operation without additional scope", + "description" : "Runs a specific custom operation without additional scope. Is suitable for operations with scope `system` or `internal`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], "parameters" : [ { - "$ref" : "#/components/parameters/user" + "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/confirmationPassword" + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } } ], "responses" : { "200" : { - "description" : "The identifiers of all generated vouchers", + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "type" : "string" - } + "$ref" : "#/components/schemas/RunOperationResult" + } + }, + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" } } } @@ -22987,54 +34378,183 @@ } }, "500" : { - "description" : "An error occurred while buying the voucher(s)", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/BuyVoucherError" + "$ref" : "#/components/schemas/Error" } } } } }, "requestBody" : { - "description" : "The buy voucher parameters", - "required" : true, + "description" : "The custom operation parameters", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/BuyVoucher" + "$ref" : "#/components/schemas/RunOperation" } } } } } }, - "/{user}/vouchers/buy-with-status" : { + "/operations/{operation}/run-upload" : { "post" : { - "operationId" : "buyVouchersWithStatus", - "summary" : "Buys one or more vouchers for the given user returning the status.", - "description" : "Buys vouchers. If the payment type has custom fields, the values should be passed as well. The status returned in the result is shared by all vouchers.", - "tags" : [ "Vouchers" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] + "operationId" : "runOperationWithUpload", + "summary" : "Runs a custom operation without additional scope while uploading a file", + "description" : "Runs a specific custom operation without additional scope. Is suitable for operations with scope `system` or `internal`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" }, { - "accessClient" : [ ] + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } } ], + "responses" : { + "200" : { + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/RunOperationResult" + } + }, + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + }, + "requestBody" : { + "content" : { + "multipart/form-data" : { + "schema" : { + "type" : "object", + "properties" : { + "params" : { + "description" : "The custom operation parameters.", + "allOf" : [ { + "$ref" : "#/components/schemas/RunOperation" + } ] + }, + "file" : { + "type" : "string", + "format" : "binary", + "description" : "The file being uploaded" + } + } + } + } + } + } + } + }, + "/operations/callback/{id}" : { + "post" : { + "operationId" : "runCustomOperationCallback", + "summary" : "Runs the callback of an external redirect custom operation", + "description" : "Custom operations may be configured in Cyclos to be of result type `externalRedirect`. In such case, the regular execution returns an URL to which redirect clients. Once the external page processing is complete, the user is redirected back, so the operation can be completed. This operation should be executed to complete the payment. In order for the external service receive the correct URL, Cyclos need to have a link generation script that handles the link type `EXTERNAL_REDIRECT`.", + "tags" : [ "Operations" ], "parameters" : [ { - "$ref" : "#/components/parameters/user" + "name" : "id", + "description" : "The external redirect identifier. Received as part of the URL which is generated by Cyclos to the external service to use as callback.", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } }, { - "$ref" : "#/components/parameters/confirmationPassword" + "name" : "token", + "description" : "The security token which is received as part of the URL which is generated by Cyclos to the external service to use as callback.", + "in" : "query", + "required" : false, + "schema" : { + "type" : "string" + } } ], "responses" : { "200" : { - "description" : "The status of all bougth vouchers and their identifiers.", + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/VoucherBoughtResult" + "$ref" : "#/components/schemas/RunOperationResult" } } } @@ -23070,35 +34590,34 @@ } }, "500" : { - "description" : "An error occurred while buying the voucher(s)", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/BuyVoucherError" + "$ref" : "#/components/schemas/Error" } } } } }, "requestBody" : { - "description" : "The buy voucher parameters", - "required" : true, + "description" : "Data of the original callback request sent by the external service", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/BuyVoucher" + "$ref" : "#/components/schemas/HttpRequestData" } } } } } }, - "/{user}/vouchers/data-for-redeem" : { + "/marketplace/{ad}/operations" : { "get" : { - "operationId" : "getVoucherInitialDataForRedeem", - "summary" : "Returns initial data for redeeming vouchers", - "description" : "Returns initial data for redeeming vouchers", - "tags" : [ "Vouchers" ], + "operationId" : "listOperationsByAd", + "summary" : "Lists the custom operations over the given advertisement", + "description" : "Returns the custom operations the authenticated user can run over the given advertisement. All returned operations have the scope `advertisement`.", + "tags" : [ "Operations" ], "security" : [ { "basic" : [ ] }, { @@ -23109,15 +34628,18 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/user" + "$ref" : "#/components/parameters/ad" } ], "responses" : { "200" : { - "description" : "The data for redeeming vouchers", + "description" : "The list of custom operations", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/VoucherInitialDataForRedeem" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Operation" + } } } } @@ -23165,12 +34687,12 @@ } } }, - "/{user}/vouchers/{token}/data-for-redeem" : { + "/marketplace/{ad}/operations/{operation}/data-for-run" : { "get" : { - "operationId" : "getVoucherDataForRedeem", - "summary" : "Returns data for redeeming a voucher by token", - "description" : "Data for redeeming a specific voucher", - "tags" : [ "Vouchers" ], + "operationId" : "getAdOperationDataForRun", + "summary" : "Returns configuration data for running a custom operation over an advertisement", + "description" : "Returns data to run a specific custom operation over an advertisement. The operation scope must be `advertisement`.", + "tags" : [ "Operations" ], "security" : [ { "basic" : [ ] }, { @@ -23181,10 +34703,10 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/user" + "$ref" : "#/components/parameters/ad" }, { - "name" : "token", - "description" : "The voucher token to be redeemed", + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", "in" : "path", "required" : true, "schema" : { @@ -23193,11 +34715,11 @@ } ], "responses" : { "200" : { - "description" : "The data for redeeming vouchers", + "description" : "The data used to run the operation", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/VoucherDataForRedeem" + "$ref" : "#/components/schemas/OperationDataForRun" } } } @@ -23233,11 +34755,11 @@ } }, "500" : { - "description" : "An error occurred while retrieving data for redeeming the voucher", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RedeemVoucherError" + "$ref" : "#/components/schemas/Error" } } } @@ -23245,24 +34767,19 @@ } } }, - "/{user}/vouchers/{token}/redeem" : { + "/marketplace/{ad}/operations/{operation}/run" : { "post" : { - "operationId" : "redeemVoucher", - "summary" : "Redeems a voucher for the given user", - "description" : "Redeems a voucher", - "tags" : [ "Vouchers" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + "operationId" : "runAdOperation", + "summary" : "Runs a custom operation over an advertisement", + "description" : "Runs a specific custom operation over a given advertisement. The operation scope must be `advertisement`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], "parameters" : [ { - "$ref" : "#/components/parameters/user" + "$ref" : "#/components/parameters/fields" }, { - "name" : "token", - "description" : "The voucher token to be redeemed", + "$ref" : "#/components/parameters/ad" + }, { + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", "in" : "path", "required" : true, "schema" : { @@ -23270,20 +34787,44 @@ } } ], "responses" : { - "201" : { - "description" : "The identifiers of the voucher and the generated payment for redeem", + "200" : { + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", "headers" : { - "Location" : { - "description" : "URL for viewing the redeemed voucher", + "X-Total-Count" : { "schema" : { - "type" : "string" - } + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." } }, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/VoucherRedeemResult" + "$ref" : "#/components/schemas/RunOperationResult" + } + }, + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" } } } @@ -23319,130 +34860,86 @@ } }, "500" : { - "description" : "An error occurred while redeeming the voucher", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RedeemVoucherError" + "$ref" : "#/components/schemas/Error" } } } } }, "requestBody" : { - "description" : "Additional redeem data", + "description" : "The custom operation parameters", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RedeemVoucher" + "$ref" : "#/components/schemas/RunOperation" } } } } } }, - "/tickets/data-for-new" : { - "get" : { - "operationId" : "dataForNewTicket", - "summary" : "Returns data for create a new ticket for the logged user.", - "tags" : [ "Tickets" ], + "/marketplace/{ad}/operations/{operation}/run-upload" : { + "post" : { + "operationId" : "runAdOperationWithUpload", + "summary" : "Runs a custom operation over an advertisement while uploading a file", + "description" : "Runs a specific custom operation over a given advertisement. The operation scope must be `advertisement`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "name" : "type", - "in" : "query", - "required" : false, - "description" : "The payment type id or qualified internal name (in the form `fromAccountType.paymentType`). If no payment type is provided, the possible types will be returned, so the payer can choose.", - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/ad" }, { - "name" : "payer", - "in" : "query", - "required" : false, - "description" : "Will only be used if no specific payment type is given. An identification for the user which will pay the ticket. Is optional, and in most cases, should be left empty. If specified, the returned payment types will take into account those that can be paid by the given user.", + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", + "in" : "path", + "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { - "description" : "The data for creating a ticket", - "content" : { - "application/json" : { + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "headers" : { + "X-Total-Count" : { "schema" : { - "$ref" : "#/components/schemas/DataForTransaction" - } - } - } - }, - "401" : { - "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", - "content" : { - "application/json" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { "schema" : { - "$ref" : "#/components/schemas/UnauthorizedError" - } - } - } - }, - "403" : { - "description" : "Permission denied for such operation", - "content" : { - "application/json" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { "schema" : { - "$ref" : "#/components/schemas/ForbiddenError" - } - } - } - }, - "404" : { - "description" : "An expected data was not found", - "content" : { - "application/json" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { "schema" : { - "$ref" : "#/components/schemas/NotFoundError" - } + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." } - } - }, - "500" : { - "description" : "Unexpected error", + }, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Error" + "$ref" : "#/components/schemas/RunOperationResult" } - } - } - } - } - } - }, - "/tickets/{ticket}" : { - "get" : { - "operationId" : "viewTicket", - "summary" : "Returns details about a ticket by ticket number", - "description" : "Returns details about a ticket by ticket number.", - "tags" : [ "Tickets" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "name" : "ticket", - "in" : "path", - "required" : true, - "description" : "The ticket number", - "schema" : { - "type" : "string" - } - } ], - "responses" : { - "200" : { - "description" : "Transaction details", - "content" : { - "application/json" : { + }, + "*/*" : { "schema" : { - "$ref" : "#/components/schemas/TransactionView" + "type" : "string", + "format" : "binary" } } } @@ -23487,15 +34984,37 @@ } } } + }, + "requestBody" : { + "content" : { + "multipart/form-data" : { + "schema" : { + "type" : "object", + "properties" : { + "params" : { + "description" : "The custom operation parameters.", + "allOf" : [ { + "$ref" : "#/components/schemas/RunOperation" + } ] + }, + "file" : { + "type" : "string", + "format" : "binary", + "description" : "The file being uploaded" + } + } + } + } + } } } }, - "/tickets" : { - "post" : { - "operationId" : "newTicket", - "summary" : "Creates a new ticket with status `open` for the logged user.", - "description" : "The logged user will be the ticket's owner and then the receiver of the payment generated after processing the ticket only if was previously approved by the payer.", - "tags" : [ "Tickets" ], + "/records/{id}/operations" : { + "get" : { + "operationId" : "listOperationsByRecord", + "summary" : "Lists the custom operations over the given record", + "description" : "Returns the custom operations the authenticated user can run over the given record. All returned operations have the scope `record`.", + "tags" : [ "Operations" ], "security" : [ { "basic" : [ ] }, { @@ -23505,22 +35024,19 @@ } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/id" } ], "responses" : { - "201" : { - "description" : "The created ticket", - "headers" : { - "Location" : { - "description" : "URL for viewing the ticket details", - "schema" : { - "type" : "string" - } - } - }, + "200" : { + "description" : "The list of custom operations", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Transaction" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Operation" + } } } } @@ -23555,16 +35071,6 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { "description" : "Unexpected error", "content" : { @@ -23575,50 +35081,42 @@ } } } - }, - "requestBody" : { - "description" : "The data to create the new ticket", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/TicketNew" - } - } - } } } }, - "/tickets/{ticket}/qr-code" : { + "/records/{id}/operations/{operation}/data-for-run" : { "get" : { - "operationId" : "getTicketQrCode", - "summary" : "Returns the QR-code image for the given ticket only if its status is `open`", - "description" : "This request will return the image contents as expected but our api documentation page (or any other usage of an <img> tag), created using swagger-ui, generates a second request to include the image in the page. This new (GET) request won't send the authentication parameters and as this path requires authentication the image will be shown as broken. Optionally, to solve the problem described above and to allow authenticate the user when using sessions, a `sessionToken` or `accessClientToken` query parameter could be specified.", - "tags" : [ "Tickets" ], + "operationId" : "getRecordOperationDataForRun", + "summary" : "Returns configuration data for running a custom operation over a record", + "description" : "Returns data to run a specific custom operation over a record. The operation scope must be `record`.", + "tags" : [ "Operations" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], "parameters" : [ { - "name" : "ticket", - "description" : "The ticket number.", + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/id" + }, { + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", "in" : "path", "required" : true, "schema" : { "type" : "string" } - }, { - "name" : "size", - "in" : "query", - "required" : false, - "schema" : { - "$ref" : "#/components/schemas/ImageSizeEnum" - } } ], "responses" : { "200" : { - "description" : "The image content", + "description" : "The data used to run the operation", "content" : { - "image/png" : { + "application/json" : { "schema" : { - "type" : "string", - "format" : "binary" + "$ref" : "#/components/schemas/OperationDataForRun" } } } @@ -23666,24 +35164,19 @@ } } }, - "/tickets/{ticket}/preview" : { + "/records/{id}/operations/{operation}/run" : { "post" : { - "operationId" : "previewTicket", - "summary" : "Previews the payment generated by the ticket.", - "description" : "Previews the payment that will be generated if the ticket is approved by a user (i.e the payer). The ticket status must be `open` and `successUrl` null or `approved`. The actual balance checking is not performed in the preview.", - "tags" : [ "Tickets" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + "operationId" : "runRecordOperation", + "summary" : "Runs a custom operation over a record", + "description" : "Runs a specific custom operation over a given record. The operation scope must be `record`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "name" : "ticket", - "description" : "The ticket number", + "$ref" : "#/components/parameters/id" + }, { + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", "in" : "path", "required" : true, "schema" : { @@ -23692,11 +35185,43 @@ } ], "responses" : { "200" : { - "description" : "The approval preview", + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/TicketPreview" + "$ref" : "#/components/schemas/RunOperationResult" + } + }, + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" } } } @@ -23731,16 +35256,6 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { "description" : "Unexpected error", "content" : { @@ -23751,25 +35266,32 @@ } } } + }, + "requestBody" : { + "description" : "The custom operation parameters", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/RunOperation" + } + } + } } } }, - "/tickets/{ticket}/cancel" : { + "/records/{id}/operations/{operation}/run-upload" : { "post" : { - "operationId" : "cancelTicket", - "summary" : "Cancels a ticket by the receiver.", - "description" : "Cancels a ticket by the receiver before being approved by the payer. The logged user must be the ticket's owner.", - "tags" : [ "Tickets" ], - "security" : [ { - "basic" : [ ] + "operationId" : "runRecordOperationWithUpload", + "summary" : "Runs a custom operation over a record while uploading a file", + "description" : "Runs a specific custom operation over a given record. The operation scope must be `record`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" }, { - "session" : [ ] + "$ref" : "#/components/parameters/id" }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "name" : "ticket", - "description" : "The ticket number", + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", "in" : "path", "required" : true, "schema" : { @@ -23777,8 +35299,47 @@ } } ], "responses" : { - "204" : { - "description" : "The ticket was canceled. Nothing is returned." + "200" : { + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/RunOperationResult" + } + }, + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -23820,52 +35381,24 @@ } } } - } - } - }, - "/tickets/{ticket}/approve" : { - "post" : { - "operationId" : "approveTicket", - "summary" : "Approves a ticket by the payer.", - "description" : "After a successful approval, a new direct payment from the logged user (i.e the payer) to the user who created the ticket will be generated ONLY if the ticket doesn't have a defined `successUrl` nor `successWebhook`, in that case the ticket goes to `processed` status. Otherwise the ticket just goes to the `approved` status and the corresponding payment will be generated only after the ticket is processed by the receiver.", - "tags" : [ "Tickets" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/confirmationPassword" - }, { - "name" : "ticket", - "description" : "The ticket number", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } - } ], - "responses" : { - "200" : { - "description" : "The approval result.", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/TicketApprovalResult" - } - } - } - }, - "500" : { - "description" : "If a payment error has occurred", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/PaymentError" + }, + "requestBody" : { + "content" : { + "multipart/form-data" : { + "schema" : { + "type" : "object", + "properties" : { + "params" : { + "description" : "The custom operation parameters.", + "allOf" : [ { + "$ref" : "#/components/schemas/RunOperation" + } ] + }, + "file" : { + "type" : "string", + "format" : "binary", + "description" : "The file being uploaded" + } } } } @@ -23873,12 +35406,12 @@ } } }, - "/tickets/{ticket}/process" : { - "post" : { - "operationId" : "processTicket", - "summary" : "Processes a ticket by the receiver.", - "description" : "Processes an already approved ticket generating a new direct payment from the user who approve the ticket to the logged user (i.e the ticket's creator). A ticket can be processed only if its status is `approved` and the `orderId` (if any) matches the one given at ticket creation. After successfully processing it goes to the final status: `processed`.", - "tags" : [ "Tickets" ], + "/transfers/{key}/operations" : { + "get" : { + "operationId" : "listOperationsByTransfer", + "summary" : "Lists the custom operations over the given transfer", + "description" : "Returns the custom operations the authenticated user can run over the given transfer. All returned operations have the scope `transfer`.", + "tags" : [ "Operations" ], "security" : [ { "basic" : [ ] }, { @@ -23889,81 +35422,23 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "name" : "ticket", - "description" : "The ticket number", + "name" : "key", "in" : "path", "required" : true, + "description" : "Either the id or transaction number", "schema" : { "type" : "string" } - }, { - "name" : "orderId", - "description" : "The order id given at ticket creation. Must be specified only if an `orderId` was given when the ticket was created.", - "in" : "query", - "required" : false, - "schema" : { - "type" : "string" - } - } ], - "responses" : { - "200" : { - "description" : "The process result", - "headers" : { - "Location" : { - "description" : "URL for viewing the payment details", - "schema" : { - "type" : "string" - } - } - }, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/TicketProcessResult" - } - } - } - }, - "500" : { - "description" : "If a payment error has occurred", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/PaymentError" - } - } - } - } - } - } - }, - "/{owner}/record-types" : { - "get" : { - "operationId" : "listRecordTypesByOwner", - "summary" : "Lists the record types over a user or system", - "description" : "Returns the record types the authenticated user can view over the given user or system if the `system` owner is used.", - "tags" : [ "Records" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/owner" } ], "responses" : { "200" : { - "description" : "The list of visible record types", + "description" : "The list of custom operations", "content" : { "application/json" : { "schema" : { "type" : "array", "items" : { - "$ref" : "#/components/schemas/OwnerRecordPermissions" + "$ref" : "#/components/schemas/Operation" } } } @@ -24012,12 +35487,12 @@ } } }, - "/{owner}/record-types/{type}" : { + "/transfer/{key}/operations/{operation}/data-for-run" : { "get" : { - "operationId" : "getRecordTypeByOwner", - "summary" : "Returns a single record type over a user or system", - "description" : "Returns the a specific record type the authenticated user can view over the given user or system if the `system` owner is used.", - "tags" : [ "Records" ], + "operationId" : "getTransferOperationDataForRun", + "summary" : "Returns configuration data for running a custom operation over a transfer", + "description" : "Returns data to run a specific custom operation over a transfer. The operation scope must be `transfer`.", + "tags" : [ "Operations" ], "security" : [ { "basic" : [ ] }, { @@ -24028,10 +35503,16 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/owner" + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number", + "schema" : { + "type" : "string" + } }, { - "name" : "type", - "description" : "Either the identifier or internal name of the record type", + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", "in" : "path", "required" : true, "schema" : { @@ -24040,11 +35521,11 @@ } ], "responses" : { "200" : { - "description" : "The record type details", + "description" : "The data used to run the operation", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/OwnerRecordPermissions" + "$ref" : "#/components/schemas/OperationDataForRun" } } } @@ -24092,26 +35573,25 @@ } } }, - "/{owner}/records/{type}/data-for-search" : { - "get" : { - "operationId" : "getRecordDataForOwnerSearch", - "summary" : "Returns data for searching records of a specific type and owner", - "description" : "Returns data for searching records of a specific type, either for system or user records, depending on the `owner` parameter.", - "tags" : [ "Records" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + "/transfers/{key}/operations/{operation}/run" : { + "post" : { + "operationId" : "runTransferOperation", + "summary" : "Runs a custom operation over a transfer", + "description" : "Runs a specific custom operation over a given transfer. The operation scope must be `transfer`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/owner" + "name" : "key", + "in" : "path", + "required" : true, + "description" : "Either the id or transaction number", + "schema" : { + "type" : "string" + } }, { - "name" : "type", - "description" : "Either the identifier or internal name of the record type", + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", "in" : "path", "required" : true, "schema" : { @@ -24120,11 +35600,43 @@ } ], "responses" : { "200" : { - "description" : "The configuration data for searching records", + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RecordDataForSearch" + "$ref" : "#/components/schemas/RunOperationResult" + } + }, + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" } } } @@ -24169,104 +35681,47 @@ } } } + }, + "requestBody" : { + "description" : "The custom operation parameters", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/RunOperation" + } + } + } } } }, - "/{owner}/records/{type}" : { - "get" : { - "operationId" : "searchOwnerRecords", - "summary" : "Searches for records of a specific type and owner", - "description" : "Returns records matching the search criteria, for a specific type, either for system or user records, depending on the `owner` parameter. The custom fields returned on each record depend on the field configuration, which needs to be enabled to return on list. The profile fields available as search filters for records are assigned in the products (or admin group permissions).", - "tags" : [ "Records" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + "/transfers/{key}/operations/{operation}/run-upload" : { + "post" : { + "operationId" : "runTransferOperationWithUpload", + "summary" : "Runs a custom operation over a transfer while uploading a file", + "description" : "Runs a specific custom operation over a given transfer. The operation scope must be `transfer`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/owner" - }, { - "name" : "type", - "description" : "Either the identifier or internal name of the record type", + "name" : "key", "in" : "path", "required" : true, + "description" : "Either the id or transaction number", "schema" : { "type" : "string" } }, { - "name" : "creationPeriod", - "in" : "query", - "required" : false, - "description" : "The minimum / maximum record creation date", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string", - "format" : "date-time" - } - } - }, { - "name" : "customFields", - "in" : "query", - "required" : false, - "description" : "Record custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=tradeType:offer|search,extraDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `tradeType` is either `offer` or `search`, and whose `extraDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=extraDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `customFields=dynamic:'business`.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "keywords", - "in" : "query", - "required" : false, - "description" : "Textual search keywords. Sometimes, like in user search, the fields matched depends on what is configured on the products.", + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", + "in" : "path", + "required" : true, "schema" : { "type" : "string" } - }, { - "name" : "page", - "in" : "query", - "required" : false, - "description" : "The page number (zero-based) of the search. The default value is zero.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - }, { - "name" : "pageSize", - "in" : "query", - "required" : false, - "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - }, { - "name" : "profileFields", - "in" : "query", - "required" : false, - "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } } ], "responses" : { "200" : { - "description" : "The configuration data for searching records", + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", "headers" : { "X-Total-Count" : { "schema" : { @@ -24296,10 +35751,13 @@ "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/RecordResult" - } + "$ref" : "#/components/schemas/RunOperationResult" + } + }, + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" } } } @@ -24344,39 +35802,59 @@ } } } + }, + "requestBody" : { + "content" : { + "multipart/form-data" : { + "schema" : { + "type" : "object", + "properties" : { + "params" : { + "description" : "The custom operation parameters.", + "allOf" : [ { + "$ref" : "#/components/schemas/RunOperation" + } ] + }, + "file" : { + "type" : "string", + "format" : "binary", + "description" : "The file being uploaded" + } + } + } + } + } } - }, - "post" : { - "operationId" : "createRecord", - "summary" : "Creates a new record for the given owner and type", - "description" : "Creates a new record for the given owner and type. If the owner is `system` will be a system record. Otherwise will be a user record.", - "tags" : [ "Records" ], + } + }, + "/contact-list/{id}/operations" : { + "get" : { + "operationId" : "listOperationsByContact", + "summary" : "Lists the custom operations over the given contact", + "description" : "Returns the custom operations the authenticated user can run over the given contact. All returned operations have the scope `contact`.", + "tags" : [ "Operations" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], "parameters" : [ { - "$ref" : "#/components/parameters/owner" + "$ref" : "#/components/parameters/fields" }, { - "name" : "type", - "description" : "Either the identifier or internal name of the record type", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/id" } ], "responses" : { - "201" : { - "description" : "Returns the identifier of the new record", - "headers" : { - "Location" : { - "description" : "URL for viewing the record details", - "schema" : { - "type" : "string" - } - } - }, + "200" : { + "description" : "The list of custom operations", "content" : { - "text/plain" : { + "application/json" : { "schema" : { - "type" : "string" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Operation" + } } } } @@ -24411,16 +35889,6 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { "description" : "Unexpected error", "content" : { @@ -24431,26 +35899,15 @@ } } } - }, - "requestBody" : { - "description" : "The record to be created", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/RecordNew" - } - } - } } } }, - "/{owner}/records/{type}/data-for-new" : { + "/contact-list/{id}/operations/{operation}/data-for-run" : { "get" : { - "operationId" : "getRecordDataForNew", - "summary" : "Returns data to create a new record", - "description" : "Returns configuration data for creating a record for the given owner and type. If the owner is `system` will be a system record. Otherwise will be a user record.", - "tags" : [ "Records" ], + "operationId" : "getContactOperationDataForRun", + "summary" : "Returns configuration data for running a custom operation over a contact", + "description" : "Returns data to run a specific custom operation over a contact. The operation scope must be `contact`.", + "tags" : [ "Operations" ], "security" : [ { "basic" : [ ] }, { @@ -24461,23 +35918,23 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/owner" + "$ref" : "#/components/parameters/id" }, { - "name" : "type", - "required" : true, + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", "in" : "path", - "description" : "The record type to be created", + "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { - "description" : "The data for creating a record", + "description" : "The data used to run the operation", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RecordDataForNew" + "$ref" : "#/components/schemas/OperationDataForRun" } } } @@ -24525,31 +35982,64 @@ } } }, - "/records/{id}/data-for-edit" : { - "get" : { - "operationId" : "getRecordDataForEdit", - "summary" : "Returns data to edit an existing record", - "description" : "Returns configuration data for editing a record, plus the current `RecordEdit` object that can be altered and sent back", - "tags" : [ "Records" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + "/contact-list/{id}/operations/{operation}/run" : { + "post" : { + "operationId" : "runContactOperation", + "summary" : "Runs a custom operation over a contact", + "description" : "Runs a specific custom operation over a given contact. The operation scope must be `contact`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { "$ref" : "#/components/parameters/id" + }, { + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } } ], "responses" : { "200" : { - "description" : "The data for editing a record", + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RecordDataForEdit" + "$ref" : "#/components/schemas/RunOperationResult" + } + }, + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" } } } @@ -24594,34 +36084,77 @@ } } } + }, + "requestBody" : { + "description" : "The custom operation parameters", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/RunOperation" + } + } + } } } }, - "/records/{id}" : { - "get" : { - "operationId" : "viewRecord", - "summary" : "Returns details of a specific record", - "description" : "Returns information about a record, located by id", - "tags" : [ "Records" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + "/contact-list/{id}/operations/{operation}/run-upload" : { + "post" : { + "operationId" : "runContactOperationWithUpload", + "summary" : "Runs a custom operation over an contact while uploading a file", + "description" : "Runs a specific custom operation over a given contact. The operation scope must be `contact`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { "$ref" : "#/components/parameters/id" + }, { + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } } ], "responses" : { "200" : { - "description" : "The record data", + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RecordView" + "$ref" : "#/components/schemas/RunOperationResult" + } + }, + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" } } } @@ -24666,13 +36199,37 @@ } } } + }, + "requestBody" : { + "content" : { + "multipart/form-data" : { + "schema" : { + "type" : "object", + "properties" : { + "params" : { + "description" : "The custom operation parameters.", + "allOf" : [ { + "$ref" : "#/components/schemas/RunOperation" + } ] + }, + "file" : { + "type" : "string", + "format" : "binary", + "description" : "The file being uploaded" + } + } + } + } + } } - }, - "put" : { - "operationId" : "updateRecord", - "summary" : "Updates an existing record", - "description" : "Updates an existing record", - "tags" : [ "Records" ], + } + }, + "/contact-infos/{id}/operations" : { + "get" : { + "operationId" : "listOperationsByContactInfo", + "summary" : "Lists the custom operations over the given additional contact information", + "description" : "Returns the custom operations the authenticated user can run over the given additional contact iformation. All returned operations have the scope `contactInfo`.", + "tags" : [ "Operations" ], "security" : [ { "basic" : [ ] }, { @@ -24681,18 +36238,20 @@ "accessClient" : [ ] } ], "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { "$ref" : "#/components/parameters/id" } ], "responses" : { - "204" : { - "description" : "The record was updated" - }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", + "200" : { + "description" : "The list of custom operations", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ConflictError" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Operation" + } } } } @@ -24727,16 +36286,6 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { "description" : "Unexpected error", "content" : { @@ -24747,24 +36296,15 @@ } } } - }, - "requestBody" : { - "description" : "The record to be edited", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/RecordEdit" - } - } - } } - }, - "delete" : { - "operationId" : "deleteRecord", - "summary" : "Removes a record", - "description" : "Removes a record", - "tags" : [ "Records" ], + } + }, + "/contact-infos/{id}/operations/{operation}/data-for-run" : { + "get" : { + "operationId" : "getContactInfoOperationDataForRun", + "summary" : "Returns configuration data for running a custom operation over an additional contact information", + "description" : "Returns data to run a specific custom operation over an additional contact information. The operation scope must be `contactInfo`.", + "tags" : [ "Operations" ], "security" : [ { "basic" : [ ] }, { @@ -24773,18 +36313,25 @@ "accessClient" : [ ] } ], "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { "$ref" : "#/components/parameters/id" + }, { + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } } ], "responses" : { - "204" : { - "description" : "The record was deleted" - }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", + "200" : { + "description" : "The data used to run the operation", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ConflictError" + "$ref" : "#/components/schemas/OperationDataForRun" } } } @@ -24832,32 +36379,64 @@ } } }, - "/general-records/record-types" : { - "get" : { - "operationId" : "listRecordTypesForGeneralSearch", - "summary" : "Lists the record types for general search", - "description" : "Returns the record types the authenticated user can use to search records in general, that is, without being of a particular user, but any managed user.", - "tags" : [ "Records" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + "/contact-infos/{id}/operations/{operation}/run" : { + "post" : { + "operationId" : "runContactInfoOperation", + "summary" : "Runs a custom operation over an additional contact information", + "description" : "Runs a specific custom operation over a given additional contact information. The operation scope must be `contactInfo`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], "parameters" : [ { "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/id" + }, { + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } } ], "responses" : { "200" : { - "description" : "The list of visible record types", + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/RecordTypeWithMenu" - } + "$ref" : "#/components/schemas/RunOperationResult" + } + }, + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" } } } @@ -24902,27 +36481,32 @@ } } } + }, + "requestBody" : { + "description" : "The custom operation parameters", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/RunOperation" + } + } + } } } }, - "/general-records/{type}/data-for-search" : { - "get" : { - "operationId" : "getRecordDataForGeneralSearch", - "summary" : "Returns data for searching records of a type over any owner", - "description" : "Returns data for searching records of a specific type over any owner. Is not tied to a particular owner (user or system), hence, is considered a general search.", - "tags" : [ "Records" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + "/contact-infos/{id}/operations/{operation}/run-upload" : { + "post" : { + "operationId" : "runContactInfoOperationWithUpload", + "summary" : "Runs a custom operation over an additional contact information while uploading a file", + "description" : "Runs a specific custom operation over a given additional contact information. The operation scope must be `contactInfo`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", + "tags" : [ "Operations" ], "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "name" : "type", - "description" : "Either the identifier or internal name of the record type", + "$ref" : "#/components/parameters/id" + }, { + "name" : "operation", + "description" : "Either the id or internal name of the custom operation", "in" : "path", "required" : true, "schema" : { @@ -24931,11 +36515,43 @@ } ], "responses" : { "200" : { - "description" : "The configuration data for searching records of this type", + "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/GeneralRecordsDataForSearch" + "$ref" : "#/components/schemas/RunOperationResult" + } + }, + "*/*" : { + "schema" : { + "type" : "string", + "format" : "binary" } } } @@ -24980,15 +36596,37 @@ } } } + }, + "requestBody" : { + "content" : { + "multipart/form-data" : { + "schema" : { + "type" : "object", + "properties" : { + "params" : { + "description" : "The custom operation parameters.", + "allOf" : [ { + "$ref" : "#/components/schemas/RunOperation" + } ] + }, + "file" : { + "type" : "string", + "format" : "binary", + "description" : "The file being uploaded" + } + } + } + } + } } } }, - "/general-records/{type}" : { + "/nfc/{tokenType}/{value}" : { "get" : { - "operationId" : "searchGeneralRecords", - "summary" : "Searches for records of a specific type over any owner", - "description" : "Returns records matching the search criteria, for a specific type. The custom fields returned on each record depend on the field configuration, which needs to be enabled to return on list. The profile fields available as search filters for records are assigned in the products (or admin group permissions).", - "tags" : [ "Records" ], + "operationId" : "getNfcToken", + "summary" : "Retrieve the NFC token detailed data", + "description" : "Returns the token's data and the user owner of the token (i.e the assigned user, if any)", + "tags" : [ "NFC" ], "security" : [ { "basic" : [ ] }, { @@ -24997,144 +36635,29 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "name" : "type", - "description" : "Either the identifier or internal name of the record type", + "name" : "tokenType", + "description" : "The internal name or id of the token type", "in" : "path", "required" : true, "schema" : { "type" : "string" } }, { - "name" : "brokers", - "in" : "query", - "required" : false, - "description" : "Either the ids or identification methods of record owners' brokers", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "creationPeriod", - "in" : "query", - "required" : false, - "description" : "The minimum / maximum record creation date", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string", - "format" : "date-time" - } - } - }, { - "name" : "customFields", - "in" : "query", - "required" : false, - "description" : "Record custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=tradeType:offer|search,extraDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `tradeType` is either `offer` or `search`, and whose `extraDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=extraDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `customFields=dynamic:'business`.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "groups", - "in" : "query", - "required" : false, - "description" : "Either the ids or internal names of record owners' groups", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "keywords", - "in" : "query", - "required" : false, - "description" : "Textual search keywords. Sometimes, like in user search, the fields matched depends on what is configured on the products.", + "name" : "value", + "description" : "The token value", + "in" : "path", + "required" : true, "schema" : { "type" : "string" } - }, { - "name" : "page", - "in" : "query", - "required" : false, - "description" : "The page number (zero-based) of the search. The default value is zero.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - }, { - "name" : "pageSize", - "in" : "query", - "required" : false, - "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - }, { - "name" : "profileFields", - "in" : "query", - "required" : false, - "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } } ], "responses" : { "200" : { - "description" : "The configuration data for searching records", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, + "description" : "Returns the token data", "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/RecordWithOwnerResult" - } + "$ref" : "#/components/schemas/TokenDetailed" } } } @@ -25182,12 +36705,12 @@ } } }, - "/shared-records/data-for-search" : { - "get" : { - "operationId" : "getRecordDataForSharedSearch", - "summary" : "Returns data for searching records with shared fields", - "description" : "Returns data for searching records from multiple types, using shared fields. Only user records can be shared this way.", - "tags" : [ "Records" ], + "/nfc/external-auth" : { + "post" : { + "operationId" : "nfcExternalAuth", + "summary" : "NFC external authentication", + "description" : "The NFC tag will normally perform a mutual authentication, by first generating a challenge that must be encrypted by the external system with the device key. With this the external system is authenticated. Cyclos also returns a challenge that should be encrypted by the NFC tag. This challenge can later be passed in specific operations (for example, when performing a payment) for Cyclos to make sure the NFC tag is present on the operation.", + "tags" : [ "NFC" ], "security" : [ { "basic" : [ ] }, { @@ -25195,16 +36718,14 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - } ], + "parameters" : [ ], "responses" : { "200" : { - "description" : "The configuration data for searching records with shared fields", + "description" : "Returns the challenge to be encrypted by the NFC tag in a subsequent operation", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/SharedRecordsDataForSearch" + "$ref" : "#/components/schemas/NfcExternalAuthenticateResult" } } } @@ -25239,25 +36760,46 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { - "description" : "Unexpected error", + "description" : "If a NFC external authentication error has occurred", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Error" + "$ref" : "#/components/schemas/NfcAuthError" } } } } + }, + "requestBody" : { + "description" : "The parameters for the external authentication. If the `token` value is informed, it will be performed an external authentication with the token itself, using the Application Master Key (AMK). If the `token` is not informed, the authentication will be done using the PICC Master Key (PMK), which is useful, for example, when initializing the NFC tag.", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NfcExternalAuthenticateParameter" + } + } + } } } }, - "/shared-records" : { + "/nfc/data-for-initialize" : { "get" : { - "operationId" : "searchSharedRecords", - "summary" : "Searches for records with shared fields", - "description" : "Returns records matching the search criteria, using shared fields. This allows searching over multiple record types that use shared fields. The custom fields returned on each record depend on the field configuration, which needs to be enabled to return on list. The profile fields available as search filters for records are assigned in the products (or admin group permissions).", - "tags" : [ "Records" ], + "operationId" : "getNfcDataForInitialize", + "summary" : "Returns data for NFC tag initialization. Optionally the user can personalize the tag too.", + "description" : "Returns data with the NFC token types the authenticated user can use to initialize NFC tags.", + "tags" : [ "NFC" ], "security" : [ { "basic" : [ ] }, { @@ -25267,148 +36809,14 @@ } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" - }, { - "name" : "brokers", - "in" : "query", - "required" : false, - "description" : "Either the ids or identification methods of record owners' brokers", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "creationPeriod", - "in" : "query", - "required" : false, - "description" : "The minimum / maximum record creation date", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string", - "format" : "date-time" - } - } - }, { - "name" : "customFields", - "in" : "query", - "required" : false, - "description" : "Record custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=tradeType:offer|search,extraDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `tradeType` is either `offer` or `search`, and whose `extraDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=extraDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `customFields=dynamic:'business`.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "groups", - "in" : "query", - "required" : false, - "description" : "Either the ids or internal names of record owners' groups", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "keywords", - "in" : "query", - "required" : false, - "description" : "Textual search keywords. Sometimes, like in user search, the fields matched depends on what is configured on the products.", - "schema" : { - "type" : "string" - } - }, { - "name" : "page", - "in" : "query", - "required" : false, - "description" : "The page number (zero-based) of the search. The default value is zero.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - }, { - "name" : "pageSize", - "in" : "query", - "required" : false, - "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - }, { - "name" : "profileFields", - "in" : "query", - "required" : false, - "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "types", - "in" : "query", - "required" : false, - "description" : "Either the ids or identification methods of record types", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } } ], "responses" : { "200" : { - "description" : "The configuration data for searching records", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, + "description" : "The data for NFC tag initialization", "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/RecordWithOwnerResult" - } + "$ref" : "#/components/schemas/NfcDataForInitialize" } } } @@ -25456,12 +36864,12 @@ } } }, - "/{owner}/operations" : { - "get" : { - "operationId" : "listOperationsByOwner", - "summary" : "Lists the custom operations over the system or user", - "description" : "Returns the custom operations the authenticated user can run over the given user or system if the `system` owner is used.", - "tags" : [ "Operations" ], + "/nfc/initialize" : { + "post" : { + "operationId" : "initializeNfc", + "summary" : "Initializes a NFC tag", + "description" : "Initializes a NFC tag, creating a new `token` in Cyclos. Returns the keys (PICC Master Key, Application Master Key and the Operational Key) to be stored on the NFC tag.", + "tags" : [ "NFC" ], "security" : [ { "basic" : [ ] }, { @@ -25469,21 +36877,14 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/owner" - } ], + "parameters" : [ ], "responses" : { "200" : { - "description" : "The list of custom operations", + "description" : "The data for NFC tag initialization", "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/Operation" - } + "$ref" : "#/components/schemas/NfcInitializeResult" } } } @@ -25518,25 +36919,46 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { - "description" : "Unexpected error", + "description" : "If a NFC tag inititalization error has occurred", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Error" + "$ref" : "#/components/schemas/InitializeNfcError" } } } } + }, + "requestBody" : { + "description" : "The parameters for initializing the NFC tag. If the `user` value is left blank, the NFC tag will be only initialized, but not personalized (assigned to any user). If a user is given, the permission to personalize is required (besides the permission to initialize), and is a shortcut to initializing and later personalizing the tag. The initialization is a sensitive operation, as the result contains the plain keys that should be stored on the NFC tag. Hence, can only be performed by managers (with granted permission). Later on, other users (for example, businesses) will be able to personalize the NFC tag for customers.", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NfcInitializeParameter" + } + } + } } } }, - "/{owner}/operations/{operation}/data-for-run" : { + "/nfc/data-for-personalize" : { "get" : { - "operationId" : "getOwnerOperationDataForRun", - "summary" : "Returns configuration data for running a custom operation over an owner", - "description" : "Returns data to run a specific custom operation over a given user or system if the `system` owner is used. The operation scope must match, being either `system` or `user`.", - "tags" : [ "Operations" ], + "operationId" : "getNfcDataForPersonalize", + "summary" : "Returns data for perfornalizing an initialized NFC tag for a user", + "description" : "Returns data for personalizing a NFC tag for a given user.", + "tags" : [ "NFC" ], "security" : [ { "basic" : [ ] }, { @@ -25547,23 +36969,29 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/owner" + "name" : "tokenType", + "in" : "query", + "required" : true, + "description" : "The token type reference (id or internal name) of the token principal type, which is stored on the NFC card being personalized.", + "schema" : { + "type" : "string" + } }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", + "name" : "user", + "in" : "query", "required" : true, + "description" : "The user reference (id or an identification method) of the user to whom the NFC tag will be personalized. When authenticated as a manager of that user (administrator or broker) no confirmation password will be required for the personalization. However, if the authenticated user is not a manager, the user will be required a confirmation password.", "schema" : { "type" : "string" } } ], "responses" : { "200" : { - "description" : "The data used to run the operation", + "description" : "The data for NFC tag personalization", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/OperationDataForRun" + "$ref" : "#/components/schemas/NfcDataForPersonalize" } } } @@ -25611,67 +37039,25 @@ } } }, - "/{owner}/operations/{operation}/run" : { + "/nfc/personalize" : { "post" : { - "operationId" : "runOwnerOperation", - "summary" : "Runs a custom operation either for system or user", - "description" : "Runs a specific custom operation over a given user or system if the `system` owner is used. The operation scope must match, being either `system` or `user`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "operationId" : "personalizeNfc", + "summary" : "Personalizes a NFC tag", + "description" : "Personalization requires a NFC tag that was previously initialized, but is still unassigned. This operation doesn't store any key in the NFC tag itself, hence the plain keys are not returned. What is needed is an external authentication with the NFC tag, in order to ensure the card is physically present. The flow for personalizing a tag is: - `GET /nfc/data-for-personalize?user={user}`: Obtain the data for\n personalizing NFC tags for this user. The most important information\n is which the confirmation password will be required, if any;\n- `POST /nfc/external-auth`: With a challenge previously encrypted by the\n NFC tag, invoke this operation. If the challenge matches the NFC token\n in Cyclos, it will be encrypted and returned. Also a new challenge will\n be returned, which should be then encrypted by the NFC tag for later\n being sent back;\n- `POST /nfc/personalize`: With the encrypted challenge and the\n confirmation password (if any), this operation will update the NFC\n token in Cyclos, so it is now assigned to the specified user. From\n this point on, the NFC tag is operational.", + "tags" : [ "NFC" ], + "security" : [ { + "basic" : [ ] }, { - "$ref" : "#/components/parameters/owner" + "session" : [ ] }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/confirmationPassword" } ], "responses" : { - "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" - } - }, - "*/*" : { - "schema" : { - "type" : "string", - "format" : "binary" - } - } - } + "204" : { + "description" : "The NFC tag is personalized and nothing is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -25703,90 +37089,65 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { - "description" : "Unexpected error", + "description" : "If a NFC tag personalization error has occurred", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Error" + "$ref" : "#/components/schemas/PersonalizeNfcError" } } } } }, "requestBody" : { - "description" : "The custom operation parameters", + "description" : "The parameters for the initialization.", + "required" : true, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RunOperation" + "$ref" : "#/components/schemas/NfcPersonalizeParameter" } } } } } }, - "/{owner}/operations/{operation}/run-upload" : { + "/nfc/personalize/otp" : { "post" : { - "operationId" : "runOwnerOperationWithUpload", - "summary" : "Runs a custom operation either for system or user while uploading a file", - "description" : "Runs a specific custom operation over a given user or system if the `system` owner is used. The operation scope must match, being either `system` or `user`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "operationId" : "getOtpForPersonalizeNfc", + "summary" : "Generates a new One-Time-Password (OTP) for personalizing a NFC tag", + "description" : "Sends a new OTP for the customer which will own the NFC tag. The OTP belongs to the NFC tag owner, not the authenticated user.", + "tags" : [ "NFC" ], + "security" : [ { + "basic" : [ ] }, { - "$ref" : "#/components/parameters/owner" + "session" : [ ] }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", + "accessClient" : [ ] + } ], + "parameters" : [ { + "name" : "medium", + "in" : "query", "required" : true, + "description" : "The medium the user wants to receive the otp", "schema" : { - "type" : "string" + "$ref" : "#/components/schemas/SendMediumEnum" } } ], "responses" : { - "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" - } - }, - "*/*" : { - "schema" : { - "type" : "string", - "format" : "binary" - } - } - } + "204" : { + "description" : "The OTP is sent to the user, and no content is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -25819,71 +37180,43 @@ } }, "500" : { - "description" : "Unexpected error", + "description" : "There was an error when generating the OTP", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Error" + "$ref" : "#/components/schemas/OtpError" } } } } }, "requestBody" : { + "description" : "The parameters identifying the token and the user", + "required" : true, "content" : { - "multipart/form-data" : { + "application/json" : { "schema" : { - "type" : "object", - "properties" : { - "params" : { - "description" : "The custom operation parameters.", - "allOf" : [ { - "$ref" : "#/components/schemas/RunOperation" - } ] - }, - "file" : { - "type" : "string", - "format" : "binary", - "description" : "The file being uploaded" - } - } + "$ref" : "#/components/schemas/NfcPersonalizeDataParameter" } } } } } }, - "/operations/{operation}/data-for-run" : { - "get" : { - "operationId" : "getOperationDataForRun", - "summary" : "Returns configuration data for running a custom operation without additional scope", - "description" : "Returns data to run a specific custom operation, which must not have any additional scope to run, such as user, contact, record or advertisement. Hence, this path is suitable for custom operations with scope `system` or `internal`.", - "tags" : [ "Operations" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } - } ], + "/nfc/personalize/device-confirmations" : { + "post" : { + "operationId" : "createDeviceConfirmationForPersonalizeNfc", + "summary" : "Creates a pending device confirmation for personalizing a NFC tag.", + "description" : "Creates a device confirmation for the customer which will own the NFC tag. The confirmation must be approved by the NFC tag owner, not the authenticated user, i.e the confirmation QR-code must be read (e.g with the Mobile App) by the customer. After the confirmation being processed the authenticated user will be notified.", + "tags" : [ "NFC" ], + "parameters" : [ ], "responses" : { - "200" : { - "description" : "The data used to run the operation", + "201" : { + "description" : "Returns the identifier of the new confirmation.", "content" : { - "application/json" : { + "text/plain" : { "schema" : { - "$ref" : "#/components/schemas/OperationDataForRun" + "type" : "string" } } } @@ -25918,6 +37251,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -25928,21 +37271,47 @@ } } } + }, + "requestBody" : { + "description" : "The parameters identifying the token and the user", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NfcPersonalizeDataParameter" + } + } + } } } }, - "/operations/{operation}/run" : { - "post" : { - "operationId" : "runOperation", - "summary" : "Runs a custom operation without additional scope", - "description" : "Runs a specific custom operation without additional scope. Is suitable for operations with scope `system` or `internal`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], + "/nfc/personalize/device-confirmations/{id}" : { + "get" : { + "operationId" : "viewDeviceConfirmationForPersonalizeNfc", + "summary" : "Shows the details of a device confirmation that was created to confirm the personalize nfc-tag operation.", + "description" : "Shows a device confirmation for the user which will own the NFC tag. The confirmation belongs to that user, not the authenticated user. The same parameters used for the creation must be sent for this operation too.", + "tags" : [ "NFC" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "$ref" : "#/components/parameters/id" + }, { + "name" : "user", + "description" : "The principal (id, login name, etc) of the user who will own the tag. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`.", + "in" : "query", + "required" : true, + "schema" : { + "type" : "string" + } }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", + "name" : "type", + "description" : "Either the identifier or internal name of fhe NFC token type", + "in" : "query", "required" : true, "schema" : { "type" : "string" @@ -25950,43 +37319,11 @@ } ], "responses" : { "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, + "description" : "The device confirmation details.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" - } - }, - "*/*" : { - "schema" : { - "type" : "string", - "format" : "binary" + "$ref" : "#/components/schemas/DeviceConfirmationView" } } } @@ -26031,75 +37368,49 @@ } } } - }, - "requestBody" : { - "description" : "The custom operation parameters", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/RunOperation" - } - } - } } - } - }, - "/operations/{operation}/run-upload" : { - "post" : { - "operationId" : "runOperationWithUpload", - "summary" : "Runs a custom operation without additional scope while uploading a file", - "description" : "Runs a specific custom operation without additional scope. Is suitable for operations with scope `system` or `internal`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], + }, + "delete" : { + "operationId" : "deleteDeviceConfirmationForPersonalizeNfc", + "summary" : "Deletes a device confirmation that was created to confirm the personalize nfc-tag operation.", + "description" : "Deletes a device confirmation for the user which will own the NFC tag. The confirmation belongs to that user, not the authenticated user. The same parameters used for the creation must be sent for this operation too.", + "tags" : [ "NFC" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "$ref" : "#/components/parameters/id" }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", + "name" : "user", + "description" : "The principal (id, login name, etc) of the user who will own the tag. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`.", + "in" : "query", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "name" : "type", + "description" : "Either the identifier or internal name of fhe NFC token type", + "in" : "query", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { - "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, + "204" : { + "description" : "The device confirmation was removed." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" - } - }, - "*/*" : { - "schema" : { - "type" : "string", - "format" : "binary" + "$ref" : "#/components/schemas/ConflictError" } } } @@ -26144,61 +37455,49 @@ } } } - }, - "requestBody" : { - "content" : { - "multipart/form-data" : { - "schema" : { - "type" : "object", - "properties" : { - "params" : { - "description" : "The custom operation parameters.", - "allOf" : [ { - "$ref" : "#/components/schemas/RunOperation" - } ] - }, - "file" : { - "type" : "string", - "format" : "binary", - "description" : "The file being uploaded" - } - } - } - } - } } } }, - "/operations/callback/{id}" : { - "post" : { - "operationId" : "runCustomOperationCallback", - "summary" : "Runs the callback of an external redirect custom operation", - "description" : "Custom operations may be configured in Cyclos to be of result type `externalRedirect`. In such case, the regular execution returns an URL to which redirect clients. Once the external page processing is complete, the user is redirected back, so the operation can be completed. This operation should be executed to complete the payment. In order for the external service receive the correct URL, Cyclos need to have a link generation script that handles the link type `EXTERNAL_REDIRECT`.", - "tags" : [ "Operations" ], + "/nfc/personalize/device-confirmations/{id}/qr-code" : { + "get" : { + "operationId" : "getDeviceConfirmationQrCodeForPersonalizeNfc", + "summary" : "Returns the QR-code image for the given device confirmation only if it was not yet approved / rejected", + "description" : "This request will return the image contents as expected but our api documentation page (or any other usage of an <img> tag), created using swagger-ui, generates a second request to include the image in the page. This new (GET) request won't send the authentication parameters and as this path requires authentication the image will be shown as broken. Optionally, to solve the problem described above and to allow authenticate the user when using sessions, a `sessionToken` or `accessClientToken` query parameter could be specified.", + "tags" : [ "NFC" ], "parameters" : [ { - "name" : "id", - "description" : "The external redirect identifier. Received as part of the URL which is generated by Cyclos to the external service to use as callback.", - "in" : "path", + "$ref" : "#/components/parameters/id" + }, { + "name" : "user", + "description" : "The principal (id, login name, etc) of the user who will own the tag. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`.", + "in" : "query", "required" : true, "schema" : { "type" : "string" } }, { - "name" : "token", - "description" : "The security token which is received as part of the URL which is generated by Cyclos to the external service to use as callback.", + "name" : "type", + "description" : "Either the identifier or internal name of fhe NFC token type", "in" : "query", - "required" : false, + "required" : true, "schema" : { "type" : "string" } + }, { + "name" : "size", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/ImageSizeEnum" + } } ], "responses" : { "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "description" : "The image content", "content" : { - "application/json" : { + "image/png" : { "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" + "type" : "string", + "format" : "binary" } } } @@ -26243,25 +37542,15 @@ } } } - }, - "requestBody" : { - "description" : "Data of the original callback request sent by the external service", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/HttpRequestData" - } - } - } } } }, - "/marketplace/{ad}/operations" : { - "get" : { - "operationId" : "listOperationsByAd", - "summary" : "Lists the custom operations over the given advertisement", - "description" : "Returns the custom operations the authenticated user can run over the given advertisement. All returned operations have the scope `advertisement`.", - "tags" : [ "Operations" ], + "/nfc/cancel" : { + "post" : { + "operationId" : "cancelNfc", + "summary" : "Cancels a NFC tag", + "description" : "Cancels a NFC token. Must be authenticated as a manager (administrator / broker) of the token owner, and have the correct permission.", + "tags" : [ "NFC" ], "security" : [ { "basic" : [ ] }, { @@ -26269,24 +37558,10 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/ad" - } ], + "parameters" : [ ], "responses" : { - "200" : { - "description" : "The list of custom operations", - "content" : { - "application/json" : { - "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/Operation" - } - } - } - } + "204" : { + "description" : "The NFC tag is canceled and nothing is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -26328,42 +37603,122 @@ } } } + }, + "requestBody" : { + "description" : "The parameters for canceling.", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NfcTokenParameter" + } + } + } } } }, - "/marketplace/{ad}/operations/{operation}/data-for-run" : { + "/push/subscribe" : { "get" : { - "operationId" : "getAdOperationDataForRun", - "summary" : "Returns configuration data for running a custom operation over an advertisement", - "description" : "Returns data to run a specific custom operation over an advertisement. The operation scope must be `advertisement`.", - "tags" : [ "Operations" ], - "security" : [ { - "basic" : [ ] + "operationId" : "subscribeForPushNotifications", + "summary" : "Subscribes for receiving push notifications of specific types", + "description" : "Returns an event stream of server-sent events", + "tags" : [ "Push" ], + "parameters" : [ { + "name" : "clientId", + "in" : "query", + "required" : true, + "description" : "An id generated by the client. This id is valid for the authenticated used, indicating a single session. As event streams can timeout and be reconnected, subsequent subscriptions with the same user and client id are considered the same subscription, and missed events since the last timeout will be immediately delivered. Missed events are enqueued up to a few minutes after the connection timeout. After that window, any enqueued events are discarded.", + "schema" : { + "type" : "string" + } }, { - "session" : [ ] + "name" : "kinds", + "in" : "query", + "required" : true, + "description" : "The event kinds for which the client desires to subscribe", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/PushNotificationEventKind" + } + } }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "name" : "accountIds", + "in" : "query", + "required" : false, + "description" : "When subscribing to `accountStatus` events, this parameter must be informed to select the accounts to be watched for.", + "schema" : { + "type" : "array", + "items" : { + "type" : "string" + } + } }, { - "$ref" : "#/components/parameters/ad" + "name" : "ticketNumber", + "in" : "query", + "required" : false, + "description" : "When subscribing to `ticket` events, this parameter can be used to filter which ticket to monitor.", + "schema" : { + "type" : "string" + } }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, + "name" : "deviceConfirmationId", + "in" : "query", + "required" : false, + "description" : "When subscribing to `deviceConfirmationFeedback` events, this parameter can be used to filter which device confirmation to monitor.", + "schema" : { + "type" : "string" + } + }, { + "name" : "identityProviderRequestId", + "in" : "query", + "required" : false, + "description" : "When subscribing to `identityProviderCallback` events, this parameter can be used to filter which request to monitor.", + "schema" : { + "type" : "string" + } + }, { + "name" : "lastEventId", + "in" : "header", + "required" : false, + "description" : "The last received event id, in case of reconnections. May also be passed as the standard header `Last-Event-ID`.", "schema" : { "type" : "string" } } ], "responses" : { "200" : { - "description" : "The data used to run the operation", + "description" : "The event stream", + "content" : { + "text/event-stream" : { + "schema" : { + "type" : "string" + } + } + } + }, + "203" : { + "description" : "This status code isn't actually returned, but listed here to reference all possible data types which are sent in push events.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/OperationDataForRun" + "anyOf" : [ { + "$ref" : "#/components/schemas/NewNotificationPush" + }, { + "$ref" : "#/components/schemas/NewMessagePush" + }, { + "$ref" : "#/components/schemas/Transaction" + }, { + "$ref" : "#/components/schemas/TransactionView" + }, { + "$ref" : "#/components/schemas/AccountWithStatus" + }, { + "$ref" : "#/components/schemas/DeviceConfirmationView" + }, { + "$ref" : "#/components/schemas/DeviceConfirmationFeedbackPush" + }, { + "$ref" : "#/components/schemas/IdentityProviderCallbackResult" + } ] } } } @@ -26411,64 +37766,56 @@ } } }, - "/marketplace/{ad}/operations/{operation}/run" : { - "post" : { - "operationId" : "runAdOperation", - "summary" : "Runs a custom operation over an advertisement", - "description" : "Runs a specific custom operation over a given advertisement. The operation scope must be `advertisement`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], + "/ui/data-for-ui" : { + "get" : { + "operationId" : "dataForUi", + "summary" : "Returns useful data required to properly display a user interface", + "description" : "The returned data contains settings and also content like header, footer and theme.", + "tags" : [ "UI" ], "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/ad" + "name" : "kind", + "in" : "query", + "required" : false, + "description" : "Specifies the kind of user interface to get data for. If null then no data related to the UI will be returned.", + "schema" : { + "$ref" : "#/components/schemas/UiKind" + } }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, + "$ref" : "#/components/parameters/cyclosVersion" + }, { + "$ref" : "#/components/parameters/headerIf" + }, { + "$ref" : "#/components/parameters/footerIf" + }, { + "$ref" : "#/components/parameters/themeIf" + }, { + "$ref" : "#/components/parameters/themeByComponents" + }, { + "name" : "deviceId", + "in" : "query", + "required" : false, + "description" : "Trusted device identification. If given and the device is active then a pending device confirmation will be created that will be validated after the user logs-in. If the validation passes then no confirmation password will be used only for that session.", + "schema" : { + "type" : "string" + } + }, { + "name" : "pinId", + "in" : "query", + "required" : false, + "description" : "Device PIN identification. If given then the information about whether it is active or not will be given in the returned `dataForLogin`.", "schema" : { "type" : "string" } } ], "responses" : { "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, + "description" : "Returns the data for display a user interface", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" - } - }, - "*/*" : { - "schema" : { - "type" : "string", - "format" : "binary" + "$ref" : "#/components/schemas/DataForUi" } } } @@ -26513,80 +37860,27 @@ } } } - }, - "requestBody" : { - "description" : "The custom operation parameters", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/RunOperation" - } - } - } } } }, - "/marketplace/{ad}/operations/{operation}/run-upload" : { + "/validate/email-change/{key}" : { + "parameters" : [ { + "name" : "key", + "required" : true, + "in" : "path", + "description" : "The e-mail change validation key the user has received.", + "schema" : { + "type" : "string" + } + } ], "post" : { - "operationId" : "runAdOperationWithUpload", - "summary" : "Runs a custom operation over an advertisement while uploading a file", - "description" : "Runs a specific custom operation over a given advertisement. The operation scope must be `advertisement`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/ad" - }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } - } ], + "operationId" : "validateEmailChange", + "summary" : "Validate a pending e-mail change.", + "description" : "When e-mail validation on change is enabled on the configuration, when a user changes their e-mail the new e-mail will not be immediately used. In this case, an e-mail is sent to the new e-mail address, with a link to validate it. That link should include the validation key, which should be sent to the Cyclos backend to actually validate the new e-mail. Only after this the new e-mail address will be effectively used in Cyclos.", + "tags" : [ "Validation" ], "responses" : { "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" - } - }, - "*/*" : { - "schema" : { - "type" : "string", - "format" : "binary" - } - } - } + "description" : "If the e-mail change was validated correctly." }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -26608,12 +37902,22 @@ } } }, - "404" : { - "description" : "An expected data was not found", + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/NotFoundError" + "$ref" : "#/components/schemas/InputError" } } } @@ -26628,59 +37932,31 @@ } } } - }, - "requestBody" : { - "content" : { - "multipart/form-data" : { - "schema" : { - "type" : "object", - "properties" : { - "params" : { - "description" : "The custom operation parameters.", - "allOf" : [ { - "$ref" : "#/components/schemas/RunOperation" - } ] - }, - "file" : { - "type" : "string", - "format" : "binary", - "description" : "The file being uploaded" - } - } - } - } - } } } }, - "/records/{id}/operations" : { - "get" : { - "operationId" : "listOperationsByRecord", - "summary" : "Lists the custom operations over the given record", - "description" : "Returns the custom operations the authenticated user can run over the given record. All returned operations have the scope `record`.", - "tags" : [ "Operations" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/id" - } ], + "/validate/registration/{key}" : { + "parameters" : [ { + "name" : "key", + "required" : true, + "in" : "path", + "description" : "The registration validation key the user has received.", + "schema" : { + "type" : "string" + } + } ], + "post" : { + "operationId" : "validateUserRegistration", + "summary" : "Validate a pending user registration.", + "description" : "Validate a pending user registration for the given validation key. After validating the registration is completed. However, the group configuration defines if the user is initially active or not.", + "tags" : [ "Validation" ], "responses" : { "200" : { - "description" : "The list of custom operations", + "description" : "The result of the validation. The resulting status only can be `active` or `inactive`.", "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/Operation" - } + "$ref" : "#/components/schemas/UserRegistrationResult" } } } @@ -26715,6 +37991,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -26728,12 +38014,15 @@ } } }, - "/records/{id}/operations/{operation}/data-for-run" : { - "get" : { - "operationId" : "getRecordOperationDataForRun", - "summary" : "Returns configuration data for running a custom operation over a record", - "description" : "Returns data to run a specific custom operation over a record. The operation scope must be `record`.", - "tags" : [ "Operations" ], + "/{user}/registration/validate" : { + "parameters" : [ { + "$ref" : "#/components/parameters/userNoSelf" + } ], + "post" : { + "operationId" : "manuallyValidateUserRegistration", + "summary" : "Manually validates a pending user / operator registration.", + "description" : "Marks the user registration as validated. Can only be performed by a manager (admin / broker) of the pending user. The actual resulting user status depends on the group configuration. The user status must be `pending`.", + "tags" : [ "Validation" ], "security" : [ { "basic" : [ ] }, { @@ -26741,26 +38030,13 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/id" - }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } - } ], "responses" : { "200" : { - "description" : "The data used to run the operation", + "description" : "The result of the e-mail validation. The resulting status only can be `active` or `inactive`.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/OperationDataForRun" + "$ref" : "#/components/schemas/UserRegistrationResult" } } } @@ -26808,67 +38084,25 @@ } } }, - "/records/{id}/operations/{operation}/run" : { + "/{user}/registration/resend" : { + "parameters" : [ { + "$ref" : "#/components/parameters/userNoSelf" + } ], "post" : { - "operationId" : "runRecordOperation", - "summary" : "Runs a custom operation over a record", - "description" : "Runs a specific custom operation over a given record. The operation scope must be `record`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "operationId" : "resendUserRegistrationEmail", + "summary" : "Re-sends the e-mail to validate a pending user / operator registration.", + "description" : "Sends the validation e-mail again. This operation has to be executed by the user manager (admin or broker). The user status must be `pending`.", + "tags" : [ "Validation" ], + "security" : [ { + "basic" : [ ] }, { - "$ref" : "#/components/parameters/id" + "session" : [ ] }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } + "accessClient" : [ ] } ], "responses" : { - "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" - } - }, - "*/*" : { - "schema" : { - "type" : "string", - "format" : "binary" - } - } - } + "204" : { + "description" : "The e-mail is sent and nothing is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -26910,80 +38144,28 @@ } } } - }, - "requestBody" : { - "description" : "The custom operation parameters", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/RunOperation" - } - } - } } } }, - "/records/{id}/operations/{operation}/run-upload" : { + "/{user}/email-change/validate" : { + "parameters" : [ { + "$ref" : "#/components/parameters/userNoSelf" + } ], "post" : { - "operationId" : "runRecordOperationWithUpload", - "summary" : "Runs a custom operation over a record while uploading a file", - "description" : "Runs a specific custom operation over a given record. The operation scope must be `record`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "operationId" : "manuallyValidateEmailChange", + "summary" : "Manually validates a pending e-mail change.", + "description" : "If the user has a new e-mail address pending validation, this operation, which has to be executed by the user manager (admin or broker) marks the new e-mail address as validating, effectively changing the user's e-mail.", + "tags" : [ "Validation" ], + "security" : [ { + "basic" : [ ] }, { - "$ref" : "#/components/parameters/id" + "session" : [ ] }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } + "accessClient" : [ ] } ], "responses" : { - "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" - } - }, - "*/*" : { - "schema" : { - "type" : "string", - "format" : "binary" - } - } - } + "204" : { + "description" : "The new e-mail address is effectly used and nothing is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -27025,37 +38207,18 @@ } } } - }, - "requestBody" : { - "content" : { - "multipart/form-data" : { - "schema" : { - "type" : "object", - "properties" : { - "params" : { - "description" : "The custom operation parameters.", - "allOf" : [ { - "$ref" : "#/components/schemas/RunOperation" - } ] - }, - "file" : { - "type" : "string", - "format" : "binary", - "description" : "The file being uploaded" - } - } - } - } - } } } }, - "/transfers/{key}/operations" : { - "get" : { - "operationId" : "listOperationsByTransfer", - "summary" : "Lists the custom operations over the given transfer", - "description" : "Returns the custom operations the authenticated user can run over the given transfer. All returned operations have the scope `transfer`.", - "tags" : [ "Operations" ], + "/{user}/email-change/resend" : { + "parameters" : [ { + "$ref" : "#/components/parameters/userNoSelf" + } ], + "post" : { + "operationId" : "resendEmailChangeEmail", + "summary" : "Re-sends the e-mail to validate a pending e-mail change.", + "description" : "Sends again the e-mail to the new user e-mail address. This operation has to be executed by the user manager (admin or broker).", + "tags" : [ "Validation" ], "security" : [ { "basic" : [ ] }, { @@ -27063,30 +38226,9 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number", - "schema" : { - "type" : "string" - } - } ], "responses" : { - "200" : { - "description" : "The list of custom operations", - "content" : { - "application/json" : { - "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/Operation" - } - } - } - } + "204" : { + "description" : "The new e-mail address is effectly used and nothing is returned" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -27131,12 +38273,12 @@ } } }, - "/transfer/{key}/operations/{operation}/data-for-run" : { + "/localization/locales" : { "get" : { - "operationId" : "getTransferOperationDataForRun", - "summary" : "Returns configuration data for running a custom operation over a transfer", - "description" : "Returns data to run a specific custom operation over a transfer. The operation scope must be `transfer`.", - "tags" : [ "Operations" ], + "operationId" : "getLocales", + "summary" : "Returns the list of available locales, this collection is already sent in DataForUI or MobileBaseData.", + "description" : "Returns the list of available locales.", + "tags" : [ "Localization" ], "security" : [ { "basic" : [ ] }, { @@ -27144,32 +38286,16 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number", - "schema" : { - "type" : "string" - } - }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } - } ], "responses" : { "200" : { - "description" : "The data used to run the operation", + "description" : "The list of available locales.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/OperationDataForRun" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/UserLocale" + } } } } @@ -27217,73 +38343,23 @@ } } }, - "/transfers/{key}/operations/{operation}/run" : { + "/localization/settings" : { "post" : { - "operationId" : "runTransferOperation", - "summary" : "Runs a custom operation over a transfer", - "description" : "Runs a specific custom operation over a given transfer. The operation scope must be `transfer`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "operationId" : "saveLocalizationSettings", + "summary" : "Saves the localization settings for the authenticated user.", + "description" : "Saves the localization settings for the authenticated user such as the preferred language.", + "parameters" : [ ], + "tags" : [ "Localization" ], + "security" : [ { + "basic" : [ ] }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number", - "schema" : { - "type" : "string" - } + "session" : [ ] }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } + "accessClient" : [ ] } ], "responses" : { - "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" - } - }, - "*/*" : { - "schema" : { - "type" : "string", - "format" : "binary" - } - } - } + "204" : { + "description" : "The settings were saved" }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -27325,47 +38401,121 @@ } } } - }, - "requestBody" : { - "description" : "The custom operation parameters", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/RunOperation" - } - } + }, + "requestBody" : { + "description" : "The localization settings.", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/LocalizationSettings" + } + } + } + } + } + }, + "/alerts/user" : { + "get" : { + "operationId" : "searchUserAlerts", + "summary" : "Searches for user alerts.", + "description" : "Searches for user alerts according to a give set of filters.", + "tags" : [ "Alerts" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "name" : "brokers", + "in" : "query", + "required" : false, + "description" : "Either the ids or identification methods the alert user's brokers", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "datePeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum alert date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "groups", + "in" : "query", + "required" : false, + "description" : "Either the ids or internal names of the alert user", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string" + } + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" } - } - } - }, - "/transfers/{key}/operations/{operation}/run-upload" : { - "post" : { - "operationId" : "runTransferOperationWithUpload", - "summary" : "Runs a custom operation over a transfer while uploading a file", - "description" : "Runs a specific custom operation over a given transfer. The operation scope must be `transfer`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" }, { - "name" : "key", - "in" : "path", - "required" : true, - "description" : "Either the id or transaction number", + "name" : "types", + "in" : "query", + "required" : false, + "description" : "The types of user alerts to search", "schema" : { - "type" : "string" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/UserAlertTypeEnum" + } } }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, + "name" : "user", + "in" : "query", + "required" : false, + "description" : "Either the id or identifier of the alert user", "schema" : { "type" : "string" } } ], "responses" : { "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "description" : "The accounts with their statuses.", "headers" : { "X-Total-Count" : { "schema" : { @@ -27395,13 +38545,10 @@ "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" - } - }, - "*/*" : { - "schema" : { - "type" : "string", - "format" : "binary" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/UserAlert" + } } } } @@ -27446,37 +38593,15 @@ } } } - }, - "requestBody" : { - "content" : { - "multipart/form-data" : { - "schema" : { - "type" : "object", - "properties" : { - "params" : { - "description" : "The custom operation parameters.", - "allOf" : [ { - "$ref" : "#/components/schemas/RunOperation" - } ] - }, - "file" : { - "type" : "string", - "format" : "binary", - "description" : "The file being uploaded" - } - } - } - } - } } } }, - "/contact-list/{id}/operations" : { + "/alerts/user/data-for-search" : { "get" : { - "operationId" : "listOperationsByContact", - "summary" : "Lists the custom operations over the given contact", - "description" : "Returns the custom operations the authenticated user can run over the given contact. All returned operations have the scope `contact`.", - "tags" : [ "Operations" ], + "operationId" : "getUserAlertDataForSearch", + "summary" : "Returns configuration data for searching user alerts.", + "description" : "Returns configuration data for searching user alerts.", + "tags" : [ "Alerts" ], "security" : [ { "basic" : [ ] }, { @@ -27486,19 +38611,14 @@ } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/id" } ], "responses" : { "200" : { - "description" : "The list of custom operations", + "description" : "The data for searching user alerts", "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/Operation" - } + "$ref" : "#/components/schemas/UserAlertDataForSearch" } } } @@ -27546,12 +38666,15 @@ } } }, - "/contact-list/{id}/operations/{operation}/data-for-run" : { + "/{user}/references/data-for-search" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], "get" : { - "operationId" : "getContactOperationDataForRun", - "summary" : "Returns configuration data for running a custom operation over a contact", - "description" : "Returns data to run a specific custom operation over a contact. The operation scope must be `contact`.", - "tags" : [ "Operations" ], + "operationId" : "getUserReferencesDataForSearch", + "summary" : "Returns data for searching references of a specific user.", + "description" : "Returns data for searching references of a specific user.", + "tags" : [ "References" ], "security" : [ { "basic" : [ ] }, { @@ -27561,24 +38684,14 @@ } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/id" - }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } } ], "responses" : { "200" : { - "description" : "The data used to run the operation", + "description" : "The configuration data for searching references", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/OperationDataForRun" + "$ref" : "#/components/schemas/UserReferenceDataForSearch" } } } @@ -27626,28 +38739,93 @@ } } }, - "/contact-list/{id}/operations/{operation}/run" : { - "post" : { - "operationId" : "runContactOperation", - "summary" : "Runs a custom operation over a contact", - "description" : "Runs a specific custom operation over a given contact. The operation scope must be `contact`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], + "/{user}/references" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], + "get" : { + "operationId" : "searchUserReferences", + "summary" : "Searches for references of a specific user", + "description" : "Returns references matching the search criteria, for a specific user.", + "tags" : [ "References" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/id" + "name" : "direction", + "in" : "query", + "required" : false, + "schema" : { + "$ref" : "#/components/schemas/ReferenceDirectionEnum" + } }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, + "name" : "levels", + "in" : "query", + "required" : false, + "description" : "The levels to filter", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ReferenceLevelEnum" + } + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "period", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum reference date", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "relatedUser", + "in" : "query", + "required" : false, + "description" : "The user that either gave or received the reference to the user specified in the path. Should be either the id or some other allowed identification (login name, email, etc).", "schema" : { "type" : "string" } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } } ], "responses" : { "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", + "description" : "The references matching the search filters.", "headers" : { "X-Total-Count" : { "schema" : { @@ -27677,13 +38855,10 @@ "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" - } - }, - "*/*" : { - "schema" : { - "type" : "string", - "format" : "binary" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/UserReferenceResult" + } } } } @@ -27728,77 +38903,54 @@ } } } - }, - "requestBody" : { - "description" : "The custom operation parameters", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/RunOperation" - } - } - } } } }, - "/contact-list/{id}/operations/{operation}/run-upload" : { - "post" : { - "operationId" : "runContactOperationWithUpload", - "summary" : "Runs a custom operation over an contact while uploading a file", - "description" : "Runs a specific custom operation over a given contact. The operation scope must be `contact`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], + "/{user}/references/statistics" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], + "get" : { + "operationId" : "getUserReferenceStatistics", + "summary" : "Returns statistics for a given user references.", + "description" : "Returns statistics for a given user references.", + "tags" : [ "References" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/id" + "name" : "direction", + "in" : "query", + "required" : false, + "description" : "Whether to return statistics on received or given references. When not specified, defaults to received.", + "schema" : { + "$ref" : "#/components/schemas/ReferenceDirectionEnum" + } }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, + "name" : "periods", + "description" : "The requested periods for statistics. The result will have the `periods` field corresponding to the input periods. When not specified, the default is to return 2 periods: all time and last 30 days. The maximum allowed number of periods is 5. Each period can either be:\n\n- Single date: in ISO 8601 format, from that date and up.\n Example: `2019-10-30`;\n\n- 2 dates, split by pipe: Both in ISO 8601 format, specifying\n a period range. Example: `2019-10-01|2019-12-31T23:59:59.999`.", + "in" : "query", + "required" : false, "schema" : { - "type" : "string" + "type" : "array", + "items" : { + "type" : "string" + } } } ], "responses" : { "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, + "description" : "The reference statistics for the requested periods.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" - } - }, - "*/*" : { - "schema" : { - "type" : "string", - "format" : "binary" + "$ref" : "#/components/schemas/ReferenceStatistics" } } } @@ -27843,37 +38995,34 @@ } } } - }, - "requestBody" : { - "content" : { - "multipart/form-data" : { - "schema" : { - "type" : "object", - "properties" : { - "params" : { - "description" : "The custom operation parameters.", - "allOf" : [ { - "$ref" : "#/components/schemas/RunOperation" - } ] - }, - "file" : { - "type" : "string", - "format" : "binary", - "description" : "The file being uploaded" - } - } - } - } - } } } }, - "/contact-infos/{id}/operations" : { + "/{from}/reference/{to}/data-for-set" : { + "parameters" : [ { + "name" : "from", + "required" : true, + "in" : "path", + "x-dotInPath" : true, + "schema" : { + "type" : "string" + }, + "description" : "The user that will give the reference. Can be `self` for the currently authenticated user, or the id or some other allowed identifier (login name, e-mail, etc)." + }, { + "name" : "to", + "required" : true, + "in" : "path", + "x-dotInPath" : true, + "schema" : { + "type" : "string" + }, + "description" : "The user that will receive the reference. Can be the id or some other allowed identifier (login name, e-mail, etc)." + } ], "get" : { - "operationId" : "listOperationsByContactInfo", - "summary" : "Lists the custom operations over the given additional contact information", - "description" : "Returns the custom operations the authenticated user can run over the given additional contact iformation. All returned operations have the scope `contactInfo`.", - "tags" : [ "Operations" ], + "operationId" : "getReferenceDataForSet", + "summary" : "Returns details for setting a reference.", + "description" : "Returns details for setting a reference.", + "tags" : [ "References" ], "security" : [ { "basic" : [ ] }, { @@ -27883,19 +39032,14 @@ } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/id" } ], "responses" : { "200" : { - "description" : "The list of custom operations", + "description" : "Contains data for setting the reference, as well as the current value, if any.", "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/Operation" - } + "$ref" : "#/components/schemas/ReferenceDataForSet" } } } @@ -27943,39 +39087,46 @@ } } }, - "/contact-infos/{id}/operations/{operation}/data-for-run" : { - "get" : { - "operationId" : "getContactInfoOperationDataForRun", - "summary" : "Returns configuration data for running a custom operation over an additional contact information", - "description" : "Returns data to run a specific custom operation over an additional contact information. The operation scope must be `contactInfo`.", - "tags" : [ "Operations" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/id" - }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } - } ], + "/{from}/reference/{to}" : { + "parameters" : [ { + "name" : "from", + "required" : true, + "in" : "path", + "x-dotInPath" : true, + "schema" : { + "type" : "string" + }, + "description" : "The user that will give the reference. Can be `self` for the currently authenticated user, or the id or some other allowed identifier (login name, e-mail, etc)." + }, { + "name" : "to", + "required" : true, + "in" : "path", + "x-dotInPath" : true, + "schema" : { + "type" : "string" + }, + "description" : "The user that will receive the reference. Can be the id or some other allowed identifier (login name, e-mail, etc)." + } ], + "post" : { + "operationId" : "setReference", + "summary" : "Creates or changes the reference between the given users.", + "description" : "Creates or changes the reference between the given users.", + "tags" : [ "References" ], "responses" : { - "200" : { - "description" : "The data used to run the operation", + "201" : { + "description" : "Returns the identifier of the created / modified reference", + "headers" : { + "Location" : { + "description" : "URL for viewing the reference details", + "schema" : { + "type" : "string" + } + } + }, "content" : { - "application/json" : { + "text/plain" : { "schema" : { - "$ref" : "#/components/schemas/OperationDataForRun" + "type" : "string" } } } @@ -28010,6 +39161,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -28020,70 +39181,107 @@ } } } + }, + "requestBody" : { + "description" : "The reference details", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ReferenceSet" + } + } + } } } }, - "/contact-infos/{id}/operations/{operation}/run" : { - "post" : { - "operationId" : "runContactInfoOperation", - "summary" : "Runs a custom operation over an additional contact information", - "description" : "Runs a specific custom operation over a given additional contact information. The operation scope must be `contactInfo`. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "/references/{id}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], + "get" : { + "operationId" : "viewReference", + "summary" : "Returns details of a specific reference.", + "description" : "Returns details of a specific reference.", + "tags" : [ "References" ], + "security" : [ { + "basic" : [ ] }, { - "$ref" : "#/components/parameters/id" + "session" : [ ] }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" } ], "responses" : { "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { + "description" : "The reference details.", + "content" : { + "application/json" : { "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { + "$ref" : "#/components/schemas/ReferenceView" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + "$ref" : "#/components/schemas/ForbiddenError" + } } - }, + } + }, + "404" : { + "description" : "An expected data was not found", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" + "$ref" : "#/components/schemas/NotFoundError" } - }, - "*/*" : { + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { "schema" : { - "type" : "string", - "format" : "binary" + "$ref" : "#/components/schemas/Error" } } } + } + } + }, + "put" : { + "operationId" : "updateReference", + "summary" : "Updates an existing reference.", + "description" : "Updates an existing reference.", + "tags" : [ "References" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "responses" : { + "204" : { + "description" : "The reference is updated and nothing is returned." }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -28115,6 +39313,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -28127,75 +39335,115 @@ } }, "requestBody" : { - "description" : "The custom operation parameters", + "description" : "The reference details", + "required" : true, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RunOperation" + "$ref" : "#/components/schemas/ReferenceSet" } } } } - } - }, - "/contact-infos/{id}/operations/{operation}/run-upload" : { - "post" : { - "operationId" : "runContactInfoOperationWithUpload", - "summary" : "Runs a custom operation over an additional contact information while uploading a file", - "description" : "Runs a specific custom operation over a given additional contact information. The operation scope must be `contactInfo`. This path allows uploading a file, by using a `multipart-form-data` post. If the operation resulted in a file download (either because the `resultType` is `fileDownload` or is a `resultPage` running for either PDF or CSV) the resulting contente type will be of the file itself. Otherwise will result in an `application/json` with the result object.", - "tags" : [ "Operations" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" + }, + "delete" : { + "operationId" : "deleteReference", + "summary" : "Removes a reference", + "description" : "Removes a reference", + "tags" : [ "References" ], + "security" : [ { + "basic" : [ ] }, { - "$ref" : "#/components/parameters/id" + "session" : [ ] }, { - "name" : "operation", - "description" : "Either the id or internal name of the custom operation", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/id" } ], "responses" : { - "200" : { - "description" : "The custom operation result, either as `RunOperationResult` or as the file itself", - "headers" : { - "X-Total-Count" : { + "204" : { + "description" : "The reference was deleted" + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", + "content" : { + "application/json" : { "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { + "$ref" : "#/components/schemas/ConflictError" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + "$ref" : "#/components/schemas/NotFoundError" + } } - }, + } + }, + "500" : { + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RunOperationResult" + "$ref" : "#/components/schemas/Error" } - }, - "*/*" : { + } + } + } + } + } + }, + "/references/{id}/data-for-edit" : { + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], + "get" : { + "operationId" : "getReferenceDataForEdit", + "summary" : "Returns data to edit an existing reference.", + "description" : "Returns configuration data for editing a reference, plus the current `ReferenceSet` object that can be altered and sent back.", + "tags" : [ "References" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], + "responses" : { + "200" : { + "description" : "The data for editing a reference", + "content" : { + "application/json" : { "schema" : { - "type" : "string", - "format" : "binary" + "$ref" : "#/components/schemas/ReferenceDataForSet" } } } @@ -28240,28 +39488,6 @@ } } } - }, - "requestBody" : { - "content" : { - "multipart/form-data" : { - "schema" : { - "type" : "object", - "properties" : { - "params" : { - "description" : "The custom operation parameters.", - "allOf" : [ { - "$ref" : "#/components/schemas/RunOperation" - } ] - }, - "file" : { - "type" : "string", - "format" : "binary", - "description" : "The file being uploaded" - } - } - } - } - } } } }, @@ -28371,7 +39597,6 @@ "in" : "query", "required" : false, "description" : "Either ids or an identifications, such as login name, e-mail, etc, for the brokers of the advertisement owner. Can only be used when searching with a broker himself or admin.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -28400,7 +39625,6 @@ "in" : "query", "required" : false, "description" : "Advertisement custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=tradeType:offer|search,extraDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `tradeType` is either `offer` or `search`, and whose `extraDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=extraDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `customFields=dynamic:'business`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -28413,7 +39637,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum expiration date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -28427,7 +39650,6 @@ "in" : "query", "required" : false, "description" : "Array of either id or internal names of user groups the advertisement owner must belong to", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -28522,8 +39744,7 @@ "name" : "priceRange", "in" : "query", "required" : false, - "description" : "The minumum / maximum price. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", + "description" : "The minumum / maximum price. Used only if a currency is specified. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", "schema" : { "type" : "array", "items" : { @@ -28532,12 +39753,19 @@ "format" : "number" } } + }, { + "name" : "productNumber", + "in" : "query", + "required" : false, + "description" : "Textual search for a product number for webshop only.", + "schema" : { + "type" : "string" + } }, { "name" : "profileFields", "in" : "query", "required" : false, "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -28550,7 +39778,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum publication date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -28567,12 +39794,19 @@ "schema" : { "type" : "boolean" } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } }, { "name" : "statuses", "in" : "query", "required" : false, "description" : "", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -28746,6 +39980,14 @@ "$ref" : "#/components/parameters/fields" }, { "$ref" : "#/components/parameters/user" + }, { + "name" : "basedOnId", + "in" : "query", + "required" : false, + "description" : "Indicates the advertisement id to be based on by copying some data (e.g publication period) to the new advertisement.", + "schema" : { + "type" : "string" + } }, { "name" : "kind", "in" : "query", @@ -28844,7 +40086,6 @@ "in" : "query", "required" : false, "description" : "Advertisement custom field values used as filters. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by : (colon). For example, `customFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, customFields=field1:valueA|valueB. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `customFields=tradeType:offer|search,extraDate:2000-01-01|2001-12-31` would match results whose custom field with internal name `tradeType` is either `offer` or `search`, and whose `extraDate` is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `customFields=extraDate:|2001-12-31`. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `customFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `customFields=dynamic:'business`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -28857,7 +40098,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum expiration date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -28945,8 +40185,7 @@ "name" : "priceRange", "in" : "query", "required" : false, - "description" : "The minumum / maximum price. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", + "description" : "The minumum / maximum price. Used only if a currency is specified. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", "schema" : { "type" : "array", "items" : { @@ -28955,12 +40194,19 @@ "format" : "number" } } + }, { + "name" : "productNumber", + "in" : "query", + "required" : false, + "description" : "Textual search for a product number for webshop only.", + "schema" : { + "type" : "string" + } }, { "name" : "profileFields", "in" : "query", "required" : false, "description" : "User profile fields, both basic (full name, login name, phone, e-mail, etc) and custom fields, that are used for search. Is a comma-separated array, where each part consists in two parts: the internal name (or custom field id) of the field, and a value, both separated by `:` (colon). For example, `profileFields=field1:value1,field2:value2`. Sometimes multiple values are accepted. In this case, the multiple values are separated by pipes. For example, `profileFields=field1:valueA|valueB`. The accepted fields depend on the products the authenticated user has. Enumerated fields accept multiple values, while numeric and date fields also accept ranges, which are two values, pipe-separated. For example, `profileFields=rank:bronze|silver,birthDate:2000-01-01|2001-12-31` would match results whose custom field with internal name 'rank' is either bronze or silver, and whose 'birthDate' is between January 1, 2000 and December 31, 2001. To specify a single bound in ranges (like birth dates before December 31, 2001), use a pipe in one of the values, like `profileFields=birthDate:|2001-12-31`.\nThe basic profile fields have one of the following identifiers:\n- `name` or `fullName`: Full name; - `username`, `loginName` or `login`: Login name; - `email`: E-mail; - `phone`: Phone; - `accountNumber`, `account`: Account number; - `image`: Image (accepts a boolean value, indicating that either it is required that users either have images or not).\n\nIf address is an allowed profile field for search, specific address fields may be searched. The allowed ones are normally returned as the `addressFieldsInSearch` field in the corresponding result from a data-for-search request. The specific address fields are:\n- `address`: Searches on any address field (not a specific field); - `address.address`: Searches on the fields that represent the street address, which are `addressLine1`, `addressLine2`, `street`, `buildingNumber` and `complement`. Note that normally only a subset of them should be enabled in the configuration (either line 1 / 2 or street + number + complement);\n- `address.zip`: Searches for matching zip (postal) code; - `address.poBox`: Searches for matching postal box; - `address.neighborhood`: Searches by neighborhood; - `address.city`: Searches by city; - `address.region`: Searches by region (or state); - `address.country`: Searches by ISO 3166-1 alpha-2 country code. A note for dynamic custom fields: If a script is used to generate possible values for search, the list will be returned in the corresponding data, and it is sent as a pipe-separated list of values (not labels). For example: `profileFields=dynamic:a|b|c`. However, it is also possible to perform a keywords-like (full-text) search using the dynamic value label. In this case a single value, prefixed by single quotes should be used. For example: `profileFields=dynamic:'business`.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -28973,7 +40219,6 @@ "in" : "query", "required" : false, "description" : "The minimum / maximum publication date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -28982,12 +40227,19 @@ "format" : "date-time" } } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } }, { "name" : "statuses", "in" : "query", "required" : false, "description" : "", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -29462,33 +40714,18 @@ } } }, - "/marketplace/{ad}/questions" : { + "/marketplace/{ad}/hide" : { "post" : { - "operationId" : "createAdQuestion", - "summary" : "Creates a new advertisement question.", - "description" : "Creates a new question for an advertisement and associate it to the authenticated user.", + "operationId" : "hideAd", + "summary" : "Hides an advertisement by id.", + "description" : "Hides an advertisement thus making it visible only for the owner and its managers.", "tags" : [ "Marketplace" ], "parameters" : [ { "$ref" : "#/components/parameters/ad" } ], "responses" : { - "201" : { - "description" : "Returns the identifier of the new question.", - "headers" : { - "Location" : { - "description" : "URL for viewing the advertisement question details.", - "schema" : { - "type" : "string" - } - } - }, - "content" : { - "text/plain" : { - "schema" : { - "type" : "string" - } - } - } + "204" : { + "description" : "The advertisement was hidden." }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -29520,16 +40757,6 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { "description" : "Unexpected error", "content" : { @@ -29540,47 +40767,77 @@ } } } - }, - "requestBody" : { - "required" : true, - "content" : { - "text/plain" : { - "schema" : { - "type" : "string" - } - } - } } } }, - "/questions/{id}" : { - "get" : { - "operationId" : "getAdQuestion", - "summary" : "Returns details of an advertisement question.", - "description" : "Return detailed information of an advertisement question.", + "/marketplace/{ad}/unhide" : { + "post" : { + "operationId" : "unhideAd", + "summary" : "Unhides an advertisement by id.", + "description" : "Unhides an advertisement thus making it visible for other members.", "tags" : [ "Marketplace" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/id" + "$ref" : "#/components/parameters/ad" } ], "responses" : { - "200" : { - "description" : "Returns the advertisement question information.", + "204" : { + "description" : "The advertisement was unhidden." + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/AdQuestionView" + "$ref" : "#/components/schemas/Error" } } } + } + } + } + }, + "/marketplace/{ad}/set-as-draft" : { + "post" : { + "operationId" : "setAdAsDraft", + "summary" : "Change the advertisement status to `draft`.", + "description" : "Change the advertisement status to `draft` thus making it only visible for the owner.", + "tags" : [ "Marketplace" ], + "parameters" : [ { + "$ref" : "#/components/parameters/ad" + } ], + "responses" : { + "204" : { + "description" : "The advertisement status was changed." }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -29622,36 +40879,32 @@ } } } + }, + "requestBody" : { + "description" : "The comments for the action. Only if the authenticated user is a manager of the advertisement's owner with permissions to manage pending ads.", + "required" : false, + "content" : { + "text/plain" : { + "schema" : { + "type" : "string" + } + } + } } - }, - "delete" : { - "operationId" : "deleteAdQuestion", - "summary" : "Removes an advertisement question.", - "description" : "Removes an advertisement question created for the authenticated user.", + } + }, + "/marketplace/{ad}/request-authorization" : { + "post" : { + "operationId" : "submitAdForAuthorization", + "summary" : "Request for authorization for an advertisement.", + "description" : "Request for authorization for an advertisement. Only if the system is configured to require authorizations and the authenticated user is the owner of the advertisement. The advertisement will remain in status `pending` until approved or rejected.", "tags" : [ "Marketplace" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], "parameters" : [ { - "$ref" : "#/components/parameters/id" + "$ref" : "#/components/parameters/ad" } ], "responses" : { "204" : { - "description" : "The advertisement question was removed." - }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ConflictError" - } - } - } + "description" : "The advertisement was submitted for authorization." }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -29696,35 +40949,18 @@ } } }, - "/shopping-carts" : { - "get" : { - "operationId" : "getShoppingCarts", - "summary" : "Returns the shopping carts list.", - "description" : "Returns the shopping carts for the authenticated user. Each cart contains all webshop ads offered by the same seller and in the same currency.", + "/marketplace/{ad}/approve" : { + "post" : { + "operationId" : "approveAd", + "summary" : "Approves a pending advertisement.", + "description" : "Change the advertisement status from `pending` to `active`, making it publcly visible.", "tags" : [ "Marketplace" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "$ref" : "#/components/parameters/ad" } ], "responses" : { - "200" : { - "description" : "The shopping carts list.", - "content" : { - "application/json" : { - "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/ShoppingCartResult" - } - } - } - } + "204" : { + "description" : "The advertisement status was changed." }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -29769,34 +41005,18 @@ } } }, - "/shopping-carts/{id}" : { - "get" : { - "operationId" : "getShoppingCartDetails", - "summary" : "Returns details of a shopping cart.", - "description" : "Returns the details of a shopping cart by id with all webshop ads offered by the same seller and in the same currency.", + "/marketplace/{ad}/reject" : { + "post" : { + "operationId" : "rejectAd", + "summary" : "Rejects a pending advertisement.", + "description" : "Change the advertisement status from `pending` to `draft`, making it visible only to its owner. A comment text is set in the request body.", "tags" : [ "Marketplace" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/id" + "$ref" : "#/components/parameters/ad" } ], "responses" : { - "200" : { - "description" : "The shopping cart details.", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ShoppingCartView" - } - } - } + "204" : { + "description" : "The advertisement status was changed." }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -29838,40 +41058,44 @@ } } } + }, + "requestBody" : { + "description" : "The comments for the action.", + "required" : false, + "content" : { + "text/plain" : { + "schema" : { + "type" : "string" + } + } + } } - }, - "delete" : { - "operationId" : "removeShoppingCart", - "summary" : "Removes a shopping cart.", - "description" : "Removes the given shopping cart by id and returns the total number of the webshop ads in the remaining all carts.", - "tags" : [ "Marketplace" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + } + }, + "/marketplace/{ad}/questions" : { + "post" : { + "operationId" : "createAdQuestion", + "summary" : "Creates a new advertisement question.", + "description" : "Creates a new question for an advertisement and associate it to the authenticated user.", + "tags" : [ "AdQuestions" ], "parameters" : [ { - "$ref" : "#/components/parameters/id" + "$ref" : "#/components/parameters/ad" } ], "responses" : { - "200" : { - "description" : "The shopping cart was removed. Returns the total number of the webshop ads in all the remaining shopping carts.", - "content" : { - "application/json" : { + "201" : { + "description" : "Returns the identifier of the new question.", + "headers" : { + "Location" : { + "description" : "URL for viewing the advertisement question details.", "schema" : { - "type" : "integer" + "type" : "string" } } - } - }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", + }, "content" : { - "application/json" : { + "text/plain" : { "schema" : { - "$ref" : "#/components/schemas/ConflictError" + "type" : "string" } } } @@ -29906,6 +41130,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -29916,15 +41150,25 @@ } } } + }, + "requestBody" : { + "required" : true, + "content" : { + "text/plain" : { + "schema" : { + "type" : "string" + } + } + } } } }, - "/shopping-carts/{id}/adjust" : { - "post" : { - "operationId" : "adjustAndGetShoppingCartDetails", - "summary" : "Adjusts a shopping cart items, returning its details.", - "description" : "Works like `GET /shopping-carts/{id}`, but first adjusts the status of all items. For each item checks both the availability and the quantity, setting to corresponding `availability` or `quantityAdjustment` property if anything was modified.", - "tags" : [ "Marketplace" ], + "/questions/{id}" : { + "get" : { + "operationId" : "getAdQuestion", + "summary" : "Returns details of an advertisement question.", + "description" : "Return detailed information of an advertisement question.", + "tags" : [ "AdQuestions" ], "security" : [ { "basic" : [ ] }, { @@ -29939,11 +41183,11 @@ } ], "responses" : { "200" : { - "description" : "The shopping cart details.", + "description" : "Returns the advertisement question information.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ShoppingCartView" + "$ref" : "#/components/schemas/AdQuestionView" } } } @@ -29989,14 +41233,12 @@ } } } - } - }, - "/shopping-carts/items/{ad}" : { - "post" : { - "operationId" : "addItemToShoppingCart", - "summary" : "Adds the given webshop ad to the corresponding shopping cart.", - "description" : "Adds the given webshop ad to the corresponding shopping cart according to the seller and currency and returns the total number of webshop ads in all carts. Optionally a quantity can be specified. The different shopping carts are created dynamically according to the seller and currency.\nE.g if the user adds the following webshop ads (i.e items):\n- 1 from Seller1 in Dolars;\n- 2 from Seller1 in Euros;\n- 1 from Seller2 un Dolars.\n\nThen the following three carts will be created for the authenticated user:\n\n- 1 cart containing 1 item offered by Seller1 in Dolars;\n- 1 cart containing 2 items offered by Seller1 in Euros;\n- 1 cart containing 1 item offered by Seller2 in Dolars.\n\nFinally, the total number of wbshop ads returned will be 4. For those quantity-limited products the given quantity could have been adjusted to meet the restrictions. You can view the adjustment applied to each item when retrieving the details of a shopping cart. if you want to remove the adjustment just send a new request to modify the quantity (using `PUT /shopping-carts/items/{ad}`) and specify the current quantity (i.e the already adjusted and returned in the details of the shopping cart) as the parameter.", - "tags" : [ "Marketplace" ], + }, + "delete" : { + "operationId" : "deleteAdQuestion", + "summary" : "Removes an advertisement question.", + "description" : "Removes an advertisement question created for the authenticated user.", + "tags" : [ "AdQuestions" ], "security" : [ { "basic" : [ ] }, { @@ -30005,24 +41247,18 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/ad" - }, { - "name" : "quantity", - "in" : "query", - "required" : false, - "description" : "The quantity being added. It could be a decimal number only if the corresponding webshop ad allows it.", - "schema" : { - "type" : "number", - "format" : "double" - } + "$ref" : "#/components/parameters/id" } ], "responses" : { - "200" : { - "description" : "Returns the total number of webshop ads present in all the shopping carts.", + "204" : { + "description" : "The advertisement question was removed." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", "content" : { "application/json" : { "schema" : { - "type" : "integer" + "$ref" : "#/components/schemas/ConflictError" } } } @@ -30058,52 +41294,30 @@ } }, "500" : { - "description" : "If an error has occurred adding the webshop ad to the cart.", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ShoppingCartError" + "$ref" : "#/components/schemas/Error" } } } } } - }, - "delete" : { - "operationId" : "removeItemFromShoppingCart", - "summary" : "Removes the given webshop ad from the corresponding shopping cart.", - "description" : "Removes the given webshop ad from the corresponding shopping cart according to the seller and currency and returns the total number of the remaining webshop ads in all carts.", - "tags" : [ "Marketplace" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], + } + }, + "/questions/{id}/answer" : { + "post" : { + "operationId" : "answerAdQuestion", + "summary" : "Answers an advertisement question as the authenticated user.", + "description" : "Answers a question by id (created for an advertisement of its own).", + "tags" : [ "AdQuestions" ], "parameters" : [ { - "$ref" : "#/components/parameters/ad" + "$ref" : "#/components/parameters/id" } ], "responses" : { - "200" : { - "description" : "The webshop ad was removed from the shopping cart. Returns the total number of the remaining webshop ads in all the shopping carts.", - "content" : { - "application/json" : { - "schema" : { - "type" : "integer" - } - } - } - }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ConflictError" - } - } - } + "204" : { + "description" : "The question was answered." }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -30135,6 +41349,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -30145,13 +41369,25 @@ } } } + }, + "requestBody" : { + "required" : true, + "content" : { + "text/plain" : { + "schema" : { + "type" : "string" + } + } + } } - }, - "put" : { - "operationId" : "modifyItemQuantityOnShoppingCart", - "summary" : "Modifies the corresponding cart with the new quantity for the given webshop ad.", - "description" : "Modifies the corresponding shopping cart with the new quantity for the given webshop ad only if it was already added to the cart of the authenticted user and returns the total number of webshop ads in all carts. For those quantity-limited products the given quantity could have been adjusted to met the restrictions. You can view the adjustment applied to each item when retrieving the details of a shopping cart. if you want to remove the adjustment just send a new request to modify the quantity and specify the current quantity (i.e the already adjusted and returned in the details of the shopping cart) as the parameter.", - "tags" : [ "Marketplace" ], + } + }, + "/{user}/unanswered-questions" : { + "get" : { + "operationId" : "searchUnansweredAdQuestions", + "summary" : "Searches for unanswered questions for a specific user", + "description" : "Searches for unanswered questions for a specific user, if a type is not given then `simple` will be used. Only if the user has the ad questions enabled or can manage webshops and the authenticated user can manage ads / webshops of the given user.", + "tags" : [ "AdQuestions" ], "security" : [ { "basic" : [ ] }, { @@ -30160,24 +41396,53 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/ad" + "$ref" : "#/components/parameters/fields" }, { - "name" : "quantity", + "$ref" : "#/components/parameters/user" + }, { + "name" : "kind", "in" : "query", - "required" : true, - "description" : "The new quantity for the given webshop ad. It could be a decimal number only if the corresponding webshop ad allows it. If zero then the webshop ad is removed from the cart.", + "required" : false, "schema" : { - "type" : "number", - "format" : "double" + "$ref" : "#/components/schemas/AdKind" + } + }, { + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" } } ], "responses" : { "200" : { - "description" : "The quantity for the given webshop was updated. Returns the total number of webshop ads present in all the shopping carts.", + "description" : "Returns the unanswered questions.", "content" : { "application/json" : { "schema" : { - "type" : "integer" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/AdQuestion" + } } } } @@ -30212,22 +41477,12 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { - "description" : "If an error has occurred modifying the quantity.", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ShoppingCartError" + "$ref" : "#/components/schemas/Error" } } } @@ -30235,12 +41490,12 @@ } } }, - "/shopping-carts/{id}/data-for-checkout" : { + "/shopping-carts" : { "get" : { - "operationId" : "getShoppingCartDataForCheckout", - "summary" : "Returns configuration data for check-out a shopping cart.", - "description" : "Returns configuration data for check-out the given shopping cart by id.", - "tags" : [ "Marketplace" ], + "operationId" : "getShoppingCarts", + "summary" : "Returns the shopping carts list.", + "description" : "Returns the shopping carts for the authenticated user. Each cart contains all webshop ads offered by the same seller and in the same currency.", + "tags" : [ "ShoppingCarts" ], "security" : [ { "basic" : [ ] }, { @@ -30250,16 +41505,17 @@ } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/id" } ], "responses" : { "200" : { - "description" : "The configuration data for check-out.", + "description" : "The shopping carts list.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ShoppingCartDataForCheckout" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ShoppingCartResult" + } } } } @@ -30307,12 +41563,12 @@ } } }, - "/shopping-carts/{id}/checkout" : { - "post" : { - "operationId" : "checkoutShoppingCart", - "summary" : "Checks out a shopping cart.", - "description" : "Checks out the given shopping cart associated to the authenticated user. After the check-out the purchase order will be awaiting for the seller's acceptance (i. e with status `pendingSeller`).", - "tags" : [ "Marketplace" ], + "/shopping-carts/{id}" : { + "get" : { + "operationId" : "getShoppingCartDetails", + "summary" : "Returns details of a shopping cart.", + "description" : "Returns the details of a shopping cart by id with all webshop ads offered by the same seller and in the same currency.", + "tags" : [ "ShoppingCarts" ], "security" : [ { "basic" : [ ] }, { @@ -30321,25 +41577,17 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/id" + "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/confirmationPassword" + "$ref" : "#/components/parameters/id" } ], "responses" : { "200" : { - "description" : "The shopping cart was cheked out. Returns the total number of the webshop ads in all the remaining shopping carts. The id of the purchase order is not returned because is the same as the id of the given shopping cart but a header with the url to view the details does.", - "headers" : { - "Location" : { - "description" : "URL for viewing the order details.", - "schema" : { - "type" : "string" - } - } - }, + "description" : "The shopping cart details.", "content" : { "application/json" : { "schema" : { - "type" : "integer" + "$ref" : "#/components/schemas/ShoppingCartView" } } } @@ -30374,46 +41622,23 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { - "description" : "If an error has occurred in the check-out process.", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ShoppingCartCheckoutError" + "$ref" : "#/components/schemas/Error" } } } } - }, - "requestBody" : { - "description" : "The data for check-out.", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/ShoppingCartCheckout" - } - } - } } - } - }, - "/{user}/orders" : { - "get" : { - "operationId" : "searchUserOrders", - "summary" : "Searches for orders of a specific user.", - "description" : "Returns a page of orders that match a given criteria for a given user. The authenticated user must be the seller, buyer or a manager user with permission to view purchases or sales. A list of statuses is accepted but at this moment only one status can be specified.", - "tags" : [ "Marketplace" ], + }, + "delete" : { + "operationId" : "removeShoppingCart", + "summary" : "Removes a shopping cart.", + "description" : "Removes the given shopping cart by id and returns the total number of the webshop ads in the remaining all carts.", + "tags" : [ "ShoppingCarts" ], "security" : [ { "basic" : [ ] }, { @@ -30421,115 +41646,26 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/user" - }, { - "name" : "creationPeriod", - "in" : "query", - "required" : false, - "description" : "The minimum / maximum order creation date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string", - "format" : "date-time" - } - } - }, { - "name" : "number", - "in" : "query", - "required" : false, - "description" : "The generated order number according to the webshop settings.", - "schema" : { - "type" : "string" - } - }, { - "name" : "page", - "in" : "query", - "required" : false, - "description" : "The page number (zero-based) of the search. The default value is zero.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - }, { - "name" : "pageSize", - "in" : "query", - "required" : false, - "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - }, { - "name" : "relatedUser", - "in" : "query", - "required" : false, - "description" : "Either id or an identification, such as login name, e-mail, etc, for the seller or buyer according whether we are searching for purchases or sales. The allowed identification methods are those the authenticated user can use on keywords search.", - "schema" : { - "type" : "string" - } - }, { - "name" : "sales", - "in" : "query", - "required" : false, - "description" : "Are we searching for sales or purchases? If not specified it's assumed purchases (i.e `false`)", - "schema" : { - "type" : "boolean" - } - }, { - "name" : "statuses", - "in" : "query", - "required" : false, - "description" : "", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/OrderStatusEnum" - } - } - } ], + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], "responses" : { "200" : { - "description" : "The orders matching the criteria.", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { + "description" : "The shopping cart was removed. Returns the total number of the webshop ads in all the remaining shopping carts.", + "content" : { + "application/json" : { "schema" : { "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } } - }, + } + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/UserOrderResult" - } + "$ref" : "#/components/schemas/ConflictError" } } } @@ -30577,12 +41713,12 @@ } } }, - "/orders/{order}" : { - "get" : { - "operationId" : "viewOrder", - "summary" : "Returns details of an order.", - "description" : "Returns detailed information of an order given by id.", - "tags" : [ "Marketplace" ], + "/shopping-carts/{id}/adjust" : { + "post" : { + "operationId" : "adjustAndGetShoppingCartDetails", + "summary" : "Adjusts a shopping cart items, returning its details.", + "description" : "Works like `GET /shopping-carts/{id}`, but first adjusts the status of all items. For each item checks both the availability and the quantity, setting to corresponding `availability` or `quantityAdjustment` property if anything was modified.", + "tags" : [ "ShoppingCarts" ], "security" : [ { "basic" : [ ] }, { @@ -30593,15 +41729,15 @@ "parameters" : [ { "$ref" : "#/components/parameters/fields" }, { - "$ref" : "#/components/parameters/order" + "$ref" : "#/components/parameters/id" } ], "responses" : { "200" : { - "description" : "The order details.", + "description" : "The shopping cart details.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/OrderView" + "$ref" : "#/components/schemas/ShoppingCartView" } } } @@ -30649,12 +41785,12 @@ } } }, - "/orders/{order}/seller/data-for-set-delivery" : { - "get" : { - "operationId" : "getDataForSetDeliveryMethod", - "summary" : "Returns configuration data to set delivery method data by seller.", - "description" : "Returns configuration data to set delivery method data by seller of an order given by id.", - "tags" : [ "Marketplace" ], + "/shopping-carts/items/{ad}" : { + "post" : { + "operationId" : "addItemToShoppingCart", + "summary" : "Adds the given webshop ad to the corresponding shopping cart.", + "description" : "Adds the given webshop ad to the corresponding shopping cart according to the seller and currency and returns the total number of webshop ads in all carts. Optionally a quantity can be specified. The different shopping carts are created dynamically according to the seller and currency.\nE.g if the user adds the following webshop ads (i.e items):\n- 1 from Seller1 in Dolars;\n- 2 from Seller1 in Euros;\n- 1 from Seller2 un Dolars.\n\nThen the following three carts will be created for the authenticated user:\n\n- 1 cart containing 1 item offered by Seller1 in Dolars;\n- 1 cart containing 2 items offered by Seller1 in Euros;\n- 1 cart containing 1 item offered by Seller2 in Dolars.\n\nFinally, the total number of wbshop ads returned will be 4. For those quantity-limited products the given quantity could have been adjusted to meet the restrictions. You can view the adjustment applied to each item when retrieving the details of a shopping cart. if you want to remove the adjustment just send a new request to modify the quantity (using `PUT /shopping-carts/items/{ad}`) and specify the current quantity (i.e the already adjusted and returned in the details of the shopping cart) as the parameter.", + "tags" : [ "ShoppingCarts" ], "security" : [ { "basic" : [ ] }, { @@ -30663,84 +41799,75 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" + "$ref" : "#/components/parameters/ad" }, { - "$ref" : "#/components/parameters/order" + "name" : "quantity", + "in" : "query", + "required" : false, + "description" : "The quantity being added. It could be a decimal number only if the corresponding webshop ad allows it.", + "schema" : { + "type" : "number", + "format" : "double" + } } ], "responses" : { "200" : { - "description" : "The configuration data for set he delivery method.", + "description" : "Returns the total number of webshop ads present in all the shopping carts.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/OrderDataForSetDeliveryMethod" + "type" : "integer" } } } }, - "500" : { - "description" : "If a payment error has occurred", + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentError" + "$ref" : "#/components/schemas/UnauthorizedError" } } } - } - } - } - }, - "/orders/{order}/seller/set-delivery" : { - "post" : { - "operationId" : "setDeliveryMethod", - "summary" : "Sets delivery method data by seller.", - "description" : "Sets the delivery method data by seller for the order given by id. This operation can be used only if the order is in status `pendingSeller` and has not already set delivery method data. After the delivery method has been set the order will be enter in status `pendingBuyer` to be accepted by buyer.", - "tags" : [ "Marketplace" ], - "security" : [ { - "basic" : [ ] - }, { - "session" : [ ] - }, { - "accessClient" : [ ] - } ], - "parameters" : [ { - "$ref" : "#/components/parameters/order" - } ], - "responses" : { - "204" : { - "description" : "The delivery method was set by seller. Nothing is returned." }, - "500" : { - "description" : "If a payment error has occurred", + "403" : { + "description" : "Permission denied for such operation", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentError" + "$ref" : "#/components/schemas/ForbiddenError" } } } - } - }, - "requestBody" : { - "description" : "The parameters for setting the delivery method.", - "required" : false, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/SetDeliveryMethod" + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "If an error has occurred adding the webshop ad to the cart.", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ShoppingCartError" + } } } } } - } - }, - "/orders/{order}/buyer/data-for-accept" : { - "get" : { - "operationId" : "getOrderDataForAcceptByBuyer", - "summary" : "Returns configuration data for accept an order by buyer.", - "description" : "Returns configuration data for accept an order given by id as the buyer.", - "tags" : [ "Marketplace" ], + }, + "delete" : { + "operationId" : "removeItemFromShoppingCart", + "summary" : "Removes the given webshop ad from the corresponding shopping cart.", + "description" : "Removes the given webshop ad from the corresponding shopping cart according to the seller and currency and returns the total number of the remaining webshop ads in all carts.", + "tags" : [ "ShoppingCarts" ], "security" : [ { "basic" : [ ] }, { @@ -30749,17 +41876,25 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "$ref" : "#/components/parameters/order" + "$ref" : "#/components/parameters/ad" } ], "responses" : { "200" : { - "description" : "The configuration data for accept the order as the buyer.", + "description" : "The webshop ad was removed from the shopping cart. Returns the total number of the remaining webshop ads in all the shopping carts.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/OrderDataForAcceptByBuyer" + "type" : "integer" + } + } + } + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConflictError" } } } @@ -30805,14 +41940,12 @@ } } } - } - }, - "/orders/{order}/buyer/accept" : { - "post" : { - "operationId" : "acceptOrderByBuyer", - "summary" : "Accepts a pending order by buyer.", - "description" : "Accepts a pending order by buyer generating the corresponding payment. The order status must be `pendingBuyer` to be accepted by the authenticated user (i.e the buyer).\nThe `paymentType` and the `confirmationPassword` are required under the following circumstances:\n`paymentType`: Only required if the order was generated as a sale by the seller and not from the shopping cart check-out (Sales are not supported yet).\n`confirmationPassword`: Only required if at check-out a delivery method was not set or its charge type is `negotiatied`.\nThe possible statuses after an order acceptance are: - `paymentPending`: if the generated payment is awaiting authorization; - `completed`: if the payment was done.", - "tags" : [ "Marketplace" ], + }, + "put" : { + "operationId" : "modifyItemQuantityOnShoppingCart", + "summary" : "Modifies the corresponding cart with the new quantity for the given webshop ad.", + "description" : "Modifies the corresponding shopping cart with the new quantity for the given webshop ad only if it was already added to the cart of the authenticted user and returns the total number of webshop ads in all carts. For those quantity-limited products the given quantity could have been adjusted to met the restrictions. You can view the adjustment applied to each item when retrieving the details of a shopping cart. if you want to remove the adjustment just send a new request to modify the quantity and specify the current quantity (i.e the already adjusted and returned in the details of the shopping cart) as the parameter.", + "tags" : [ "ShoppingCarts" ], "security" : [ { "basic" : [ ] }, { @@ -30821,44 +41954,87 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/order" + "$ref" : "#/components/parameters/ad" }, { - "$ref" : "#/components/parameters/confirmationPassword" + "name" : "quantity", + "in" : "query", + "required" : true, + "description" : "The new quantity for the given webshop ad. It could be a decimal number only if the corresponding webshop ad allows it. If zero then the webshop ad is removed from the cart.", + "schema" : { + "type" : "number", + "format" : "double" + } } ], "responses" : { - "204" : { - "description" : "The order was accepted by the buyer. Nothing is returned." + "200" : { + "description" : "The quantity for the given webshop was updated. Returns the total number of webshop ads present in all the shopping carts.", + "content" : { + "application/json" : { + "schema" : { + "type" : "integer" + } + } + } }, - "500" : { - "description" : "If a payment error has occurred", + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentError" + "$ref" : "#/components/schemas/UnauthorizedError" } } } - } - }, - "requestBody" : { - "description" : "The parameters for accepting the order.", - "required" : false, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/AcceptOrderByBuyer" + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "If an error has occurred modifying the quantity.", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ShoppingCartError" + } } } } } } }, - "/orders/{order}/seller/accept" : { - "post" : { - "operationId" : "acceptOrderBySeller", - "summary" : "Accepts a pending order by seller.", - "description" : "Accepts a pending order by seller generating the corresponding payment. The order status must be `pendingSeller` to be accepted by the authenticated user (i.e seller). The possible statuses after order acceptance are:\n- `paymentPending`: if the generated payment is awaiting for authorization; - `completed`: if the payment was done.", - "tags" : [ "Marketplace" ], + "/shopping-carts/{id}/data-for-checkout" : { + "get" : { + "operationId" : "getShoppingCartDataForCheckout", + "summary" : "Returns configuration data for check-out a shopping cart.", + "description" : "Returns configuration data for check-out the given shopping cart by id.", + "tags" : [ "ShoppingCarts" ], "security" : [ { "basic" : [ ] }, { @@ -30867,42 +42043,70 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/order" + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/id" } ], "responses" : { - "204" : { - "description" : "The order was accepted by seller. Nothing is returned." + "200" : { + "description" : "The configuration data for check-out.", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ShoppingCartDataForCheckout" + } + } + } }, - "500" : { - "description" : "If a payment error has occurred", + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PaymentError" + "$ref" : "#/components/schemas/UnauthorizedError" } } } - } - }, - "requestBody" : { - "description" : "The parameters for accepting the order.", - "required" : false, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/AcceptOrderBySeller" + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } } } } } } }, - "/orders/{order}/reject" : { + "/shopping-carts/{id}/checkout" : { "post" : { - "operationId" : "rejectOrder", - "summary" : "Rejects a pending order.", - "description" : "Rejects a pending order by buyer or seller. The order status must be `pendingBuyer` or `pendingSeller` to be rejected by the authenticated user (buyer/seller). The possible statuses after an order rejection are:\n- `rejectedBySeller`: if the authenticated user is the seller; - `rejectedByBuyer`: if the authenticated user is the buyer.", - "tags" : [ "Marketplace" ], + "operationId" : "checkoutShoppingCart", + "summary" : "Checks out a shopping cart.", + "description" : "Checks out the given shopping cart associated to the authenticated user. After the check-out the purchase order will be awaiting for the seller's acceptance (i. e with status `pendingSeller`).", + "tags" : [ "ShoppingCarts" ], "security" : [ { "basic" : [ ] }, { @@ -30911,11 +42115,28 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/order" + "$ref" : "#/components/parameters/id" + }, { + "$ref" : "#/components/parameters/confirmationPassword" } ], "responses" : { - "204" : { - "description" : "The order was rejected by the authenticated user. Nothing is returned." + "200" : { + "description" : "The shopping cart was cheked out. Returns the total number of the webshop ads in all the remaining shopping carts. The id of the purchase order is not returned because is the same as the id of the given shopping cart but a header with the url to view the details does.", + "headers" : { + "Location" : { + "description" : "URL for viewing the order details.", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "application/json" : { + "schema" : { + "type" : "integer" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -30958,35 +42179,35 @@ } }, "500" : { - "description" : "Unexpected error", + "description" : "If an error has occurred in the check-out process.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Error" + "$ref" : "#/components/schemas/ShoppingCartCheckoutError" } } } } }, "requestBody" : { - "description" : "The parameters for rejecting the order.", - "required" : false, + "description" : "The data for check-out.", + "required" : true, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/RejectOrder" + "$ref" : "#/components/schemas/ShoppingCartCheckout" } } } } } }, - "/nfc/{tokenType}/{value}" : { + "/{user}/orders" : { "get" : { - "operationId" : "getNfcToken", - "summary" : "Retrieve the NFC token detailed data", - "description" : "Returns the token's data and the user owner of the token (i.e the assigned user, if any)", - "tags" : [ "NFC" ], + "operationId" : "searchUserOrders", + "summary" : "Searches for orders of a specific user.", + "description" : "Returns a page of orders that match a given criteria for a given user. The authenticated user must be the seller, buyer or a manager user with permission to view purchases or sales. A list of statuses is accepted but at this moment only one status can be specified.", + "tags" : [ "Orders" ], "security" : [ { "basic" : [ ] }, { @@ -30995,29 +42216,128 @@ "accessClient" : [ ] } ], "parameters" : [ { - "name" : "tokenType", - "description" : "The internal name or id of the token type", - "in" : "path", - "required" : true, + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/user" + }, { + "name" : "creationPeriod", + "in" : "query", + "required" : false, + "description" : "The minimum / maximum order creation date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "schema" : { + "type" : "array", + "items" : { + "description" : "", + "type" : "string", + "format" : "date-time" + } + } + }, { + "name" : "number", + "in" : "query", + "required" : false, + "description" : "The generated order number according to the webshop settings.", "schema" : { "type" : "string" } }, { - "name" : "value", - "description" : "The token value", - "in" : "path", - "required" : true, + "name" : "page", + "in" : "query", + "required" : false, + "description" : "The page number (zero-based) of the search. The default value is zero.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "pageSize", + "in" : "query", + "required" : false, + "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", + "schema" : { + "type" : "integer", + "format" : "int32" + } + }, { + "name" : "productNumber", + "in" : "query", + "required" : false, + "description" : "The product number (with the mask if there is one) of an advertisement contained in the orders.", + "schema" : { + "type" : "string" + } + }, { + "name" : "relatedUser", + "in" : "query", + "required" : false, + "description" : "Either id or an identification, such as login name, e-mail, etc, for the seller or buyer according whether we are searching for purchases or sales. The allowed identification methods are those the authenticated user can use on keywords search.", "schema" : { "type" : "string" } + }, { + "name" : "sales", + "in" : "query", + "required" : false, + "description" : "Are we searching for sales or purchases? If not specified it's assumed purchases (i.e `false`)", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "skipTotalCount", + "in" : "query", + "required" : false, + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit.", + "schema" : { + "type" : "boolean" + } + }, { + "name" : "statuses", + "in" : "query", + "required" : false, + "description" : "", + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/OrderStatusEnum" + } + } } ], "responses" : { "200" : { - "description" : "Returns the token data", + "description" : "The orders matching the criteria.", + "headers" : { + "X-Total-Count" : { + "schema" : { + "type" : "integer" + }, + "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." + }, + "X-Page-Size" : { + "schema" : { + "type" : "integer" + }, + "description" : "The maximum number of results per page" + }, + "X-Current-Page" : { + "schema" : { + "type" : "integer" + }, + "description" : "The current page the results are in" + }, + "X-Has-Next-Page" : { + "schema" : { + "type" : "boolean" + }, + "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." + } + }, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/TokenDetailed" + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/UserOrderResult" + } } } } @@ -31063,14 +42383,12 @@ } } } - } - }, - "/nfc/external-auth" : { + }, "post" : { - "operationId" : "nfcExternalAuth", - "summary" : "NFC external authentication", - "description" : "The NFC tag will normally perform a mutual authentication, by first generating a challenge that must be encrypted by the external system with the device key. With this the external system is authenticated. Cyclos also returns a challenge that should be encrypted by the NFC tag. This challenge can later be passed in specific operations (for example, when performing a payment) for Cyclos to make sure the NFC tag is present on the operation.", - "tags" : [ "NFC" ], + "operationId" : "createOrder", + "summary" : "Creates a new order as the seller for a specific buyer", + "description" : "Creates a new order as the seller (i.e the user given in the path must resolve to the authenticated user) for a specific buyer (given in the request body). By default the status of the order will be `draft`. If the order contains all the required information and the seller wants to send it to the buyer then he can do it changing the `draft` boolean field to `false` before submit.", + "tags" : [ "Orders" ], "security" : [ { "basic" : [ ] }, { @@ -31078,14 +42396,24 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ ], + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], "responses" : { - "200" : { - "description" : "Returns the challenge to be encrypted by the NFC tag in a subsequent operation", + "201" : { + "description" : "Returns the identifier of the new order", + "headers" : { + "Location" : { + "description" : "URL for viewing the order details", + "schema" : { + "type" : "string" + } + } + }, "content" : { - "application/json" : { + "text/plain" : { "schema" : { - "$ref" : "#/components/schemas/NfcExternalAuthenticateResult" + "type" : "string" } } } @@ -31131,35 +42459,35 @@ } }, "500" : { - "description" : "If a NFC external authentication error has occurred", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/NfcAuthError" + "$ref" : "#/components/schemas/Error" } } } } }, "requestBody" : { - "description" : "The parameters for the external authentication. If the `token` value is informed, it will be performed an external authentication with the token itself, using the Application Master Key (AMK). If the `token` is not informed, the authentication will be done using the PICC Master Key (PMK), which is useful, for example, when initializing the NFC tag.", + "description" : "The order to be created with status `draft`", "required" : true, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/NfcExternalAuthenticateParameter" + "$ref" : "#/components/schemas/OrderNew" } } } } } }, - "/nfc/data-for-initialize" : { + "/{user}/orders/data-for-new" : { "get" : { - "operationId" : "getNfcDataForInitialize", - "summary" : "Returns data for NFC tag initialization. Optionally the user can personalize the tag too.", - "description" : "Returns data with the NFC token types the authenticated user can use to initialize NFC tags.", - "tags" : [ "NFC" ], + "operationId" : "getOrderDataForNew", + "summary" : "Returns data for creating orders as the seller for a specific buyer.", + "description" : "The authenticated user must be the seller (i.e the user given in the path must resolve to the authenticated user) with webshop enable permission.", + "tags" : [ "Orders" ], "security" : [ { "basic" : [ ] }, { @@ -31169,14 +42497,32 @@ } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/user" + }, { + "name" : "buyer", + "in" : "query", + "required" : true, + "description" : "The user for whom the order will be created. It could be a user identification value, such as id, username, e-mail, phone, etc. Id is always allowed, others depend on Cyclos configuration. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix\\ the value with a single quote (like in Excel spreadsheets);", + "schema" : { + "type" : "string" + } + }, { + "name" : "currency", + "in" : "query", + "required" : false, + "description" : "Either id or internal name of the currency for the new order. If not given a list with the available currencies for the given buyer will be returned. At the moment of create the order a currency is required.", + "schema" : { + "type" : "string" + } } ], "responses" : { "200" : { - "description" : "The data for NFC tag initialization", + "description" : "The order data for create sales.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/NfcDataForInitialize" + "$ref" : "#/components/schemas/OrderDataForNew" } } } @@ -31211,12 +42557,12 @@ } } }, - "500" : { - "description" : "Unexpected error", + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Error" + "$ref" : "#/components/schemas/InputError" } } } @@ -31224,12 +42570,12 @@ } } }, - "/nfc/initialize" : { - "post" : { - "operationId" : "initializeNfc", - "summary" : "Initializes a NFC tag", - "description" : "Initializes a NFC tag, creating a new `token` in Cyclos. Returns the keys (PICC Master Key, Application Master Key and the Operational Key) to be stored on the NFC tag.", - "tags" : [ "NFC" ], + "/{user}/orders/data-for-search" : { + "get" : { + "operationId" : "getOrderDataForSearch", + "summary" : "Returns data for searching orders (purchases / sales) of a specific user.", + "description" : "The authenticated user must be the seller, buyer or a manager user with permission to view purchases or sales.", + "tags" : [ "Orders" ], "security" : [ { "basic" : [ ] }, { @@ -31237,14 +42583,26 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/user" + }, { + "name" : "sales", + "in" : "query", + "required" : false, + "description" : "Whether we are getting data for searching purchases or sales", + "schema" : { + "type" : "boolean" + } + } ], "responses" : { "200" : { - "description" : "The data for NFC tag initialization", + "description" : "The order data fo search.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/NfcInitializeResult" + "$ref" : "#/components/schemas/OrderDataForSearch" } } } @@ -31279,46 +42637,28 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { - "description" : "If a NFC tag inititalization error has occurred", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/InitializeNfcError" + "$ref" : "#/components/schemas/Error" } } } } - }, - "requestBody" : { - "description" : "The parameters for initializing the NFC tag. If the `user` value is left blank, the NFC tag will be only initialized, but not personalized (assigned to any user). If a user is given, the permission to personalize is required (besides the permission to initialize), and is a shortcut to initializing and later personalizing the tag. The initialization is a sensitive operation, as the result contains the plain keys that should be stored on the NFC tag. Hence, can only be performed by managers (with granted permission). Later on, other users (for example, businesses) will be able to personalize the NFC tag for customers.", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/NfcInitializeParameter" - } - } - } } } }, - "/nfc/data-for-personalize" : { + "/orders/{order}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/order" + } ], "get" : { - "operationId" : "getNfcDataForPersonalize", - "summary" : "Returns data for perfornalizing an initialized NFC tag for a user", - "description" : "Returns data for personalizing a NFC tag for a given user.", - "tags" : [ "NFC" ], + "operationId" : "viewOrder", + "summary" : "Returns details of an order.", + "description" : "Returns detailed information of an order.", + "tags" : [ "Orders" ], "security" : [ { "basic" : [ ] }, { @@ -31328,30 +42668,14 @@ } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" - }, { - "name" : "tokenType", - "in" : "query", - "required" : true, - "description" : "The token type reference (id or internal name) of the token principal type, which is stored on the NFC card being personalized.", - "schema" : { - "type" : "string" - } - }, { - "name" : "user", - "in" : "query", - "required" : true, - "description" : "The user reference (id or an identification method) of the user to whom the NFC tag will be personalized. When authenticated as a manager of that user (administrator or broker) no confirmation password will be required for the personalization. However, if the authenticated user is not a manager, the user will be required a confirmation password.", - "schema" : { - "type" : "string" - } } ], "responses" : { "200" : { - "description" : "The data for NFC tag personalization", + "description" : "The order details.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/NfcDataForPersonalize" + "$ref" : "#/components/schemas/OrderView" } } } @@ -31397,14 +42721,12 @@ } } } - } - }, - "/nfc/personalize" : { - "post" : { - "operationId" : "personalizeNfc", - "summary" : "Personalizes a NFC tag", - "description" : "Personalization requires a NFC tag that was previously initialized, but is still unassigned. This operation doesn't store any key in the NFC tag itself, hence the plain keys are not returned. What is needed is an external authentication with the NFC tag, in order to ensure the card is physically present. The flow for personalizing a tag is: - `GET /nfc/data-for-personalize?user={user}`: Obtain the data for\n personalizing NFC tags for this user. The most important information\n is which the confirmation password will be required, if any;\n- `POST /nfc/external-auth`: With a challenge previously encrypted by the\n NFC tag, invoke this operation. If the challenge matches the NFC token\n in Cyclos, it will be encrypted and returned. Also a new challenge will\n be returned, which should be then encrypted by the NFC tag for later\n being sent back;\n- `POST /nfc/personalize`: With the encrypted challenge and the\n confirmation password (if any), this operation will update the NFC\n token in Cyclos, so it is now assigned to the specified user. From\n this point on, the NFC tag is operational.", - "tags" : [ "NFC" ], + }, + "put" : { + "operationId" : "updateOrder", + "summary" : "Updates an existing order.", + "description" : "Updates an existing order.", + "tags" : [ "Orders" ], "security" : [ { "basic" : [ ] }, { @@ -31412,12 +42734,19 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "$ref" : "#/components/parameters/confirmationPassword" - } ], "responses" : { "204" : { - "description" : "The NFC tag is personalized and nothing is returned" + "description" : "The order was updated." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConflictError" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -31460,35 +42789,33 @@ } }, "500" : { - "description" : "If a NFC tag personalization error has occurred", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/PersonalizeNfcError" + "$ref" : "#/components/schemas/Error" } } } } }, "requestBody" : { - "description" : "The parameters for the initialization.", + "description" : "The order to be edited.", "required" : true, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/NfcPersonalizeParameter" + "$ref" : "#/components/schemas/OrderEdit" } } } } - } - }, - "/nfc/personalize/otp" : { - "post" : { - "operationId" : "getOtpForPersonalizeNfc", - "summary" : "Generates a new One-Time-Password (OTP) for personalizing a NFC tag", - "description" : "Sends a new OTP for the customer which will own the NFC tag. The OTP belongs to the NFC tag owner, not the authenticated user.", - "tags" : [ "NFC" ], + }, + "delete" : { + "operationId" : "deleteOrder", + "summary" : "Removes an order.", + "description" : "Removes an order.", + "tags" : [ "Orders" ], "security" : [ { "basic" : [ ] }, { @@ -31496,18 +42823,19 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ { - "name" : "medium", - "in" : "query", - "required" : true, - "description" : "The medium the user wants to receive the otp", - "schema" : { - "$ref" : "#/components/schemas/SendMediumEnum" - } - } ], "responses" : { "204" : { - "description" : "The OTP is sent to the user, and no content is returned" + "description" : "The order was removed." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConflictError" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -31540,43 +42868,43 @@ } }, "500" : { - "description" : "There was an error when generating the OTP", + "description" : "Unexpected error", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/OtpError" + "$ref" : "#/components/schemas/Error" } } } } - }, - "requestBody" : { - "description" : "The parameters identifying the token and the user", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/NfcPersonalizeDataParameter" - } - } - } } } }, - "/nfc/personalize/device-confirmations" : { - "post" : { - "operationId" : "createDeviceConfirmationForPersonalizeNfc", - "summary" : "Creates a pending device confirmation for personalizing a NFC tag.", - "description" : "Creates a device confirmation for the customer which will own the NFC tag. The confirmation must be approved by the NFC tag owner, not the authenticated user, i.e the confirmation QR-code must be read (e.g with the Mobile App) by the customer. After the confirmation being processed the authenticated user will be notified.", - "tags" : [ "NFC" ], - "parameters" : [ ], + "/orders/{order}/data-for-edit" : { + "get" : { + "operationId" : "getOrderDataForEdit", + "summary" : "Returns data for modifying an order as the seller.", + "description" : "Returns data for modifying an order as the seller.", + "tags" : [ "Orders" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/order" + } ], "responses" : { - "201" : { - "description" : "Returns the identifier of the new confirmation.", + "200" : { + "description" : "The order data.", "content" : { - "text/plain" : { + "application/json" : { "schema" : { - "type" : "string" + "$ref" : "#/components/schemas/OrderDataForEdit" } } } @@ -31620,37 +42948,102 @@ } } } + } + } + } + }, + "/orders/{order}/seller/data-for-set-delivery" : { + "get" : { + "operationId" : "getDataForSetDeliveryMethod", + "summary" : "Returns configuration data to set delivery method data by seller.", + "description" : "Returns configuration data to set delivery method data by seller of an order given by id.", + "tags" : [ "Orders" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + }, { + "$ref" : "#/components/parameters/order" + } ], + "responses" : { + "200" : { + "description" : "The configuration data for set he delivery method.", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/OrderDataForSetDeliveryMethod" + } + } + } }, "500" : { - "description" : "Unexpected error", + "description" : "If a payment error has occurred", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Error" + "$ref" : "#/components/schemas/PaymentError" + } + } + } + } + } + } + }, + "/orders/{order}/seller/set-delivery" : { + "post" : { + "operationId" : "setDeliveryMethod", + "summary" : "Sets delivery method data by seller.", + "description" : "Sets the delivery method data by seller for the order given by id. This operation can be used only if the order is in status `pendingSeller` and has not already set delivery method data. After the delivery method has been set the order will be enter in status `pendingBuyer` to be accepted by buyer.", + "tags" : [ "Orders" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/order" + } ], + "responses" : { + "204" : { + "description" : "The delivery method was set by seller. Nothing is returned." + }, + "500" : { + "description" : "If a payment error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentError" } } } } }, "requestBody" : { - "description" : "The parameters identifying the token and the user", - "required" : true, + "description" : "The parameters for setting the delivery method.", + "required" : false, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/NfcPersonalizeDataParameter" + "$ref" : "#/components/schemas/SetDeliveryMethod" } } } } } }, - "/nfc/personalize/device-confirmations/{id}" : { + "/orders/{order}/buyer/data-for-accept" : { "get" : { - "operationId" : "viewDeviceConfirmationForPersonalizeNfc", - "summary" : "Shows the details of a device confirmation that was created to confirm the personalize nfc-tag operation.", - "description" : "Shows a device confirmation for the user which will own the NFC tag. The confirmation belongs to that user, not the authenticated user. The same parameters used for the creation must be sent for this operation too.", - "tags" : [ "NFC" ], + "operationId" : "getOrderDataForAcceptByBuyer", + "summary" : "Returns configuration data for accept an order by buyer.", + "description" : "Returns configuration data for accept an order given by id as the buyer.", + "tags" : [ "Orders" ], "security" : [ { "basic" : [ ] }, { @@ -31659,31 +43052,17 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/id" - }, { - "name" : "user", - "description" : "The principal (id, login name, etc) of the user who will own the tag. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`.", - "in" : "query", - "required" : true, - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/fields" }, { - "name" : "type", - "description" : "Either the identifier or internal name of fhe NFC token type", - "in" : "query", - "required" : true, - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/order" } ], "responses" : { "200" : { - "description" : "The device confirmation details.", + "description" : "The configuration data for accept the order as the buyer.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/DeviceConfirmationView" + "$ref" : "#/components/schemas/OrderDataForAcceptByBuyer" } } } @@ -31729,12 +43108,14 @@ } } } - }, - "delete" : { - "operationId" : "deleteDeviceConfirmationForPersonalizeNfc", - "summary" : "Deletes a device confirmation that was created to confirm the personalize nfc-tag operation.", - "description" : "Deletes a device confirmation for the user which will own the NFC tag. The confirmation belongs to that user, not the authenticated user. The same parameters used for the creation must be sent for this operation too.", - "tags" : [ "NFC" ], + } + }, + "/orders/{order}/buyer/accept" : { + "post" : { + "operationId" : "acceptOrderByBuyer", + "summary" : "Accepts a pending order by buyer.", + "description" : "Accepts a pending order by buyer generating the corresponding payment. The order status must be `pendingBuyer` to be accepted by the authenticated user (i.e the buyer).\nThe `paymentType` and the `confirmationPassword` are required under the following circumstances:\n`paymentType`: Only required if the order was generated as a sale by the seller and not from the shopping cart check-out (Sales are not supported yet).\n`confirmationPassword`: Only required if at check-out a delivery method was not set or its charge type is `negotiatied`.\nThe possible statuses after an order acceptance are: - `paymentPending`: if the generated payment is awaiting authorization; - `completed`: if the payment was done.", + "tags" : [ "Orders" ], "security" : [ { "basic" : [ ] }, { @@ -31743,37 +43124,101 @@ "accessClient" : [ ] } ], "parameters" : [ { - "$ref" : "#/components/parameters/id" + "$ref" : "#/components/parameters/order" }, { - "name" : "user", - "description" : "The principal (id, login name, etc) of the user who will own the tag. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`.", - "in" : "query", - "required" : true, - "schema" : { - "type" : "string" + "$ref" : "#/components/parameters/confirmationPassword" + } ], + "responses" : { + "204" : { + "description" : "The order was accepted by the buyer. Nothing is returned." + }, + "500" : { + "description" : "If a payment error has occurred", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/PaymentError" + } + } + } } - }, { - "name" : "type", - "description" : "Either the identifier or internal name of fhe NFC token type", - "in" : "query", - "required" : true, - "schema" : { - "type" : "string" + }, + "requestBody" : { + "description" : "The parameters for accepting the order.", + "required" : false, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/AcceptOrderByBuyer" + } + } } + } + } + }, + "/orders/{order}/seller/accept" : { + "post" : { + "operationId" : "acceptOrderBySeller", + "summary" : "Accepts a pending order by seller.", + "description" : "Accepts a pending order by seller generating the corresponding payment. The order status must be `pendingSeller` to be accepted by the authenticated user (i.e seller). The possible statuses after order acceptance are:\n- `paymentPending`: if the generated payment is awaiting for authorization; - `completed`: if the payment was done.", + "tags" : [ "Orders" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/order" } ], "responses" : { "204" : { - "description" : "The device confirmation was removed." + "description" : "The order was accepted by seller. Nothing is returned." }, - "409" : { - "description" : "This operation expected an entity state, but it has resulted in a conflict", + "500" : { + "description" : "If a payment error has occurred", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ConflictError" + "$ref" : "#/components/schemas/PaymentError" } } } + } + }, + "requestBody" : { + "description" : "The parameters for accepting the order.", + "required" : false, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/AcceptOrderBySeller" + } + } + } + } + } + }, + "/orders/{order}/reject" : { + "post" : { + "operationId" : "rejectOrder", + "summary" : "Rejects a pending order.", + "description" : "Rejects a pending order by buyer or seller. The order status must be `pendingBuyer` or `pendingSeller` to be rejected by the authenticated user (buyer/seller). The possible statuses after an order rejection are:\n- `rejectedBySeller`: if the authenticated user is the seller; - `rejectedByBuyer`: if the authenticated user is the buyer.", + "tags" : [ "Orders" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/order" + } ], + "responses" : { + "204" : { + "description" : "The order was rejected by the authenticated user. Nothing is returned." }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -31805,6 +43250,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -31815,49 +43270,46 @@ } } } + }, + "requestBody" : { + "description" : "The parameters for rejecting the order.", + "required" : false, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/RejectOrder" + } + } + } } } }, - "/nfc/personalize/device-confirmations/{id}/qr-code" : { + "/{user}/delivery-methods/list-data" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], "get" : { - "operationId" : "getDeviceConfirmationQrCodeForPersonalizeNfc", - "summary" : "Returns the QR-code image for the given device confirmation only if it was not yet approved / rejected", - "description" : "This request will return the image contents as expected but our api documentation page (or any other usage of an <img> tag), created using swagger-ui, generates a second request to include the image in the page. This new (GET) request won't send the authentication parameters and as this path requires authentication the image will be shown as broken. Optionally, to solve the problem described above and to allow authenticate the user when using sessions, a `sessionToken` or `accessClientToken` query parameter could be specified.", - "tags" : [ "NFC" ], - "parameters" : [ { - "$ref" : "#/components/parameters/id" - }, { - "name" : "user", - "description" : "The principal (id, login name, etc) of the user who will own the tag. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`.", - "in" : "query", - "required" : true, - "schema" : { - "type" : "string" - } + "operationId" : "getUserDeliveryMethodsListData", + "summary" : "Returns data for webshop delivery methods listing of the given user.", + "description" : "Returns the user webshop delivery methods, plus additional data related to them.", + "tags" : [ "DeliveryMethods" ], + "security" : [ { + "basic" : [ ] }, { - "name" : "type", - "description" : "Either the identifier or internal name of fhe NFC token type", - "in" : "query", - "required" : true, - "schema" : { - "type" : "string" - } + "session" : [ ] }, { - "name" : "size", - "in" : "query", - "required" : false, - "schema" : { - "$ref" : "#/components/schemas/ImageSizeEnum" - } + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" } ], "responses" : { "200" : { - "description" : "The image content", + "description" : "The data for listing webshop delivery methods", "content" : { - "image/png" : { + "application/json" : { "schema" : { - "type" : "string", - "format" : "binary" + "$ref" : "#/components/schemas/UserDeliveryMethodsListData" } } } @@ -31905,12 +43357,15 @@ } } }, - "/nfc/cancel" : { - "post" : { - "operationId" : "cancelNfc", - "summary" : "Cancels a NFC tag", - "description" : "Cancels a NFC token. Must be authenticated as a manager (administrator / broker) of the token owner, and have the correct permission.", - "tags" : [ "NFC" ], + "/{user}/delivery-methods/data-for-new" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], + "get" : { + "operationId" : "getDeliveryMethodDataForNew", + "summary" : "Returns data for creating a new webshop delivery method for a given user.", + "description" : "Returns data for creating a new webshop delivery method for a given user.", + "tags" : [ "DeliveryMethods" ], "security" : [ { "basic" : [ ] }, { @@ -31918,10 +43373,19 @@ }, { "accessClient" : [ ] } ], - "parameters" : [ ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], "responses" : { - "204" : { - "description" : "The NFC tag is canceled and nothing is returned" + "200" : { + "description" : "The data for creating a new webshop delivery method.", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DeliveryMethodDataForNew" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -31963,78 +43427,38 @@ } } } - }, - "requestBody" : { - "description" : "The parameters for canceling.", - "required" : true, - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/NfcTokenParameter" - } - } - } } } }, - "/push/subscribe" : { - "get" : { - "operationId" : "subscribeForPushNotifications", - "summary" : "Subscribes for receiving push notifications of specific types", - "description" : "Returns an event stream of server-sent events", - "tags" : [ "Push" ], - "parameters" : [ { - "name" : "clientId", - "in" : "query", - "required" : true, - "description" : "An id generated by the client. This id is valid for the authenticated used, indicating a single session. As event streams can timeout and be reconnected, subsequent subscriptions with the same user and client id are considered the same subscription, and missed events since the last timeout will be immediately delivered. Missed events are enqueued up to a few minutes after the connection timeout. After that window, any enqueued events are discarded.", - "schema" : { - "type" : "string" - } - }, { - "name" : "kinds", - "in" : "query", - "required" : true, - "description" : "The event kinds for which the client desires to subscribe", - "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/PushNotificationEventKind" - } - } - }, { - "name" : "accountIds", - "in" : "query", - "required" : false, - "description" : "When subscribing to `accountStatus` events, this parameter must be informed to select the accounts to be watched for.", - "schema" : { - "type" : "array", - "items" : { - "type" : "string" - } - } + "/{user}/delivery-methods" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], + "post" : { + "operationId" : "createDeliveryMethod", + "summary" : "Creates a new webshop delivery method for a given user.", + "description" : "Creates a new webshop delivery method for a given user.", + "tags" : [ "DeliveryMethods" ], + "security" : [ { + "basic" : [ ] }, { - "name" : "ticketNumber", - "in" : "query", - "required" : false, - "description" : "When subscribing to `ticket` events, this parameter can be used to filter which ticket to monitor.", - "schema" : { - "type" : "string" - } + "session" : [ ] }, { - "name" : "lastEventId", - "in" : "header", - "required" : false, - "description" : "The last received event id, in case of reconnections. May also be passed as the standard header `Last-Event-ID`.", - "schema" : { - "type" : "string" - } + "accessClient" : [ ] } ], "responses" : { - "200" : { - "description" : "The event stream", + "201" : { + "description" : "Returns the identifier of the new delivery method.", + "headers" : { + "Location" : { + "description" : "URL for viewing the delivery method details.", + "schema" : { + "type" : "string" + } + } + }, "content" : { - "text/event-stream" : { + "text/plain" : { "schema" : { "type" : "string" } @@ -32071,6 +43495,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -32081,59 +43515,46 @@ } } } + }, + "requestBody" : { + "description" : "The delivery method to be created.", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DeliveryMethodNew" + } + } + } } } }, - "/ui/data-for-ui" : { + "/delivery-methods/{id}/data-for-edit" : { + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], "get" : { - "operationId" : "dataForUi", - "summary" : "Returns useful data required to properly display a user interface", - "description" : "The returned data contains settings and also content like header, footer and theme.", - "tags" : [ "UI" ], - "parameters" : [ { - "$ref" : "#/components/parameters/fields" - }, { - "name" : "kind", - "in" : "query", - "required" : false, - "description" : "Specifies the kind of user interface to get data for. If null then no data related to the UI will be returned.", - "schema" : { - "$ref" : "#/components/schemas/UiKind" - } - }, { - "$ref" : "#/components/parameters/cyclosVersion" - }, { - "$ref" : "#/components/parameters/headerIf" - }, { - "$ref" : "#/components/parameters/footerIf" - }, { - "$ref" : "#/components/parameters/themeIf" - }, { - "$ref" : "#/components/parameters/themeByComponents" + "operationId" : "getDeliveryMethodDataForEdit", + "summary" : "Returns data for modifying a webshop delivery method.", + "description" : "Returns data for modifying a webshop delivery method.", + "tags" : [ "DeliveryMethods" ], + "security" : [ { + "basic" : [ ] }, { - "name" : "deviceId", - "in" : "query", - "required" : false, - "description" : "Trusted device identification. If given and the device is active then a pending device confirmation will be created that will be validated after the user logs-in. If the validation passes then no confirmation password will be used only for that session.", - "schema" : { - "type" : "string" - } + "session" : [ ] }, { - "name" : "pinId", - "in" : "query", - "required" : false, - "description" : "Device PIN identification. If given then the information about whether it is active or not will be given in the returned `dataForLogin`.", - "schema" : { - "type" : "string" - } + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" } ], "responses" : { "200" : { - "description" : "Returns the data for display a user interface", + "description" : "The webshop delivery method data.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/DataForUi" + "$ref" : "#/components/schemas/DeliveryMethodDataForEdit" } } } @@ -32181,24 +43602,35 @@ } } }, - "/validate/email-change/{key}" : { + "/delivery-methods/{id}" : { "parameters" : [ { - "name" : "key", - "required" : true, - "in" : "path", - "description" : "The e-mail change validation key the user has received.", - "schema" : { - "type" : "string" - } + "$ref" : "#/components/parameters/id" } ], - "post" : { - "operationId" : "validateEmailChange", - "summary" : "Validate a pending e-mail change.", - "description" : "When e-mail validation on change is enabled on the configuration, when a user changes their e-mail the new e-mail will not be immediately used. In this case, an e-mail is sent to the new e-mail address, with a link to validate it. That link should include the validation key, which should be sent to the Cyclos backend to actually validate the new e-mail. Only after this the new e-mail address will be effectively used in Cyclos.", - "tags" : [ "Validation" ], + "get" : { + "operationId" : "viewDeliveryMethod", + "summary" : "Returns details of a webshop delivery method.", + "description" : "Returns details of a webshop delivery method.", + "tags" : [ "DeliveryMethods" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], "responses" : { "200" : { - "description" : "If the e-mail change was validated correctly." + "description" : "The webshop delivery method data.", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DeliveryMethodView" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -32230,16 +43662,6 @@ } } }, - "422" : { - "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/InputError" - } - } - } - }, "500" : { "description" : "Unexpected error", "content" : { @@ -32251,30 +43673,29 @@ } } } - } - }, - "/validate/registration/{key}" : { - "parameters" : [ { - "name" : "key", - "required" : true, - "in" : "path", - "description" : "The registration validation key the user has received.", - "schema" : { - "type" : "string" - } - } ], - "post" : { - "operationId" : "validateUserRegistration", - "summary" : "Validate a pending user registration.", - "description" : "Validate a pending user registration for the given validation key. After validating the registration is completed. However, the group configuration defines if the user is initially active or not.", - "tags" : [ "Validation" ], + }, + "put" : { + "operationId" : "updateDeliveryMethod", + "summary" : "Updates an existing webshop delivery method.", + "description" : "Updates an existing webshop delivery method.", + "tags" : [ "DeliveryMethods" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], "responses" : { - "200" : { - "description" : "The result of the validation. The resulting status only can be `active` or `inactive`.", + "204" : { + "description" : "The webshop delivery method was updated." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/UserRegistrationResult" + "$ref" : "#/components/schemas/ConflictError" } } } @@ -32329,18 +43750,24 @@ } } } + }, + "requestBody" : { + "description" : "The webshop delivery method to be edited.", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/DeliveryMethodEdit" + } + } + } } - } - }, - "/{user}/registration/validate" : { - "parameters" : [ { - "$ref" : "#/components/parameters/userNoSelf" - } ], - "post" : { - "operationId" : "manuallyValidateUserRegistration", - "summary" : "Manually validates a pending user / operator registration.", - "description" : "Marks the user registration as validated. Can only be performed by a manager (admin / broker) of the pending user. The actual resulting user status depends on the group configuration. The user status must be `pending`.", - "tags" : [ "Validation" ], + }, + "delete" : { + "operationId" : "deleteDeliveryMethod", + "summary" : "Removes a webshop delivery method.", + "description" : "Removes a webshop delivery method.", + "tags" : [ "DeliveryMethods" ], "security" : [ { "basic" : [ ] }, { @@ -32349,12 +43776,15 @@ "accessClient" : [ ] } ], "responses" : { - "200" : { - "description" : "The result of the e-mail validation. The resulting status only can be `active` or `inactive`.", + "204" : { + "description" : "The webshop delivery method was removed." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/UserRegistrationResult" + "$ref" : "#/components/schemas/ConflictError" } } } @@ -32402,15 +43832,15 @@ } } }, - "/{user}/registration/resend" : { + "/{user}/webshop-settings" : { "parameters" : [ { - "$ref" : "#/components/parameters/userNoSelf" + "$ref" : "#/components/parameters/user" } ], - "post" : { - "operationId" : "resendUserRegistrationEmail", - "summary" : "Re-sends the e-mail to validate a pending user / operator registration.", - "description" : "Sends the validation e-mail again. This operation has to be executed by the user manager (admin or broker). The user status must be `pending`.", - "tags" : [ "Validation" ], + "get" : { + "operationId" : "viewWebshopSettings", + "summary" : "Returns the webshop settings for a given user.", + "description" : "Returns the webshop settings for a given user.", + "tags" : [ "WebshopSettings" ], "security" : [ { "basic" : [ ] }, { @@ -32418,9 +43848,19 @@ }, { "accessClient" : [ ] } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], "responses" : { - "204" : { - "description" : "The e-mail is sent and nothing is returned" + "200" : { + "description" : "The webshop settings.", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/WebshopSettingsView" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -32463,17 +43903,12 @@ } } } - } - }, - "/{user}/email-change/validate" : { - "parameters" : [ { - "$ref" : "#/components/parameters/userNoSelf" - } ], - "post" : { - "operationId" : "manuallyValidateEmailChange", - "summary" : "Manually validates a pending e-mail change.", - "description" : "If the user has a new e-mail address pending validation, this operation, which has to be executed by the user manager (admin or broker) marks the new e-mail address as validating, effectively changing the user's e-mail.", - "tags" : [ "Validation" ], + }, + "put" : { + "operationId" : "updateWebshopSettings", + "summary" : "Updates a user's webshop settings.", + "description" : "Updates a user's webshop settings.", + "tags" : [ "WebshopSettings" ], "security" : [ { "basic" : [ ] }, { @@ -32483,7 +43918,7 @@ } ], "responses" : { "204" : { - "description" : "The new e-mail address is effectly used and nothing is returned" + "description" : "The webshop settings were updated." }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -32515,6 +43950,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -32525,18 +43970,29 @@ } } } + }, + "requestBody" : { + "description" : "The new webshop settings", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/WebshopSettingsDetailed" + } + } + } } } }, - "/{user}/email-change/resend" : { + "/{user}/marketplace-interests/list-data" : { "parameters" : [ { - "$ref" : "#/components/parameters/userNoSelf" + "$ref" : "#/components/parameters/user" } ], - "post" : { - "operationId" : "resendEmailChangeEmail", - "summary" : "Re-sends the e-mail to validate a pending e-mail change.", - "description" : "Sends again the e-mail to the new user e-mail address. This operation has to be executed by the user manager (admin or broker).", - "tags" : [ "Validation" ], + "get" : { + "operationId" : "getUserAdInterestsListData", + "summary" : "Returns data for advertisement interests listing of the given user.", + "description" : "Returns data for advertisement interests listing of the given user.", + "tags" : [ "AdInterests" ], "security" : [ { "basic" : [ ] }, { @@ -32544,9 +44000,19 @@ }, { "accessClient" : [ ] } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], "responses" : { - "204" : { - "description" : "The new e-mail address is effectly used and nothing is returned" + "200" : { + "description" : "The data for listing advertisement interests.", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UserAdInterestsListData" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -32591,12 +44057,15 @@ } } }, - "/localization/locales" : { + "/{user}/marketplace-interests/data-for-new" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], "get" : { - "operationId" : "getLocales", - "summary" : "Returns the list of available locales, this collection is already sent in DataForUI or MobileBaseData.", - "description" : "Returns the list of available locales.", - "tags" : [ "Localization" ], + "operationId" : "getAdInterestDataForNew", + "summary" : "Returns data for creating a new advertisement interest for a given user.", + "description" : "Returns data for creating a new advertisement interest for a given user.", + "tags" : [ "AdInterests" ], "security" : [ { "basic" : [ ] }, { @@ -32604,16 +44073,16 @@ }, { "accessClient" : [ ] } ], + "parameters" : [ { + "$ref" : "#/components/parameters/fields" + } ], "responses" : { "200" : { - "description" : "The list of available locales.", + "description" : "The data for creating a new advertisement interest.", "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/UserLocale" - } + "$ref" : "#/components/schemas/AdInterestDataForNew" } } } @@ -32661,13 +44130,15 @@ } } }, - "/localization/settings" : { + "/{user}/marketplace-interests" : { + "parameters" : [ { + "$ref" : "#/components/parameters/user" + } ], "post" : { - "operationId" : "saveLocalizationSettings", - "summary" : "Saves the localization settings for the authenticated user.", - "description" : "Saves the localization settings for the authenticated user such as the preferred language.", - "parameters" : [ ], - "tags" : [ "Localization" ], + "operationId" : "createAdInterest", + "summary" : "Creates a new advertisement interest for a given user.", + "description" : "Creates a new advertisement interest for a given user.", + "tags" : [ "AdInterests" ], "security" : [ { "basic" : [ ] }, { @@ -32676,8 +44147,23 @@ "accessClient" : [ ] } ], "responses" : { - "204" : { - "description" : "The settings were saved" + "201" : { + "description" : "Returns the identifier of the new advertisement interest.", + "headers" : { + "Location" : { + "description" : "URL for viewing the advertisement interest details.", + "schema" : { + "type" : "string" + } + } + }, + "content" : { + "text/plain" : { + "schema" : { + "type" : "string" + } + } + } }, "401" : { "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", @@ -32709,6 +44195,16 @@ } } }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, "500" : { "description" : "Unexpected error", "content" : { @@ -32721,24 +44217,27 @@ } }, "requestBody" : { - "description" : "The localization settings.", + "description" : "The advertisement interest to be created.", "required" : true, "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/LocalizationSettings" + "$ref" : "#/components/schemas/AdInterestNew" } } } } } }, - "/alerts/user" : { + "/marketplace-interests/{id}/data-for-edit" : { + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], "get" : { - "operationId" : "searchUserAlerts", - "summary" : "Searches for user alerts.", - "description" : "Searches for user alerts according to a give set of filters.", - "tags" : [ "Alerts" ], + "operationId" : "getAdInterestDataForEdit", + "summary" : "Returns data for modifying an advertisement interest.", + "description" : "Returns data for modifying an advertisement interest.", + "tags" : [ "AdInterests" ], "security" : [ { "basic" : [ ] }, { @@ -32748,121 +44247,14 @@ } ], "parameters" : [ { "$ref" : "#/components/parameters/fields" - }, { - "name" : "brokers", - "in" : "query", - "required" : false, - "description" : "Either the ids or identification methods the alert user's brokers", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "datePeriod", - "in" : "query", - "required" : false, - "description" : "The minimum / maximum alert date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string", - "format" : "date-time" - } - } - }, { - "name" : "groups", - "in" : "query", - "required" : false, - "description" : "Either the ids or internal names of the alert user", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "description" : "", - "type" : "string" - } - } - }, { - "name" : "page", - "in" : "query", - "required" : false, - "description" : "The page number (zero-based) of the search. The default value is zero.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - }, { - "name" : "pageSize", - "in" : "query", - "required" : false, - "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting.", - "schema" : { - "type" : "integer", - "format" : "int32" - } - }, { - "name" : "types", - "in" : "query", - "required" : false, - "description" : "The types of user alerts to search", - "style" : "simple", - "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/UserAlertTypeEnum" - } - } - }, { - "name" : "user", - "in" : "query", - "required" : false, - "description" : "Either the id or identifier of the alert user", - "schema" : { - "type" : "string" - } } ], "responses" : { "200" : { - "description" : "The accounts with their statuses.", - "headers" : { - "X-Total-Count" : { - "schema" : { - "type" : "integer" - }, - "description" : "The total number of results. It may be configured in Cyclos to skip the total count, which is useful on large databases, where the count itself may use a lot of resources from the database. If disabled, this header is not returned." - }, - "X-Page-Size" : { - "schema" : { - "type" : "integer" - }, - "description" : "The maximum number of results per page" - }, - "X-Current-Page" : { - "schema" : { - "type" : "integer" - }, - "description" : "The current page the results are in" - }, - "X-Has-Next-Page" : { - "schema" : { - "type" : "boolean" - }, - "description" : "Returns whether there is a next page. This is normally always returned, whether total count is enabled or not. If the total count is not returned, is the only way for clients to know whether more results are available or not." - } - }, + "description" : "The advertisement interest data.", "content" : { "application/json" : { "schema" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/UserAlert" - } + "$ref" : "#/components/schemas/AdInterestDataForEdit" } } } @@ -32910,12 +44302,15 @@ } } }, - "/alerts/user/data-for-search" : { + "/marketplace-interests/{id}" : { + "parameters" : [ { + "$ref" : "#/components/parameters/id" + } ], "get" : { - "operationId" : "getUserAlertDataForSearch", - "summary" : "Returns configuration data for searching user alerts.", - "description" : "Returns configuration data for searching user alerts.", - "tags" : [ "Alerts" ], + "operationId" : "viewAdInterest", + "summary" : "Returns details of an advertisement interest.", + "description" : "Returns details of an advertisement interest.", + "tags" : [ "AdInterests" ], "security" : [ { "basic" : [ ] }, { @@ -32928,11 +44323,168 @@ } ], "responses" : { "200" : { - "description" : "The data for searching user alerts", + "description" : "The advertisement interest data.", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/UserAlertDataForSearch" + "$ref" : "#/components/schemas/AdInterestView" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + } + }, + "put" : { + "operationId" : "updateAdInterest", + "summary" : "Updates an existing advertisement interest.", + "description" : "Updates an existing advertisement interest.", + "tags" : [ "AdInterests" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "responses" : { + "204" : { + "description" : "The advertisement interest was updated." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConflictError" + } + } + } + }, + "401" : { + "description" : "Unauthorized access. Missing or invalid crendentials supplied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/UnauthorizedError" + } + } + } + }, + "403" : { + "description" : "Permission denied for such operation", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ForbiddenError" + } + } + } + }, + "404" : { + "description" : "An expected data was not found", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NotFoundError" + } + } + } + }, + "422" : { + "description" : "Input error. Either a validation error or the maximum allowed items was exceeded", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/InputError" + } + } + } + }, + "500" : { + "description" : "Unexpected error", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Error" + } + } + } + } + }, + "requestBody" : { + "description" : "The advertisement interest to be edited.", + "required" : true, + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/AdInterestEdit" + } + } + } + } + }, + "delete" : { + "operationId" : "deleteAdInterest", + "summary" : "Removes an advertisement interest.", + "description" : "Removes an advertisement interest.", + "tags" : [ "AdInterests" ], + "security" : [ { + "basic" : [ ] + }, { + "session" : [ ] + }, { + "accessClient" : [ ] + } ], + "responses" : { + "204" : { + "description" : "The advertisement interest was removed." + }, + "409" : { + "description" : "This operation expected an entity state, but it has resulted in a conflict", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConflictError" } } } @@ -32986,7 +44538,7 @@ "basic" : { "type" : "http", "scheme" : "basic", - "description" : "User and password, which are sent on every request (stateless). The user identification, commonly referred as principal, can be, according to the settings in Cyclos:\n\n- Login name;\n\n- E-mail;\n\n- Mobile phone;\n\n- Account number;\n\n- Custom field (fields configured as principal type in Cyclos);\n\n- Pin (see below for more details).\n\n\nThere is a configuration in Cyclos, under System > Configurations > Channels (tab) > Channel that specifies which identification methods (principal types) are allowed for that channel. There is also a setting for the default. When a specific principal type is not given, if there is a 'Default user identification method', that one is used. If there's no default, all possible principal types are attempted.\n\n\nTo specify the principal type, set the HTTP header `Principal-Type`, containing the principal type internal name. If there is a default set in the channel configuration, but still you want all types to be attempted, pass `*` in the `Principal-Type` header.\n\n\nIt is also possible to access with a device PIN. To do so, first activate a device PIN, which will result in both a PIN principal value (identifier) and a cryptographic salt. Then, to authenticate as PIN, set the `Principal-Type` header to `#` and send the `Authorization` header with value: `Basic base64(principal:salt+PIN)`." + "description" : "User and password, which are sent on every request (stateless). The user identification, commonly referred as principal, can be, according to the settings in Cyclos:\n\n- Login name;\n- E-mail;\n- Mobile phone;\n- Account number;\n- Custom field (fields configured as principal type in Cyclos);\n- Pin (see below for more details).\n\nThere is a configuration in Cyclos, under System > Configurations > Channels (tab) > Channel that specifies which identification methods (principal types) are allowed for that channel. There is also a setting for the default. When a specific principal type is not given, if there is a 'Default user identification method', that one is used. If there's no default, all possible principal types are attempted.\n\nTo specify the principal type, set the HTTP header `Principal-Type`, containing the principal type internal name. If there is a default set in the channel configuration, but still you want all types to be attempted, pass `*` in the `Principal-Type` header.\n\nIt is also possible to access with a device PIN. To do so, first activate a device PIN, which will result in both a PIN principal value (identifier) and a cryptographic salt. Then, to authenticate as PIN, set the `Principal-Type` header to `#` and send the `Authorization` header with value: `Basic base64(principal:salt+PIN)`." }, "session" : { "type" : "apiKey", @@ -32999,6 +44551,11 @@ "name" : "Access-Client-Token", "in" : "header", "description" : "Access via an access client token, which is obtained when the client is activated. This token is passed in as a header on every request (stateless)." + }, + "oidc" : { + "type" : "openIdConnect", + "openIdConnectUrl" : "http://localhost:8888/.well-known/openid-configuration", + "description" : "OAuth2 / OpenID Connect authentication. Clients must be previously registered in Cyclos. Then they request an authorization using the standard OAuth2 / OpenID Connect authorization endpoint at `http://localhost:8888/api/oidc/authorize`. When the OpenID Connect standard scope `openid` is requested, the flow will follow the OpenID Connect specification, allowing `id_token`s to be issued. Otherwise, plain OAuth2 authorization will be granted. The obtained access token should be passed in the `Authorization: Bearer ` request header to access the API." } }, "parameters" : { @@ -33039,13 +44596,12 @@ "type" : "string" } }, - "description" : "Select which fields to include on returned data. If nothing is set, all object fields are returned. Unprefixed field names will be handled like a whitelist (only listed fields will be included), while names starting with a minus (-) or exclamation mark (!) will be handled as blacklist (listed fields will not be included). This works for nesting as well. For example: `a,b.b1,c.-c1,c.-c2` will return the fields `a`, `b` (containing only the `b1` field) and `c` (containing all its fields except for `c1` or `c2`)." + "description" : "Select which fields to include on returned data. On the beginning of this page is an explanation on how this parameter works." }, "customFields" : { "name" : "customFields", "required" : false, "in" : "query", - "style" : "simple", "schema" : { "type" : "array", "items" : { @@ -33093,6 +44649,15 @@ }, "description" : "The object identification" }, + "format" : { + "name" : "format", + "required" : true, + "in" : "path", + "description" : "The format to export the data", + "schema" : { + "type" : "string" + } + }, "order" : { "name" : "order", "required" : true, @@ -33178,11 +44743,6 @@ } }, "schemas" : { - "AccountHistoryOrderByEnum" : { - "description" : "Contains the possible 'order by' values when searching for transfers\nPossible values are:\n- `amountAsc`: The result is ordered by amount descendant\n- `amountDesc`: The result is ordered by amount descendant\n- `dateAsc`: The result is ordered by date ascendant\n- `dateDesc`: The result is ordered by date descendant\n", - "type" : "string", - "enum" : [ "amountAsc", "amountDesc", "dateAsc", "dateDesc" ] - }, "AccountKind" : { "description" : "Indicates whether an account belongs to system or user\nPossible values are:\n- `system`: System account, there is only one account per type in the system. Managed only by administrators\n- `user`: User account, there is one account of this type per user.\n", "type" : "string", @@ -33198,11 +44758,6 @@ "type" : "string", "enum" : [ "images", "simple" ] }, - "AdDeliveryMethodChargeEnum" : { - "description" : "The possible charge types for a delivery method of a webshop ad.\nPossible values are:\n- `fixed`: The delivery method charge is fixed set by the seller.\n- `negotiated`: The delivery method charge can be be negotiated between the seller and the buyer.\n", - "type" : "string", - "enum" : [ "fixed", "negotiated" ] - }, "AdKind" : { "description" : "The possible kinds of an advertisement\nPossible values are:\n- `simple`: A simple advertisement that can be viewed, but not directly bought\n- `webshop`: An advertisement that is part of an webshop. Can be bought, there is stock management, etc.\n", "type" : "string", @@ -33328,15 +44883,30 @@ "type" : "string", "enum" : [ "dmyDash", "dmyPeriod", "dmySlash", "mdyDash", "mdyPeriod", "mdySlash", "ymdDash", "ymdPeriod", "ymdSlash" ] }, + "DeliveryMethodChargeTypeEnum" : { + "description" : "How the price is determined on this delivery method\nPossible values are:\n- `fixed`: The delivery method price will be fixed.\n- `negotiated`: The delivery method price will be negotiated between the seller and the buyer.\n", + "type" : "string", + "enum" : [ "fixed", "negotiated" ] + }, + "DeviceActionEnum" : { + "description" : "Possible actions that could be confirmed with a device for another device\nPossible values are:\n- `activate`: Activate a device as trusted\n- `remove`: Remove the trusted device\n", + "type" : "string", + "enum" : [ "activate", "remove" ] + }, + "DeviceActivationEnum" : { + "description" : "Contains useful information needed when a device is being activated as trusted\nPossible values are:\n- `disabled`: The activation is not required but the user can not activate a device as trusted because it does not have any mediums to receive the activation code or the session is already trusted\n- `optional`: The activation is not required and the user can activate a device by code\n- `required`: The activation is required with an activation code\n- `requiredNoMediums`: The activation is required but the user can not activate a device as trusted because it does not have any mediums to receive the activation code\n- `requiredWithDevice`: The activation is required with an existing trusted device\n", + "type" : "string", + "enum" : [ "disabled", "optional", "required", "requiredNoMediums", "requiredWithDevice" ] + }, "DeviceConfirmationStatusEnum" : { "description" : "The possible status for a device confirmation\nPossible values are:\n- `approved`: The confirmation was approved through a trusted device\n- `pending`: The confirmation is pending for approval through a trusted device\n- `rejected`: The confirmation was rejected through a trusted device\n", "type" : "string", "enum" : [ "approved", "pending", "rejected" ] }, "DeviceConfirmationTypeEnum" : { - "description" : "Contains all possible device confirmation types\nPossible values are:\n- `acceptOrder`: A confirmation for accepting a pending order as buyer\n- `approveTicket`: A confirmation for approving a pending ticket as payer\n- `buyVouchers`: A confirmation for buying vouchers\n- `changeAccountLimits`: A confirmation for change the account limits of a user account\n- `chargeback`: A confirmation for transfer chargeback\n- `clientAction`: A confirmation for an action over an access client\n- `editProfile`: A confirmation for editing the profile of his own\n- `generatePassword`: A confirmation for generating a new password\n- `generateVouchers`: A confirmation for generating vouchers\n- `importPayments`: A confirmation for importin payments as admin\n- `importUserPayments`: A confirmation for batch payments as user\n- `manageAddress`: A confirmation for managing an user address of his own\n- `manageAuthorization`: A confirmation for managing a pending payment authorization\n- `manageContactInfo`: A confirmation for managing an additional contact information of his own\n- `manageExternalPayment`: A confirmation for managing an external payment\n- `manageFailedOccurrence`: A confirmation for managing a recurring payment failed occurrence\n- `manageInstallment`: A confirmation for managing a scheduled payment installment\n- `managePaymentRequest`: A confirmation for managing a payment request\n- `managePhone`: A confirmation for managing a phone of his own\n- `manageRecurringPayment`: A confirmation for managing a recurring payment\n- `manageScheduledPayment`: A confirmation for managing a scheduled payment\n- `manageVoucher`: A confirmation for managing a voucher\n- `performExternalPayment`: A confirmation for performing an external payment\n- `performPayment`: A confirmation for performing a payment\n- `personalizeNfc`: A confirmation for personalizing a NFC tag\n- `runOperation`: A confirmation for running a custom operation\n- `secondaryLogin`: A confirmation for the secondary login\n- `shoppingCartCheckout`: A confirmation for the cart checkout\n", + "description" : "Contains all possible device confirmation types\nPossible values are:\n- `acceptOrder`: A confirmation for accepting a pending order as buyer\n- `approveTicket`: A confirmation for approving a pending ticket as payer\n- `buyVouchers`: A confirmation for buying vouchers\n- `changeAccountLimits`: A confirmation for change the account limits of a user account\n- `chargeback`: A confirmation for transfer chargeback\n- `clientAction`: A confirmation for an action over an access client\n- `editProfile`: A confirmation for editing the profile of his own\n- `generatePassword`: A confirmation for generating a new password\n- `generateVouchers`: A confirmation for generating vouchers\n- `importPayments`: A confirmation for importin payments as admin\n- `importUserPayments`: A confirmation for batch payments as user\n- `manageAddress`: A confirmation for managing an user address of his own\n- `manageAuthorization`: A confirmation for managing a pending payment authorization\n- `manageContactInfo`: A confirmation for managing an additional contact information of his own\n- `manageDevice`: A confirmation for managing a trusted device\n- `manageExternalPayment`: A confirmation for managing an external payment\n- `manageFailedOccurrence`: A confirmation for managing a recurring payment failed occurrence\n- `manageInstallment`: A confirmation for managing a scheduled payment installment\n- `managePaymentRequest`: A confirmation for managing a payment request\n- `managePhone`: A confirmation for managing a phone of his own\n- `manageRecurringPayment`: A confirmation for managing a recurring payment\n- `manageScheduledPayment`: A confirmation for managing a scheduled payment\n- `manageVoucher`: A confirmation for managing a voucher\n- `performExternalPayment`: A confirmation for performing an external payment\n- `performPayment`: A confirmation for performing a payment\n- `personalizeNfc`: A confirmation for personalizing a NFC tag\n- `runOperation`: A confirmation for running a custom operation\n- `secondaryLogin`: A confirmation for the secondary login\n- `shoppingCartCheckout`: A confirmation for the cart checkout\n", "type" : "string", - "enum" : [ "acceptOrder", "approveTicket", "buyVouchers", "changeAccountLimits", "chargeback", "clientAction", "editProfile", "generatePassword", "generateVouchers", "importPayments", "importUserPayments", "manageAddress", "manageAuthorization", "manageContactInfo", "manageExternalPayment", "manageFailedOccurrence", "manageInstallment", "managePaymentRequest", "managePhone", "manageRecurringPayment", "manageScheduledPayment", "manageVoucher", "performExternalPayment", "performPayment", "personalizeNfc", "runOperation", "secondaryLogin", "shoppingCartCheckout" ] + "enum" : [ "acceptOrder", "approveTicket", "buyVouchers", "changeAccountLimits", "chargeback", "clientAction", "editProfile", "generatePassword", "generateVouchers", "importPayments", "importUserPayments", "manageAddress", "manageAuthorization", "manageContactInfo", "manageDevice", "manageExternalPayment", "manageFailedOccurrence", "manageInstallment", "managePaymentRequest", "managePhone", "manageRecurringPayment", "manageScheduledPayment", "manageVoucher", "performExternalPayment", "performPayment", "personalizeNfc", "runOperation", "secondaryLogin", "shoppingCartCheckout" ] }, "DistanceUnitEnum" : { "description" : "Determines the unit used to measure distances\nPossible values are:\n- `kilometer`: Kilometer(s)\n- `mile`: Mile(s)\n", @@ -33398,15 +44968,20 @@ "type" : "string", "enum" : [ "autocomplete", "contacts", "principalType" ] }, + "IdentityProviderCallbackStatusEnum" : { + "description" : "The status the result of a callback from an identity provider.\nPossible values are:\n- `denied`: The user has denied the request. Generally nothing should be done, as the popup will be automatically closed.\n- `error`: There was an error. The `errorMessage` property is likely to contain the error description, though it can be empty. If so, a generic error message should be displayed.\n- `linked`: The currently logged user was successfully linked to the provider.\n- `loginEmail`: Successful login. No user was previously linked to this provider account, but a user was matched by e-mail and automatically linked. The `sessionToken` is returned.\n- `loginLink`: Successful login with a user was previously linked to the provider.\n- `loginNoEmail`: Similar to `loginNoMatch`, except that the identity provider hasn't returned / disclosed the user's e-mail address.\n- `loginNoMatch`: No matching user, either linked or by e-mail. If on the next login the `requestId` value is passed in, a link will be automatically created, so the next time the login works directly. The `sessionToken` is returned.\n- `registrationData`: The profile data was read and the available data has been returned.\n- `registrationDone`: The user was directly registered and logged-in. The `sessionToken` is returned.\n", + "type" : "string", + "enum" : [ "denied", "error", "linked", "loginEmail", "loginLink", "loginNoEmail", "loginNoMatch", "registrationData", "registrationDone" ] + }, "ImageKind" : { - "description" : "Determines the kind of an image\nPossible values are:\n- `contactInfo`: An image of an additional contact information\n- `customFieldValue`: An image used as custom field value\n- `marketplace`: Advertisement images are associated with an advertisement, be it simple or for web shop.\n- `marketplaceCategory`: An image of an advertisement (simple or webshop)\n- `profile`: User profile images are those associated with the user profile. The first profile image is used to depict the user on search results.\n- `systemCustom`: System custom images are additional images an administrator that can be used on rich text contents.\n- `temp`: A temporary image which can upload for later associating with an entity being registered (for example, user or advertisement).\n- `userCustom`: User custom images are additional images that can be used on rich text contents.\n- `voucherType`: An image of a voucher type\n", + "description" : "Determines the kind of an image\nPossible values are:\n- `contactInfo`: An image of an additional contact information\n- `customFieldValue`: An image used as custom field value\n- `identityProvider`: An external identity provider\n- `marketplace`: Advertisement images are associated with an advertisement, be it simple or for web shop.\n- `marketplaceCategory`: An image of an advertisement (simple or webshop)\n- `oidcClient`: An OpenID Connect client\n- `profile`: User profile images are those associated with the user profile. The first profile image is used to depict the user on search results.\n- `systemCustom`: System custom images are additional images an administrator that can be used on rich text contents.\n- `temp`: A temporary image which can upload for later associating with an entity being registered (for example, user or advertisement).\n- `userCustom`: User custom images are additional images that can be used on rich text contents.\n- `voucherType`: An image of a voucher type\n", "type" : "string", - "enum" : [ "contactInfo", "customFieldValue", "marketplace", "marketplaceCategory", "profile", "systemCustom", "temp", "userCustom", "voucherType" ] + "enum" : [ "contactInfo", "customFieldValue", "identityProvider", "marketplace", "marketplaceCategory", "oidcClient", "profile", "systemCustom", "temp", "userCustom", "voucherType" ] }, "ImageSizeEnum" : { - "description" : "The possible sizes of images. The actual pixel size depends on the configuration in Cyclos\nPossible values are:\n- `large`: Full image size\n- `medium`: Medium thumbnail\n- `small`: Small thumbnail\n", + "description" : "The possible sizes of images. The actual pixel size depends on the configuration in Cyclos\nPossible values are:\n- `large`: Full image size\n- `medium`: Medium thumbnail\n- `small`: Small thumbnail\n- `tiny`: Tiny thumbnail\n", "type" : "string", - "enum" : [ "large", "medium", "small" ] + "enum" : [ "large", "medium", "small", "tiny" ] }, "InitializeNfcErrorCode" : { "description" : "Application-specific error codes for an initialize NFC error\nPossible values are:\n- `tokenInUse`: The token specified for initialization is already in use (exists and it is active)\n- `unexpected`: An unexpected error has occurred. See the `exceptionType` and `exceptionMessage` fields for the internal information.\n", @@ -33423,6 +44998,11 @@ "type" : "string", "enum" : [ "process", "settle" ] }, + "InstallmentStatusEnum" : { + "description" : "The status of a installment\nPossible values are:\n- `blocked`: The installment is blocked, and won't be automatically processed on its due date\n- `canceled`: The installment was canceled\n- `failed`: The installment processing failed, for example, because there was no funds in the source account\n- `processed`: The installment was processed, generating a transfer\n- `scheduled`: The installment is scheduled for a future date\n- `settled`: The installment was marked as settled by the receiver\n", + "type" : "string", + "enum" : [ "blocked", "canceled", "failed", "processed", "scheduled", "settled" ] + }, "InvalidDeviceConfirmationEnum" : { "description" : "The possible results for an invalid device confirmation\nPossible values are:\n- `invalidConfirmation`: The confirmation being processed / checked was not found or not belongs to the authenticated user\n- `invalidDevice`: The trusted device used to approve / reject the confirmation was not found or is not associated to the authenticated user\n- `maxCheckAtemptsReached`: The maximum number of attempts to check for a processed (approved / rejected) device confirmation was reached. The logged user was blocked\n", "type" : "string", @@ -33479,7 +45059,7 @@ "enum" : [ "commaAsDecimal", "periodAsDecimal" ] }, "OperationPageContextEnum" : { - "description" : "The context an operation with `resultType` is `resultPage` runs\nPossible values are:\n- `csv`: Export results as Comma-Separated-Values (CSV)\n- `page`: Normal search, returning the data as rows in the result\n- `pdf`: Export results as printable PDF\n", + "description" : "DEPRECATED: Use `exportFormat` instead. The context an operation with `resultType` is `resultPage` runs\nPossible values are:\n- `csv`: Export results as Comma-Separated-Values (CSV)\n- `page`: Normal search, returning the data as rows in the result\n- `pdf`: Export results as printable PDF\n", "type" : "string", "enum" : [ "csv", "page", "pdf" ] }, @@ -33498,15 +45078,20 @@ "type" : "string", "enum" : [ "advertisement", "bulkAction", "contact", "contactInfo", "internal", "menu", "record", "system", "transfer", "user" ] }, + "OperationShowFormEnum" : { + "description" : "Determines in which conditions the parameters form is shown\nPossible values are:\n- `always`: Show form even if parameters are not missing\n- `missingAny`: Show form if any parameter (optional or required) is missing\n- `missingRequired`: Show form only if required parameters are missing\n", + "type" : "string", + "enum" : [ "always", "missingAny", "missingRequired" ] + }, "OperatorGroupAccountAccessEnum" : { - "description" : "How an owner account can be accessed by operators\nPossible values are:\n- `full`: The account is fully visible\n- `incoming`: All (and only) incoming payments are visible\n- `none`: The account is not visible\n- `outgoing`: All (and only) outgoing payments are visible\n- `own`: Only payments performed / received by the operators are visible\n", + "description" : "How an owner account can be accessed by operators\nPossible values are:\n- `full`: The account is fully visible\n- `incoming`: All incoming and own payments are visible\n- `none`: The account is not visible\n- `outgoing`: All outgoing and own payments are visible\n- `own`: Only payments performed / received by the operators are visible\n", "type" : "string", "enum" : [ "full", "incoming", "none", "outgoing", "own" ] }, "OrderStatusEnum" : { - "description" : "The possible statuses for an order\nPossible values are:\n- `completed`: The order was accepted by the seller and/or buyer and the related payment was done.\n- `disposed`: The order was marked as disposed because the seller and/or buyer were removed or they do not have any account in the order's currency.\n- `draft`: The order has been created by the seller, but has not yet been sent to the buyer for approval\n- `paymentCanceled`: The related payment was not done because was canceled after finish the authorization process.\n- `paymentDenied`: The related payment was not done because was denied.\n- `paymentExpired`: The related payment was not done because the pending authorization has expired.\n- `paymentPending`: The order was accepted by the seller and/or buyer and the related payment is waiting for authorization.\n- `pendingBuyer`: The order is pending by the buyer's action.\n- `pendingSeller`: The order is pending by the seller's action.\n- `rejectedByBuyer`: The order was rejected by the buyer.\n- `rejectedBySeller`: The order was rejected by the seller.\n", + "description" : "The possible statuses for an order\nPossible values are:\n- `completed`: The order was accepted by the seller and/or buyer and the related payment was done.\n- `disposed`: The order was marked as disposed because the seller and/or buyer were removed or they do not have any account in the order's currency.\n- `draft`: The order has been created by the seller, but has not yet been sent to the buyer for approval\n- `paymentCanceled`: The related payment was not done because was canceled after finish the authorization process.\n- `paymentDenied`: The related payment was not done because was denied.\n- `paymentExpired`: The related payment was not done because the pending authorization has expired.\n- `paymentPending`: The order was accepted by the seller and/or buyer and the related payment is waiting for authorization.\n- `pendingBuyer`: The order is pending by the buyer's action.\n- `pendingSeller`: The order is pending by the seller's action.\n- `rejectedByBuyer`: The order was rejected by the buyer.\n- `rejectedBySeller`: The order was rejected by the seller.\n- `shoppingCart`: The order is just a shopping cart, possibly temporary, as hasn't been checked out yet\n", "type" : "string", - "enum" : [ "completed", "disposed", "draft", "paymentCanceled", "paymentDenied", "paymentExpired", "paymentPending", "pendingBuyer", "pendingSeller", "rejectedByBuyer", "rejectedBySeller" ] + "enum" : [ "completed", "disposed", "draft", "paymentCanceled", "paymentDenied", "paymentExpired", "paymentPending", "pendingBuyer", "pendingSeller", "rejectedByBuyer", "rejectedBySeller", "shoppingCart" ] }, "OtpErrorCode" : { "description" : "Application-specific error codes for an OTP error.\nPossible values are:\n- `errorSendingSms`: An error has occurred trying to send the OTP through SMS.\n- `unexpected`: An unexpected error has occurred.\n", @@ -33569,9 +45154,9 @@ "enum" : [ "landLine", "mobile" ] }, "PhysicalTokenTypeEnum" : { - "description" : "The possible physical type for tokens. Determines how applications interact with hardware in order to read the token value.\nPossible values are:\n- `barcode`: A 1d barcode printed on a card\n- `nfcDevice`: A phone (or other device) with NFC support\n- `nfcTag`: A NFC tag, normally a DESFire NFC card\n- `other`: Other\n- `qrCode`: A QR-code\n- `swipe`: A swipe card\n", + "description" : "The possible physical type for tokens. Determines how applications interact with hardware in order to read the token value.\nPossible values are:\n- `barcode`: A 1d barcode printed on a card\n- `nfcTag`: A NFC tag, normally a DESFire NFC card\n- `other`: Other\n- `qrCode`: A QR-code\n- `swipe`: A swipe card\n", "type" : "string", - "enum" : [ "barcode", "nfcDevice", "nfcTag", "other", "qrCode", "swipe" ] + "enum" : [ "barcode", "nfcTag", "other", "qrCode", "swipe" ] }, "PosErrorCode" : { "description" : "Application-specific error codes for a POS operation error\nPossible values are:\n- `payerInaccessiblePrincipal`: The specified payer cannot use the given identification method (principal type) in the POS channel.\n- `payerNotInChannel`: The specified payer user does not participate on the POS channel.\n- `payerNotOperative`: The specified payer has some restriction that renders he/she inoperative for POS operations. An example of such case is when the user has pending agreements.\n- `unexpected`: An unexpected error has occurred. See the `exceptionType` and `exceptionMessage` fields for the internal information.\n", @@ -33594,9 +45179,9 @@ "enum" : [ "administrator", "broker", "member" ] }, "PushNotificationEventKind" : { - "description" : "Kind of events that can be triggered on push notifications\nPossible values are:\n- `accountStatus`: The account status (balance, reserved amount, etc) has changed\n- `deviceConfirmation`: A device confirmation was approved / rejected\n- `loggedOut`: The current session has been invalidated\n- `newMessage`: New message on the user's inbox\n- `newNotification`: New received notification\n- `ticket`: A ticket status has changed\n", + "description" : "Kind of events that can be triggered on push notifications\nPossible values are:\n- `accountStatus`: The account status (balance, reserved amount, etc) has changed\n- `deviceConfirmation`: A device confirmation was approved / rejected\n- `deviceConfirmationFeedback`: The result of an operation approved by a device confirmation\n- `identityProviderCallback`: An identity provider has returned profile data for the user\n- `loggedOut`: The current session has been invalidated\n- `newMessage`: New message on the user's inbox\n- `newNotification`: New received notification\n- `paymentAuthorization`: A payment authorization status has changed\n- `ticket`: A ticket status has changed\n", "type" : "string", - "enum" : [ "accountStatus", "deviceConfirmation", "loggedOut", "newMessage", "newNotification", "ticket" ] + "enum" : [ "accountStatus", "deviceConfirmation", "deviceConfirmationFeedback", "identityProviderCallback", "loggedOut", "newMessage", "newNotification", "paymentAuthorization", "ticket" ] }, "RecordKind" : { "description" : "The possible kinds of a record, which can either belong to system or to an user\nPossible values are:\n- `system`: The record belongs to the system, and is unrelated to an user\n- `user`: The record belongs to a specific user\n", @@ -33613,11 +45198,6 @@ "type" : "string", "enum" : [ "cancel" ] }, - "RecurringPaymentOccurrenceStatusEnum" : { - "description" : "The status of a recurring payment occurrence\nPossible values are:\n- `failed`: The occurrence has failed processing (probably because there was not enough funds in the payer account)\n- `processed`: The occurrence was correctly processed, generating a transfer\n", - "type" : "string", - "enum" : [ "failed", "processed" ] - }, "RecurringPaymentStatusEnum" : { "description" : "The status of a recurring payment\nPossible values are:\n- `canceled`: The recurring payment was manually canceled\n- `closed`: The recurring payment is closed, as the last scheduled occurrence was processed\n- `open`: The recurring payment is open, as there are more future occurrences\n", "type" : "string", @@ -33628,21 +45208,31 @@ "type" : "string", "enum" : [ "notAllowedForUser", "notAllowedForVoucher", "notAllowedToday", "notAllowedYet", "payment", "unexpected", "userBlocked" ] }, + "ReferenceDirectionEnum" : { + "description" : "The reference direction in relation to a given user\nPossible values are:\n- `given`: The reference was given from the given user to another user\n- `received`: The reference was received by the given user from another user\n", + "type" : "string", + "enum" : [ "given", "received" ] + }, + "ReferenceLevelEnum" : { + "description" : "The reference level represents the satisfaction level\nPossible values are:\n- `bad`: Unsatisfied\n- `good`: Satisfied\n- `neutral`: Neutral\n- `veryBad`: Very unsatisfied\n- `veryGood`: Very satisfied\n", + "type" : "string", + "enum" : [ "bad", "good", "neutral", "veryBad", "veryGood" ] + }, "RoleEnum" : { "description" : "The main role the user has.\nPossible values are:\n- `administrator`: A user who can manage the system and other users.\n- `broker`: A user who can manage other users.\n- `member`: A regular user who can manage operators.\n- `operator`: A \"sub-user\" created by a member to manage his data.\n", "type" : "string", "enum" : [ "administrator", "broker", "member", "operator" ] }, + "RunOperationResultColumnTypeEnum" : { + "description" : "The data type for a custom operation column\nPossible values are:\n- `boolean`: Each cell value is a boolean\n- `currencyAmount`: Each cell value is an object with 2 properties: amount (number represented as string) and currency (of type `Currency`)\n- `date`: Each cell value is a date represented as string\n- `number`: Each cell value is a number, but may be represented as string\n- `string`: Each cell value is a string\n", + "type" : "string", + "enum" : [ "boolean", "currencyAmount", "date", "number", "string" ] + }, "ScheduledPaymentActionEnum" : { "description" : "Possible actions that could be confirmed with a device for a scheduled payment\nPossible values are:\n- `block`: Block the scheduled payment\n- `cancel`: Cancel the scheduled payment\n- `settle`: Settle the scheduled payment\n- `unblock`: Unblock the scheduled payment\n", "type" : "string", "enum" : [ "block", "cancel", "settle", "unblock" ] }, - "ScheduledPaymentInstallmentStatusEnum" : { - "description" : "The status of a scheduled payment installment\nPossible values are:\n- `blocked`: The installment is blocked, and won't be automatically processed on its due date\n- `canceled`: The installment was canceled\n- `failed`: The installment processing failed, for example, because there was no funds in the source account\n- `processed`: The installment was processed, generating a transfer\n- `scheduled`: The installment is scheduled for a future date\n- `settled`: The installment was marked as settled by the receiver\n", - "type" : "string", - "enum" : [ "blocked", "canceled", "failed", "processed", "scheduled", "settled" ] - }, "ScheduledPaymentStatusEnum" : { "description" : "The status of a scheduled payment\nPossible values are:\n- `blocked`: The scheduled payment is blocked - won't have any installment processed until being unblocked again\n- `canceled`: The scheduled payment, as well as all open installments were canceled\n- `closed`: The scheduled payment is closed\n- `open`: The scheduled payment has open installments\n", "type" : "string", @@ -33674,9 +45264,9 @@ "enum" : [ "max", "min", "stock" ] }, "SystemAlertTypeEnum" : { - "description" : "The type of system alert\nPossible values are:\n- `accountFeeChargedNoFailures`: An account fee charge has finished without any failures\n- `accountFeeChargedWithFailures`: An account fee charge has finished with at least one failure\n- `applicationRestarted`: The application has been restarted, or started for the first time\n- `custom`: Custom alerts thrown by scripts\n- `maxGlobalSmsReached`: The groups under a certain configuration have run out of SMS messages\n- `maxIncorrectLoginAttempts`: Someone tried for a given number of tries to login with an invalid username\n", + "description" : "The type of system alert\nPossible values are:\n- `accountFeeChargedNoFailures`: An account fee charge has finished without any failures\n- `accountFeeChargedWithFailures`: An account fee charge has finished with at least one failure\n- `applicationRestarted`: The application has been restarted, or started for the first time\n- `custom`: Custom alerts thrown by scripts\n- `maxBlockedUsersReached`: The max number of users blocked from the same IP has been reached\n- `maxGlobalSmsReached`: The groups under a certain configuration have run out of SMS messages\n- `maxIncorrectLoginAttempts`: Someone tried for a given number of tries to login with an invalid username\n", "type" : "string", - "enum" : [ "accountFeeChargedNoFailures", "accountFeeChargedWithFailures", "applicationRestarted", "custom", "maxGlobalSmsReached", "maxIncorrectLoginAttempts" ] + "enum" : [ "accountFeeChargedNoFailures", "accountFeeChargedWithFailures", "applicationRestarted", "custom", "maxBlockedUsersReached", "maxGlobalSmsReached", "maxIncorrectLoginAttempts" ] }, "TempImageTargetEnum" : { "description" : "The possible targets for a temporary image\nPossible values are:\n- `advertisement`: The image will be used for an advertisement of a specific user\n- `contactInfo`: The image will be used for an additional contact information of a specific user\n- `customValue`: The image will be used for a value of a specific custom field\n- `userProfile`: The image will be used as a profile image for an existing user\n- `userRegistration`: The image will be used as a profile image for a newly registered user\n", @@ -33708,6 +45298,11 @@ "type" : "string", "enum" : [ "barcode", "nfcDevice", "nfcTag", "other", "qrcode", "swipe" ] }, + "TransOrderByEnum" : { + "description" : "Contains the possible 'order by' values when searching for transfers / transactions\nPossible values are:\n- `amountAsc`: The result is ordered by amount descendant\n- `amountDesc`: The result is ordered by amount descendant\n- `dateAsc`: The result is ordered by date ascendant\n- `dateDesc`: The result is ordered by date descendant\n", + "type" : "string", + "enum" : [ "amountAsc", "amountDesc", "dateAsc", "dateDesc" ] + }, "TransactionAuthorizationActionEnum" : { "description" : "An action performed when a transaction was pending authorization\nPossible values are:\n- `authorized`: The transaction was authorized\n- `canceled`: The authorization process was canceled by the payer/admin\n- `denied`: The transaction was denied (rejected)\n- `expired`: The authorization process has expired by system\n", "type" : "string", @@ -33739,9 +45334,9 @@ "enum" : [ "credit", "debit" ] }, "TransferKind" : { - "description" : "Indicates the reason the transfer was created\nPossible values are:\n- `accountFee`: A transfer generated by an account fee charge\n- `chargeback`: A transfer which is a chargeback of another transfer\n- `import`: An imported transfer\n- `initialCredit`: A transfer which is the initial credit for a newly created account\n- `payment`: A transfer generated by a direct payment or accepting a webshop order\n- `recurringPayment`: A transfer generated when processing a recurring payment\n- `scheduledPaymentInstallment`: A transfer generated when processing a scheduled payment installment\n- `transferFee`: A transfer generated by a transfer fee charge\n", + "description" : "Indicates the reason the transfer was created\nPossible values are:\n- `accountFee`: A transfer generated by an account fee charge\n- `chargeback`: A transfer which is a chargeback of another transfer\n- `import`: An imported transfer\n- `initialCredit`: A transfer which is the initial credit for a newly created account\n- `installment`: A transfer generated when processing a scheduled / recurring payment installment / occurrence\n- `payment`: A transfer generated by a direct payment or accepting a webshop order\n- `transferFee`: A transfer generated by a transfer fee charge\n", "type" : "string", - "enum" : [ "accountFee", "chargeback", "import", "initialCredit", "payment", "recurringPayment", "scheduledPaymentInstallment", "transferFee" ] + "enum" : [ "accountFee", "chargeback", "import", "initialCredit", "installment", "payment", "transferFee" ] }, "UiKind" : { "description" : "Indicates the type of user interface\nPossible values are:\n- `custom`: A custom front-end application. Has no headers, footers or theme\n- `main`: The main web user interface\n- `mobile`: The mobile application user interface\n- `pay`: The Ticket / Easy invoice confirmation application user interface\n", @@ -33749,9 +45344,9 @@ "enum" : [ "custom", "main", "mobile", "pay" ] }, "UnauthorizedErrorCode" : { - "description" : "Error codes for 401 Unauthorized HTTP status.\nPossible values are:\n- `blockedAccessClient`: The access client used for access is blocked\n- `invalidAccessClient`: The access client used for access is invalid\n- `invalidChannelUsage`: Attempt to login on a stateless-only channel, or use stateless in a stateful-only channel, or invoke as guest in a channel configuration which is only for users\n- `invalidNetwork`: Attempt to access a network that has been disabled\n- `loggedOut`: The session token used for access is invalid\n- `login`: Either user identification (principal) or password are invalid. May have additional information, such as the user / password status\n- `missingAuthorization`: Attempt to access an operation as guest, but the operation requires authentication\n- `remoteAddressBlocked`: The IP address being used for access has been blocked by exceeding tries with invalid users\n- `unauthorizedAddress`: The user cannot access the system using an IP address that is not white-listed\n- `unauthorizedUrl`: The user's configuration demands access using a specific URL, and this access is being done using another one\n", + "description" : "Error codes for 401 Unauthorized HTTP status.\nPossible values are:\n- `blockedAccessClient`: The access client used for access is blocked\n- `invalidAccessClient`: The access client used for access is invalid\n- `invalidAccessToken`: The OAuth2 / OpenID Connect access token used for access is invalid\n- `invalidChannelUsage`: Attempt to login on a stateless-only channel, or use stateless in a stateful-only channel, or invoke as guest in a channel configuration which is only for users\n- `invalidNetwork`: Attempt to access a network that has been disabled\n- `loggedOut`: The session token used for access is invalid\n- `login`: Either user identification (principal) or password are invalid. May have additional information, such as the user / password status\n- `missingAuthorization`: Attempt to access an operation as guest, but the operation requires authentication\n- `remoteAddressBlocked`: The IP address being used for access has been blocked by exceeding tries with invalid users\n- `unauthorizedAddress`: The user cannot access the system using an IP address that is not white-listed\n- `unauthorizedUrl`: The user's configuration demands access using a specific URL, and this access is being done using another one\n", "type" : "string", - "enum" : [ "blockedAccessClient", "invalidAccessClient", "invalidChannelUsage", "invalidNetwork", "loggedOut", "login", "missingAuthorization", "remoteAddressBlocked", "unauthorizedAddress", "unauthorizedUrl" ] + "enum" : [ "blockedAccessClient", "invalidAccessClient", "invalidAccessToken", "invalidChannelUsage", "invalidNetwork", "loggedOut", "login", "missingAuthorization", "remoteAddressBlocked", "unauthorizedAddress", "unauthorizedUrl" ] }, "UserAddressResultEnum" : { "description" : "Determines which address is returned on the search, if any. By default no addresses are returned. This option is useful for displaying results as locations on a map. In all cases only located addresses (those that have the geographical coordinates set) are returned. When returning all addresses, data related with multiple addresses is returned multiple times.\nPossible values are:\n- `all`: All addresses are returned.\n- `nearest`: The nearest address from the reference location is returned. Only usable if a reference coordinate (`latitude` and `longitude`)\n- `none`: Addresses are not returned.\n- `primary`: The primary (default) user address is returned\n", @@ -33763,6 +45358,11 @@ "type" : "string", "enum" : [ "custom", "givenVeryBadRefs", "insufficientBalanceForInitialCredit", "maxDeviceActivationAttemptsReached", "maxDeviceConfirmationCheckAttemptsReached", "maxTokenActivationAttemptsReached", "maxUserLocalizationAttemptsReached", "maxVoucherRedeemAttemptsReached", "moveUserAutomaticallyFailed", "passwordDisabledByTries", "passwordTemporarilyBlocked", "receivedVeryBadRefs", "scheduledPaymentFailed" ] }, + "UserIdentityProviderStatusEnum" : { + "description" : "The status of a link between a user and an identity provider\nPossible values are:\n- `disabled`: The identity provider is disabled for the user, which means that the login with external provider will not work even if the user has the same e-mail address in the provider and in Cyclos.\n- `linked`: The identity provider is linked to the user\n- `notLinked`: The identity provider is not currently linked with the user\n", + "type" : "string", + "enum" : [ "disabled", "linked", "notLinked" ] + }, "UserImageKind" : { "description" : "Determines the kind of an user image\nPossible values are:\n- `custom`: User custom images are additional images that can be used on rich text contents.\n- `profile`: User profile images are those associated with the user profile. The first profile image is used to depict the user on search results.\n", "type" : "string", @@ -33813,6 +45413,11 @@ "type" : "string", "enum" : [ "bought", "generated" ] }, + "VoucherOrderByEnum" : { + "description" : "The voucher search result order\nPossible values are:\n- `creationDateAsc`: Order by creation date, ascending\n- `creationDateDesc`: Order by creation date, descending (default)\n- `expirationDateAsc`: Order by expiration date, ascending\n- `expirationDateDesc`: Order by expiration date, descending\n- `redeemDateAsc`: Order by redeem date, ascending, then expiration date, ascending\n- `redeemDateDesc`: Order by redeem date, descending, then expiration date, descending\n", + "type" : "string", + "enum" : [ "creationDateAsc", "creationDateDesc", "expirationDateAsc", "expirationDateDesc", "redeemDateAsc", "redeemDateDesc" ] + }, "VoucherRelationEnum" : { "description" : "The ways a voucher is related to an user\nPossible values are:\n- `bought`: A voucher the user has bought\n- `redeemed`: A voucher the user has redeemed\n", "type" : "string", @@ -34018,9 +45623,18 @@ } }, "broker" : { - "description" : "Either the ids or identification methods of users' broker", + "description" : "DEPRECATED: Use `brokers` instead. Will be removed in 4.14. Either the ids or identification methods of users' broker", + "deprecated" : true, + "x-remove-version" : 4.14, "type" : "string" }, + "brokers" : { + "description" : "Either the ids or identification methods of users' broker", + "type" : "array", + "items" : { + "type" : "string" + } + }, "user" : { "description" : "Either the id or identifier of the account owner", "type" : "string" @@ -34092,35 +45706,18 @@ "AccountHistoryResult" : { "description" : "Represents a balance transfer between accounts, as viewed from the point-of-view account of a a specific account. This means that credits will have a positive amount, while debits will be negative.", "allOf" : [ { - "$ref" : "#/components/schemas/Entity" + "$ref" : "#/components/schemas/TransResult" }, { "type" : "object", "properties" : { - "date" : { - "description" : "The transfer date and time", - "type" : "string", - "format" : "date-time" - }, - "amount" : { - "description" : "The transfer amount. May be positive or negative.", - "type" : "string", - "format" : "number" - }, "relatedAccount" : { "description" : "The account that either received / sent the balance", "allOf" : [ { "$ref" : "#/components/schemas/AccountWithOwner" } ] }, - "type" : { - "$ref" : "#/components/schemas/TransferType" - }, - "description" : { - "description" : "The transaction description. Is optional.", - "type" : "string" - }, - "transactionNumber" : { - "description" : "The transaction number identifying this balance transfer. The currency configuration has the definition on whether transaction numbers are enabled and which format they have.", + "relatedName" : { + "description" : "Contains an optional custom from / to name, which can be set when the transaction is performed.", "type" : "string" }, "customValues" : { @@ -34131,7 +45728,7 @@ } }, "transaction" : { - "description" : "If this balance transfer was originated from a transaction (like a payment or scheduled payment), contains the reference to this transaction.", + "description" : "If this balance transfer was originated from a transaction (like a payment or scheduled payment), contains the a simple reference to this transaction.\nWARNING: The only fields that will be filled-in are `id`, `transactionNumber` and `kind`.", "allOf" : [ { "$ref" : "#/components/schemas/Transaction" } ] @@ -34346,7 +45943,7 @@ "AccountWithHistoryStatus" : { "description" : "Account data plus account history status information", "allOf" : [ { - "$ref" : "#/components/schemas/AccountWithCurrency" + "$ref" : "#/components/schemas/AccountWithOwnerAndCurrency" }, { "type" : "object", "properties" : { @@ -34375,6 +45972,19 @@ } } ] }, + "AccountWithOwnerAndCurrency" : { + "description" : "Contains account data, plus owner and currency reference", + "allOf" : [ { + "$ref" : "#/components/schemas/AccountWithOwner" + }, { + "type" : "object", + "properties" : { + "currency" : { + "$ref" : "#/components/schemas/Currency" + } + } + } ] + }, "AccountWithStatus" : { "description" : "Account data plus status information", "allOf" : [ { @@ -34434,7 +46044,7 @@ "type" : "object", "properties" : { "customFields" : { - "description" : "The possible advertisement custom fields", + "description" : "The possible editable advertisement custom fields", "type" : "array", "items" : { "$ref" : "#/components/schemas/CustomFieldDetailed" @@ -34444,8 +46054,20 @@ "description" : "Indicates whether advertisements require an authorization from the administration in order to be published for other users to see", "type" : "boolean" }, + "canCreateNew" : { + "description" : "Indicates whether the user can create a new advertisement (if not reached max setting)", + "type" : "boolean" + }, + "maxCategoriesPerAd" : { + "description" : "Indicates if user can select single or multiples categories per advertisement", + "type" : "integer" + }, + "maxImages" : { + "description" : "Indicates the maximum amount of images the user can upload for an advertisement", + "type" : "integer" + }, "categories" : { - "description" : "The advertisement categoriesn each with its children, forming a tree", + "description" : "The advertisement categories each with its children, forming a tree", "type" : "array", "items" : { "$ref" : "#/components/schemas/AdCategoryWithChildren" @@ -34457,6 +46079,35 @@ "items" : { "$ref" : "#/components/schemas/Address" } + }, + "currencies" : { + "description" : "The currencies the authenticated user may use to specify the advertisement price", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Currency" + } + }, + "kind" : { + "description" : "The advertisement kind this data is related to.", + "allOf" : [ { + "$ref" : "#/components/schemas/AdKind" + } ] + }, + "owner" : { + "description" : "The owner of the advertisement.", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "webshopSettings" : { + "$ref" : "#/components/schemas/WebshopSettings" + }, + "deliveryMethods" : { + "description" : "The available delivery methods. Only for webshops.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/DeliveryMethod" + } } } }, @@ -34500,6 +46151,9 @@ }, { "type" : "object", "properties" : { + "status" : { + "$ref" : "#/components/schemas/AdStatusEnum" + }, "edit" : { "type" : "boolean", "description" : "Indicates whether the current ad can be edited by the currently authenticated used." @@ -34508,6 +46162,11 @@ "type" : "boolean", "description" : "Indicates whether the current ad can be edited by the currently authenticated used." }, + "creationDate" : { + "description" : "The creation date the advertisement was created", + "type" : "string", + "format" : "date-time" + }, "advertisement" : { "description" : "The advertisement that is being edited", "allOf" : [ { @@ -34562,6 +46221,14 @@ "type" : "string" } }, + "hidePrice" : { + "description" : "Indicates whether show or not the advertisements price to guests", + "type" : "boolean" + }, + "hideOwner" : { + "description" : "Indicates whether show or not the advertisements owner to guests", + "type" : "boolean" + }, "query" : { "description" : "Default query filters to search advertisements", "allOf" : [ { @@ -34571,31 +46238,6 @@ } } ] }, - "AdDeliveryMethod" : { - "description" : "Contains delivery information used when do shopping.", - "allOf" : [ { - "$ref" : "#/components/schemas/NamedEntity" - }, { - "type" : "object", - "properties" : { - "deliveryTime" : { - "$ref" : "#/components/schemas/TimeInterval" - }, - "description" : { - "description" : "Description of the delivery method (if any).", - "type" : "string" - }, - "chargeAmount" : { - "description" : "The delivery method charge amount. Required if `chargeType` is `fixed`.", - "type" : "string", - "format" : "number" - }, - "chargeType" : { - "$ref" : "#/components/schemas/AdDeliveryMethodChargeEnum" - } - } - } ] - }, "AdDetailed" : { "x-abstract" : true, "description" : "Contains data which is common for `AdResult` and `AdView`", @@ -34655,8 +46297,205 @@ } } ] }, + "AdInterest" : { + "description" : "Reference to an advertisement interest", + "allOf" : [ { + "$ref" : "#/components/schemas/NamedEntity" + } ] + }, + "AdInterestBasicData" : { + "description" : "Contains data shared by both AdInterestDataForNew and AdInterestDataForEdit", + "type" : "object", + "properties" : { + "user" : { + "description" : "Reference to the owner of the advertisement interest", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "categories" : { + "description" : "Contains the list of possible categories for the advertisement interest", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/AdCategoryWithChildren" + } + }, + "currencies" : { + "description" : "Contains the list of possible currencies for the advertisement interest", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Currency" + } + } + } + }, + "AdInterestDataForEdit" : { + "description" : "Contains data for editing an exinsting advertisement interest", + "allOf" : [ { + "$ref" : "#/components/schemas/AdInterestBasicData" + }, { + "type" : "object", + "properties" : { + "edit" : { + "description" : "Can the authenticated user edit this advertisement interest?", + "type" : "boolean" + }, + "remove" : { + "description" : "Can the authenticated user remove this advertisement interest?", + "type" : "boolean" + }, + "adInterest" : { + "description" : "The advertisement interest populated with the current fields. This value can be modified and sent back on `PUT /marketplace-interest/{id}`.", + "allOf" : [ { + "$ref" : "#/components/schemas/AdInterestEdit" + } ] + } + } + } ] + }, + "AdInterestDataForNew" : { + "description" : "Contains data for creating a new advertisement interest", + "allOf" : [ { + "$ref" : "#/components/schemas/AdInterestBasicData" + }, { + "type" : "object", + "properties" : { + "adInterest" : { + "description" : "The advertisement interest populated with the default fields. This value can be modified and sent back on `POST /{user}/marketplace-interest`.", + "allOf" : [ { + "$ref" : "#/components/schemas/AdInterestNew" + } ] + } + } + } ] + }, + "AdInterestEdit" : { + "description" : "Fields for modifying an advertisement interest.", + "allOf" : [ { + "$ref" : "#/components/schemas/AdInterestManage" + }, { + "type" : "object", + "properties" : { + "version" : { + "type" : "integer", + "description" : "The version stamp for the current object, used for optimistic locking. When saving, the same version as previously received needs to be passed back. If no one else has saved the object, the version will match and the object will be updated. However, if someone other has saved the object, the version will no longer match, and an error will be raised. This is used to prevent multiple users (or processes) from updating the same object and unwilingly overridding the property values, leading to data loss." + } + } + } ] + }, + "AdInterestManage" : { + "description" : "Common fields for either creating or editing an advertisement interest", + "type" : "object", + "x-abstract" : true, + "properties" : { + "name" : { + "description" : "The name identifying this advertisement interest.", + "type" : "string" + }, + "kind" : { + "description" : "The kind of advertisements.", + "allOf" : [ { + "$ref" : "#/components/schemas/AdKind" + } ] + }, + "category" : { + "description" : "Either internal name or id of the advertisements category.", + "type" : "string" + }, + "keywords" : { + "type" : "array", + "items" : { + "type" : "string" + }, + "description" : "A set of keywords to match advertisements." + }, + "currency" : { + "description" : "Either internal name or id of the currency for price range.", + "type" : "string" + }, + "minPrice" : { + "description" : "Minimum price for advertisements.", + "type" : "string", + "format" : "number" + }, + "maxPrice" : { + "description" : "Maximum price for advertisements.", + "type" : "string", + "format" : "number" + }, + "user" : { + "description" : "Either internal id or other accepted identification (username, e-mail, etc) for the user to watch advertisements", + "type" : "string" + } + } + }, + "AdInterestNew" : { + "description" : "Fields for a new advertisement interest.", + "allOf" : [ { + "$ref" : "#/components/schemas/AdInterestManage" + } ] + }, + "AdInterestView" : { + "description" : "Details of an advertisement interest", + "allOf" : [ { + "$ref" : "#/components/schemas/AdInterest" + }, { + "type" : "object", + "properties" : { + "kind" : { + "description" : "The kind of advertisements.", + "allOf" : [ { + "$ref" : "#/components/schemas/AdKind" + } ] + }, + "category" : { + "description" : "The advertisements category.", + "allOf" : [ { + "$ref" : "#/components/schemas/AdCategoryWithParent" + } ] + }, + "keywords" : { + "type" : "array", + "items" : { + "type" : "string" + }, + "description" : "Set of keywords to match advertisements." + }, + "currency" : { + "description" : "Currency for the price range.", + "allOf" : [ { + "$ref" : "#/components/schemas/Currency" + } ] + }, + "minPrice" : { + "description" : "Minimum price for advertisements.", + "type" : "string", + "format" : "number" + }, + "maxPrice" : { + "description" : "Maximum price for advertisements.", + "type" : "string", + "format" : "number" + }, + "user" : { + "description" : "Owner of advertisements", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "edit" : { + "description" : "Can the authenticated user edit this advertisement interest?", + "type" : "boolean" + }, + "remove" : { + "description" : "Can the authenticated user remove this advertisement interest?", + "type" : "boolean" + } + } + } ] + }, "AdManage" : { - "description" : "Common fields for either creating or editing a advertisement", + "description" : "Common fields for either creating or editing a simple or webshop advertisement", "type" : "object", "x-abstract" : true, "properties" : { @@ -34706,7 +46545,46 @@ } }, "addresses" : { - "description" : "Ids of addresses (belogining to the advertisement owner) this dvertisement is available at.", + "description" : "Ids of addresses (belonging to the advertisement owner) this advertisement is available at.", + "type" : "array", + "items" : { + "type" : "string" + } + }, + "unlimitedStock" : { + "description" : "Whether the stock is unlimited or not. If true then it means there is always disponibility of the webshop and the `stockQuantity` and `minStockQuantityToNotify` are meaningless.", + "type" : "boolean" + }, + "stockQuantity" : { + "description" : "The quantity in stock (if `unlimitedStock` is false). Only for webshop.", + "type" : "string", + "format" : "number" + }, + "minStockQuantityToNotify" : { + "description" : "Reached this minimum limit a notification will be sent to the user indicating there is low stock for this webshop. Only for webshop.", + "type" : "string", + "format" : "number" + }, + "minAllowedInCart" : { + "description" : "Minimum quantity allowed in a shopping cart. Only for webshop.", + "type" : "string", + "format" : "number" + }, + "maxAllowedInCart" : { + "description" : "Maximum quantity allowed in a shopping cart. Only for webshop.", + "type" : "string", + "format" : "number" + }, + "allowDecimalQuantity" : { + "description" : "Whether a decimal quantity of this webshop can be added to the shopping cart or not.", + "type" : "boolean" + }, + "productNumber" : { + "description" : "The unique number assigned to this webshop. Required if it's not marked as generated in the user webshop settings. Only for webshop.", + "type" : "string" + }, + "deliveryMethods" : { + "description" : "Ids of delivery method (belonging to the advertisement owner) this advertisement has allowed.", "type" : "array", "items" : { "type" : "string" @@ -34759,7 +46637,7 @@ "broker" : { "type" : "string", "deprecated" : true, - "x-remove-at" : 4.14, + "x-remove-version" : 4.15, "description" : "DEPRECATED. Use `brokers` instead." }, "brokers" : { @@ -34804,13 +46682,26 @@ "type" : "string" }, "answerDate" : { - "description" : "The answer date and time.", + "description" : "The answer date and time (if any).", "type" : "string", "format" : "date-time" } } } ] }, + "AdQuestionQueryFilters" : { + "description" : "Definitions for unanswered questions search", + "allOf" : [ { + "$ref" : "#/components/schemas/QueryFilters" + }, { + "type" : "object", + "properties" : { + "kind" : { + "$ref" : "#/components/schemas/AdKind" + } + } + } ] + }, "AdQuestionView" : { "description" : "A question asked for an advertisement.", "allOf" : [ { @@ -34912,7 +46803,17 @@ "type" : "boolean" }, "canManage" : { - "description" : "Indicates if the authenticated user manage this advertisement", + "description" : "Use `canEdit` or `canRemove` instead.\n\n\nIndicates if the authenticated user manage this advertisement", + "deprecated" : true, + "x-remove-version" : 4.15, + "type" : "boolean" + }, + "canEdit" : { + "description" : "Indicates if the authenticated user can edit this advertisement", + "type" : "boolean" + }, + "canRemove" : { + "description" : "Indicates if the authenticated user can remove this advertisement. The owner of the ad with manage permissions can remove the advertisement regardless the ad status.", "type" : "boolean" }, "canBuy" : { @@ -34923,10 +46824,38 @@ "description" : "Indicates if the authenticated user can ask questions about this advertisement.", "type" : "boolean" }, + "canHide" : { + "description" : "Indicates if the authenticated user can hide this advertisement.", + "type" : "boolean" + }, + "canUnhide" : { + "description" : "Indicates if the authenticated user can unhide this advertisement.", + "type" : "boolean" + }, + "canSetAsDraft" : { + "description" : "Indicates if the authenticated user can set as draft an already authorized (published) advertisement.", + "type" : "boolean" + }, + "canRequestAuthorization" : { + "description" : "Indicates if the authenticated user can request for authorization for this advertisement.", + "type" : "boolean" + }, + "canApprove" : { + "description" : "Indicates if the authenticated user can authorize this advertisement (user managers only).", + "type" : "boolean" + }, + "canReject" : { + "description" : "Indicates if the authenticated user can reject this advertisement (user managers only).", + "type" : "boolean" + }, "questionsEnabled" : { "description" : "Indicates if the questions are anabled for the given advertisement.", "type" : "boolean" }, + "lastAuthorizationComments" : { + "description" : "The last comments set by a manager when rejecting or set as draft this advertisement. Only send if the advertisement requires authorization and the authenticated user can view the comments.", + "type" : "string" + }, "additionalImages" : { "type" : "array", "items" : { @@ -34963,7 +46892,7 @@ "description" : "The available delivery methods for this webshop ad.", "type" : "array", "items" : { - "$ref" : "#/components/schemas/AdDeliveryMethod" + "$ref" : "#/components/schemas/DeliveryMethod" } }, "productNumber" : { @@ -34976,6 +46905,14 @@ "items" : { "$ref" : "#/components/schemas/Operation" } + }, + "hidePrice" : { + "description" : "Indicates whether show or not this advertisement price to guests", + "type" : "boolean" + }, + "hideOwner" : { + "description" : "Indicates whether show or not this advertisement owner to guests", + "type" : "boolean" } } } ] @@ -35349,6 +47286,16 @@ } } ] }, + "AlertsPermissions" : { + "description" : "Permissions related to user alerts", + "type" : "object", + "properties" : { + "view" : { + "description" : "Whether the logged user can view user alerts or not", + "type" : "boolean" + } + } + }, "AmountSummary" : { "description" : "Contains summarized statistics over amounts", "type" : "object", @@ -35442,9 +47389,11 @@ } ] }, "recurringPayments" : { - "description" : "Recurring payments permissions", + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED: Recurring payment permissions are no longer separated from scheduled payment permissions. Use `scheduledPayments` instead.\n\nRecurring payments permissions", "allOf" : [ { - "$ref" : "#/components/schemas/RecurringPaymentsPermissions" + "$ref" : "#/components/schemas/ScheduledPaymentsPermissions" } ] }, "externalPayments" : { @@ -35464,6 +47413,18 @@ "allOf" : [ { "$ref" : "#/components/schemas/TicketsPermissions" } ] + }, + "searchGeneralTransfers" : { + "description" : "Can the authenticated admin / broker perform a general transfers search (all visible transfers, regardless of the user / account)?", + "type" : "boolean" + }, + "searchUsersWithBalances" : { + "description" : "Can the authenticated admin / broker search managed users together with their account balances?", + "type" : "boolean" + }, + "searchGeneralBalanceLimits" : { + "description" : "Can the authenticated admin / broker perform a general account balance limit search, for all visible accounts?", + "type" : "boolean" } } }, @@ -35686,6 +47647,10 @@ "description" : "Returns whether the current user has some agreements pending accept. If so, a call to `GET /agreements/pending` should be performed to get the content of the pending agreements, and then a `POST /agreements/pending{id_or_internal_name}` to accept each agreement.", "type" : "boolean" }, + "everAcceptedAgreements" : { + "description" : "Returns whether the current user has ever accepted any agreement. This is always false for operators, as operators themselves don't accept agreements. However, their owner members do.", + "type" : "boolean" + }, "expiredSecondaryPassword" : { "description" : "Returns whether the current secondary access password is expired. If so, the user will have to change the password, or all other actions will be denied.", "type" : "boolean" @@ -35763,14 +47728,6 @@ "$ref" : "#/components/schemas/Image" } }, - "linkedEntityValue" : { - "deprecated" : true, - "x-remove-version" : 4.13, - "description" : "Use one of the specific fields: - `userValue`: If the entity type is `user` - `recordValue`: If the entity type is `record` - `transactionValue`: If the entity type is `transaction` - `transferValue`: If the entity type is `transfer` - `adValue`: If the entity type is `advertisement`\n\n\nThe field value if the field type is `linkedEntity`.", - "allOf" : [ { - "$ref" : "#/components/schemas/InternalNamedEntity" - } ] - }, "adValue" : { "description" : "The field value if the field type is `linkedEntity` and the linked entity type is `advertisement`. If the currently set record is not accessible by the logged user, only the `name` field is sent, which contains the advertisement title.", "allOf" : [ { @@ -35804,6 +47761,106 @@ } } ] }, + "BaseInstallmentDataForSearch" : { + "x-abstract" : true, + "description" : "Contains common data used to search installments for a given owner", + "type" : "object", + "properties" : { + "exportFormats" : { + "description" : "The formats which the search results can be exported.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExportFormat" + } + }, + "groups" : { + "description" : "Groups that can be used to filter entries, so that only transfers from or to users of those groups are returned on search. Is only returned if the authenticated user is an administrator.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Group" + } + }, + "accountTypes" : { + "description" : "Visible account types from the given owner", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/AccountType" + } + }, + "canViewAuthorized" : { + "description" : "Can the authenticated user view authorized transactions of this owner?", + "type" : "boolean" + }, + "visibleKinds" : { + "description" : "Contains the transaction kinds the authenticated user can view over this owner. Only kinds that allow installments are returned.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionKind" + } + } + } + }, + "BaseInstallmentQueryFilters" : { + "x-abstract" : true, + "description" : "Base query filters for installments", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseTransactionOrInstallmentQueryFilters" + }, { + "type" : "object", + "properties" : { + "statuses" : { + "description" : "Possible statuses for installments.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/InstallmentStatusEnum" + } + } + } + } ] + }, + "BaseInstallmentResult" : { + "description" : "Base fields for an installment result", + "type" : "object", + "properties" : { + "status" : { + "description" : "The installment status.", + "allOf" : [ { + "$ref" : "#/components/schemas/InstallmentStatusEnum" + } ] + }, + "number" : { + "description" : "The installment number", + "type" : "integer" + }, + "totalInstallments" : { + "description" : "The total number of installments in the transaction. Only not returned if the installment belongs to a recurring payment with an unbound number of occurrences (until cancel).", + "type" : "integer" + }, + "dueDate" : { + "description" : "The installment due date", + "type" : "string", + "format" : "date-time" + }, + "amount" : { + "description" : "The installment amount.", + "type" : "string", + "format" : "number" + }, + "transactionNumber" : { + "description" : "When processed, is the transaction number of the generated transfer.", + "type" : "string" + }, + "transferDate" : { + "description" : "When processed, is the date of the generated transfer.", + "type" : "string", + "format" : "date-time" + }, + "transferId" : { + "description" : "When processed, is the id of the generated transfer.", + "type" : "string" + } + } + }, "BaseNfcError" : { "description" : "Base Error when work with a NFC card", "x-abstract" : true, @@ -35892,6 +47949,28 @@ } } ] }, + "BasePasswordType" : { + "description" : "Contains base definitions for a password type", + "allOf" : [ { + "$ref" : "#/components/schemas/InternalNamedEntity" + }, { + "type" : "object", + "properties" : { + "onlyNumeric" : { + "type" : "boolean", + "description" : "Indicates whether this password type only allows numbers as possible characters" + }, + "minLength" : { + "type" : "integer", + "description" : "Indicates the minimum length of characters allowed for a password definition" + }, + "maxLength" : { + "type" : "integer", + "description" : "Indicates the maximum length of characters allowed for a password definition" + } + } + } ] + }, "BaseRecordDataForSearch" : { "description" : "Common definitions for searching records", "x-abstract" : true, @@ -35940,6 +48019,49 @@ "items" : { "$ref" : "#/components/schemas/AddressQueryFieldEnum" } + }, + "exportFormats" : { + "description" : "The formats which the data can be exported", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExportFormat" + } + } + } + } ] + }, + "BaseReferenceDataForSearch" : { + "description" : "Configuration data for searching references", + "type" : "object", + "x-abstract" : true, + "properties" : { + "manage" : { + "description" : "Can the authenticated user manage returned references?", + "type" : "boolean" + } + } + }, + "BaseReferenceQueryFilters" : { + "description" : "common query filters for references", + "allOf" : [ { + "$ref" : "#/components/schemas/QueryFilters" + }, { + "type" : "object", + "properties" : { + "period" : { + "description" : "The minimum / maximum reference date", + "type" : "array", + "items" : { + "type" : "string", + "format" : "date-time" + } + }, + "levels" : { + "description" : "The levels to filter", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ReferenceLevelEnum" + } } } } ] @@ -35990,25 +48112,18 @@ "$ref" : "#/components/schemas/Group" } }, - "accessClients" : { - "description" : "References for access clients which can be used to filter entries by transfers generated by a specific access client", - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/EntityReference" - } - }, - "operators" : { - "description" : "References for operators, which can be used to filter entries by transfers performed or received by that specific operator", + "preselectedPeriods" : { + "description" : "Contains the pre-selected period filter ranges according to the Cyclos configuration", "type" : "array", "items" : { - "$ref" : "#/components/schemas/User" + "$ref" : "#/components/schemas/PreselectedPeriod" } }, - "preselectedPeriods" : { - "description" : "Contains the pre-selected period filter ranges according to the Cyclos configuration", + "exportFormats" : { + "description" : "The formats which the search results can be exported.", "type" : "array", "items" : { - "$ref" : "#/components/schemas/PreselectedPeriod" + "$ref" : "#/components/schemas/ExportFormat" } } } @@ -36063,9 +48178,18 @@ "type" : "string" }, "broker" : { - "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "description" : "DEPRECATED: Use `brokers` instead.\n\nReference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "string" }, + "brokers" : { + "description" : "Reference to the broker of users involved in transfers. Is only taken into account if authenticated as administrator.", + "type" : "array", + "items" : { + "type" : "string" + } + }, "channels" : { "description" : "Reference to the channel used to perform / receive the transfer. Only taken into account if authenticated as administrator.", "type" : "array", @@ -36102,6 +48226,222 @@ "type" : "string", "format" : "number" } + }, + "orderBy" : { + "$ref" : "#/components/schemas/TransOrderByEnum" + } + } + } ] + }, + "BaseTransactionDataForSearch" : { + "description" : "Contains data used to search transactions, either as an owner point of view or as overview.", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseTransDataForSearch" + }, { + "type" : "object", + "properties" : { + "accountTypes" : { + "description" : "Visible account types from the given owner", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/AccountType" + } + }, + "canViewAuthorized" : { + "description" : "Can the authenticated user view authorized transactions of this owner?", + "type" : "boolean" + }, + "visibleKinds" : { + "description" : "Contains the transaction kinds the authenticated user can view over this owner.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionKind" + } + } + } + } ] + }, + "BaseTransactionOrInstallmentQueryFilters" : { + "description" : "Base query filters for either transactions or installments", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseTransQueryFilters" + }, { + "type" : "object", + "properties" : { + "kinds" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionKind" + } + }, + "authorized" : { + "description" : "When set, will only return transactions that went through the authorization process (if true) or that never went through it (when false). In either case, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "type" : "boolean" + }, + "authorizationStatuses" : { + "description" : "Authorization statuses used as search criteria. When set, only kinds that can go through authorization are returned (`payment`, `order`, `recurringPayment` or `scheduledPayment`).", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransactionAuthorizationStatusEnum" + } + }, + "authorizationPerformedBy" : { + "description" : "Id or other identifier (login name, email, etc) of the user that performed an authorization action (authorize, deny or cancel).", + "type" : "string" + } + } + } ] + }, + "BaseTransactionQueryFilters" : { + "description" : "Base query filters for transactions", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseTransactionOrInstallmentQueryFilters" + }, { + "type" : "object", + "properties" : { + "ticketStatuses" : { + "description" : "Statuses used as search criteria applied only to transactions of kind `ticket`.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TicketStatusEnum" + } + }, + "recurringPaymentStatuses" : { + "description" : "Statuses used as search criteria applied only to transactions of kind `recurringPayment`. If this filter is not empty then pending recurring payments will be excluded from the result. Pending recurring payments does not have a status.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/RecurringPaymentStatusEnum" + } + }, + "scheduledPaymentStatuses" : { + "description" : "Statuses used as search criteria applied only to transactions of kind `scheduledPayment`. If this filter is not empty then pending scheduled payments will be excluded from the result. Pending scheduled payments does not have a status.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ScheduledPaymentStatusEnum" + } + }, + "paymentRequestStatuses" : { + "description" : "Statuses used as search criteria applied only to transactions of kind `paymentRequest`.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/PaymentRequestStatusEnum" + } + }, + "paymentRequestExpiration" : { + "description" : "The minimum / maximum date for payment request expiration. Only affects payment requests. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "type" : "array", + "items" : { + "type" : "string", + "format" : "date-time" + } + }, + "externalPaymentStatuses" : { + "description" : "Statuses used as search criteria applied only to transactions of kind `externalPayment`.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExternalPaymentStatusEnum" + } + } + } + } ] + }, + "BaseTransactionResult" : { + "description" : "Base fields for transaction result", + "allOf" : [ { + "$ref" : "#/components/schemas/TransResult" + }, { + "type" : "object", + "properties" : { + "kind" : { + "description" : "The transaction kind. For example, if the front end has distinct views for a regular payment, scheduled payment and so on, this information is useful to determine the actual view.", + "allOf" : [ { + "$ref" : "#/components/schemas/TransactionKind" + } ] + }, + "authorizationStatus" : { + "$ref" : "#/components/schemas/TransactionAuthorizationStatusEnum" + }, + "currency" : { + "description" : "Either internal name or id of the transaction currency.", + "type" : "string" + }, + "expirationDate" : { + "description" : "Only returned if the `kind` is either `paymentRequest`, `externalPayment` or `ticket`. The deadline for the payment to be processed. In case of `externalPayment` if no user is registered with either e-mail or mobile phone matching, it is canceled. The same is done in case of `ticket` if it is not accepted by any user.", + "type" : "string", + "format" : "date-time" + }, + "scheduledPaymentStatus" : { + "description" : "The scheduled payment status. Only returned if `kind` is `scheduledPayment`.", + "allOf" : [ { + "$ref" : "#/components/schemas/ScheduledPaymentStatusEnum" + } ] + }, + "installmentCount" : { + "description" : "The total number of installments. Only returned if `kind` is `scheduledPayment`.", + "type" : "integer" + }, + "processedInstallments" : { + "description" : "The number of processed installments. Only returned if `kind` is `scheduledPayment`.", + "type" : "integer" + }, + "firstInstallment" : { + "description" : "A reference to the first installment of this scheduled payment. Only returned if `kind` is `scheduledPayment`.", + "allOf" : [ { + "$ref" : "#/components/schemas/Installment" + } ] + }, + "firstOpenInstallment" : { + "description" : "A reference to the first installment which is still open. Only returned if `kind` is `scheduledPayment`.", + "allOf" : [ { + "$ref" : "#/components/schemas/Installment" + } ] + }, + "recurringPaymentStatus" : { + "description" : "The recurring payment status. Only returned if `kind` is `recurringPayment`.", + "allOf" : [ { + "$ref" : "#/components/schemas/RecurringPaymentStatusEnum" + } ] + }, + "occurrencesCount" : { + "description" : "The total number of occurrences to process. When null will be processed until manually canceled. Only returned if `kind` is `recurringPayment`.", + "type" : "integer" + }, + "nextOccurrenceDate" : { + "description" : "When the next recurring payment occurrence will be processed. Only returned if `kind` is `recurringPayment`.", + "type" : "string", + "format" : "date-time" + }, + "lastOccurrenceNumber" : { + "description" : "The number of the last processed occurrence", + "type" : "integer" + }, + "externalPaymentStatus" : { + "description" : "The external payment status. Only returned if `kind` is `externalPayment`.", + "allOf" : [ { + "$ref" : "#/components/schemas/ExternalPaymentStatusEnum" + } ] + }, + "toPrincipalType" : { + "description" : "The principal type an external payment was sent to. Only returned if `kind` is `externalPayment`.", + "allOf" : [ { + "$ref" : "#/components/schemas/EntityReference" + } ] + }, + "toPrincipalValue" : { + "description" : "The principal to which an external payment was sent to. Only returned if `kind` is `externalPayment`.", + "type" : "string" + }, + "paymentRequestStatus" : { + "description" : "The payment request status. Only returned if `kind` is `paymentRequest`.", + "allOf" : [ { + "$ref" : "#/components/schemas/PaymentRequestStatusEnum" + } ] + }, + "ticketStatus" : { + "description" : "The ticket status. Only returned if `kind` is `ticket`.", + "allOf" : [ { + "$ref" : "#/components/schemas/TicketStatusEnum" + } ] } } } ] @@ -36143,14 +48483,21 @@ }, "description" : "Transfer statuses used as search criteria. Each array element should be either the identifier or the status qualified internal name, composed by flow internal name, a dot, and the status internal name. For example, `loan.open` would be a valid internal name." }, - "transferKinds" : { + "kinds" : { + "description" : "The kind of transfers to return", "type" : "array", "items" : { "$ref" : "#/components/schemas/TransferKind" } }, - "orderBy" : { - "$ref" : "#/components/schemas/AccountHistoryOrderByEnum" + "transferKinds" : { + "description" : "DEPRECATED: Use `kinds` instead", + "deprecated" : true, + "x-remove-version" : 4.15, + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransferKind" + } } } } ] @@ -36200,6 +48547,13 @@ "items" : { "$ref" : "#/components/schemas/AddressQueryFieldEnum" } + }, + "exportFormats" : { + "description" : "The formats which the search results can be exported.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExportFormat" + } } } }, @@ -36227,13 +48581,17 @@ "description" : "Either id or internal name of a currency for the price" }, "priceRange" : { - "description" : "The minumum / maximum price. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "description" : "The minumum / maximum price. Used only if a currency is specified. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", "type" : "array", "items" : { "type" : "string", "format" : "number" } }, + "productNumber" : { + "type" : "string", + "description" : "Textual search for a product number for webshop only." + }, "hasImages" : { "type" : "boolean", "description" : "When set to `true` only advertisements with images are returned" @@ -36758,6 +49116,21 @@ } } }, + "ChangeVoucherExpirationDate" : { + "description" : "Parameters for changing the voucher expiration date.", + "type" : "object", + "properties" : { + "comments" : { + "description" : "A comment that can be set.", + "type" : "string" + }, + "newExpirationDate" : { + "description" : "The new voucher expiration date.", + "type" : "string", + "format" : "date-time" + } + } + }, "ClientView" : { "description" : "Details on an access client", "allOf" : [ { @@ -37221,6 +49594,9 @@ "description" : "Data for searching an user's contact list", "type" : "object", "properties" : { + "user" : { + "$ref" : "#/components/schemas/User" + }, "customFields" : { "description" : "The list of contact custom fields that are either to be used as search filter (if its internal name is present on `fieldsInSearch`) and / or in the result list (if its internal name is present on `fieldsInList`)", "type" : "array", @@ -37558,6 +49934,16 @@ "numberOfVouchers" : { "type" : "integer", "description" : "The number of vouchers to be generated. Required only if type is `generateVouchers` or `buyVouchers`." + }, + "deviceId" : { + "type" : "string", + "description" : "The id of a device. Required only if type is `manageDevice`." + }, + "deviceAction" : { + "description" : "The action being applied to the device. Required only if type is `manageDevice`.", + "allOf" : [ { + "$ref" : "#/components/schemas/DeviceActionEnum" + } ] } } }, @@ -37819,24 +50205,6 @@ "items" : { "type" : "string" } - }, - "allowedMimeTypes" : { - "description" : "Use `mimeTypes` instead.\n\n\nOnly applicable when the custom field type is `file`. Contains the possible built-in mime types allowed for the file being uploaded.", - "deprecated" : true, - "x-remove-version" : 4.13, - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/FileMimeTypeEnum" - } - }, - "otherMimeTypes" : { - "description" : "Use `mimeTypes` instead.\n\n\nOnly applicable when the custom field type is `file`and the `others` option was selected in `allowedMimeTypes`. Contains the other mime types allowed for the file being uploaded.", - "deprecated" : true, - "x-remove-version" : 4.13, - "type" : "array", - "items" : { - "type" : "string" - } } } } ] @@ -37911,7 +50279,21 @@ "type" : "object", "properties" : { "account" : { - "$ref" : "#/components/schemas/AccountWithCurrency" + "$ref" : "#/components/schemas/AccountWithOwnerAndCurrency" + }, + "accessClients" : { + "description" : "References for access clients which can be used to filter entries by transfers generated by a specific access client", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/EntityReference" + } + }, + "operators" : { + "description" : "References for operators, which can be used to filter entries by transfers performed or received by that specific operator", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/User" + } }, "transactionNumberMask" : { "description" : "If a transaction number is used for this account, is a pattern that represent it.", @@ -37969,6 +50351,13 @@ "items" : { "$ref" : "#/components/schemas/AccountType" } + }, + "exportFormats" : { + "description" : "The formats which the search results can be exported.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExportFormat" + } } } }, @@ -38195,6 +50584,13 @@ "$ref" : "#/components/schemas/DeviceConfirmationView" } ] }, + "identityProviders" : { + "description" : "The identity providers available for login", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/IdentityProvider" + } + }, "forgotPasswordCaptchaProvider" : { "description" : "If the forgot password request requires a captcha, will be the provider used to request one. Otherwise will be null.", "allOf" : [ { @@ -38225,7 +50621,10 @@ "$ref" : "#/components/schemas/DataForLogin" }, "dataForDeviceConfirmationApproval" : { - "$ref" : "#/components/schemas/DataForDeviceConfirmationApproval" + "description" : "Data for confirmation approval. Only sent if a device id was given when getting the guest data and it was not removed.", + "allOf" : [ { + "$ref" : "#/components/schemas/DataForDeviceConfirmationApproval" + } ] }, "groupsForRegistration" : { "description" : "The list of groups the authenticated user can use to perform a new user registration", @@ -38277,10 +50676,6 @@ "$ref" : "#/components/schemas/UIElementWithContent" } ] }, - "mapBrowserApiKey" : { - "description" : "The Google Maps browser API key", - "type" : "string" - }, "pages" : { "description" : "The visible mobile pages", "type" : "array", @@ -38300,9 +50695,17 @@ "type" : "boolean" }, "canActivateAsTrustedDevice" : { - "description" : "Indicates whether there is an allowed medium to activate the device as trusted", + "x-remove-version" : 4.15, + "deprecated" : true, + "description" : "DEPRECATED: Use `deviceActivationMode` instead. Will be removed in 4.15. Indicates whether there is an allowed medium to activate the device as trusted", "type" : "boolean" }, + "deviceActivationMode" : { + "description" : "Contains information needed when the authenticated user wants to activate a device as trusted.", + "allOf" : [ { + "$ref" : "#/components/schemas/DeviceActivationEnum" + } ] + }, "personalizeOtherUsers" : { "description" : "Indicates if the current user can personalize NFC tags for other users (as member)", "type" : "boolean" @@ -38550,6 +50953,16 @@ "description" : "The mobile app url in the Play store.", "type" : "string" }, + "hideUserSearchInMenu" : { + "description" : "Whether the search users action must be shown or not in the menu. If the user doesn't have permission to search other users (`permissions.users.search`) then this flag will be `true`. Otherwise it depends on the configuration", + "type" : "boolean" + }, + "deviceActivationMode" : { + "description" : "Contains information needed when the authenticated user wants to activate a device as trusted.", + "allOf" : [ { + "$ref" : "#/components/schemas/DeviceActivationEnum" + } ] + }, "theme" : { "description" : "The theme content (i.e the CSS or its components according). Only returned when changed or if the corresponding `themeIf` parameter was not specified.\nThe returned theme will be the following according to the UI kind:\n\n- `main`: If there is a logged user then the theme for\n users associated to the configuration. Otherwise the theme for guests;\n\n- `mobile`: only returned for guest;\n- `pay`: The theme defined for the ticket / easy\n invoice confirmation application interface (it's the same for logged\n users and guests).", "allOf" : [ { @@ -38567,6 +50980,10 @@ "allOf" : [ { "$ref" : "#/components/schemas/UIElementWithContent" } ] + }, + "shoppingCartWebShopCount" : { + "description" : "The total number of webshop ads present in the shopping cart. Not returned for guests.", + "type" : "integer" } } }, @@ -38597,11 +51014,8 @@ "description" : "Contains the data used to manage passwords of a user", "type" : "object", "properties" : { - "confirmationPasswordInput" : { - "description" : "If a confirmation password is used, contains the definitions on how to request that password from the user. This confirmation password is required when performing sensible actions. Sometimes this is dynamic, for example, the confirmation might be configured to be used only once per session, or operations like payments may have a limit per day to be without confirmation (pinless).", - "allOf" : [ { - "$ref" : "#/components/schemas/PasswordInput" - } ] + "user" : { + "$ref" : "#/components/schemas/User" }, "passwords" : { "description" : "The status and possible actions for each password", @@ -38615,6 +51029,12 @@ "allOf" : [ { "$ref" : "#/components/schemas/DataForSetSecurityAnswer" } ] + }, + "confirmationPasswordInput" : { + "description" : "If a confirmation password is used, contains the definitions on how to request that password from the user. This confirmation password is required when performing sensible actions. Sometimes this is dynamic, for example, the confirmation might be configured to be used only once per session, or operations like payments may have a limit per day to be without confirmation (pinless).", + "allOf" : [ { + "$ref" : "#/components/schemas/PasswordInput" + } ] } } }, @@ -38650,6 +51070,212 @@ } } }, + "DeliveryMethod" : { + "description" : "Reference to a webshop delivery method", + "allOf" : [ { + "$ref" : "#/components/schemas/NamedEntity" + }, { + "type" : "object", + "properties" : { + "description" : { + "type" : "string", + "description" : "A description on how this delivery method works." + }, + "enabled" : { + "type" : "boolean", + "description" : "Whether this delivery method is enabled for new sales." + }, + "chargeType" : { + "$ref" : "#/components/schemas/DeliveryMethodChargeTypeEnum" + }, + "deliveryTime" : { + "x-remove-version" : 4.15, + "deprecated" : true, + "description" : "Use `minDeliveryTime` and `maxDeliveryTime` instead.\n\nThe maximum time interval expected for the products to be delivered.", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] + }, + "minDeliveryTime" : { + "description" : "The minimum time interval expected for the products to be delivered.", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] + }, + "maxDeliveryTime" : { + "description" : "The maximum time interval expected for the products to be delivered.", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] + }, + "chargeAmount" : { + "description" : "The amount to be charged. Only makes sense if `chargeType` is `fixed`.", + "type" : "string", + "format" : "number" + }, + "chargeCurrency" : { + "description" : "The delivery price currency. Only makes sense if `chargeType` is `fixed`.", + "allOf" : [ { + "$ref" : "#/components/schemas/Currency" + } ] + } + } + } ] + }, + "DeliveryMethodBasicData" : { + "description" : "Contains data shared by both DeliveryMethodDataForNew and DeliveryMethodDataForEdit", + "type" : "object", + "properties" : { + "user" : { + "description" : "Reference to the owner of the delivery method", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "currencies" : { + "description" : "Contains the list of possible currencies for the delivery method", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Currency" + } + } + } + }, + "DeliveryMethodDataForEdit" : { + "description" : "Contains data for editing an exinsting webshop delivery method", + "allOf" : [ { + "$ref" : "#/components/schemas/DeliveryMethodBasicData" + }, { + "type" : "object", + "properties" : { + "edit" : { + "description" : "Can the authenticated user edit this delivery method?", + "type" : "boolean" + }, + "remove" : { + "description" : "Can the authenticated user remove this delivery method?", + "type" : "boolean" + }, + "deliveryMethod" : { + "description" : "The delivery method populated with the current fields. This value can be modified and sent back on `PUT /delivery-methods/{id}`.", + "allOf" : [ { + "$ref" : "#/components/schemas/DeliveryMethodEdit" + } ] + } + } + } ] + }, + "DeliveryMethodDataForNew" : { + "description" : "Contains data for creating a new webshop delivery method", + "allOf" : [ { + "$ref" : "#/components/schemas/DeliveryMethodBasicData" + }, { + "type" : "object", + "properties" : { + "deliveryMethod" : { + "description" : "The delivery method populated with the default fields. This value can be modified and sent back on `POST /{user}/delivery-methods`.", + "allOf" : [ { + "$ref" : "#/components/schemas/DeliveryMethodNew" + } ] + } + } + } ] + }, + "DeliveryMethodEdit" : { + "description" : "Fields for modifying a webshop delivery method.", + "allOf" : [ { + "$ref" : "#/components/schemas/DeliveryMethodManage" + }, { + "type" : "object", + "properties" : { + "version" : { + "type" : "integer", + "description" : "The version stamp for the current object, used for optimistic locking. When saving, the same version as previously received needs to be passed back. If no one else has saved the object, the version will match and the object will be updated. However, if someone other has saved the object, the version will no longer match, and an error will be raised. This is used to prevent multiple users (or processes) from updating the same object and unwilingly overridding the property values, leading to data loss." + } + } + } ] + }, + "DeliveryMethodManage" : { + "description" : "Common fields for either creating or editing a delivery method", + "type" : "object", + "x-abstract" : true, + "properties" : { + "enabled" : { + "type" : "boolean", + "description" : "Whether this delivery method is enabled for new sales." + }, + "name" : { + "type" : "string", + "description" : "The visible name for this delivery method." + }, + "description" : { + "type" : "string", + "description" : "A description on how this delivery method works." + }, + "chargeType" : { + "$ref" : "#/components/schemas/DeliveryMethodChargeTypeEnum" + }, + "deliveryTime" : { + "x-remove-version" : 4.15, + "deprecated" : true, + "description" : "Use `minDeliveryTime` and `maxDeliveryTime` instead.\n\nThe maximum time interval expected for the products to be delivered.", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] + }, + "minDeliveryTime" : { + "description" : "The minimum time interval expected for the products to be delivered.", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] + }, + "maxDeliveryTime" : { + "description" : "The maximum time interval expected for the products to be delivered.", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] + }, + "chargeAmount" : { + "type" : "string", + "format" : "number", + "description" : "The delivery price. Only makes sense if `chargeType` is `fixed`." + }, + "chargeCurrency" : { + "type" : "string", + "description" : "Either id or internal name of the price currency." + } + } + }, + "DeliveryMethodNew" : { + "description" : "Fields for a new webshop delivery method.", + "allOf" : [ { + "$ref" : "#/components/schemas/DeliveryMethodManage" + } ] + }, + "DeliveryMethodView" : { + "description" : "Details of a webshop delivery method", + "allOf" : [ { + "$ref" : "#/components/schemas/DeliveryMethod" + }, { + "type" : "object", + "properties" : { + "edit" : { + "description" : "Can the authenticated user edit this delivery method?", + "type" : "boolean" + }, + "remove" : { + "description" : "Can the authenticated user remove this delivery method?", + "type" : "boolean" + }, + "user" : { + "description" : "The user which owns this delivery method", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + } + } + } ] + }, "Device" : { "description" : "A device reference", "allOf" : [ { @@ -38669,6 +51295,23 @@ } } ] }, + "DeviceActivation" : { + "type" : "object", + "properties" : { + "code" : { + "type" : "string", + "description" : "The device activation code. Only required if the activation must be confirmed with code." + }, + "deviceId" : { + "type" : "string", + "description" : "Trusted device identification. Only required if the activation must be confirmed with another trusted device." + }, + "deviceConfirmationId" : { + "type" : "string", + "description" : "The approved device confirmation identification used to validate the activation. Only required if the activation must be confirmed with another trusted device." + } + } + }, "DeviceActivationResult" : { "type" : "object", "properties" : { @@ -38695,6 +51338,19 @@ } } }, + "DeviceConfirmationFeedbackPush" : { + "description" : "The result of the action accepted by a device confirmation", + "type" : "object", + "properties" : { + "deviceConfirmation" : { + "$ref" : "#/components/schemas/DeviceConfirmationView" + }, + "successful" : { + "description" : "True if the operation approved by the device confirmation has finished successfully.", + "type" : "boolean" + } + } + }, "DeviceConfirmationView" : { "description" : "Detailed information when viewing a device confirmation", "allOf" : [ { @@ -38753,11 +51409,15 @@ } }, "mediums" : { - "description" : "The available mediums for the activation code to be sent.", + "description" : "The available mediums for the activation code to be sent. Only returned if the activation can be made by using an activation code.", "type" : "array", "items" : { "$ref" : "#/components/schemas/SendMediumEnum" } + }, + "deviceConfirmation" : { + "description" : "The pending device confirmation used to confirm the device activation. Only returned if a trusted device is required for the new activation.", + "$ref" : "#/components/schemas/DeviceConfirmationView" } } }, @@ -38947,6 +51607,9 @@ "canManageIndividual" : { "description" : "Indicates whether the logged user can manage individual documents of managed users", "type" : "boolean" + }, + "query" : { + "$ref" : "#/components/schemas/DocumentQueryFilters" } } }, @@ -39048,6 +51711,10 @@ "user" : { "description" : "Either the id or identifier of the document owner", "type" : "string" + }, + "keywords" : { + "description" : "Used to filter documents containing that keywords in the the name or description (case insensitive)", + "type" : "string" } } } ] @@ -39148,6 +51815,28 @@ }, "required" : [ "exceptionType" ] }, + "ExportFormat" : { + "description" : "Contains a reference to an export format", + "allOf" : [ { + "$ref" : "#/components/schemas/InternalNamedEntity" + }, { + "type" : "object", + "properties" : { + "contentType" : { + "type" : "string", + "description" : "Indicates the content type (mime type) for the generated content." + }, + "binary" : { + "type" : "boolean", + "description" : "Indicates whether the content generated by this format is binary (true) or textual (false)" + }, + "encoding" : { + "type" : "string", + "description" : "Indicates the character encoding for the textual content. Only returned `binary` is false." + } + } + } ] + }, "ExternalPaymentsPermissions" : { "description" : "Permissions over own external payments", "type" : "object", @@ -39464,6 +52153,13 @@ }, { "type" : "object", "properties" : { + "groups" : { + "description" : "The groups the authenticated user can use to filter user records", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Group" + } + }, "query" : { "description" : "Default query filters for searching records", "allOf" : [ { @@ -39493,6 +52189,10 @@ "items" : { "type" : "string" } + }, + "user" : { + "description" : "Either the id or identifier of the record owner", + "type" : "string" } } } ] @@ -39812,6 +52512,122 @@ } } }, + "IdentityProvider" : { + "description" : "A reference to an identity provider", + "allOf" : [ { + "$ref" : "#/components/schemas/InternalNamedEntity" + }, { + "type" : "object", + "properties" : { + "backgroundColor" : { + "description" : "The background color for the button that represents this provider", + "type" : "string" + }, + "borderColor" : { + "description" : "The border color for the button that represents this provider", + "type" : "string" + }, + "textColor" : { + "description" : "The text color for the button that represents this provider", + "type" : "string" + }, + "image" : { + "description" : "The provider image", + "allOf" : [ { + "$ref" : "#/components/schemas/Image" + } ] + } + } + } ] + }, + "IdentityProviderCallbackResult" : { + "description" : "Result of a callback by an identity provider", + "type" : "object", + "properties" : { + "identityProvider" : { + "$ref" : "#/components/schemas/IdentityProvider" + }, + "status" : { + "$ref" : "#/components/schemas/IdentityProviderCallbackStatusEnum" + }, + "requestId" : { + "description" : "The identifier used to track this operation.", + "type" : "string" + }, + "sessionToken" : { + "description" : "If the user was logged-in, this is the token identifying the session. Only returned if `status` is either: `loginLink`, `loginEmail` or `registrationDone`.", + "type" : "string" + }, + "name" : { + "description" : "The user display name as returned by the provider. Only returned if `status` is `registrationData`.", + "type" : "string" + }, + "email" : { + "description" : "The user e-mail as returned by the provider. Only returned if `status` is `registrationData`.", + "type" : "string" + }, + "username" : { + "description" : "The user login name as returned by the provider. Only returned if `status` is `registrationData`.", + "type" : "string" + }, + "mobilePhone" : { + "description" : "The user mobile phone number name as returned by the provider. Only returned if `status` is `registrationData`.", + "type" : "string" + }, + "landLinePhone" : { + "description" : "The user land-line phone number name as returned by the provider. Only returned if `status` is `registrationData`.", + "type" : "string" + }, + "landLineExtension" : { + "description" : "The user land-line phone extension name as returned by the provider. Only returned if `status` is `registrationData`.", + "type" : "string" + }, + "image" : { + "description" : "The user image as returned by the provider. Only returned if `status` is `registrationData`.", + "allOf" : [ { + "$ref" : "#/components/schemas/Image" + } ] + }, + "customValues" : { + "description" : "The user custom field values as returned by the provider. Only returned if `status` is `registrationData`.", + "type" : "object", + "additionalProperties" : { + "type" : "string" + } + }, + "errorMessage" : { + "description" : "Description for the error being returned. It is possible that no message is returned. In this case, a generic error message should be displayed for the user. Only returned if `status` is `error`.", + "type" : "string" + } + } + }, + "IdentityProviderRequestResult" : { + "description" : "Result of the preparation of an operation with an identity provider", + "type" : "object", + "properties" : { + "identityProvider" : { + "$ref" : "#/components/schemas/IdentityProvider" + }, + "requestId" : { + "description" : "The identifier used to track this operation", + "type" : "string" + }, + "url" : { + "description" : "The URL which should be opened in a new browser window / popup to get the user consent.", + "type" : "string" + } + } + }, + "IdentityProvidersPermissions" : { + "description" : "Permissions over the logged user's identity provider links", + "type" : "object", + "properties" : { + "enabled" : { + "description" : "Is the identity providers functionality enabled for the logged user?", + "type" : "boolean" + } + } + }, "Image" : { "description" : "Contains data for displaying an image", "allOf" : [ { @@ -40020,6 +52836,207 @@ } } }, + "Installment" : { + "description" : "Reference to a scheduled payment installment", + "allOf" : [ { + "$ref" : "#/components/schemas/Entity" + }, { + "type" : "object", + "properties" : { + "number" : { + "description" : "The installment number.", + "type" : "integer" + }, + "dueDate" : { + "description" : "The installment due date.", + "type" : "string", + "format" : "date-time" + }, + "amount" : { + "description" : "The installment amount", + "type" : "string", + "format" : "number" + }, + "status" : { + "$ref" : "#/components/schemas/InstallmentStatusEnum" + } + } + } ] + }, + "InstallmentDataForSearch" : { + "description" : "Contains data used to search installments for a given owner", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseInstallmentDataForSearch" + }, { + "type" : "object", + "properties" : { + "user" : { + "description" : "When the given owner is a user, is the reference to it", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + } + } + } ] + }, + "InstallmentOverviewDataForSearch" : { + "description" : "Contains data used to search installments regardless of an owner", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseInstallmentDataForSearch" + } ] + }, + "InstallmentOverviewQueryFilters" : { + "description" : "Query filters for installments regardless of an account owner.", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseInstallmentQueryFilters" + }, { + "type" : "object", + "properties" : { + "currencies" : { + "description" : "The currencies internal names or ids.", + "type" : "array", + "items" : { + "type" : "string" + } + }, + "fromAccountTypes" : { + "description" : "The source account types internal names or ids.", + "type" : "array", + "items" : { + "type" : "string" + } + }, + "toAccountTypes" : { + "description" : "The source account types internal names or ids.", + "type" : "array", + "items" : { + "type" : "string" + } + } + } + } ] + }, + "InstallmentOverviewResult" : { + "description" : "Represents an installment.", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseInstallmentResult" + }, { + "type" : "object", + "properties" : { + "transaction" : { + "description" : "The transaction that originated this installment", + "allOf" : [ { + "$ref" : "#/components/schemas/TransactionOverviewResult" + } ] + } + } + } ] + }, + "InstallmentPreview" : { + "description" : "Preview of an installment", + "type" : "object", + "properties" : { + "number" : { + "description" : "The installment number", + "type" : "integer" + }, + "dueDate" : { + "description" : "The installment due date", + "type" : "string", + "format" : "date-time" + }, + "totalAmount" : { + "description" : "The final total installment amount", + "type" : "string", + "format" : "number" + }, + "mainAmount" : { + "description" : "Depending on the configured fees, it could happen that the main amount is deducted from fees amount. This reflects the new main amount. If no fees deduct, it will be the same as `totalAmount`.", + "type" : "string", + "format" : "number" + }, + "fees" : { + "description" : "Only returned for direct payments. Contains the fees that would be paid by the payer if the payment is confirmed.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransferFeePreview" + } + } + } + }, + "InstallmentQueryFilters" : { + "description" : "Query filters for transactions related to an account owner.", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseInstallmentQueryFilters" + }, { + "type" : "object", + "properties" : { + "accountTypes" : { + "description" : "The account types", + "type" : "array", + "items" : { + "type" : "string" + } + }, + "direction" : { + "$ref" : "#/components/schemas/TransferDirectionEnum" + } + } + } ] + }, + "InstallmentResult" : { + "description" : "Represents an installment, as viewed from the point-of-view of an account owner. This means that credits will have a positive amount, while debits will be negative.", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseInstallmentResult" + }, { + "type" : "object", + "properties" : { + "transaction" : { + "description" : "The transaction that originated this installment", + "allOf" : [ { + "$ref" : "#/components/schemas/TransactionResult" + } ] + } + } + } ] + }, + "InstallmentView" : { + "description" : "Contains details about an installment", + "allOf" : [ { + "$ref" : "#/components/schemas/Installment" + }, { + "type" : "object", + "properties" : { + "by" : { + "description" : "The user that performed an status change. For example, who manually paid, settled or canceled an open installment", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "transferId" : { + "description" : "Only if the installment was processed, contains the internal identifier of the generated transfer.", + "type" : "string" + }, + "transactionNumber" : { + "description" : "Only if the installment was processed, contains the transaction number of the generated transfer.", + "type" : "string" + }, + "transferDate" : { + "description" : "The date the transfer was processed.", + "type" : "string", + "format" : "date-time" + }, + "canProcess" : { + "description" : "Can the authenticated user process this installment?", + "type" : "boolean" + }, + "canSettle" : { + "description" : "Can the authenticated user settle this installment?", + "type" : "boolean" + } + } + } ] + }, "InternalNamedEntity" : { "description" : "Basic definition of a persistent entity which has both a name and an internal name", "x-abstract" : true, @@ -40048,10 +53065,29 @@ }, "toAccount" : { "$ref" : "#/components/schemas/AccountWithOwner" + }, + "toOperator" : { + "description" : "The operator who is receiving the payment. Only sent if the payment is made to an operator.", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] } } } ] }, + "JWKSResponse" : { + "type" : "object", + "properties" : { + "keys" : { + "description" : "Each of the JWK", + "type" : "array", + "items" : { + "type" : "object", + "additionalProperties" : true + } + } + } + }, "Language" : { "description" : "Reference to a language in Cyclos", "allOf" : [ { @@ -40135,28 +53171,64 @@ "description" : "Permissions for the marketplace", "type" : "object", "properties" : { + "mySimple" : { + "description" : "Simple advertisement permissions for the logged user. Only returned if there is an authenticated user.", + "$ref" : "#/components/schemas/MyMarketplacePermissions" + }, + "myWebshop" : { + "description" : "Webshop ad permissions for the logged user. Only returned if there is an authenticated user.", + "$ref" : "#/components/schemas/MyMarketplacePermissions" + }, + "userSimple" : { + "description" : "Permissions over simple advertisements of other users", + "$ref" : "#/components/schemas/UserBaseAdPermissions" + }, + "userWebshop" : { + "description" : "Permissions over webshop ads of other users", + "$ref" : "#/components/schemas/UserBaseAdPermissions" + }, + "interests" : { + "description" : "Are ad interests enabled? Only returned if there is an authenticated user.", + "type" : "boolean" + }, + "questions" : { + "description" : "Are questions enabled? Only returned if there is an authenticated user.", + "type" : "boolean" + }, "search" : { - "description" : "Can search for simple and webshop advertisements?", + "description" : "Use `userSimple.view` or `userWebshop.view` instead\n\n\nCan search for simple and webshop advertisements?", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "boolean" }, "ownAdvertisements" : { - "description" : "Can own simple advertisements? Only returned if there is an authenticated user.", + "description" : "Use `mySimple.enable` instead\n\n\nCan own simple advertisements? Only returned if there is an authenticated user.", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "boolean" }, "manageOwnAdvertisements" : { - "description" : "Can manage own simple advertisements? Only returned if there is an authenticated user.", + "description" : "Use `mySimple.manage` instead\n\n\nCan manage own simple advertisements? Only returned if there is an authenticated user.", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "boolean" }, "purchase" : { - "description" : "Can buy webwop ads? Only returned if there is an authenticated user.", + "description" : "Use `userWebshop.purchase` instead\n\n\nCan buy webwop ads? Only returned if there is an authenticated user.", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "boolean" }, "viewAdvertisements" : { - "description" : "Can view simple advertisements? Only returned if there is an authenticated user.", + "description" : "Use `userSimple.view` instead\n\n\nCan view simple advertisements? Only returned if there is an authenticated user.", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "boolean" }, "viewWebshop" : { - "description" : "Can view webshop advertisements? If this permission is granted then the user can can buy webshop ads too. Only returned if there is an authenticated user.", + "description" : "Use `userWebshop.view` instead\n\n\nCan view webshop advertisements? Only returned if there is an authenticated user.", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "boolean" } } @@ -40217,6 +53289,10 @@ "description" : "Quality for JPEG image types (higher means better quality)", "type" : "integer" }, + "mapBrowserApiKey" : { + "description" : "The Google Maps browser API key", + "type" : "string" + }, "numberFormat" : { "$ref" : "#/components/schemas/NumberFormatEnum" }, @@ -40274,6 +53350,20 @@ } } ] }, + "MyMarketplacePermissions" : { + "description" : "Permissions for the marketplace for the logged user", + "type" : "object", + "properties" : { + "enable" : { + "description" : "Are advertisements enabled? Only returned if there is an authenticated user.", + "type" : "boolean" + }, + "manage" : { + "description" : "Can manage own advertisements? Only returned if there is an authenticated user.", + "type" : "boolean" + } + } + }, "NamedEntity" : { "description" : "Basic definition of a persistent entity which has a name", "x-abstract" : true, @@ -40573,7 +53663,7 @@ "type" : "boolean" }, "personalizeAsMember" : { - "description" : "Can personalize tokens of this type as member? Only send if the authenticated user is a broker.", + "description" : "Can personalize tokens of this type as member? Always `false` if the authenticated user is a not a broker.", "type" : "boolean" } } @@ -40650,12 +53740,6 @@ "description" : "Indicates whether the notification was marked as already read or not", "type" : "boolean" }, - "location" : { - "deprecated" : true, - "x-remove-version" : 4.13, - "description" : "Use `entityType` instead.\n\n\nThe standard location to which the notification points to", - "type" : "string" - }, "entityId" : { "description" : "The identifier of the entity referenced by the notification, if any. The `entityType` and `entityId` attributes are both not null or both null in case there is a referenced entity.", "type" : "string" @@ -40749,6 +53833,13 @@ "$ref" : "#/components/schemas/EntityReference" } }, + "userAccounts" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/AccountType" + }, + "description" : "The available accounts types for user payment notifications" + }, "userGroups" : { "description" : "The visible user groups. Only applicable for administrators, not users (members / brokers).", "type" : "array", @@ -40857,6 +53948,20 @@ "items" : { "type" : "string" } + }, + "version" : { + "type" : "integer", + "description" : "The version stamp for the current object, used for optimistic locking. When saving, the same version as previously received needs to be passed back. If no one else has saved the object, the version will match and the object will be updated. However, if someone other has saved the object, the version will no longer match, and an error will be raised. This is used to prevent multiple users (or processes) from updating the same object and unwilingly overridding the property values, leading to data loss." + } + } + }, + "NotificationSettingsPermissions" : { + "description" : "Permissions over notification settings", + "type" : "object", + "properties" : { + "enable" : { + "description" : "Whether the own notification settings are enabled or not.", + "type" : "boolean" } } }, @@ -40983,6 +54088,80 @@ } } }, + "OidcAuthorizeResult" : { + "description" : "Result after an OAuth2 / OpenID Connect approve / deny", + "type" : "object", + "properties" : { + "url" : { + "description" : "The URL to which the user should be redirected", + "type" : "string" + }, + "postData" : { + "type" : "object", + "additionalProperties" : { + "type" : "string" + }, + "description" : "Variables that should be POSTed to the given URL. When null it means that a plain redirect should be performed." + } + } + }, + "OidcClient" : { + "description" : "Represents a client", + "allOf" : [ { + "$ref" : "#/components/schemas/InternalNamedEntity" + }, { + "type" : "object", + "properties" : { + "image" : { + "$ref" : "#/components/schemas/Image" + } + } + } ] + }, + "OidcError" : { + "description" : "Error generating an OAuth2 / OpenID Connect response", + "type" : "object", + "properties" : { + "error" : { + "description" : "The error code", + "type" : "string" + }, + "error_description" : { + "description" : "The error description", + "type" : "string" + } + } + }, + "OidcTokenResult" : { + "description" : "Result after an OAuth2 / OpenID Connect token request", + "type" : "object", + "properties" : { + "access_token" : { + "description" : "The access token which can be used to make additional requests. It will be used as a `Bearer` token.", + "type" : "string" + }, + "token_type" : { + "description" : "Cyclos always returns `bearer` tokens.", + "type" : "string" + }, + "id_token" : { + "description" : "The JWT-encoded ID token.", + "type" : "string" + }, + "state" : { + "description" : "The same opaque `state` value provided by the client on the authenticate request.", + "type" : "string" + }, + "expires_in" : { + "description" : "The number of seconds until the token expires, counted from the time the request was received.", + "type" : "integer" + }, + "refresh_token" : { + "description" : "The refresh token, which can be used to obtain additional access tokens. Is only issued if the `offline_access` scope has been granted, and only when the `grant_type` is `authorization_code`.", + "type" : "string" + } + } + }, "Operation" : { "description" : "Contains definitions used to run a custom operation", "allOf" : [ { @@ -41015,11 +54194,11 @@ "type" : "boolean" }, "allowExport" : { - "description" : "Does this operation allows exporting the results as CSV? Only returned if `resultType` is `resultPage`. Only returned in contexts where the operation can be executed.", + "description" : "Does this operation allows exporting the result page as file? Only returned if `resultType` is `resultPage`. Only returned in contexts where the operation can be executed.", "type" : "boolean" }, "allowPrint" : { - "description" : "Does this operation allows printing the results as PDF? Only returned if `resultType` is `resultPage`. Only returned in contexts where the operation can be executed.", + "description" : "Should the front-end show a print action for the custom operation result? Before Cyclos 4.13 this was used for `resultType` `resultPage`, but since 4.13 is only used for `plainText` or `richText`. Only returned in contexts where the operation can be executed.", "type" : "boolean" }, "missingOptionalParameters" : { @@ -41037,15 +54216,17 @@ } }, "showFormForMissingOptionalParameters" : { - "description" : "Indicates whether a form to enter the missing optional parameters must be shown. Only returned if the `missingOptionalParameters` list is not empty and `scope` is `internal`. Only returned in contexts where the operation can be executed.", - "type" : "boolean" - }, - "canRunDirectly" : { "deprecated" : true, - "x-remove-version" : 4.13, - "description" : "Use the other flags instead. This flag was decomposed in several others to allow better control at the moment of run a custom operation. For example, if your front-end asks for the confirmation password in a popup instead of in its own page and the only thing you need to run the operation is that (i.e thereare no missing parameters, no file upload, etc) then you could show the popup to collect the password and then run the custom operation directly in the same page on which you are.\n\n\nIndicates whether this operation can be executed directly, without showing a form page. More specifically, this flag is true if:\n\n- There are no confirmation text nor informational text\n- File upload is not allowed\n- Confirmation password is not required\n- All required parameters were set\n- All optional parametes were set or, if not, the option to show the form in case of missing parameters is false.\n\nOnly returned in contexts where the operation can be executed.", + "x-remove-version" : 4.15, + "description" : "Use `showForm` instead.\n\n\nIndicates whether a form to enter the missing optional parameters must be shown. Only returned if the `missingOptionalParameters` list is not empty and `scope` is `internal`. Only returned in contexts where the operation can be executed.", "type" : "boolean" }, + "showForm" : { + "description" : "Indicates whether a form with the parameters must be shown. Only returned if `scope` is `internal` and the `resultType` is not `resultPage` Only returned in contexts where the operation can be executed.", + "allOf" : [ { + "$ref" : "#/components/schemas/OperationShowFormEnum" + } ] + }, "scope" : { "$ref" : "#/components/schemas/OperationScopeEnum" }, @@ -41098,6 +54279,13 @@ "$ref" : "#/components/schemas/PasswordInput" } ] }, + "exportFormats" : { + "description" : "The formats which a custom operation result of type `resultPage` can be exported.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExportFormat" + } + }, "searchAutomatically" : { "description" : "Should the operation be immediately executed by the third party client software when first presenting the form to the user (when `true`) or only when the user clicks submit (when `false`)? Only returned if `resultType` is `resultPage`.", "type" : "boolean" @@ -41311,9 +54499,9 @@ "type" : "boolean", "description" : "Can the permission to unblock tokens (cards) be granted?" }, - "canRegisterUsersAsBroker" : { + "broker" : { "type" : "boolean", - "description" : "Can the permission to register users as broker be granted?" + "description" : "Indicates whether the owner user is a broker. If so, can delegate brokering operations to operators." }, "canHaveMessages" : { "type" : "boolean", @@ -41451,10 +54639,6 @@ "type" : "boolean", "description" : "Can operators of this group redeem vouchers?" }, - "registerUsersAsBroker" : { - "type" : "boolean", - "description" : "Can operators of this group register users as broker?" - }, "requestPayments" : { "type" : "boolean", "description" : "Can operators of this group request payments?" @@ -41483,6 +54667,10 @@ "type" : "boolean", "description" : "Can operators of this group unblock their own tokens (cards)?" }, + "brokering" : { + "type" : "boolean", + "description" : "Can operators of this group perform brokering operations? This includes full brokering operatations the user is allowed, including user registration, accounts access, payments as user, etc." + }, "restrictPaymentsToUsers" : { "type" : "array", "items" : { @@ -41607,10 +54795,6 @@ "type" : "boolean", "description" : "Can operators of this group redeem vouchers?" }, - "registerUsersAsBroker" : { - "type" : "boolean", - "description" : "Can operators of this group register users as broker?" - }, "requestPayments" : { "type" : "boolean", "description" : "Can operators of this group request payments?" @@ -41639,6 +54823,10 @@ "type" : "boolean", "description" : "Can operators of this group unblock their own tokens (cards)?" }, + "brokering" : { + "type" : "boolean", + "description" : "Can operators of this group perform brokering operations?" + }, "restrictPaymentsToUsers" : { "type" : "array", "items" : { @@ -41717,6 +54905,19 @@ } } ] }, + "OperatorResult" : { + "description" : "Result of a operator search.", + "allOf" : [ { + "$ref" : "#/components/schemas/UserResult" + }, { + "type" : "object", + "properties" : { + "group" : { + "$ref" : "#/components/schemas/EntityReference" + } + } + } ] + }, "OperatorsPermissions" : { "description" : "Permissions over own operators", "type" : "object", @@ -41735,6 +54936,36 @@ } } }, + "OrderBasicData" : { + "description" : "Common data for `OrderDataForNew` and `OrderDataForEdit`", + "type" : "object", + "properties" : { + "seller" : { + "$ref" : "#/components/schemas/User" + }, + "buyer" : { + "$ref" : "#/components/schemas/User" + }, + "deliveryMethods" : { + "description" : "List with all delivery methods defined for the seller. When creating or updating an order it can be filled with the fields from one of these existing delivery methods or a custom delivery method can be set.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/DeliveryMethod" + } + }, + "addressConfiguration" : { + "description" : "The address configuration for the buyer\n", + "$ref" : "#/components/schemas/AddressConfiguration" + }, + "addresses" : { + "description" : "List containing the visible addresses of the buyer. When creating or updating an order it can be filled with the fields from one of these existing addresses or a custom delivery address can be set.\n", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Address" + } + } + } + }, "OrderDataForAcceptByBuyer" : { "description" : "Data used to accept an order by the buyer.", "type" : "object", @@ -41754,6 +54985,82 @@ } } }, + "OrderDataForEdit" : { + "description" : "Data for edit an order as the seller", + "allOf" : [ { + "$ref" : "#/components/schemas/OrderBasicData" + }, { + "type" : "object", + "properties" : { + "edit" : { + "description" : "Can the authenticated user edit this order?", + "type" : "boolean" + }, + "remove" : { + "description" : "Can the authenticated user remove this order?", + "type" : "boolean" + }, + "currency" : { + "$ref" : "#/components/schemas/Currency" + }, + "order" : { + "description" : "The order that is being edited", + "$ref" : "#/components/schemas/OrderEdit" + } + } + } ] + }, + "OrderDataForNew" : { + "description" : "Data for create a new order as the seller", + "allOf" : [ { + "$ref" : "#/components/schemas/OrderBasicData" + }, { + "type" : "object", + "properties" : { + "currencies" : { + "description" : "The available currencies for the sale", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Currency" + } + }, + "order" : { + "description" : "The order that is being created", + "$ref" : "#/components/schemas/OrderNew" + } + } + } ] + }, + "OrderDataForSearch" : { + "description" : "Data for searching orders (purchases / sales)", + "type" : "object", + "properties" : { + "user" : { + "$ref" : "#/components/schemas/User" + }, + "query" : { + "description" : "Default query filters to search operators", + "allOf" : [ { + "$ref" : "#/components/schemas/OrderQueryFilters" + } ] + }, + "numberMask" : { + "type" : "string", + "description" : "The order number mask according to the webshop settings if it is manually generated. Only for sales" + }, + "currencies" : { + "description" : "The visible currencies the user have. Only for sales", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Currency" + } + }, + "canCreateNew" : { + "description" : "Whether the logged user can create a new sale or not.", + "type" : "boolean" + } + } + }, "OrderDataForSetDeliveryMethod" : { "description" : "Data used to to set a delivery method.", "type" : "object", @@ -41765,11 +55072,52 @@ "description" : "List with all delivery methods shared by all products contained in the order.", "type" : "array", "items" : { - "$ref" : "#/components/schemas/AdDeliveryMethod" + "$ref" : "#/components/schemas/DeliveryMethod" } } } }, + "OrderDeliveryMethod" : { + "description" : "The order delivery method", + "type" : "object", + "properties" : { + "name" : { + "description" : "The name of the delivery method", + "type" : "string" + }, + "minTime" : { + "description" : "The minimum time interval expected for the products to be delivered.", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] + }, + "maxTime" : { + "description" : "The maximum time interval expected for the products to be delivered.", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] + }, + "price" : { + "description" : "The amount to be charged for the delivery method", + "type" : "string", + "format" : "number" + } + } + }, + "OrderEdit" : { + "description" : "Fields for modifying an order.", + "allOf" : [ { + "$ref" : "#/components/schemas/OrderManage" + }, { + "type" : "object", + "properties" : { + "version" : { + "type" : "integer", + "description" : "The version stamp for the current object, used for optimistic locking. When saving, the same version as previously received needs to be passed back. If no one else has saved the object, the version will match and the object will be updated. However, if someone other has saved the object, the version will no longer match, and an error will be raised. This is used to prevent multiple users (or processes) from updating the same object and unwilingly overridding the property values, leading to data loss." + } + } + } ] + }, "OrderItem" : { "description" : "Data for an order item.", "allOf" : [ { @@ -41790,6 +55138,95 @@ } } ] }, + "OrderItemManage" : { + "description" : "Data for create / edit an order item", + "type" : "object", + "properties" : { + "quantity" : { + "description" : "It represents how much of the product was ordered. It could be a decimal number only if it's allowed by the product (i.e the webshopad).", + "type" : "string", + "format" : "number" + }, + "price" : { + "description" : "The charged price of the product.", + "type" : "string", + "format" : "number" + }, + "product" : { + "description" : "Can be either the ad webshop internal identifier or the product number.", + "type" : "string" + } + } + }, + "OrderLog" : { + "description" : "Information regarding a specific order status change", + "type" : "object", + "properties" : { + "by" : { + "$ref" : "#/components/schemas/User" + }, + "date" : { + "description" : "When the chage was made", + "type" : "string", + "format" : "date-time" + }, + "remarks" : { + "description" : "The remarks associated to the change made by the user", + "type" : "string" + }, + "status" : { + "description" : "The new status for the order", + "allOf" : [ { + "$ref" : "#/components/schemas/OrderStatusEnum" + } ] + } + } + }, + "OrderManage" : { + "description" : "Common fields for either creating or editing an order", + "type" : "object", + "properties" : { + "deliveryMethod" : { + "$ref" : "#/components/schemas/OrderDeliveryMethod" + }, + "deliveryAddress" : { + "$ref" : "#/components/schemas/SimpleAddress" + }, + "draft" : { + "description" : "If `true` then the order is saved with status `draft` and is visible only for the seller. Otherwise, the order is saved with status `pendingBuyer` and sent to the buyer for acceptance.", + "type" : "boolean" + }, + "remarks" : { + "description" : "Remarks shown to the buyer if set", + "type" : "string" + }, + "items" : { + "description" : "The order items", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/OrderItemManage" + } + } + } + }, + "OrderNew" : { + "description" : "A new order to be created", + "allOf" : [ { + "$ref" : "#/components/schemas/OrderManage" + }, { + "type" : "object", + "properties" : { + "currency" : { + "description" : "Either internal name or id of the order currency.", + "type" : "string" + }, + "buyer" : { + "description" : "Either internal id or other accepted identification (username, e-mail, etc) for the buyer", + "type" : "string" + } + } + } ] + }, "OrderQueryFilters" : { "description" : "Search filters for orders.", "allOf" : [ { @@ -41822,6 +55259,10 @@ "items" : { "$ref" : "#/components/schemas/OrderStatusEnum" } + }, + "productNumber" : { + "type" : "string", + "description" : "The product number (with the mask if there is one) of an advertisement contained in the orders." } } } ] @@ -41885,19 +55326,47 @@ } ] }, "deliveryAddress" : { - "$ref" : "#/components/schemas/Address" + "$ref" : "#/components/schemas/SimpleAddress" + }, + "deliveryMethod" : { + "$ref" : "#/components/schemas/OrderDeliveryMethod" }, "deliveryMethodName" : { + "x-remove-version" : 4.15, + "deprecated" : true, "type" : "string", - "description" : "The delivery method name." + "description" : "Use `deliveryMethod.name` instead." }, "deliveryPrice" : { + "x-remove-version" : 4.15, + "deprecated" : true, "type" : "string", "format" : "number", - "description" : "The delivery method price." + "description" : "Use `deliveryMethod.price` instead." }, "deliveryTime" : { - "$ref" : "#/components/schemas/TimeInterval" + "x-remove-version" : 4.15, + "deprecated" : true, + "description" : "Use `deliveryMethod.minTime` and `deliveryMethod.maxTime` instead.", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] + }, + "minDeliveryTime" : { + "x-remove-version" : 4.15, + "deprecated" : true, + "description" : "Use `deliveryMethod.minTime` instead.", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] + }, + "maxDeliveryTime" : { + "x-remove-version" : 4.15, + "deprecated" : true, + "description" : "Use `deliveryMethod.maxTime` instead.", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] }, "paymentType" : { "$ref" : "#/components/schemas/TransferType" @@ -41916,6 +55385,25 @@ "sale" : { "type" : "boolean", "description" : "Is it a sale (initiated by the seller)?" + }, + "canAccept" : { + "description" : "An order can be accepted only for the following statuses:\n\n- `draft`: only if the authenticated user is the seller meaning the seller can submit the sale to the buyer.\n- `pendingBuyer`: only if the authenticated user is the buyer\n- `pendingSeller`: only if the authenticated user is the seller and the order has a delivery method already set", + "type" : "boolean" + }, + "canReject" : { + "description" : "An order can be rejected only for the following statuses:\n\n- `pendingBuyer`: only if the authenticated user is the buyer or the seller\n- `pendingSeller`: only if the authenticated user is the seller", + "type" : "boolean" + }, + "canSetDeliveryInformation" : { + "description" : "Delivery information can be set only for the following statuses:\n\n- `draft`: only if the authenticated user is the seller\n- `pendingSeller`: only if the authenticated user is the seller and a delivery method was not already set", + "type" : "boolean" + }, + "history" : { + "description" : "Contains the history entries for all order status changes", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/OrderLog" + } } } } ] @@ -41942,17 +55430,13 @@ "OwnerRecordPermissions" : { "description" : "Permissions over a user record for a given owner", "allOf" : [ { - "$ref" : "#/components/schemas/RecordBasePermissions" + "$ref" : "#/components/schemas/RecordPermissions" }, { "type" : "object", "properties" : { "count" : { "description" : "The current number of records of this type for this owner", "type" : "integer" - }, - "singleRecordId" : { - "description" : "If this record type layout is single, and the record exists, contains its identifier", - "type" : "string" } } } ] @@ -42026,6 +55510,10 @@ "description" : "For text passwords, the maximum password length", "type" : "integer" }, + "onlyNumeric" : { + "description" : "Whether the password contains only numbers or not", + "type" : "boolean" + }, "numberOfButtons" : { "description" : "Only for `virtualKeyboard`, is the number of buttons to be displayed", "type" : "integer" @@ -42188,7 +55676,7 @@ "PasswordType" : { "description" : "Contains definitions for a password type", "allOf" : [ { - "$ref" : "#/components/schemas/InternalNamedEntity" + "$ref" : "#/components/schemas/BasePasswordType" }, { "type" : "object", "properties" : { @@ -42205,7 +55693,7 @@ "PasswordTypeRegistration" : { "description" : "Data for a given password type to be used on user registration", "allOf" : [ { - "$ref" : "#/components/schemas/InternalNamedEntity" + "$ref" : "#/components/schemas/BasePasswordType" }, { "type" : "object", "properties" : { @@ -42308,7 +55796,7 @@ "description" : "Only returned for scheduled payments. Contains the previews of each installment, if the payment is confirmed.", "type" : "array", "items" : { - "$ref" : "#/components/schemas/ScheduledPaymentInstallmentPreview" + "$ref" : "#/components/schemas/InstallmentPreview" } }, "payment" : { @@ -42336,6 +55824,10 @@ "description" : "The maturity used for this payment", "type" : "string", "format" : "number" + }, + "skipConfirmation" : { + "description" : "True if the payment should be performed directly without showing the preview. If there is a `confirmationPasswordInput` defined then this flag will be false regardless the setting in the transfer type.", + "type" : "boolean" } } } ] @@ -42363,12 +55855,6 @@ "changeExpiration" : { "description" : "The payment request expiration date can be changed by the payee or managers.", "type" : "boolean" - }, - "authorize" : { - "description" : "Use accept instead", - "type" : "boolean", - "deprecated" : true, - "x-remove-version" : 4.13 } } }, @@ -42449,6 +55935,23 @@ } } }, + "PerformInstallment" : { + "description" : "An installment definition when performing a scheduled payment", + "type" : "object", + "properties" : { + "dueDate" : { + "description" : "The installment due date", + "type" : "string", + "format" : "date-time" + }, + "amount" : { + "description" : "The installment amount", + "type" : "string", + "format" : "number" + } + }, + "required" : [ "dueDate", "amount" ] + }, "PerformInternalTransaction" : { "description" : "Base definitions to performing a transaction to an internal account (any except `externalPayment`, or `chargeback` which is performed distinctly).", "allOf" : [ { @@ -42488,7 +55991,7 @@ "description" : "An array containing individual installments definitions, allowing full control over generated installments. Used only if `scheduling` is `scheduled`.", "type" : "array", "items" : { - "$ref" : "#/components/schemas/PerformScheduledPaymentInstallment" + "$ref" : "#/components/schemas/PerformInstallment" } }, "occurrencesCount" : { @@ -42517,23 +56020,6 @@ } } ] }, - "PerformScheduledPaymentInstallment" : { - "description" : "An installment definition when performing a scheduled payment", - "type" : "object", - "properties" : { - "dueDate" : { - "description" : "The installment due date", - "type" : "string", - "format" : "date-time" - }, - "amount" : { - "description" : "The installment amount", - "type" : "string", - "format" : "number" - } - }, - "required" : [ "dueDate", "amount" ] - }, "PerformTransaction" : { "description" : "Base definitions for performing a transaction", "allOf" : [ { @@ -42613,11 +56099,41 @@ "$ref" : "#/components/schemas/NotificationsPermissions" } ] }, + "notificationSettings" : { + "description" : "Permissions over notifications settings", + "allOf" : [ { + "$ref" : "#/components/schemas/NotificationSettingsPermissions" + } ] + }, "tokens" : { "description" : "Permissions over tokens", "allOf" : [ { "$ref" : "#/components/schemas/TokensPermissions" } ] + }, + "sessions" : { + "description" : "Permissions over user sessions", + "allOf" : [ { + "$ref" : "#/components/schemas/SessionsPermissions" + } ] + }, + "alerts" : { + "description" : "Permissions related to user alers", + "allOf" : [ { + "$ref" : "#/components/schemas/AlertsPermissions" + } ] + }, + "vouchers" : { + "description" : "Permissions over vouchers", + "allOf" : [ { + "$ref" : "#/components/schemas/VouchersPermissions" + } ] + }, + "identityProviders" : { + "description" : "Permissions over identity provider links", + "allOf" : [ { + "$ref" : "#/components/schemas/IdentityProvidersPermissions" + } ] } } }, @@ -43169,6 +56685,10 @@ "pageSize" : { "type" : "integer", "description" : "The maximum number of records that will be returned on the search. The default value is 40. The maximum number of returned results is configured in Cyclos, and even if more than that is requested, it will be limited by that setting." + }, + "skipTotalCount" : { + "type" : "boolean", + "description" : "When set to true the result will not include the total record count, only the information on whether there are more records. Depending on the server-side configuration, this can be always true. Otherwise, if the server allows total count, and the client doesn't need it, setting this to true can increase performance a bit." } } }, @@ -43194,7 +56714,7 @@ "type" : "object", "properties" : { "type" : { - "$ref" : "#/components/schemas/RecordType" + "$ref" : "#/components/schemas/RecordTypeWithMenu" }, "create" : { "description" : "Can the authenticated user create new records of this type?", @@ -43352,6 +56872,12 @@ }, { "type" : "object", "properties" : { + "user" : { + "description" : "The user searching a record type, empty if there is self otherwise the managed user", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, "query" : { "description" : "Default query filters for searching records", "allOf" : [ { @@ -43399,28 +56925,29 @@ }, "RecordPermissions" : { "description" : "Permissions over own records of a given type", - "type" : "object", - "properties" : { - "type" : { - "$ref" : "#/components/schemas/RecordType" - }, - "create" : { - "description" : "Can create records of this type?", - "type" : "boolean" - }, - "update" : { - "description" : "Can update records of this type?", - "type" : "boolean" - }, - "remove" : { - "description" : "Can remove records of this type?", - "type" : "boolean" - }, - "singleId" : { - "description" : "If the record type `layout` is `single` this property contains the identifier of the existing record (if any) of this type.", - "type" : "string" + "allOf" : [ { + "$ref" : "#/components/schemas/RecordBasePermissions" + }, { + "type" : "object", + "properties" : { + "singleRecordId" : { + "description" : "If this record type layout is single, and the record exists, contains its identifier", + "type" : "string" + }, + "update" : { + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "Use `edit` property\n\n\nCan update records of this type?", + "type" : "boolean" + }, + "singleId" : { + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "Use `singleRecordId` property\n\n\nIf the record type `layout` is `single` this property contains the identifier of the existing record (if any) of this type.", + "type" : "string" + } } - } + } ] }, "RecordQueryFilters" : { "description" : "Query filters for records", @@ -43443,6 +56970,10 @@ "type" : "string", "format" : "date-time" } + }, + "createdBy" : { + "description" : "Either the id or identifier of the user that created the record", + "type" : "string" } } } ] @@ -43643,14 +57174,21 @@ "type" : "object", "properties" : { "user" : { - "description" : "Permissions over each visible user record type", + "description" : "Permissions over each visible own user record type.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/RecordPermissions" + } + }, + "userManagement" : { + "description" : "Permissions over each visible user record type of managed users.", "type" : "array", "items" : { "$ref" : "#/components/schemas/RecordPermissions" } }, "system" : { - "description" : "Permissions over each visible system record type", + "description" : "Permissions over each visible system record type.", "type" : "array", "items" : { "$ref" : "#/components/schemas/RecordPermissions" @@ -43658,52 +57196,6 @@ } } }, - "RecurringPaymentOccurrenceView" : { - "description" : "Contains details about an occurrence of a recurring payment", - "allOf" : [ { - "$ref" : "#/components/schemas/Entity" - }, { - "type" : "object", - "properties" : { - "number" : { - "description" : "The occurrence number.", - "type" : "integer" - }, - "date" : { - "description" : "The occurrence date.", - "type" : "string", - "format" : "date-time" - }, - "amount" : { - "description" : "The installment amount", - "type" : "string", - "format" : "number" - }, - "by" : { - "description" : "The user that performed an status change. For example, who manually paid, settled or canceled an open installment", - "allOf" : [ { - "$ref" : "#/components/schemas/User" - } ] - }, - "transferId" : { - "description" : "Only if the occurrence was processed, contains the internal identifier of the generated transfer.", - "type" : "string" - }, - "transactionNumber" : { - "description" : "Only if the occurrence was processed, contains the transaction number of the generated transfer.", - "type" : "string" - }, - "transferDate" : { - "description" : "The date the occurrence was processed. It might happen that the occurrence has first failed, then later processed", - "type" : "string", - "format" : "date-time" - }, - "status" : { - "$ref" : "#/components/schemas/RecurringPaymentOccurrenceStatusEnum" - } - } - } ] - }, "RecurringPaymentPermissions" : { "description" : "Permissions the user has over a recurring payment", "type" : "object", @@ -43778,6 +57270,147 @@ } } ] }, + "Reference" : { + "description" : "A general reference between 2 users", + "allOf" : [ { + "$ref" : "#/components/schemas/Entity" + }, { + "type" : "object", + "properties" : { + "date" : { + "description" : "The date the reference was set", + "type" : "string", + "format" : "date-time" + }, + "level" : { + "$ref" : "#/components/schemas/ReferenceLevelEnum" + }, + "comments" : { + "description" : "The reference comments", + "type" : "string" + } + } + } ] + }, + "ReferenceDataForSet" : { + "description" : "Configuration data for setting a reference", + "type" : "object", + "properties" : { + "from" : { + "description" : "The user that gave the reference", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "to" : { + "description" : "The user that received the reference", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "reference" : { + "description" : "The object that should be edited and posted back", + "allOf" : [ { + "$ref" : "#/components/schemas/ReferenceSet" + } ] + } + } + }, + "ReferencePeriodStatistics" : { + "description" : "Statistics for received or given references in a given period", + "type" : "object", + "properties" : { + "period" : { + "description" : "The date period ranges. Null when the results are for all time.", + "allOf" : [ { + "$ref" : "#/components/schemas/DatePeriod" + } ] + }, + "total" : { + "type" : "integer", + "description" : "The total number of accounted references." + }, + "totalNegative" : { + "description" : "The total number of accounted `good` or `veryGood` references.", + "type" : "integer" + }, + "totalPositive" : { + "description" : "The total number of accounted `bad` or `veryBad` references.", + "type" : "integer" + }, + "counts" : { + "description" : "References count per level.", + "type" : "object", + "additionalProperties" : { + "type" : "integer" + } + }, + "score" : { + "type" : "number", + "format" : "float", + "description" : "The score is a value from 1 to 5 which contains the average score when counting all levels. Each reference level has a score:\n\n- `veryBad`: 1;\n- `bad`: 2;\n- `neutral`: 3;\n- `good`: 4;\n- `veryGood`: 5.\n\nThe score will be 0 when there are no references." + } + } + }, + "ReferenceSet" : { + "description" : "Parameters for setting a reference value. When modifying an existing reference, the `version` field must be passed in with the correct value, as returned in `GET /{from}/reference/{to}/data-for-set`.", + "type" : "object", + "properties" : { + "level" : { + "$ref" : "#/components/schemas/ReferenceLevelEnum" + }, + "comments" : { + "description" : "Comments for this reference", + "type" : "string" + }, + "version" : { + "type" : "integer", + "description" : "The version stamp for the current object, used for optimistic locking. When saving, the same version as previously received needs to be passed back. If no one else has saved the object, the version will match and the object will be updated. However, if someone other has saved the object, the version will no longer match, and an error will be raised. This is used to prevent multiple users (or processes) from updating the same object and unwilingly overridding the property values, leading to data loss." + } + } + }, + "ReferenceStatistics" : { + "description" : "Statistics for received or given references", + "type" : "object", + "properties" : { + "user" : { + "$ref" : "#/components/schemas/User" + }, + "periods" : { + "description" : "For each requested period, contains corresponding statistics", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ReferencePeriodStatistics" + } + } + } + }, + "ReferenceView" : { + "description" : "Details of a reference", + "allOf" : [ { + "$ref" : "#/components/schemas/Reference" + }, { + "type" : "object", + "properties" : { + "from" : { + "description" : "The user that gave the reference", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "to" : { + "description" : "The user that received the reference", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "manage" : { + "description" : "Can the authenticated user manage this reference?", + "type" : "boolean" + } + } + } ] + }, "RejectOrder" : { "description" : "Parameters used to reject an order by the authenticated user.", "allOf" : [ { @@ -43833,8 +57466,13 @@ "description" : "When running a custom operation with `resultType` = `resultPage`, determines the number of results per page. Whether this is implemented depends on the script code itself.", "type" : "integer" }, + "exportFormat" : { + "description" : "Only when running a custom operation with `resultType` = `resultPage`. Is the internal name of the format to export the results. If unset will not generate a file, but return the result data.", + "type" : "string" + }, "pageContext" : { - "description" : "Only when running a custom operation with `resultType` = `resultPage`.", + "description" : "DEPRECATED: Use `exportFormat` instead.\nOnly when running a custom operation with `resultType` = `resultPage`.", + "x-remove-version" : 4.15, "allOf" : [ { "$ref" : "#/components/schemas/OperationPageContextEnum" } ] @@ -43943,10 +57581,17 @@ "description" : "Contains the property name for each row element to access this column value.", "type" : "string" }, + "type" : { + "$ref" : "#/components/schemas/RunOperationResultColumnTypeEnum" + }, "align" : { "description" : "The horizontal alignment. The actual values depend on the semantics of both the script result and the client application.", "type" : "string" }, + "decimalDigits" : { + "description" : "The number of decimal digits (scale) to format numbers. -1 represents variable scale. Only if `type` is `number`.", + "type" : "integer" + }, "valign" : { "description" : "The vertical alignment. The actual values depend on the semantics of both the script result and the client application.", "type" : "string" @@ -43957,102 +57602,6 @@ } } }, - "ScheduledPaymentInstallment" : { - "description" : "Reference to a scheduled payment installment", - "allOf" : [ { - "$ref" : "#/components/schemas/Entity" - }, { - "type" : "object", - "properties" : { - "number" : { - "description" : "The installment number.", - "type" : "integer" - }, - "dueDate" : { - "description" : "The installment due date.", - "type" : "string", - "format" : "date-time" - }, - "amount" : { - "description" : "The installment amount", - "type" : "string", - "format" : "number" - }, - "status" : { - "$ref" : "#/components/schemas/ScheduledPaymentInstallmentStatusEnum" - } - } - } ] - }, - "ScheduledPaymentInstallmentPreview" : { - "description" : "Preview of a direct or scheduled payment", - "type" : "object", - "properties" : { - "number" : { - "description" : "The installment number", - "type" : "integer" - }, - "dueDate" : { - "description" : "The installment due date", - "type" : "string", - "format" : "date-time" - }, - "totalAmount" : { - "description" : "The final total installment amount", - "type" : "string", - "format" : "number" - }, - "mainAmount" : { - "description" : "Depending on the configured fees, it could happen that the main amount is deducted from fees amount. This reflects the new main amount. If no fees deduct, it will be the same as `totalAmount`.", - "type" : "string", - "format" : "number" - }, - "fees" : { - "description" : "Only returned for direct payments. Contains the fees that would be paid by the payer if the payment is confirmed.", - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/TransferFeePreview" - } - } - } - }, - "ScheduledPaymentInstallmentView" : { - "description" : "Contains details about an installment of a scheduled payment", - "allOf" : [ { - "$ref" : "#/components/schemas/ScheduledPaymentInstallment" - }, { - "type" : "object", - "properties" : { - "by" : { - "description" : "The user that performed an status change. For example, who manually paid, settled or canceled an open installment", - "allOf" : [ { - "$ref" : "#/components/schemas/User" - } ] - }, - "transferId" : { - "description" : "Only if the installment was processed, contains the internal identifier of the generated transfer.", - "type" : "string" - }, - "transactionNumber" : { - "description" : "Only if the installment was processed, contains the transaction number of the generated transfer.", - "type" : "string" - }, - "transferDate" : { - "description" : "The date the transfer was processed.", - "type" : "string", - "format" : "date-time" - }, - "canProcess" : { - "description" : "Can the authenticated user process this installment?", - "type" : "boolean" - }, - "canSettle" : { - "description" : "Can the authenticated user settle this installment?", - "type" : "boolean" - } - } - } ] - }, "ScheduledPaymentPermissions" : { "description" : "Permissions the user has over a scheduled payment", "type" : "object", @@ -44284,6 +57833,24 @@ } } ] }, + "SessionsPermissions" : { + "description" : "Permissions over user sessions", + "type" : "object", + "properties" : { + "view" : { + "description" : "Whether the logged user can view connected users or not", + "type" : "boolean" + }, + "disconnect" : { + "description" : "Whether the logged user can disconnect users or not", + "type" : "boolean" + }, + "login" : { + "description" : "Whether the logged user can login (i.e create a session) users or not", + "type" : "boolean" + } + } + }, "SetAccountBalanceLimits" : { "description" : "Parameters for setting the new account limits.", "allOf" : [ { @@ -44315,7 +57882,24 @@ "format" : "number" }, "time" : { - "$ref" : "#/components/schemas/TimeInterval" + "x-remove-version" : 4.15, + "deprecated" : true, + "description" : "Use `minTime` and `maxTime` instead.", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] + }, + "minTime" : { + "description" : "The delivery method minimum time interval", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] + }, + "maxTime" : { + "description" : "The delivery method maximum time interval", + "allOf" : [ { + "$ref" : "#/components/schemas/TimeInterval" + } ] } } } ] @@ -44435,10 +58019,10 @@ } }, "deliveryMethods" : { - "description" : "The list of delivery method commons to all of the products added to the shopping cart ordered by name.", + "description" : "The list of delivery method commons to all of the products added to the shopping cart ordered by name.", "type" : "array", "items" : { - "$ref" : "#/components/schemas/AdDeliveryMethod" + "$ref" : "#/components/schemas/DeliveryMethod" } }, "addressConfiguration" : { @@ -44569,6 +58153,63 @@ } } ] }, + "SimpleAddress" : { + "description" : "Address fields container", + "type" : "object", + "x-implements" : "IAddress", + "properties" : { + "addressLine1" : { + "type" : "string", + "description" : "The first line of the descriptive address" + }, + "addressLine2" : { + "type" : "string", + "description" : "The second line of the descriptive address" + }, + "street" : { + "type" : "string", + "description" : "The street name" + }, + "buildingNumber" : { + "type" : "string", + "description" : "The numeric identifier for a land parcel, house, building or other" + }, + "complement" : { + "type" : "string", + "description" : "The complement (like apartment number)" + }, + "zip" : { + "type" : "string", + "description" : "A zip code that identifies a specific geographic (postal) delivery area" + }, + "poBox" : { + "type" : "string", + "description" : "The post-office box, is an uniquely addressable box" + }, + "neighborhood" : { + "type" : "string", + "description" : "The neighborhood name" + }, + "city" : { + "type" : "string", + "description" : "The city name" + }, + "region" : { + "type" : "string", + "description" : "The region or state" + }, + "country" : { + "type" : "string", + "description" : "The country, represented as 2-letter, uppercase, ISO 3166-1 code" + }, + "location" : { + "description" : "The geolocation of the current address", + "allOf" : [ { + "$ref" : "#/components/schemas/GeographicalCoordinate" + } ] + } + } + }, "StoredFile" : { "description" : "Contains data about a stored file", "allOf" : [ { @@ -44758,34 +58399,15 @@ } }, "Token" : { - "description" : "Contains reference to a token. Tokens are used to identify users.", + "description" : "Contains reference to a token. Tokens are used to identify users, and are normally used as cards.", "allOf" : [ { - "$ref" : "#/components/schemas/NamedEntity" + "$ref" : "#/components/schemas/Entity" }, { "type" : "object", "properties" : { - "type" : { - "$ref" : "#/components/schemas/TokenType" - }, "value" : { - "description" : "The token value only if not NFC. Othwise the token's label.", + "description" : "The token value only if not NFC. Otherwise is the token label.", "type" : "string" - } - } - } ] - }, - "TokenDetailed" : { - "description" : "Contain all the information of a token.", - "allOf" : [ { - "$ref" : "#/components/schemas/Token" - }, { - "type" : "object", - "properties" : { - "user" : { - "description" : "The assigned user. Only if status is not `unassigned`.", - "allOf" : [ { - "$ref" : "#/components/schemas/User" - } ] }, "activationDate" : { "description" : "When the owner user activated the token.", @@ -44808,6 +58430,176 @@ } } ] }, + "TokenDataForNew" : { + "description" : "Configuration data to create a new token", + "type" : "object", + "properties" : { + "type" : { + "$ref" : "#/components/schemas/TokenType" + }, + "user" : { + "description" : "The user details, in case a user was requested.", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "token" : { + "description" : "The object that should be modified and posted back.", + "allOf" : [ { + "$ref" : "#/components/schemas/TokenNew" + } ] + } + } + }, + "TokenDataForSearch" : { + "description" : "Configuration data for a general tokens search of a given type", + "allOf" : [ { + "$ref" : "#/components/schemas/TokenPermissions" + }, { + "type" : "object", + "properties" : { + "groups" : { + "description" : "The groups the authenticated user can use to filter tokens. Admins can always filter by groups, while brokers depend on a permission, which can be to only view group sets, only groups or none.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Group" + } + }, + "exportFormats" : { + "description" : "The formats which the data can be exported", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExportFormat" + } + }, + "query" : { + "description" : "Default query filters to search tokens", + "allOf" : [ { + "$ref" : "#/components/schemas/TokenQueryFilters" + } ] + } + } + } ] + }, + "TokenDetailed" : { + "description" : "Contains detailed information of a token.", + "allOf" : [ { + "$ref" : "#/components/schemas/TokenResult" + }, { + "type" : "object", + "properties" : { + "type" : { + "$ref" : "#/components/schemas/TokenType" + } + } + } ] + }, + "TokenNew" : { + "description" : "Data to create a new token", + "type" : "object", + "properties" : { + "user" : { + "description" : "Either id or identification of the user to initially assign the token to. If set the token initial status will be either `pending` or `active` (if `activateNow` is true). If the user is not set, the initial status will always be `unassigned`.", + "type" : "string" + }, + "value" : { + "description" : "The token value to create. The token value is commonly used as the card number.", + "type" : "string" + }, + "activateNow" : { + "description" : "When set to true, the token will be initially active when `user` is also set. Has no effect if `user` is null.", + "type" : "boolean" + } + } + }, + "TokenPermissions" : { + "description" : "Permissions over tokens of a specific type", + "type" : "object", + "properties" : { + "type" : { + "$ref" : "#/components/schemas/TokenType" + }, + "create" : { + "description" : "Can create tokens of this type? For NFC tags, this permission is mapped to the 'Initialize' action.", + "type" : "boolean" + }, + "activate" : { + "description" : "Can activate tokens of this type? For NFC tags, this permission is mapped to the 'Personalize' action.", + "type" : "boolean" + } + } + }, + "TokenQueryFilters" : { + "description" : "Query filters for tokens", + "allOf" : [ { + "$ref" : "#/components/schemas/QueryFilters" + }, { + "type" : "object", + "properties" : { + "activationPeriod" : { + "description" : "The minimum / maximum token activation date.", + "type" : "array", + "items" : { + "type" : "string", + "format" : "date-time" + } + }, + "expiryPeriod" : { + "description" : "The minimum / maximum token expiry date.", + "type" : "array", + "items" : { + "type" : "string", + "format" : "date-time" + } + }, + "groups" : { + "type" : "array", + "items" : { + "type" : "string" + }, + "description" : "Either id or internal names of groups / group sets" + }, + "brokers" : { + "type" : "array", + "items" : { + "type" : "string" + }, + "description" : "Either id or a principal (login name, e-mail, etc) for brokers" + }, + "user" : { + "type" : "string", + "description" : "Either id or a principal (login name, e-mail, etc) for the token owner user" + }, + "value" : { + "type" : "string", + "description" : "The token value" + }, + "statuses" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TokenStatusEnum" + }, + "description" : "The desired token statuses" + } + } + } ] + }, + "TokenResult" : { + "description" : "Result of a general token search", + "allOf" : [ { + "$ref" : "#/components/schemas/Token" + }, { + "type" : "object", + "properties" : { + "user" : { + "description" : "The assigned user. Only if status is not `unassigned`.", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + } + } + } ] + }, "TokenType" : { "description" : "A reference to a token type", "allOf" : [ { @@ -44815,6 +58607,10 @@ }, { "type" : "object", "properties" : { + "pluralName" : { + "description" : "The name for the plural form", + "type" : "string" + }, "mask" : { "description" : "In case the token value is entered by users or formatted, this is the (optional) mask to be used.", "type" : "string" @@ -44825,12 +58621,78 @@ } } ] }, + "TokenView" : { + "description" : "Contains all data regarding a token", + "allOf" : [ { + "$ref" : "#/components/schemas/TokenDetailed" + }, { + "type" : "object", + "properties" : { + "activationDeadline" : { + "description" : "Limit date a pending token can be activated. Not returned when status is not `pending`.", + "type" : "string", + "format" : "date-time" + }, + "activate" : { + "description" : "Can this token be directly activated?", + "type" : "boolean" + }, + "assign" : { + "description" : "Can this token be assigned to a user?", + "type" : "boolean" + }, + "block" : { + "description" : "Can this token be blocked?", + "type" : "boolean" + }, + "unblock" : { + "description" : "Can this token be unblocked?", + "type" : "boolean" + }, + "cancel" : { + "description" : "Can this token be canceled?", + "type" : "boolean" + }, + "setActivationDeadline" : { + "description" : "Can the activation deadline date of this token be changed?", + "type" : "boolean" + }, + "setExpiryDate" : { + "description" : "Can the expiry date of this token be changed?", + "type" : "boolean" + } + } + } ] + }, "TokensPermissions" : { "description" : "Permissions over tokens", "type" : "object", "properties" : { + "my" : { + "description" : "Permissions over my own tokens type", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TokenPermissions" + } + }, + "user" : { + "description" : "Permissions over tokens types of other users", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TokenPermissions" + } + }, + "personalizeNfcTokensAsMember" : { + "description" : "NFC token types the authenticated member can personalize to other members (example, a business personalizing cards for clients).", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TokenType" + } + }, "nfc" : { - "description" : "Permissions over each visible nfc token type", + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED: Use either `my`, `user` or `personalizeNfcTokensAsMember`, filtering by `physicalType` to be `nfcTag`.\n\nPermissions over each visible nfc token type", "type" : "array", "items" : { "$ref" : "#/components/schemas/NfcTokenPermissions" @@ -44838,8 +58700,8 @@ } } }, - "Transaction" : { - "description" : "Reference to a transaction", + "Trans" : { + "description" : "Common data for transfer and transaction", "allOf" : [ { "$ref" : "#/components/schemas/Entity" }, { @@ -44847,61 +58709,136 @@ "properties" : { "display" : { "type" : "string", - "description" : "The descriptive text for this transaction, according to the transaction type and currency configuration in Cyclos" + "description" : "A display text for this transfer / transaction, according to the transaction type and currency configuration in Cyclos." }, "transactionNumber" : { - "description" : "The transaction number identifying this balance transfer. The currency configuration has the definition on whether transaction numbers are enabled and which format they have.", + "description" : "The transaction number identifying this transfer / transaction. The currency configuration has the definition on whether transaction numbers are enabled and which format they have.", "type" : "string" }, - "ticketNumber" : { - "description" : "A 32-length alphanumeric ticket identifier. Only returned if kind is `ticket`.", + "date" : { + "description" : "The creation date and time.", + "type" : "string", + "format" : "date-time" + }, + "amount" : { + "description" : "The transfer / transaction amount.", + "type" : "string", + "format" : "number" + }, + "from" : { + "description" : "The debited account.", + "allOf" : [ { + "$ref" : "#/components/schemas/AccountWithOwner" + } ] + }, + "to" : { + "description" : "The credited account.", + "allOf" : [ { + "$ref" : "#/components/schemas/AccountWithOwner" + } ] + }, + "type" : { + "description" : "WARNING: Currently this object contains both `from` and `to` account types. Starting with Cyclos 4.15 they won't be returned, anymore, as the account types are already returned in the `from` / `to` accounts.", + "allOf" : [ { + "$ref" : "#/components/schemas/TransferType" + } ] + }, + "currency" : { + "description" : "The transfer / transaction currency.", + "allOf" : [ { + "$ref" : "#/components/schemas/Currency" + } ] + } + } + } ] + }, + "TransResult" : { + "description" : "Base fields for results of both transfers and transactions", + "allOf" : [ { + "$ref" : "#/components/schemas/Entity" + }, { + "type" : "object", + "properties" : { + "transactionNumber" : { + "description" : "The transaction number identifying this balance transfer. The currency configuration has the definition on whether transaction numbers are enabled and which format they have.", "type" : "string" }, "date" : { - "description" : "The transfer date and time", + "description" : "The transaction date and time.", "type" : "string", "format" : "date-time" }, "amount" : { - "description" : "The transfer amount. May be positive or negative.", + "description" : "The transaction amount.", "type" : "string", "format" : "number" }, + "type" : { + "description" : "WARNING: Currently this object contains both `from` and `to` account types. Starting with Cyclos 4.15 they won't be returned, the account types are already returned in the accounts.", + "allOf" : [ { + "$ref" : "#/components/schemas/TransferType" + } ] + }, + "description" : { + "description" : "The transaction description. Is optional.", + "type" : "string" + } + } + } ] + }, + "Transaction" : { + "description" : "Reference to a transaction", + "allOf" : [ { + "$ref" : "#/components/schemas/Trans" + }, { + "type" : "object", + "properties" : { + "ticketNumber" : { + "description" : "A 32-length alphanumeric ticket identifier. Only returned if kind is `ticket`.", + "type" : "string" + }, + "fromName" : { + "description" : "Contains an optional custom from name, which can be set when the transaction is performed.", + "type" : "string" + }, + "toName" : { + "description" : "Contains an optional custom to name, which can be set when the transaction is performed.", + "type" : "string" + }, "fromKind" : { - "description" : "The from account kind", + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED. Use `from.kind`.\n\nThe kind of account owner that sent the transaction. WARNING: for kinds `paymentRequest` and `ticket` will represent the `to` account. This way the pre-Cyclos 4.13 semantic is kept. But keep this in mind that when updating your client code.", "allOf" : [ { "$ref" : "#/components/schemas/AccountKind" } ] }, "fromUser" : { - "description" : "The user that performed this transaction. Is only returned if `fromKind` is `user`.", + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED. Use `from.user`.\n\nThe kind of account owner that sent the transaction. WARNING: for kinds `paymentRequest` and `ticket` will represent the `to` account. This way the pre-Cyclos 4.13 semantic is kept. But keep this in mind that when updating your client code.", "allOf" : [ { "$ref" : "#/components/schemas/User" } ] }, "toKind" : { - "description" : "The to account kind", + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED. Use `to.kind`.\n\nThe kind of account owner that sent the transaction. WARNING: for kinds `paymentRequest` and `ticket` will represent the `from` account. This way the pre-Cyclos 4.13 semantic is kept. But keep this in mind that when updating your client code.", "allOf" : [ { "$ref" : "#/components/schemas/AccountKind" } ] }, "toUser" : { - "description" : "The user that performed this transaction. Is only returned if `toKind` is `user`.", + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED. Use `to.user`.\n\nThe kind of account owner that sent the transaction. WARNING: for kinds `paymentRequest` and `ticket` will represent the `from` account. This way the pre-Cyclos 4.13 semantic is kept. But keep this in mind that when updating your client code.", "allOf" : [ { "$ref" : "#/components/schemas/User" } ] }, - "type" : { - "$ref" : "#/components/schemas/TransferType" - }, - "currency" : { - "description" : "The transaction currency. Is only returned if this object is not embedded in a `TransferView`.", - "allOf" : [ { - "$ref" : "#/components/schemas/Currency" - } ] - }, "description" : { - "description" : "The transaction description. Is optional.", + "description" : "The optional transaction description.", "type" : "string" }, "kind" : { @@ -45009,32 +58946,28 @@ "TransactionDataForSearch" : { "description" : "Contains data used to search transactions for a given owner", "allOf" : [ { - "$ref" : "#/components/schemas/BaseTransDataForSearch" + "$ref" : "#/components/schemas/BaseTransactionDataForSearch" }, { "type" : "object", "properties" : { - "accountTypes" : { - "description" : "Visible account types from the given owner", + "user" : { + "description" : "When the given owner is a user, is the reference to it", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "accessClients" : { + "description" : "References for access clients which can be used to filter entries by transfers generated by a specific access client", "type" : "array", "items" : { - "$ref" : "#/components/schemas/AccountType" + "$ref" : "#/components/schemas/EntityReference" } }, - "canViewAuthorized" : { - "description" : "Can the authenticated user view authorized transactions of this owner?", - "type" : "boolean" - }, - "canViewScheduled" : { - "description" : "Use `visibleKinds` instead.\n\n\nCan the authenticated user view scheduled payments of this owner?", - "type" : "boolean", - "deprecated" : true, - "x-remove-version" : 4.13 - }, - "visibleKinds" : { - "description" : "Contains the transaction kinds the authenticated user can view over this owner.", + "operators" : { + "description" : "References for operators, which can be used to filter entries by transfers performed or received by that specific operator", "type" : "array", "items" : { - "$ref" : "#/components/schemas/TransactionKind" + "$ref" : "#/components/schemas/User" } }, "query" : { @@ -45046,6 +58979,126 @@ } } ] }, + "TransactionOverviewDataForSearch" : { + "description" : "Contains data used to search transactions regardless of an account owner", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseTransactionDataForSearch" + }, { + "type" : "object", + "properties" : { + "authorizablePaymentTypes" : { + "description" : "Payment types the authenticated administrator can authorize. Only returned when logged-in as administrator and the request had the `pendingMyAuthorization` flag set to true.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/TransferType" + } + }, + "query" : { + "description" : "Default query filters for the transactions search", + "allOf" : [ { + "$ref" : "#/components/schemas/TransactionOverviewQueryFilters" + } ] + } + } + } ] + }, + "TransactionOverviewQueryFilters" : { + "description" : "Query filters for transactions regardless of an account owner.", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseTransactionQueryFilters" + }, { + "type" : "object", + "properties" : { + "currencies" : { + "description" : "The currencies internal names or ids.", + "type" : "array", + "items" : { + "type" : "string" + } + }, + "fromAccountTypes" : { + "description" : "The source account types internal names or ids.", + "type" : "array", + "items" : { + "type" : "string" + } + }, + "toAccountTypes" : { + "description" : "The source account types internal names or ids.", + "type" : "array", + "items" : { + "type" : "string" + } + }, + "pendingMyAuthorization" : { + "description" : "When set to true will only return transactions (`payment`, `recurringPayment` or `scheduledPayment`) in pending authorization state that the logged user can authorize", + "type" : "boolean" + } + } + } ] + }, + "TransactionOverviewResult" : { + "description" : "Represents a transaction.", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseTransactionResult" + }, { + "type" : "object", + "properties" : { + "from" : { + "description" : "The debited account", + "allOf" : [ { + "$ref" : "#/components/schemas/AccountWithOwner" + } ] + }, + "fromName" : { + "description" : "Contains an optional custom from name, which can be set when the transaction is performed.", + "type" : "string" + }, + "to" : { + "description" : "The credited account", + "allOf" : [ { + "$ref" : "#/components/schemas/AccountWithOwner" + } ] + }, + "toName" : { + "description" : "Contains an optional custom to name, which can be set when the transaction is performed.", + "type" : "string" + }, + "fromKind" : { + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED. Use `from.kind`.", + "allOf" : [ { + "$ref" : "#/components/schemas/AccountKind" + } ] + }, + "fromUser" : { + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED. Use `from.user`.", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "toKind" : { + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED. Use `to.kind`.", + "allOf" : [ { + "$ref" : "#/components/schemas/AccountKind" + } ] + }, + "toUser" : { + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED. Use `to.user`.", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + } + } + } ] + }, "TransactionPreview" : { "description" : "Base definitions for a preview before performing a transaction", "type" : "object", @@ -45069,6 +59122,12 @@ "fromAccount" : { "$ref" : "#/components/schemas/AccountWithOwner" }, + "fromOperator" : { + "description" : "The operator who is performing the payment. Only sent if the payment is made from an operator.", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, "totalAmount" : { "description" : "The final amount charged to the payer including fees.", "type" : "string", @@ -45084,9 +59143,9 @@ } }, "TransactionQueryFilters" : { - "description" : "Query filters for transactions", + "description" : "Query filters for transactions related to an account owner.", "allOf" : [ { - "$ref" : "#/components/schemas/BaseTransQueryFilters" + "$ref" : "#/components/schemas/BaseTransactionQueryFilters" }, { "type" : "object", "properties" : { @@ -45099,54 +59158,6 @@ }, "direction" : { "$ref" : "#/components/schemas/TransferDirectionEnum" - }, - "kinds" : { - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/TransactionKind" - } - }, - "authorizationStatuses" : { - "description" : "Authorization statuses used as search criteria", - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/TransactionAuthorizationStatusEnum" - } - }, - "ticketStatuses" : { - "description" : "Statuses used as search criteria applied only to transactions of kind `ticket`.", - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/TicketStatusEnum" - } - }, - "recurringPaymentStatuses" : { - "description" : "Statuses used as search criteria applied only to transactions of kind `recurringPayment`.", - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/RecurringPaymentStatusEnum" - } - }, - "scheduledPaymentStatuses" : { - "description" : "Statuses used as search criteria applied only to transactions of kind `scheduledPayment`.", - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/ScheduledPaymentStatusEnum" - } - }, - "paymentRequestStatuses" : { - "description" : "Statuses used as search criteria applied only to transactions of kind `paymentRequest`.", - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/PaymentRequestStatusEnum" - } - }, - "externalPaymentStatuses" : { - "description" : "Statuses used as search criteria applied only to transactions of kind `externalPayment`.", - "type" : "array", - "items" : { - "$ref" : "#/components/schemas/ExternalPaymentStatusEnum" - } } } } ] @@ -45154,120 +59165,35 @@ "TransactionResult" : { "description" : "Represents a transaction, as viewed from the point-of-view of an account owner. This means that credits will have a positive amount, while debits will be negative.", "allOf" : [ { - "$ref" : "#/components/schemas/Entity" + "$ref" : "#/components/schemas/BaseTransactionResult" }, { "type" : "object", "properties" : { - "transactionNumber" : { - "description" : "The transaction number identifying this balance transfer. The currency configuration has the definition on whether transaction numbers are enabled and which format they have.", - "type" : "string" - }, - "date" : { - "description" : "The transfer date and time", - "type" : "string", - "format" : "date-time" + "related" : { + "description" : "Either from or to account", + "allOf" : [ { + "$ref" : "#/components/schemas/AccountWithOwner" + } ] }, - "amount" : { - "description" : "The transfer amount. May be positive or negative.", - "type" : "string", - "format" : "number" + "relatedName" : { + "description" : "Contains an optional custom from / to name, which can be set when the transaction is performed.", + "type" : "string" }, "relatedKind" : { - "description" : "The related account owner kind", + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED. Use `related.kind` instead.", "allOf" : [ { "$ref" : "#/components/schemas/AccountKind" } ] }, "relatedUser" : { - "description" : "The user that either performed or received this transaction. Is only returned if `relatedKind` is `user`.", + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED. Use `related.user` instead.", "allOf" : [ { "$ref" : "#/components/schemas/User" } ] - }, - "type" : { - "$ref" : "#/components/schemas/TransferType" - }, - "currency" : { - "description" : "Either internal name or id of the transaction currency.", - "type" : "string" - }, - "description" : { - "description" : "The transaction description. Is optional.", - "type" : "string" - }, - "installmentCount" : { - "description" : "The total number of installments. Only returned if `kind` is `scheduledPayment`.", - "type" : "integer" - }, - "processedInstallments" : { - "description" : "The number of processed installments. Only returned if `kind` is `scheduledPayment`.", - "type" : "integer" - }, - "firstInstallment" : { - "description" : "A reference to the first installment of this scheduled payment. Only returned if `kind` is `scheduledPayment`.", - "allOf" : [ { - "$ref" : "#/components/schemas/ScheduledPaymentInstallment" - } ] - }, - "firstOpenInstallment" : { - "description" : "A reference to the first installment which is still open. Only returned if `kind` is `scheduledPayment`.", - "allOf" : [ { - "$ref" : "#/components/schemas/ScheduledPaymentInstallment" - } ] - }, - "nextOccurrenceDate" : { - "description" : "When the next recurring payment occurrence will be processed. Only returned if `kind` is `recurringPayment`.", - "type" : "string", - "format" : "date-time" - }, - "toPrincipalType" : { - "description" : "The principal type an external payment was sent to. Only returned if `kind` is `externalPayment`.", - "allOf" : [ { - "$ref" : "#/components/schemas/EntityReference" - } ] - }, - "toPrincipalValue" : { - "description" : "The principal to which an external payment was sent to. Only returned if `kind` is `externalPayment`.", - "type" : "string" - }, - "kind" : { - "description" : "The transaction kind. For example, if the front end has distinct views for a regular payment, scheduled payment and so on, this information is useful to determine the actual view.", - "allOf" : [ { - "$ref" : "#/components/schemas/TransactionKind" - } ] - }, - "authorizationStatus" : { - "$ref" : "#/components/schemas/TransactionAuthorizationStatusEnum" - }, - "scheduledPaymentStatus" : { - "description" : "The scheduled payment status. Only returned if `kind` is `scheduledPayment`.", - "allOf" : [ { - "$ref" : "#/components/schemas/ScheduledPaymentStatusEnum" - } ] - }, - "recurringPaymentStatus" : { - "description" : "The recurring payment status. Only returned if `kind` is `recurringPayment`.", - "allOf" : [ { - "$ref" : "#/components/schemas/RecurringPaymentStatusEnum" - } ] - }, - "paymentRequestStatus" : { - "description" : "The ticket status. Only returned if `kind` is `ticket`.", - "allOf" : [ { - "$ref" : "#/components/schemas/PaymentRequestStatusEnum" - } ] - }, - "ticketStatus" : { - "description" : "The ticket status. Only returned if `kind` is `ticket`.", - "allOf" : [ { - "$ref" : "#/components/schemas/TicketStatusEnum" - } ] - }, - "externalPaymentStatus" : { - "description" : "The external payment status. Only returned if `kind` is `externalPayment`.", - "allOf" : [ { - "$ref" : "#/components/schemas/ExternalPaymentStatusEnum" - } ] } } } ] @@ -45295,12 +59221,6 @@ "description" : "The maximum allowed installments. If it is zero, no kind of scheduled payments is allowed. If it is 1, a single future date can be used.", "type" : "integer" }, - "requiresDescription" : { - "deprecated" : true, - "x-remove-version" : 4.13, - "description" : "Use `descriptionAvailability` instead\n\n\nThe transaction description can be either required, or optional, depending on this setting.", - "type" : "boolean" - }, "defaultExpirationDate" : { "description" : "The default expiration date, according to the configuration. Only for payment requests.", "type" : "string", @@ -45380,6 +59300,12 @@ "$ref" : "#/components/schemas/EntityReference" } ] }, + "oidcClient" : { + "description" : "When the transaction was performed from an OpenID Connect / OAuth2 client, contains a reference to it. The client is the third party application used to perform the payment", + "allOf" : [ { + "$ref" : "#/components/schemas/OidcClient" + } ] + }, "by" : { "description" : "The user that actually performed the action. May be different than the from, for example, an administrator can perform payments in behalf of other users", "allOf" : [ { @@ -45387,7 +59313,7 @@ } ] }, "receivedBy" : { - "description" : "The operator that actually received the payment. Only available if some other user has paid directly to it or the operator has received the payment vía POS.", + "description" : "The operator that actually received the payment. Only available if some other user has paid directly to it or the operator has received the payment via POS.", "allOf" : [ { "$ref" : "#/components/schemas/User" } ] @@ -45449,7 +59375,7 @@ "description" : "Only returned if the `kind` is `scheduledPayment`. Contains the installment references.", "type" : "array", "items" : { - "$ref" : "#/components/schemas/ScheduledPaymentInstallmentView" + "$ref" : "#/components/schemas/InstallmentView" } }, "recurringPaymentPermissions" : { @@ -45477,7 +59403,7 @@ "description" : "Only returned if the `kind` is `recurringPayment`. A list with all occurrences this payment has.", "type" : "array", "items" : { - "$ref" : "#/components/schemas/RecurringPaymentOccurrenceView" + "$ref" : "#/components/schemas/InstallmentView" } }, "originalTransfer" : { @@ -45601,6 +59527,13 @@ }, "ticketStatus" : { "$ref" : "#/components/schemas/TicketStatusEnum" + }, + "exportFormats" : { + "description" : "The formats which the data can be exported", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExportFormat" + } } } } ] @@ -45608,49 +59541,10 @@ "Transfer" : { "description" : "Reference to a balance transfer between accounts", "allOf" : [ { - "$ref" : "#/components/schemas/Entity" + "$ref" : "#/components/schemas/Trans" }, { "type" : "object", "properties" : { - "display" : { - "type" : "string", - "description" : "The descriptive text for this transfer, according to the transfer type and currency configuration in Cyclos" - }, - "date" : { - "description" : "The transfer date and time", - "type" : "string", - "format" : "date-time" - }, - "amount" : { - "description" : "The transfer amount. May be positive or negative.", - "type" : "string", - "format" : "number" - }, - "type" : { - "description" : "The transfer type", - "allOf" : [ { - "$ref" : "#/components/schemas/EntityReference" - } ] - }, - "currency" : { - "$ref" : "#/components/schemas/Currency" - }, - "from" : { - "description" : "The account that sent the balance", - "allOf" : [ { - "$ref" : "#/components/schemas/AccountWithOwner" - } ] - }, - "to" : { - "description" : "The account that received the balance", - "allOf" : [ { - "$ref" : "#/components/schemas/AccountWithOwner" - } ] - }, - "transactionNumber" : { - "description" : "The transaction number identifying this balance transfer. The currency configuration has the definition on whether transaction numbers are enabled and which format they have.", - "type" : "string" - }, "statuses" : { "description" : "Contains the current status for each status flow this transfer has", "type" : "array", @@ -45705,6 +59599,12 @@ "description" : "The transfer fee amout", "type" : "string", "format" : "number" + }, + "currency" : { + "description" : "The transfer fee currency", + "allOf" : [ { + "$ref" : "#/components/schemas/Currency" + } ] } } }, @@ -45732,16 +59632,43 @@ "type" : "object", "properties" : { "currency" : { - "description" : "Either id or internal name of the currency", + "description" : "DEPRECATED: Use `currencies` instead.\n\nEither id or internal name of the currency", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "string" }, + "currencies" : { + "description" : "Either ids or internal names of the currency", + "type" : "array", + "items" : { + "type" : "string" + } + }, "fromAccountType" : { - "description" : "Either id or internal name of the origin account type", + "description" : "DEPRECATED: Use `fromAccountTypes` instead.\n\nEither ids or internal names of the origin account type", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "string" }, + "fromAccountTypes" : { + "description" : "Either ids or internal names of the origin account type", + "type" : "array", + "items" : { + "type" : "string" + } + }, "toAccountType" : { - "description" : "Either id or internal name of the destination account type", + "description" : "DEPRECATED: Use `toAccountTypes` instead.\n\nEither ids or internal names of the destination account type", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "string" + }, + "toAccountTypes" : { + "description" : "Either ids or internal names of the destination account type", + "type" : "array", + "items" : { + "type" : "string" + } } } } ] @@ -45951,6 +59878,13 @@ }, "usersWhichCanViewProfile" : { "$ref" : "#/components/schemas/TransactionSubjectsEnum" + }, + "exportFormats" : { + "description" : "The formats which the data can be exported", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExportFormat" + } } } } ] @@ -45969,19 +59903,6 @@ } } ] }, - "UnansweredAdQuestionResult" : { - "description" : "An unanswered question for an advertisement.", - "allOf" : [ { - "$ref" : "#/components/schemas/AdQuestion" - }, { - "type" : "object", - "properties" : { - "ad" : { - "$ref" : "#/components/schemas/Ad" - } - } - } ] - }, "UnauthorizedError" : { "description" : "Error returned when a HTTP status code 401 occurs", "type" : "object", @@ -46010,6 +59931,10 @@ "allOf" : [ { "$ref" : "#/components/schemas/PasswordStatusEnum" } ] + }, + "error" : { + "description" : "Is the OAuth2 / OpenID Connect required error message. Is only returned when `code` is `invalidAccessToken`.", + "type" : "string" } } }, @@ -46022,11 +59947,13 @@ "properties" : { "display" : { "type" : "string", - "description" : "Contains the formatting of the user according to the configuration. Is only returned if no profile fields are marked to return in user list." + "description" : "Contains the formatting of the user according to the configuration. When this object is in the search result, this is only returned if no profile fields are marked to return in user list." }, "shortDisplay" : { + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "string", - "description" : "Contains the short formatting of the user according to the configuration. Is only returned if no profile fields are marked to return in user list" + "description" : "DEPRECATED: The short display was originally meant for SMS only. Will be removed in Cyclos 4.15 with no replacement.\n\nContains the optional short formatting of the user according to the configuration. When not defined, the value is not sent. When this object is in the search result, this is only returned if no profile fields are marked to return in user list." }, "image" : { "description" : "The primary user profile image", @@ -46059,6 +59986,27 @@ } } }, + "UserAdInterestsListData" : { + "description" : "Contains, besides the user's advertisement interests, additional data for its management", + "type" : "object", + "properties" : { + "canManage" : { + "description" : "Indicates whether the advertisement interests can be managed by the authenticated user", + "type" : "boolean" + }, + "canCreate" : { + "description" : "Indicates whether the authenticated user can create a new ad interest", + "type" : "boolean" + }, + "adInterests" : { + "description" : "The advertisement interests list", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/AdInterest" + } + } + } + }, "UserAddressesListData" : { "description" : "Contains, besides the user's addresses, additional data for its management", "type" : "object", @@ -46152,6 +60100,9 @@ "items" : { "$ref" : "#/components/schemas/Group" } + }, + "query" : { + "$ref" : "#/components/schemas/UserAlertQueryFilters" } } }, @@ -46217,6 +60168,16 @@ } } ] }, + "UserAuthorizedPaymentsPermissions" : { + "description" : "Permissions for authorized payments over a user", + "type" : "object", + "properties" : { + "view" : { + "description" : "Can the authenticated administrator or broker view authorized payments of the given user?", + "type" : "boolean" + } + } + }, "UserBalanceLimitsPermissions" : { "description" : "Permissions regarding the account balance limits of a given user", "type" : "object", @@ -46227,6 +60188,32 @@ } } }, + "UserBaseAdPermissions" : { + "description" : "Permissions over advertisements of other users", + "type" : "object", + "properties" : { + "view" : { + "description" : "Can view advertisements of others?", + "type" : "boolean" + }, + "manage" : { + "description" : "Can manage advertisements of others? Only returned if there is an authenticated user.", + "type" : "boolean" + }, + "viewPending" : { + "description" : "Can view pending advertisements of others? Only returned if there is an authenticated manager with permissions", + "type" : "boolean" + }, + "managePending" : { + "description" : "Can manage pending advertisements of others? Only returned if there is an authenticated manager with permissions", + "type" : "boolean" + }, + "purchase" : { + "description" : "Can purchase webshop ads? Only returned if there is an authenticated user. It is false for simple ads.", + "type" : "boolean" + } + } + }, "UserBasicData" : { "description" : "Contains properties shared by both UserDataForNew and UserDataForEdit", "type" : "object", @@ -46467,6 +60454,25 @@ }, { "type" : "object", "properties" : { + "group" : { + "description" : "Details of the registration group.", + "allOf" : [ { + "$ref" : "#/components/schemas/GroupForRegistration" + } ] + }, + "broker" : { + "description" : "When the user registration is requested with a broker, contains the broker details.", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "identityProviders" : { + "description" : "The identity providers available for registering in this group. Only returned for public registrations.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/IdentityProvider" + } + }, "addressConfiguration" : { "$ref" : "#/components/schemas/AddressConfigurationForUserProfile" }, @@ -46555,6 +60561,30 @@ } } ] }, + "UserDeliveryMethodsListData" : { + "description" : "Contains, besides the user's delivery methods, additional data for its management", + "type" : "object", + "properties" : { + "user" : { + "$ref" : "#/components/schemas/User" + }, + "canManage" : { + "description" : "Indicates whether the delivery methods can be managed by the authenticated user", + "type" : "boolean" + }, + "canCreate" : { + "description" : "Indicates whether the authenticated user can create a new delivery method this user", + "type" : "boolean" + }, + "deliveryMethods" : { + "description" : "The delivery methods list", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/DeliveryMethod" + } + } + } + }, "UserDocumentsPermissions" : { "description" : "Permissions regarding the documents of a given user", "type" : "object", @@ -46583,6 +60613,16 @@ } } ] }, + "UserExternalPaymentsPermissions" : { + "description" : "Permissions for external payments over a user", + "type" : "object", + "properties" : { + "view" : { + "description" : "Can the authenticated administrator or broker view external payments of the given user?", + "type" : "boolean" + } + } + }, "UserGroupPermissions" : { "description" : "Permissions regarding the group membership of a given user", "type" : "object", @@ -46593,6 +60633,69 @@ } } }, + "UserIdentityProvider" : { + "description" : "A link between a user an an identity provider", + "allOf" : [ { + "$ref" : "#/components/schemas/Entity" + }, { + "type" : "object", + "properties" : { + "identityProvider" : { + "$ref" : "#/components/schemas/IdentityProvider" + }, + "status" : { + "$ref" : "#/components/schemas/UserIdentityProviderStatusEnum" + }, + "linkDate" : { + "description" : "The date the link was created. Only if `status` is `linked`.", + "type" : "string", + "format" : "date-time" + }, + "name" : { + "description" : "The display name of the user in the identity provider. Only if `status` is `linked`.", + "type" : "string" + }, + "email" : { + "description" : "The e-mail name of the user in the identity provider Only if `status` is `linked` and if the provider has disclosed the user's e-mail.", + "type" : "string" + } + } + } ] + }, + "UserIdentityProvidersListData" : { + "description" : "Contains, besides the user's identity provider links, additional data for its management", + "type" : "object", + "properties" : { + "user" : { + "$ref" : "#/components/schemas/User" + }, + "canLink" : { + "description" : "Indicates whether a new identity provider can be linked to the user", + "type" : "boolean" + }, + "canManage" : { + "description" : "Indicates whether existing links can be managed", + "type" : "boolean" + }, + "identityProviders" : { + "description" : "The identity provider links", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/UserIdentityProvider" + } + } + } + }, + "UserIdentityProvidersPermissions" : { + "description" : "Permissions over the identity provider links", + "type" : "object", + "properties" : { + "view" : { + "description" : "Can view the relationships to identity providers?", + "type" : "boolean" + } + } + }, "UserLocale" : { "description" : "Defines the user's language and region", "allOf" : [ { @@ -46629,28 +60732,56 @@ "description" : "Permissions over a user marketplace", "type" : "object", "properties" : { + "simple" : { + "description" : "Permissions over simple advertisements", + "$ref" : "#/components/schemas/UserBaseAdPermissions" + }, + "webshop" : { + "description" : "Permissions over webshop ads", + "$ref" : "#/components/schemas/UserWebshopPermissions" + }, + "viewInterests" : { + "description" : "Can view ad interests? Only returned if there is an authenticated user.", + "type" : "boolean" + }, + "manageInterests" : { + "description" : "Can manage ad interests? Only returned if there is an authenticated user.", + "type" : "boolean" + }, "viewAdvertisements" : { - "description" : "Can view simple advertisements?", + "description" : "Use `simple.view` instead\n\n\nCan view simple advertisements?", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "boolean" }, "manageAdvertisements" : { - "description" : "Can manage simple advertisements?", + "description" : "Use `simple.manage` instead\n\n\nCan manage simple advertisements?", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "boolean" }, "viewWebshop" : { - "description" : "Can view webshop advertisements?", + "description" : "Use `webshop.view` instead\n\n\nCan view webshop advertisements?", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "boolean" }, "manageWebshop" : { - "description" : "Can manage webshop advertisements?", + "description" : "Use `webshop.manage` instead\n\n\nCan manage webshop advertisements?", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "boolean" }, "viewPurchases" : { - "description" : "Can view the purchases?", + "description" : "Use `webshop.viewPurchases` instead\n\n\nCan view the purchases?", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "boolean" }, "viewSales" : { - "description" : "Can view the sales?", + "description" : "Use `webshop.viewSales` instead\n\n\nCan view the sales?", + "deprecated" : true, + "x-remove-version" : 4.15, "type" : "boolean" } } @@ -46667,6 +60798,10 @@ "type" : "string", "description" : "The initial user group" }, + "broker" : { + "type" : "string", + "description" : "Either the identifier or other identification value (login name, e-mail, etc) of the broker for the new user. Only allowed if logged-in as administrator with permission." + }, "mobilePhones" : { "type" : "array", "items" : { @@ -46692,6 +60827,10 @@ "type" : "boolean", "description" : "When set to true, the activation e-mail is not sent to the registered user. Can only be used when an administrator / broker is registering a user, and ignored on public registrations (the e-mail is always sent on public registrations)." }, + "identityProviderRequestId" : { + "type" : "string", + "description" : "When using an [external identity provider](https://wiki4.cyclos.org/index.php/External_identity_providers), this is the request id used to complete the registration process after filling up the registration form." + }, "addresses" : { "type" : "array", "items" : { @@ -46746,6 +60885,16 @@ } } ] }, + "UserNotificationSettingsPermissions" : { + "description" : "Permissions regarding the notification settings of a given user", + "type" : "object", + "properties" : { + "view" : { + "description" : "Can the authenticated user view the notification settings of a given user?", + "type" : "boolean" + } + } + }, "UserOperatorGroupsListData" : { "description" : "Contains, besides the user's operator groups, additional data for their management", "type" : "object", @@ -46867,6 +61016,20 @@ } } ] }, + "UserPasswordsPermissions" : { + "description" : "Permissions over passwords of a given user", + "type" : "object", + "properties" : { + "manage" : { + "description" : "Can the authenticated administrator or broker manage the password(s) of the given user?", + "type" : "boolean" + }, + "resetSecurityQuestion" : { + "description" : "Can the authenticated administrator or broker reset the user's security question, so that the user can set it again?", + "type" : "boolean" + } + } + }, "UserPaymentPermissions" : { "description" : "Permissions for payments regarding a user", "type" : "object", @@ -46893,6 +61056,32 @@ } } }, + "UserPaymentRequestsPermissions" : { + "description" : "Permissions for payment requests over a user", + "type" : "object", + "properties" : { + "view" : { + "description" : "Can the authenticated administrator or broker view payment requests of the given user?", + "type" : "boolean" + }, + "sendFromSystem" : { + "description" : "Can the authenticated administrator send a payment request from system to the given user?", + "type" : "boolean" + }, + "sendFromUser" : { + "description" : "Can the authenticated user send a payment request to the given user?", + "type" : "boolean" + }, + "sendAsUserToUser" : { + "description" : "Can the authenticated administrator or broker send payment requests in behalf of the given user to other users?", + "type" : "boolean" + }, + "sendAsUserToSystem" : { + "description" : "Can the authenticated administrator or broker send payment requests in behalf of the given user to system?", + "type" : "boolean" + } + } + }, "UserPermissions" : { "description" : "Determines permission the authenticated have over a specific user", "type" : "object", @@ -46900,6 +61089,12 @@ "profile" : { "$ref" : "#/components/schemas/UserProfilePermissions" }, + "passwords" : { + "$ref" : "#/components/schemas/UserPasswordsPermissions" + }, + "validation" : { + "$ref" : "#/components/schemas/UserValidationPermissions" + }, "contact" : { "$ref" : "#/components/schemas/UserContactPermissions" }, @@ -46931,6 +61126,30 @@ "payment" : { "$ref" : "#/components/schemas/UserPaymentPermissions" }, + "scheduledPayments" : { + "$ref" : "#/components/schemas/UserScheduledPaymentsPermissions" + }, + "identityProviders" : { + "$ref" : "#/components/schemas/UserIdentityProvidersPermissions" + }, + "recurringPayments" : { + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED: As of Cyclos 4.13, the recurring payments permissions are the same as scheduled payments. Use `scheduledPayments` instead.", + "$ref" : "#/components/schemas/UserScheduledPaymentsPermissions" + }, + "paymentRequests" : { + "$ref" : "#/components/schemas/UserPaymentRequestsPermissions" + }, + "authorizedPayments" : { + "$ref" : "#/components/schemas/UserAuthorizedPaymentsPermissions" + }, + "tickets" : { + "$ref" : "#/components/schemas/UserTicketsPermissions" + }, + "externalPayments" : { + "$ref" : "#/components/schemas/UserExternalPaymentsPermissions" + }, "records" : { "description" : "Records types the authenticated user can view over the given user", "type" : "array", @@ -46952,18 +61171,26 @@ } }, "tokens" : { - "description" : "Tokens the authenticated user can view over the given user", + "description" : "Permissions over tokens of each visible type.", "type" : "array", "items" : { - "$ref" : "#/components/schemas/TokenType" + "$ref" : "#/components/schemas/TokenPermissions" } }, "personalizeNfcTokens" : { - "description" : "NFC tokens the authenticated user can personalize for the given user", + "deprecated" : true, + "x-remove-version" : 4.15, + "description" : "DEPRECATED: Filter the `tokens` list with `type.physicalType = 'nfcTag'` and `activate = true`.\n\nNFC tokens the authenticated user can personalize for the given user", "type" : "array", "items" : { "$ref" : "#/components/schemas/TokenType" } + }, + "vouchers" : { + "$ref" : "#/components/schemas/UserVouchersPermissions" + }, + "notificationSettings" : { + "$ref" : "#/components/schemas/UserNotificationSettingsPermissions" } } }, @@ -47187,9 +61414,17 @@ "type" : "boolean", "description" : "When set to `true`, instead of returning users with corresponding profile fields set on list, will return them with `display` and `shortDisplay`." }, + "contactsOwner" : { + "type" : "string", + "description" : "Indicates the (managed) user to exclude contacts when `excludecontacts` is set. Defaults to the logged user." + }, "excludeContacts" : { "type" : "boolean", - "description" : "When set to `true` will not return any user that is already a contact of the currently authenticated user." + "description" : "When set to `true` will not return any user that is already a contact of the user indicated on `contactsOwner` (the logged user if not set)." + }, + "fromMenu" : { + "type" : "boolean", + "description" : "When set to true the search will be restricted to those groups defined for the user search menu, if false then for those defined in the 'Search users on groups' product setting (or in the configuration in case of guests)." }, "statuses" : { "type" : "array", @@ -47209,6 +61444,74 @@ } } ] }, + "UserReferenceDataForSearch" : { + "description" : "Data for searching references of a given user", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseReferenceDataForSearch" + }, { + "type" : "object", + "properties" : { + "user" : { + "$ref" : "#/components/schemas/User" + }, + "query" : { + "description" : "Default query filters", + "allOf" : [ { + "$ref" : "#/components/schemas/UserReferenceQueryFilters" + } ] + }, + "set" : { + "description" : "Can the authenticated user set a reference to the given user?", + "type" : "boolean" + }, + "current" : { + "description" : "The current reference, if any, from the authenticated user to the given user", + "allOf" : [ { + "$ref" : "#/components/schemas/Reference" + } ] + } + } + } ] + }, + "UserReferenceQueryFilters" : { + "description" : "Query filters for a user's references", + "allOf" : [ { + "$ref" : "#/components/schemas/BaseReferenceQueryFilters" + }, { + "type" : "object", + "properties" : { + "direction" : { + "$ref" : "#/components/schemas/ReferenceDirectionEnum" + }, + "relatedUser" : { + "description" : "The user that either gave or received the reference to the user specified in the path. Should be either the id or some other allowed identification (login name, email, etc).", + "type" : "string" + } + } + } ] + }, + "UserReferenceResult" : { + "description" : "Result of searching references of a given user", + "allOf" : [ { + "$ref" : "#/components/schemas/Reference" + }, { + "type" : "object", + "properties" : { + "relatedUser" : { + "description" : "The user that either gave to or received from the user specified in the path variable.", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, + "direction" : { + "description" : "Whether this reference was given to or received from the user specified in the path variable.", + "allOf" : [ { + "$ref" : "#/components/schemas/ReferenceDirectionEnum" + } ] + } + } + } ] + }, "UserRegistrationPrincipal" : { "description" : "Contains information about a principal (user identification) and the channels that can be accessed using it", "type" : "object", @@ -47323,6 +61626,16 @@ } } ] }, + "UserScheduledPaymentsPermissions" : { + "description" : "Permissions for scheduled payments over a user", + "type" : "object", + "properties" : { + "view" : { + "description" : "Can the authenticated administrator or broker view scheduled payments of the given user?", + "type" : "boolean" + } + } + }, "UserSessionPermissions" : { "description" : "Permissions regarding the login session of a given user", "type" : "object", @@ -47391,6 +61704,58 @@ } } }, + "UserTicketsPermissions" : { + "description" : "Permissions for tickets over a user", + "type" : "object", + "properties" : { + "view" : { + "description" : "Can the authenticated administrator or broker view tickets of the given user?", + "type" : "boolean" + } + } + }, + "UserTokensListData" : { + "description" : "Data for tokens of a specific type and user", + "allOf" : [ { + "$ref" : "#/components/schemas/TokenPermissions" + }, { + "type" : "object", + "properties" : { + "user" : { + "$ref" : "#/components/schemas/User" + }, + "tokens" : { + "description" : "The tokens for this type and user.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Token" + } + } + } + } ] + }, + "UserValidationPermissions" : { + "description" : "Permissions over the registration / email change validations of a given user", + "type" : "object", + "properties" : { + "validateRegistration" : { + "description" : "Can the authenticated administrator or broker manually mark a pending user as validated?", + "type" : "boolean" + }, + "resendRegistrationValidation" : { + "description" : "Can the authenticated administrator or broker re-send the e-mail to confirm the registration of the given user?", + "type" : "boolean" + }, + "validateEmailChange" : { + "description" : "Can the authenticated administrator or broker manually mark a pending e-mail change as validated for the given user?", + "type" : "boolean" + }, + "resendEmailChange" : { + "description" : "Can the authenticated administrator or broker re-send the e-mail to confirm the e-mail change of the given user?", + "type" : "boolean" + } + } + }, "UserView" : { "description" : "Represents a user with all data for viewing the profile", "allOf" : [ { @@ -47411,6 +61776,10 @@ "type" : "string", "description" : "The user's e-mail" }, + "emailPendingValidation" : { + "description" : "Returned for managers / own user when the user has changed his e-mail but hasn't yet validated the new e-mail. The e-mail change validation is a configuration in Cyclos.", + "type" : "string" + }, "enabledProfileFields" : { "description" : "The internal names of profile fields enabled for this user. For example, the user might have no phones, but it might be because he is not allowed to have phones or because there are currently no phones. Same for addresses, images and optional profile fields.", "type" : "array", @@ -47426,17 +61795,23 @@ } }, "group" : { - "description" : "Reference to the user group. Is only returned if the authenticated user has permission to see groups", + "description" : "Reference to the user group. Is only returned if the authenticated user has permission to see groups.", "allOf" : [ { "$ref" : "#/components/schemas/EntityReference" } ] }, "groupSet" : { - "description" : "Reference to the user group set. Is only returned if the authenticated user has permission to see group sets and the user group is in a group set", + "description" : "Reference to the user group set. Is only returned if the authenticated user has permission to see group sets and the user group is in a group set.", "allOf" : [ { "$ref" : "#/components/schemas/EntityReference" } ] }, + "status" : { + "description" : "The user status. Only returned if the authenticated user has permission to view the user status.", + "allOf" : [ { + "$ref" : "#/components/schemas/UserStatusEnum" + } ] + }, "additionalImages" : { "type" : "array", "items" : { @@ -47521,6 +61896,9 @@ "description" : "Contains configuration data for searching vouchers of a user", "type" : "object", "properties" : { + "user" : { + "$ref" : "#/components/schemas/User" + }, "mask" : { "description" : "The input mask for voucher tokens. Optional.", "type" : "string" @@ -47532,11 +61910,40 @@ "$ref" : "#/components/schemas/EntityReference" } }, + "operators" : { + "description" : "When searching for redeemed vouchers, the operators of the redeemer.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/User" + } + }, "query" : { "$ref" : "#/components/schemas/UserVouchersQueryFilters" } } }, + "UserVouchersPermissions" : { + "description" : "Permissions over a user vouchers", + "type" : "object", + "properties" : { + "viewRedeemed" : { + "description" : "Can view redeemed vouchers?", + "type" : "boolean" + }, + "redeem" : { + "description" : "Can redeem vouchers?", + "type" : "boolean" + }, + "viewBought" : { + "description" : "Can view bought vouchers?", + "type" : "boolean" + }, + "buy" : { + "description" : "Can buy vouchers?", + "type" : "boolean" + } + } + }, "UserVouchersQueryFilters" : { "description" : "Definitions for searching vouchers of a user", "allOf" : [ { @@ -47576,6 +61983,10 @@ "format" : "date-time" } }, + "redeemBy" : { + "description" : "The user who perform the redeem action. A user identification value, such as id, username, e-mail, phone, etc. Id is always allowed, others depend on Cyclos configuration. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`;", + "type" : "string" + }, "token" : { "description" : "The voucher token (with or without mask)", "type" : "string" @@ -47599,6 +62010,32 @@ } } ] }, + "UserWebshopPermissions" : { + "description" : "Permissions over webshop asd of a specific user", + "allOf" : [ { + "$ref" : "#/components/schemas/UserBaseAdPermissions" + }, { + "type" : "object", + "properties" : { + "viewPurchases" : { + "description" : "Can view the purchases? Only returned if there is an authenticated user.", + "type" : "boolean" + }, + "viewSales" : { + "description" : "Can view the sales? Only returned if there is an authenticated user.", + "type" : "boolean" + }, + "viewSettings" : { + "description" : "Can view the webshop settings? Only returned if there is an authenticated user.", + "type" : "boolean" + }, + "manageSettings" : { + "description" : "Can manage the webshop settings? Only returned if there is an authenticated user.", + "type" : "boolean" + } + } + } ] + }, "UserWithBalanceResult" : { "description" : "Result of a user search with balance", "allOf" : [ { @@ -47794,6 +62231,9 @@ "description" : "Contains common data for either buying or redeeming a voucher", "type" : "object", "properties" : { + "user" : { + "$ref" : "#/components/schemas/User" + }, "type" : { "$ref" : "#/components/schemas/VoucherTypeDetailed" }, @@ -47845,7 +62285,7 @@ } ] }, "VoucherDataForBuy" : { - "description" : "Data used to buy a voucher", + "description" : "If a type is not specified when requesting this data only the given user data and the list of types the authenticated user can buy for it (could be himself) is returned.", "allOf" : [ { "$ref" : "#/components/schemas/VoucherBasicData" }, { @@ -47877,6 +62317,13 @@ "allOf" : [ { "$ref" : "#/components/schemas/TimeInterval" } ] + }, + "types" : { + "description" : "The list of voucher types the authenticated user can buy to another user (or himself). Only if no type parameter is given.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/VoucherTypeDetailed" + } } } } ] @@ -47910,12 +62357,64 @@ "description" : "Initial data used to redeem vouchers", "type" : "object", "properties" : { + "user" : { + "$ref" : "#/components/schemas/User" + }, "mask" : { "description" : "The voucher token mask", "type" : "string" } } }, + "VoucherPermissions" : { + "description" : "Permissions over vouchers", + "type" : "object", + "properties" : { + "configuration" : { + "$ref" : "#/components/schemas/VoucherConfiguration" + }, + "buy" : { + "description" : "Whether the logged user can buy vouchers of types belonging to this configuration", + "type" : "boolean" + }, + "redeem" : { + "description" : "Whether the logged user can redeem vouchers of types belonging to this configuration", + "type" : "boolean" + }, + "cancel" : { + "description" : "Whether the logged user can cancel vouchers of types belonging to this configuration. Only if the authenticated user is an admin. Otherwise `false`.", + "type" : "boolean" + }, + "changeExpirationDate" : { + "description" : "Whether the logged user can change the expiration date of vouchers of types belonging to this configuration. Only if the authenticated user is an admin. Otherwise `false`.", + "type" : "boolean" + }, + "refund" : { + "description" : "Whether the logged user can refund vouchers of types belonging to this configuration.", + "type" : "boolean" + }, + "generate" : { + "description" : "Whether the logged user can generate vouchers of types belonging to this configuration. Only if the authenticated user is an admin. Otherwise `false`.", + "type" : "boolean" + }, + "view" : { + "description" : "Whether the logged user can view vouchers of types belonging to this configuration. Only if the authenticated user is an admin. Otherwise `false`.", + "type" : "boolean" + }, + "viewBought" : { + "description" : "Whether the logged user can view vouchers bought of types belonging to this configuration. Only if the authenticated user is a member or broker. Otherwise `false`.", + "type" : "boolean" + }, + "viewRedeemed" : { + "description" : "Whether the logged user can view vouchers redeemed of types belonging to this configuration. Only if the authenticated user is a member or broker. Otherwise `false`.", + "type" : "boolean" + }, + "enabled" : { + "description" : "Whether the logged user has enabled the types belonging to this configuration. Only if the authenticated user is a member. Otherwise `false`.", + "type" : "boolean" + } + } + }, "VoucherRedeemResult" : { "description" : "Result when redeeming a voucher", "type" : "object", @@ -47953,6 +62452,12 @@ "type" : "string", "format" : "date-time" }, + "redeemBy" : { + "description" : "The user who perform the redeem action, could be an admin, broker or operator of the redeemer. Is not returned when the voucher was not yet redeemed or if it is the same as the redeemer.", + "allOf" : [ { + "$ref" : "#/components/schemas/User" + } ] + }, "redeemer" : { "description" : "The voucher redeemer. Is not returned when the voucher was not yet redeemed or when searching for redeemed vouchers of a user.", "allOf" : [ { @@ -48048,11 +62553,9 @@ "$ref" : "#/components/schemas/Transaction" } ] }, - "canCancel" : { - "description" : "This is redundant with `cancelAction`, is `false` if `cancelAction` is `null`, and `true` if `cancelAction` is not `null`.\n\n\nCan the authenticated user cancel this voucher?", - "type" : "boolean", - "deprecated" : true, - "x-remove-version" : 4.13 + "canChangeExpirationDate" : { + "description" : "Can the authenticated user change this voucher's expiration date?", + "type" : "boolean" }, "showConfiguration" : { "description" : "Should the voucher configuration be shown to users? This flag is `true` when there are multiple available configurations.", @@ -48071,6 +62574,163 @@ }, "cancelAction" : { "$ref" : "#/components/schemas/VoucherCancelActionEnum" + }, + "refund" : { + "description" : "The transaction which refunds this voucher, if any and visible.", + "allOf" : [ { + "$ref" : "#/components/schemas/Transaction" + } ] + }, + "exportFormats" : { + "description" : "The formats which the data can be exported", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExportFormat" + } + }, + "confirmationPasswordInput" : { + "description" : "If a confirmation password is used, contains the definitions on how to request that password from the user. This confirmation password is required when performing sensible actions. Sometimes this is dynamic, for example, the confirmation might be configured to be used only once per session, or operations like payments may have a limit per day to be without confirmation (pinless).", + "allOf" : [ { + "$ref" : "#/components/schemas/PasswordInput" + } ] + } + } + } ] + }, + "VouchersDataForSearch" : { + "description" : "Contains configuration data for searching vouchers as admin", + "type" : "object", + "properties" : { + "mask" : { + "description" : "The input mask for voucher tokens. Optional.", + "type" : "string" + }, + "types" : { + "description" : "The voucher types that can be used for searching", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/VoucherType" + } + }, + "userGroups" : { + "description" : "Visible user groups for the authenticated user", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Group" + } + }, + "exportFormats" : { + "description" : "The formats which the search results can be exported.", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ExportFormat" + } + }, + "query" : { + "$ref" : "#/components/schemas/VouchersQueryFilters" + } + } + }, + "VouchersPermissions" : { + "description" : "Permissions over voucher configurations", + "type" : "object", + "properties" : { + "vouchers" : { + "description" : "Permissions over each voucher configuration", + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/VoucherPermissions" + } + } + } + }, + "VouchersQueryFilters" : { + "description" : "Definitions for searching vouchers as admin", + "allOf" : [ { + "$ref" : "#/components/schemas/QueryFilters" + }, { + "type" : "object", + "properties" : { + "amountRange" : { + "description" : "The minimum / maximum voucher amount", + "type" : "array", + "items" : { + "type" : "string", + "format" : "number" + } + }, + "creationPeriod" : { + "description" : "The minimum / maximum voucher creation date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "type" : "array", + "items" : { + "type" : "string", + "format" : "date-time" + } + }, + "expirationPeriod" : { + "description" : "The minimum / maximum voucher expiration date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "type" : "array", + "items" : { + "type" : "string", + "format" : "date-time" + } + }, + "redeemPeriod" : { + "description" : "The minimum / maximum voucher redeem date. Is expressed an array, with the lower bound as first element, and the upper bound as second element. When only one element, will have just the lower bound. To specify only the upper bound, prefix the value with a comma.", + "type" : "array", + "items" : { + "type" : "string", + "format" : "date-time" + } + }, + "token" : { + "description" : "The voucher token (with or without mask)", + "type" : "string" + }, + "types" : { + "description" : "The ids or internal names of voucher types", + "type" : "array", + "items" : { + "type" : "string" + } + }, + "statuses" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/VoucherStatusEnum" + } + }, + "creationType" : { + "$ref" : "#/components/schemas/VoucherCreationTypeEnum" + }, + "printed" : { + "description" : "If it is passed, filter if the voucher was printed or not.", + "type" : "boolean" + }, + "buyer" : { + "description" : "The buyer of the voucher. A user identification value, such as id, username, e-mail, phone, etc. Id is always allowed, others depend on Cyclos configuration. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`;", + "type" : "string" + }, + "redeemer" : { + "description" : "The redeemer of the voucher. A user identification value, such as id, username, e-mail, phone, etc. Id is always allowed, others depend on Cyclos configuration. Note that a valid numeric value is always considered as id. For example, when using another identification method that can be numeric only, prefix the value with a single quote (like in Excel spreadsheets), for example, `'1234567890`;", + "type" : "string" + }, + "buyerGroups" : { + "description" : "The ids or internal names of buyers groups", + "type" : "array", + "items" : { + "type" : "string" + } + }, + "redeemerGroups" : { + "description" : "The ids or internal names of redeemers groups", + "type" : "array", + "items" : { + "type" : "string" + } + }, + "orderBy" : { + "$ref" : "#/components/schemas/VoucherOrderByEnum" } } } ] @@ -48111,6 +62771,61 @@ } } } ] + }, + "WebshopSettings" : { + "description" : "Base Settings for a user's webshop", + "type" : "object", + "properties" : { + "productNumberGenerated" : { + "type" : "boolean", + "description" : "Whether the product number, which is required for webshop advertisements, will be generated (true) or manual (false)." + }, + "productNumberMask" : { + "type" : "string", + "description" : "A mask that indicates the format of product numbers. The following characters are accepted:\n- `?`, `_`: Any character; - `#`, `0`, `9`: A digit; - `A`, `a`: A letter (regardless the case); - `L`, `l`: A lowercase letter; - `U`, `u`: An uppercase letter; - `C`, `c`: A capitalized letter; - `\\` folowed by any character, or any character not in the list\n above: A literal character.", + "example" : "UUU-####" + } + } + }, + "WebshopSettingsDetailed" : { + "description" : "Settings for a user's webshop", + "allOf" : [ { + "$ref" : "#/components/schemas/WebshopSettings" + }, { + "type" : "object", + "properties" : { + "customOrderNumberFormat" : { + "type" : "boolean", + "description" : "Whether orders will have a custom format for assigned numbers. When set, the number will be generated from a given prefix, inner length and suffix. When false, a numeric string will be used." + }, + "orderNumberPrefix" : { + "type" : "string", + "description" : "The order number prefix. You can generate a date part by using a [Java date pattern](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html) between sharp (#) characters.", + "example" : "#yyyyMM#-" + }, + "orderNumberInnerLength" : { + "type" : "integer", + "description" : "The size of the numerical part of the order number." + }, + "orderNumberSuffix" : { + "type" : "string", + "description" : "The order number suffix. You can generate a date part by using a [Java date pattern](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html) between sharp (#) characters." + } + } + } ] + }, + "WebshopSettingsView" : { + "description" : "Details of a user webshop settings", + "allOf" : [ { + "$ref" : "#/components/schemas/WebshopSettingsDetailed" + }, { + "type" : "object", + "properties" : { + "user" : { + "$ref" : "#/components/schemas/User" + } + } + } ] } } }