Интеграция Airtable и n8n: upsert записей, формы и защита от дублей ¶

Обновлено: 2026-05-30

Проблема: Airtable часто используют как быструю CRM или операционную базу, но простой create record на каждый webhook быстро создаёт дубли и ломает представления.

Решение: Надёжная интеграция Airtable и n8n должна нормализовать входные поля, собрать стабильный external_id, найти существующий record через filterByFormula и выполнить update или create только после проверки.

Проблема: почему простая интеграция создаёт дубли и ручной хаос ¶

Airtable удобен как рабочая база для маркетинга, контента, продаж и поддержки: таблицы понятны команде, views заменяют лёгкую CRM, а формы быстро собирают данные. Проблема начинается, когда данные приходят из нескольких источников: Tilda, Telegram, email, CRM, платежи и ручной импорт.

Если workflow каждый раз вызывает create record, в базе появляются одинаковые строки с разными статусами, attachment fields теряют связь с исходной заявкой, а менеджеры перестают доверять views. Поэтому задача статьи — не “подключить Airtable”, а построить upsert-слой между n8n и базой.

Архитектура workflow для n8n ¶

Для production лучше иметь отдельное поле External ID с уникальным бизнес-ключом. Формула поиска должна использовать это поле, а не title или имя клиента.

Контракт входных данных ¶

{
  "source": "landing_form",
  "entity_id": "lead-2026-10492",
  "name": "Алексей",
  "phone": "+7 (916) 111-22-33",
  "email": "alexey@example.ru",
  "status": "new",
  "tags": [
    "n8n",
    "crm",
    "priority"
  ],
  "budget": 150000,
  "source_url": "https://example.ru/request/10492",
  "attachments": [
    {
      "url": "https://example.ru/files/brief.pdf",
      "filename": "brief.pdf"
    }
  ]
}

Минимальный контракт: source, entity_id и хотя бы одно поле для человека — name, email или phone. В Airtable нельзя полагаться на название записи как на ключ дедупликации.

Code Node: нормализация, mapping и guard-условия ¶

const src = $json.body ?? $json;
const source = String(src.source ?? 'external').trim().toLowerCase();
const entityId = String(src.entity_id ?? src.id ?? '').trim();
if (!entityId) throw new Error('No entity_id for Airtable upsert');
const rawPhone = String(src.phone ?? '').trim();
let digits = rawPhone.replace(/\D/g, '');
if (digits.length === 11 && digits.startsWith('8')) digits = `7${digits.slice(1)}`;
if (digits.length === 10) digits = `7${digits}`;
const email = String(src.email ?? '').trim().toLowerCase();
const tags = Array.isArray(src.tags) ? src.tags.map(String).slice(0, 10) : [];
const externalId = `${source}:${entityId}`;
const filterByFormula = `{External ID} = '${externalId.replace(/'/g, "\'")}'`;
return [{ json: {
  external_id: externalId,
  filterByFormula,
  fields: {
    'External ID': externalId,
    'Name': String(src.name ?? 'Новая запись').trim(),
    'Phone': digits ? `+${digits}` : '',
    'Email': email,
    'Status': String(src.status ?? 'new').trim(),
    'Tags': tags,
    'Budget': Number(src.budget ?? 0),
    'Source URL': String(src.source_url ?? '').trim(),
    'Last synced at': new Date().toISOString(),
    'Attachments': Array.isArray(src.attachments) ? src.attachments.map(a => ({ url: a.url, filename: a.filename })) : []
  }
}}];

Готовый workflow JSON: скачать и импортировать ¶

Скачать готовый workflow JSON Скачать тестовый payload

{
  "name": "Nodbot - Airtable upsert records with external id",
  "nodes": [
    {
      "name": "Airtable Webhook",
      "type": "n8n-nodes-base.webhook",
      "purpose": "Принять событие"
    },
    {
      "name": "Normalize Airtable fields",
      "type": "n8n-nodes-base.code",
      "purpose": "Собрать fields и filterByFormula"
    },
    {
      "name": "Find Airtable record",
      "type": "n8n-nodes-base.httpRequest",
      "purpose": "Найти record по External ID"
    },
    {
      "name": "Create or update record",
      "type": "n8n-nodes-base.httpRequest",
      "purpose": "Сделать create/update"
    },
    {
      "name": "Respond",
      "type": "n8n-nodes-base.respondToWebhook",
      "purpose": "Вернуть статус"
    }
  ],
  "connections": "Airtable Webhook → Normalize Airtable fields → Find Airtable record → Create or update record → Respond"
}

Пошаговая настройка связки ¶

1. Создайте в Airtable поле External ID и не переименовывайте его без миграции workflow.
2. Импортируйте workflow JSON и замените baseId, tableId, credential и field names.
3. Проверьте filterByFormula на тестовой записи до production.
4. Настройте handling для attachments: Airtable должен иметь доступ к URL файла.
5. Отправьте одинаковый payload дважды и убедитесь, что обновляется одна запись.

Тесты перед production ¶

curl -X POST "https://YOUR-N8N-DOMAIN/webhook/integration-airtable-n8n-upsert-records" \
  -H "Content-Type: application/json" \
  --data @integration-airtable-n8n-upsert-records-payload.json

1. Повторный payload не создаёт дубль и возвращает тот же output key.
2. Некорректный mapping останавливается до запроса к внешнему API.
3. Пустые необязательные поля не ломают workflow.
4. Ошибка API уходит в alert или DLQ с безопасным payload.
5. Execution data не содержит секретов, токенов и лишних персональных данных.

Production-риски ¶

• Поиск по title. Ручная правка названия создаст дубль при следующей синхронизации.
• Переименованы поля. Airtable API начнёт возвращать ошибку или писать не туда.
• Attachment URL недоступен. Файл не прикрепится, хотя record будет создан.
• Нет лимитов и retry. Массовый импорт может упереться в API rate limits.
• Секреты в execution data. Не логируйте personal access token и полный payload без маскирования.

Полезные ссылки и смежные материалы ¶

• Airtable Web API documentation
• Airtable List records
• Airtable Create records
• Webhook idempotency to Postgres
• Google Sheets и n8n

Критерии готовности ¶

1. External ID есть в таблице и используется для поиска.
2. Повторный payload обновляет один record, а не создаёт второй.
3. Attachments проходят тест с реальным URL.
4. Ошибки Airtable API уходят в alert или DLQ.
5. У workflow есть владелец, версия и тестовый payload.