EntryGoDocs
QuickstartProtocolAPI Reference

Guide

First Export

This guide walks through the shortest production-shaped path to a successful export in EntryGo.

It is written for:

  • human developers validating their first integration
  • operator teams testing the workflow end to end
  • AI agents and automation clients running a first controlled export

The machine-readable contract lives at /docs/api/openapi.

#What you will do

  1. Authenticate against EntryGo
  2. Sync one order
  3. Plan the export
  4. Review readiness
  5. Execute the export
  6. Inspect the result
  7. Read customs package and artifact state

#Before you begin

You need:

  • an API key scoped to the target EntryGo account
  • the correct accountId
  • a valid warehouseId
  • a valid brokerId
  • at least one existing EntryGo productId for the order line items

Important: the core public workflow starts at order sync. If product records do not exist yet, load them through the product setup flow before using this guide.

#1. Set local environment variables

bash
export ENTRYGO_BASE_URL="http://localhost:3000"
export ENTRYGO_API_KEY="shpbndl_live_..."
export ENTRYGO_ACCOUNT_ID="acc_123"
export ENTRYGO_WAREHOUSE_ID="wh_123"
export ENTRYGO_BROKER_ID="br_123"
export ENTRYGO_PRODUCT_ID="prod_123"

#2. Verify authentication

bash
curl "$ENTRYGO_BASE_URL/api/system/health" \
  -H "authorization: Bearer $ENTRYGO_API_KEY"

If this fails:

  • 401 INVALID_API_KEY means the key is missing or invalid
  • networking or environment errors should be fixed before you continue

#3. Sync the first order

Call POST /api/orders/sync to make the source order visible to the protocol.

bash
curl -X POST "$ENTRYGO_BASE_URL/api/orders/sync" \
  -H "authorization: Bearer $ENTRYGO_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: first-export-orders-001" \
  -d '{
    "accountId": "'"$ENTRYGO_ACCOUNT_ID"'",
    "items": [
      {
        "externalId": "ord-ext-1001",
        "destinationCountry": "US",
        "destinationRegion": "CA",
        "destinationPostalCode": "94105",
        "items": [
          {
            "productId": "'"$ENTRYGO_PRODUCT_ID"'",
            "quantity": 1,
            "unitValueUsd": 110
          }
        ],
        "metadata": {
          "source": "first-export-guide"
        }
      }
    ]
  }'

Expected response shape:

json
{
  "data": [
    {
      "id": "ord_123",
      "externalId": "ord-ext-1001",
      "totalValueUsd": 110
    }
  ]
}

Save the returned EntryGo order ID. Planning uses EntryGo order IDs, not only your externalId.

#4. Plan the export

Call POST /api/exports/plan with the synced order ID.

bash
curl -X POST "$ENTRYGO_BASE_URL/api/exports/plan" \
  -H "authorization: Bearer $ENTRYGO_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: first-export-plan-001" \
  -d '{
    "accountId": "'"$ENTRYGO_ACCOUNT_ID"'",
    "warehouseId": "'"$ENTRYGO_WAREHOUSE_ID"'",
    "brokerId": "'"$ENTRYGO_BROKER_ID"'",
    "destinationCountry": "US",
    "orderIds": ["ord_123"],
    "dryRun": false
  }'

Typical planning response:

json
{
  "exportId": "batch_123",
  "planHash": "planhash_abc123",
  "readinessState": "REVIEW_REQUIRED",
  "validationMessages": [
    {
      "code": "METALS_REVIEW_RECOMMENDED",
      "severity": "warning"
    }
  ],
  "included_order_ids": ["ord_123"],
  "next_recommended_action": "review_flags_then_execute"
}

Persist:

  • exportId
  • planHash

#5. Review readiness before execution

Treat the plan response as a decision surface, not as approval by default.

Review these fields:

  • readinessState
  • validationMessages
  • flags
  • missing_data
  • next_recommended_action

Suggested policy:

readinessState Meaning Action
READY No blocking readiness issues Execute if policy allows
REVIEW_REQUIRED Warnings or review signals exist Continue only if acceptable
BLOCKED Required data or readiness is missing Fix the issue first

Common planning failures:

  • invalid order IDs
  • warehouse or broker outside account scope
  • missing product readiness data
  • destination data missing or malformed

#6. Execute the export

Once the plan is acceptable, call POST /api/exports/execute.

bash
curl -X POST "$ENTRYGO_BASE_URL/api/exports/execute" \
  -H "authorization: Bearer $ENTRYGO_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: first-export-execute-001" \
  -d '{
    "accountId": "'"$ENTRYGO_ACCOUNT_ID"'",
    "batchId": "batch_123"
  }'

Typical execute response:

json
{
  "exportId": "batch_123",
  "status": "COMPLETED",
  "customs_package_id": "cp_123",
  "artifacts": [
    {
      "artifact_type": "manifest",
      "filename": "manifest.json"
    }
  ],
  "brokerSubmission": {
    "status": "sent",
    "recipient_email": "broker@example.com"
  }
}

Important:

  • execution is idempotent when you reuse the same idempotency key for the same logical request
  • if the network fails after submit, retry with the same idempotency key first

Common execution errors:

  • 409 INVALID_EXPORT_STATE if the batch cannot transition from its current state
  • 409 IDEMPOTENCY_CONFLICT if the same idempotency key is reused with a different logical payload

#7. Inspect the export

Use inspect as the canonical source of truth after side effects.

bash
curl "$ENTRYGO_BASE_URL/api/exports/batch_123" \
  -H "authorization: Bearer $ENTRYGO_API_KEY"

Typical inspect response:

json
{
  "exportId": "batch_123",
  "status": "COMPLETED",
  "planHash": "planhash_abc123",
  "artifacts": [
    {
      "artifact_type": "manifest",
      "filename": "manifest.json"
    }
  ],
  "customsPackage": {
    "id": "cp_123",
    "state": "sent_to_broker"
  },
  "brokerSubmission": {
    "status": "sent"
  }
}

Use inspect to confirm:

  • current lifecycle state
  • current customs package state
  • current artifact inventory
  • broker submission status
  • event timeline

#8. Read customs package state

If you need package-specific artifact inventory, call:

bash
curl "$ENTRYGO_BASE_URL/api/customs-packages/cp_123" \
  -H "authorization: Bearer $ENTRYGO_API_KEY"

Use this endpoint when you already know the package ID and only need package-level details.

#Safe retry rules

Operation Retry posture
Order sync Retry with the same Idempotency-Key if the request may have been accepted
Plan Retry with the same key if the client lost the response
Execute Retry with the same key first, then inspect if state is unclear
Inspect and package lookup Ordinary safe read retries are fine

#What success looks like

At the end of a successful first export you should have:

  • a stable EntryGo order ID
  • an exportId
  • a planHash
  • a completed execute response
  • an inspect response showing the latest export state
  • a customs package ID and artifact inventory

#Next steps