Работа с AmoCRM на Python

1. Переходим в amoМаркет -> жмем на три точки-> Создать интеграцию

2. Выбираем «Внешняя интеграция». Второй подход, по всей видимости, становится наиболее релевантным, если вашей целью является создание интеграции, которой смогут успешно пользоваться и другие пользователи.

3. Давайте остановимся на полях, которые необходимо запомнить.

5. Заходим в раздел установленные, и видим, что наша интеграция отключена. Давайте включим ее.

Для этого заходим в нашу интеграцию и нажимаем «Отключить» (Я уже нажал). У Вас появится чекбокс и кнопка “Установить”, принимаем условия и нажимам “Установить”.

На этом первичная настройка завершена, у вас должно быть написано «Установлено», как на скриншоте ниже.

1. Начнем с импортирования необходимых библиотек в проект. В случае, если какая-либо библиотека отсутствует, выполните ее установку с помощью pip. На данном этапе мы не будем подробно останавливаться.

import dotenv
import jwt
import requests
from datetime import datetime
import time
import logging
from requests.exceptions import JSONDecodeError
from justcode.settings import BASE_DIR
from dotenv import load_dotenv
import os
                            

2. Так как токены являются важной конфиденциальной информацией, их хранение должно происходить в соответствии с «best practices» безопасности. Я выбрал для себя вариант хранения в .env файле. Если вы ранее не сталкивались с .env, рекомендую ознакомиться с соответствующим материалом: https://pypi.org/project/python-dotenv/

3. Инициализируем .env

dotenv_path = os.path.join(“Ваш путь до файла”, ".env")
load_dotenv(dotenv_path=dotenv_path)
load_dotenv()
                            

4. Создаем сам файл .env, со следующей структурой

AMOCRM_SUBDOMAIN=вставляем «Ссылку для перенаправления» из настроек интеграции, вы задали это при создании интеграции
AMOCRM_CLIENT_ID=вставляем «ID интеграции» из настроек интеграции
AMOCRM_CLIENT_SECRET=вставляем «Секретный ключ» из настроек интеграции
AMOCRM_REDIRECT_URL=https://ваш url из настроек, которые вы зада.kz
AMOCRM_ACCESS_TOKEN='' 
AMOCRM_REFRESH_TOKEN=''
                            

В основном файле, где вы работаете над интеграцией, добавляется следующий код:

subdomain = os.getenv("AMOCRM_SUBDOMAIN")
client_id = os.getenv("AMOCRM_CLIENT_ID")
client_secret = os.getenv("AMOCRM_CLIENT_SECRET")
redirect_uri = os.getenv("AMOCRM_REDIRECT_URL")
secret_code = "Сюда как раз вставляем Код авторизации из настроек, ключ который живет только 20 минут"
                            

Затем создаем четыре функции:

1. _is_expire – функция, которая принимает access_token и проверяет его актуальность (действителен ли он или уже прошло более 24 часов).
2. _save_tokens – функция, которая принимает два токена и сохраняет их в .env файл
3. Два геттера _get_refresh_token и _get_access_token, для получения токенов из .env файла

def _is_expire(token: str):
    token_data = jwt.decode(token, options={"verify_signature": False})
    exp = datetime.utcfromtimestamp(token_data["exp"])
    now = datetime.utcnow()

    return now >= exp


def _save_tokens(access_token: str, refresh_token: str):
    # Записываем в ключи .env
    os.environ["AMOCRM_ACCESS_TOKEN"] = access_token
    os.environ["AMOCRM_REFRESH_TOKEN"] = refresh_token
    dotenv.set_key(dotenv_path, "AMOCRM_ACCESS_TOKEN", os.environ["AMOCRM_ACCESS_TOKEN"])
    dotenv.set_key(dotenv_path, "AMOCRM_REFRESH_TOKEN", os.environ["AMOCRM_REFRESH_TOKEN"])


def _get_refresh_token():
    return os.getenv("AMOCRM_REFRESH_TOKEN")


def _get_access_token():
    return os.getenv("AMOCRM_ACCESS_TOKEN")
                            

В переменную data добавляем client_id, client_secret, secret_code, redirect_uri, которые мы инициализировали ранее (см. пункт 5). Затем с помощью библиотеки requests отправляем запрос на сервер, получаем из ответа токены и с помощью функции _save_tokens сохраняем их.

