Tracium overview

Tracium es la capa de trazabilidad. Estandariza eventos de Captia o cualquier fuente de ingestion, los valida contra el process map del tenant, ancla los eventos críticos on-chain, y auto-genera bundles regulatorios por framework.

Qué podés hacer vía API

Capacidad	Surface	Estado
Enviar eventos (flow de prepared transaction)	`POST /api/v1/events/prepare` + firmar client-side + enviar a chain	shipped
Validar payload sin gastar gas	`POST /api/v1/events/validate`	shipped
Querear eventos por lote / actor / período	`GET /api/v1/events`, `GET /api/v1/events/:id`, `GET /api/v1/events/nft/:tokenId`	shipped
Querear inventario NFT + linaje	`GET /api/v1/nfts`, `GET /api/v1/nfts/:tokenId`, `GET /api/v1/nfts/tlc/:tlc`, `/ancestry`, `/descendants`, `/relations`	shipped
Huella de carbono / ambiental (agregada por árbol)	`GET /api/v1/nfts/:tokenId/footprint`	shipped
Análisis de impacto de recall	`GET /api/v1/nfts/:tokenId/recall-impact`	shipped
Recall on-chain (TENANT_ADMIN)	`POST /api/v1/nfts/recall/prepare` + firmar	shipped
Transferencia de custodia (prepare + sign)	`POST /api/v1/custody/prepare`, `GET /api/v1/custody/nft/:tokenId`, `GET /api/v1/custody/org/:orgId`	shipped
Track tx submitted	`POST /api/v1/tx/track`, `POST /api/v1/tx/track/status`, `GET /api/v1/tx/track/mine`	shipped
Reportes operacionales (alerts, documents, supplier perf, yields, inventory)	`GET /api/v1/reports/*`	shipped
Bundles regulatorios FSMA 204	servicio separado `traceability-reports`	shipped en otro repo
Bundles EUDR / USMCA / IATF / ESPR DPP	mapping en spec, endpoint pendiente	roadmap
Webhooks para downstream	`POST /api/v1/webhooks` (CRUD, TENANT_ADMIN)	shipped

La reference completa se auto-genera del OpenAPI spec en vivo — ver la sección Reference cuando shipee la integración de Phase 3.

El patrón “prepared transaction”

Muchas operaciones de write usan un flow de 3 pasos:

POST /api/v1/<resource>/prepare — el server valida el request, escribe metadata canónica a IPFS, construye la transacción no firmada, devuelve { preparedTx: { to, data, gasEstimate, chainId }, eventId, ipfsCid }.
El cliente firma + envía la transacción al chain RPC directamente, usando la wallet del actor (ethers.js, viem, MetaMask, hardware wallet).
(Opcional) POST /api/v1/tx/track — registrar el txHash resultante con Tracium para que monitoree confirmación + emita webhooks event.recorded cuando el bloque sea minado.

Por qué este flow:

La clave privada del actor nunca toca la plataforma.
El server valida reglas de negocio antes de que el cliente queme gas.
IPFS write es idempotente: mismo CID si re-llamás /prepare con el mismo payload.

Para integraciones server-to-server high-volume, hay un flow de managed wallet scopeada por API-key disponible — hablanos si lo necesitás para un deployment de producción.

Leer la chain

Para queries read-only (el caso común para retailers, auditores, análisis AI), no se requiere firmar. Bearer token o API key.

# Conseguir todos los eventos de un lote
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.darwinevolution.io/api/v1/events?tlc=LOT-2026-A1"

# Caminar el árbol de ancestros
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.darwinevolution.io/api/v1/nfts/$TOKEN_ID/ancestry"

(Reemplazá api.darwinevolution.io con la URL de tu sandbox durante evaluación. Ver Sandbox.)

Qué NO está en la API de Tracium

Captura en campo — eso es Captia (PWA mobile + conectores de ingestion). Los operadores no pegan a Tracium directamente.
Viewer de Digital Product Passport — eso es Fidenta. Experiencia QR consumer-facing.
Provisioning de tenant + admin — tooling CLI / ops interno, no expuesto públicamente.

Cross-links

Quickstart — enviar tu primer evento end-to-end
Autenticación — JWT + API key + DID
Webhooks — recibir eventos desde Tracium
Reportes de compliance — bundles regulatorios
On-chain vs off-chain — el split de datos