Protocol Primitives

These are conceptual objects first. Exact field-level schemas live at /docs/api/openapi.

#Why primitives matter

The EntryGo API is small, but the system still exposes several durable objects. Clients should understand which objects are:

• source inputs
• planning outputs
• execution outputs
• read-model state

That keeps integrations from overfitting to one endpoint response.

#Primitive map

#Order

An Order is an account-scoped demand record the protocol can plan against.

Conceptually an order includes:

• a stable source-system identifier
• destination details
• line items
• product references

What clients should remember:

• orders are synced into EntryGo first
• planning uses the EntryGo order id, not only your externalId
• line items reference existing EntryGo productId values

#ExportBatch / Export

ExportBatch is the top-level orchestration object created by planning.

In machine-facing responses you will see export-oriented naming such as:

• exportId
• batch_id
• state
• status

Treat ExportBatch and Export as two views of the same durable object:

• ExportBatch is the orchestration and persistence idea
• Export is the public protocol view that clients interact with

This is the object you will plan, execute, inspect, and store locally for later reconciliation.

#ExportUnit

An ExportUnit is a grouping inside an export batch.

Today the implementation maps one synced order per unit in the current planning result, but clients should not assume that mapping is permanent. The concept exists so EntryGo can express grouping decisions independently of one top-level batch.

That matters if the grouping strategy evolves later.

#CustomsPackage

A CustomsPackage is the package-level execution object created during export execution.

It contains package metadata and the generated artifact inventory. It is not the same thing as a customs filing. It is the protocol-side package the rest of the export workflow can reason about.

Clients typically encounter it in one of two ways:

• as customs_package_id on execute or inspect
• by fetching GET /api/customs-packages/{id}

#Artifact

An Artifact is a generated file record attached to a customs package.

Artifacts are surfaced as metadata, not as a promise about transport or download mechanics. The stable parts are the machine fields that tell clients:

• what was generated
• what the filename is
• when generation occurred

Artifacts exist so automation and AI agents can reason about document availability without parsing a UI.

#Notification

A Notification is a protocol-managed partner communication record.

In the current implementation notifications represent operational communication outcomes related to warehouses and brokers. Notifications are mutable operational records.

That makes them different from events.

#ExportEvent

An ExportEvent is an immutable lifecycle fact.

Events tell clients that something happened at a particular point in the lifecycle. They are useful for:

• audit trails
• automation monitoring
• debugging
• agent reconciliation

If you need current mutable partner-delivery state, look at notifications or broker submission. If you need immutable history, look at events.

#BrokerSubmission

A BrokerSubmission is the protocol’s record of broker-facing package delivery.

Today it models a lean email-based transport and typically includes:

• identifier
• submission type
• status
• recipient email
• subject
• timestamps
• error message when relevant

Clients should not treat broker delivery as a private side channel. It is part of export execution and therefore belongs in the protocol state.

#What to persist locally

Most clients should persist at least:

• EntryGo order IDs from order sync
• exportId
• planHash
• customs_package_id when package lookups matter

That small set of identifiers is usually enough to re-enter the protocol safely after process restarts, human review, or automation failures.