# CBUS Shops: Rake ← → Omnyfy Integration

This document details the goals, functionality, and suggested APIs, webhooks, payloads, and responses to enable real-time integration of Omnyfy's marketplace transactions to trigger Rake messaging and tasks.

###### This is a working document and specifications may change after review from each party.

---

### Goals:
CBUS Shops wishes to provide a holistic virtual shopping experience including last mile delivery for shoppers of large retail centers. The proposed solution will implement Omnyfy as the marketplace for one-stop ecommerce, and Rake as the messaging and task management platform to inform drivers that orders are ready for pickup/delivery and CBUS customers of the status of that delivery.

---

#### About Omnyfy (https://omnyfy.com):
Omnyfy is a technology company that provides a marketplace platform to enable buyers to purchase products from multiple sellers in a single order. The platform enables hundreds of powerful functions designed specifically to enable multi-vendor product commerce.

#### About CBUS Shops (https://cbusshops.com):
CBUS Shops is a service company. Providing large retail centers and their brick-and-mortar retail partners a last-mile, same-day delivery solution for items that are purchased online typically for “Pick-up In-Store”.

#### About Rake (https://rake.ai):
Rake provides a messaging-as-a-platform solution to simplify messaging for all stakeholders in a workspace. Workspaces in Rake are collections of users focused on a common goal, kept accountable through tasks in a centralized hub of managed, programmable communication and messaging tools.

---

### Actors:
* **Customer** = a visitor/user of the CBUS Shops marketplace and service
* **CBUS Shops** = website or app brand through which the customer relationship exists. ``Note: All messaging to Customer should come from CBUS Shops branding.``
* **CBUS Drivers** = gig employees registered in the CBUS Workspace on Rake.
* **Partner Retailers** = brick-and-mortar stores in shopping centers partnered with CBUS Shops for last mile delivery and virtual shopping experience.
* **Omnyfy** = Marketplace software platform, backend system used by CBUS Shops to facilitate order placement to disperate retail systems.
* **Rake** = messaging and task management platform to notify CBUS drivers and update Omnyfy of delivery tasks statuses

---

### Transaction Flow Overview:

1. Customer places order on CBUS Shops website or app.
2. Omnyfy processes the order with the Retail Partners included in the transaction and confirms availability of all items at all Partner Retailer’s store locations.
3. Omnyfy sends createTask API to Rake, the task payload includes details such as CBUS Shops orderID, line item detail of items (SKUs, descriptions, sizes, colors, etc), a Customer data (First/Last Name, email, phone number), Delivery address, Delivery due date/time, and the webhook URL for callback events.
4. Rake processes task API and notifies CBUS Drivers of new task waiting via message on a common channel, and other push notifications for unassigned Tasks.
5. A CBUS Driver claims the task or is assigned the task by a CBUS Shops administrator. Rake sends a callback event to Omnyfy webhook for task status update to “Assigned”, with the user's first name and last initial (e.g. Andy W.). Omnyfy notifies Customer on behalf of CBUS Shops that their order has been assigned to {CBUS Driver: Andy W.} for delivery by {deliveryDueDate}.
6. CBUS Driver picks up items at various Partner Retailers, once all items in hand, the CBUS Driver marks the Rake task status as “Working”. Rake sends updated status to Omnyfy webhook. Omnyfy notifies Customer on behalf of CBUS Shops that {CBUS Driver: Andy W.} is out for delivery.
7. CBUS Driver travels to Customer delivery address and delivers packages. CBUS Driver then marks the Rake task as status “Complete”. Rake sends notification to Omnyfy webhook to updating Task status. Omnyfy sends customer notification on behalf of CBUS that the packages have been delivered.

---

### Rake APIs

Rake will provide a single API for Omnyfy to create a task on the Rake platform with customer and webhook callback details.

### create-task

#### Request

POST https://api.rake.ai/workspaces/workspaceId:/tasks/create-task

* Authorization: ```authToken= "bearer {data}"```
> *Rake authTokens have a 60000ms TTL. authTokens should be generated using the GetToken API which requires a "systemUserId" and "API Secret", both values will be provided by Rake and are specific to the CBUS Shops workspace in Rake. Future integrations would require different values to allow CRUD actions on tasks for a workspace.*
* Parameters: ```workspaceId (int)```

JSON Payload example:

{
    "taskData": {
       "taskTypeId": 123,   // this ID is not actual, Rake will provide the actual Task Type ID’s.  There will be two types: “Order for Delivery Today”, “Order for Delivery Tomorrow”
        "taskName": “DeliveryOrderID 123456 - Customer: Mike Brown - Deliver by Today at 5pm”,
        "assignedSystemUser":   //leave blank for unassigned 
        "taskDateDue": 01/01/2020 13:30 AM,  // UTC time - optional, TaskType will set this automatically
        "taskDetails": "plain text here" //client would prefer this to support markdown or full html
        },
    "customerData": {
          "entityId": (int 1234),  //leave empty for new Customer
          "lastName": "Testlast",
          "firstName": "Testfirst",
          "email": "[e-mail]",
          "phone": "[phone]" //needs to be in E.164 formatted
          },
    "taskWebhooks": { //optional - in case of omnyfy, this would be required
        "statusChanges": "https://webhook.site/26f95674-81f9-4b51-9824-71b09c46377d"
        }  
}     

#### Response

200 OK
{
    "message": "Task created successfully",
    "data": {
        "taskId": 12345,
        "workspaceId": 1922,
        "taskTypeId": 123,
        "taskName": "DeliveryOrderID 123456 - Customer: Mike Brown - Deliver by Today at 5pm",
        "assignedSystemUserId": (int) 1234,
        "customerEntityId": 12345
        "taskDateDue": 01/01/2020 13:30 AM,
        "taskDetailsText": "Lorem ipsum dolor sit amet",
        "webhookURL": "https://webhook.site/26f95674-81f9-4b51-9824-71b09c46377d"
        }
}