Форматы данных

Автоматизации умеют читать и создавать JSON, XML, CSV, TSV и обычный текст. Формат настраивается отдельно для каждого источника и назначения.

Ответ одного источника не должен превышать 5 МБ.

JSON

response:
  format: json
  encoding: utf-8

JSON преобразуется в обычные значения JavaScript:

• объект — в объект;
• массив — в массив;
• строки, числа, логические значения и null сохраняют тип.

Пример входного ответа:

{
  "items": [
    { "id": 17, "amount": 1250.5 }
  ]
}

В обработчике данные доступны как input.items.

При отправке в JSON результат transform сериализуется автоматически. Не нужно вызывать JSON.stringify перед возвратом.

XML

response:
  format: xml
  encoding: windows-1251

XML преобразуется в объект. Корневой элемент становится первым ключом, дочерние элементы — полями объекта.

Исходный XML:

<?xml version="1.0" encoding="UTF-8"?>
<Employees>
  <Employee active="true">
    <Id>42</Id>
    <Name>Анна Смирнова</Name>
  </Employee>
  <Employee active="false">
    <Id>57</Id>
    <Name>Павел Орлов</Name>
  </Employee>
</Employees>

Объект в JavaScript:

{
  Employees: {
    Employee: [
      {
        "@attributes": { active: "true" },
        Id: "42",
        Name: "Анна Смирнова"
      },
      {
        "@attributes": { active: "false" },
        Id: "57",
        Name: "Павел Орлов"
      }
    ]
  }
}

Правила преобразования:

• атрибуты находятся в @attributes;
• текст элемента находится в #text, если у элемента одновременно есть текст и дочерние элементы;
• один дочерний элемент становится объектом или строкой;
• несколько элементов с одинаковым именем становятся массивом;
• числа и логические значения из XML поступают строками, поэтому их нужно явно преобразовать;
• DTD и XML-директивы, способные подключать внешние сущности, запрещены;
• максимальная глубина вложенности XML — 100 уровней.

XML из 1С

Выгрузки 1С часто используют Windows-1251 и могут вернуть один элемент вместо массива, когда запись всего одна. Безопасный обработчик учитывает оба варианта:

function transform(input, context) {
  const raw = input.Employees?.Employee;
  const employees = Array.isArray(raw) ? raw : raw ? [raw] : [];

  return employees.map((employee) => ({
    externalId: String(employee.Id || ""),
    fullName: String(employee.Name || "").trim(),
    active: employee["@attributes"]?.active === "true",
  }));
}

Отправка XML

request:
  format: xml
  encoding: utf-8
  options:
    root: Employees

options.root задаёт корневой элемент. Если результат обработчика — объект с единственным верхним ключом, этот ключ используется как корень автоматически.

CSV

response:
  format: csv
  encoding: windows-1251
  options:
    delimiter: ";"
    header: true

Настройка	По умолчанию	Назначение
delimiter	;	Один символ-разделитель.
header	true	Первая строка содержит названия колонок.

CSV с заголовком:

id;name;amount
1;Первый заказ;350
2;Второй заказ;420

Преобразуется в:

[
  { id: "1", name: "Первый заказ", amount: "350" },
  { id: "2", name: "Второй заказ", amount: "420" }
]

Значения CSV всегда являются строками. Для расчётов используйте Number(value).

Если header: false, входные данные будут массивом строк:

[
  ["1", "Первый заказ", "350"],
  ["2", "Второй заказ", "420"]
]

Отправка CSV

Чтобы отправить CSV, обработчик должен вернуть массив объектов:

function transform(input, context) {
  return input.items.map((item) => ({
    id: item.id,
    name: item.name,
    amount: item.amount,
  }));
}

Колонки формируются по ключам первого объекта. Поэтому у всех строк лучше возвращать одинаковый набор полей.

TSV

TSV работает так же, как CSV, но использует символ табуляции в качестве разделителя.

response:
  format: tsv
  encoding: utf-8

Для TSV значение options.delimiter не требуется.

text

response:
  format: text
  encoding: utf-8

Обработчик получает строку без дополнительного разбора.

function transform(input, context) {
  const lines = String(input)
    .split("\n")
    .map((line) => line.trim())
    .filter(Boolean);

  return { lines };
}

При отправке в формате text результат преобразуется в строку.

Автоматическое определение формата

Если response.format не задан, Synchra24 анализирует заголовок Content-Type:

• значение с json — JSON;
• значение с xml — XML;
• значение с csv — CSV;
• остальные ответы — text.

Для предсказуемой рабочей интеграции формат лучше указывать явно, особенно если внешний сервис возвращает неверный или общий Content-Type.

Кодировки

Поддерживаются:

• utf-8 или utf8;
• windows-1251 или cp1251.

Если encoding не указан, используется UTF-8.

Кодировка применяется после получения ответа и перед разбором формата. При отправке порядок обратный: сначала формируется JSON, XML, CSV, TSV или текст, затем результат кодируется.

Как выбрать формат

• Для современных API используйте JSON.
• Для 1С и старых учётных систем часто нужны XML, CSV и Windows-1251.
• Для табличной выгрузки без сложной вложенности подходят CSV или TSV.
• Для нестандартного плоского ответа используйте text и разберите строку в обработчике.