使用 Celigo B2B Manager 构建/维护…

在 Celigo B2B Manager 中入驻交易伙伴、创建/复用 EDI profile 与 file definition、搭建 X12/EDIFACT 导入导出流并监控交易时使用。

适用场景

解决思路

1. 用资源决策矩阵选择资源：发现伙伴模板运行 `celigo tp-connectors list`；定义交换信封运行 `celigo edi-profiles create`；定义文档解析/生成运行 `celigo file-definitions create`；监控文档交换运行 `celigo edi-transactions list`；连接伙伴端点运行 `celigo connections create`。
2. 创建 EDI profile（X12）时确保必需字段：`name`、`fileType: "edix12"`、`tpInterchangeId`、`myInterchangeId`、`tpIdQualifier`、`myIdQualifier`、`tpGroupId`、`myGroupId`、`isa12`、`gs07`、`gs08`。
3. 创建 EDI profile（EDIFACT）时确保必需字段：`name`、`fileType: "edifact"`、`unb010_0001`、`unb010_0002`、`versionNumber`、`releaseNumber`、`controllingAgency`。
4. 创建 file definition 时确保必需字段：`name`、`version: "2"`、`format`（如 `delimited/x12`）、`delimited` 块（`rowSuffix`、`colDelimiter`）、`rules[]`。
5. 查找 trading partner connector：运行 `celigo tp-connectors list` 和 `celigo tp-connectors get <connectorId>`；查看 `supportedBy` 对象确定连接、EDI profile、导出/导入预配置和用户需提供内容；若无 connector，则从头构建 connection、EDI profile、file definitions。
6. 创建任何资源前检查现有资源：运行 `celigo account search "<partner-name>"`、`celigo edi-profiles list | grep -i "<partner-name>"`、`celigo file-definitions list | grep -i "<partner-name>"`、`celigo connections list | grep -i "<partner-name>"`；EDI profile 按伙伴，避免重复浪费控制号序列。
7. 创建连接：用 `celigo connections create < connection.json` 创建 FTP/AS2/VAN 连接，使用 connector 的 `supportedBy.connection` 预配置字段；用 `celigo connections ping <connectionId>` 验证；详见 configuring-connections。
8. 创建 EDI profile：读取 `references/schemas/edi-profile-request.yml`；定义 ISA/GS（X12）或 UNB（EDIFACT）交换信封；X12 关键字段：`tpInterchangeId`/`myInterchangeId`（ISA06/ISA08）、`tpIdQualifier`/`myIdQualifier`（ISA05/ISA07，例如 ZZ）、`isa12`（如 00401）、`isa15`（P 生产/T 测试）、`controlNumber` 自动递增；运行 `celigo edi-profiles create < profile.json`。
9. 创建 file definitions：每种文档类型（850/810/856 等）单独定义，含解析/生成规则；读取 `references/schemas/file-definition-request.yml`；关键字段：`format`（`delimited/x12` 或 `delimited/edifact`）、`globalId`（标准模板引用，不可变）、`delimited.rowSuffix`（段终止符，X12 用 `~`）、`delimited.colDelimiter`（元素分隔符，X12 用 `*`）、`rules[]`（层级段/元素树）；运行 `celigo file-definitions create < filedef.json`。
10. 创建入站 EDI export：设置 `adaptorType: "FTPExport"`、`file.type: "filedefinition"`、`file.fileDefinition._fileDefinitionId`、`_ediProfileId`、`ftp.directoryPath`；参考 configuring-exports。
11. 创建出站 EDI import：设置 `adaptorType: "FTPImport"`，并引用同一 file definition 和 profile；参考 configuring-imports。
12. 接入 flows 的典型模式：入站 = FTP export（解析 EDI）→ 转换 EDI 字段到 ERP → ERP import；出站 = ERP export → 转换到 EDI → FTP import（生成 EDI）；997 FA 通过入站 export 的 `file.faAcknowledgement: true` 自动生成；参考 building-flows。
13. 区分 file definition 与 EDI profile：file definition 拥有文档语法（段、元素、循环、信封结构），每个文档类型和方向一个；EDI profile 拥有伙伴身份（交换 ID、限定符、组 ID、版本、控制设置），每个伙伴每个 EDI 标准一个；运行时 file definition 规则中的信封元素用 `{{{ediProfile.…}}}` 引用，平台从 export/import 上链接的 `_ediProfileId` 替换值；解析时替换值要与实际文件字节验证，不匹配会因 EDI-profile 验证错误失败；生成时写入产出的文件信封。
14. 确保基于文件的 EDI 步骤同时有 file definition 和 linked profile：平台拒绝没有链接 profile 的 X12/EDIFACT file definition；先创建 profile，再创建引用它的 export/import，与连接顺序相同。
15. 理解一个 profile 两个方向：profile 与方向无关，字段按 `tp*` vs `my*` 标识身份；入站解析时 sender 绑定 `tp*`、receiver 绑定 `my*`；出站生成时 sender 绑定 `my*`、receiver 绑定 `tp*`；一个伙伴 profile 服务入站 850 和出站 810；file definition 则有单独的 parse 和 generate 变体，parse 规则容忍伙伴发送内容，generate 规则必须产出伙伴要求内容。
16. 从样本文件生成 EDI profile：给平台一个真实伙伴样本 EDI 文件，平台从首个字符自动检测标准并读取交换信封（X12 的 ISA/GS 或 EDIFACT 的 UNB），提取信封字段到可复查的 profile；创建前复查提取值，尤其 `isa15`（T vs P）和限定符；提取不产生 `name`，需提供并按伙伴名约定命名（如 "Acme Corp X12"）；伙伴发来的样本中伙伴在 sender 槽，方向不明确时确认样本流向。
17. 不要从零开始构建 EDI file definition：使用 Celigo 全局预建 EDI 模板目录（X12/EDIFACT 文档定义，许多供应商特定），模板按 vendor、document type、direction 标记；将模板实例化到账户级 file definition，然后按伙伴 companion guide 定制；规范来源顺序：账户级同文档类型已存在→复用或作为基础；全局模板匹配→实例化到账户并定制；从零构建→最后手段，仅用于无模板覆盖的文档。
18. 遵守同类型规则：file definition 仅对相同交易集类型有效基础；现有 850 可用于另一个伙伴的 850；860 不能作为 850 的基础；有模板时不要手建规则树，避免信封关闭规则和元素约定错误。
19. 入驻整个伙伴时优先用 trading partner connector：它一并提供 connection、export、import、EDI profile 以及伙伴特定字段；仅当为已入驻伙伴添加一个文档流时，才直接构建单个 EDI 步骤。
20. 功能性确认（997/CONTRL）作为普通 file definitions 处理：设置 `documentType` 为 `997` 或 `CONTRL`；通常双向接线：为收到的每个交换生成确认，并解析伙伴返回的确认；生成侧可在入站 export 设置 `file.faAcknowledgement: true` 自动发出；通过 `faStatus` 按文档跟踪确认状态。
21. 严格验证：EDI 解析会根据 EDI 标准和链接 profile 验证入站文件；两个 file-definition 标志可放宽：`skipEDIValidation` 跳过对 EDI 标准的结构验证；`skipEDIProfileValidation` 跳过对链接 EDI profile 的信封验证；不要默认使用；优先修复规则或 profile 让验证通过；仅在伙伴不符合已确认、认可且不会在伙伴侧修复时使用。
22. 监控 EDI 交易：B2B Manager 跟踪每个 EDI 文档；关键字段 `documentType`、`documentNumber`、`direction`（Inbound/Outbound）、`faStatus`（inProgress/notApplicable/notReceived/received/rejected）、`controlNumber`、`s3Key`/`_flowJobId`（用于原始文件下载）；运行 `celigo edi-transactions list`，可用 `--file-type EDIFACT`、`--start-date 2026-01-01 --end-date 2026-01-31`、`--limit <n>` 过滤。
23. 使用 CLI 管理 EDI profiles：`celigo edi-profiles list`、`get <id>`、`create < profile.json`、`update <id> < profile.json`、`set <id> <key>=<value> [<key2>=<value2> ...]`、`delete <id>`。
24. 使用 CLI 管理 file definitions：`celigo file-definitions list`、`get <id>`、`create < filedef.json`、`update <id> < filedef.json`、`set <id> <key>=<value> [<key2>=<value2> ...]`、`delete <id>`。
25. 使用 CLI 查看 trading partner connectors：`celigo tp-connectors list`、`celigo tp-connectors get <id>`。
26. 使用 CLI 查看 EDI transactions：`celigo edi-transactions list`、`--file-type EDIFACT`、`--start-date <date> --end-date <date>`、`--limit <n>`。
27. 下载 EDI 文件：`celigo jobs download-files <jobId>`；或 `celigo jobs download-files <jobId> --file-id <s3Key> -o output.edi`。
28. 提交前检查：确认 EDI profile 的 `fileType` 正确（`edix12` 或 `edifact`），创建后不可变。
29. 提交前检查：ISA IDs 正确右填充到 15 字符空格。
30. 提交前检查：file definition 的 `format` 与标准匹配（`delimited/x12` 或 `delimited/edifact`）。
31. 提交前检查：file definition 的 `globalId` 引用正确标准模板，创建后不可变。
32. 提交前检查：入站 exports 不要使用 `type: "blob"`（会跳过解析）。
33. 提交前检查：`controlNumber` 从 1 开始，除非伙伴要求特定序列。
34. 提交前检查：exports/imports 同时引用 `_fileDefinitionId` 和 `_ediProfileId`。
35. 提交前检查：file definition 来自同类型模板或现有定义，不要手建。
36. 提交前检查：`skipEDIValidation` / `skipEDIProfileValidation` 保持关闭，除非伙伴不符合已确认并认可。
37. 提交前检查：file definition 仅用于基于标记、固定宽度或 EDI 文件；普通同列 CSV 用步骤的 `file.csv` 选项；JSON/XML/XLSX 用步骤级 parser 配置。
38. 提交前检查：编辑共享 file definition 前运行 `celigo account dependencies` 检查引用；若变更只服务一个消费者则克隆。
39. Gotcha：EDI profiles 按伙伴而非文档类型；按伙伴名搜索，不按文档类型。
40. Gotcha：ISA IDs 右填充到 15 字符；API 返回带填充；裁剪由调用方负责。
41. Gotcha：`fileType` 和 `globalId` 创建后不可变；需要不同标准或模板时创建新资源。
42. Gotcha：file definitions 因交易伙伴而异；Costco 850 与 Walmart 850 结构不同；始终使用正确伙伴特定定义。
43. Gotcha：入站和出站定义不同；同一文档类型的解析和生成规则不可互换。
44. Gotcha：不要在没有有效 `_fileDefinitionId` 时设置 `file.type: "filedefinition"`；先创建不带 `file` 属性，之后链接。
45. Gotcha：FTP/AS2 exports 处理 EDI 时不得使用 `type: "blob"`；省略 `type` 字段，让 file definition parser 运行。
46. Gotcha：`controlNumber` 自动递增；除非伙伴要求，不要重置；重复会导致拒绝。
47. Gotcha：997 FAs 通过 `faStatus` 按交易跟踪；用入站 export 的 `file.faAcknowledgement: true` 自动生成。
48. Gotcha：EDI transactions 需要 EDI license；`edi-transactions list` 仅对启用 B2B Manager 的账户有效。
49. Gotcha：`skipEDIValidation` / `skipEDIProfileValidation` 是逃生舱不是默认；优先修复规则或 profile；仅在伙伴不符合已确认、认可且不会修复时使用。
50. Gotcha：有模板时绝不手建 EDI file definition；实例化匹配的全局模板（同文档类型和方向）并定制；file definition 仅对同交易集类型有效基础——另一个 850 可以，860 不能给 850。
51. Gotcha：功能确认是 file definitions；`997`/`CONTRL` 设置 `documentType`；通常双向接线——收到每个交换生成一个，解析伙伴返回的。
52. Gotcha：file definitions 是共享资源——编辑影响所有引用步骤；若语法修正对所有人都适用，就地编辑；若只服务一个消费者，克隆定义、修改克隆、仅重链该步骤；编辑或删除前检查引用（`celigo account dependencies`）。
53. Gotcha：无标记 CSV 不是 file-definition 工作；结构化文件解析器期望每行有行类型标记（`HDR`/`LIN`、`A`/`B`）、固定宽度切片或 EDI 信封；喂普通同列 CSV 会解析错误，通常合并成单条记录；普通 CSV/TSV 用步骤的 `file.csv` 选项（`hasHeaderRow`、定界符）；JSON/XML/XLSX 用步骤级 parser 配置，绝不用 file definition。

适用边界 · 注意事项

• 不适用于未启用 Celigo B2B Manager / 无 EDI license 的账户；`edi-transactions list` 和 B2B EDI 资源需要该许可。
• 不要用 file definition 解析普通同列 CSV/TSV、JSON/XML/XLSX；普通 CSV/TSV 用步骤的 `file.csv` 选项，JSON/XML/XLSX 用步骤级 parser 配置。
• 不要在伙伴不符合尚未确认、未认可或伙伴会修复时启用 `skipEDIValidation` / `skipEDIProfileValidation`。