APP365提供的Open API是典型的RESTful API,让你能非常容易地将自己的应用与APP365进行集成; 你可以在应用程序中按照自己的需要查询或修改运单、车辆、车次、客户、司机、出入库信息、运输过程信息、跟踪信息、财务信息等; APP365 Open API采用JSON作为请求和响应的数据格式。
在你考虑自己创建与APP365集成的模块时,请先检查“插件工具”栏目中是否已经提供了相同的模块,以免重复劳动。
当前的APP365 Open API 仅支持HTTP Basic access authentication认证方式;API调用连接必须通过安全的HTTPS连接;证书信息由一个有效的用户名和其关联的API Key组成; 请参见下节的“启用 APP365 Open API”,以了解怎样获取一个API Key;在调用时,如果证书无效或者没有提供,服务器会返回“401未经授权”的响应。
要授权一个用户让其可以调用API,请按照下列步骤操作:
在角色模块中,配置指定角色能够存取的资源和可以执行的动作,让特定的角色只能访问与自己相关的资源和动作,保证系统数据的安全。 在调用API时,采用同样地策略来控制用户的访问权限,如果用户无权访问指定的资源,则会返回响应 “403 Forbidden”。
要调用APP365 API,你需要在执行请求时,设置Basic HTTP Authorization头部:username:api_key.
如果使用cURL工具,你可以采用下面两种方式之一请求登录授权:
通过"--user"参数构造登录授权的头部curl --user apiUsername:api_key
通过"--header"参数直接设置登录授权的头部curl --header "Authorization: Basic YWRtaW46WW91ckFQSUtleUhlcmU="
APP365 Open API采用JSON作为请求和响应的数据格式,API分为三种类型,查询数据、保存数据、删除数据:
查询数据
查找单条记录URL:http://biz.app365.com/bizweb/services/bizobjects
/m56.Barcode /* 实体模型id */ /{id}?fields=station_name,barcodes /* 记录id及其要查询返回的字段列表*/查询列表URL: http://biz.app365.com/bizweb/services/query
/ilms.LmsOrder.selectForList /* 要执行的SqlId */ /"o.name": 'lgh', "o.code": 'fff'/0,100 /* 查询条件参数,查询记录的offset limit*/完整的请求举例:
curl --request GET \ --header "Authorization: Basic YWRtaW46WW91ckFQSUtleUhlcmU=" \ http://biz.app365.com/bizweb/services/bizobjects/m56.Barcode/{id}?fields=station_name,barcodes curl --request GET \ --header "Authorization: Basic YWRtaW46WW91ckFQSUtleUhlcmU=" \ http://biz.app365.com/bizweb/services/query/ilms.LmsOrder.selectForList/ \ "o.name": 'lgh', "o.code": 'fff'/0,100保存数据
保存整个对象的URL: http://biz.app365.com/bizweb/services/bizobjects/m56.Barcode/,同时post一个json对象
更新几个字段的URL:http://biz.app365.com/bizweb/services/bizobjects/m56.Barcode/{id},同时post一个json对象
完整的请求举例:
curl http://biz.app365.com/bizweb/services/bizobjects/m56.Barcode/ -H "Content-Type: application/json" -d @barcode.json -H "Authorization: Basic YWRtaW46WW91ckFQSUtleUhlcmU="APP365 API根据请求的结果,返回相应的HTTP状态代码。根据HTTP的规定,响应按照下列状态码性质被分成几大类。出错的响应中也同时包含了一个错误消息在响应的body中,你可以根据这个消息判断和解决问题。
Code | Definition | Purpose |
---|---|---|
200 | OK | For successful GET/PUT requests. |
201 | Created | For a successful POST request. |
202 | Accepted | For a request that resulted in a scheduled task being created to perform the actual request. |
204 |
No Content |
For a successful request that produced no response (such as DELETE requests). |
Code | Definition | Purpose |
---|---|---|
301 | Moved Permanently | When the API routes have changed (unlikely) or if the incoming request is not secure (http) then it will be redirect to the secure (https) version. |
302 |
Found |
When the resource was found at a different location. When a request to a deprecated version of the API is received, a 302 Found response will be issued to the current API version. |
304 |
Not Modified |
If an If-Modified-Since header is sent in the request and the resource has not been modified since the specified date, then this response will be sent. NB. See resource specific pages for support for the If-Modified-Since header. |
Code | Definition | Purpose |
---|---|---|
400 |
Bad Request |
Issued when a malformed request was sent. Such as due to invalid syntax or missing required data. |
401 |
Unauthorized |
This response is sent when either the clients credentials are not provided or are incorrect. |
403 |
Forbidden |
When the user doesn't have permission to perform a specific operation on a resource (eg. edit a product). Permissions can be set through the store control panel. |
404 | Not Found | When a particular resource doesn't exist or couldn't be found. |
405 |
Method Not Allowed |
The resource was found, but doesn't support the request method. Issued when either a specific method isn't yet implemented on a resource, or the resource doesn't support the method at all (eg. PUT on /orders is invalid, but PUT on /orders/{id} is valid). |
406 |
Not Acceptable |
When the client specifies a response content type in the Accept header that is not supported. |
409 | Conflict | A change requested by the client is being rejected due to a condition imposed by the server. The exact reasons response for this will vary from one resource to the next. Examples may include attempting to delete a Category which would result in Products being orphaned. Additional information about the conflict and how to resolve it may be available in the details section of the response. |
413 |
Request Entity Too Large |
When the client requests too many objects. eg. the limit parameter was above the maximum allowed. |
415 |
Unsupported Media Type |
When the client specifies a content type in the Content-Type header that is not supported by the API. |
Code | Definition | Purpose |
---|---|---|
500 | Internal Server Error | When an error has occurred within the API. |
501 | Not Implemented | When a request method is sent that is not supported by the API (eg. TRACE, PATCH). |
503 |
Service Unavailable |
When the store is marked as "Down for Maintenance" or the store is being upgraded to a new version. |
507 |
Insufficient Storage |
When the store has reached a limitation for the resource according to their BigCommerce plan (eg 500 product limit). |
509 |
Bandwidth Limit Exceeded |
When the requests-per-hour limitations for the API have been reached. |