BLUEFIN QUICKSWIPE API LIBRARY. Processing API s for QuickSwipe Mobile / QuickSwipe mpos

Transcription

1 BLUEFIN QUICKSWIPE API LIBRARY Processing API s for QuickSwipe Mobile / QuickSwipe mpos 1

2 Contents Introduction QuickSwipe API Library... 4 JSON REST API Format... 4 Account API... 5 Users API... 9 Items API Transactions API Tax Rates API Categories Settings

3 Bluefin has made efforts to ensure the accuracy and completeness of the information in this document. However, Bluefin disclaims all representations, warranties and conditions, whether express or implied, arising by statute, operation of law, usage of trade, course of dealing or otherwise, with respect to the information contained herein. Bluefin assumes no liability to any party for any loss or damage, whether direct, indirect, incidental, consequential, special or exemplary, with respect to (a) the information; and/or (b) the evaluation, application or use of any product or service described herein. Bluefin disclaims any and all representation that its products or services do not infringe upon any existing or future intellectual property rights. Bluefin owns and retains all right, title and interest in and to the Bluefin intellectual property, including without limitation, its patents, marks, copyrights and technology associated with the Bluefin services. No title or ownership of any of the foregoing is granted or otherwise transferred hereunder. Bluefin reserves the right to make changes to any information herein without further notice. Related Bluefin Trademarks Bluefin Bluefin Payment Systems QuickSwipe PayConex FraudFirewall Swipe Over IP 2015 All Rights Reserved S. 129 th E. Ave., Suite 101, Tulsa, OK Toll Free (800) Phone (918) Fax (918) efax (918) UPDATED: May 27, 2015 Document Version

4 Introduction QuickSwipe API Library This document reviews Bluefin s QuickSwipe family of Application Programming Interface (API) services. These services provide our clients with user, product, category, and order-level management pertaining to the QuickSwipe mobile app and POS system. JSON REST API Format Every request that requires authentication will require that a token be passed in the url?token=abcde. A token will be generated during a successful login request Parameter & s Unless noted all strings will have a maximum length of 255 characters. Unless noted all decimal values will have a 2 decimal place precision. True or false parameters should be posted using either a 1 or 0. o Including the parameter without a value will be typecasted to false. File upload will require that a multipart/form-data post be made. Date/Time values will be returned using the following format: o YYYY-MM-DD HH:MM:SS 4

5 Account API End Points Login Logout Account Information Update 5

6 Login Will generate and save an authenticity token. URL: /api/json/account/login/ Method: POST curl \ -d "account_id=12345" \ -d " =admin@example.org" \ -d "password=admin" Arguments account_id: integer (required) string (required) passsword: string (required) HTTP/ OK Content-Type: application/json; charset=utf-8 } "id" : 8, "company_id" : 1, "retired" : false, "confirmed" : true, "first_name" : "John", "last_name" : "Doe", " " : "john.doe@example.org", "role" : "admin", "time_zone" : "America\/Chicago", "token" : "535e787c-7fc4-4d8c f00abbf825", "photo" : "", "mobile" : "", "permission_items_manage" : false, "permission_items_retire" : false, "permission_transactions_discount" : false, "permission_transactions_refund" : false, "permission_transactions_tax_exempt": false, "modified" : " :49:16", "created" : " :43:48" 6

7 Logout Will remove the user's authenticity token. URL: /api/json/account/logout/ Method: GET curl HTTP/ No Content 7

8 Account Information URL: /api/json/account/ Method: GET curl HTTP/ OK Content-Type: application/json; charset=utf-8 } "id" : 8, "company_id" : 1, "retired" : false, "confirmed" : true, "first_name" : "John", "last_name" : "Doe", " " : "john.doe@example.org", "role" : "admin", "time_zone" : "America\/Chicago", "token" : "535e787c-7fc4-4d8c f00abbf825", "photo" : "", "mobile" : "", "permission_items_manage" : false, "permission_items_retire" : false, "permission_transactions_discount" : false, "permission_transactions_refund" : false, "permission_transactions_tax_exempt": false, "modified" : " :49:16", "created" : " :43:48" 8

