Rest API Справочник контрагентов - datawizio/pythonAPI GitHub Wiki

Контрагенты - это справочник всех контрагентов, с которыми были или ведутся торговые отношения. С помощью ресурса /contractors/ можно получить доступ к списку контрагентов. А также добавлять в справочник новых контрагентов

Для управления ресурсом /contractors/ поддерживаются следующие команды:

• GET - получить одну страницу коллекции
• POST - загрузить информацию о контрагента
• OPTIONS - мета-информация по структуре объекта
• HEAD - аналог GET, но возвращается только заголовок ответа

Вид команды: GET http://api.datawiz.io/api/v1/contractors

• .json - получить ответ с сервера в формате JSON
• .api - получить ответ с сервера в формате HTML (тестовая платформа)

• format = json | api - аналог вышеуказанных суффиксов
• page_size = nn - установить размер страницы равен nn объектов
• page = n - загрузить страницу n
• search = text - отображать только объекты, в поле name, где найдено "text"
• ordering = name | identifier - сортировать по полю в алфавитном порядке (от меньшего - к большему)
• ordering = -name | -identifier - сортировать по полю в обратном порядке

Объект "коллекция" состоит из четырех полей (count, next, previous, results).

Пример пустой коллекции, полученной в результате запроса:

GET http://api.datawiz.io/api/v1/contractors/.json/?search=unknown-string

{
     "count": 0,
     "next": null,
     "previous": null,
     "results": [] 
}

Пример коллекции из 2-х элементов: GET http://api.datawiz.io/api/v1/contractors/?format=api&page_size=2:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
    "count": 11, 
    "next": "http://api.datawiz.io/api/v1/contractors/?page=2&page_size=2&format=api", 
    "previous": null, 
    "results": [
        {
            "contractor_id": "contractor-1",
            "name": "Vasya",
            "phone": null,
            "address": null
        }, 
        {
            "contractor_id": "contractor-2",
            "name": "Roma",
            "phone": null,
            "address": null
        }
    ]
}

В случае ошибки сервер возвращает ответ с соответствующим статусом, а также сообщением об ошибке, записанным в ключе detail и / или в поле http.response.content:

HTTP 404 NOT FOUND 
Content-Type: application/json 
Vary: Accept 
Allow: GET, HEAD, OPTIONS, PATCH 
{
"detail": "Not found"
}

Вид команды: POST http://api.datawiz.io/api/v1/contractors/?format=json

• .json - получить ответ с сервера в формате JSON
• .api - получить ответ с сервера в формате HTML (тестовая платформа)

• format = json | api - аналог вышеуказанных суффиксов

Данные запроса:

В запросе передается JSON-объект типа словарь (dictionary), который описывает информацию о контрагенте. Важные поля: contractor_id, name. Последовательность полей не принципиальна.

Пример запроса на загрузку информации об контрагента товара: POST http://api.datawiz.io/api/v1/suppliers/.json

{
    "contractor_id": "contractor-1",
    "name": "Vasya",
    "phone": null,
    "address": null
}

При корректной обработке запроса сервер возвращает код статуса 201 и статус создания объекта.

Пример ответа сервера:

HTTP 201 CREATED
Content-Type: application/json
Vary: Accept
Location: http://api.datawiz.io/api/v1/contractors/124/
Allow: GET, POST, HEAD, OPTIONS
{
"updated": 0,
"inserted": 1
}

• Если объект с идентификатором contractor_id уже существует на сервере, то указанный запрос заменит объект на сервере (replace) без предупреждения.
• Нельзя добавить на сервер объект, если нет товара с указанным идентификатором contractor_id

В случае ошибки сервер возвращает ответ с соответствующим статусом, а также сообщением об ошибке, записанным напротив имени поля, с которым эта ошибка связана. Если ошибка касается не отдельного поля, а всего объекта, то сообщение об ошибке будет записано напротив ключа non_field_errors.

ПРИМЕЧАНИЕ. Каждое сообщение об ошибке представляет собой коллекцию (массив) строчных символов.

Пример ответа сервера при возникновении ошибки (поле name передано пустым):

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
     "name": [
         "This field is required." 
     ] 
}

При выполнении данной команды возвращается такая JSON-структура:

OPTIONS /api/v1/contractors/

HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
{
"name": "Сontractor List",
"description": "this is my text. You can see this text on the REST-page",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
],
"actions": {
"POST": {
"contractor_id": {
"type": "string",
"required": true,
"read_only": false,
"label": "Сontractor id",
"max_length": 12
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "Name",
"max_length": 200
},
"phone": {
"type": "string",
"required": false,
"read_only": false,
"label": "Phone",
"max_length": 25
},
"address": {
"type": "string",
"required": false,
"read_only": false,
"label": "Address",
"max_length": 50
}
}
}
}