API-метод создания сделок

Содержание

Запрос

POST: https://api.calltouch.ru/lead-service/v1/api/client-order/create

HTTP-заголовки:

• Access-Token – API-ключ
• SiteId – ID ЛК Calltouch

Тело запроса в формате JSON:

{
    "crm": "Название CRM",
    "orders": [

     // Сделка 1
    
        {
            "matching": [
                {
                    "type": "request",
                    "requestParams": {
                        "requestId": 1,
                        "tags": ["тег1", "тег2"],
                        "tagsLogic": "and"
                    }
                },
                {
                    "type": "call",
                    "callParams": {
                        "callId": 2 ,
                        "tags": ["тег"],
                        "tagsLogic": "and"
                    }
                },
                {
                    "type": "requestContact",
                    "requestContactParams": {
                        "emails": ["name@server.com"],
                        "phones": ["79157771122", "+7 (915) 888-11-22"],
                        "md5Phones": ["4fec00b25336e719d4a0b255ea5aa0f5"],
                        "date": "Дата и время заявки",
                        "tags": ["тег"],
                        "tagsLogic": "and",
                        "requestTypeToMatch": "nearestUniq",
                        "searchDepth": 262800
                    }
                },
                {
                    "type": "callContact",
                    "callContactParams": {
                        "phones": ["84953338877"],
                        "md5Phones": ["4fec00b25336e719d4a0b255ea5aa0f5"],
                        "date": "Дата и время звонка",
                        "tags": ["тег"],
                        "tagsLogic": "and",
                        "callTypeToMatch": "nearestUniq",
                        "searchDepth": 262800
                        }
                },
                {
                    "type": "call",
                    "callParams": {
                        "callId": 2,
                        "tags": ["тег"],
                        "tagsLogic": "and"
                    }
                },
                {
                    "type": "customSources",
                    "customSourceParams": {
                        "source": "Произвольный источник",
                        "medium": "Произвольный канал",
                        "campaign": "Произвольная кампания",
                        "content": "Произвольное объявление",
                        "term": "Произвольная ключевая фраза"
                    }
                },
                {
                    "type": "withoutSource"
                }
            ],
        "orderNumber": "ID сделки 1 внутри CRM",
        "funnel": "Название воронки",
        "status": "Название статуса",
        "statusDate": "Дата и время установки текущего статуса сделки",
        "orderDate": "Дата и время создания сделки",
        "currency": "rub",
        "revenue": "100000.50",
        "margin": "100.50",
        "orderLink": "https://site.ru/crm/deal/123/",
        "orderName": "Название сделки",
        "manager": "ФИО продавца",
        "comment": {
            "text": "Комментарий к сделке"
            },
        "addTags": [
            {"tag": "Тег 1"},
            {"tag": "Тег 2"},
            {"tag": "Тег N"}
            ],
        "addTagsToLead": {
                "tags": [
                    {
                        "tag": "Тег 1"
                    },
                    {
                        "tag": "Тег 2"
                    }
            ],
                "overwrite": true
            },
        "customFields": [
            {"field": "grossprofit", "value": "456.50"},
            {"field": "name", "value": "123"}
            ],
        "products": [
            {
                "name": "Табурет",
                "price": "500.25",
                "brand": "ikea",
                "category": "Столы, стулья",
                "variant": "Черный",
                "quantity": 10
            },
            {
                "name": "Стол",
                "price": "1500"
            }]
        }

     // Сделка N

        ...
    ]
}

Комментарии через // следует убрать из запроса перед его выполнением.

Параметры запроса

Ответ

Процесс матчинга запускается сразу же после отправки запроса, после чего сразу же возвращается и ответ, пример:

{
    "meta": [],
    "data": {
        "orders": [
            {
                "orderNumber": "UdvPC9bBjjLnEJ9R",
                "calltouchOrderId": 2396375,
                "matchedType": "request",
                "created": true,
                "callInfo": null,
                "requestInfo": {
                    "requestId": 1257513,
                    "requestNumber": "1257513"
                },
                "customSources": null,
                "error": null
            }
        ]
    }
}

Если API-токен не указан, то матчинг не выполняется и выводится ошибка:

{
    "meta": [],
    "data": {
        "message": "Ошибка доступа"
    }
}

Если API-токен указан не верно, то матчинг не выполняется и выводится ошибка:

{
    "message": "Access token не найден"
}

Параметры ответа

Если в запросе обнаруживаются ошибки валидации, то матчинг не выполняется и выводится ошибка:

{
    "meta": [],
    "data": {
        "type": "validationError",
        "apiErrorData": null,
        "validationErrorData": {
            "violations": [
                {
                    "fieldPath": "orders[0].statusDate",
                    "message": "Значение даты и времени недопустимо."
                }
            ]
        }
    }
}

Добавление пользовательских полей

В описанном выше методе вы можете использовать пользовательские поля для того, чтобы передать дополнительную информацию из вашей CRM-системы в личный кабинет Calltouch. Для того, чтобы создать такое поле в вашем личном кабинете, необходимо зайти в раздел «Интеграции –> API и Webhooks»:

Это делает возможным выгружать к нам из CRM любые показатели сделок, например, себестоимость, операционные доходы, чистую прибыль, размер скидки и любые другие характеристики. Все добавленные поля автоматически становятся доступными в:

• В API-методах создания/обновления/выгрузки сделок
• В пользовательских столбцах Calltouch

Например, как в ЛК Calltouch увидеть валовую прибыль? Теперь очень просто. Добавьте поле "Себестоимость" в API и выгружайте в него данные из CRM. А чтобы посчитать валовую прибыль, просто создайте пользовательский столбец, задав в нем формулу:

В этом примере созданный пользовательский столбец будет отображать валовую прибыль сделок на этапе "Счет на предоплату" менеджера Васи с тегом "Акции". Настроив один раз пользовательский столбец, он станет доступным в любом отчете Calltouch:

Вы можете передавать в пользовательское поле любое целое значение, в том числе отрицательное, максимальное кол-во знаков 38. Для текстовых предназначены теги. При удалении пользовательского поля, все данные, переданные в нем, будут так же удалены.