API y Automatización

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

​

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

​

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

​

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/…)

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)

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

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 — í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.