class AmoCRMWrapper:
    def init_oauth2(self):
        data = {
            "client_id": client_id,
            "client_secret": client_secret,
            "grant_type": "authorization_code",
            "code": secret_code,
            "redirect_uri": redirect_uri
        }

        response = requests.post("https://{}.amocrm.ru/oauth2/access_token".format(subdomain), json=data).json()
        print(response)
        access_token = response["access_token"]
        refresh_token = response["refresh_token"]

        _save_tokens(access_token, refresh_token)
                        

Теперь нам нужно создать экземпляр класса AmoCRMWrapper и вызвать метод init_oauth2().

amocrm_wrapper_1 = AmoCRMWrapper() 

amocrm_wrapper_1.init_oauth2()
                        

Для начала, создадим функцию, которая будет получать новую пару токенов при истечении срока действия access_token (то есть, если прошло более 24 часов с момента его получения) и сохранять их в .env файл.

Согласно документации, отправляем запрос на получение новой пары токенов.

def _get_new_tokens():
    data = {
            "client_id": client_id,
            "client_secret": client_secret,
            "grant_type": "refresh_token",
            "refresh_token": _get_refresh_token(),
            "redirect_uri": redirect_uri
    }
    response = requests.post("https://{}.amocrm.ru/oauth2/access_token".format(subdomain), json=data).json()
    access_token = response["access_token"]
    refresh_token = response["refresh_token"]

    _save_tokens(access_token, refresh_token)
                        

Теперь дополним наш класс AmoCRMWrapper методом _base_request. Этот метод будет использоваться для отправки запросов к API.

def _base_request(self, **kwargs):
    if _is_expire(_get_access_token()):
        _get_new_tokens()

    access_token = "Bearer " + _get_access_token()

    headers = {"Authorization": access_token}
    req_type = kwargs.get("type")
    response = ""
    if req_type == "get":
        try:
            response = requests.get("https://{}.amocrm.ru{}".format(
                subdomain, kwargs.get("endpoint")), headers=headers).json()
        except JSONDecodeError as e:
            logging.exception(e)

    elif req_type == "get_param":
        url = "https://{}.amocrm.ru{}?{}".format(
            subdomain,
            kwargs.get("endpoint"), kwargs.get("parameters"))
        response = requests.get(str(url), headers=headers).json()
    elif req_type == "post":
        response = requests.post("https://{}.amocrm.ru{}".format(
            subdomain,
            kwargs.get("endpoint")), headers=headers, json=kwargs.get("data")).json()
    return response
                        

Мы реализуем этот запрос в нашем классе AmoCRMWrapper добавлением метода get_lead_by_id. Этот метод будет принимать lead_id в качестве параметра, затем формировать URL, и отправлять запрос с помощью метода _base_request.

def get_lead_by_id(self, lead_id):
    url = "/api/v4/leads/" + str(lead_id)
    return self._base_request(endpoint=url, type="get")
                        

Где взять ID-cделки?
Для этого перейдите к любой сделке в вашем аккаунте AmoCRM - ID сделки отображается в URL страницы сделки. AmoCRM Cкриншот что такое ID ниже:

Пример кода:

if __name__ == "__main__":
    amocrm_wrapper_1 = AmoCRMWrapper()

    print(amocrm_wrapper_1.get_lead_by_id(12879113))
                        

Пример вывода:

Код функции:

def set_task(self, lead_id, responsible_user_id):
    data = [
        {
            "task_type_id": 1,
            "text": "Повторная заявка, необходимо связаться",
            "complete_till": 0,
            "entity_id": lead_id,
            "entity_type": "leads",
            "responsible_user_id": responsible_user_id,
        }
    ]

    response = self._base_request(endpoint="/api/v4/tasks", type="post", data=data)
    return response
                        

Давайте воспользуемся нашим методом:
1. В переменную lead сохраним объект “Лида” полученного от API с помощью метода get_lead_by_id.
2. Вызываем метод set_task с передачей ID-сделки и ID ответственного пользователя (в объекте lead можно обратиться по ключу responsible_user_id)

Код функции:

if __name__ == "__main__":
    amocrm_wrapper_1 = AmoCRMWrapper()

    lead = amocrm_wrapper_1.get_lead_by_id(12879113)

    amocrm_wrapper_1.set_task(lead_id=12879113,
responsible_user_id=lead.get('responsible_user_id'))
                            

