> ## 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 y Automatización

> Endpoints públicos de verificación (Smart COA, CVV) + API de integración (X-EUM-Api-Key, scopes) + webhooks firmados HMAC-SHA256. Para sistemas e IAs.

> Dos superficies: **endpoints públicos de verificación** (sin auth, para consumidores e IAs) y la **API de
> integración** (con API key, para sistemas de laboratorio/seller que operan máquina-a-máquina). Base URL:
> `https://coa.extractoseum.com`.
>
> **Tipo:** Referencia. **Audiencia:** integradores e IAs. **Estado:** v1 (2026-08-01, verificado contra el
> sistema). El manual profundo de integración de laboratorios vive en `docs/api-manual/` (PDF + HTML).
>
> **¿Tienes una tienda Shopify y quieres vender productos de EUM?** No necesitas esta API — instala la app
> oficial y usa el app block. Ve a [Vende EUM en tu Shopify (Collective)](vende-en-tu-shopify.md).

***

## Discovery para IAs / agentes

Estos docs están hechos para ser leídos por agentes. Puntos de entrada legibles por máquina (sin auth):

* **`llms.txt`** — índice AI-readable de toda la documentación (raíz del sitio de docs).
* **`GET https://coa.extractoseum.com/ara.md`** — resumen del sistema en Markdown, listo para importarse como
  "documento externo" en un asistente.
* **`GET https://coa.extractoseum.com/ara.json`** — la misma información en JSON estructurado.

Úsalos para que tu agente entienda qué es EXTRACTOS EUM™, qué puede verificar y qué endpoints existen antes de
llamar a la API.

***

## A. Endpoints públicos de verificación (sin autenticación)

Para verificar autenticidad y contenido de un producto — aptos para agentes/IA (rate-limited):

| Método   | Ruta                                           | Qué devuelve                                |
| -------- | ---------------------------------------------- | ------------------------------------------- |
| GET      | `/api/v1/coas/:token`                          | El **Smart COA** por su token público       |
| GET      | `/api/v1/coas/preview/:token`                  | Preview público del COA                     |
| GET      | `/api/v1/coas/preview/qr/:qr_token`            | Preview por token de QR                     |
| GET·POST | `/api/v1/verify/:cvv`                          | Verifica un **CVV** (autenticidad de pieza) |
| POST     | `/api/v1/coas/preview/qr/:qr_token/verify-cvv` | Verifica el CVV emparejado a un QR          |

## B. API de integración (máquina-a-máquina, con API key)

Para que un sistema externo (laboratorio, seller) envíe muestras a análisis, registre guías y reciba avisos.

### Autenticación

* Header: **`X-EUM-Api-Key: <tu_api_key>`** (opaca; hasheada en reposo).
* **Scopes** por key (se validan por endpoint): `orders:create`, `orders:read`, `samples:write`.
* **Rotación con gracia**: al rotar, la key anterior sigue válida \~24 h (config) para no cortar integraciones.

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

| Método | Ruta                              | Scope               | Para qué                                      |
| ------ | --------------------------------- | ------------------- | --------------------------------------------- |
| GET    | `/me`                             | (cualquiera válida) | Identidad + scopes de tu key                  |
| POST   | `/analysis-orders`                | `orders:create`     | Crear orden de análisis                       |
| GET    | `/analysis-orders`                | `orders:read`       | Listar tus órdenes                            |
| GET    | `/analysis-orders/:id`            | `orders:read`       | Detalle de una orden                          |
| PUT    | `/analysis-orders/:id/tracking`   | `orders:create`     | Registrar la **guía** del envío de la muestra |
| PUT    | `/samples/:sample_token/metadata` | `samples:write`     | Metadatos de la muestra (lote, peso, etc.)    |
| POST   | `/samples/:sample_token/photo`    | `samples:write`     | Adjuntar foto de la muestra                   |
| POST   | `/checkout`                       | `orders:create`     | Generar el cobro del análisis                 |

> **Guía obligatoria y validada:** al registrar la guía por API aplica la misma regla que en el portal —
> se valida que sea real (nada de "0000000000") y sin guía no se recibe la muestra en laboratorio.

### Webhooks (avisos firmados)

EUM envía avisos POST a tu endpoint cuando cambia el estado de una orden/muestra. Cada aviso va **firmado**:

* Headers: `X-EUM-Event`, `X-EUM-Delivery-Id`, `X-EUM-Timestamp` (unix s), **`X-EUM-Signature`**.
* **Firma:** HMAC-SHA256 (base64) del **body crudo** con el secret de tu endpoint.
* **Verifica siempre:** recomputa el HMAC y rechaza si no coincide; rechaza también si el timestamp tiene
  **>5 min de desfase** (anti-replay). Reintentos con backoff (2/10/30…) ante fallos.

Ejemplo de verificación (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. Para IAs / agentes

* Empieza por **[llms.txt](llms.txt)** — índice legible por máquina de estos docs.
* Los endpoints de la sección A no requieren auth: una IA puede verificar un Smart COA o un CVV directamente.
* La API de integración (sección B) requiere API key con scopes — pídela al equipo EUM.
* *Roadmap: skill de agente "eum-docs" (estilo `stripe-docs`) para que tu IA consuma estos docs y la API.*

***

*Manual profundo de integración de laboratorios (Parte A integrador + Parte B operador de laboratorio):
`docs/api-manual/EUM-API-Manual-Labs.pdf`. Esta página es la referencia pública reconciliada + verificada.*