SMS & eSIM Reseller API.

# Production only. Placeholder key; there is no free sandbox.
export PORTPROOF_API_KEY='YOUR_PORTPROOF_API_KEY'
export API='https://api.portproof.org/v1'
# cURL 7.76+, jq and uuidgen. Restrict files containing customer delivery data.
umask 077
# Browse service/country choices. Requires digital:read.
curl --fail-with-body -sS -H "Authorization: Bearer $PORTPROOF_API_KEY" "$API/digital/reseller/catalog?family=sms&digital_kind=sms_activation&limit=60" > catalog.json
jq '.facets, (.products[] | {sku,title,sell_cents,currency,available,digital_details})' catalog.json
# eSIM: select an available compatible plan, then use the same purchase steps.
curl --fail-with-body -sS -H "Authorization: Bearer $PORTPROOF_API_KEY" "$API/digital/reseller/catalog?family=esim&limit=60" > esim-catalog.json
jq '.products[] | {sku,title,sell_cents,currency,available,digital_details}' esim-catalog.json

# Download both families, including unavailable products. Requires digital:read.
for FAMILY in sms esim; do
  PAGE=1
  while :; do
    curl --fail-with-body -sS -H "Authorization: Bearer $PORTPROOF_API_KEY" "$API/digital/reseller/catalog?family=$FAMILY&limit=60&page=$PAGE&sort=price_asc" > "$FAMILY-$PAGE.json" || exit 1
    jq '.products[] | {sku,title,sell_cents,currency,available,availability_note,digital_details}' "$FAMILY-$PAGE.json"
    [ "$(jq -r .has_more "$FAMILY-$PAGE.json")" = true ] || break
    PAGE=$((PAGE + 1))
  done
done

# Replace with an available Portproof SKU from the catalogue. One product per request.
export SKU='REPLACE_WITH_SELECTED_PORTPROOF_SKU'
curl --fail-with-body -sS -H "Authorization: Bearer $PORTPROOF_API_KEY" \
  "$API/digital/prices/$SKU" > price.json || exit 1
jq . price.json
# Review total_cents (EUR cents, including applicable VAT) before proceeding.
# Prepare ONCE per intended purchase and save durably. Do not overwrite on a retry.
KEY=$(uuidgen)
jq -n --arg key "$KEY" --slurpfile p price.json \
  '{key:$key,request:{sku:$p[0].sku,expected_total_cents:$p[0].total_cents,accept_terms:true}}' > purchase-intent.json

# SPENDS WALLET FUNDS. accept_terms accepts the linked policies and immediate start.
# For network failure/429/5xx, retry this exact saved intent with the same key.
# Never generate a fresh key to recover an uncertain purchase.
jq '.request' purchase-intent.json > purchase-request.json
curl --fail-with-body -sS --max-time 30 -X POST "$API/digital/purchases" \
  -H "Authorization: Bearer $PORTPROOF_API_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(jq -r .key purchase-intent.json)" \
  --data-binary @purchase-request.json > purchase.json || exit 1
jq '{method,order_id:.order.id,status:.order.status,total_cents:.order.total_cents,replayed}' purchase.json
ORDER_ID=$(jq -er .order.id purchase.json)
# Read the current order. 201/paid means payment accepted, not delivered.
curl --fail-with-body -sS -H "Authorization: Bearer $PORTPROOF_API_KEY" "$API/orders/$ORDER_ID" > order.json