9 Users API Endpoints List Create View Update Delete 9

10 List URL: /api/json/users/ Method: GET curl HTTP/ OK Content-Type: application/json; charset=utf-8 [ ] } "id" : 8, "company_id" : 1, "retired" : false, "confirmed" : true, "first_name" : "John", "last_name" : "Doe", " " : "john.doe@example.org", "role" : "admin", "time_zone" : "America\/Chicago", "token" : "535e787c-7fc4-4d8c f00abbf825", "photo" : "", "mobile" : "", "permission_items_manage" : false, "permission_items_retire" : false, "permission_transactions_discount" : false, "permission_transactions_refund" : false, "permission_transactions_tax_exempt": false, "modified" : " :49:16", "created" : " :43:48" 10

11 Create URL: /api/json/users/ Method: POST curl \ -F " =new-clerk@example.org" \ -F "password=p@ssw0rd" \ -F "role=clerk" \ -F "photo=@file.jpg" Arguments string (required) password: string (required) role: admin clerk (required) photo: file permission_items_manage: boolean permission_items_active: boolean permission_transactions_discount: boolean permission_transactions_refund: boolean permission_transactions_tax_exempt: boolean HTTP/ Created Location: /api/json/users/9/ Content-Type: application/json; charset=utf-8 "id" : 9, "company_id" : 1, "retired" : false, "confirmed" : true, "first_name" : "John", "last_name" : "Doe", " " : "new-clerk@example.org", "role" : "admin", "time_zone" : "America\/Chicago", "token" : "535e787c-7fc4-4d8c f00abbf825", "photo" : " "mobile" : "", "permission_items_manage" : false, "permission_items_retire" : false, "permission_transactions_discount" : false, "permission_transactions_refund" : false, "permission_transactions_tax_exempt": false, "modified" : " :49:16", "created" : " :43:48" 11

12 } 12

13 View URL: /api/json/users/1/ Method: GET curl HTTP/ OK Content-Type: application/json; charset=utf-8 } "id" : 9, "company_id" : 1, "retired" : false, "confirmed" : true, "first_name" : "John", "last_name" : "Doe", " " : "john.doe@example.org", "role" : "admin", "time_zone" : "America\/Chicago", "token" : "535e787c-7fc4-4d8c f00abbf825", "photo" : "", "mobile" : "", "permission_items_manage" : false, "permission_items_retire" : false, "permission_transactions_discount" : false, "permission_transactions_refund" : false, "permission_transactions_tax_exempt": false, "modified" : " :49:16", "created" : " :43:48" 13

14 Update URL: /api/json/users/1/ Method: PUT curl \ -F " =old-clerk@example.org" \ -F "photo=@file.jpg" Arguments string password: string role: admin clerk photo: file permission_items_manage: boolean permission_items_active: boolean permission_transactions_discount: boolean permission_transactions_refund: boolean permission_transactions_tax_exempt: boolean HTTP/ OK Content-Type: application/json; charset=utf-8 } "id" : 8, "company_id" : 1, "retired" : false, "confirmed" : true, "first_name" : "John", "last_name" : "Doe", " " : "john.doe@example.org", "role" : "admin", "time_zone" : "America\/Chicago", "token" : "535e787c-7fc4-4d8c f00abbf825", "photo" : "", "mobile" : "", "permission_items_manage" : false, "permission_items_retire" : false, "permission_transactions_discount" : false, "permission_transactions_refund" : false, "permission_transactions_tax_exempt": false, "modified" : " :49:16", "created" : " :43:48" 14

15 Delete URL: /api/json/users/11/ Method: DELETE curl -X DELETE HTTP/ No Content 15

16 Items API End Points List/Filter Create View Update 16

