postalform-machine-order

# PostalForm Machine Order

Use this workflow when an agent needs to send real postal mail (a physical print-and-mail order) reliably on the first attempt.

## Workflow

### 1. Collect inputs and choose address strategy

Require these inputs:
- `buyer_name`, `buyer_email`
- `sender_name`, `recipient_name`
- PDF source (`upload_token`, `{ download_url, file_id }`, data URL, or allowed `https` URL)
- Mailing options (`double_sided`, `color`, `mail_class`, `certified`)

For each party (`sender`, `recipient`), choose exactly one strategy:
- Manual address: `*_address_type: "Manual"` + `*_address_manual`
- Loqate address: `*_address_type: "Address"` + `*_address_id` + `*_address_text`

Do not mix manual + Loqate for the same party.

### 2. Build payload with strict idempotency

Generate a UUID `request_id` once and keep payload bytes stable across retries.

Set `buyer_email` every time (required for Stripe receipt routing).

For manual addresses:
- Include `line1`, `city`, `state`, `zip`
- Include `line2` only when it has a non-empty string value
- Omit optional fields instead of sending `null`

Use the tested template in `references/payload_templates.md`.

### 3. Preflight with validate endpoint (recommended)

Call:
- `POST https://postalform.com/api/machine/orders/validate`

If response is `200`, confirm:
- `quote.page_count` matches expected page count
- `quote.price_usd` and options are acceptable

If response is `422`, fix payload before paying.

### 4. Create order and settle x402 payment

Endpoint:
- `POST https://postalform.com/api/machine/orders`

Flow:
1. Send order payload without payment header.
2. Receive `402` with `PAYMENT-REQUIRED`.
3. Create payment using your wallet stack on the requested network.
4. Retry the exact same request body with `PAYMENT-SIGNATURE`.
5. Expect `202` and settlement metadata.

Payment client options:
- `purl` CLI (fastest path when available)
- Any x402-compliant client (`@x402/core`, `@x402/evm`, or equivalent custom signer flow...