# Serial cached polling, at most 40 attempts, for either product family.
# HTTP errors stop this cURL loop. For 429, wait Retry-After before resuming.
READY=false
for attempt in $(seq 1 40); do
  curl --fail-with-body -sS --max-time 20 -H "Authorization: Bearer $PORTPROOF_API_KEY" "$API/orders/$ORDER_ID" > order.json || exit 1
  if jq -e '.order.status as $s | (["failed","refunded","failed_refunded","cancelled","expired"] | index($s)) != null' order.json >/dev/null || \
     jq -e 'any(.order.items[]; .status == "held" or .status == "failed" or .status == "refunded")' order.json >/dev/null; then
    echo 'Stop: inspect order or contact Portproof; do not repurchase.'; exit 1
  fi
  ASSET_ID=$(jq -r '[.order.items[].fulfilment_ref | select(. != null and startswith("dga_"))][0] // empty' order.json)
  if [ -n "$ASSET_ID" ]; then
    curl --fail-with-body -sS --max-time 20 -H "Authorization: Bearer $PORTPROOF_API_KEY" "$API/digital/assets/$ASSET_ID" > asset.json || exit 1
    if jq -e '.asset.status as $s | (["expired","cancelled","refunded","unknown"] | index($s)) != null' asset.json >/dev/null; then
      echo 'Asset ended or needs review'; exit 1
    fi
    # eSIM installation: never query the SMS endpoint for an eSIM.
    if [ "$(jq -r .asset.kind asset.json)" = esim_plan ]; then
      if [ "$(jq -r .asset.installation_available asset.json)" = true ]; then
        curl --fail-with-body -sS -H "Authorization: Bearer $PORTPROOF_API_KEY" "$API/digital/assets/$ASSET_ID/installation" > installation.json || exit 1
        READY=true; break
      fi
    else
      # phone_number is in private asset.json, even while status is processing.
      curl --fail-with-body -sS -H "Authorization: Bearer $PORTPROOF_API_KEY" "$API/digital/assets/$ASSET_ID/messages" > messages.json || exit 1
      if jq -e 'any(.data[]; .content_withheld == false and ((.code // "") != "" or (.text // "") != ""))' messages.json >/dev/null; then
        READY=true; break
      fi
      if jq -e '.asset.status == "completed" or .asset.status == "code_received"' asset.json >/dev/null; then
        echo 'Polling stopped; inspect saved history or contact support'; exit 1
      fi
    fi
  fi
  sleep 15
done
[ "$READY" = true ] || { echo 'Still waiting; save order and resume later, no new purchase.'; exit 1; }
# Treat all files as private; deliver only to your authorised end customer.
# Follow messages.next_cursor (URL-encoded) until null for additional saved history.
# qr_url is relative to the API origin, requires auth, and must be fetched server-side.

# Read saved state; digital:read. These calls do not buy anything.
curl --fail-with-body -sS -H "Authorization: Bearer $PORTPROOF_API_KEY" "$API/digital/assets/$ASSET_ID" > asset.json
# Execute only when asset.installation_available is true. Treat output as a secret.
curl --fail-with-body -sS -H "Authorization: Bearer $PORTPROOF_API_KEY" "$API/digital/assets/$ASSET_ID/installation" > installation.json
# {installation:{activation_code,smdp_address,lpa_uri,qr_url,iccid}}
# For the authenticated QR image:
curl --fail-with-body -sS -H "Authorization: Bearer $PORTPROOF_API_KEY" "$API/digital/assets/$ASSET_ID/qr.png" -o installation-private.png

# Read-only eligible top-ups; product_id is Portproof's opaque option ID.
curl --fail-with-body -sS -H "Authorization: Bearer $PORTPROOF_API_KEY" \
  "$API/digital/assets/$ASSET_ID/topups" > topups.json
TOPUP_ID=$(jq -er '.data[0].product_id' topups.json) || exit 1
jq -n --arg id "$TOPUP_ID" '{action:"esim_topup",product_id:$id}' > quote-request.json
curl --fail-with-body -sS -X POST -H "Authorization: Bearer $PORTPROOF_API_KEY" \
  -H 'Content-Type: application/json' --data-binary @quote-request.json \
  "$API/digital/assets/$ASSET_ID/quotes" > quote.json || exit 1
jq . quote.json
# Review total_cents and expires_at. Quote expires after 5 minutes; no stock reservation.
# SPENDS WALLET FUNDS. Save key + body before execution; reuse both on retry.
ACTION_KEY=$(uuidgen)
jq '{quote_id:.quote.id,expected_total_cents:.quote.total_cents,confirm:true,accept_terms:true}' quote.json > action-request.json
printf '%s' "$ACTION_KEY" > action-key.txt
curl --fail-with-body -sS -X POST -H "Authorization: Bearer $PORTPROOF_API_KEY" \
  -H 'Content-Type: application/json' -H "Idempotency-Key: $(cat action-key.txt)" \
  --data-binary @action-request.json "$API/digital/assets/$ASSET_ID/execute" > operation.json || exit 1
