Integration GuidesGuide
Examples
Copyable cURL and TypeScript examples for the current Partner API, webhooks and laboratory contract.
On this page
Setup
export SOLIA_API_BASE="https://app.soliadirect.com/api/public/partner/v1"
export SOLIA_API_KEY="<key>"Important
There is no Solia SDK. These examples call the HTTP contract directly.
Programs and Catalog
curl -s "$SOLIA_API_BASE/programs" -H "Authorization: Bearer $SOLIA_API_KEY"
curl -s "$SOLIA_API_BASE/programs/$PROGRAM_ID/catalog" -H "Authorization: Bearer $SOLIA_API_KEY"
curl -s "$SOLIA_API_BASE/programs/$PROGRAM_ID/requirements?item_id=$ITEM_ID" -H "Authorization: Bearer $SOLIA_API_KEY"Serviceability
curl -s -X POST "$SOLIA_API_BASE/serviceability" \
-H "Authorization: Bearer $SOLIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"program_id":"'"$PROGRAM_ID"'","item_id":"'"$ITEM_ID"'","region":"'"$REGION"'","collection":"'"$COLLECTION"'"}'Create and simulate a Sandbox order
const base = process.env.SOLIA_API_BASE;
if (!base || !process.env.SOLIA_API_KEY) throw new Error("Missing server-side configuration");
const headers = {
Authorization: `Bearer ${process.env.SOLIA_API_KEY}`,
"Content-Type": "application/json",
};
export async function createOrder(programId: string, itemId: string, collection: string, externalOrderId: string, externalSubjectId: string) {
const res = await fetch(`${base}/orders`, {
method: "POST",
headers: { ...headers, "Idempotency-Key": externalOrderId },
body: JSON.stringify({
external_order_id: externalOrderId,
program_id: programId,
item_id: itemId,
external_subject_id: externalSubjectId,
collection,
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error?.code} (request ${body.request_id})`);
return body.data;
}
export async function simulate(orderId: string) {
const res = await fetch(`${base}/sandbox/orders/${orderId}/simulate`, {
method: "POST",
headers,
body: JSON.stringify({ scenario: "happy_path" }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error?.code} (request ${body.request_id})`);
return body.data;
}Read order, results and events
curl -s "$SOLIA_API_BASE/orders/$ORDER_ID" -H "Authorization: Bearer $SOLIA_API_KEY"
curl -s "$SOLIA_API_BASE/orders/$ORDER_ID/results" -H "Authorization: Bearer $SOLIA_API_KEY"
curl -s "$SOLIA_API_BASE/events?limit=50" -H "Authorization: Bearer $SOLIA_API_KEY"Verify a webhook signature
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifySolia(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || !headers || typeof headers !== "object") return false;
if (typeof secret !== "string" || !secret) return false;
const timestamp = headers["x-solia-timestamp"];
const presented = headers["x-solia-signature"];
const deliveryId = headers["x-solia-delivery-id"];
const eventId = headers["x-solia-event-id"];
if (typeof timestamp !== "string" || !/^\d+$/.test(timestamp)) return false;
if (typeof presented !== "string" || !/^v1=[0-9a-f]{64}$/.test(presented)) return false;
if (typeof deliveryId !== "string" || !deliveryId.trim()) return false;
if (typeof eventId !== "string" || !eventId.trim()) return false;
const seconds = Number(timestamp);
if (!Number.isSafeInteger(seconds) || Math.abs(Date.now() / 1000 - seconds) > 300) return false;
const expected = createHmac("sha256", secret).update(timestamp + ".").update(rawBody).digest();
const actual = Buffer.from(presented.slice(3), "hex");
return actual.length === expected.length && timingSafeEqual(expected, actual);
}Signature verification has no delivery side effects. Atomically persist event-id-based idempotent processing and delivery records with successful business processing. A completed duplicate returns 2xx without reprocessing; verification alone must not consume a delivery. Use durable bounded storage, not a process-local set.
HTTPS/JSON laboratory endpoint
Your laboratory server receives POST <your base>/connection-test and POST <your base>/orders with X-Solia-Contract-Version: solia.lab.v1, X-Solia-Tenant-Id, X-Solia-Adapter-Key, X-Solia-Transmission-Id and Idempotency-Key. Respond 2xx within 15 seconds and deduplicate on the idempotency key.
Inbound lifecycle events are POSTed to /api/public/lab-events signed with X-Solia-Signature: v1=<hex HMAC-SHA256> over <X-Solia-Timestamp>.<raw body>. Send the configured laboratory API credential as Authorization: Bearer, separately from the inbound HMAC secret; never substitute a Partner key. Set BODY from the canonical synthetic envelope with its tenant, adapter, transmission and event identifiers. The exact body schema is published at /api/public/solia-lab-contract.
TS=$(date +%s)
SIG="v1=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$LAB_SIGNING_SECRET" -hex | sed 's/^.* //')"
curl -s -X POST "https://app.soliadirect.com/api/public/lab-events" \
-H "X-Solia-Timestamp: $TS" -H "X-Solia-Signature: $SIG" \
-H "Authorization: Bearer $LAB_API_CREDENTIAL" \
-H "Content-Type: application/json" --data-binary "$BODY"