EntryGoDocs
QuickstartProtocolAPI Reference

Concept

EntryGo Protocol

EntryGo is an export-side protocol for operators shipping from outside the United States into the U.S. market.

The platform is intentionally protocol-first. The durable product is not the dashboard UI. The durable product is the machine contract that tells clients how to:

  1. sync operational demand
  2. plan a deterministic export
  3. execute side effects exactly once
  4. inspect the resulting state

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

#What the protocol is optimizing for

EntryGo moves expensive export and customs preparation work upstream. Instead of waiting for ambiguity at the border, it normalizes order data, evaluates readiness, generates customs-oriented artifacts, and coordinates broker delivery before downstream handoff becomes urgent.

That architecture matters because cross-border workflows fail when every client invents its own state machine. EntryGo keeps the lifecycle narrow and explicit so the same contract works for:

  • human developers building integrations
  • AI coding agents making policy-aware decisions
  • automation systems, SDK users, and internal operator tooling

#The four-step protocol spine

The EntryGo core loop is:

Step Endpoint What it does Side effects
Sync POST /api/orders/sync Makes account-scoped order demand visible to the protocol Yes, durable upsert
Plan POST /api/exports/plan Computes a deterministic export decision No external side effects
Execute POST /api/exports/execute Materializes customs package state and partner notifications Yes
Inspect GET /api/exports/{id} Returns canonical current export state No

That separation is the most important design rule in the product.

#Planning vs execution vs inspection

#Planning is decision

Planning answers: "What should happen if these orders are exported through this warehouse and this broker?"

It returns structured readiness fields such as:

  • planHash
  • readinessState
  • validationMessages
  • flags
  • missing_data
  • included_order_ids
  • excluded_order_ids
  • next_recommended_action

Planning should be safe to reason over repeatedly. Clients should treat it as a deterministic decision surface, not as evidence that work already happened.

#Execution is side effect

Execution answers: "Apply the approved plan and create the operational outcomes."

In the current implementation that includes:

  • creating or reusing customs package state
  • generating artifact metadata
  • creating notification records
  • performing broker submission through the current broker-delivery transport

Execution is where retries and idempotency discipline matter most. A client that loses the network after sending execute should retry with the same idempotency key before assuming failure.

#Inspection is truth

Inspection answers: "What is the current state of this export now?"

Use inspect to confirm:

  • lifecycle status
  • planning snapshot identity
  • current artifacts
  • current customs package state
  • broker submission outcome
  • notifications
  • events

Inspect is the reconciliation surface for both humans and automation. If a write succeeded but the client is uncertain about the outcome, inspect should be the next step.

#Thin clients are a product requirement

EntryGo clients should stay thin.

They should:

  • collect source data
  • call the protocol
  • render protocol state
  • retry safely with idempotency keys
  • branch on structured machine fields

They should not:

  • re-implement grouping logic
  • maintain a second export state machine
  • infer broker delivery from side channels
  • scrape dashboard pages to reconstruct protocol outcomes

This matters for ordinary applications and even more for AI agents. An AI client should not "guess" the business logic. It should query the protocol and act on the returned state.

#Actors around the protocol

#Developers

Developers integrate EntryGo by speaking the protocol directly. Their job is to submit accurate data, store the returned IDs, and orchestrate the lifecycle correctly.

#Warehouses

Warehouses are downstream operators. Their systems usually own source order data and physical handling, but they should still rely on EntryGo for readiness, planning, customs package generation, and export state.

#Brokers

Brokers are also downstream actors. Broker coordination is part of execution, not a client-side afterthought. Today the transport is email-oriented, but the contract is modeled so broker delivery can evolve later without changing the top-level flow.

#AI agents and automation

Agents benefit from EntryGo because the control surface is compact:

  • narrow set of endpoints
  • deterministic planHash
  • explicit idempotency behavior
  • machine-readable error envelope
  • inspectable current state

That makes policy loops feasible: sync, plan, evaluate readiness, execute, inspect, then continue only if the observed state supports the next action.

#Contract rules every client should follow

  1. Store EntryGo IDs returned by the API. Do not plan from external order references alone.
  2. Treat planHash as the identity of the planning snapshot, not as decoration.
  3. Retry write calls with the same idempotency key when the request may have succeeded.
  4. Use inspect after side effects instead of inferring success from one response body or one email.
  5. Build against the documented contract, not internal persistence fields.