OP_ID=$(jq -er .operation.id operation.json)
curl --fail-with-body -sS -H "Authorization: Bearer $PORTPROOF_API_KEY" "$API/digital/operations/$OP_ID"
# SMS lifecycle actions use the same quote/execute contract, without product_id:
# {"action":"sms_complete"}, {"action":"sms_reuse"}, {"action":"sms_paid_reuse"}
# Only request actions listed in asset.actions; inspect every quote before execute.
# sms_cancel can require owner refund review; do not assume an automatic refund.

// Node.js 22+. Run only after reviewing/saving purchase-intent.json above.
// SPENDS FUNDS by submitting that saved purchase; reruns use the same identity.
import { readFile, writeFile } from 'node:fs/promises';
const API = 'https://api.portproof.org/v1';
const token = process.env.PORTPROOF_API_KEY;
if (!token) throw new Error('Set PORTPROOF_API_KEY securely');
const intent = JSON.parse(await readFile('purchase-intent.json', 'utf8'));
const deadline = Date.now() + 10 * 60 * 1000;
const pause = ms => {
  if (Date.now() + ms >= deadline) throw new Error('Deadline reached; save order and resume later');
  return new Promise(resolve => setTimeout(resolve, ms));
};
async function call(path, body, key) {
  for (let attempt = 0; attempt < 4; attempt++) {
    if (Date.now() >= deadline) throw new Error('Deadline reached; resume saved order later');
    let r;
    try { r = await fetch(API + path, { method: body ? 'POST' : 'GET',
      headers: { Authorization: 'Bearer ' + token, 'Content-Type': 'application/json',
        ...(key ? { 'Idempotency-Key': key } : {}) },
      body: body ? JSON.stringify(body) : undefined, signal: AbortSignal.timeout(Math.max(1, Math.min(20000, deadline - Date.now()))) }); }
    catch { if (attempt === 3) throw new Error('Outcome unconfirmed; keep saved key and request');
      await pause(2000 * 2 ** attempt); continue; }
    if (r.status === 429 || r.status >= 500) {
      if (attempt === 3) throw new Error('Service pending/unavailable; resume same saved request');
      const retry = Number(r.headers.get('retry-after'));
      await pause(Math.max(2 ** attempt * 2000, Number.isFinite(retry) ? retry * 1000 : 0)); continue;
    }
    const data = await r.json();
    if (!r.ok) throw new Error('HTTP ' + r.status + ': ' + (data.code || 'request_failed'));
    return data;
  }
}
const paid = await call('/digital/purchases', intent.request, intent.key);
const id = paid.order.id;
console.log('Saved order', id); // store this against your own customer order
for (let n = 0; n < 40; n++) {
  const { order } = await call('/orders/' + id);
  if (['failed','refunded','failed_refunded','cancelled','expired'].includes(order.status) ||
      order.items.some(i => ['held','failed','refunded'].includes(i.status)))
    throw new Error('Stop: order needs review; do not buy again');
  const assetId = order.items.find(i => i.fulfilment_ref?.startsWith('dga_'))?.fulfilment_ref;
  if (assetId) {
    const { asset } = await call('/digital/assets/' + assetId);
    if (['expired','cancelled','refunded','unknown'].includes(asset.status))
      throw new Error('Stop: ' + asset.status);
    if (asset.kind === 'esim_plan' && asset.installation_available) {
      const details = await call('/digital/assets/' + assetId + '/installation');
      // Deliver through your authenticated customer portal; never log installation secrets.
      await writeFile('installation-private.json', JSON.stringify(details), { mode: 0o600, flag: 'wx' });
      console.log('Installation ready'); break;
    }
    if (asset.kind !== 'esim_plan') {
      let cursor = null, received = false;
      do {
        const page = await call('/digital/assets/' + assetId + '/messages' +
          (cursor ? '?cursor=' + encodeURIComponent(cursor) : ''));
        received ||= page.data.some(m => !m.content_withheld && (m.code || m.text));
        // Process privately here; phone_number is on asset. Do not log messages.
        cursor = page.next_cursor;
      } while (cursor && !received);
      if (received) { console.log('SMS available for authorised delivery'); break; }
      if (['completed','code_received'].includes(asset.status))
        throw new Error('Automatic polling stopped; inspect saved history or contact support');
    }
  }
  if (n === 39) throw new Error('Still waiting; save order and resume later, no new purchase');
  await pause(15000);
}

