⌘K

Integration GuidesGuide

Examples

Copyable cURL and TypeScript examples for the current Partner API, webhooks and laboratory contract.

On this page

Setup

bash
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

bash
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

bash
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

typescript
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

bash
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

javascript
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.

bash
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"

Related resources