Общие положения

API для работы с документами в виджете Dokker. Перед тем как его использовать для какого-либо аккаунта amoCRM (Kommo) требуется установить сам виджет из маркета.

Точка входа запросов: https://dokker.amocrm.catcode.io/api/v1/

Авторизация

Для авторизации требуется получить секретный токен, отправив запрос на почту support@catcode.io, где необходимо указать ID аккаунта, название виджета и причину использования API.

Подпись запросов происходит с помощью Basic-авторизации в Authorization-заголовке. Необходимо передать закодированную в base64 строку вида <platform>:<account_id>:<token>, где:

  • platform – одна из двух платформ: amocrm или kommo;
  • account_id – ID аккаунта amoCRM или Kommo;
  • token – токен для аккаунта выданный по запросу.

В конечном итоге заголовок должен быть примерно следующим: Authorization: Basic MjE3Nzg0MT36ZThhMGQzNDdlMzYzOTY5YTViN6k0OGMxYg==

Формат ответа

Все ответы возвращаются в JSON-формате в соответствии с JSend, где обязательно присутствуют следующие ключи:

  1. status – результирующий статус работы запроса:
  • success – запрос валидный, обработан успешно и в процессе не возникло ошибок. Данные результата в data.
  • fail – обязательные поля не заполнены или содержат некорректные данные. В data массив полей со списками допущенных ошибок.
  • error – в процессе обработки запроса возникла ошибка по вине некорректного запроса или ошибки на сервере. В data поясняющий текст.
  1. data – результат запроса, формат которого зависит от статуса выше.

Другими словами, по полю status можно определять как работать с полем data. При этом HTTP-статус ответа зависит от серьёзности ошибки и может использоваться для определения проблемной стороны.

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

  • Успешный ответ 200 OK

    {
        "status": "success",
        "data": {
            ...
        }
    }
    
  • Переданы невалидные параметры 400 Bad Request

    {
        "status": "fail",
        "data": {
            "date_to": [
                "Это значение не является допустимой датой."
            ]
        }
    }
    
  • Ошибка авторизации 401 Unauthorized

    {
        "status": "error",
        "data": "Неавторизованный вызов, проверьте заголовок Authorization"
    }
    
  • Ошибка сервера 500 Internal Server Error

    {
        "status": "error",
        "data": "Запрос выполнить не удалось, обратитесь в поддержку"
    }
    
  • Также могут и другие типы ответов уникальные для конкретного метода (см. подробнее в описании таких методов).