# Python 3.10+, standard library only. Same reviewed purchase-intent.json as cURL.
# SPENDS FUNDS once; retries and reruns submit the identical saved intent.
import json, os, time
from urllib.request import Request, urlopen
from urllib.error import HTTPError, URLError
API = 'https://api.portproof.org/v1'
HEADERS = {'Authorization': 'Bearer ' + os.environ['PORTPROOF_API_KEY']}
deadline = time.monotonic() + 600
def pause(seconds):
    if time.monotonic() + seconds >= deadline:
        raise RuntimeError('Deadline reached; resume saved order later')
    time.sleep(seconds)
with open('purchase-intent.json') as f:
    intent = json.load(f)
def call(path, body=None, key=None):
    for attempt in range(4):
        if time.monotonic() >= deadline:
            raise RuntimeError('Deadline reached; resume saved order later')
        try:
            request = Request(API + path,
                data=json.dumps(body).encode() if body is not None else None,
                headers={**HEADERS, 'Content-Type': 'application/json',
                         **({'Idempotency-Key': key} if key else {})},
                method='POST' if body is not None else 'GET')
            try:
                r = urlopen(request, timeout=max(0.1, min(20, deadline - time.monotonic())))
            except HTTPError as error:
                r = error
        except (URLError, TimeoutError, OSError):
            if attempt == 3:
                raise RuntimeError('Outcome unconfirmed; keep saved key and request')
            pause(2 * 2 ** attempt)
            continue
        status, headers = r.code, r.headers
        raw = r.read()
        r.close()
        if status == 429 or status >= 500:
            if attempt == 3:
                raise RuntimeError('Service pending/unavailable; resume same saved request')
            try:
                wait = float(headers.get('Retry-After', '0'))
            except ValueError:
                wait = 0
            pause(max(2 * 2 ** attempt, wait))
            continue
        data = json.loads(raw)
        if not 200 <= status < 300:
            raise RuntimeError(f"HTTP {status}: {data.get('code', 'request_failed')}")
        return data
paid = call('/digital/purchases', intent['request'], intent['key'])
order_id = paid['order']['id']
print('Saved order', order_id)
for n in range(40):
    order = call('/orders/' + order_id)['order']
    if order['status'] in ('failed','refunded','failed_refunded','cancelled','expired') or any(
            i['status'] in ('held','failed','refunded') for i in order['items']):
        raise RuntimeError('Stop: order needs review; do not buy again')
    asset_id = next((i['fulfilment_ref'] for i in order['items']
        if (i.get('fulfilment_ref') or '').startswith('dga_')), None)
    if asset_id:
        asset = call('/digital/assets/' + asset_id)['asset']
        if asset['status'] in ('expired','cancelled','refunded','unknown'):
            raise RuntimeError('Stop: ' + asset['status'])
        if asset['kind'] == 'esim_plan' and asset['installation_available']:
            details = call('/digital/assets/' + asset_id + '/installation')
            fd = os.open('installation-private.json', os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
            with os.fdopen(fd, 'w') as f:
                json.dump(details, f)  # deliver privately through an authenticated portal
            print('Installation ready')
            break
        if asset['kind'] != 'esim_plan':
            cursor, received = None, False
            while True:
                from urllib.parse import quote
                path = '/digital/assets/' + asset_id + '/messages'
                page = call(path + ('?cursor=' + quote(cursor, safe='') if cursor else ''))
                received = any(not m['content_withheld'] and (m['code'] or m['text']) for m in page['data'])
                # Process privately here; phone_number is on asset. Never log messages.
                cursor = page['next_cursor']
                if received or not cursor:
                    break
            if received:
                print('SMS available for authorised delivery')
                break
            if asset['status'] in ('completed','code_received'):
                raise RuntimeError('Polling stopped; inspect history or contact support')
    if n == 39:
        raise RuntimeError('Still waiting; save order and resume later, no new purchase')
    pause(15)