Docs | EntryGo

The key design goal is straightforward: an agent should be able to reason over export state without guessing hidden business logic.

#Why EntryGo works well for agents

EntryGo is a good agent substrate because the protocol is narrow and stateful in the right places.

Useful properties:

order intake is explicit
planning is separated from execution
planning produces deterministic planHash
write operations support idempotency
inspect provides canonical current state
errors are machine-readable
artifacts and broker submission are visible in the contract

That gives agents a stable loop:

sync current inputs
plan
decide based on structured policy signals
execute if policy allows
inspect and reconcile before continuing

#The canonical agent loop

Phase	Endpoint	Agent responsibility
Sync	`POST /api/orders/sync`	Submit current source state and store EntryGo order IDs
Plan	`POST /api/exports/plan`	Read readiness, validation, and `planHash`
Execute	`POST /api/exports/execute`	Trigger side effects exactly once
Inspect	`GET /api/exports/{id}`	Reconcile current truth before the next decision

This loop is the foundation for reliable automation.

#Authentication

All core workflow endpoints require:

http

Authorization: Bearer <api-key>

Rules:

write payload accountId must match the API key scope
invalid keys return 401 INVALID_API_KEY
scope mismatch returns 403 INVALID_ACCOUNT_SCOPE

#Step 1: Sync current demand

Agents should start from current operational demand, not cached assumptions.

Use POST /api/orders/sync and persist the returned EntryGo order IDs.

json

{
  "accountId": "acc_123",
  "items": [
    {
      "externalId": "agent-order-1001",
      "destinationCountry": "US",
      "destinationRegion": "CA",
      "destinationPostalCode": "94105",
      "items": [
        {
          "productId": "prod_hoodie_001",
          "quantity": 1,
          "unitValueUsd": 110
        }
      ],
      "metadata": {
        "source": "automation-agent",
        "workflow_run_id": "run_001"
      }
    }
  ]
}

Agent rule:

persist data[].id
never plan using only your external order identifier

#Step 2: Plan and extract policy signals

Use POST /api/exports/plan to compute the decision surface.

Important fields to extract:

exportId
planHash
readinessState
validationMessages
flags
missing_data
next_recommended_action

Typical planning excerpt:

json

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

#Step 3: Apply execution policy

Do not execute just because planning returned success.

Recommended policy baseline:

`readinessState`	Agent behavior
`READY`	Execute automatically if your policy allows it
`REVIEW_REQUIRED`	Execute only if warnings are acceptable under policy
`BLOCKED`	Stop and request correction or escalation

Preferred machine signals:

readinessState
validationMessages[].code
validationMessages[].severity
flags
missing_data

Avoid using the human-readable message field as your primary control mechanism.

#Step 4: Execute safely

Call POST /api/exports/execute only when the plan satisfies policy.

Execution rules for agents:

always send an idempotency key
if the client loses the response, retry with the same key first
do not issue a new logical execute request until you reconcile state

This is how an agent avoids duplicate side effects.

#Step 5: Inspect after side effects

Inspect is the canonical post-execution truth surface.

Use GET /api/exports/{id} to reconcile:

current lifecycle state
current artifacts
package state
broker submission status
event history

Typical inspect excerpt:

json

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

#Recommended agent memory

Persist at least:

EntryGo order IDs
exportId
planHash
latest observed lifecycle status
latest observed broker submission status if it affects the workflow

That minimal memory model is usually enough to resume safely.

#Error handling strategy

Use HTTP status plus errorCode:

Error	Agent action
`VALIDATION_ERROR`	Fix the request; do not retry unchanged
`INVALID_ACCOUNT_SCOPE`	Stop and correct scope configuration
`INVALID_ORDER_REFERENCE`	Re-sync demand or correct the order IDs
`INVALID_EXPORT_STATE`	Inspect current export state before deciding again
`IDEMPOTENCY_CONFLICT`	Re-send the original request or generate a new key for a genuinely new operation

#What agents should not do

infer success from an email, UI state, or one partial response
generate their own lifecycle transitions outside the protocol
retry execute with a new key before reconciling the prior attempt
parse free-form message text when stable machine fields exist

#Best use cases

EntryGo is a good fit for agents that need to:

monitor export readiness
decide whether warnings are policy-acceptable
trigger execution exactly once
inspect and reconcile artifacts and broker delivery
report operational state back into a broader workflow system