Routes¶
All routes are dispatched using the included RouteResolver. If you platform has a built in parser, the associated regex is attached (statically) to each route in the Expressly\Routes namespace. The RouteResolver will check if the required header(s), method, and route were passed through, and return the valid data (if any) inside a matched Route object, or null.
$query = '/expressly/api/*';
// @type Expressly\Entity\Route|null
$route = $app['route.resolver']->process($query);
Every single expected endpoint will be prefixed with the registered merchant_url. All Endpoints that must have hooks created in the mother system have a corresponding Presenter.
Ping Store¶
-
GET
/expressly/api/ping
¶ Route class: Expressly\Route\Ping Simple response message to note that the plugin has been installed.
Request Headers: - Content-Type – application/json
Response Headers: - Content-Type – application/json
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "expressly": "Stuff is happening!" }
Show Popup¶
-
GET
/expressly/api/
(string: uuid)¶ Route class: Expressly\Route\CampaignPopup Start the user migration process. This uri should invoke the Get Campaign Migration Popup request. The Popup can be shown over any page you wish, we recommend appending the html to your homepage.
Request Headers: - Authorization – Basic token
Response Headers: - Content-Type – text/html
Migrate User¶
-
GET
/expressly/api/
(string: uuid)/migrate
¶ Route class: Expressly\Route\CampaignMigration End of the user migration process. This uri should invoke the Get Campaign Migration Data request. The method should add all data for the provided user to the store, and if provided, add a product and/or coupon to the users’ cart. The user should be logged in directly after this migration, and a welcome email (if not part of your stores’ initial flow) should be dispatched.
Request Headers: - Authorization – Basic token
Response Headers: - Content-Type – text/html
Get User¶
-
GET
/expressly/api/user/
(string: email)¶ Route class: Expressly\Route\UserData Returns user, via your application facilities, conforming to our defined entities.
Request Headers: - Authorization – Basic token
- Content-Type – application/json
Response Headers: - Content-Type – application/json
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "meta": { "locale": "UKR", "sender": "https://yourstore.com/", "issuerData": [] }, "data": { "email": "john.smith@gmail.com", "customerData": { "firstName": "John", "lastName": "Smith", "gender": "M", "billingAddress": 0, "shippingAddress": 1, "company": "Expressly", "dob": "1987-08-07", "taxNumber": "GB0249894821", "onlinePresence": [ { "field": "website", "value": "www.myblog.com" } ], "dateUpdated": "2015-07-10T11:42:00+01:00", "dateLastOrder": "2015-07-10T11:42:00+01:00", "numberOrdered": 5, "emails": [ { "email": "john.smith@gmail.com", "alias": "default" }, { "email": "john@smithcorp.com", "alias": "work" } ], "phones": [ { "type": "M", "number": "020734581250", "countryCode": 44 }, { "type": "L", "number": "020731443250", "countryCode": 44 } ], "addresses": [ { "firstName": "John", "lastName": "Smith", "address1": "12 Piccadilly", "address2": "Room 14", "city": "London", "companyName": "WorkHard Ltd", "zip": "W1C 34U", "phone": 1, "alias": "Work address", "stateProvince": "LND", "country": "GBR" }, { "firstName": "John C.", "lastName": "Smith", "address1": "23 Sallsberry Ave", "address2": "Flat 3", "city": "London", "companyName": "", "zip": "NW3 4HG", "phone": 0, "alias": "Home address", "stateProvince": "LND", "country": "GBR" } ] } } }
PHP Implementation Example:
$customer = new Customer(); /* * fill in as many applicable setters as possible * $customer * ->setFirstName('John') * ->setLastName('Smith'); */ $response = new CustomerMigratePresenter($merchant, $customer, $email, $id); // display content however your application prefers echo json_encode($response->toArray());
Invoices for Customer Purchases¶
-
POST
/expressly/api/batch/invoice
¶ Route class: Expressly\Route\BatchInvoice Given a list of date ranges, and emails checks to see if the associated campaign users have had any transactions during the specified period.
Request Headers: - Authorization – Basic token
- Content-Type – application/json
Response Headers: - Content-Type – application/json
Example Request:
POST /expressly/api/batch/invoice Host: prod.expresslyapp.com Authorization: Basic token { "customers": [ { "email": "john.smith@gmail.com", "from": "2015-07-01T00:00:00+00:00", "to": "2015-08-01T00:00:00+00:00" } ] }
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "invoices": [ { "email": "john.smith@gmail.com", "orderCount": 1, "preTaxTotal": 100.00, "tax": 10.00, "orders": [ { "id": "ORDER-5321311", "date": "2015-07-10T11:42:00+01:00", "itemCount": 2, "coupon": "", "currency": "GBP", "preTaxTotal": 100.00, "postTaxTotal": 110.00, "tax": 10.00 } ] } ] }
PHP Implementation Example:
use Expressly\Entity\Invoice; use Expressly\Entity\Order; use Expressly\Presenter\BatchInvoicePresenter; $invoices = array(); foreach ($json->customers as $customer) { $invoice = new Invoice(); $invoice->setEmail($customer->email); foreach ($userOrders as $userOrder) { $order = new Order(); $order ->setId($userOrder->getId()) ->setDate(new \DateTime($userOrder->getOrderDate()) ->setItemCount($userOrder->getQuantity()) ->setTotal($userOrder->getTotalPreTax(), $userOrder->getTax()) ->setCoupon($userOrder->getCoupon()); $invoice->addOrder($order); } $invoices[] = $invoice; } $presenter = new BatchInvoicePresenter($invoices); // display content however your application prefers echo json_encode($presenter->toArray());
Customers on Store¶
-
POST
/expressly/api/batch/customer
¶ Route class: Expressly\Route\BatchCustomer Given a list of emails, checks to see if a user has completed the migration process.
Request Headers: - Authorization – Basic token
- Content-Type – application/json
Response Headers: - Content-Type – application/json
Example Request:
POST /expressly/api/batch/customer Host: prod.expresslyapp.com Authorization: Basic token { "emails": [ "john.smith@gmail.com" ] }
Example Response:
HTTP/1.1 200 OK Content-Type: application/json { "existing": [ "john.smith@gmail.com" ], "deleted": [], "pending": [] }
PHP Implementation Example:
use Expressly\Presenter\BatchCustomerPresenter; $existingUsers = array(); $deletedUsers = array(); $pendingUsers = array(); foreach ($json->emails as $email) { // add user to certain sector of array, depending on state } $presenter = new BatchCustomerPresenter($existingUsers, $deletedUsers, $pendingUsers); // display content however your application prefers echo json_encode($presenter->toArray());
[RouteResolver] | src/Resolver/RouteResolver (namespace ExpresslyResolverRouteResolver) |
[merchant_url] | the location to execute/catch our paths; example: https://www.example.com/route?action=/expressly/api/ping |
[Route] | src/Entity/Route (namespace ExpresslyEntityRoute) |
[Presenter] | src/Presenter (namespace ExpresslyPresenter) |
[entities] | src/Entity (namespace ExpresslyEntity) |