Заходим в сделку в AmoCRM и проверяем сохранилась ли задача. Должно выглядеть примерно так:

Скриншот моих полей для сделок ниже:

Иллюстрируя на примере с ID для пользовательского поля utm_content, следует учесть, что ID для каждого аккаунта уникальны. Это означает, что вам придется вручную собирать ID, которые вы планируете использовать при добавлении сделки. Я уверен, что вы справитесь с этой задачей без проблем.

Что касается конкретных полей в переменной data, их подробное описание можно найти в официальной документации по добавлению сделок в раздел "неразобранное". Ссылка на эту документацию была предоставлена ранее.

def add_unsorted_lead(self, **kwargs):
    data = [
        {
            "source_name": kwargs.get("lead_name"),
            "source_uid": "1",
            "_embedded": {
                "leads": [
                    {
                        "name": kwargs.get("form_lead_name"),
                        "custom_fields_values": [
                            {
                                # utm_content
                                "field_id": 92773,
                                "values": [
                                    {
                                        "value": kwargs.get("form_utm_content")
                                    }
                                ]
                            },
                            {
                                # utm_medium
                                "field_id": 92775,
                                "values": [
                                    {
                                        "value": kwargs.get("form_utm_medium")
                                    }
                                ]
                            },
                            {
                                # utm_campaign
                                "field_id": 92777,
                                "values": [
                                    {
                                        "value": kwargs.get("form_utm_campaign")
                                    }
                                ]
                            },
                            {
                                # utm_source
                                "field_id": 92779,
                                "values": [
                                    {
                                        "value": kwargs.get("form_utm_source")
                                    }
                                ]
                            },
                            {
                                # utm_term
                                "field_id": 92781,
                                "values": [
                                    {
                                        "value": kwargs.get("form_utm_term")
                                    }
                                ]
                            },
                            {
                                # _ym_uid
                                "field_id": 92801,
                                "values": [
                                    {
                                        "value": kwargs.get("form_ym_uid")
                                    }
                                ]
                            },
                            {
                                # _ym_counter
                                "field_id": 92803,
                                "values": [
                                    {
                                        "value": kwargs.get("form_ym_counter")
                                    }
                                ]
                            },
                            {
                                # Страница
                                "field_id": 982883,
                                "values": [
                                    {
                                        "value": kwargs.get("form_page_name")
                                    }
                                ]
                            },
                            {
                                # Форма
                                "field_id": 1923211,
                                "values": [
                                    {
                                        "value": kwargs.get("form_form_name")
                                    }
                                ]
                            },

                        ],
                        "_embedded": {
                            "tags": [
                                {
                                    "name": "Сайт"
                                }
                            ]
                        }
                    }
                ],
                "contacts": [
                    {
                        "name": kwargs.get("form_lead_name"),
                        # "first_name": "first_name justcode_v2",
                        # "last_name": "surname justcode_v2",
                        "custom_fields_values": [
                            {
                                "field_code": "PHONE",
                                "values": [
                                    {
                                        "value": kwargs.get("form_phone")
                                    }
                                ]
                            },
                            {
                                "field_id": 1925337,
                                "values": [
                                    {
                                        "value": kwargs.get("message")
                                    }
                                ]
                            }
                        ]
                    }
                ],
                # "companies": [
                #     # {
                #     #     "name": "ОАО Коспромсервис"
                #     # }
                # ]
            },
            "metadata": {
                "ip": kwargs.get("ip_address"),
                "form_id": "test",
                "form_sent_at": int(time.time()),
                "form_name": kwargs.get("form_form_name"),
                "form_page": kwargs.get("form_page_name"),
                "referer": "https://justcode.kz"
            }
        }
    ]

    response = self._base_request(endpoint="/api/v4/leads/unsorted/forms", type="post", data=data)

    lead_id = response.get('_embedded').get('unsorted')[0].get("_embedded").get("leads")[0].get("id")

    # Ну или получать вот так :)
    # for key, value in response.items():
    #     if key == "_embedded":
    # for item_key, item_value in test.items():
    #     print(item_key, " ", item_value, "\n")
    #     for k, v in item_value[0].items():
    #         if k == "_embedded":
    #             for x, y in v.items():
    #                 if x == "leads":
    #                     for a, b in y[0].items():
    #                         if a == "id":
    #                             return b
    return lead_id