17 List / Filter URL: /api/json/items/ Method: GET Arguments (optional) amount: integer - Number of results to return contains: integer - Offset amount retired: boolean favorite: boolean price_min: float price_max: float created_by_id: integer category_id: integer curl HTTP/ OK Content-Type: application/json; charset=utf-8 [ "id" :614, "company_id" :1, "created_by_id" :4, "tax_rate_id" :null, "canonical_id" :196, "version" :"current", "name" :"Race Car", "price" :2.5, "sku" :"0", "note" :"This is a note", "photo" :" "retired" :false, "favorite" :true, "use_default_tax" :true, "recurring" :true, "recurring_schedule":"monthly_1", "recurring_payments":7, "modified" :" :48:27", "created" :" :41:06", "tax_rate" : "id" :2, "company_id":1, "name" :"County Tax", "amount" :2.25, "modified" :" :19:26", "created" :" :19:26" }, 17

18 ] } "categories":[ "id" :7, "company_id":1, "name" :"Toys", "photo" :null, "modified" :" :49:26", "created" :" :35:00" } ] 18

19 Create URL: /api/json/items/ Method: POST Arguments name: string (required) price: float (required) category_ids: integer list tax_rate_id: integer sku: string photo: file note: string retired: true favorite: boolean use_default_tax: boolean recurring: boolean recurring_schedule: string curl \ -F "name=a New Item" \ -F "price=3.99" \ -F "tax_rate_id=1" \ -F "category_ids=1,2" \ -F "photo=@file.jpg" HTTP/ Created Location: /api/json/items/1/ Content-Type: application/json; charset=utf-8 "id" :1, "company_id" :1, "created_by_id" :2, "tax_rate_id" :1, "canonical_id" :1, "version" :"current", "name" :"A New Item", "price" :3.99, "sku" :null, "note" :null, "photo" :" "retired" :false, "favorite" :false, "use_default_tax" :false, "recurring" :false, "recurring_schedule":null, "recurring_payments":null, "modified" :" :43:03", "created" :" :43:00", 19

20 } "tax_rate" : "id" :1, "company_id":1, "name" :"Illinois State Tax", "amount" :6.25, "modified" :" :19:26", "created" :" :19:26" }, "categories" :[ "id" :1, "company_id":1, ] }, } "name" :"Electronics", "photo" :null, "modified" :" :43:03", "created" :" :19:26" "id" :2, "company_id":1, "name" :"Books", "photo" :null, "modified" :" :43:03", "created" :" :19:26" 20

21 View URL: /api/json/items/:canonical_id/ Method: GET Arguments id: integer (optional) used to retrieve the item by id instead of canonical_id curl HTTP/ OK Content-Type: application/json; charset=utf-8 "id" :1, "company_id" :1, "created_by_id" :2, "tax_rate_id" :1, "canonical_id" :1, "version" :"current", "name" :"A New Item", "price" :3.99, "sku" :null, "note" :null, "photo" :" "retired" :false, "favorite" :false, "use_default_tax" :false, "recurring" :false, "recurring_schedule":null, "recurring_payments":null, "modified" :" :43:03", "created" :" :43:00", "tax_rate" : "id" :1, "company_id":1, "name" :"Illinois State Tax", "amount" :6.25, "modified" :" :19:26", "created" :" :19:26" }, "categories" :[ "id" :1, "company_id":1, "name" :"Electronics", "photo" :null, "modified" :" :43:03", 21

22 } ] }, } "created" :" :19:26" "id" :2, "company_id":1, "name" :"Books", "photo" :null, "modified" :" :43:03", "created" :" :19:26" 22

23 Update URL: /api/json/items/1/ Method: POST Arguments name: string price: float category_ids: integer list tax_rate_id: integer sku: string photo: file note: string retired: true favorite: boolean use_default_tax: boolean recurring: boolean recurring_schedule: string curl \ -d "name=my EBook" HTTP/ OK Content-Type: application/json; charset=utf-8 "id" :2, "company_id" :1, "created_by_id" :2, "tax_rate_id" :1, "canonical_id" :1, "version" :"current", "name" :"My EBook", "price" :3.99, "sku" :null, "note" :null, "photo" :" "retired" :false, "favorite" :false, "use_default_tax" :false, "recurring" :false, "recurring_schedule":null, "recurring_payments":null, "modified" :" :43:03", "created" :" :43:00", "tax_rate" : "id" :1, "company_id":1, "name" :"Illinois State Tax", "amount" :6.25, 23

