terra-vantage

Browse the three-level catalog with GET /api/v1/products down to variants, then POST /api/v1/orders with a variant_id, quantity, recipient, and collection_type AT_HOME with a shipping_address. Send an Idempotency-Key header so retried creations do not double-order.

Webhooks carry an X-Terra-Signature header formatted t=<unix_seconds>,v1=<hex>. Compute HMAC-SHA256 over "{t}.{raw_body}" with your signing secret and compare in constant time; the timestamp is in seconds, not milliseconds, and you must use the raw request body.

AT_HOME ships a self-collection kit to the recipient's shipping_address, while GO_TO_LAB routes the sample draw to a lab site near the requested_lab_address. Use GET /api/v1/labs?zip_code= to offer nearby draw sites and bind the choice via requested_lab on order creation.

Order, item, recipient, and test-taker IDs are 64-bit snowflakes serialized as JSON strings. Parsing them as numbers loses precision in JavaScript, so always keep them as strings; catalog reads still return numeric ids.

Yes, acknowledgment is mandatory and must be triggered by an explicit end-user action after viewing results, never automatically by your backend. Skipping it blocks patient access, transfers liability to your organization, and lets suppliers contact patients directly after the acknowledgment_due_by deadline.

Use POST /api/v1/orders/{orderID}/simulate with an event name to apply any lifecycle transition, including failure paths like sample_rejected, with the signed webhook delivered. Alternatively the sandbox supplier auto-progresses orders on timers after browser-based kit activation.