EntryGoDocs
QuickstartProtocolAPI Reference

SDK

Python SDK

Protocol version: `EntryGo Export Protocol v1`

On this page

Machine-readable source of truth:

Related docs:

#What the SDK wraps

The Python SDK is a thin client over the current protocol endpoints under /api.

The default base_url is:

python
http://localhost:3000/api

So methods such as client.plan(...) call /api/exports/plan at runtime.

#Quickstart

python
import os
from shpbndl import SHPBNDL, SHPBNDLError

client = SHPBNDL(
    api_key=os.environ["SHPBNDL_API_KEY"],
    base_url=os.environ.get("ENTRYGO_BASE_URL", "http://localhost:3000/api"),
)

try:
    synced_orders = client.orders.sync(
        accountId="acc_123",
        items=[
            {
                "externalId": "ord-ext-1001",
                "destinationCountry": "US",
                "destinationRegion": "CA",
                "destinationPostalCode": "94105",
                "items": [
                    {
                        "productId": "prod_123",
                        "quantity": 1,
                        "unitValueUsd": 110,
                    }
                ],
                "metadata": {
                    "source": "sdk-py-example",
                },
            }
        ],
        idempotencyKey="orders-sync-001",
    )

    order_id = str(synced_orders["data"][0]["id"])

    plan = client.plan(
        accountId="acc_123",
        warehouseId="wh_123",
        brokerId="br_123",
        destinationCountry="US",
        orderIds=[order_id],
        idempotencyKey="plan-acc-123-001",
    )

    print(plan["exportId"], plan["planHash"], plan["readinessState"])

    if plan["readinessState"] == "BLOCKED":
        print(plan["validationMessages"])
        raise SystemExit(1)

    execution = client.execute(
        accountId="acc_123",
        batchId=plan["exportId"],
        idempotencyKey="execute-acc-123-001",
    )

    print(execution["customs_package_id"], execution["artifacts"])

    inspection = client.inspect(plan["exportId"])
    print(inspection["status"], inspection["notifications"], inspection["events"])

except SHPBNDLError as error:
    print(error.error_code, error.message, error.field, error.details)

#Current methods

Top-level:

  • client.plan(...)
  • client.execute(...)
  • client.inspect(export_id)

Grouped clients:

  • client.orders.sync(...)
  • client.products.sync(...)
  • client.exports.plan(...)
  • client.exports.execute(...)
  • client.exports.get(export_id)
  • client.exports.inspect(export_id)

Legacy compatibility:

  • client.exports.optimize(...) remains available as a compatibility alias, but the current contract should prefer plan(...)

#Request and response highlights

#orders.sync(...)

Important request fields:

  • accountId
  • items[].externalId
  • items[].destinationCountry
  • items[].items[].productId
  • items[].items[].quantity
  • items[].items[].unitValueUsd

Important response fields:

  • data
  • data[].id
  • data[].externalId
  • data[].totalValueUsd

Important rule:

  • planning expects EntryGo order IDs returned by order sync

#plan(...)

Important response fields:

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

#execute(...)

Important response fields:

  • exportId
  • customs_package_id
  • artifacts
  • notification_ids
  • execution_timestamp
  • brokerSubmission

#inspect(...)

Important response fields:

  • status
  • state
  • planHash
  • artifacts
  • customsPackage
  • notifications
  • brokerSubmission
  • events
  • snapshot

#Idempotency and automation guidance

Best practice:

  • pass idempotencyKey for orders.sync, plan, and execute
  • reuse the same key only for retries of the same logical operation
  • use inspect(...) after ambiguous failures or timeouts

For agent or workflow systems:

  • treat planHash as the planning fingerprint
  • branch on readinessState, validationMessages, status, and brokerSubmission

#Errors

The SDK raises SHPBNDLError with:

  • error_code
  • message
  • field
  • details

Common values:

  • VALIDATION_ERROR
  • INVALID_API_KEY
  • INVALID_ACCOUNT_SCOPE
  • INVALID_ORDER_REFERENCE
  • INVALID_EXPORT_STATE
  • IDEMPOTENCY_CONFLICT
  • NOT_FOUND

#Notes

  • The Python SDK returns dictionaries rather than generated typed models.
  • For full field definitions, use /docs/api/openapi.