Miravia Open Platform
Getting started with Miravia Push Mechanism
Step1 : Prepare your callback url to receive notifications from Miravia.
Step2: Understand push mechanism details include authorization, retry, etc.. and finish your coding.
Step3: Fill your url in and verify it.
Step4: Subscribe to push messages.
This work-through document will take order notification as example.
Step1 : Prepare your callback url to receive notifications from Miravia.
It must be a https with CA certs.
- Certification must be authorized by CA. Self-signed certs are not acceptable.
- Certs must be OV or EV. DV is not working.(know more about certs level : https://www.digicert.com/difference-between-dv-ov-and-ev-ssl-certificates ).
Step2: Understand push mechanism details include authorization, retry, etc.. and finish your coding.
After have your call back url, you need to know what a notification looks like. For example, order msg have two types of messages: trade order message and reverse order message. Trade order message triggered when trade order actions happens. trade order actions includes all you can do to a order except return and refund. When customer decide to return, refund, a reverse order message will be sent.
#Header:Only you need to know is the 'Authorization' tag since that is the signature. #More details about it will be covered later. #1.trade order message sample(trade order actions includes order create, paid, shipped.. etc) POST / example / uri HTTP / 1.1 Host : www . example . com Content - Type : application / json Content - Length : 1238 Authorization : 34 f7b258df045d4ed9341850ca85b866f34828fd7d51862f11137216294a894c #body { "seller_id" : "123 4567" , #seller id "message_type" : 0 , "data" :{ "order_status" : "unpaid" , #Order status "status_update_time" : 1603698638 , #timestamp of the order status update "trade_order_id" : "260422900198363" , #trade order id which mapping to the order_id in API "trade_order_line_id" : "260422900298363" #sub order id. }, "timestamp" : 1603766859530 , #timestamp of push "site" : "Arise_vn" # site info } #2.reverse order message sample (reverse order actions includes return, refund etc..) POST / example / uri HTTP / 1.1 Host : www . example . com Content - Type : application / json Content - Length : 1238 Authorization : 34 f7b258df045d4ed9341850ca85b866f34828fd7d51862f11137216294a894c #body { "seller_id" : " 1000114855" , "message_type" : 0 , "data" :{ "order_status" : "canceled" , "reverse_order_id" : "501977696648153" , #reverse order id "reverse_order_line_id" : "502491640048153" , #reverse sub-order id "status_update_time" : 1603703663 , "trade_order_id" : "252883361348153" , #related trade order id "trade_order_line_id" : "252883361948153" #related trade order sub id }, "timestamp" : 1603715010436 , " site" : "Arise_vn" }
Note: "order_status" refers to order line status, the push notification is sent by order line. If one order includes 3 order line, it will receive 3 different notification and the order status is belong to every one order line.
Authorization:
To make sure the request is sent from Miravia and the request data is complete, Miravia will generate a signature and put it into request header. Client can reproduce the signature and compare it to the one received in message before consuming.
Signature is generated by Hex-encoded HMAC-SHA256.
/* Base = {your_app_key} + "{message_body_you_receieved}" Secret = {your_app_Secret}; */ Authorization = HEX_ENCODE(HMAC-SHA256(Base, Secret));
Sample Java Code to reproduce the signature:
import org . slf4j . Logger ; import org . slf4j . LoggerFactory ; import javax . crypto . Mac ; import javax . crypto . spec . SecretKeySpec ; /** * Signature tool class * @author Jeremy * @date 2020/12/01 * / public class SignatureUtil { private static final String HMAC_SHA256 = "HmacSHA256" ; private static final Logger LOGGER = LoggerFactory . getLogger ( SignatureUtil . class ); /** * Hmac-SHA256 * @param base {AppKey} + {messageBody} * @ param secret {AppSecret} * Eg: AppKey = 123456, AppSecret = 3412gyo124goi3124 * messageBody: {"seller_id":"1234567", "message_type":0, "data":{...}..} * * base = " 123456" + "{\"seller_id\":\"1234567\", \"message_type\":0, "data":{...}..}" * secret = 3412gyo124goi3124 * signature = getSignature(base, secret ; . getBytes ( ) , HMAC_SHA256 ) _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ ; sha256Hmac . init ( secretKey ); return byteArraytoHexString ( sha256Hmac . doFinal ( base . getBytes ())); } catch ( Exception e ) { LOGGER .error ( "Failed to generate signature" ); } return null ; } /** * Hex Encode * @param bytes * @return */ private static String byteArraytoHexString ( byte [] bytes ) { if ( bytes == null ) { return null ; } StringBuilder sb = new StringBuilder (); String stmp ; for ( byte aByte : bytes ) { stmp = Integer . toHexString ( aByte & 0XFF ); if ( stmp . length () == 1 ) { sb . append ( '0' ); } sb . append ( stmp ); } return sb . toString () . toLowerCase (); } }
Sucess acknowledgment and retry:
- You need to ack with Http status code 200 with in 500ms
- If you fail to do 1, server will retry sending the message after 30 mins.
- If retry fails again, the server will retry in another 30 mins.
- if you fail more than 12 times or you successfully do 1 before 12 times, server will stop retrying.
Question you may have:
- Once a message is successfully acked, the server wont retry sending this message.
- Order status may be changed in 30 mins, will server update the status before push? Yes
Step3: App Console self-test, self-access .
Log in to open.Miravia.com , and enter APP Console-APP Management-Manage-Push Mechanism tab after logging in
1. Fill in the callback address and click Verify. Verify will automatically send a test message to the filled address, if the return meets expectations, it will prompt success.
Note: The access person should manually enter the background to confirm the test message, including confirming the test content, confirming the signature, etc. The signature here is true.
2. After the verification is successful, select the message type to subscribe, and click Save in the upper right corner.
Note : The data of all ISVs that have been manually accessed before will be automatically synchronized here, and you do not need to perform the above automatic access operations.
The following actions will not take effect immediately before March 15th and will be delayed until March 15th:
1. The newly connected ISV uses automatic access to save the online address.
2. The ISV that was previously manually accessed uses automatic access to change the online address.
Step4: Go production and best practice
After onboarded, below is a recommended way of consuming the message.
A way of consuming push message is:
OrderMessage ----------> /order/get ---------->/order/items/get -> business logic
trade_order_id trade_order_id
How to switch the consuming pattern from `pulling only` to `consume push, but pull with low frequency to protect from missing` ?
Strategy 1:
Keep pulling frequency unchanged, but add consuming push logic. And gradually lowering the frequency of pulling.
Strategy 2:
Whitelisting some sellers, use the new startegy. And gradually adding sellers to whitelist.
FAQ:
I need the IPs of push servers to do ip white-listing, can you guys provide the ips?
Miravia recommends to use signature on authorization header to check the origin of pushes. No further supports on IPs from Miravia.
Some sellers messages are missing.
Server will check the authorization between sellerId and appkey. If the auth is revoked or expired, server will abort the pushing. You can verify the authorization by checking the token that you use for calling the API.
Would there be more message types beside order message?
Only order message is online now. Product, promotions, stock message is under developing.
How to get the orders if all retries failed?
You need to use /orders/get API to get them. The recommended way of consuming the message is: Consume the order messages, and pull the orders periodically to check if there is any missing. So called "consume push, but pull with low frequency to protect from missing"
Duplicate message pushed for same order?
Firstly, small amount of duplicate message is normal. Message design is 'at least once push'. Idempotently consuming is required.
Secondly, if you got huge amount duplicate, please pay attention to the field 'trade_order_line_id'. If two messages have same trade_order_id but different trade_order_line_id, server will treat it as different messages.
