Brother
Professional
- Messages
- 2,590
- Reaction score
- 544
- Points
- 113
Table of contents. Integration with cash register software 3 .. General requirements 3.2. Notation 3.3. Directory Values 3.4. authorization of web services 4.5. Diagram of information flows 5 2.services of the web service CARD SERVICE methods of processing cards of the GetBalanceByCardNumber method of the GetBalanceByMobileNumber method of the GetBalanceByContactCode method of the Issue method of the Active method of the Block method of the UnBlock method.
Integration with cash register software .. General requirements Integration of cash register software with loyalty processing bpm online is designed to solve the following blocks of tasks: Obtaining information on the balance of cards Changing the status of cards Replacing cards The interaction model assumes that the initial data for the specified objects are loaded / updated in JSON format from using web services (HTTP / REST). Continuous updating can be organized as in real time with the required exchange rate. Interaction information is logged in the system. There are 2 logging modes: Logging integration errors (always logged) Logging requests and responses (logged with additional configuration using a constant in the API itself) .. 2. Legend Name Incoming parameters parameters, which are transferred from the external system to the bpm online API Outgoing parameters are parameters that are transferred from bpm online to the external system. 3. Values of references Values for system references are transferred in the form of a code, which is stored in the Code field of the reference. Usually the code is a string.
Authorization of web services For authorization when calling the API method, it is necessary to convert the password and login using the standard Basic authentication algorithm. It is necessary to add a request header with an Authorization key and a value in the format: Basic {data}, where user data is formed as follows: Login and password separated by a colon (username: userpass), encoded in base64 (YWxhZGRpbjpvcGVuc2VzYWl). More detailed information and examples of authorization can be found at the link.
Diagram of information flows Business processes of information exchange between cash register software and processing are as follows: Obtaining card balance - By card number - By phone number - By contact code.
Available card statuses and reasons for changing them Obtaining the card balance: The card balance is obtained by calling the methods of the CardService web service: o api / card / balance / by / {number} o api / card / balance / by / phone / {phone} } o api / card / balance / by / {code} To get the balance of a card by its number, the balance / by / {number} method is called. On the bpm online side, the existing list of cards is checked and, if a card is found, the method returns a contact that meets the search criteria, with basic data, bonus balance and loyalty card status. To get the card balance by the contact's phone number, the balance / by / phone / {phone}} method is called. On the bpm online side, the existing list of phone numbers is checked, and if the card is found by the phone number, the method returns a contact that meets the search criteria, with basic data, bonus balance and loyalty card status. To get the balance of the card by the contact code, the balance / by / {code} method is called. On the bpm online side, the existing list of contact codes is checked and, if the card is found by the code, the method returns a contact that meets the search criteria, with basic data, bonus balance and loyalty card status. Changes to card statuses: Card statuses are changed by calling the methods of the CardService web service: o api / card / issue o api / card / bindto o api / card / active o api / card / block o api / card / unblock With manual issue cards in bpm online cards are assigned the “New” status by default - such a card is not tied to a contact. 6 To get the balance of the card by the contact code, the balance / by / {code} method is called. On the bpm online side, the existing list of contact codes is checked and, if the card is found by the code, the method returns a contact that meets the search criteria, with basic data, bonus balance and loyalty card status. Changes to card statuses: Card statuses are changed by calling the methods of the CardService web service: o api / card / issue o api / card / bindto o api / card / active o api / card / block o api / card / unblock With manual issue cards in bpm online cards are assigned the “New” status by default - such a card is not tied to a contact. 6 To get the balance of the card by the contact code, the balance / by / {code} method is called. On the bpm online side, the existing list of contact codes is checked and, if the card is found by the code, the method returns a contact that meets the search criteria, with basic data, bonus balance and loyalty card status. Changes to card statuses: Card statuses are changed by calling the methods of the CardService web service: o api / card / issue o api / card / bindto o api / card / active o api / card / block o api / card / unblock With manual issue cards in bpm online cards are assigned the “New” status by default - such a card is not tied to a contact. 6 with basic data, bonus balance and loyalty card status. Changes to card statuses: Card statuses are changed by calling the methods of the CardService web service: o api / card / issue o api / card / bindto o api / card / active o api / card / block o api / card / unblock With manual issue cards in bpm online cards are assigned the “New” status by default - such a card is not tied to a contact. 6 with basic data, bonus balance and loyalty card status. Changes to card statuses: Card statuses are changed by calling the methods of the CardService web service: o api / card / issue o api / card / bindto o api / card / active o api / card / block o api / card / unblock With manual issue cards in bpm online cards are assigned the “New” status by default - such a card is not tied to a contact.
When the fact of selling a physical card with scanning its number, the status of the card changes from "New" to "Issued", the api / card / issue method is called. Binding a card to a contact occurs after the fact of registering a contact using the api / card / bindto method. In this case, the status of the card "Issued" may not change to "Activated" if the registration data fields are not filled in enough (the customer determines whether the registration data is sufficient). When the fact of registration of a client and checking for the adequacy of filling in the fields of registration data, the api / card / active method is called - the card goes into the "Active" status. If the client wants to block his card himself through the Site or MT or with the help of a CC operator or a marketer due to loss or an administrator, a senior employee of a merchant wants to block a card due to the blacklisting of his / her phone number / card number (indicating the reason for blocking) the card goes into the "Blocked" status by calling the api / card / block method. As a result, bonuses and participation in the PL are temporarily blocked on the card. Card blocking is possible after linking the card to a contact with the "Issued" or "Active" status. If the client wants to unblock his card himself (the client can unblock the card only through the Website or MT), with the help of a CC operator or a marketer due to finding a card, or an administrator, a senior employee of a trade enterprise wants to unblock the card due to the withdrawal of the client's phone number / card number from the blacklist (indicating the reason for unblocking) the card returns to the "Issued" or "Active" status, depending on how much the client's personal data on the card is filled, by calling the method api / card / unblock. As a result, the card unblocks the write-off of bonuses (if the card goes into the "Active" status) and participation in the PL. A card blocked by an administrator cannot be unblocked (it can only be unblocked by an administrator). 7 locked by the administrator cannot be unlocked (only the administrator can unlock it). 7 locked by the administrator cannot be unlocked (only the administrator can unlock it).
API services Updating / adding data on purchases, their cancellation, refund, and card balance will be carried out using API web services over the HTTP / HTTPs protocol (RESTfull API), using the GET or POST request methods. 2 .. web service CARD SERVICE Name CARD SERVICE Service path This service is used to work with cards, their statuses, balances, replacement and search. Contains methods: GET: / balance / by / {number} GET: / balance / by / {code} GET: / balance / by / phone / {phone} GET: / Issue POST: / BindTo GET: / Active POST: / Block POST: / UnBlock http (s): // {processing address} / api / card methods for processing cards This section describes methods for obtaining a balance, binding a contact and changing card statuses of the GetBalanceByCardNumber method Name HTTP Method Path to the service GetBalanceByCardNumber GET The method is intended for getting card balance by card number http (s).
Incoming parameters Object with information about the number of the requested card in bpm online: Name Type Mandatory Value Mapping Number true Card number [Card]. [Number] Outgoing parameters Name Type Value Mapping Status boolean Operation result: - error true - no error true Key String Error code. Value String errors. The field will be empty if the request is successful. Number Card number [Card]. [Number] MobileNumb er Customer phone number [Contact]. [Mobile Number] Code Contact code (unique identifier) StatusCode Card status code. Compliance: New - Issued 2 - Active 3 - Locked StatusName Card status name: New Issued Active Locked 2 3 New, Issued, Active, Locked. [Contact]. [ Code ] [Card]. [StatusCo de] [Card]. [StatusNa me] Name Name of the contact to which the card is bound [Contact]. [Name] CategoryCod e Loyalty card category code: Match :. Plastic. Virtual [Card]. [Category Code] CategoryNa me Loyalty card category name: Plastic Plastic, Virtual [Card]. [Category Name]
Virtual TypeCode Loyalty card type code: Compliance :. Bonus. Discount 2. Bonus / Discount 2 [Card]. [TypeCod e] TypeName Name of the type of loyalty card: Bonus Discount Bonus / Discount Bonus, Discount, Bonus / D original [Card]. [TypeNam e] Bonuses Collecti on Information on bonuses collection BonusesInfo Parameters with data on the balance of bonuses: Name Type Value Mapping Amount decim al Number of bonuses with a certain status [BalanceBonus]. [A mount] StatusCo de Bonuses status code. Correspondence:. - active ,. - inactive, 2. burnt out, 3. frozen 4. - with the nearest date of combustion [BalanceBonus]. [B onusstatuscode] StatusNa me Name of the status of bonuses. active, inactive, burnt out, frozen with the nearest combustion date Active, inactive, burnt, frozen, with the nearest combustion date [BalanceBonus]. [B onusstatusname] ExpireDa te date The nearest Bonus expiration date (bonus status code 4) [BalanceBonus]. [B onusexpiredate] TypeCod e Bonus type code. Correspondence:. - cash,. - status [BalanceBonus]. [B onustypecode] TypeNam e Name of the type of bonuses. cash, status Cash, status [BalanceBonus]. [B onustypename].
Returned method results Code Status OK true Receiving card balance by card number was successful CannotFindCardN umber InvalidCardNumb er Card was not found by the Number parameter. No balance received. The card number was sent in the wrong format.
GetBalanceByMobileNumber method Name HTTP Method Path to the service GetBalanceByMobileNumber GET The method is designed to get the card balance by the contact's phone number http (s): // {processing address} / api / card / balance / by / phone / {phone} Incoming parameters Object with information about the requested phone number to search for the card balance in bpm online: Name Type Mandatory Value Mapping MobileN umber true Contact phone number [Contact]. [MobileNum ber] Outgoing parameters Name Type Value Mapping Status boolean Operation result: - error true - no error true Key String Error code. Value String errors. The field will be empty if the request is successful. Number Card number [Card]. [Number] MobileNumb er Contact phone number [Contact]. [Mobile Number] Code Contact code (unique identifier) StatusCode Card status code.
StatusName Card status name: New Issued Active Blocked New, Issued, Active, Blocked. Name Name of the contact to which the card is linked [Contact]. [Name] CategoryCod e Loyalty card category code: Match :. Plastic. Virtual [Card]. [Category Code] CategoryNa me Loyalty card category name: Plastic Virtual Plastic, Virtual [Card]. [Category Name] TypeCode Loyalty card type code: Match :. Bonus. Discount 2. Bonus / Discount 2 [Card]. [TypeCod e] TypeName Name of the type of loyalty card: Bonus Discount Bonus / Discount Bonus, Discount, Bonus / D original [Card]. [TypeNam e] Bonuses Collecti on Information on bonuses collection BonusesInfo Parameters with data on the balance of bonuses: Name Type Value Mapping Amount decim al Number of bonuses with a certain status [BalanceBonus]. [A mount] StatusCo de Bonuses status code. Correspondence:. - active ,. - inactive, 2. burnt out, 3. frozen 4. - with the nearest date of combustion [BalanceBonus]. [B onusstatuscode] StatusNa me Name of the status of bonuses. active, inactive, active, inactive, burned out, [BalanceBonus]. [B onusstatusname].
Burnt, frozen with the nearest burning date frozen, with the nearest burning date ExpireDa te date Nearest Bonus burning date (bonus status code 4) [BalanceBonus]. [B onusexpiredate] TypeCod e Bonus type code. Correspondence:. - cash,. - status [BalanceBonus]. [B onustypecode] TypeNam e Name of the type of bonuses. cash, status Cash, status [BalanceBonus]. [B onustypename] Returned method results Code Status OK true Retrieving the card balance by the contact's phone number was successful CannotFindMobil enumber The card was not found by the MobileNumber parameter. No balance received. InvalidMobileNu mber The mobile phone was sent in the wrong format.
GetBalanceByContactCode method Name HTTP Method Path to the service GetBalanceByContactCode GET The method is designed to get the card balance by the contact code http (s): // {processing address} / api / card / balance / by / {code} Input parameters Object with information about the requested code contact for searching card balance in bpm online: Name Type Mandatory Value Code true Contact code (unique identifier) Mapping [Contact]. [ Code ] Outgoing parameters Name Type Value Mapping Status boolean Operation result: - error true - no error true Key String Error code. Value String errors. The field will be empty if the request is successful. Number Card number [Card]. [Number] MobileNumb er Contact phone number [Contact]. [Mobile Number] Code Contact code (unique identifier) StatusCode Card status code.
StatusName Card status name: New Issued Active Blocked New, Issued, Active, Blocked. Name Name of the contact to which the card is linked [Contact]. [Name] CategoryCod e Loyalty card category code: Match :. Plastic. Virtual [Card]. [Category Code] CategoryNa me Loyalty card category name: Plastic Virtual Plastic, Virtual [Card]. [Category Name] TypeCode Loyalty card type code: Match :. Bonus. Discount 2. Bonus / Discount 2 [Card]. [TypeCod e] TypeName Name of the type of loyalty card: Bonus Discount Bonus / Discount Bonus, Discount, Bonus / D original [Card]. [TypeNam e] Bonuses Collecti on Information on bonuses collection BonusesInfo Parameters with data on the balance of bonuses: Name Type Value Mapping Amount decim al Number of bonuses with a certain status [BalanceBonus]. [A mount] StatusCo de Bonuses status code. Correspondence:. - active ,. - inactive, 2. burnt out, 3. frozen 4. - with the nearest date of combustion [BalanceBonus]. [B onusstatuscode] StatusNa me Name of the status of bonuses. active, inactive, active, inactive, burned out, [BalanceBonus]. [B onusstatusname].
Burnt, frozen with the nearest burning date frozen, with the nearest burning date ExpireDa te date Nearest Bonus burning date (bonus status code 4) [BalanceBonus]. [B onusexpiredate] TypeCod e Bonus type code. Correspondence:. - cash,. - status [BalanceBonus]. [B onustypecode] TypeNam e Name of the type of bonuses. cash, status Cash, status [BalanceBonus]. [B onustypename] Returned method results Code Status OK true Receiving card balance by contact code was successful CannotFindConta ctcode Card was not found by Code parameter. No balance received. InvalidContactCo de The contact code was sent in the wrong format.
Issue method Name Issue HTTP Method GET This method is used to change the card status from "New" to "Issued" in the bpm online system. Path to the method http (s): // {processing address} / api / card / issue Incoming parameters Name Type Mandatory Value Mapping Number String true Card number [Card]. [Number] Outgoing parameters Name Type Values Mapping Status boolean Result operations: - error true - success true Key String Error code. Value String errors. The field will be empty if the request is successful. Returned method results Code Status OK true Change of card status from “New” to “Issued” has been successfully performed. CardNumberCanno tfind InvalidCardNumbe r No card found for the passed Number parameter. The card number was sent in the wrong format.
19StatusError Card status mismatch. The card status cannot be changed to “Issued” by this method, since the card is in the “Activated” status. The card status cannot be changed to “Issued” by this method, since the card is in the “Blocked” status 9
Method BindTo Name HTTP Method BindTo POST This method is used to bind a contact to a card. The path to the method http (s): // {processing address} / api / card / binto Incoming parameters Name Type Mandatory Value Mapping Number Strin g true Card number to be bound to the contact. [Card]. [Numb er] MobileNum ber Strin g true Mobile phone number of the contact to which the card must be bound [Contact]. [Mo bilenumber] Outgoing parameters Name Type Values Mapping Status boolean Operation result: - error true - success true Key String Code errors. Value String errors. The field will be empty if the request is successful. Returned method results Code Status OK true The binding of the card to the contact was successful RequiredParamete rnotspecified The required method parameter was not passed. If several required parameters are not specified, then all parameters are displayed in the error description separated by commas.
CannotFindMobile The contact for the specified mobile phone was not found InvalidMobileNum ber CannotFindCardNu mber InvalidCardNumbe r CardNumberBindT oanothercontact ContactBindToAno thercardnumber The mobile phone was sent in the wrong format. No card found for the specified parameter Number The card number was sent in the wrong format. The card by the specified Number parameter is linked to another contact The contact is linked to another card. Binding of a new card is possible only if the existing card is blocked without further possibility of unblocking it. StatusError Card status mismatch. A card in the "New" status cannot be linked to a contact. 2. A card in the "Blocked" status cannot be linked to a contact.
Method Active Name HTTP Method Path to the Active GET method This method is used to activate the card after it is bound to a contact or at the time of binding to a contact with sufficient filling in of the personal data (the sufficiency of filling in the personal data is determined by the customer). http (s): // {processing address} / api / card / active Incoming parameters Object with information about the requested card for transmission to bpm'online: Name Type Mandatory Value Mapping Number Strin g true Card number [Card]. [Numb er] Outgoing parameters Name Type Values Mapping Status boolean Operation result: - error true - success true Key String Error code. Value String errors. The field will be empty if the request is successful. Returned method results Code Status OK true Card activation was successful CannotFindCardNu mber No card found for the specified parameter Number StatusError Card status mismatch. A card in the "New" status cannot change to status 22
"Active". 2. A card in the “Issued” status cannot switch to the “Active” status if it is tied to a contact, but a sufficient number of personal data is not filled in (the sufficiency of the number of personal data is determined by the customer). 3. A card in the “Blocked” status cannot go to the “Active” status using this method. 23
Block method Name HTTP Method Block POST This method is used to block the card in the bpm online system. Method path http (s): // {processing address} / api / card / block Incoming parameters Name Type Required Value Mapping Number Strin g true * Card number [Card]. [Car dnumber] BlockReaso ncode Strin g true Code reasons for blocking the card. Available values:. Loss of the card (Blocked by the client through the website / mp or blocked by the marketer, CC operator, senior employee or deputy director / director of the trade enterprise). Getting into the list of unwanted customers (blocked by a senior employee or deputy director / director of a trade enterprise) 2. Getting into a black list (blocked by a deputy director / director of a trade enterprise) 3. Refusal to use (blocked by a marketer,
The card can be replaced by a marketer, CC operator, senior employee or deputy director / director of a trade enterprise) BlockReaso nname Strin g to the list of unwanted clients, Getting into the black list, Refusal to use, Replacing the [Card]. [Blo ckreasonn ame] ContactMob ilenumber Strin g true * Mobile phone number of the contact [Contact]. [MobileNum ber] Note: one from parameters * must be specified in a mandatory order Outgoing parameters Name Type Values Mapping Status boolean Operation result: - error true - success true Key String Error code. Value String errors. The field will be empty if the request is successful.
RequiredParamete rnotspecified A required method parameter was not passed. If several required parameters are not specified, then all parameters are displayed in the error description separated by commas. CannotFindMobile The contact for the specified mobile phone was not found InvalidMobileNum ber CannotFindCardNu mber InvalidCardNumbe r The mobile phone was sent in the wrong format. No card found for the specified parameter Number The card number was sent in the wrong format. BlockReasonError The blocking reason specified does not match the user's role. The card cannot be blocked by the client indicating the reasons for blocking: Getting into the list of unwanted clients Getting into the black list Refusal to use Card replacement 2. The card cannot be blocked by the CC Operator, indicating the reasons for blocking: Getting into the list of unwanted customers Getting into the blacklist 3. The card cannot be blocked by a senior employee of the trade enterprise indicating the reasons for blocking: Getting into the black list Refusal to use 3. The card cannot be blocked by the marketer indicating the reasons for blocking Getting into the black list Hit to the list of unwanted clients 4. The card cannot be blocked by the deputy director / director of the trade enterprise indicating the reasons for blocking Refusal to use StatusError Card status inconsistency. A card in the “New” status cannot switch to the “Blocked” status. 2. A card in the “Issued” status, but without binding to a contact, cannot switch to the “Blocked” status. 26 Getting into the black list Refusal to use 3. The card cannot be blocked by a marketer indicating the reasons for blocking. Getting into the black list Getting into the list of unwanted customers 4. The card cannot be blocked by the deputy director / director of a trading company indicating the reasons for blocking Refusal to use StatusError Card status mismatch. A card in the “New” status cannot switch to the “Blocked” status. 2. A card in the “Issued” status, but without binding to a contact, cannot switch to the “Blocked” status. 26 Getting into the black list Refusal to use 3. The card cannot be blocked by a marketer indicating the reasons for blocking. Getting into the black list Getting into the list of unwanted customers 4. The card cannot be blocked by the deputy director / director of a trading company indicating the reasons for blocking Refusal to use StatusError Card status mismatch. A card in the “New” status cannot switch to the “Blocked” status. 2. A card in the “Issued” status, but without binding to a contact, cannot switch to the “Blocked” status. 26 The card cannot be blocked by the deputy director / director of the trade enterprise, indicating the reasons for blocking. Refusal to use StatusError Card status mismatch. A card in the “New” status cannot switch to the “Blocked” status. 2. A card in the “Issued” status, but without binding to a contact, cannot switch to the “Blocked” status. 26 The card cannot be blocked by the deputy director / director of the trade enterprise, indicating the reasons for blocking. Refusal to use StatusError Card status mismatch. A card in the “New” status cannot switch to the “Blocked” status. 2. A card in the “Issued” status, but without binding to a contact, cannot switch to the “Blocked” status.
Method UnBlock Name HTTP Method UnBlock POST This method is used to unblock the card. Path to the method http (s): // {processing address} / api / card / unblock Incoming parameters Object with information about the requested card for transmission to bpm'online: Name Type Mandatory Value Mapping Number Strin g true * Card number [ Card]. [CardNu mber] UnBlockRea soncode Strin g true Code of the reason for unblocking the card. Available values:. Finding the card (the client can unblock the card through the website / mp or a marketer, CC operator, senior employee or deputy director / director of a trade enterprise). Exit from the list of unwanted clients (the card can be unblocked by a senior employee, deputy director / director of a trade enterprise) 2.
After refusal to use (the marketer or CC operator can unblock the card) UnBlockRea sonname Strin g Name of the reason for unblocking the card: Finding the card Exiting the list of unwanted customers Exiting the blacklist Restoring the card after refusing to use Finding the card, Exiting the list of desirable customers, Exiting not blacklisted, Card recovery after refusing to use [Card]. [UnBlock ReasonN ame] ContactMob ilenumber Strin g true * Mobile phone number of the contact [Contact]. [Mobile Number] Note: one of the parameters * must be specified order Outgoing parameters Name Type Values Mapping Status boolean Operation result: - error true - success true Key String Error code. Value String errors. The field will be empty if the request is successful. Returned method results Code Status OK true Card unlocking was successful RequiredParamete rnotspecified A required method parameter was not passed. If several required parameters are not specified, then all parameters are displayed in the error description separated by commas. CannotFindMobile Contact cannot be found on the specified mobile phone.
InvalidMobileNum ber CannotFindCardNu mber InvalidCardNumbe r UnBlockReasonErr or The mobile phone was sent in the wrong format. No card found for the specified parameter Number The card number was sent in the wrong format. The specified reason for blocking / unblocking does not match the user's role. The card cannot be unblocked by the client if the reason for blocking has been indicated: Getting into the blacklist Getting into the list of unwanted clients Refusal to use Replacing the card 2. The card cannot be unblocked by the CC Operator if the reason for blocking has been specified: list of unwanted customers Card replacement 3. The card could not be unblocked by the senior employee of the merchant if the reason for blocking was indicated: Getting into the black list Refusal to use Card replacement.
By an employee of a merchant, indicating the reason: Recovering the card after refusal to use Exit from the blacklist 9. The card cannot be unlocked by the marketer indicating the reason: Exit from the list of unwanted customers Exit from the blacklist. The card cannot be unlocked by the deputy director / director of the trading enterprise, indicating the reason: StatusError Card status inconsistency Card restoration after refusal to use. A card in the “Blocked” status cannot switch to the “New” status after being unblocked. 2. A card in the “Blocked” status cannot switch to the “Activated” status if not enough contact registration fields are filled in. 3. A card in the “Blocked” status cannot switch to the “Issued” status if a sufficient number of contact registration fields are filled in.
Integration with cash register software .. General requirements Integration of cash register software with loyalty processing bpm online is designed to solve the following blocks of tasks: Obtaining information on the balance of cards Changing the status of cards Replacing cards The interaction model assumes that the initial data for the specified objects are loaded / updated in JSON format from using web services (HTTP / REST). Continuous updating can be organized as in real time with the required exchange rate. Interaction information is logged in the system. There are 2 logging modes: Logging integration errors (always logged) Logging requests and responses (logged with additional configuration using a constant in the API itself) .. 2. Legend Name Incoming parameters parameters, which are transferred from the external system to the bpm online API Outgoing parameters are parameters that are transferred from bpm online to the external system. 3. Values of references Values for system references are transferred in the form of a code, which is stored in the Code field of the reference. Usually the code is a string.
Authorization of web services For authorization when calling the API method, it is necessary to convert the password and login using the standard Basic authentication algorithm. It is necessary to add a request header with an Authorization key and a value in the format: Basic {data}, where user data is formed as follows: Login and password separated by a colon (username: userpass), encoded in base64 (YWxhZGRpbjpvcGVuc2VzYWl). More detailed information and examples of authorization can be found at the link.
Diagram of information flows Business processes of information exchange between cash register software and processing are as follows: Obtaining card balance - By card number - By phone number - By contact code.
Available card statuses and reasons for changing them Obtaining the card balance: The card balance is obtained by calling the methods of the CardService web service: o api / card / balance / by / {number} o api / card / balance / by / phone / {phone} } o api / card / balance / by / {code} To get the balance of a card by its number, the balance / by / {number} method is called. On the bpm online side, the existing list of cards is checked and, if a card is found, the method returns a contact that meets the search criteria, with basic data, bonus balance and loyalty card status. To get the card balance by the contact's phone number, the balance / by / phone / {phone}} method is called. On the bpm online side, the existing list of phone numbers is checked, and if the card is found by the phone number, the method returns a contact that meets the search criteria, with basic data, bonus balance and loyalty card status. To get the balance of the card by the contact code, the balance / by / {code} method is called. On the bpm online side, the existing list of contact codes is checked and, if the card is found by the code, the method returns a contact that meets the search criteria, with basic data, bonus balance and loyalty card status. Changes to card statuses: Card statuses are changed by calling the methods of the CardService web service: o api / card / issue o api / card / bindto o api / card / active o api / card / block o api / card / unblock With manual issue cards in bpm online cards are assigned the “New” status by default - such a card is not tied to a contact. 6 To get the balance of the card by the contact code, the balance / by / {code} method is called. On the bpm online side, the existing list of contact codes is checked and, if the card is found by the code, the method returns a contact that meets the search criteria, with basic data, bonus balance and loyalty card status. Changes to card statuses: Card statuses are changed by calling the methods of the CardService web service: o api / card / issue o api / card / bindto o api / card / active o api / card / block o api / card / unblock With manual issue cards in bpm online cards are assigned the “New” status by default - such a card is not tied to a contact. 6 To get the balance of the card by the contact code, the balance / by / {code} method is called. On the bpm online side, the existing list of contact codes is checked and, if the card is found by the code, the method returns a contact that meets the search criteria, with basic data, bonus balance and loyalty card status. Changes to card statuses: Card statuses are changed by calling the methods of the CardService web service: o api / card / issue o api / card / bindto o api / card / active o api / card / block o api / card / unblock With manual issue cards in bpm online cards are assigned the “New” status by default - such a card is not tied to a contact. 6 with basic data, bonus balance and loyalty card status. Changes to card statuses: Card statuses are changed by calling the methods of the CardService web service: o api / card / issue o api / card / bindto o api / card / active o api / card / block o api / card / unblock With manual issue cards in bpm online cards are assigned the “New” status by default - such a card is not tied to a contact. 6 with basic data, bonus balance and loyalty card status. Changes to card statuses: Card statuses are changed by calling the methods of the CardService web service: o api / card / issue o api / card / bindto o api / card / active o api / card / block o api / card / unblock With manual issue cards in bpm online cards are assigned the “New” status by default - such a card is not tied to a contact.
When the fact of selling a physical card with scanning its number, the status of the card changes from "New" to "Issued", the api / card / issue method is called. Binding a card to a contact occurs after the fact of registering a contact using the api / card / bindto method. In this case, the status of the card "Issued" may not change to "Activated" if the registration data fields are not filled in enough (the customer determines whether the registration data is sufficient). When the fact of registration of a client and checking for the adequacy of filling in the fields of registration data, the api / card / active method is called - the card goes into the "Active" status. If the client wants to block his card himself through the Site or MT or with the help of a CC operator or a marketer due to loss or an administrator, a senior employee of a merchant wants to block a card due to the blacklisting of his / her phone number / card number (indicating the reason for blocking) the card goes into the "Blocked" status by calling the api / card / block method. As a result, bonuses and participation in the PL are temporarily blocked on the card. Card blocking is possible after linking the card to a contact with the "Issued" or "Active" status. If the client wants to unblock his card himself (the client can unblock the card only through the Website or MT), with the help of a CC operator or a marketer due to finding a card, or an administrator, a senior employee of a trade enterprise wants to unblock the card due to the withdrawal of the client's phone number / card number from the blacklist (indicating the reason for unblocking) the card returns to the "Issued" or "Active" status, depending on how much the client's personal data on the card is filled, by calling the method api / card / unblock. As a result, the card unblocks the write-off of bonuses (if the card goes into the "Active" status) and participation in the PL. A card blocked by an administrator cannot be unblocked (it can only be unblocked by an administrator). 7 locked by the administrator cannot be unlocked (only the administrator can unlock it). 7 locked by the administrator cannot be unlocked (only the administrator can unlock it).
API services Updating / adding data on purchases, their cancellation, refund, and card balance will be carried out using API web services over the HTTP / HTTPs protocol (RESTfull API), using the GET or POST request methods. 2 .. web service CARD SERVICE Name CARD SERVICE Service path This service is used to work with cards, their statuses, balances, replacement and search. Contains methods: GET: / balance / by / {number} GET: / balance / by / {code} GET: / balance / by / phone / {phone} GET: / Issue POST: / BindTo GET: / Active POST: / Block POST: / UnBlock http (s): // {processing address} / api / card methods for processing cards This section describes methods for obtaining a balance, binding a contact and changing card statuses of the GetBalanceByCardNumber method Name HTTP Method Path to the service GetBalanceByCardNumber GET The method is intended for getting card balance by card number http (s).
Incoming parameters Object with information about the number of the requested card in bpm online: Name Type Mandatory Value Mapping Number true Card number [Card]. [Number] Outgoing parameters Name Type Value Mapping Status boolean Operation result: - error true - no error true Key String Error code. Value String errors. The field will be empty if the request is successful. Number Card number [Card]. [Number] MobileNumb er Customer phone number [Contact]. [Mobile Number] Code Contact code (unique identifier) StatusCode Card status code. Compliance: New - Issued 2 - Active 3 - Locked StatusName Card status name: New Issued Active Locked 2 3 New, Issued, Active, Locked. [Contact]. [ Code ] [Card]. [StatusCo de] [Card]. [StatusNa me] Name Name of the contact to which the card is bound [Contact]. [Name] CategoryCod e Loyalty card category code: Match :. Plastic. Virtual [Card]. [Category Code] CategoryNa me Loyalty card category name: Plastic Plastic, Virtual [Card]. [Category Name]
Virtual TypeCode Loyalty card type code: Compliance :. Bonus. Discount 2. Bonus / Discount 2 [Card]. [TypeCod e] TypeName Name of the type of loyalty card: Bonus Discount Bonus / Discount Bonus, Discount, Bonus / D original [Card]. [TypeNam e] Bonuses Collecti on Information on bonuses collection BonusesInfo Parameters with data on the balance of bonuses: Name Type Value Mapping Amount decim al Number of bonuses with a certain status [BalanceBonus]. [A mount] StatusCo de Bonuses status code. Correspondence:. - active ,. - inactive, 2. burnt out, 3. frozen 4. - with the nearest date of combustion [BalanceBonus]. [B onusstatuscode] StatusNa me Name of the status of bonuses. active, inactive, burnt out, frozen with the nearest combustion date Active, inactive, burnt, frozen, with the nearest combustion date [BalanceBonus]. [B onusstatusname] ExpireDa te date The nearest Bonus expiration date (bonus status code 4) [BalanceBonus]. [B onusexpiredate] TypeCod e Bonus type code. Correspondence:. - cash,. - status [BalanceBonus]. [B onustypecode] TypeNam e Name of the type of bonuses. cash, status Cash, status [BalanceBonus]. [B onustypename].
Returned method results Code Status OK true Receiving card balance by card number was successful CannotFindCardN umber InvalidCardNumb er Card was not found by the Number parameter. No balance received. The card number was sent in the wrong format.
GetBalanceByMobileNumber method Name HTTP Method Path to the service GetBalanceByMobileNumber GET The method is designed to get the card balance by the contact's phone number http (s): // {processing address} / api / card / balance / by / phone / {phone} Incoming parameters Object with information about the requested phone number to search for the card balance in bpm online: Name Type Mandatory Value Mapping MobileN umber true Contact phone number [Contact]. [MobileNum ber] Outgoing parameters Name Type Value Mapping Status boolean Operation result: - error true - no error true Key String Error code. Value String errors. The field will be empty if the request is successful. Number Card number [Card]. [Number] MobileNumb er Contact phone number [Contact]. [Mobile Number] Code Contact code (unique identifier) StatusCode Card status code.
StatusName Card status name: New Issued Active Blocked New, Issued, Active, Blocked. Name Name of the contact to which the card is linked [Contact]. [Name] CategoryCod e Loyalty card category code: Match :. Plastic. Virtual [Card]. [Category Code] CategoryNa me Loyalty card category name: Plastic Virtual Plastic, Virtual [Card]. [Category Name] TypeCode Loyalty card type code: Match :. Bonus. Discount 2. Bonus / Discount 2 [Card]. [TypeCod e] TypeName Name of the type of loyalty card: Bonus Discount Bonus / Discount Bonus, Discount, Bonus / D original [Card]. [TypeNam e] Bonuses Collecti on Information on bonuses collection BonusesInfo Parameters with data on the balance of bonuses: Name Type Value Mapping Amount decim al Number of bonuses with a certain status [BalanceBonus]. [A mount] StatusCo de Bonuses status code. Correspondence:. - active ,. - inactive, 2. burnt out, 3. frozen 4. - with the nearest date of combustion [BalanceBonus]. [B onusstatuscode] StatusNa me Name of the status of bonuses. active, inactive, active, inactive, burned out, [BalanceBonus]. [B onusstatusname].
Burnt, frozen with the nearest burning date frozen, with the nearest burning date ExpireDa te date Nearest Bonus burning date (bonus status code 4) [BalanceBonus]. [B onusexpiredate] TypeCod e Bonus type code. Correspondence:. - cash,. - status [BalanceBonus]. [B onustypecode] TypeNam e Name of the type of bonuses. cash, status Cash, status [BalanceBonus]. [B onustypename] Returned method results Code Status OK true Retrieving the card balance by the contact's phone number was successful CannotFindMobil enumber The card was not found by the MobileNumber parameter. No balance received. InvalidMobileNu mber The mobile phone was sent in the wrong format.
GetBalanceByContactCode method Name HTTP Method Path to the service GetBalanceByContactCode GET The method is designed to get the card balance by the contact code http (s): // {processing address} / api / card / balance / by / {code} Input parameters Object with information about the requested code contact for searching card balance in bpm online: Name Type Mandatory Value Code true Contact code (unique identifier) Mapping [Contact]. [ Code ] Outgoing parameters Name Type Value Mapping Status boolean Operation result: - error true - no error true Key String Error code. Value String errors. The field will be empty if the request is successful. Number Card number [Card]. [Number] MobileNumb er Contact phone number [Contact]. [Mobile Number] Code Contact code (unique identifier) StatusCode Card status code.
StatusName Card status name: New Issued Active Blocked New, Issued, Active, Blocked. Name Name of the contact to which the card is linked [Contact]. [Name] CategoryCod e Loyalty card category code: Match :. Plastic. Virtual [Card]. [Category Code] CategoryNa me Loyalty card category name: Plastic Virtual Plastic, Virtual [Card]. [Category Name] TypeCode Loyalty card type code: Match :. Bonus. Discount 2. Bonus / Discount 2 [Card]. [TypeCod e] TypeName Name of the type of loyalty card: Bonus Discount Bonus / Discount Bonus, Discount, Bonus / D original [Card]. [TypeNam e] Bonuses Collecti on Information on bonuses collection BonusesInfo Parameters with data on the balance of bonuses: Name Type Value Mapping Amount decim al Number of bonuses with a certain status [BalanceBonus]. [A mount] StatusCo de Bonuses status code. Correspondence:. - active ,. - inactive, 2. burnt out, 3. frozen 4. - with the nearest date of combustion [BalanceBonus]. [B onusstatuscode] StatusNa me Name of the status of bonuses. active, inactive, active, inactive, burned out, [BalanceBonus]. [B onusstatusname].
Burnt, frozen with the nearest burning date frozen, with the nearest burning date ExpireDa te date Nearest Bonus burning date (bonus status code 4) [BalanceBonus]. [B onusexpiredate] TypeCod e Bonus type code. Correspondence:. - cash,. - status [BalanceBonus]. [B onustypecode] TypeNam e Name of the type of bonuses. cash, status Cash, status [BalanceBonus]. [B onustypename] Returned method results Code Status OK true Receiving card balance by contact code was successful CannotFindConta ctcode Card was not found by Code parameter. No balance received. InvalidContactCo de The contact code was sent in the wrong format.
Issue method Name Issue HTTP Method GET This method is used to change the card status from "New" to "Issued" in the bpm online system. Path to the method http (s): // {processing address} / api / card / issue Incoming parameters Name Type Mandatory Value Mapping Number String true Card number [Card]. [Number] Outgoing parameters Name Type Values Mapping Status boolean Result operations: - error true - success true Key String Error code. Value String errors. The field will be empty if the request is successful. Returned method results Code Status OK true Change of card status from “New” to “Issued” has been successfully performed. CardNumberCanno tfind InvalidCardNumbe r No card found for the passed Number parameter. The card number was sent in the wrong format.
19StatusError Card status mismatch. The card status cannot be changed to “Issued” by this method, since the card is in the “Activated” status. The card status cannot be changed to “Issued” by this method, since the card is in the “Blocked” status 9
Method BindTo Name HTTP Method BindTo POST This method is used to bind a contact to a card. The path to the method http (s): // {processing address} / api / card / binto Incoming parameters Name Type Mandatory Value Mapping Number Strin g true Card number to be bound to the contact. [Card]. [Numb er] MobileNum ber Strin g true Mobile phone number of the contact to which the card must be bound [Contact]. [Mo bilenumber] Outgoing parameters Name Type Values Mapping Status boolean Operation result: - error true - success true Key String Code errors. Value String errors. The field will be empty if the request is successful. Returned method results Code Status OK true The binding of the card to the contact was successful RequiredParamete rnotspecified The required method parameter was not passed. If several required parameters are not specified, then all parameters are displayed in the error description separated by commas.
CannotFindMobile The contact for the specified mobile phone was not found InvalidMobileNum ber CannotFindCardNu mber InvalidCardNumbe r CardNumberBindT oanothercontact ContactBindToAno thercardnumber The mobile phone was sent in the wrong format. No card found for the specified parameter Number The card number was sent in the wrong format. The card by the specified Number parameter is linked to another contact The contact is linked to another card. Binding of a new card is possible only if the existing card is blocked without further possibility of unblocking it. StatusError Card status mismatch. A card in the "New" status cannot be linked to a contact. 2. A card in the "Blocked" status cannot be linked to a contact.
Method Active Name HTTP Method Path to the Active GET method This method is used to activate the card after it is bound to a contact or at the time of binding to a contact with sufficient filling in of the personal data (the sufficiency of filling in the personal data is determined by the customer). http (s): // {processing address} / api / card / active Incoming parameters Object with information about the requested card for transmission to bpm'online: Name Type Mandatory Value Mapping Number Strin g true Card number [Card]. [Numb er] Outgoing parameters Name Type Values Mapping Status boolean Operation result: - error true - success true Key String Error code. Value String errors. The field will be empty if the request is successful. Returned method results Code Status OK true Card activation was successful CannotFindCardNu mber No card found for the specified parameter Number StatusError Card status mismatch. A card in the "New" status cannot change to status 22
"Active". 2. A card in the “Issued” status cannot switch to the “Active” status if it is tied to a contact, but a sufficient number of personal data is not filled in (the sufficiency of the number of personal data is determined by the customer). 3. A card in the “Blocked” status cannot go to the “Active” status using this method. 23
Block method Name HTTP Method Block POST This method is used to block the card in the bpm online system. Method path http (s): // {processing address} / api / card / block Incoming parameters Name Type Required Value Mapping Number Strin g true * Card number [Card]. [Car dnumber] BlockReaso ncode Strin g true Code reasons for blocking the card. Available values:. Loss of the card (Blocked by the client through the website / mp or blocked by the marketer, CC operator, senior employee or deputy director / director of the trade enterprise). Getting into the list of unwanted customers (blocked by a senior employee or deputy director / director of a trade enterprise) 2. Getting into a black list (blocked by a deputy director / director of a trade enterprise) 3. Refusal to use (blocked by a marketer,
The card can be replaced by a marketer, CC operator, senior employee or deputy director / director of a trade enterprise) BlockReaso nname Strin g to the list of unwanted clients, Getting into the black list, Refusal to use, Replacing the [Card]. [Blo ckreasonn ame] ContactMob ilenumber Strin g true * Mobile phone number of the contact [Contact]. [MobileNum ber] Note: one from parameters * must be specified in a mandatory order Outgoing parameters Name Type Values Mapping Status boolean Operation result: - error true - success true Key String Error code. Value String errors. The field will be empty if the request is successful.
RequiredParamete rnotspecified A required method parameter was not passed. If several required parameters are not specified, then all parameters are displayed in the error description separated by commas. CannotFindMobile The contact for the specified mobile phone was not found InvalidMobileNum ber CannotFindCardNu mber InvalidCardNumbe r The mobile phone was sent in the wrong format. No card found for the specified parameter Number The card number was sent in the wrong format. BlockReasonError The blocking reason specified does not match the user's role. The card cannot be blocked by the client indicating the reasons for blocking: Getting into the list of unwanted clients Getting into the black list Refusal to use Card replacement 2. The card cannot be blocked by the CC Operator, indicating the reasons for blocking: Getting into the list of unwanted customers Getting into the blacklist 3. The card cannot be blocked by a senior employee of the trade enterprise indicating the reasons for blocking: Getting into the black list Refusal to use 3. The card cannot be blocked by the marketer indicating the reasons for blocking Getting into the black list Hit to the list of unwanted clients 4. The card cannot be blocked by the deputy director / director of the trade enterprise indicating the reasons for blocking Refusal to use StatusError Card status inconsistency. A card in the “New” status cannot switch to the “Blocked” status. 2. A card in the “Issued” status, but without binding to a contact, cannot switch to the “Blocked” status. 26 Getting into the black list Refusal to use 3. The card cannot be blocked by a marketer indicating the reasons for blocking. Getting into the black list Getting into the list of unwanted customers 4. The card cannot be blocked by the deputy director / director of a trading company indicating the reasons for blocking Refusal to use StatusError Card status mismatch. A card in the “New” status cannot switch to the “Blocked” status. 2. A card in the “Issued” status, but without binding to a contact, cannot switch to the “Blocked” status. 26 Getting into the black list Refusal to use 3. The card cannot be blocked by a marketer indicating the reasons for blocking. Getting into the black list Getting into the list of unwanted customers 4. The card cannot be blocked by the deputy director / director of a trading company indicating the reasons for blocking Refusal to use StatusError Card status mismatch. A card in the “New” status cannot switch to the “Blocked” status. 2. A card in the “Issued” status, but without binding to a contact, cannot switch to the “Blocked” status. 26 The card cannot be blocked by the deputy director / director of the trade enterprise, indicating the reasons for blocking. Refusal to use StatusError Card status mismatch. A card in the “New” status cannot switch to the “Blocked” status. 2. A card in the “Issued” status, but without binding to a contact, cannot switch to the “Blocked” status. 26 The card cannot be blocked by the deputy director / director of the trade enterprise, indicating the reasons for blocking. Refusal to use StatusError Card status mismatch. A card in the “New” status cannot switch to the “Blocked” status. 2. A card in the “Issued” status, but without binding to a contact, cannot switch to the “Blocked” status.
Method UnBlock Name HTTP Method UnBlock POST This method is used to unblock the card. Path to the method http (s): // {processing address} / api / card / unblock Incoming parameters Object with information about the requested card for transmission to bpm'online: Name Type Mandatory Value Mapping Number Strin g true * Card number [ Card]. [CardNu mber] UnBlockRea soncode Strin g true Code of the reason for unblocking the card. Available values:. Finding the card (the client can unblock the card through the website / mp or a marketer, CC operator, senior employee or deputy director / director of a trade enterprise). Exit from the list of unwanted clients (the card can be unblocked by a senior employee, deputy director / director of a trade enterprise) 2.
After refusal to use (the marketer or CC operator can unblock the card) UnBlockRea sonname Strin g Name of the reason for unblocking the card: Finding the card Exiting the list of unwanted customers Exiting the blacklist Restoring the card after refusing to use Finding the card, Exiting the list of desirable customers, Exiting not blacklisted, Card recovery after refusing to use [Card]. [UnBlock ReasonN ame] ContactMob ilenumber Strin g true * Mobile phone number of the contact [Contact]. [Mobile Number] Note: one of the parameters * must be specified order Outgoing parameters Name Type Values Mapping Status boolean Operation result: - error true - success true Key String Error code. Value String errors. The field will be empty if the request is successful. Returned method results Code Status OK true Card unlocking was successful RequiredParamete rnotspecified A required method parameter was not passed. If several required parameters are not specified, then all parameters are displayed in the error description separated by commas. CannotFindMobile Contact cannot be found on the specified mobile phone.
InvalidMobileNum ber CannotFindCardNu mber InvalidCardNumbe r UnBlockReasonErr or The mobile phone was sent in the wrong format. No card found for the specified parameter Number The card number was sent in the wrong format. The specified reason for blocking / unblocking does not match the user's role. The card cannot be unblocked by the client if the reason for blocking has been indicated: Getting into the blacklist Getting into the list of unwanted clients Refusal to use Replacing the card 2. The card cannot be unblocked by the CC Operator if the reason for blocking has been specified: list of unwanted customers Card replacement 3. The card could not be unblocked by the senior employee of the merchant if the reason for blocking was indicated: Getting into the black list Refusal to use Card replacement.
By an employee of a merchant, indicating the reason: Recovering the card after refusal to use Exit from the blacklist 9. The card cannot be unlocked by the marketer indicating the reason: Exit from the list of unwanted customers Exit from the blacklist. The card cannot be unlocked by the deputy director / director of the trading enterprise, indicating the reason: StatusError Card status inconsistency Card restoration after refusal to use. A card in the “Blocked” status cannot switch to the “New” status after being unblocked. 2. A card in the “Blocked” status cannot switch to the “Activated” status if not enough contact registration fields are filled in. 3. A card in the “Blocked” status cannot switch to the “Issued” status if a sufficient number of contact registration fields are filled in.
