> ## Documentation Index > Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt > Use this file to discover all available pages before exploring further. # Relink migrated JE source_id to Arcus order/invoice UUIDs > A migrated historical journal entry is born with `source_id` holding the source-system (Versa) document INTEGER, because historical GL is loaded BEFORE orders/invoices: the Arcus order/invoice UUID does not exist yet. Native Arcus order JEs set `source_id` = the Arcus order UUID, and the GL UI / reports resolve the source document by that UUID. This endpoint is the corrective reconciliation pass run AFTER orders and invoices are migrated. The caller supplies a batch of items, each mapping a source-system journal id (`external_id`, carried on `journal_entries.external_id`) to its Arcus order/invoice UUID (`source_id`). **Strict-resolve safety.** `source_id` must be a UUID that resolves to an order in the entity (or a vendor_bill when source_module='ap' or new_source_type is AP_BILL / AP_PAYMENT, added 2026-05-27). A non-UUID or non-resolving value is rejected, never written -- this prevents re-stamping a source-system integer or mislinking across entities. **Idempotent.** When a JE already carries the target `source_id` (and the target `source_type` and `description` match), the item returns `relinked=false` (no-op). Re-running the whole pass is safe. **Scope guard (relaxed 2026-05-27 MIGRATION-MAPPING-NATIVE).** Only `journal_entries` whose `external_source = 'versa_cloud'` can be matched. Previously also required `source_type = VERSA_MIGRATION`; relaxed so the handler can relink rows that the loader has already classified to canonical source_types (PAYMENT, INVOICE, AP_BILL, etc). `is_historical_import` is asserted as a belt-and-suspenders guard. Native Arcus JEs (external_source IS NULL) are never matched. **Optional source_type upgrade (`new_source_type`, added 2026-05-27).** When supplied, upgrades `source_type` from VERSA_MIGRATION to a canonical Arcus value. The handler never downgrades a canonical source_type back to the fallback. **Optional description enrichment (`enrich_description`, added 2026-05-27).** When true, rebuilds `description` from the canonical native template with the order_number suffix. Non-order-attached source_types (INVENTORY_ADJUSTMENT / MANUAL / BANK_RECON / BANK_DEPOSIT) are skipped to preserve the Versa memo carried by the loader. **Pure header UPDATE.** Touches only `journal_entries.source_id`, `source_module`, `source_type`, and `description`. No line is touched, no amount is touched, no FK is created or dropped. **Scope:** `migration:write`. ## OpenAPI ````yaml /openapi.yaml post /entities/{entity_id}/migration/journal-entries/relink-source openapi: 3.1.0 info: title: Arcus ERP Public API version: 1.0.0 description: > Arcus ERP public REST API. Designed for external integrations and data migration. **Authentication.** Bearer token (API key) via the `Authorization` header. Format: `Authorization: Bearer ark_live_ent__` (or `ark_test_*` for sandbox). API keys are issued per-entity in **Settings > Developers > API Keys**. **Entity scoping.** The entity is encoded in the API key prefix; routes are flat (e.g. `/v1/accounts`, `/v1/orders`, `/v1/products`). A small set of platform endpoints (migration, reconciliation, events, webhook endpoints, API keys) use the `/v1/entities/{entity_id}/...` form -- those are noted in their tags. **Key capabilities.** - Related-resource hydration via `?expand[]=` (see `x-arcus-expand` on each resource). - Cursor-based pagination (`starting_after` / `ending_before` / `limit`). - Idempotency via the `Idempotency-Key` header. - Webhook events for asynchronous notification. - Conditional requests / ETag for cache validation. servers: - url: https://api.arcuserp.com/v1 description: Arcus ERP API (accepts both live `ark_live_*` and test `ark_test_*` keys) - url: https://dev-api.arcuserp.com/v1 description: >- Dev sandbox API (test-only data, accepts `ark_test_*` keys against dev RDS) security: [] paths: /entities/{entity_id}/migration/journal-entries/relink-source: post: tags: - Migration summary: Relink migrated JE source_id to Arcus order/invoice UUIDs description: > A migrated historical journal entry is born with `source_id` holding the source-system (Versa) document INTEGER, because historical GL is loaded BEFORE orders/invoices: the Arcus order/invoice UUID does not exist yet. Native Arcus order JEs set `source_id` = the Arcus order UUID, and the GL UI / reports resolve the source document by that UUID. This endpoint is the corrective reconciliation pass run AFTER orders and invoices are migrated. The caller supplies a batch of items, each mapping a source-system journal id (`external_id`, carried on `journal_entries.external_id`) to its Arcus order/invoice UUID (`source_id`). **Strict-resolve safety.** `source_id` must be a UUID that resolves to an order in the entity (or a vendor_bill when source_module='ap' or new_source_type is AP_BILL / AP_PAYMENT, added 2026-05-27). A non-UUID or non-resolving value is rejected, never written -- this prevents re-stamping a source-system integer or mislinking across entities. **Idempotent.** When a JE already carries the target `source_id` (and the target `source_type` and `description` match), the item returns `relinked=false` (no-op). Re-running the whole pass is safe. **Scope guard (relaxed 2026-05-27 MIGRATION-MAPPING-NATIVE).** Only `journal_entries` whose `external_source = 'versa_cloud'` can be matched. Previously also required `source_type = VERSA_MIGRATION`; relaxed so the handler can relink rows that the loader has already classified to canonical source_types (PAYMENT, INVOICE, AP_BILL, etc). `is_historical_import` is asserted as a belt-and-suspenders guard. Native Arcus JEs (external_source IS NULL) are never matched. **Optional source_type upgrade (`new_source_type`, added 2026-05-27).** When supplied, upgrades `source_type` from VERSA_MIGRATION to a canonical Arcus value. The handler never downgrades a canonical source_type back to the fallback. **Optional description enrichment (`enrich_description`, added 2026-05-27).** When true, rebuilds `description` from the canonical native template with the order_number suffix. Non-order-attached source_types (INVENTORY_ADJUSTMENT / MANUAL / BANK_RECON / BANK_DEPOSIT) are skipped to preserve the Versa memo carried by the loader. **Pure header UPDATE.** Touches only `journal_entries.source_id`, `source_module`, `source_type`, and `description`. No line is touched, no amount is touched, no FK is created or dropped. **Scope:** `migration:write`. operationId: postMigrationJournalEntryRelinkSource parameters: - name: entity_id in: path required: true schema: type: string format: uuid - name: Idempotency-Key in: header required: false schema: type: string description: > Optional idempotency key. If supplied, retrying the same call within 24 hours returns the previous result. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MigrationJournalEntryRelinkBatch' examples: batch: summary: Relink a batch of migrated JEs value: items: - external_id: '5611654' source_id: 6b1e9a4f-1d2c-4f8e-9c8a-8b1d2e3f4a5b source_module: invoice - external_id: '5611655' source_id: 7c2f0b5e-2e3d-5f9f-ad9b-9c2e3f4a5b6c source_module: payment responses: '200': description: JE source-relink result content: application/json: schema: $ref: '#/components/schemas/MigrationJournalEntryRelinkResult' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' security: - ApiKeyAuth: [] components: schemas: MigrationJournalEntryRelinkBatch: type: object required: - items description: Batch JE source-relink payload (up to 500 items per call). properties: items: type: array minItems: 1 maxItems: 500 items: $ref: '#/components/schemas/MigrationJournalEntryRelinkItem' MigrationJournalEntryRelinkResult: type: object description: > Result envelope for JE source relink. Each row in `results` reports independently; a failure on one item does not roll back the others. Pure column UPDATE on the JE header (source_id / source_module / source_type / description). No line is touched and no amount is touched. properties: object: type: string enum: - migration_je_source_relink_result total: type: integer relinked: type: integer already_linked: type: integer not_found: type: integer failed: type: integer source_type_upgraded: type: integer description: | Total per-batch count of rows where source_type was upgraded from VERSA_MIGRATION to a canonical value. Added 2026-05-27. descriptions_enriched: type: integer description: | Total per-batch count of rows where the description was rebuilt to the canonical native template. Added 2026-05-27. results: type: array items: $ref: '#/components/schemas/MigrationJournalEntryRelinkResultItem' MigrationJournalEntryRelinkItem: type: object required: - external_id - source_id description: One JE source-relink request. properties: external_id: type: string description: > The source-system journal id stored on `journal_entries.external_id` (e.g. the Versa `journal_id`). Matched alongside the API key's entity_id and the JE's `external_source` to locate exactly one migrated JE. source_id: type: string format: uuid description: > The Arcus order/invoice UUID to write into `journal_entries.source_id`. Strictly validated: must be a UUID that resolves to an order in the entity. A non-UUID or non-resolving value is rejected, never written. source_module: type: string maxLength: 50 description: > Optional. Updates `journal_entries.source_module` (e.g. invoice, bill, payment, order) so GL reports can scope "order-sourced JEs only" for the source-id JOIN. When omitted the existing value is preserved. new_source_type: type: string enum: - PAYMENT - AP_PAYMENT - INVOICE - AP_BILL - FULFILLMENT - INVENTORY_ADJUSTMENT - BANK_RECON - BANK_DEPOSIT - MANUAL - VERSA_MIGRATION description: > Optional. Upgrade `journal_entries.source_type` from the migration fallback `VERSA_MIGRATION` to a canonical Arcus source_type (e.g. PAYMENT, INVOICE, AP_BILL) once classification is known. The handler ONLY upgrades when the current row carries source_type=VERSA_MIGRATION; it never downgrades a canonical source_type back to the fallback. Validated against the JE_SOURCE_TYPE allowlist; arbitrary values are rejected. Added 2026-05-27 (MIGRATION-MAPPING-NATIVE). enrich_description: type: boolean default: false description: > Optional. When true AND the source lookup resolves to an order with an order_number, the handler recomputes `journal_entries.description` using the canonical native template (`Customer payment received for SO-12345`, `Invoice posted for INV-40089`, etc.) and updates only if it differs from the current value. Non-order-attached source_types (INVENTORY_ADJUSTMENT, MANUAL, BANK_RECON, BANK_DEPOSIT) are NOT enriched (would destroy the Versa memo suffix preserved by the loader). Added 2026-05-27 (MIGRATION-MAPPING-NATIVE). MigrationJournalEntryRelinkResultItem: type: object description: Per-item result of a JE source-relink attempt. properties: external_id: type: string journal_entry_id: type: string format: uuid description: The Arcus journal_entry UUID matched (omitted when not found). source_id: type: string description: The current source_id after the call. source_type: type: string description: | The current source_type after the call. Added 2026-05-27 to surface new_source_type upgrade outcomes. source_type_upgraded: type: boolean description: | true when source_type was upgraded from VERSA_MIGRATION to a canonical value on this call. Added 2026-05-27. description_enriched: type: boolean description: > true when description was rebuilt to the canonical native template (e.g. "Customer payment received for SO-12345") on this call. Added 2026-05-27. relinked: type: boolean description: > true if source_id was changed; false on idempotent no-op (the JE already carried the target source_id). error: type: string description: Present only on failure. code: type: string description: Machine-readable error code. hint: type: string ErrorEnvelope: type: object description: | Canonical error response envelope. All API errors use this shape. required: - error - code properties: error: type: string description: Machine-readable error key example: not_found code: type: string description: Machine-readable error code (often same as error) example: not_found type: type: string enum: - validation_error - permission_error - not_found - conflict - rate_limit - internal - expand_error - not_implemented example: not_found hint: type: string description: Human-readable one-sentence explanation (English) example: >- The requested order does not exist or does not belong to this entity. param: type: string description: The parameter that caused the error, if applicable example: expand[0] required: type: string description: The scope required (only on insufficient_scope errors) example: accounts:read request_id: type: string description: >- Unique request ID for support tracing (maps to CloudWatch log stream) example: req_abc123 responses: Error: description: Error response (400/401/403/404/409/422/429/500) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: ApiKeyAuth: type: http scheme: bearer description: | API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent__ Test keys use ark_test_ent__. Both are issued per entity via Settings > Developers > API Keys. ````