{ "openapi": "3.0.0", "info": { "title": "Spaycial REST API", "version": "3.2.0", "description": "The Spaycial REST API lets your programme register members, follow their bank connections and receive enriched transactions. Start with the [Docs](/docs/) and the [Quick start](/docs/getting-started/quick-start/)." }, "paths": { "/banks": { "x-swagger-router-controller": "bank_api", "get": { "description": "Lists the banks available in your programme.\n\nThis endpoint is not meant to display banks to your members: the bank choice is part of the Spaycial Web UI, which members reach through the onboarding flow. Use it to monitor which banks are open in your programme.\n\nTo be notified when Spaycial adds a bank to, or removes one from, your programme, subscribe to the [bank_association_notification](/docs/webhooks/bank_association_notification/) webhook.", "operationId": "getBanks", "tags": [ "bank" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "cardType", "description": "type of card associated to this bank (bank vs restaurant )", "in": "query", "schema": { "type": "string", "enum": [ "bank", "restaurant" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "title": "Bank", "properties": { "id": { "type": "string", "description": "bank id in data provider's repository" }, "name": { "type": "string", "description": "bank name" }, "countryCode": { "type": "string", "description": "country code of the bank" }, "available": { "type": "boolean", "description": "true if the bank is available for connection, false otherwise (use to make teasing on future banks)" }, "interactive": { "type": "boolean", "description": "true if the bank requires user interaction, false otherwise" }, "cardType": { "type": "string", "description": "type of card associated to this bank (bank vs restaurant )", "enum": [ "bank", "restaurant" ] }, "logoUrl": { "type": "string", "description": "url of bank logo" }, "type": { "type": "string", "description": "type of data provider connection", "enum": [ "PSD2", "SCR" ] } }, "required": [ "id", "name", "countryCode", "cardType" ] }, "example": { "application/json": [ [ { "id": "d9a25c93-bda9-4253-a49b-45f2a0979847", "name": "A French Bank", "countryCode": "FR", "available": true, "cardType": "bank", "logoUrl": "http://logo.com/frenchbank.png" }, { "id": "4adb3a28-81e3-4e76-9a7f-ec59870b4893", "name": "Rest DE", "countryCode": "DE", "available": false, "cardType": "rest", "logoUrl": "http://logo.com/rest.png" } ] ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes for GET /banks\n* `invalidCountry` - Country parameter is invalid. Need to be 2 letters ISO code. Multiple countries seperated with comma.\n", "enum": [ "invalidCountry" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List banks" } }, "/auth/optins": { "x-swagger-router-controller": "auth_api", "get": { "description": "get optins list", "operationId": "getOptins", "tags": [ "auth" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "lng", "description": "country code (2 letters) used to filter bank list by country", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "registrationType", "description": "type of customer registration, default 'SCR' (optins depend on registation type)", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "restaurant", "receipt", "CLO", "PSD2", "SCR", "COM" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "title": "Optin", "properties": { "code": { "type": "string", "description": "optin code" }, "label": { "type": "string", "description": "optin label" }, "headerTranslationKey": { "type": "string", "description": "optin header label key optional" }, "required": { "type": "boolean", "description": "true if optin is mandatory, false otherwise" } }, "required": [ "code", "label", "required" ] }, "example": { "application/json": [ [ { "code": "optin1", "label": "This optin is mandatory", "required": true }, { "code": "optin2", "label": "This optin is optional", "required": false } ] ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes for GET /banks\n* `invalidLanguage` - invalid language code\n", "enum": [ "invalidLanguage" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List available opt-ins" } }, "/auth/registration": { "x-swagger-router-controller": "auth_api", "post": { "description": "register to Spaycial using an identifier (mobile phone, email, external id, ...)", "operationId": "postRegistration", "tags": [ "auth" ], "security": [ { "apiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "title": "RegistrationInfo", "properties": { "phoneNumber": { "type": "string", "description": "phone number, without any prefix" }, "countryCode": { "type": "integer", "description": "phone country code (i.e. 33 for France)" }, "captcha": { "type": "string", "description": "google recaptcha code to avoid bot registration" }, "origin": { "type": "string", "description": "customer origin", "enum": [ "email", "iOS-app", "Android-app", "website", "desk" ] }, "referer": { "type": "string", "description": "customer referer, a string identifying previous page visited before registering" }, "customerExternalId": { "type": "string", "description": "customer identifier in programme repository" }, "firstName": { "type": "string", "description": "customer's first name" }, "lastName": { "type": "string", "description": "customer's last name" }, "familyStatus": { "type": "string", "description": "Family situation of the customer\n* `singleWithoutChildren` - single customer without children\n* `singleWithChildren` - single customer with children\n* `marriedWithoutChildren` - married customer without children\n* `marriedWithChildren` - married customer without children\n", "enum": [ "singleWithoutChildren", "singleWithChildren", "marriedWithoutChildren", "marriedWithChildren" ] }, "postalCode": { "type": "string", "description": "The postal code of the address - can be alphanumeric, dashes or spaces" }, "email": { "type": "string", "description": "email of the customer" }, "optins": { "type": "array", "title": "Array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "optin code get from GET /auth/optins API" }, "value": { "type": "boolean", "description": "true if the optin has been validated, false otherwhise" } } } }, "outsideOptIn": { "type": "boolean", "description": "true if customer accepts its out of mall transactions to be analyzed, false otherwhise" }, "referralInfo": { "type": "object", "title": "ReferralInfo", "description": "referral information to get referral offer", "properties": { "code": { "type": "string", "description": "referral code" }, "phoneNumber": { "type": "string", "description": "referral's phone number, without any prefix" }, "countryCode": { "type": "integer", "description": "referral's phone country code (i.e. 33 for France)" } } }, "preferredLanguage": { "type": "string", "description": "customer preferred language for communication (email, sms...) - ISO 639-1 format is expected (i.e. fr-FR or en)" }, "transactionsEligibleFromDate": { "type": "number", "description": "Unix Timestamp (in seconds) representing the start date from where the customer's transactions will be pushed. If not provided, it will default to the customer's registrationDate" } } } } }, "description": "body containing registration info", "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "id of connected customer" }, "bankAlreadyConnected": { "type": "boolean", "description": "true if customer is already known and has a bank account connected, false otherwhise" }, "registrationToken": { "type": "string", "description": "registration token to provide along the registration requests" } }, "required": [ "customerId", "bankAlreadyConnected" ], "example": { "application/json": [ { "customerId": "91c2003e-3eb0-87c6-ac8d-4fcaad4cbd19", "bankAlreadyConnected": false } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of registration\n* `phoneRequired` - phone number is required (countryCode + phoneNumber)\n* `emailRequired` - email is required\n* `customerExternalIdRequired` - customer external id (in programme repository)\n* `captchaRequired` - recaptcha code is required to ensure submission is not made by a bot\n* `invalidBirthDate` - birth date provided is invalid\n* `invalidEmail` - email is invalid\n* `invalidLanguage` - invalid preferred language\n* `invalidCaptcha` - provided captcha is invalid\n* `invalidOptins` - provided optins are invalid\n* `emailAlreadyUsed` - email is already taken\n* `externalIdAlreadyUsed` - external id is already taken\n* `numberAlreadyUsed` - phone number is already taken (legacy code, same as phoneAlreadyUsed)\n* `alreadyRegistered` - given customer already complete registration process\n* `invalidSponsorshipCode` - No valid sponsorship code\n* `invalidTransactionsEligibleFromDate` - Invalid transactionsEligibleFromDate: Valid values are dates between today and past 90 days\n* `invalidRegistration` - Registration is currently unavailable for this programme\n", "enum": [ "phoneRequired", "emailRequired", "customerExternalIdRequired", "captchaRequired", "invalidBirthDate", "invalidEmail", "invalidCaptcha", "invalidLanguage", "emailAlreadyUsed", "phoneAlreadyUsed", "externalIdAlreadyUsed", "numberAlreadyUsed", "alreadyRegistered", "invalidSponsorshipCode" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Register a member" } }, "/auth/receipt": { "x-swagger-router-controller": "auth_api", "post": { "description": "Allows a customer to register by uploading a receipt", "operationId": "postFirstReceipt", "tags": [ "customer", "auth" ], "security": [ { "registrationJWT": [] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "description": "Image of the receipt to upload", "type": "string", "format": "binary" }, "customerId": { "description": "Customer identifier", "type": "string" }, "optins": { "description": "Stringified optins JSON object which contains array of optins objects with string code and boolean value", "type": "string" } }, "required": [ "customerId", "optins" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "isProperReceiptExtract": { "type": "boolean", "description": "true if extracted data contains all essential information we need, false otherwhise" } }, "example": { "application/json": [ { "isProperReceiptExtract": true } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes for POST /customer/receipts and POST /auth/receipt\n* `invalidCustomer` - Invalid customer identifier\n* `invalidOptins` - optins parameter is invalid\n* `invalidFileType` - Invalid file type\n* `tooLargeFile` - The provided file is too large\n", "enum": [ "invalidCustomer", "invalidOptins", "invalidFileType", "tooLargeFile" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "alreadyExists" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Register a member with a first receipt", "x-spaycial-profiles": [ { "option": "scan", "notRelevantWhen": "disabled" } ] } }, "/auth/bank/connectionCallback": { "x-swagger-router-controller": "auth_api", "post": { "description": "Add a first bank connection to customer by providing bank website callback code", "operationId": "postBankConnectionCallback", "tags": [ "auth" ], "security": [ { "apiKey": [], "registrationJWT": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "customer identifier get from /auth/register response" }, "bankId": { "description": "identifier of the bank to connect with (found in GET /banks)", "nullable": true, "type": "string" }, "dataProviderConnectionId": { "description": "identifier of the bank connection in data provider repository (found in GET /banks)", "nullable": true, "type": "string" }, "queryString": { "type": "object", "description": "object containing the temp code retrieved from psd2 callback login and the customer_id" }, "redirectUri": { "type": "string", "description": "the URI where to redirect to" } }, "required": [ "customerId" ] } } }, "description": "body containing connection info", "required": true }, "responses": { "200": { "description": "A jwt token to access Spaycial authenticated APIs", "content": { "application/json": { "schema": { "type": "object", "properties": { "bankConnectionId": { "type": "string", "description": "the identifier of the bank connection created" }, "accessToken": { "type": "string", "description": "access token, to provide in Authorization header for matching routes" } }, "required": [ "bankConnectionId", "accessToken" ], "example": { "application/json": [ { "bankConnectionId": "c0b88330-ec05-49c3-99eb-e67b1a1e3fc9", "accessToken": "xxxxx.yyyyy.zzzzz" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of bank connection\n* `bankNotFound` - Bank not found\n* `customerNotFound` - Customer not found\n* `bankNotAvailable` - Bank exists but is not available for connection\n* `alreadyRegistered` - Customer already complete registration process\n* `bankAlreadyConnected` - Customer already has a bank connection\n* `credentialsRequired` - Credentials are required\n* `invalidCredentials` - Provided credentials are invalid\n* `actionNeeded` - An action is needed on the bank website\n* `alreadyUsedCredentials` - Credentials already used\n* `invalidCustomer` - Invalid customer id\n* `providerError` - Failed to create connection with the bank\n* `ConnectionNotFoundInSe` - Connection Not Found In Salt Edge\n", "enum": [ "bankNotFound", "customerNotFound", "bankNotAvailable", "alreadyRegistered", "bankAlreadyConnected", "credentialsRequired", "invalidCredentials", "actionNeeded", "alreadyUsedCredentials", "invalidCustomer", "providerError", "ConnectionNotFoundInSe" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Add a first bank connection from a bank callback" } }, "/auth/token": { "x-swagger-router-controller": "auth_api", "get": { "description": "Get an access token for the given customerId or customerExternalId.\n\nPlease note that before generating the access token, we need to verify your customer's external token (see [here](/docs/authentication/access-token-validation/) for detailed information on how we proceed)\n", "operationId": "getAccessToken", "tags": [ "auth" ], "security": [ { "apiKey": [], "signature": [] } ], "parameters": [ { "name": "customerId", "description": "customer identifier get from /auth/register response", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "customerExternalId", "description": "the customer external id", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "x-access-token", "description": "the customer access token in mall repository", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Expires-at", "description": "request expiration time as a UNIX timestamp in UTC timezone. We suggest to use +1 minute from the current time.", "in": "header", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "access token, to provide in Authorization header for matching routes" } }, "required": [ "accessToken" ], "example": { "application/json": [ { "accessToken": "xxxxx.yyyyy.zzzzz" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of GET /auth/token\n* `invalidCustomer` - Invalid customer id\n* `invalidExternalToken` - Invalid external token\n* `customerNotFound` - Customer not found\n* `incompleteRegistration` - Customer must complete registration\n", "enum": [ "invalidCustomer", "invalidExternalToken", "customerNotFound", "incompleteRegistration" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Get an access token" } }, "/auth/login": { "x-swagger-router-controller": "auth_api", "post": { "description": "login to Spaycial using mobile phone and password", "operationId": "postLogin", "tags": [ "auth" ], "security": [ { "apiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "phone number, without any prefix" }, "countryCode": { "type": "integer", "description": "phone country code (i.e. 33 for France)" }, "email": { "type": "string", "description": "customer's email" }, "password": { "type": "string", "description": "customer's area password" } }, "required": [ "password" ] } } }, "description": "the body containing login info", "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "access token, to provide in Authorization header for matching routes" } }, "required": [ "accessToken" ], "example": { "application/json": [ { "accessToken": "xxxxx.yyyyy.zzzzz" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of POST /auth/login\n* `incompleteRegistration` - Customer must complete registration before he can login\n* `invalidCredentials` - Invalid credentials\n* `blockedAccount` - Account is blocked\n", "enum": [ "customerNotFound", "incompleteRegistration" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Log in with phone and password" } }, "/auth/passwordEmailConfirmation": { "x-swagger-router-controller": "auth_api", "get": { "description": "get an email containing a URL to confirm the password creation request", "operationId": "getPasswordEmailConfirmation", "tags": [ "auth" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "email", "description": "customer's email", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of GET /auth/login\n* `emailNotFound` - Email not found\n* `incompleteRegistration` - Customer must complete registration\n", "enum": [ "emailNotFound", "incompleteRegistration" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Send the password confirmation email" } }, "/auth/temporaryCode": { "x-swagger-router-controller": "auth_api", "get": { "description": "get an SMS temporary code to confirm customer identity", "operationId": "getTemporaryCode", "tags": [ "auth" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "phoneNumber", "description": "phone number, without any prefix", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "countryCode", "description": "phone country code (i.e. 33 for France)", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of GET /auth/temporaryCode\n* `unknownPhone` - Invalid phone number\n* `incompleteRegistration` - Customer must complete registration before asking a temporary code\n", "enum": [ "unknownPhone", "incompleteRegistration" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Send an SMS verification code" }, "post": { "description": "post the temporary code received via SMS to confirm identity", "operationId": "postTemporaryCode", "tags": [ "auth" ], "security": [ { "apiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "phone number, without any prefix" }, "countryCode": { "type": "integer", "description": "phone country code (i.e. 33 for France)" }, "temporaryCode": { "type": "string", "description": "temporary code, received by SMS" } }, "required": [ "phoneNumber", "countryCode", "temporaryCode" ] } } }, "description": "the body containing code information", "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "access token, to provide in Authorization header for matching routes" } }, "required": [ "accessToken" ], "example": { "application/json": [ { "accessToken": "xxxxx.yyyyy.zzzzz" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of POST /auth/temporaryCode\n* `unknownPhone` - Invalid phone number\n* `incompleteRegistration` - Customer must complete registration before sending a temporary code\n* `invalidCode` - Provided code is invalid\n* `askCodeBefore` - No code asked before\n* `maxAttemptReached` - Max attempt reached\n* `expiredCode` - Code is too old\n", "enum": [ "unknownPhone", "incompleteRegistration", "invalidCode", "askCodeBefore", "maxAttemptReached", "expiredCode" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Confirm an SMS verification code" } }, "/admin/stores": { "x-swagger-router-controller": "admin_api", "get": { "description": "Get all stores for your programme", "operationId": "getStoresList", "tags": [ "admin" ], "security": [ { "apiKey": [], "signature": [] } ], "responses": { "200": { "description": "return an array of object with all the stores", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "shoppingHubShortcut": { "type": "string", "description": "shoppingHub shortcut" }, "storeExternalId": { "type": "string", "description": "store external id" }, "retailerName": { "type": "string", "description": "retailer name of the store" }, "address": { "type": "string", "description": "address of the store" }, "locality": { "type": "string", "description": "locality of the store" }, "inProgram": { "type": "boolean", "description": "true if the store is part of the program, false otherwise" }, "closingDate": { "type": "string", "description": "date-time when the store is permanently closed", "format": "date-time" }, "status": { "type": "string", "description": "the store status. 'open' means the store is currently open for business, 'permanently_closed' means the store is permanently_closed and will never reopen.", "enum": [ "open", "permanently_closed" ] } } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "502": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "badGetaway" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List the programme's stores" } }, "/admin/stores/v2": { "x-swagger-router-controller": "admin_api", "post": { "description": "Synchronize the program's store list with the Spaycial repository (for the updates, you don't have to provide the full store list as our system is able to handle incremental updates)", "operationId": "postStoresListV2", "tags": [ "admin" ], "security": [ { "apiKey": [], "signature": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "stores": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "externalId": { "type": "string", "minLength": 1, "description": "the store identifier in your repository" }, "brandName": { "type": "string", "minLength": 1, "description": "retailer name (brand name) for the store to create" }, "isOnline": { "type": "boolean", "description": "true if the store is an online point of sale, false if it's a brick and mortar point of sale" }, "googlePlaceId": { "type": "string", "minLength": 1, "description": "the Google Places Identifier of the store, required when isOnline=false (see https://developers.google.com/maps/documentation/places/web-service/place-id)" }, "website": { "type": "string", "description": "the website of the store (ex. 'https://my-fashion-store.com'), required when isOnline=true" }, "status": { "type": "string", "description": "the store status. 'open' means the store is currently open for business, 'permanently_closed' means the store is permanently_closed and will never reopen.", "enum": [ "open", "permanently_closed" ] }, "inProgram": { "type": "boolean", "description": "true if the store is part of the program (default value if not provided), false otherwise (for instance, in a loyalty program, a supermarket could be located in the mall but could be excluded from the offers of the program)" }, "closingDate": { "type": "string", "description": "date-time when the store has permanently closed (don't set this date if a store is temporary closed)", "format": "date-time" } }, "required": [ "externalId", "brandName", "isOnline", "status" ] } } } } } }, "description": "the body containing the stores information", "required": true }, "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes\n* `RequestValidationError` - OpenAPI format error (for instance if a required parameter is missing or does not have the right format)\n", "enum": [ "RequestValidationError" ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Synchronise the store list", "x-spaycial-profiles": [ { "option": "storeReferential", "notRelevantWhen": "spaycialPlatform" } ] } }, "/shoppingHub/webhooks": { "x-swagger-router-controller": "shopping_hub_api", "get": { "description": "get all the subscribed webhooks", "operationId": "getWebhooks", "tags": [ "shoppingHub" ], "security": [ { "apiKey": [], "signature": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "webhookId": { "type": "string", "description": "the webhook id" }, "name": { "type": "string", "description": "an optional webhook name" }, "url": { "type": "string", "description": "the webhook endpoint to post events" }, "events": { "type": "array", "items": { "type": "string", "description": "Webhook events\n* `bank_connections_update_v2` - A bank connection is created, updated or removed\n* `bank_status_update` - Event trigger when bank active status is updated\n* `bank_association_notification` - A bank has been removed or added to a program\n* `customer_creation` - A customer has been created\n* `customer_subscription` - A customer subscribed\n* `customer_transactions` - A customer transaction has been created (mall programs only)\n* `all_transactions` - All enriched transactions for non-mall programs\n* `receipt_updated` - A receipt status has been updated (pending, validated, rejected)\n* `store_list_updated` - A request has been made to POST /admin/stores/v2 and the store referential update is over\n* `offer_updated` - An offer of the loyalty program has been created or updated\n* `reward_updated` - A member of the program has made progress on a given offer\n* `initial_transaction_update` - An initial transaction status has been updated (created, validated, rejected)\n", "enum": [ "bank_status_update", "bank_association_notification", "bank_connections_update_v2", "customer_creation", "customer_subscription", "customer_transactions", "all_transactions", "receipt_updated", "store_list_updated", "offer_updated", "reward_updated", "initial_transaction_update" ] } }, "active": { "type": "boolean", "description": "whether the webhook is active" } } } }, "examples": { "response": { "value": [ [ { "webhookId": "055b00a5-bd3e-482e-897c-0bcca6054dcf", "name": "Webhook Spaycial", "url": "https://transactionconnect.com/webhook", "events": [ "bank_connections_update_v2", "receipt_updated", "customer_transactions", "all_transactions", "customer_creation", "customer_subscription", "claim_update", "initial_transaction_update" ], "active": true } ] ] } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List webhooks" } }, "/admin/sendInitialTransaction": { "x-swagger-router-controller": "admin_api", "post": { "description": "Send an initial transaction for store enrichment setup. This allows clients to send transaction information to initialize the enrichment algorithm for a store.", "operationId": "postSendInitialTransaction", "tags": [ "admin" ], "security": [ { "apiKey": [], "signature": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerExternalId": { "type": "string", "description": "the customer identifier in the client repository" }, "storeExternalId": { "type": "string", "description": "the store identifier in the client repository (must match the externalId provided when syncing stores via POST /admin/stores/v2)" }, "transactionDate": { "type": "string", "format": "date", "description": "the date of the transaction (YYYY-MM-DD)" }, "transactionAmount": { "type": "number", "description": "the amount of the transaction" }, "transactionLabel": { "type": "string", "description": "the label of the transaction (optional but could help to spot the transaction)" } }, "required": [ "customerExternalId", "storeExternalId", "transactionDate", "transactionAmount" ] } } }, "description": "the body containing the initial transaction information", "required": true }, "responses": { "201": { "description": "Initial transaction created successfully" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes for initial transaction\n* `customerExternalIdRequired` - Customer external ID is required\n* `storeExternalIdRequired` - Store external ID is required\n* `transactionDateRequired` - Transaction date is required\n* `transactionAmountRequired` - Transaction amount is required\n* `invalidTransactionDate` - Transaction date is invalid\n* `invalidAmount` - Transaction amount is invalid\n* `customerNotFound` - Customer not found\n* `storeNotFound` - Store not found\n", "enum": [ "customerExternalIdRequired", "storeExternalIdRequired", "transactionDateRequired", "transactionAmountRequired", "invalidTransactionDate", "invalidAmount", "customerNotFound", "storeNotFound" ] }, "message": { "type": "string", "description": "Error message" } }, "required": [ "requestId" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Customer or store not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Send an initial transaction", "x-spaycial-profiles": [ { "option": "transactionInit", "notRelevantWhen": "spaycialWebapp" } ] } }, "/shoppingHub/webhook": { "x-swagger-router-controller": "shopping_hub_api", "post": { "description": "add a webhook too be posted events onto", "operationId": "postWebhook", "tags": [ "shoppingHub" ], "security": [ { "apiKey": [], "signature": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "an optional webhook name to let the client identify the webhooks" }, "url": { "type": "string", "description": "the webhook endpoint to post events" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "description": "Webhook events\n* `bank_connections_update_v2` - A bank connection is created, updated or removed\n* `bank_status_update` - Event trigger when bank active status is updated\n* `bank_association_notification` - A bank has been removed or added to a program\n* `customer_creation` - A customer has been created\n* `customer_subscription` - A change occurred in a customer subscription\n* `claim_update` - A claim has been posted, validated or rejected\n* `customer_transactions` - A customer transaction has been created (mall programs only)\n* `all_transactions` - All enriched transactions for non-mall programs\n* `receipt_updated` - A receipt status has been updated (pending, validated, rejected)\n* `store_list_updated` - A request has been made to POST /admin/stores/v2 and the store referential update is over\n* `offer_updated` - An offer of the loyalty program has been created or updated\n* `reward_updated` - A member of the program has made progress on a given offer\n* `initial_transaction_update` - An initial transaction status has been updated (created, validated, rejected)\n", "enum": [ "claim_update", "bank_status_update", "bank_association_notification", "bank_connections_update_v2", "customer_creation", "customer_subscription", "customer_transactions", "all_transactions", "receipt_updated", "store_list_updated", "offer_updated", "reward_updated", "initial_transaction_update" ] } }, "active": { "type": "boolean", "description": "weather the webhook is active", "default": true } }, "required": [ "url", "events" ] } } }, "description": "body containing connection info", "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string", "description": "the webhook id" } }, "required": [ "webhookId" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of bank connection\n* `invalidURL` - Url is not valid\n* `eventDoesNotExist` - Some events doeas not exist\n* `invalidApiKeyHeader` - Invalid Api-Key header\n", "enum": [ "invalidURL", "eventDoesNotExist", "invalidApiKeyHeader" ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Register a webhook" }, "patch": { "description": "patch an existing webhook", "operationId": "patchWebhook", "tags": [ "shoppingHub" ], "security": [ { "apiKey": [], "signature": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string", "description": "the webhookId to patch" }, "name": { "type": "string", "description": "an optional webhook name to let the client identify the webhooks" }, "url": { "type": "string", "description": "the webhook endpoint to post events" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "description": "Webhook events\n* `bank_connections_update_v2` - A bank connection is created, updated or removed\n* `bank_status_update` - Event trigger when bank active status is updated\n* `bank_association_notification` - A bank has been removed or added to a program\n* `customer_creation` - A customer has been created\n* `customer_subscription` - A customer subscribed\n* `customer_transactions` - A customer transaction has been created (mall programs only)\n* `all_transactions` - All enriched transactions for non-mall programs\n* `receipt_updated` - A receipt status has been updated (pending, validated, rejected)\n* `store_list_updated` - A request has been made to POST /admin/stores/v2 and the store referential update is over\n* `offer_updated` - An offer of the loyalty program has been created or updated\n* `reward_updated` - A member of the program has made progress on a given offer\n* `initial_transaction_update` - An initial transaction status has been updated (created, validated, rejected)\n", "enum": [ "bank_status_update", "bank_association_notification", "bank_connections_update_v2", "customer_creation", "customer_subscription", "customer_transactions", "all_transactions", "receipt_updated", "store_list_updated", "offer_updated", "reward_updated", "initial_transaction_update" ] } }, "active": { "type": "boolean", "description": "weather the webhook is active", "default": true } }, "required": [ "webhookId" ] } } }, "description": "body containing connection info", "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string", "description": "the webhook id" } }, "required": [ "webhookId" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of bank connection\n* `invalidURL` - Url is not valid\n* `eventDoesNotExist` - Some events doeas not exist\n* `invalidApiKeyHeader` - Invalid Api-Key header\n", "enum": [ "invalidURL", "eventDoesNotExist", "invalidApiKeyHeader" ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Update a webhook" } }, "/shoppingHub/webhook/{webhookId}": { "x-swagger-router-controller": "shopping_hub_api", "delete": { "description": "delete a webhook and its associated events", "operationId": "deleteWebhook", "tags": [ "shoppingHub" ], "security": [ { "apiKey": [], "signature": [] } ], "parameters": [ { "name": "webhookId", "in": "path", "description": "the webhookId", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Delete a webhook" } }, "/shoppingHub/customers/balances": { "x-swagger-router-controller": "shopping_hub_api", "post": { "description": "get the current balance of one or more members of the caller's programme", "operationId": "getCustomerBalances", "tags": [ "shoppingHub" ], "security": [ { "apiKey": [], "signature": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "description": "Max 100 distinct members per request; chunk client-side for larger sets.", "items": { "type": "string", "description": "a member identifier - the Spaycial member id, or the member's identifier in your own system" } } } } } }, "description": "the customerId (uuid) or external_id of the members to fetch balances for", "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "balances": { "type": "array", "items": { "type": "object", "properties": { "customerId": { "type": "string", "description": "the Spaycial customer id (UUID)" }, "externalId": { "type": "string", "description": "the member's external id, null if not set" }, "hubId": { "type": "string", "description": "the caller's programme id (always the authenticated programme)" }, "balanceCents": { "type": "integer", "description": "The current balance as an integer amount in the minor unit of `currency`\n(e.g. cents for EUR). Divide by 100 for the displayed amount. This holds for\nevery program type; `balanceType` indicates the kind of loyalty benefit, not a\ndifferent unit.\n" }, "currency": { "type": "string", "description": "the programme currency, trimmed and uppercased, null if unknown" }, "balanceType": { "type": "string", "description": "The kind of loyalty benefit the member's balance represents:\n* `points` - a loyalty points program\n* `gift_card` - a gift-card program\n", "enum": [ "points", "gift_card" ] } } } }, "notFound": { "type": "array", "items": { "type": "string" }, "description": "requested ids not matched by any member in the caller's programme" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes for the customer balances endpoint\n* `invalidParameter` - ids is missing, not an array, empty, or contains a non-string/blank element\n* `tooManyIds` - ids contains more than 100 elements after dedupe\n", "enum": [ "invalidParameter", "tooManyIds" ] }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Get members' balances" } }, "/customer": { "x-swagger-router-controller": "customer_api", "get": { "description": "Get current customer information (deduced from header token)", "operationId": "getCustomer", "tags": [ "customer" ], "security": [ { "JWT": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "title": "CustomerInfo", "properties": { "customerId": { "type": "string", "description": "customer's id" }, "hubExternalId": { "type": "string", "description": "programme external id'" }, "hubName": { "type": "string", "description": "programme's name" }, "firstName": { "type": "string", "description": "customer's first name" }, "lastName": { "type": "string", "description": "customer's last name" }, "scanEnable": { "type": "boolean", "description": "true if scan is enable for customer, false otherwise" }, "email": { "type": "string", "description": "customer's email" }, "bankAlreadyConnected": { "type": "boolean", "description": "information about customer's bank connection" }, "registered": { "type": "boolean", "description": "true if customer is registered, false otherwise" }, "phoneVerified": { "type": "boolean", "description": "information about customer's phone verfication" }, "phoneNumber": { "type": "string", "description": "phone number, without any prefix" }, "countryCode": { "type": "integer", "description": "phone country code (i.e. 33 for France)" }, "createdAt": { "type": "string", "description": "date-time of the customer's creation", "format": "date-time" }, "referralCode": { "type": "string", "description": "the referral code of a customer" } }, "required": [ "bankAlreadyConnected", "customerId", "scanEnable", "registered", "createdAt" ], "example": { "application/json": [ { "customerId": "c5562d40-be8b-43cf-88ca-96933e76629f", "firstName": "John", "bankAlreadyConnected": true, "email": "foo@bar.com", "phoneVerified": true, "registered": true, "createdAt": "2018-10-19T16:07:05.887Z" } ] } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Get the current member" }, "patch": { "description": "update current customer", "operationId": "patchCustomer", "tags": [ "customer" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "title": "Customer", "properties": { "firstName": { "type": "string", "description": "customer's first name" }, "lastName": { "type": "string", "description": "customer's last name" }, "email": { "type": "string", "description": "customer's email" }, "phoneNumber": { "type": "string", "description": "phone number, without any prefix" }, "countryCode": { "type": "integer", "description": "phone country code (i.e. 33 for France)" }, "password": { "type": "string", "description": "customer's password" }, "outsideOptIn": { "type": "boolean", "description": "true if customer accepts its out of mall transactions to be analyzed, false otherwhise" }, "preferredLanguage": { "type": "string", "description": "customer preferred language for communication (email, sms...) - ISO 639-1 format is expected (i.e. fr-FR or en)" }, "postalCode": { "type": "string", "description": "The postal code of the customer" }, "familyStatus": { "type": "string", "description": "Family situation of the customer\n* `singleWithoutChildren` - single customer without children\n* `singleWithChildren` - single customer with children\n* `marriedWithoutChildren` - married customer without children\n* `marriedWithChildren` - married customer without children\n", "enum": [ "singleWithoutChildren", "singleWithChildren", "marriedWithoutChildren", "marriedWithChildren" ] } } } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "title": "CustomerInfo", "properties": { "customerId": { "type": "string", "description": "customer's id" }, "hubExternalId": { "type": "string", "description": "programme external id'" }, "hubName": { "type": "string", "description": "programme's name" }, "firstName": { "type": "string", "description": "customer's first name" }, "lastName": { "type": "string", "description": "customer's last name" }, "scanEnable": { "type": "boolean", "description": "true if scan is enable for customer, false otherwise" }, "email": { "type": "string", "description": "customer's email" }, "bankAlreadyConnected": { "type": "boolean", "description": "information about customer's bank connection" }, "registered": { "type": "boolean", "description": "true if customer is registered, false otherwise" }, "phoneVerified": { "type": "boolean", "description": "information about customer's phone verfication" }, "phoneNumber": { "type": "string", "description": "phone number, without any prefix" }, "countryCode": { "type": "integer", "description": "phone country code (i.e. 33 for France)" }, "createdAt": { "type": "string", "description": "date-time of the customer's creation", "format": "date-time" }, "referralCode": { "type": "string", "description": "the referral code of a customer" } }, "required": [ "bankAlreadyConnected", "customerId", "scanEnable", "registered", "createdAt" ], "example": { "application/json": [ { "customerId": "c5562d40-be8b-43cf-88ca-96933e76629f", "firstName": "John", "bankAlreadyConnected": true, "email": "foo@bar.com", "phoneVerified": true, "registered": true, "createdAt": "2018-10-19T16:07:05.887Z" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of PATCH /customer\n* `nothingToPatch` - No customer attributes to patch was provided\n* `invalidPassword` - Password format is invalid\n* `invalidBirthDate` - Birth date format is invalid\n* `invalidLanguage` - invalid preferred language\n* `invalidEmail` - Email is invalid\n* `emailAlreadyUsed` - Email already linked to an account\n* `numberAlreadyUsed` - Phone number already linked to an account\n", "enum": [ "nothingToPatch", "invalidPassword", "invalidBirthDate", "invalidEmail", "invalidLanguage", "emailAlreadyUsed", "numberAlreadyUsed" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Update the current member" }, "delete": { "description": "Delete current customer in the Spaycial repository (deduced from header token)", "operationId": "deleteCustomer", "tags": [ "customer" ], "responses": { "204": { "description": "Success" }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Delete the current member" } }, "/customer/password": { "x-swagger-router-controller": "customer_api", "patch": { "description": "update current customer password", "operationId": "changeCustomerPassword", "tags": [ "customer" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "currentPassword", "password" ], "properties": { "currentPassword": { "type": "string" }, "password": { "type": "string" } } } } }, "description": "The user data." }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad request" } }, "summary": "Change the member's password" } }, "/customer/clo/connections": { "x-swagger-router-controller": "customer_connection_api", "get": { "description": "Returns customer's CLO connections list", "operationId": "getCloConnections", "tags": [ "customer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "title": "CLOConnectionInfo", "properties": { "customerId": { "type": "string", "description": "customer id in the Spaycial repository" }, "connections": { "type": "array", "title": "Array", "items": { "type": "object", "description": "object containing credit card details", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "scheme": { "type": "string" }, "programId": { "type": "string" }, "metadata": { "type": "object" }, "live": { "type": "boolean" }, "lastNumbers": { "type": "string" }, "firstNumbers": { "type": "string" }, "expMonth": { "type": "number" }, "expYear": { "type": "number" }, "expDate": { "type": "string" }, "countryCode": { "type": "string" }, "accountId": { "type": "string" } }, "required": [ "id", "lastNumbers", "expDate", "scheme", "metadata" ], "example": { "created": "2019-10-08T12:30:44.487Z", "updated": "2019-10-08T12:30:44.487Z", "id": "a83b4b96-568a-49f9-8019-d6fdff41c4c8", "type": "visa", "scheme": "visa", "programId": "4c65afca-047b-4c3e-b079-761545a40e1d", "metadata": { "id": "032ad8f4-098a-4187-aed9-5b1c05424df6" }, "live": false, "lastNumbers": "4322", "firstNumbers": "444400", "expYear": 2020, "expMonth": 2, "expDate": "2020-02-29T23:59:59.999Z", "countryCode": "CAN", "accountId": "8e8aed10-19ae-4faf-8cd2-147b1d9d1b94" } } } }, "required": [ "customerId", "connections" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List the member's card-linked connections" } }, "/customer/creditCard/connections": { "x-swagger-router-controller": "customer_connection_api", "post": { "description": "add a credit card connection providing checkout credit card token", "operationId": "addCreditCardConnection", "tags": [ "customer" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "creditCardToken": { "type": "string", "description": "credit card token (issued by Checkout tokenization)" } }, "required": [ "creditCardToken" ] } } }, "description": "body containing connection info", "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "creditCardId": { "type": "string", "description": "the identifier of the credit card created" } }, "required": [ "creditCardId" ], "example": { "application/json": [ { "creditCardId": "c0b88330-ec05-49c3-99eb-e67b1a1e3fc9" } ] } } } } }, "202": { "description": "3DS challenge redirect URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectUrl": { "type": "string", "description": "Redirect url to the customer's bank" } }, "required": [ "redirectUrl" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of bank connection\n* `notFullyRegistered` - Customer not fully registered\n* `creditCardRequired` - Credit Card is required\n* `cardAlreadyLinked` - Credit Card is already linked to the program\n* `errorLinkingCard` - Error while linking card to the program\n* `invalidTokenFormat` - Error while linking card to the program\n", "enum": [ "notFullyRegistered", "creditCardRequired", "cardAlreadyLinked", "errorLinkingCard", "invalidTokenFormat" ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Add a credit card connection" } }, "/customer/connections/{connectionId}": { "x-swagger-router-controller": "customer_connection_api", "delete": { "description": "delete a connection of any type", "operationId": "deleteConnection", "tags": [ "customer" ], "parameters": [ { "name": "connectionId", "in": "path", "description": "the connection id (either a bank connection id or a credit card id)", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of bank connection delete\n* `invalidConnectionId` - Invalid connection id\n* `bankConnectionNotFound` - Bank connection not found\n* `customerNotFound` - Customer not found\n* `customerIdMismatch` - Customer id doesn't match\n", "enum": [ "invalidConnectionId", "bankConnectionNotFound", "customerNotFound", "customerIdMismatch" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Delete a connection" } }, "/customer/all/connections": { "x-swagger-router-controller": "customer_connection_api", "get": { "description": "Returns customer's bank", "operationId": "getAllCustomerConnections", "tags": [ "customer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "title": "ConnectionInfo", "properties": { "customerId": { "type": "string", "description": "customer id in the Spaycial repository" }, "connections": { "type": "array", "title": "Array", "items": { "type": "object", "title": "Connection", "properties": { "id": { "type": "string", "description": "the connection id" }, "creationDate": { "type": "string", "format": "date", "description": "creation of the connection, in date-time format of RFC3339" }, "type": { "type": "string", "description": "type of data provider connection", "enum": [ "CLO", "PSD2", "SCR" ] }, "bankId": { "type": "string", "description": "bank identifier (as found in GET /banks) (provided only for connections of type PSD2 and SCR)" }, "bankName": { "type": "string", "description": "bank name (provided only for connections of type PSD2 and SCR)" }, "cardType": { "type": "string", "description": "type of card associated to this bank (bank vs restaurant )", "enum": [ "bank", "restaurant" ] }, "lastUpdate": { "type": "string", "description": "the last time data has been successfuly fetch from the bank by the data provider, in date-time format of RFC3339 (provided only for connections of type PSD2 and SCR)", "format": "date" }, "passwordError": { "type": "boolean", "description": "true if bank password needs to be updated, false otherwise (provided only for connections of type PSD2 and SCR)" }, "scheme": { "type": "string", "description": "credit card's scheme (provided only for connections of type CLO)" }, "lastNumbers": { "type": "string", "description": "credit card's last four numbers (provided only for connections of type CLO)" }, "expDate": { "type": "string", "description": "credit card's expire date (provided only for connections of type CLO)", "format": "date" }, "countryCode": { "type": "string", "description": "credit card's country code ex:\"SE\" (provided only for connections of type CLO)" }, "bankActive": { "type": "boolean", "description": "false if a bank corresponding to the connection is deactivated (thus resync is not possible at the moment)" } }, "required": [ "id", "creationDate", "type", "cardType" ] } } }, "required": [ "customerId", "connections" ] }, "examples": { "response": { "value": [ { "customerId": "ffc09cbd-e5b3-497a-a9d7-9d510810efcb", "connections": [ { "id": "9d635cb0-07ec-4e90-88f7-2562d5624d05", "expDate": "2024-03-31", "scheme": "visa", "countryCode": "SE", "lastNumbers": "5453", "type": "CLO" }, { "id": "cecb2084-d005-4e04-9689-65af01affc47", "creationDate": "2020-03-27T18:15:52+01:00", "passwordError": false, "lastUpdate": "2020-03-27", "bankId": "connecteur_de_test_fr_b", "bankName": "Connecteur de test", "cardType": "bank", "type": "SCR" } ] } ] } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List all the member's connections" } }, "/customer/bank/connections": { "x-swagger-router-controller": "customer_connection_api", "get": { "description": "Returns customer's bank connections list", "operationId": "getBankConnections", "tags": [ "customer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "title": "ConnectionInfo", "properties": { "customerId": { "type": "string", "description": "customer id in the Spaycial repository" }, "connections": { "type": "array", "title": "Array", "items": { "type": "object", "title": "BankConnection", "properties": { "id": { "type": "string", "description": "bank connection id" }, "bankId": { "type": "string", "description": "bank identifier (as found in GET /banks)" }, "bankName": { "type": "string", "description": "bank name" }, "cardType": { "type": "string", "description": "type of card associated to this bank (bank vs restaurant )", "enum": [ "bank", "restaurant" ] }, "creationDate": { "type": "string", "description": "bank connection creation date, in full-date format of RFC3339", "format": "date" }, "lastUpdate": { "type": "string", "description": "the last time data has been successfuly fetch from the bank by the data provider, in date-time format of RFC3339", "format": "date" }, "passwordError": { "type": "boolean", "description": "true if bank password needs to be updated, false otherwise" }, "type": { "type": "string", "description": "type of connection", "enum": [ "SCR", "PSD2" ] } }, "required": [ "id", "bankId", "bankName", "creationDate", "passwordError" ] } } }, "required": [ "customerId", "connections" ], "example": { "application/json": [ { "customerId": "27b36da1-39f2-5ab5-8784-52a78779af58", "connections": [ { "id": "b6255bf6-b293-424d-9363-d94700aca720", "bankId": "0ef0f298-47ab-41f6-ae89-f1f6dab94104", "bankName": "Some Bank", "creationDate": "2018-01-17" }, { "id": "e13c5c09-f71f-4139-869a-3b228109594a", "bankId": "63cbd7cc-d65e-4e36-817a-ef3774f2a5ce", "bankName": "Another Bank", "creationDate": "2018-01-22" } ] } ] } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List the member's bank connections" } }, "/customer/bank/connectionCallback": { "x-swagger-router-controller": "customer_connection_api", "post": { "description": "add a bank connection to customer by providing bank website callback code", "operationId": "addBankConnectionCallback", "tags": [ "customer" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "bankId": { "description": "identifier of the bank to connect with (found in GET /banks)", "nullable": true, "type": "string" }, "queryString": { "type": "object", "description": "object containing the temp code retrieved from psd2 callback login and the customer_id" }, "redirectUri": { "type": "string", "description": "the URI where to redirect to" } }, "required": [ "queryString" ] } } }, "description": "body containing connection info", "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "bankConnectionId": { "type": "string", "description": "the identifier of the bank connection created" } }, "required": [ "bankConnectionId" ], "example": { "application/json": [ { "bankConnectionId": "c0b88330-ec05-49c3-99eb-e67b1a1e3fc9" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of bank connection\n* `bankNotFound` - Bank not found\n* `bankNotAvailable` - Bank exists but is not available for connection\n* `notFullyRegistered` - Customer not fully registered\n* `credentialsRequired` - Credentials are required\n* `invalidCredentials` - Provided credentials are invalid\n* `actionNeeded` - An action is needed on the bank website\n* `alreadyUsedCredentials` - Credentials already used\n* `providerError` - Failed to create connection with the bank\n* `connectionAlreadyExists` - The customer already have a connection with this bank\n* `ConnectionNotFoundInSe` - Connection Not Found In Salt Edge\n", "enum": [ "bankNotFound", "bankNotAvailable", "notFullyRegistered", "credentialsRequired", "invalidCredentials", "actionNeeded", "alreadyUsedCredentials", "creditCardAlreadyConnected", "providerError", "connectionAlreadyExists", "ConnectionNotFoundInSe" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Add a bank connection from a bank callback" } }, "/auth/bank/verifyDecoupledConnection": { "x-swagger-router-controller": "auth_api", "post": { "description": "verify the status of a decoupledConnection and retrieve the oauthcallback uri", "operationId": "verifyDecoupledConnection", "tags": [ "auth" ], "security": [ { "apiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "decoupledDetails": { "type": "object", "description": "object containing the decoupledDetails sent from the server to be used for the polling (the specified properties differ depending on the data provider)", "properties": { "dataProviderId": { "type": "string" }, "dataProviderShortcut": { "type": "string" }, "connectionExternalId": { "type": "string" } } } }, "required": [ "decoupledDetails" ] } } }, "description": "body containing decouple connection info", "required": true }, "responses": { "200": { "description": "an object containing the oauthcallback and success status", "content": { "application/json": { "schema": { "type": "object", "properties": { "callbackUrl": { "type": "string", "description": "the identifier of the bank connection created" }, "status": { "type": "string", "description": "status of the actual connection ( pending / completed / failed )" } }, "example": { "application/json": [ { "callbackUrl": "/oauthcallback?code=xxxx&customer_id=xxxxxx", "status": "completed" } ] } } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "AccountNotFound error\n* `accountNotFound` - The data sent is not valid\n", "enum": [ "accountNotFound" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Validation error\n* `validationError` - The data sent is not valid\n", "enum": [ "validationError" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Verify a decoupled bank connection" } }, "/customer/bank/connections/{connectionId}": { "x-swagger-router-controller": "customer_connection_api", "put": { "description": "update a bank connection by providing bank website credentials", "operationId": "updateBankConnection", "tags": [ "customer" ], "parameters": [ { "name": "connectionId", "in": "path", "description": "the connection id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "credentials": { "type": "object", "description": "object containing bank credentials" }, "redirectUri": { "type": "string", "description": "the URI where to redirect to" }, "locale": { "type": "string", "description": "for some banks, a locale can be provided to define the bank portal language" }, "psuId": { "type": "string", "description": "psuId which is the identification number of the user" }, "chosenAuthModel": { "type": "string", "description": "the chosen authentication model which is redirect or decoupled" } } } } }, "description": "body containing connection info", "required": true }, "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of bank connection update\n* `invalidConnectionId` - Invalid connection id\n* `credentialsRequired` - Credentials are required\n* `bankConnectionNotFound` - Bank connection not found\n* `customerNotFound` - Customer not found\n* `invalidCredentials` - Provided credentials are invalid\n* `actionNeeded` - An action is needed on the bank website\n* `ConnectionNotFoundInSe` - Connection Not Found In Salt Edge\n* `bankAlreadyConnected` - Customer has already connected this bank\n* `CustomerIdIsNotAUuid` - Customer is not a valid uuid\n* `bankConnectionAlreadySynchronized` - Bank connection is not in error state, no need to resync because it could spoil active FT connection\n* `providerError` - Failed to create connection with the bank\n", "enum": [ "invalidConnectionId", "CustomerIdIsNotAUuid", "credentialsRequired", "bankConnectionNotFound", "customerNotFound", "invalidCredentials", "actionNeeded", "bankAlreadyConnected", "ConnectionNotFoundInSe", "bankConnectionAlreadySynchronized", "providerError" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Update a bank connection's credentials" }, "delete": { "description": "delete a bank connection", "operationId": "deleteBankConnection", "tags": [ "customer" ], "parameters": [ { "name": "connectionId", "in": "path", "description": "the connection id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of bank connection delete\n* `invalidConnectionId` - Invalid connection id\n* `bankConnectionNotFound` - Bank connection not found\n* `customerNotFound` - Customer not found\n", "enum": [ "invalidConnectionId", "bankConnectionNotFound", "customerNotFound" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Delete a bank connection" } }, "/customer/bank/connectionCallback/{connectionId}": { "x-swagger-router-controller": "customer_connection_api", "put": { "description": "update bank connection callback", "operationId": "updateBankConnectionCallback", "tags": [ "customer" ], "parameters": [ { "name": "connectionId", "in": "path", "description": "the connection id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "queryString": { "type": "object", "description": "object containing the query string from interactive callback" } } } } }, "description": "body containing connection info", "required": true }, "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of bank connection update\n* `invalidConnectionId` - Invalid connection id\n* `credentialsRequired` - Credentials are required\n* `bankConnectionNotFound` - Bank connection not found\n* `customerNotFound` - Customer not found\n* `invalidCredentials` - Provided credentials are invalid\n* `actionNeeded` - An action is needed on the bank website\n* `ConnectionNotFoundInSe` - Connection Not Found In Salt Edge\n* `bankAlreadyConnected` - Customer has already connected this bank\n* `CustomerIdIsNotAUuid` - Customer is not a valid uuid\n* `bankConnectionAlreadySynchronized` - Bank connection is not in error state, no need to resync because it could spoil active FT connection\n* `providerError` - Failed to create connection with the bank\n", "enum": [ "invalidConnectionId", "CustomerIdIsNotAUuid", "credentialsRequired", "bankConnectionNotFound", "customerNotFound", "invalidCredentials", "actionNeeded", "bankAlreadyConnected", "ConnectionNotFoundInSe", "bankConnectionAlreadySynchronized", "providerError" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Update a bank connection from a bank callback" } }, "/customer/track": { "x-swagger-router-controller": "customer_api", "get": { "description": "Track an action made by a Customer", "operationId": "trackCustomer", "tags": [ "customer" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "customerId", "in": "query", "description": "the customer identifier", "required": true, "schema": { "type": "string" } }, { "name": "eventName", "in": "query", "description": "the event name", "required": true, "schema": { "type": "string" } }, { "name": "value", "in": "query", "description": "the event value", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of bank connection delete\n* `eventNameNotFound` - Event name was not found\n* `customerNotFound` - Customer not found\n* `invalidCustomerId` - Customer id is not valid\n", "enum": [ "customerNotFound", "eventNameNotFound", "invalidCustomerId" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Track a member action" } }, "/customer/exists/{externalId}": { "x-swagger-router-controller": "customer_api", "get": { "description": "Test if a given external identifier match a customer in the Spaycial repository", "operationId": "existsCustomer", "tags": [ "customer" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "externalId", "in": "path", "description": "the customer identifier in mall repository", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Check that a member exists" } }, "/customer/isRegistered/{customerId}": { "x-swagger-router-controller": "customer_api", "get": { "description": "Test if a given Spaycial identifier matches a registered customer in the Spaycial repository", "operationId": "isRegistered", "tags": [ "customer" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "customerId", "in": "path", "description": "the customer identifier in the Spaycial repository", "required": true, "schema": { "type": "string" } }, { "name": "eventType", "in": "query", "required": true, "description": "the event at the origin a call to this endpoint\n* `exclusive_event` - Check member registration to access to an exclusive event\n* `purchase_discount` - Check member registration to apply a purchase discount\n* `store_opening` - Check member registration to access to a new store opening\n* `toilets_access` - Check member registration to access to the toilets\n", "schema": { "type": "string", "enum": [ "exclusive_event", "purchase_discount", "store_opening", "toilets_access" ] } } ], "responses": { "204": { "description": "Success" }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Check that a member is registered" } }, "/customer/referralExists": { "x-swagger-router-controller": "customer_api", "post": { "description": "Test if the given customer info matches a referral customer in the Spaycial database", "operationId": "referralExists", "tags": [ "customer" ], "security": [ { "apiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "referralCode": { "type": "string", "description": "the customer referral code" }, "phoneNumber": { "type": "string", "description": "phone number, without any prefix" }, "countryCode": { "type": "integer", "description": "phone country code (i.e. 33 for France)" } } } } }, "description": "the body containing referral information", "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "title": "ReferralInfo", "properties": { "referralExists": { "type": "boolean", "description": "true if referral exists, false otherwhise" }, "referralFirstName": { "type": "string", "description": "the first name of referral if exists" }, "referralNbMonth": { "type": "integer", "description": "the referral's number of month since registration (if exists)" } }, "required": [ "referralExists" ], "example": { "application/json": [ { "referralExists": true } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of POST /customer/referralExists\n* `noParameter` - Need to provide either referralCode or phoneNumber + countryCode params\n", "enum": [ "noParameter" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Check a referral" } }, "/customer/favoriteAccount": { "x-swagger-router-controller": "customer_api", "post": { "description": "set customer's favorite account used for refunds", "operationId": "postFavoriteAccount", "tags": [ "customer" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "title": "FavoriteAccount", "properties": { "iban": { "type": "string", "description": "customer favorite bank account to receive refunds (in IBAN format)" }, "sortCode": { "type": "string", "description": "bank account sort code (specific to the UK bank accounts, instead of the IBAN)" }, "accountNumber": { "type": "string", "description": "bank account number (specific to the UK bank accounts, instead of the IBAN)" } } } } }, "required": true }, "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of POST /customer/favoriteAccount\n* `invalidIban` - Invalid iban provided\n* `alreadyUsedIban` - Provided IBAN is already used on another account\n", "enum": [ "invalidIban" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Set the member's favourite account" }, "get": { "description": "set customer's favorite account used for refunds", "operationId": "getCustomerFavoriteAccount", "tags": [ "customer" ], "responses": { "200": { "description": "return object with the cashback methods of the customer.", "content": { "application/json": { "schema": { "type": "object", "title": "IbanNumbers", "properties": { "IBAN": { "type": "object", "description": "IBAN with the first and the last numbers of the customer's IBAN", "properties": { "firstNumbers": { "type": "number", "description": "first numbers of the customer's iban" }, "lastNumbers": { "type": "number", "description": "last numbers of the customer's iban" } } }, "creditCard": { "type": "object", "description": "Credit Card with the last numbers of the customer's credit card", "properties": { "lastNumbers": { "type": "number", "description": "last number of the customer's credit card" } } }, "cashbackFallbackNeeded": { "type": "boolean", "description": "Information about the possibility to cashback the customer with the credit card given" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of GET /customer/favoriteAccount\n* `invalidIban` - Invalid iban provided\n", "enum": [ "noDefaultIban" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Get the member's favourite account" } }, "/customer/wallet": { "x-swagger-router-controller": "customer_api", "get": { "description": "get a link to the loyalty card to the user mobile wallet", "operationId": "getMobileWalletLink", "tags": [ "customer" ], "responses": { "200": { "description": "return object with the cashback methods of the customer.", "content": { "application/json": { "schema": { "type": "object", "title": "Wallet", "properties": { "walletURL": { "type": "string", "description": "An URL to redirect the user for him/her to add the loyalty card to the mobile wallet" } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Get the mobile wallet card link" } }, "/customer/favoriteAccountLink": { "x-swagger-router-controller": "customer_api", "get": { "description": "get an SMS containing a link to allow customer to set its favorite account used for refunds", "operationId": "getFavoriteAccountLink", "tags": [ "customer" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "phoneNumber", "description": "phone number, without any prefix", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "countryCode", "description": "phone country code (i.e. 33 for France)", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of GET /customer/favoriteAccountLink\n* `no_account` - No account found for this customer\n* `already_sent` - SMS has already been sent few minutes ago\n", "enum": [ "no_account", "already_sent" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Send a favourite account link by SMS" } }, "/customer/credentialUpdateLink": { "x-swagger-router-controller": "customer_api", "get": { "description": "get an SMS containing a link to allow customer to update its bank credentials", "operationId": "getCredentialUpdateLink", "tags": [ "customer" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "phoneNumber", "description": "phone number, without any prefix", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "countryCode", "description": "phone country code (i.e. 33 for France)", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of GET /customer/credentialUpdateLink\n* `unknown_phone` - Unknown phone number\n* `no_invalid_credentials` - No credential update needed\n* `already_sent` - SMS has already been sent few minutes ago\n", "enum": [ "unknown_phone", "no_invalid_credentials", "already_sent" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Send a bank credentials update link by SMS" } }, "/customer/rewards": { "x-swagger-router-controller": "customer_api", "get": { "description": "Returns customer rewards", "operationId": "getRewards", "tags": [ "customer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "id of the reward" }, "rewardState": { "type": "string", "description": "Status of the reward\n* `TRAN` - cashback initiated\n* `PEND` - pending\n* `TERM` - complete\n* `RFND` - cashback validated\n* `CNCL` - gift card cancelled\n* `ERR` - provider error, requires investigation\n", "enum": [ "TRAN", "PEND", "TERM", "RFND", "CNCL", "ERR" ] }, "createdAt": { "type": "string", "description": "reward date-time of creation", "format": "date-time" }, "updatedAt": { "type": "string", "description": "last update of the reward", "format": "date-time" }, "rewardValue": { "type": "number", "description": "value of the reward" }, "redeemed": { "type": "boolean", "description": "whether the reward has been redeemed or not (specific to Gift card challenges)" }, "redeemDate": { "type": "string", "format": "date-time", "description": "the date when the reward has been redeemed (specific to Gift card challenges)" }, "cashbackId": { "type": "number", "description": "the cashback id" }, "cashbackStatus": { "type": "number", "description": "the cashback id" }, "giftcardBarcodeUrl": { "type": "string", "description": "SELP barcode URL for the reward when available" }, "giftcardPin": { "type": "string", "description": "gift card pin for the reward when available" }, "challenge": { "type": "object", "description": "the challenge associated to this reward", "properties": { "id": { "type": "string", "description": "id of the challenge" }, "name": { "type": "string", "description": "name of the challenge" }, "teaser": { "type": "string", "description": "teaser of the challenge" }, "startDate": { "type": "string", "description": "the challenge start date", "format": "date-time" }, "endDate": { "type": "string", "description": "the challenge end date", "format": "date-time" }, "conditionLabel": { "type": "string", "description": "the challenge condition label" }, "terms": { "type": "string", "description": "the challenge terms of service" }, "rewardLabel": { "type": "string", "description": "the reward label" } } } }, "required": [ "id", "rewardState", "createdAt", "updatedAt" ] } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error of GET /backoffice/customers/{id}/rewards\n * `invalidCustomerId` - Invalid customer id parameter\n", "enum": [ "invalidCustomerId" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List the member's rewards", "x-spaycial-profiles": [ { "option": "offers", "notRelevantWhen": "client" } ] } }, "/customer/stores": { "x-swagger-router-controller": "stores_api", "get": { "description": "Returns all stores where the user did (or did not, depending on parameter) make a transaction", "operationId": "getStores", "tags": [ "customer" ], "parameters": [ { "name": "transaction", "in": "query", "description": "a boolean set to true if we need stores where user did make a transaction, or false if we need stores where user have not make a transaction yet", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A list of stores.", "content": { "application/json": { "schema": { "type": "array", "title": "Array", "items": { "type": "object", "title": "Store", "properties": { "id": { "type": "string", "description": "store identifier in programme repository" }, "name": { "type": "string", "description": "store name" } }, "required": [ "id", "name" ] } }, "examples": { "response": { "value": [ [ { "id": "{08228F4D-3FA0-4F1D-AC53-1C13B5E24968}", "name": "HISTOIRE D'OR" }, { "id": "{78228F4D-4GA0-9C1D-CD53-3B13B5E24968}", "name": "ZARA" } ] ] } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List stores for the member" } }, "/customer/stores/transactions": { "x-swagger-router-controller": "stores_api", "get": { "description": "Returns all customer transactions related to programme stores", "operationId": "getStoresTransactions", "tags": [ "customer" ], "parameters": [ { "name": "limit", "description": "the maximum number of results to retrieve (default 1000)", "in": "header", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1000, "default": 1000 } }, { "name": "offset", "description": "the results offset (default 0), used to paginate results", "in": "header", "required": false, "schema": { "type": "number", "minimum": 0, "default": 0 } }, { "name": "from", "in": "header", "description": "period start date, in date format of ISO8061", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "header", "description": "period end date, in date format of ISO8061, not possible to add a to without from", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "A list of transactions.", "content": { "application/json": { "schema": { "type": "array", "title": "Array", "items": { "type": "object", "title": "Transaction", "properties": { "date": { "type": "string", "description": "transaction date, in full-date format of RFC3339", "format": "date" }, "storeId": { "type": "string", "description": "the identifier of the store where transaction occurred" }, "amount": { "type": "number", "description": "transaction amount", "format": "float" }, "currency": { "type": "string", "description": "transaction's currency in ISO_4217 format", "minLength": 3, "maxLength": 3 } }, "required": [ "date", "storeId", "amount", "currency" ], "example": { "application/json": [ { "date": "2016-12-07", "storeId": "{08228F4D-3FA0-4F1D-AC53-1C13B5E24968}", "amount": -15, "currency": "EUR" }, { "date": "2016-12-08", "storeId": "{18228F4D-4FA3-4F1D-9C55-DC13B5E24954}", "amount": -40.95, "currency": "EUR" } ] } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List the member's transactions by store" } }, "/customer/points/history": { "x-swagger-router-controller": "points_api", "get": { "description": "Returns all customer points history", "operationId": "getPointsHistory", "tags": [ "customer" ], "parameters": [ { "name": "limit", "description": "the maximum number of results to retrieve (default 1000)", "in": "header", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 1000, "default": 1000 } }, { "name": "offset", "description": "the results offset (default 0), used to paginate results", "in": "header", "required": false, "schema": { "type": "number", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A list of point history elements", "content": { "application/json": { "schema": { "type": "array", "title": "Array", "items": { "type": "object", "title": "PointsHistoryElement", "properties": { "id": { "type": "string" }, "operationDate": { "type": "string", "format": "date-time" }, "value": { "type": "number" }, "type": { "type": "string", "enum": [ "SPEND", "EARNED_FROM_TRANSACTION_IN_MALL" ] } } } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Get the member's points history", "x-spaycial-profiles": [ { "option": "offers", "notRelevantWhen": "client" } ] } }, "/customer/stores/transactions/{storeId}": { "x-swagger-router-controller": "stores_api", "get": { "description": "Returns all transactions that the user did in the given store", "operationId": "getStoreTransactions", "tags": [ "customer" ], "parameters": [ { "name": "storeId", "in": "path", "description": "the store identifier in mall repository", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of transactions.", "content": { "application/json": { "schema": { "type": "array", "title": "Array", "items": { "type": "object", "title": "Transaction", "properties": { "date": { "type": "string", "description": "transaction date, in full-date format of RFC3339", "format": "date" }, "amount": { "type": "number", "description": "transaction amount", "format": "float" }, "currency": { "type": "string", "description": "transaction's currency in ISO_4217 format", "minLength": 3, "maxLength": 3 } }, "required": [ "date", "amount", "currency" ] } }, "examples": { "response": { "value": [ { "date": "2016-12-07", "amount": -15, "currency": "EUR" }, { "date": "2016-12-08", "amount": -40.95, "currency": "EUR" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of GET /stores/transactions/{storeId}\n* `invalidStoreId` - No account found for this customer\n", "enum": [ "invalidStoreId" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List the member's transactions in a store" } }, "/customer/services/transactions": { "x-swagger-router-controller": "services_api", "get": { "description": "Returns all customer transactions related to programme services", "operationId": "getServicesTransactions", "tags": [ "customer" ], "responses": { "200": { "description": "A list of transactions.", "content": { "application/json": { "schema": { "type": "array", "title": "Array", "items": { "type": "object", "title": "Transaction", "properties": { "date": { "type": "string", "description": "transaction date, in full-date format of RFC3339", "format": "date" }, "serviceId": { "type": "string", "description": "the identifier of the service where transaction occurred" }, "amount": { "type": "number", "description": "transaction amount", "format": "float" }, "currency": { "type": "string", "description": "transaction's currency in ISO_4217 format", "minLength": 3, "maxLength": 3 } }, "required": [ "date", "serviceId", "amount", "currency" ] } }, "examples": { "response": { "value": [ { "date": "2016-12-07", "serviceId": "{28228F4D-3FA0-4F1D-AC53-1C13B5E24968}", "amount": -15, "currency": "EUR" }, { "date": "2016-12-08", "serviceId": "{38228F4D-4FA3-4F1D-9C55-DC13B5E24954}", "amount": -40.95, "currency": "EUR" } ] } } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List the member's transactions by service" } }, "/customer/services/transactions/{serviceId}": { "x-swagger-router-controller": "services_api", "get": { "description": "Returns all transactions that the user did for the given service", "operationId": "getServiceTransactions", "tags": [ "customer" ], "parameters": [ { "name": "serviceId", "in": "path", "description": "the service identifier in mall repository", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of transactions.", "content": { "application/json": { "schema": { "type": "array", "title": "Array", "items": { "type": "object", "title": "Transaction", "properties": { "date": { "type": "string", "description": "transaction date, in full-date format of RFC3339", "format": "date" }, "amount": { "type": "number", "description": "transaction amount", "format": "float" }, "currency": { "type": "string", "description": "transaction's currency in ISO_4217 format", "minLength": 3, "maxLength": 3 } }, "required": [ "date", "amount", "currency" ] } }, "examples": { "response": { "value": [ { "date": "2016-12-07", "amount": -15, "currency": "EUR" }, { "date": "2016-12-08", "amount": -40.95, "currency": "EUR" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of GET /services/transactions/{serviceId}\n* `invalidServiceId` - serviceId parameter is invalid\n", "enum": [ "invalidServiceId" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List the member's transactions for a service" } }, "/customer/transactions/complaint": { "x-swagger-router-controller": "customer_api", "get": { "description": "Returns all customer transactions complaints", "operationId": "getCustomerComplaints", "tags": [ "customer" ], "responses": { "200": { "description": "A list of customer complaints.", "content": { "application/json": { "schema": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "id of the customer transaction complaint" }, "transactionDate": { "type": "string", "description": "date of the associated transaction", "format": "date" }, "attachmentUrl": { "type": "string", "description": "url of the complaint attachment" }, "amount": { "type": "number", "description": "the amount of the transaction" }, "claimStatus": { "type": "string", "description": "Status of the claim\n* `validated` - complaint was validated\n* `rejected` - complaint was rejected\n* `pending` - complaint is pending\n", "enum": [ "validated", "rejected", "pending" ] }, "createdAt": { "type": "string", "description": "customer transaction complaint date-time of creation", "format": "date-time" }, "updatedAt": { "type": "string", "description": "last update of the customer transaction complaint", "format": "date-time" }, "store": { "type": "object", "description": "the store associated to this customer transaction complaint", "properties": { "id": { "type": "string", "description": "id of the store" }, "name": { "type": "string", "description": "name of the store" } } }, "rejectionReason": { "type": "string", "description": "Reasons of the claim rejection if the status is rejected\n* `Transaction already associated` - transaction was already associated\n* `Transaction not found` - transaction was not found\n* `The store is out of program` - store is out of the program\n* `Duplicated claim` - complaint is duplicated\n* `Automatically rejected` - automatically rejected\n* `Before registration date` - before registration date\n* `Incomplete ticket` - incomplete ticket\n" }, "rejectionReasonTranslationKey": { "type": "string", "description": "rejection reason translation key in order to translate it with localisation service" } }, "required": [ "id", "transactionDate", "createdAt", "updatedAt", "store" ] } } } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List the member's claims" }, "post": { "description": "allows to send a complaint about a transaction assignment issue", "operationId": "postTransactionAssignmentComplaint", "tags": [ "customer" ], "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "description": "store identifier" }, "externalId": { "type": "string", "description": "customer external id" }, "amount": { "type": "number", "description": "transaction amount", "format": "float" }, "transactionDate": { "type": "string", "description": "transaction date of the transaction assignment request", "format": "date" }, "additionalFeedback": { "type": "string", "description": "additional feeback made by the customer", "maxLength": 255 }, "attachment": { "type": "string", "description": "Attachment file (base64)" } }, "required": [ "storeId", "amount", "transactionDate" ] } } }, "description": "body containing transaction assignement issue info", "required": true }, "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of POST /customer/transactions/complaint\n* `amountRequired` - Need to provide transaction amount parameter\n* `invalidAmount` - Invalid amount parameter\n* `invalidFileType` - Invalid attachment file type\n* `insufficientAmount` - Transaction amount is too low\n* `transactionDateRequired` - Need to provide transaction date parameter\n* `invalidTransactionDate` - Transaction date provided is invalid\n* `storeIdRequired` - Need to provide store id parameter.\n* `invalidStoreId` - Invalid store id parameter\n* `storeNotFound` - Store not found\n* `duplicate` - Same claim already made\n* `transactionDateBeforeRegistration` - Transaction date prior to registration date\n", "enum": [ "storeNotFound", "insufficientAmount", "invalidFileType", "transactionDateBeforeRegistration", "amountRequired", "duplicate", "invalidAmount", "transactionDateRequired", "invalidTransactionDate", "storeIdRequired", "invalidStoreId" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "File a claim for a missing purchase" } }, "/customer/receipts": { "x-swagger-router-controller": "customer_receipt_api", "get": { "description": "get receipts updated by a customer", "operationId": "getCustomerReceipts", "tags": [ "customer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "title": "Receipt", "properties": { "id": { "type": "string", "description": "receipt id" }, "transactionId": { "type": "string", "description": "transaction Id" }, "transactionDateTime": { "type": "string", "description": "transaction Date time" }, "status": { "type": "string", "description": "Status of the receipt\n* `validated` - valid receipt\n* `rejected` - invalid receipt\n* `pending` - pending receipt\n", "enum": [ "pending", "rejected", "validated" ] }, "receiptImageUrl": { "type": "string", "description": "receipt uploaded image url" }, "rejectionReason": { "type": "string", "description": "Status of the receipt\n* `outOfMall` - out of mall ticket\n* `notATicket` - invalid picture\n* `incomplete` - one of the informations (date, time, amount, store) is missing\n* `notADebit` - not a debit transaction\n* `storeNotFound` - store not present in the list\n* `before_registration` - ticket date is grater than registration date\n* `incomplete-store` - the store is missing\n", "enum": [ "outOfMall", "notATicket", "incomplete", "notADebit", "storeNotFound", "before_registration", "incomplete-store", "notInClientReferential" ] }, "createdAt": { "type": "string", "description": "date-time of creation of the receipt", "format": "date-time" }, "transaction": { "type": "object", "description": "the associated transaction object", "properties": { "id": { "type": "string", "description": "the transaction id" }, "transactionDate": { "type": "string", "description": "the transaction date" }, "amount": { "type": "string", "description": "the transction amount" }, "currency": { "type": "string", "description": "the transaction currency" }, "createdAt": { "type": "string", "description": "the transaction creation date-time", "format": "date-time" }, "store": { "type": "object", "description": "the store object associated to the transaction", "properties": { "id": { "type": "string", "description": "the store id" }, "name": { "type": "string", "description": "the name of the store" } } } } } }, "required": [ "id", "status", "createdAt" ] }, "example": { "application/json": [ [ { "id": "2a804a3a-8da2-4ff1-8077-da588ba53a7d", "status": "validated", "receiptImageUrl": "https://cdn.transactionconnect.com/claims/staging/88035a54-e6bb-48ae-b526-d6cba060490a", "rejectionReason": null, "createdAt": "2020-02-02T16:09:44.034Z", "transaction": { "id": "f89c9349-283e-4664-9214-cf8cb702e150", "transactionDate": "2020-02-01", "amount": "-56.00", "currency": "EUR", "createdAt": "2020-02-02T16:10:32.743Z", "store": { "id": "67322cca-03ad-4542-92b9-2dd20d73fb9f", "name": "BASIC FIT" } } }, { "id": "7adb2988-6b6e-4f84-8272-2b293af577a8", "status": "validated", "receiptImageUrl": "https://cdn.transactionconnect.com/claims/staging/88035a54-e6bb-48ae-b526-d6cba060490a", "rejectionReason": null, "createdAt": "2020-02-02T17:44:07.552Z", "transaction": { "id": "f1eb4c08-0075-4503-befc-3d74d78319a8", "transactionDate": "2020-02-01", "amount": "-56.00", "currency": "EUR", "createdAt": "2020-02-02T17:44:40.882Z", "store": { "id": "c35cd149-2f80-4f5c-b932-08044c1641c6", "name": "GIFI" } } } ] ] } } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List the member's receipts", "x-spaycial-profiles": [ { "option": "scan", "notRelevantWhen": "disabled" } ] }, "post": { "description": "Allows customer to add a receipt", "operationId": "postReceipt", "tags": [ "customer" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "description": "Image of the receipt to upload", "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "isProperReceiptExtract": { "type": "boolean", "description": "true if extracted data contains all essential information we need, false otherwhise" } }, "example": { "application/json": [ { "isProperReceiptExtract": true } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes for POST /customer/receipts and POST /auth/receipt\n* `invalidCustomer` - Invalid customer identifier\n* `invalidOptins` - optins parameter is invalid\n* `invalidFileType` - Invalid file type\n* `tooLargeFile` - The provided file is too large\n", "enum": [ "invalidCustomer", "invalidOptins", "invalidFileType", "tooLargeFile" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "alreadyExists" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Upload a receipt", "x-spaycial-profiles": [ { "option": "scan", "notRelevantWhen": "disabled" } ] }, "patch": { "description": "Allows customer to update a receipt", "operationId": "updateReceipt", "tags": [ "customer" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": "string", "description": "id of the store" }, "receiptId": { "type": "string", "description": "id of the receipt" } }, "required": [ "storeId", "receiptId" ] } } }, "description": "body containing receipt id and store id", "required": true }, "responses": { "204": { "description": "Receipt successfully updated" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of bank connection update\n* `invalidStoreId` - provided store id is invalid\n", "enum": [ "invalidStoreId" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Update a receipt", "x-spaycial-profiles": [ { "option": "scan", "notRelevantWhen": "disabled" } ] } }, "/customer/optins": { "x-swagger-router-controller": "customer_api", "get": { "description": "get optins list validated by the customer", "operationId": "getCustomerOptins", "tags": [ "customer" ], "parameters": [ { "name": "lng", "description": "country code (2 letters) used to filter bank list by country", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "title": "Optin", "properties": { "code": { "type": "string", "description": "optin code" }, "label": { "type": "string", "description": "optin label" }, "required": { "type": "boolean", "description": "true if optin is required, false otherwise" }, "value": { "type": "boolean", "description": "true for opt-in, false for opt-out" }, "registrationType": { "type": "string", "description": "optin type" } }, "required": [ "code", "label", "required", "value", "registrationType" ] }, "example": { "application/json": [ [ { "code": "optin1", "label": "This optin is opted in", "value": true, "registrationType": "SCR" }, { "code": "optin2", "label": "This optin is opted out", "value": false, "registrationType": "CLO" } ] ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes for GET /customer/optins\n* `invalidLanguage` - invalid language code\n", "enum": [ "invalidLanguage" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List the member's opt-ins" }, "put": { "description": "update optins value for current customer", "operationId": "updateOptins", "tags": [ "customer" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "registrationType": { "type": "string", "default": "SCR", "description": "type of optin's registration (default 'SCR': web scrapping)" }, "optins": { "type": "array", "items": { "type": "object", "title": "Optin", "properties": { "code": { "type": "string", "description": "optin code" }, "label": { "type": "string", "description": "optin code" }, "value": { "type": "boolean", "description": "true for opt-in, false for opt-out" } }, "required": [ "code", "value" ] }, "example": { "application/json": [ [ { "code": "optin1", "value": true }, { "code": "optin2", "value": false } ] ] } } }, "required": [ "optins" ] } } }, "description": "body containing new optin values", "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "title": "Optin", "properties": { "code": { "type": "string", "description": "optin code" }, "value": { "type": "boolean", "description": "true for opt-in, false for opt-out" } }, "required": [ "code", "value" ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of bank connection update\n* `invalidOptins` - provided optins are invalid\n", "enum": [ "invalidOptins" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Update the member's opt-ins" } }, "/challenges": { "x-swagger-router-controller": "challenge_api", "get": { "summary": "List offers", "operationId": "getChallenges", "tags": [ "challenges" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "current", "in": "query", "required": false, "description": "If true, only return challenges that are active, if missing, all challenges will be returned.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Challenge list", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "challenge identifier" }, "startDate": { "type": "string", "description": "challenge start date-time, in full-date format of RFC3339", "format": "date-time" }, "endDate": { "type": "string", "description": "challenge end date-time, in full-date format of RFC3339", "format": "date-time" }, "name": { "type": "string", "description": "name of the challenge" }, "teaser": { "type": "string", "description": "teaser of the challenge" }, "rewardType": { "type": "string", "description": "challenge's type" }, "rewardLabel": { "type": "string", "description": "reward label of the challenge" }, "rewardValue": { "type": "string", "description": "reward value of the challenge" }, "conditionLabel": { "type": "string", "description": "condition to unlock the reward" }, "legalConditionText": { "type": "string", "description": "displayable condition text" }, "active": { "type": "boolean", "description": "challenge still active or not" }, "createdAt": { "type": "string", "description": "challenge creation date-time, in date-time format of RFC3339", "format": "date-time" } }, "required": [ "id", "startDate", "endDate", "teaser", "rewardType", "rewardLabel", "rewardValue", "conditionLabel", "createdAt" ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of challenges API's\n* `invalidShoppingHubId` - Programme identifier is invalid\n", "enum": [ "invalidShoppingHubId" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "x-spaycial-profiles": [ { "option": "offers", "notRelevantWhen": "client" } ] } }, "/challenge/{id}": { "x-swagger-router-controller": "challenge_api", "get": { "summary": "Get an offer", "operationId": "getChallenge", "tags": [ "challenges" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "description": "id of the challenge", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Challenge object", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "challenge identifier" }, "startDate": { "type": "string", "description": "challenge start date-time, in full-date format of RFC3339", "format": "date-time" }, "endDate": { "type": "string", "description": "challenge end date-time, in full-date format of RFC3339", "format": "date-time" }, "name": { "type": "string", "description": "name of the challenge" }, "teaser": { "type": "string", "description": "teaser of the challenge" }, "rewardType": { "type": "string", "description": "challenge's type" }, "rewardLabel": { "type": "string", "description": "reward label of the challenge" }, "rewardValue": { "type": "string", "description": "reward value of the challenge" }, "conditionLabel": { "type": "string", "description": "condition to unlock the reward" }, "legalConditionText": { "type": "string", "description": "displayable condition text" }, "active": { "type": "boolean", "description": "challenge still active or not" }, "createdAt": { "type": "string", "description": "challenge creation date-time, in date-time format of RFC3339", "format": "date-time" } }, "required": [ "id", "startDate", "endDate", "teaser", "rewardType", "rewardLabel", "rewardValue", "conditionLabel", "createdAt" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of challenges API's\n* `invalidChallengeId` - Invalid challenge id parameter\n", "enum": [ "invalidChallengeId" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "x-spaycial-profiles": [ { "option": "offers", "notRelevantWhen": "client" } ] } }, "/admin/customers": { "x-swagger-router-controller": "admin_api", "get": { "description": "Return a list of customers that have registered in a given period", "operationId": "getCustomers", "tags": [ "admin" ], "security": [ { "signature": [], "apiKey": [] } ], "parameters": [ { "name": "startDate", "in": "header", "description": "period start date, in full-date format of RFC3339", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "header", "description": "period end date, in full-date format of RFC3339", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "limit", "description": "the maximum number of results to retrieve (default 1000)", "in": "header", "required": false, "schema": { "type": "number" } }, { "name": "offset", "description": "the results offset (default 0), used to paginate results", "in": "header", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "customerId": { "type": "string", "description": "identifier of the customer" }, "externalId": { "type": "string", "description": "external identifier of the customer" }, "registrationDate": { "type": "string", "description": "customer's registration date", "format": "date" }, "registrationType": { "type": "string", "description": "type of the registration", "enum": [ "receipt", "bank" ] } } }, "example": { "application/json": [ [ { "customerId": "0e67d4d5-e11d-4766-966c-d3d15b2acfb6", "customerExternalId": "56591974", "registrationDate": "2019-04-30T06:09:35.309Z", "registrationType": "BANK" } ] ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of GET /admin/customers\n* `invalidPeriod` - Invalid startDate or endDate\n", "enum": [ "invalidPeriod" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List members registered in a period" } }, "/admin/customer": { "x-swagger-router-controller": "admin_api", "delete": { "description": "Delete a customer in the Spaycial repository (based on customerId)", "operationId": "deleteCustomerAdmin", "tags": [ "admin" ], "security": [ { "signature": [], "apiKey": [] } ], "parameters": [ { "name": "customerId", "in": "header", "required": true, "description": "identifier of the customer to delete", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Delete a member" } }, "/admin/customer/bank/connections/{connectionId}": { "x-swagger-router-controller": "admin_api", "patch": { "description": "update a bank connection", "operationId": "patchBankConnection", "tags": [ "customer" ], "security": [ { "signature": [], "apiKey": [] } ], "parameters": [ { "name": "connectionId", "in": "path", "description": "the connection id to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "simulateInvalidCredentials": { "type": "boolean", "description": "true to simulate an invalidCredentials error on this bank connection, false to do nothing" } } } } }, "description": "body containing connection info", "required": true }, "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of bank connection update\n* `invalidConnectionId` - Invalid bank connection id\n", "enum": [ "invalidConnectionId" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "401": { "description": "Unauthorized access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `expiredToken` - The Authorization header has expired\n* `unauthorized` - The route access is unauthorized\n", "enum": [ "expiredToken", "unauthorized" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "resourceNotFound" ] }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Update a member's bank connection" } }, "/admin/customerRecommendations": { "x-swagger-router-controller": "admin_api", "post": { "description": "Retrieve recommendation for customers - 3 retailers ID for each customers based on previous customers transactions. It's a list of retailers where user haven't spent anything yet but it's likely he will. If there are no personal recommendations for a customer (no transactions made by the customer yet) 3 general recommendations would be provided", "operationId": "getCustomerRecommendations", "tags": [ "admin" ], "security": [ { "signature": [], "apiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "description": "a list of customers external ids", "type": "array", "items": { "type": "string" } }, "dataRetrievalMethod": { "description": "filter users based on the way we collect their data.\nCodes:\n* `paymentCard` - filter users who joined the program by linking their payment card\n* `scan` - filter users who manually scan of their purchase receipt as part of the program\n", "type": "string", "enum": [ "paymentCard", "scan" ] }, "status": { "description": "whether users bank connections are synchronized or desynchronized. If a user has multiple bank connections, he will be counted as desynchronised if one of his bank connections is desynchronised", "type": "string", "enum": [ "synchronized", "desynchronized" ] }, "registered": { "description": "true for users who has finished registration in the system, false for those who are not yet finished the registration process.", "type": "boolean" } } } } }, "description": "body containing customers filters", "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "customerId": { "type": "string", "description": "customer external id" }, "retailers": { "description": "A list of recommended retailers ids", "type": "array", "items": { "type": "string", "description": "retailer id" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "error code" }, "message": { "type": "string", "description": "a short error description" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Get recommended retailers for members" } }, "/admin/webhook/customerTransactions": { "x-swagger-router-controller": "admin_api", "post": { "description": "trigger a customer_transactions webhook on a programme", "operationId": "sendCustomerTransactionsWebhook", "tags": [ "admin" ], "security": [ { "apiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "minTransactions": { "type": "integer", "description": "Minimum number of generated transactions (inclusive)", "default": 3, "minimum": 1 }, "maxTransactions": { "type": "integer", "description": "Maximum number of generated transactions (inclusive)", "default": 3, "minimum": 1 }, "customersExternalIds": { "type": "array", "description": "List of external customer identifiers used randomly in generated transactions", "minItems": 1, "items": { "type": "string" } }, "purchaseLocationsExternalIds": { "type": "array", "description": "List of purchase locations external identifiers used randomly in generated transactions", "minItems": 1, "items": { "type": "string" } }, "currency": { "type": "string", "description": "Transactions currency in ISO_4217 format", "minLength": 3, "maxLength": 3, "default": "EUR" } }, "required": [ "customersExternalIds", "purchaseLocationsExternalIds" ] } } }, "description": "The data describing the customer_transactions webhook requested", "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "configuredEndpoints": { "type": "integer", "minimum": 0, "description": "Number of endpoint configured" }, "successCalls": { "type": "integer", "minimum": 0, "description": "Number of successful endpoint call" }, "failedCalls": { "type": "integer", "minimum": 0, "description": "Number of failed endpoint call" } }, "required": [ "configuredEndpoints", "successCalls", "failedCalls" ] } } } }, "400": { "description": "Bad request, no endpoint registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Bad webhook registration\n* `noEndpointRegistered` - There is no endpoint registered for this programme\n", "enum": [ "noEndpointRegistered" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Send a test customer transactions webhook", "x-spaycial-profiles": [ { "option": "programmeType", "notRelevantWhen": "nonMall" } ] } }, "/admin/webhook/bankConnectionsUpdateV2": { "x-swagger-router-controller": "admin_api", "post": { "description": "trigger a bank_connections_update_v2 webhook on a programme", "operationId": "sendBankConnectionsUpdateV2Webhook", "tags": [ "admin" ], "security": [ { "apiKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eventType": { "type": "string", "description": "Type of event between create, update or delete", "enum": [ "create", "update", "delete" ] }, "customerExternalId": { "type": "string", "description": "The client's customer id" }, "connectionId": { "type": "string", "description": "The Spaycial's bank connection id, generated if not specified" }, "errorCode": { "type": "string", "description": "The error code from the data provider", "enum": [ "psd2ConnectionInvalid", "psd2ConnectionExpired", "invalidCredentials" ] }, "bank": { "type": "string", "description": "The bank name of the bank connection", "default": "Boursorama" }, "accounts": { "type": "array", "description": "Optional list of bank accounts to include on the connection (id and accountHash per account, for joint-account testing)", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Spaycial bank account id" }, "accountHash": { "type": "string", "description": "Opaque hash of the account IBAN (nullable)" } } } } }, "required": [ "eventType", "customerExternalId" ] } } }, "description": "The data describing the bank_connections_update_v2 webhook requested", "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "configuredEndpoints": { "type": "integer", "minimum": 0, "description": "Number of endpoint configured" }, "successCalls": { "type": "integer", "minimum": 0, "description": "Number of successful endpoint call" }, "failedCalls": { "type": "integer", "minimum": 0, "description": "Number of failed endpoint call" } }, "required": [ "configuredEndpoints", "successCalls", "failedCalls" ] } } } }, "400": { "description": "Bad request, no endpoint registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Bad webhook registration\n* `noEndpointRegistered` - There is no endpoint registered for this programme\n", "enum": [ "noEndpointRegistered" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unauthorized request\n* `missingAuthorizationHeader` - The Authorization header was not found\n* `invalidAuthorizationHeader` - The Authorization header is not valid\n* `missingApiKeyHeader` - The Api-Key header was not found\n* `invalidApiKeyHeader` - The Api-Key header is not valid\n* `missingExpiresAtHeader` - The Expires-at header was not found\n* `invalidExpiresAtHeader` - The Expires-at header is not valid\n", "enum": [ "missingAuthorizationHeader", "invalidAuthorizationHeader", "missingApiKeyHeader", "invalidApiKeyHeader" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "Send a test bank connections update (v2) webhook" } }, "/transactions/pushedToHub": { "x-swagger-router-controller": "transactions_api", "get": { "description": "Return a list of transactions that have been pushed to programme in a given period (30 days max)", "operationId": "getPushedTransactions", "tags": [ "transaction" ], "security": [ { "signature": [], "apiKey": [] } ], "parameters": [ { "name": "startDate", "in": "header", "description": "period start date, in full-date format of RFC3339", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "header", "description": "period end date, in full-date format of RFC3339", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "limit", "description": "the maximum number of results to retrieve (default 1000)", "in": "header", "required": false, "schema": { "type": "number" } }, { "name": "offset", "description": "the results offset (default 0), used to paginate results", "in": "header", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "identifier of the transaction" }, "amount": { "type": "number", "description": "transaction amount", "format": "float" } } }, "example": { "application/json": [ [ { "id": "3275ffc5-f1dd-435e-8757-1d293ff1e832", "amount": "-40.17" } ] ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error codes of GET /transactions/pushedToHub\n* `invalidPeriod` - Invalid startDate or endDate\n", "enum": [ "invalidPeriod" ] }, "message": { "type": "string", "description": "a short error description" } }, "required": [ "code", "message" ] } } } }, "500": { "description": "Server Error", "content": { "application/json": { "schema": { "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "a code describing the error", "enum": [ "internalServerError" ] }, "message": { "type": "string", "description": "a short error description" } } } } } } }, "summary": "List transactions sent to your programme" } } }, "security": [ { "apiKey": [], "JWT": [] } ], "tags": [ { "name": "auth", "description": "Get access tokens, register and log members in.", "x-displayName": "Authentication" }, { "name": "customer", "description": "Read and update a member's profile, bank connections, receipts, claims and rewards.", "x-displayName": "Members" }, { "name": "bank", "description": "Banks open in your programme, for monitoring.", "x-displayName": "Banks" }, { "name": "shoppingHub", "description": "Programme information, member balances and webhook subscriptions.", "x-displayName": "Programme and webhooks" }, { "name": "challenges", "description": "Offers of your loyalty programme.", "x-displayName": "Offers" }, { "name": "transaction", "description": "Transactions sent to your programme.", "x-displayName": "Transactions" }, { "name": "admin", "x-displayName": "Programme administration", "description": "Server-to-server operations for programme owners: members, stores, initial transactions and test webhooks." } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "Api-Key", "description": "Api key to use the Spaycial API (provided to you by email)" }, "JWT": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Access token required to access API, except for registration (value: `Bearer XXX` where `XXX`=token value)\n" }, "registrationJWT": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Registration access token required to access registration API (value: `Bearer XXX` where `XXX`=token value)\n" }, "signature": { "type": "apiKey", "in": "header", "name": "Signature", "description": "Signature header to authenticate through API as a service (see Introduction)" } } }, "servers": [ { "url": "https://api.transactionconnect.com" } ] }