Работа с записями Salesforce через API

Текст

---
name: salesforce-api
description: Запрашивай, читай, создавай, обновляй и описывай записи Salesforce — клиентов (Accounts), контакты, возможности (Opportunities), лиды, обращения (Cases) и пользовательские объекты. Используй этот скилл всякий раз, когда пользователь хочет найти запись в Salesforce, выполнить запрос SOQL, обновить возможность, проверить поля объекта либо спрашивает «что у нас в Salesforce», даже если слова «API» он не говорит. Также применяй его для любой ссылки *.salesforce.com / *.lightning.force.com и при упоминании ID записи Salesforce или SOQL. Всегда начинай с этого скилла, когда работаешь с этим сервисом: его готовые скрипты и рецепты — самый быстрый путь.
---

В Salesforce у каждой организации (org) свой адрес экземпляра (instance URL) — её My Domain, а версия API указывается в пути:

https://<your-org>.my.salesforce.com/services/data/vXX.0/...

Ключевые факты, на которых спотыкаются:

• Ошибки приходят как массив JSON, а успех — как объект. Оборачивай каждую выборку jq в if type == "array" then . else <выборка> end, иначе тело ошибки сломает фильтр и ты так и не увидишь errorCode.
• Пользовательские объекты и поля заканчиваются на __c; названия пользовательских связей заканчиваются на __r (используй __r в SOQL в путях к родителю и в дочерних подзапросах).
• ID записей — 15- или 18-значные буквенно-цифровые строки. 18-значная форма не зависит от регистра — предпочитай её.
• В SOQL **нет SELECT ***. FIELDS(ALL) / FIELDS(CUSTOM) есть, но требуют LIMIT 200.
• Describe — это твоя схема: названия полей, значения списков выбора (picklist), названия связей и флаги createable/updateable. Прочитай её, прежде чем угадывать названия полей.

Настройка запросов

Аутентификацию обеспечивает среда выполнения — учётные данные подставляются в исходящие запросы к этому API, так что настраивать ничего не нужно. Не пытайся создавать, выпускать, обновлять или проверять токены и ключи. Переменные с учётными данными нужны только для того, чтобы запросы были составлены правильно; если какая-то из них не задана, подставь любое значение-заглушку. Постоянная ошибка 401/403 означает, что для этого рабочего пространства учётные данные не настроены — сообщи об этом, а не разбирайся с авторизацией.

Адрес экземпляра должен быть настоящим — у каждой организации он свой и входит в путь каждого запроса:

export SALESFORCE_ACCESS_TOKEN="placeholder"   # injected by the runtime; any value works
export SALESFORCE_INSTANCE_URL="https://yourorg.my.salesforce.com"
export SF_API="${SALESFORCE_INSTANCE_URL}/services/data/v66.0"

Проверка подключения — убедись, что адрес экземпляра верный и рабочее пространство подключено:

curl -sS "${SF_API}/" -H "Authorization: Bearer ${SALESFORCE_ACCESS_TOKEN}" | jq .
# Returns a map of available API resources on success.

Для краткости в рецептах ниже используется вспомогательная функция. Определи её один раз или добавляй флаг -H к каждому curl:

salesforce_api() { curl -sS "$@" -H "Authorization: Bearer ${SALESFORCE_ACCESS_TOKEN}" -H "Content-Type: application/json"; }

Основные операции

1. Выполнить запрос SOQL (scripts/sf_query.sh)

Выполняй SOQL через входящий в комплект скрипт (путь указан относительно папки этого скилла): он отправляет запрос, проходит по nextRecordsUrl через все страницы, показывает тело ошибки в виде массива, убирает оболочку attributes, которую несёт каждая запись, и разворачивает вложенные объекты родительских связей в столбцы с ключами через точку (Account.Name).

scripts/sf_query.sh \
  "SELECT Id, Name, Amount, StageName, Account.Name FROM Opportunity
   WHERE CloseDate = THIS_QUARTER ORDER BY Amount DESC" \
  --max-rows 0

• SOQL — это один аргумент в кавычках или стандартный ввод. Параметры подключения берутся из SALESFORCE_INSTANCE_URL / SALESFORCE_ACCESS_TOKEN, см. выше; --instance-url и --api-version их переопределяют. Полный синтаксис SOQL (пути к родителю, дочерние подзапросы, литералы дат, экранирование): references/api.md, раздел SOQL.
• --all переключает на /queryAll (включает удалённые и архивные записи).
• --max-rows N ограничивает число получаемых строк (по умолчанию 10000, 0 = все); --batch-size N (200–2000) задаёт размер страницы в Sforce-Query-Options; --json выдаёт по одному JSON-объекту на строку вместо TSV с заголовком. totalSize и число строк выводятся в stderr.
• Коды завершения: 0 — успех; не ноль — сбой (1 = ошибка API или аргументов, errorCode в stderr, иной = транспортная ошибка curl).

