API documentation on how we exchange orders data with any fulfillment centre system.
\nThis is a short summary of the steps of API communication to build proper and accurate data exchange between the Merkana Group platform and our partners - fulfillment (FF) centres. All steps described below are available and applicable only after we register and authorise the FF centre in the back-end. Steps 1 and 2 are also required for each e-commerce merchant who will be using this FF centre.
\nAll integrated FF centres will receive a unique authorisation token and must use it when sending a request to our platform. This is a key-value pair on the header (api-token - 123456789).
We are ready to implement the auth requirements from FF centres and apply them accordingly when we send data.
We use JSON with:
status - true/false
message - some user-friendly message
There is still no limit, but such may be imposed upon reaching certain volumes of data exchange.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Introduction","slug":"introduction"},{"content":"Overview","slug":"overview"},{"content":"Authentication","slug":"authentication"},{"content":"Error Codes","slug":"error-codes"},{"content":"Rate limit","slug":"rate-limit"}],"owner":"25353905","collectionId":"88949d46-1920-4fe3-9a1b-dc74fac51d9e","publishedId":"2s8ZDbWLSw","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2023-01-24T09:50:06.000Z"},"item":[{"name":"1. send to FF - product info sync","id":"cef3fba9-3ec9-4546-9602-e1c6ac29fe95","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"mid\": 293,\r\n \"products\": [\r\n {\r\n \"id\": 123, //our unique ID \r\n \"sku\": \"SKU-123\",\r\n \"ean\": \"123123\",\r\n \"title\": \"product-title\",\r\n \"img\": \"https: //clients.mercoria.com/uploads/images/products/xx/image-file.jpg\"\r\n // You can send us your requirements\r\n }\r\n ]\r\n}","options":{"raw":{"language":"json"}}},"url":"https://XXXXXXXX/sync_products.php","description":"Initial send product information to fulfillment centre (FF).
\nMust be done before linking an existing FF to a sales channel (e-commerce platform or marketplace) in Mercoria.
\nInitiated by our system, we send JSON with:
\nmid (can be changed) - unique merchant id in FF system
\nan array of products with basic product info
\nInitial stock info loading from FF.
\nMust be done before linking an existing FF to a sales channel (e-commerce platform or marketplace) in Merkana.
\nWe send a unique merchant ID from the FF system and expect JSON with the stock info.
\n\"stock\" is an array with all products for this merchant, described by SKU -quantity.
\n","urlObject":{"protocol":"https","path":["stock.php"],"host":["XXXXXXXX"],"query":[],"variable":[]}},"response":[],"_postman_id":"86f0a0cc-9196-4d88-8df7-7c0727ac7645"},{"name":"3. send to FF - new order create","id":"8e0c38e8-ea63-46fa-ae2c-ccb2ee5f805f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"mid\": 4755,\r\n \"unknownproductid\": 1,\r\n \"email_ff_problem\": \"test@valival.com\",\r\n \"id\": 40103, // our internal unique ID\r\n \"status\": \"create\", // if need\r\n \"total\": 77.7000,\r\n \"insurance\": 77, // if need\r\n \"currency\": \"BGN\",\r\n \"payment_method\": \"COD\", //COD - cash-on-delivery, NOCOD, BANK, ONLINE\r\n \"customer_note\": \"call me\", // if need\r\n \"shipping\": {\r\n \"shipping_contact\": \"Tihomir Sokolov\",\r\n \"shipping_phone\": \"0899196290\",\r\n \"shipping_country\": \"BG\",\r\n \"shipping_suburb\": \"\",\r\n \"shipping_city\": \"София\",\r\n \"shipping_street\": \"бул. Братя Бъкстон, 33\",\r\n \"shipping_postal_code\": \"1000\",\r\n \"shipping_locality_id\": null,\r\n \"shipping_instructions\": \"black door\",\r\n \"shipping_method\": null,\r\n \"company\": \"\\u0442\\u0442\",\r\n \"email\": \"tihomir.sokolov@gmail.com\",\r\n \"shipping_country_id\": null,\r\n \"shipping_city_id\": null,\r\n \"shipping_street_id\": null,\r\n \"shipping_courier_office\": \"1085\",\r\n \"shipping_courier\": \"econt\"\r\n },\r\n \"awb\": null, // number\r\n \"awb_url\": null, // label file\r\n \"url_factura\": \"https:\\/\\/api.mercoria.com\\/storage\\/invoice\\/XXXXXX\\/953-14.pdf\",\r\n \"line_items\": [\r\n {\r\n \"sku\": \"7563\",\r\n \"quantity\": 1\r\n },\r\n {\r\n \"sku\": \"9047\",\r\n \"quantity\": 1\r\n },\r\n {\r\n \"sku\": \"41705\",\r\n \"quantity\": 1\r\n }\r\n ],\r\n \"ff_note\": null //note for fulfill\r\n}","options":{"raw":{"language":"json"}}},"url":"https://cronny.metrica.bg/ecommerce/connectors/clients/mercoria/save_order_with_packets.php","description":"New order information.
\nAfter a new order is being recorded, we send it to FF - POST with JSON data:
\n\"mid\" - merchant ID in FF system
\n\"unknownproductid\" - ID of unknown product in FF system for this merchant
\n\"id\" - unique order ID from our system
\nall other standard information with shipping info and items in an order (list?).
\nJSON format can be adapted for FF.
\nExpected response: \"status\" - true
\nOrder info is sent by Q job, and if it fails, it will be retried 5 times at 10-minute intervals before the job is marked as failed.
\nFailed jobs are processed manually on the next working day.
\n","urlObject":{"protocol":"https","path":["ecommerce","connectors","clients","mercoria","save_order_with_packets.php"],"host":["cronny","metrica","bg"],"query":[],"variable":[]}},"response":[],"_postman_id":"8e0c38e8-ea63-46fa-ae2c-ccb2ee5f805f"},{"name":"4. send to FF - order cancel","id":"18c1ca37-bcf5-4040-b6b2-a4591893d870","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"mid\": 293,\r\n \"id\": 226\r\n}","options":{"raw":{"language":"json"}}},"url":"https://XXXXXXXX/cancel_order.php","description":"Request to cancel an order.
We send it if our system receives a request from a channel or marketplace for order cancellation.
Post with JSON data:
\"mid\" - merchant unique ID from FF system
\"id\" - order ID from our system
We expect:
\"status\" - true if the order can be cancelled, and false if it is being processed and can't be cancelled.
We will expect a notification when the order status is changed in the FF system.
\nAuthentication
All requests to our system must contain a header with:
key - \"api-token\" with a secret value provided by us.
JSON array can hold many orders with status changes.
\nAll parameter names can be changed on the initial fulfillment setup.
\nMandatory parameters are:
\nWe will expect a notification when the fulfillment system reports new stock for a merchant.
\nAuthentication
All requests to our system must contain a header with:
key - \"api-token\" with a secret value provided by us.
JSON array can hold many products for a specific merchant.
\nAll parameter names can be changed on the initial fulfillment setup.
\nMandatory parameters are:
\n\"mid\" - merchant ID in FF system
\n\"products\" - an array of products described by:
\"sku\" - product sku
\"br\" - number
Note: the number can be negative (e.g. if there are missing pieces in the audit)
\n