Warehouse Integration

It focuses on the real current protocol path:

1. sync orders into EntryGo
2. plan an export
3. evaluate readiness
4. execute the export
5. inspect current state
6. read package and artifact metadata

#Integration model

For a warehouse system, EntryGo should remain the export protocol layer, not an after-the-fact document generator.

Your warehouse integration should:

• submit source order data
• map warehouse records to EntryGo identifiers
• call planning before execution
• branch on readiness and validation
• rely on inspect for state reconciliation

It should not:

• re-implement planning rules locally
• generate its own competing export lifecycle
• treat broker delivery as an undocumented side channel

#Required inputs

Before the first integration test, make sure you have:

• accountId
• warehouse-scoped API key
• valid warehouseId
• valid brokerId
• EntryGo productId values for all exported line items

If your warehouse system only knows internal SKUs, maintain a local mapping from warehouse SKU to EntryGo productId.

#Authentication and account scope

All write endpoints in this workflow require bearer authentication:

Authorization: Bearer <api-key>

Rules:

• body accountId must match the API key scope
• invalid or missing keys return 401 INVALID_API_KEY
• mismatched accountId returns 403 INVALID_ACCOUNT_SCOPE
• warehouse or broker references outside the current account can return INVALID_ACCOUNT_SCOPE

#Step 1: Sync orders from the warehouse system

Use POST /api/orders/sync to upsert warehouse orders into EntryGo.

{
  "accountId": "acc_123",
  "items": [
    {
      "externalId": "wms-order-1001",
      "destinationCountry": "US",
      "destinationRegion": "CA",
      "destinationPostalCode": "94105",
      "items": [
        {
          "productId": "prod_hoodie_001",
          "quantity": 2,
          "unitValueUsd": 110
        },
        {
          "productId": "prod_cap_002",
          "quantity": 1,
          "unitValueUsd": 35
        }
      ],
      "metadata": {
        "source": "warehouse-wms",
        "pick_wave": "wave-17",
        "facility_code": "yvr-01"
      }
    }
  ]
}

Warehouse integration rules:

• treat sync as an upsert by externalId
• store the returned EntryGo order ID alongside the source order reference
• retry with the same idempotency key if the request may have been accepted

#Step 2: Plan an export

Once you have EntryGo order IDs, call POST /api/exports/plan.

{
  "accountId": "acc_123",
  "warehouseId": "wh_123",
  "brokerId": "br_123",
  "destinationCountry": "US",
  "orderIds": ["ord_123"],
  "dryRun": false
}

What to extract from the plan response:

• exportId
• planHash
• readinessState
• validationMessages
• included_order_ids
• excluded_order_ids
• next_recommended_action

#Step 3: Gate execution on readiness

Warehouse systems should not auto-execute just because planning returned success.

Use this decision rule:

Review these fields before execution:

• readinessState
• validationMessages
• flags
• missing_data

#Step 4: Execute the export

Call POST /api/exports/execute only after readiness passes policy.

{
  "accountId": "acc_123",
  "batchId": "batch_123"
}

Execution creates or updates:

• customs package state
• artifact inventory
• notification records
• broker submission state

Retry behavior:

• if execution might have succeeded, retry with the same Idempotency-Key
• if the result remains unclear, inspect the export before issuing a new logical action

#Step 5: Inspect and reconcile

After execution, use GET /api/exports/{id} as the operational source of truth.

Inspect is what warehouse-facing automation should read when it needs to answer:

• did execution complete
• what package exists now
• which artifacts are available
• what happened to broker submission
• which events have occurred

This matters because an execute response is only one moment in time. Inspect is the durable state view.

#Step 6: Read package metadata

When the warehouse workflow only needs package-level details, use GET /api/customs-packages/{id}.

That is the best endpoint for:

• package state
• artifact inventory
• package-level downstream indexing

If the workflow also needs notifications, broker status, or the planning snapshot, use inspect instead.

#Data you should persist locally

Most warehouse integrations should store:

• warehouse order reference -> EntryGo order ID mapping
• exportId
• planHash
• customs_package_id

That small set of identifiers is enough to resume the workflow after process restarts or operator intervention.

#Common warehouse integration failures

#Recommended production posture

1. Keep the warehouse client thin.
2. Persist EntryGo IDs immediately after sync and plan.
3. Retry writes with the same idempotency key before issuing a new request.
4. Use inspect as the canonical reconciliation point after side effects.
5. Prefer machine fields over string parsing or UI scraping.