Быстрая настройка AmoCRM

Данные интеграции

Домен AmoCRM: yourdomain.amocrm.ru

Integration ID: получите при создании интеграции в AmoCRM

Secret Key: хранится в безопасном месте (файл .env)

Кастомные поля контактов

В AmoCRM нужно создать 3 кастомных поля:

Поле	Тип	Назначение
Telegram Username	Текст	Хранит @username клиента
Telegram Chat ID	Число	ID чата в Telegram
Telegram Consent	Переключатель	Согласие на контакт

После создания полей запишите их Field ID из URL AmoCRM и укажите в .env.

Настройка на сервере

1. Скопируйте шаблон .env

cd /путь/к/проекту
cp .env.production.example .env

2. Заполните .env файл

Откройте .env и замените плейсхолдеры на реальные значения:

# AmoCRM
AMOCRM_DOMAIN=yourdomain.amocrm.ru
AMOCRM_CLIENT_ID=<ваш_integration_id>
AMOCRM_CLIENT_SECRET=<ваш_секретный_ключ>
AMOCRM_REDIRECT_URI=https://your-server.example.com/api/admin/amocrm/oauth/callback

# Долгосрочный токен или OAuth
AMOCRM_ACCESS_TOKEN=<ваш_токен>
AMOCRM_TOKEN_EXPIRES_AT=<дата_истечения>

# Field IDs (узнайте в AmoCRM → Настройки → Контакты → Дополнительные поля)
AMOCRM_FIELD_TELEGRAM_USERNAME=<field_id>
AMOCRM_FIELD_TELEGRAM_CHAT_ID=<field_id>
AMOCRM_FIELD_TELEGRAM_CONSENT=<field_id>

# Telegram
TELEGRAM_API_ID=<из my.telegram.org>
TELEGRAM_API_HASH=<из my.telegram.org>
TELEGRAM_PHONE=+7XXXXXXXXXX

# Database
DATABASE_URL=postgresql://telegram_user:пароль@localhost:5432/telegram_crm

# API Secret
API_SECRET_KEY=<сгенерируйте случайную строку>

# Basic Auth
UI_BASIC_AUTH_ENABLED=true
UI_BASIC_AUTH_USERS=admin:безопасный_пароль:admin

3. Запустите миграции

python3 -m alembic upgrade head

4. Запустите приложение

# Через systemd (рекомендуется)
sudo systemctl start telegram-crm-api
sudo systemctl start telegram-crm-worker

# Или через Docker Compose
docker-compose -f docker-compose.production.yml up -d

5. Проверьте статус

curl http://localhost:8000/api/admin/amocrm/status | jq

Ожидается:

{
  "configured": true,
  "domain": "yourdomain.amocrm.ru",
  "has_tokens": true,
  "token_expires_at": "..."
}

Получение Refresh Token (опционально)

Для автообновления токена рекомендуется получить refresh_token:

Откройте: https://your-server.example.com/admin/settings
Войдите с Basic Auth credentials
Секция "AmoCRM OAuth" → "Connect AmoCRM"
Авторизуйтесь в AmoCRM
Refresh token сохранится автоматически

Тестирование

Проверка создания контакта

curl -X POST http://localhost:8000/api/send-message \
  -H "X-Api-Secret: ваш_API_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+79991234567",
    "message": "Тест интеграции AmoCRM"
  }'

Проверка в AmoCRM

Откройте https://yourdomain.amocrm.ru/contacts
Должен появиться новый контакт с:
- Телефоном: +79991234567
- Telegram данными в кастомных полях
- Примечанием с текстом сообщения

Troubleshooting

Проблема: "Token expired"

Решение:

Проверьте что AMOCRM_ACCESS_TOKEN правильно скопирован в .env
Повторите OAuth flow для получения нового refresh_token

Проблема: "Field not found"

Решение: Проверьте Field IDs:

# Получите список полей через API
curl -H "Authorization: Bearer $AMOCRM_ACCESS_TOKEN" \
  "https://yourdomain.amocrm.ru/api/v4/contacts/custom_fields" | jq

Проблема: Контакты не создаются

Проверьте:

CRM_PROVIDER=amocrm (не bitrix24!)
Токен не истек
Логи: tail -f logs/app.log | grep AmoCRM

Безопасность

ВАЖНО:

.env файл НИКОГДА не коммитится в git (уже в .gitignore)
Токены и ключи хранятся ТОЛЬКО на сервере
Используйте безопасные пароли для UI_BASIC_AUTH
API_SECRET_KEY должен быть случайной строкой минимум 32 символа

Сгенерировать безопасный ключ:

openssl rand -hex 32

Готово!

AmoCRM интеграция настроена и готова к работе.

Проверьте чеклист:

.env файл заполнен на сервере
Field IDs корректные
Миграции применены
Приложение запущено
Статус показывает has_tokens: true
Тестовое сообщение создало контакт в AmoCRM

Нужна помощь? Смотрите полную документацию: CONFIGURATION.md

FilesExpand file tree

AMOCRM_SETUP_QUICK.md

Latest commit

History