.. _omnotif-label: Order Management Notification Service ===================================== The Order Management Notification Service provides support for notifications, to be sent from the Flipkart system to the seller system, for any event in a shipment lifecycle, such as shipment creation, label creation, shipment cancellation, and so on. You can use this feature to improve the performance of your application by eliminating additional network and computation costs in polling resources to determine if they have changed. **Format:** ``JSON`` +---------------------------------+---------------------------------------------------------------------+ | Notification | Description / Use Case | +=================================+=====================================================================+ |:ref:`push-shipment-create-label`|Sent when an order is placed | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-hold-label` |Sent when an order item is flagged as | | |“Hold” | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-unhold-label` |Sent when an order item flagged as “Hold” | | |is released for further processing | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-pack-label` |Sent when an order item state is changed | | |to "Packed" | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-rtd-label` |Sent when an order item is marked as | | |“Ready to Dispatch” | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-pickup-label` |Sent when the shipment is picked up by the | | |logistics team | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-ship-label` |Sent when an order item is shipped | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-deliver-label` |Sent when an order item is delivered | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-sla-label` |Sent when the dispatch date is changed | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-cancel-label` |Sent when an approved order is cancelled | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-form-failed-label` |Sent when a form generation fails | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-createreturn-label` |Sent when a new return request is created | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-tracking-id-label` |Sent when an when tracking details for a customer return is updated | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-returnexpected-label` |Sent when the expected date of return of an orderItem changes | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-pickedupreturn-label` |Sent when a return is picked up | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-completereturn-label` |Sent when a return is completed | +---------------------------------+---------------------------------------------------------------------+ |:ref:`push-cancelreturn-label` |Sent when a return request is revoked | +---------------------------------+---------------------------------------------------------------------+ .. _subscribe-notification-label: Subscribing to Notifications ---------------------------- To use notifications: * You must be a registered seller on https://seller.flipkart.com. * Setup a notification receiver in your system. This is an HTTPS server that handles the API notifications triggered when a resource changes. For example: https://www.[your-website].com/notifications-receiver. * You should have a VAPT certificate for the notification receiver in your system. Write to seller-api-queries@flipkart.com to subscribe to the notifications. Please provide the following details: - Seller id / Seller registered email address - Notification receiver URL - VAPT certificate for the URL - If return notifications are needed (Yes / NO) - If Yes then Notification receiver URL for return notification( This could be same as order notification URL) - If return notification URL is different then provide VAPT certificate for the URL - Location ids for which you wants to listen order and return notifications .. note:: Even if you are a 3rd party aggregator you need to provide seller id / seller registered email address for which you will consume the events. The proposed event structure for these notifications contain the following parameters: =============== ==================================== Parameter Name Description =============== ==================================== ``eventType`` The notification type. Possible values: ``shipment_created``, ``shipment_packed``, ``shipment_ready_to_dispatch``, ``shipment_shipped``, ``shipment_delivered``, and so on ``source`` Point of origin of the notification - "flipkart" ``timestamp`` ISO time string ``attributes`` Custom parameters for the event =============== ==================================== .. _notifauth-label: Notifications Authentication ---------------------------- All Flipkart Notifications are RESTful notifications that send event payloads to the seller system endpoint. Sellers authenticate to Flipkart API using OAuth credentials (``Application ID`` and ``Application Secret``). Those who wish to listen to notifications must register their notification endpoints with Flipkart. Sellers need a mechanism to validate whether the request originated from Flipkart and not by untrusted sources. Flipkart REST APIs authenticate to seller notification endpoints using a signature-based authentication by using Authorization headers. Every notification includes headers in the following format: :: X_Date : X_Authorization : FKLOGIN Base64 (OAuth-appid : ) Here, * ``date_timestamp`` is the timestamp at which the notification is generated and is in “HTTP-Date” format. * ``fk_signature`` is generated per request using SHA1 based message digest algorithm with values derived from request as: :: SHA-1 (date_timestamp + notification_http_url + notification_http_method + OAuth-secret) REST endpoints that receive these notifications need to authenticate the request by regenerating the Signature (``fk_signature``) using the logic above and verifying it with the Authorization (``X_Authorization``) header. Consider the following example. Authentication Sample ~~~~~~~~~~~~~~~~~~~~~ +----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ |**Seller**: PilotSeller | | | |**OAuth Appication ID**: ``6113ca4a-fe05-11e4-a322-1697f925ec7b`` | | | |**OAuth Application Secret**: ``669a57f4-fe05-11e4-a322-1697f925ec7b`` | | | |**Notification URL**: ``http://seller.api.pilotseller.com/notify/fki POST`` | | | |**Timestamp**: ``1432026135`` | | | |**Signature**: :: | | | | SHA1(1432026135http://seller.api.pilotseller.com/notify/fkiPOST669a57f4-fe05-11e4-a322-1697f925ec7b) 83762abd87b41e66ddd58320a4e803251e72b776 | | | |**Authorization Information**: :: | | | | Base64(6113ca4a-fe05-11e4-a322-1697f925ec7b:83762abd87b41e66ddd58320a4e803251e72b776)NjExM2NhNGEtZmUwNS0xMWU0LWEzMjItMTY5N2Y5MjVlYzdiOjgzNzYyYWJkODdiNDFlNjZkZGQ1ODMyMGE0ZTgwMzI1MWU3MmI3NzY= | | | |**Headers** | | | |**X_Date**: Tue, 19 May 2015 09:02:15 GMT | | | |**X_Authorization**: :: | | | | FKLOGIN NjExM2NhNGEtZmUwNS0xMWU0LWEzMjItMTY5N2Y5MjVlYzdiOjgzNzYyYWJkODdiNDFlNjZkZGQ1ODMyMGE0ZTgwMzI1MWU3MmI3NzY= | +----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. _notifresponse-label: Notifications Response ---------------------- For a notification, the seller application needs to respond with a standard HTTP success status 200, or should throw an error response in the following scenarios only: * When the seller system is down * If the payload is incorrect The notification system ensures that the message is sent at least once, but not only once. Hence, it is recommended to add an idempotency check in the client to avoid processing of duplicate notifications.