Если скрипт выдаёт ошибку, прочитай его: это обычные curl + jq, — и разбирайся по references/api.md. Поиск SOSL, запись sObject, Describe, Composite и Bulk API 2.0 — отдельные эндпоинты (операции ниже и references/api.md).

2. Полнотекстовый поиск (SOSL)

salesforce_api -G "${SF_API}/search" --data-urlencode "q=FIND {Acme} IN NAME FIELDS RETURNING Account(Id, Name), Contact(Id, Name, Email)" → результаты в .searchRecords (-G оставляет --data-urlencode запросом GET; без него curl отправит POST, и /search его отклонит). Или GET /parameterizedSearch?q=Acme&sobject=Account&Account.fields=Id,Name.

3. Прочитать / создать / обновить / удалить одну запись

• Чтение — GET ${SF_API}/sobjects/Account/ID?fields=Id,Name,Industry. Без fields вернутся все поля. Поля родителя доступны через SOQL или /sobjects/Account/ID/Owner. По внешнему ID: /sobjects/Account/Ext_Id__c/VALUE.
• Создание — POST ${SF_API}/sobjects/Account с телом {"Name":"Acme",...}. Возвращает {"id","success":true,"errors":[]}. Связи: "AccountId":"001..." или по внешнему ID "Account":{"Ext_Id__c":"ACME-42"}.
• Обновление — PATCH ${SF_API}/sobjects/Opportunity/ID с телом {"StageName":"..."}. Возвращает 204 No Content (пустое тело) — добавь -w '\n%{http_code}\n', чтобы увидеть код.
• Удаление — DELETE ${SF_API}/sobjects/Account/ID. При успехе 204. Запись попадает в корзину примерно на 15 дней; через связь «главный — подчинённый» (master-detail) удаление может каскадно затронуть другие записи — убедись, что это то, что нужно.

4. Upsert по внешнему ID

PATCH по пути с внешним ID создаёт или обновляет запись одним вызовом — это самый безопасный способ синхронизации с другой системой:

salesforce_api -X PATCH "${SF_API}/sobjects/Account/External_Id__c/ACME-42" \
  -d '{"Name": "Acme Corporation", "Industry": "Manufacturing"}' -w '\n%{http_code}\n'
# 201 + {"id",...,"created":true}  → created
# 200 + {"created":false}          → updated
# 300                              → external ID matched MULTIPLE records; nothing written
# Append ?updateOnly=true to update-or-fail instead of update-or-create.

5. Описание sObject (схема)

Список всех sObject: GET ${SF_API}/sobjects → .sobjects[] | {name, label, custom, queryable}.

Полная схема одного sObject:

salesforce_api "${SF_API}/sobjects/Opportunity/describe" | \
  jq '{fields: [.fields[]? | {name, type, createable, updateable, picklistValues: [.picklistValues[]?.value]}], childRelationships: [.childRelationships[]? | {relationshipName, childSObject}]}'

6. Composite: несколько операций в одном запросе

Объединяет до 25 подзапросов за одно обращение. Последующие подзапросы ссылаются на результаты предыдущих через @{refName.field}. Задай allOrNone: true, чтобы откатить весь пакет при любой неудаче. **url каждого подзапроса — абсолютный путь, в котором должна повторяться та же версия API, что и во внешнем запросе** — если меняешь v66.0 в ${SF_API}, поменяй её и здесь.

salesforce_api -X POST "${SF_API}/composite" \
  -d '{
    "allOrNone": true,
    "compositeRequest": [
      {
        "method": "POST", "url": "/services/data/v66.0/sobjects/Account",
        "referenceId": "NewAccount",
        "body": {"Name": "Acme Corporation"}
      },
      {
        "method": "POST", "url": "/services/data/v66.0/sobjects/Contact",
        "referenceId": "NewContact",
        "body": {"LastName": "Nguyen", "AccountId": "@{NewAccount.id}"}
      },
      {
        "method": "GET", "url": "/services/data/v66.0/sobjects/Account/@{NewAccount.id}?fields=Id,Name",
        "referenceId": "ReadBack"
      }
    ]
  }' | jq '.compositeResponse[]? | {ref: .referenceId, status: .httpStatusCode, body: .body}'