24 } "modified" :" :19:26", "created" :" :19:26" }, "categories" :[ "id" :1, "company_id":1, "name" :"Electronics", ] }, } "photo" :null, "modified" :" :43:03", "created" :" :19:26" "id" :2, "company_id":1, "name" :"Books", "photo" :null, "modified" :" :43:03", "created" :" :19:26" 24

25 Transactions API Endpoints List, Filter, Search Create View Update Photo Signature Receipt 25

26 List, Filter, Search URL: /api/json/transactions/ Method: GET Arguments (optional) amount: integer - Number of results to return contains: integer - Offset amount search: string tax_exempt: boolean tips: boolean recurring: boolean discounted: boolean date_min: date date_max: date price_min: float price_max: float cashier_id: integer curl HTTP/ OK Content-Type: application/json; charset=utf-8 [ "id" : 1, "company_id" : 1, "user_id" : 1, "token" : " ", "custom_id" : null, " " : null, "discount" : 7, "discount_description": "Discount", "item_total" : null, "subtotal" : 549, "tip" : 3, "tax" : null, "total" : 9160, "item_count" : 6, "tender_type" : "CARD", "latitude" : , "longitude" : , "city" : "Hindeloopen", "state" : "Fr", 26

27 ] } "note" : "Aliquam erat volutpat. Nulla dignissim.maecenas", "tax_exempt" : true, "billing_name" : "Cade Fowler", "billing_address_1" : " Metus. Ave", "billing_address_2" : null, "billing_city" : "Hindeloopen", "billing_state" : "Fr", "billing_zip_code" : "22774", "card_brand" : "Visa", "card_last4" : 8852, "card_expiration" : "0114", "recurring" : false, "recurring_status" : null, "recurring_token" : null, "recurring_schedule" : "MONTHLY_1", "recurring_start_date": null, "recurring_cancelled" : false, "refund_token" : null, "refund_amount" : null, "refund_reason" : null, "photo" : null, "signature" : null, "modified" : " :00:00", "created" : " :00:00", "line_items" : [ "id" : 2, "transaction_id": 2, "item_id" : 1, "canonical_id" : 1, "quantity" : 10, "tax_rate" : null, "modified" : " :19:32", "created" : " :19:32" } ] 27

28 Create URL: /api/json/transactions/ Method: POST Arguments token: integer (Bluefin Transaction ID) subtotal: float discount: float tip: float total: float (REQUIRED) tender_type: string (CARD, MANUAL, ACH, EBT, GIFT, CASH) status: string latitude: float (11, 8) longitude: float (11, 8) note: string tax_exempt: boolean billing_name: string billing_address_1: string, billing_address_2: string, billing_city: string, billing_state: string, billing_zip_code: string, card_last4: integer, recurring: boolean, recurring_schedule: string (MONTHLY_1, MONTHLY_2,...), photo: file, signature: file, line_items[0][item_id]: integer line_items[0][canonical_id]: integer line_items[0][quantity]: integer line_items[0][tax_rate]: float line_items[1][name]: string line_items[1][price]: float line_items[1][quantity]: integer line_items[1][tax_rate]: float curl \ -F "token=402732" \ -F "subtotal=100" \ -F "discount=10" \ -F "tip=14.7" \ -F "total=112.70" \ -F "photo=@file.jpg" \ -F "signature=@file.jpg" \ -F "line_items[0][item_id]=1" \ -F "line_items[0][canonical_id]=1" \ -F "line_items[0][quantity]=10" \ -F "line_items[1][name]=custom Item" \ -F "line_items[1][price]=12.34" \ -F "line_items[1][notes]=this is a custom item" \ 28

