API and Automation

Two surfaces: public verification endpoints (no auth, for consumers and AIs) and the integration API (with API key, for lab/seller systems operating machine-to-machine). Base URL: https://coa.extractoseum.com. Type: Reference. Audience: integrators and AIs. Status: v1 (2026-08-01, verified against the system). The in-depth lab integration manual lives in docs/api-manual/ (PDF + HTML). Have a Shopify store and want to sell EUM products? You don’t need this API — install the official app and use the app block. Go to Sell EUM on your Shopify (Collective).

Discovery for AIs / agents

• llms.txt — AI-readable index of the entire documentation (root of the docs site).
• GET https://coa.extractoseum.com/ara.md — system summary in Markdown, ready to import as an “external document” into an assistant.
• GET https://coa.extractoseum.com/ara.json — the same information in structured JSON.

A. Public verification endpoints (no authentication)

B. Integration API (machine-to-machine, with API key)

Authentication

• Header: X-EUM-Api-Key: <your_api_key> (opaque; hashed at rest).
• Scopes per key (validated per endpoint): orders:create, orders:read, samples:write. The full flow uses all three (new keys include them by default). A 403 with code: "falta_scope" says which one is missing and how to fix it.
• Rotation with grace period: when rotated, the previous key stays valid ~24 h (config) so integrations aren’t cut off.

Endpoints (/api/v1/integration/…)

The flow, in order (same as the portal)

1. Create the order (POST /analysis-orders; you can already send each sample’s data and presentation).
2. Pay (POST /checkout with sample_tokens) → open the invoice_url.
3. Complete the data of each sample that ships (PUT /samples/:token/metadata). Required: name, batch, weight and presentation (intake_faltantes tells you what’s missing). Bought several and shipping one today? Split it with POST /analysis-orders/:id/envio — each shipment has its own sheet and tracking number.
4. Shipping sheet (GET /analysis-orders/:id/submission-pdf): print it and put it in the package. Marks the samples as shipped.
5. Tracking number (PUT /analysis-orders/:id/tracking). Without the sheet it returns 409 hoja_pendiente.

Not sure which step you’re on? GET /analysis-orders/:id → siguiente_paso.code (pagar · completar_datos · generar_hoja · registrar_guia · en_camino · en_laboratorio · resultados_listos) and siguiente_paso.endpoint.

Mandatory, validated tracking number: same rule as the portal — it’s validated to be real (no “0000000000”), it goes after the sheet, and without it the sample is not received at the laboratory.

Webhooks (signed notifications)

• Headers: X-EUM-Event, X-EUM-Delivery-Id, X-EUM-Timestamp (unix s), X-EUM-Signature.
• Signature: HMAC-SHA256 (base64) of the raw body with your endpoint’s secret.
• Always verify: recompute the HMAC and reject if it doesn’t match; also reject if the timestamp is >5 min off (anti-replay). Retries with backoff (2/10/30…) on failure.

import crypto from 'crypto';
function verify(rawBody, headers, secret) {
  const ts = Number(headers['x-eum-timestamp']);
  if (!ts || Math.abs(Date.now()/1000 - ts) > 300) return false;   // >5 min → replay
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('base64');
  const got = headers['x-eum-signature'] || '';
  return expected.length === got.length &&
         crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got));
}

C. For AIs / agents

• Start with llms.txt — machine-readable index of these docs.
• The endpoints in section A require no auth: an AI can verify a Smart COA or a CVV directly.
• The integration API (section B) requires an API key with scopes — request it from the EUM team.
• Roadmap: an “eum-docs” agent skill (in the style of stripe-docs) so your AI can consume these docs and the API.