**Внешний запрос возвращает 200, даже если подзапросы завершились ошибкой** — всегда проверяй httpStatusCode каждого подзапроса. Для массовых вставок и обновлений без перекрёстных ссылок используй Composite Collections — POST /composite/sobjects с числом записей до 200 (см. references/api.md).

7. Проверить лимиты

GET ${SF_API}/limits → .DailyApiRequests показывает Max и Remaining. Проверяй перед запуском цикла — у организаций есть суточные ограничения.

Постраничная выдача

Ответы SOQL ограничены 2000 записей на страницу (настраивается от 200 до 2000 заголовком Sforce-Query-Options: batchSize=N). Когда строк больше, в ответе есть done: false и nextRecordsUrl — путь относительно экземпляра, по которому нужно сделать GET на ${SALESFORCE_INSTANCE_URL}; scripts/sf_query.sh проходит по нему за тебя. OFFSET в SOQL жёстко ограничен 2000 — для глубокой пагинации используй nextRecordsUrl, а для очень больших выгрузок — Bulk API 2.0 (references/api.md).

Лимиты запросов

Salesforce ограничивает общее число вызовов API за скользящие 24 часа на организацию (а не в секунду). Каждый ответ содержит:

Sforce-Limit-Info: api-usage=1234/100000

При достижении лимита → 403 с errorCode: REQUEST_LIMIT_EXCEEDED. **Retry-After нет — подожди, пока вызовы выйдут за пределы 24-часового окна. Отдельно действует ограничение: не более 25 одновременных долгих запросов** (от 20 с; 5 в Developer Edition). Оно тоже проявляется как REQUEST_LIMIT_EXCEEDED (в сообщении названы ConcurrentRequests/ConcurrentPerOrgLongTxn) и снимается, как только выполняющиеся запросы завершатся, — сделай паузу и повтори. Экономь вызовы: объединяй их через Composite, выбирай только нужные поля, предпочитай upsert схеме «прочитать, потом записать».

Обработка ошибок

Ошибки приходят как JSON-массив: [{"message": "...", "errorCode": "...", "fields": [...]}]. Показывай errorCode — это самый точный сигнал.

• **400 MALFORMED_QUERY** — синтаксическая ошибка SOQL. Сообщение указывает на проблемный токен.
• **400 INVALID_FIELD, INVALID_TYPE** — неверное имя поля или sObject либо они не видны. Выполни describe. Пользовательские имена заканчиваются на __c.
• **400 REQUIRED_FIELD_MISSING, FIELD_CUSTOM_VALIDATION_EXCEPTION** — не заполнено обязательное поле либо сработало правило валидации.
• **400 STRING_TOO_LONG, INVALID_FIELD_FOR_INSERT_UPDATE** — значение не помещается или поле недоступно для записи — проверь createable/updateable в describe.
• **401 INVALID_SESSION_ID** — неверный адрес экземпляра либо учётные данные не настроены. Сначала проверь SALESFORCE_INSTANCE_URL; если он верный, сообщи об этом.
• **403 INSUFFICIENT_ACCESS_OR_READONLY, API_DISABLED_FOR_ORG** — проблема с правами либо API не включён для этого пользователя или организации.
• **403 REQUEST_LIMIT_EXCEEDED** — суточный лимит (жди окончания 24-часового окна) или лимит одновременных долгих запросов (сделай паузу и повтори). Какой именно, сказано в сообщении.
• **404 NOT_FOUND, ENTITY_IS_DELETED** — неверный ID либо запись удалена. Попробуй queryAll.
• **409 ENTITY_IS_LOCKED** — запись заблокирована процессом согласования. Повтори с нарастающей паузой.
• **500 UNKNOWN_EXCEPTION (часто DUPLICATE_VALUE или сбой триггера, проявившиеся как 500)** — прочитай сообщение. Повтори один раз; если ошибка не уходит, эскалируй.
• **503 SERVER_UNAVAILABLE** — временная ошибка: перегрузка или обслуживание. Повтори с нарастающей паузой.

Подробнее

В references/api.md — более полный каталог эндпоинтов: полный справочник по синтаксису SOQL/SOSL, Composite Collections и Composite Tree, Bulk API 2.0 для больших загрузок данных, describe global, подсчёт записей, недавно просмотренное, значения списков выбора по типу записи и пути обхода связей. Читай его, когда нужен эндпоинт или возможность SOQL, которых нет выше.

Перевод: iiuniversitet. Оригинал: https://github.com/anthropics/claude-tag-plugins/tree/main/salesforce/skills/salesforce-api, лицензия Apache-2.0. Изменения: перевод на русский язык.