29 -F HTTP/ Created Content-Type: application/json; charset=utf-8 Location: /api/json/transactions/2/ "id": 2, "company_id": 1, "user_id": 12, "token": , "subtotal": 100, "discount": 10, "tip": 14.7, "total": , "tender_type": null, "latitude": null, "longitude": null, "note": null, "tax_exempt": false, "billing_name": null, "billing_address_1": null, "billing_address_2": null, "billing_city": null, "billing_state": null, "billing_zip_code": null, "card_last4": null, "recurring": null, "recurring_schedule": null, "photo": file.jpg, "signature": file.jpg, "modified": " :19:32", "created": " :19:32", "line_items":[ "id": 1, "transaction_id": 1, "item_id": 1, "canonical_id": 1, "quantity": 10, "tax_rate": null, "modified": " :19:32", "created": " :19:32" } ] } View 29

30 URL: /api/json/transactions/ Method: GET curl HTTP/ OK Content-Type: application/json; charset=utf-8 "id": 1, "company_id": 1, "user_id": 12, "subtotal": 100, "discount": 10, "tip": 14.7, "total": 112.7, "tender_type": null, "latitude": null, "longitude": null, "note": null, "tax_exempt": false, "billing_name": null, "billing_address_1": null, "billing_address_2": null, "billing_city": null, "billing_state": null, "billing_zip_code": null, "card_last4": null, "recurring": null, "recurring_schedule": null, "photo": " "signature": " "modified": " :35:52", "created": " :35:52", "line_items": [ "id": 1, "transaction_id": 1, "item_id": 1, "canonical_id": 1, "quantity": 10, "tax_rate": null, "modified": " :35:52", "created": " :35:52" } ] 30

31 } 31

32 Receipt URL: /api/json/transactions/1/receipt Method: POST Arguments string (required) curl \ -d " =support@bluefin.com" HTTP/ OK Content-Type: application/json; charset=utf-8 32

33 Refund URL: /api/json/transactions/1/refund Method: POST Arguments refund_amount: float line_item_ids: array curl \ -d "refund_amount=1" \ -d "line_items[]=1" \ -d "line_items[]=2" HTTP/ OK Content-Type: application/json; charset=utf-8 "id": 1, "company_id": 1, "user_id": 12, "subtotal": 100, "discount": 10, "tip": 14.7, "total": 112.7, "tender_type": null, "latitude": null, "longitude": null, "note": null, "tax_exempt": false, "billing_name": null, "billing_address_1": null, "billing_address_2": null, "billing_city": null, "billing_state": null, "billing_zip_code": null, "card_last4": null, "recurring": null, "recurring_schedule": null, "photo": " "signature": " "modified": " :35:52", "created": " :35:52", "line_items": [ 33

34 } ] }, } "id": 1, "transaction_id": 1, "item_id": 1, "canonical_id": 1, "quantity": 10, "tax_rate": null, "modified": " :35:52", "created": " :35:52" "id": 1, "transaction_id": 1, "quantity": 1, "price": -1.99, "tax_rate": null, "modified": " :35:52", "created": " :35:52" 34

35 Tax Rates API Endpoints List Create View Update Delete 35

36 List URL: /api/json/tax-rates/ Method: GET Arguments (optional) amount: contains: integer - Number of results to return integer - Offset amount curl HTTP/ OK Content-Type: application/json; charset=utf-8 [ ] } "id": 1, "company_id": 1, "name": "State Tax", "amount": 7.25, "modified": " :07:24", "created": " :07:24" 36

37 Create URL: /api/json/tax-rates/ Method: POST Arguments name: string (required) amount: decimal (required) curl \ -d "name=state Tax" \ -d "amount=7.25" \ HTTP/ Created Content-Type: application/json; charset=utf-8 Location: /api/json/tax-rates/1/ } "id": 1, "company_id": 1, "name": "State Tax", "amount": 7.25, "modified": " :38:01", "created": " :38:01" 37

38 View URL: /api/json/tax-rates/1/ Method: GET curl HTTP/ OK Content-Type: application/json; charset=utf-8 } "id": 1, "company_id": 1, "name": "State Tax", "amount": 6.25, "modified": " :38:01", "created": " :38:01" 38

39 Update URL: /api/json/tax-rates/1/ Method: POST Arguments name: amount: retired: string decimal boolean curl \ -d "name=state Tax" \ -d "amount=6.25" HTTP/ OK Content-Type: application/json; charset=utf-8 } "id": 1, "company_id": 1, "name": "State Tax", "amount": 6.25, "modified": " :38:01", "created": " :38:01" 39

