docs(integration-toolkit): document inbound direct mode - #145
Merged
Conversation
added 9 commits
August 25, 2026 20:51
New Direct Mode page under Inbound Integration: sending entity-shaped payloads that skip the mapping engine while keeping deduplication, ordering, create-vs-update resolution, relations, meter readings, and monitoring. Covers enabling the mode (open vs entity allowlist), the versioned payload contract, relations and relation references, the simulateDirect dry run, the DIRECT_* monitoring codes, what stays unsupported in version 1, and operational notes. Cross-linked from the Mapping page and the use case configuration guide; sidebar renumbered to slot the page right after Mapping.
No follow-up payload version is planned; the unsupported features are a property of direct mode itself, not of a "version 1".
The visual configuration (toggle, Open vs Restricted write access with schema and unique-id pickers, allowlist pre-fill from mapped entities) is the primary touchpoint; the JSON is what the toggle produces. Also point direct users at simulateDirect instead of the mapped Test tab.
…nfiguration guide The caching window applies to every use case configuration change, so it belongs in the shared guide once instead of a standalone reminder on the direct-mode page.
Facts verified against the shipped code and the dev environment: allowlist entries must declare at least one unique id; upsert restores soft-deleted matches (SOFT_DELETED_ENTITY_MATCHED); purge reports as ENTITY_DELETED with mode purge; a unique id missing from the schema still creates (plus UNIQUE_ID_NOT_IN_SCHEMA errors); _id references never create; request-level validation intercepts version/size defects on the dry-run endpoint with HTTP 400; packed meter batches emit one METER_READING_UPSERTED with the reading count; reused warning codes listed.
Operation semantics live in the Relations page; the direct-mode page keeps only its own envelope syntax and the strict operation whitelist.
simulateDirect is exposed through the use case Test tab for direct use cases, same as the mapping test for mapped ones.
Inbound syncs do not trigger entity automations by default (a trigger opts in via its "Ignore system activities?" setting — verified against automation-api exclusion logic and the automation hub trigger defaults) and never echo back out through outbound delivery.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Documents the new inbound direct mode shipped in erp-integration-api (API 1.20.0): integrators whose middleware already produces entity-shaped payloads can skip the mapping engine while keeping the rest of the pipeline (deduplication, per-entity ordering, create-vs-update resolution, relations with stub creation, meter-reading matching, sync-activity echo prevention, monitoring).
Changes
inbound/direct-mode.md(sidebar position 3, right after Mapping): enabling the mode (direct: true, open mode vs entity allowlist), the versioned payload contract (version: "1", entity + meter-reading operations), relations and relation references in direct syntax, email/phone unique-id handling (server-side derivation +unique_id_typesoverride), sending events on the v3 endpoint, deduplication and ordering caveats, thesimulateDirectdry run, the threeDIRECT_*monitoring codes, the unsupported-in-v1 table, and operational notes.inboundentry in the use-case type list noting thedirectflag.All examples mirror the shipped contract (source: erp-integration-api
docs/DIRECT_MODE.md); thesimulateDirectresponse examples use the actual snake_case API response shape.npm run buildpasses (no broken links).🤖 Generated with Claude Code