# Zinc API agent quickstart

Buy products from major retailers with one API. This guide gets you from
nothing to a delivered (sandbox) order in about two minutes. No account
needed.

## 1. Get a sandbox API key

    curl -X POST https://api.zinc.com/sandbox/keys

Optional JSON body: {"email": "<your operator's email, for claiming this
sandbox later>", "name": "<what this key is for>"}. An empty body works.

The response contains `api_key` (`zn_test_...`). Send it on every request as
`Authorization: Bearer <api_key>`. A test key routes to the sandbox
automatically — no extra headers needed. Keys expire after
7 days without use; mint another any time (a few per
day per IP).

## 2. Place a sandbox order

    curl -X POST https://api.zinc.com/orders \
      -H "Authorization: Bearer $ZINC_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "products": [{"url": "https://zinc.com/shop/products/test-success", "quantity": 1}],
        "shipping_address": {
          "first_name": "Sandbox", "last_name": "Agent",
          "address_line1": "101 Market St", "city": "San Francisco",
          "state": "CA", "postal_code": "94105",
          "phone_number": "4155552671", "country": "US"
        },
        "max_price": 2500
      }'

`max_price` (cents) is the ceiling you authorize for the order — required on
every order. Do not set `idempotency_key` unless you generate a fresh UUID
for it (one is generated for you when omitted).

## 3. Watch it happen

    curl https://api.zinc.com/orders/<order_id> -H "Authorization: Bearer $ZINC_KEY"

Sandbox orders run the real lifecycle on a compressed clock. `status`
becomes `order_placed` in ~30-120s — that IS the terminal status of a
successful order (or `order_failed` for a failed one). Shipping progress
then appears in `tracking_numbers[]`: a tracking number attaches and its
own `status` advances through `shipped` to `delivered` over the next
~1-3 minutes.

Prefer webhooks? Register a URL (test mode has its own webhook config,
separate from live):

    curl -X POST https://api.zinc.com/users -H "Authorization: Bearer $ZINC_KEY" \
      -H "Content-Type: application/json" \
      -d '{"webhook_url": "https://your-server.example/webhooks/zinc"}'

## 4. Learn the failure shapes

Swap the product slug to rehearse each error. Async failures (order accepted,
then fails — watch the order status):
- `test-success` — order places, ships, and delivers normally
- `test-price-exceeded` — fails after placement with `max_price_exceeded`
- `test-out-of-stock` — fails after placement with `out_of_stock`
- `test-invalid-variant` — fails after placement with `invalid_variant`
- `test-shipping-unavailable` — fails after placement with `shipping_unavailable`

Synchronous failures (rejected at `POST /orders` time):
- `test-invalid-address` — rejected at creation (400)
- `test-url-unreachable` — rejected at creation (400)
- `test-insufficient-funds` — rejected at creation (402-style insufficient funds)

Any other product URL (e.g. a real Amazon URL) succeeds in the sandbox.

## 5. Claim it, then go live

You don't have to start over. The mint response includes a `claim_url` —
give it to the human you work for. When they sign in there, this sandbox
(its order history and this key) folds into their Zinc account, and **your
key keeps working**. Poll `GET /sandbox/status` with your key to find out
when that's happened:

    curl https://api.zinc.com/sandbox/status -H "Authorization: Bearer $ZINC_KEY"

Sandbox keys never place real orders, claimed or not. To buy for real, the
account owner mints a live key (`zn_live_...`) at https://app.zinc.com and funds a
wallet. The API surface is identical — change the key, keep your code.

Full API reference: https://api.zinc.com/openapi.json