> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extractoseum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API and Automation

> Public verification endpoints (Smart COA, CVV) + integration API (X-EUM-Api-Key, scopes) + HMAC-SHA256 signed webhooks. For systems and AIs.

> 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)](vende-en-tu-shopify.md).

***

## Discovery for AIs / agents

These docs are made to be read by agents. Machine-readable entry points (no auth):

* **`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.

Use them so your agent understands what EXTRACTOS EUM® is, what it can verify, and which endpoints exist
before calling the API.

***

## A. Public verification endpoints (no authentication)

To verify a product's authenticity and contents — suitable for agents/AIs (rate-limited):

| Method | Path | What it returns |
| - | - | - |
| GET | `/api/v1/coas/:token` | The **Smart COA** by its public token |
| GET | `/api/v1/coas/preview/:token` | Public preview of the COA |
| GET | `/api/v1/coas/preview/qr/:qr_token` | Preview by QR token |
| GET·POST | `/api/v1/verify/:cvv` | Verifies a **CVV** (piece authenticity) |
| POST | `/api/v1/coas/preview/qr/:qr_token/verify-cvv` | Verifies the CVV paired to a QR |

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

For an external system (laboratory, seller) to send samples for analysis, register tracking numbers, and
receive notifications.

### 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`.
* **Rotation with grace period**: when rotated, the previous key stays valid \~24 h (config) so integrations
  aren't cut off.

### Endpoints (`/api/v1/integration/…`)

| Method | Path | Scope | Purpose |
| - | - | - | - |
| GET | `/me` | (any valid one) | Identity + scopes of your key |
| POST | `/analysis-orders` | `orders:create` | Create an analysis order |
| GET | `/analysis-orders` | `orders:read` | List your orders |
| GET | `/analysis-orders/:id` | `orders:read` | Detail of an order |
| PUT | `/analysis-orders/:id/tracking` | `orders:create` | Register the **tracking number** for the sample shipment |
| PUT | `/samples/:sample_token/metadata` | `samples:write` | Sample metadata (batch, weight, etc.) |
| POST | `/samples/:sample_token/photo` | `samples:write` | Attach a photo of the sample |
| POST | `/checkout` | `orders:create` | Generate the analysis payment |

> **Mandatory, validated tracking number:** when registering the tracking number via API, the same rule as in
> the portal applies — it's validated to be real (no "0000000000"), and without a tracking number the sample
> is not received at the laboratory.

### Webhooks (signed notifications)

EUM sends POST notifications to your endpoint when an order/sample's status changes. Each notification is
**signed**:

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

Verification example (Node/Express):

```js theme={null}
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](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.*

***

*In-depth lab integration manual (Part A integrator + Part B lab operator):
`docs/api-manual/EUM-API-Manual-Labs.pdf`. This page is the reconciled + verified public reference.*