Synchra.24
menu_bookДакументацыя
Практические материалы по запуску и развитию

Здесь собраны инструкции по запуску, разработке внутренних сценариев и встраиванию собственных инструментов в рабочий контур компании.

folderАўтаматызацыя

Фарматы дадзеных

Праца з JSON, XML, CSV, TSV і тэкстам, кадыроўкамі UTF-8 і Windows-1251, уключаючы дадзеныя з 1С.

Аўтаматычны пераклад

Аўтаматызацыі ўмеюць чытаць і ствараць 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 і разбярыце радок у апрацоўшчыку.

Тыпы ўваходных артэфактаў

Артэфакт заўсёды захоўвае JSON незалежна ад фармату знешняй сістэмы. Поўная падстаноўка ${artifacts.alias.field} у JSON-целе захоўвае тып значэння; падстаноўка ўнутры радка ператварае яго ў тэкст. Для URL і загалоўкаў, поўнае значэнне павінна быць радком. Для масіваў выкарыстоўвайце лікавы сегмент шляху, напрыклад ${artifacts.settings.items.0.id}. Падключэнне артэфактаў.