40 Delete URL: /api/json/tax-rates/1/ Method: DELETE curl \ -X DELETE HTTP/ No Content 40

41 Categories Endpoints List Create View Update Delete 41

42 List URL: /api/json/categories/ Method: GET Arguments (optional) amount: contains: integer - Number of results to return integer - Offset amount curl HTTP/ OK Content-Type: application/json; charset=utf-8 [ ] } "id": 1, "company_id": 1, "name": "Shoes", "photo": " "modified": " :11:21", "created": " :11:21" 42

43 Create URL: /api/json/categories/ Method: POST Arguments name: string (required) photo: file curl \ -F "name=shoes" \ -F "photo=@file.jpg" HTTP/ Created Content-Type: application/json; charset=utf-8 Location: /api/json/categories/1/ } "id": 3, "company_id": 1, "name": "Shoes", "photo": " "modified": " :20:56", "created": " :20:56", 43

44 View URL: /api/json/categories/1/ Method: GET curl HTTP/ OK Content-Type: application/json; charset=utf-8 } "id": 1, "company_id": 1, "name": "Shoes", "photo": " "modified": " :11:21", "created": " :11:21" 44

45 Update URL: /api/json/categories/1/ Method: POST curl \ -F "name=shoes" \ -F "photo=@file" HTTP/ OK Content-Type: application/json; charset=utf-8 } "id": 1, "company_id": 1, "name": "Shoes", "photo": " "modified": " :11:21", "created": " :11:21" 45

46 Delete URL: /api/json/categories/1/ Method: DELETE curl \ -X DELETE HTTP/ No Content 46

47 Settings Endpoints View Update 47

48 View URL: /api/json/settings/ Method: GET curl HTTP/ OK Content-Type: application/json; charset=utf-8 "id" : 1, "retired" : false, "name" : "Bluefin Payment Systems", " " : "inquiries@bluefin.com", "color" : "A4C53F", "phone" : " ", "address_1" : "314 West Superior Street", "address_2" : "Suite 501", "city" : "Chicago", "state" : "IL", "zip_code" : "60654", "time_zone" : "America\/Chicago", "logo" : null, "website" : " "facebook" : " Systems/ ", "twitter" : "BluefinPayments", "postback" : " "api_account_id" : "", "api_access_key" : "", "card_processor" : null, "merchant_number" : null, "terminal_number" : null, "industry_type" : null, "default_tax_rate" : 9.25, "tip_1" : 10, "tip_2" : 15, "tip_3" : 20, "allow_taxes" : false, "allow_tips" : false, "allow_refunds" : false, "require_zip_code" : false, "use_terminal_view": false, "modified" : " :43:35", "created" : " :43:35" 48

49 } 49

50 Update URL: /api/json/settings/ Method: POST curl \ -F "logo=@file.jpg" \ -F "color=#111111" HTTP/ OK Content-Type: application/json; charset=utf-8 "id" : 1, "retired" : false, "name" : "Bluefin Payment Systems", " " : "inquiries@bluefin.com", "color" : "A4C53F", "phone" : " ", "address_1" : "314 West Superior Street", "address_2" : "Suite 501", "city" : "Chicago", "state" : "IL", "zip_code" : "60654", "time_zone" : "America\/Chicago", "logo" : " "website" : " "facebook" : " Systems/ ", "twitter" : "BluefinPayments", "postback" : " "api_account_id" : "", "api_access_key" : "", "card_processor" : null, "merchant_number" : null, "terminal_number" : null, "industry_type" : null, "default_tax_rate" : 9.25, "tip_1" : 10, "tip_2" : 15, "tip_3" : 20, "allow_taxes" : false, "allow_tips" : false, "allow_refunds" : false, "require_zip_code" : false, "use_terminal_view": false, 50

51 } "modified" : " :43:35", "created" : " :43:35" 51

52 Misc Error Messages "error": "Error message"} 52