Tracium overview

Tracium es la capa de trazabilidad. Estandariza eventos de Captia o cualquier fuente de ingesta, los valida contra el mapa de procesos del tenant, ancla los eventos críticos on-chain, y auto-genera paquetes regulatorios por normativa.

Qué podés hacer vía API

Capacidad	Superficie	Estado
Enviar eventos (flujo de prepared transaction)	`POST /api/v1/events/prepare` + firmar del lado del cliente + enviar a chain	Disponible
Validar payload sin gastar gas	`POST /api/v1/events/validate`	Disponible
Consultar eventos por lote / actor / período	`GET /api/v1/events`, `GET /api/v1/events/:id`, `GET /api/v1/events/nft/:tokenId`	Disponible
Consultar inventario NFT + linaje	`GET /api/v1/nfts`, `GET /api/v1/nfts/:tokenId`, `GET /api/v1/nfts/tlc/:tlc`, `/ancestry`, `/descendants`, `/relations`	Disponible
Huella de carbono / ambiental (agregada por árbol)	`GET /api/v1/nfts/:tokenId/footprint`	Disponible
Análisis de impacto de recall	`GET /api/v1/nfts/:tokenId/recall-impact`	Disponible
Recall on-chain (TENANT_ADMIN)	`POST /api/v1/nfts/recall/prepare` + firmar	Disponible
Transferencia de custodia (prepare + sign)	`POST /api/v1/custody/prepare`, `GET /api/v1/custody/nft/:tokenId`, `GET /api/v1/custody/org/:orgId`	Disponible
Rastreo de tx submitted	`POST /api/v1/tx/track`, `POST /api/v1/tx/track/status`, `GET /api/v1/tx/track/mine`	Disponible
Reportes operacionales (alerts, documents, supplier perf, yields, inventory)	`GET /api/v1/reports/*`	Disponible
Paquetes regulatorios FSMA 204	Servicio dedicado de reportes regulatorios	Disponible
Paquetes EUDR / USMCA / IATF / ESPR DPP	Bajo demanda	Disponible bajo demanda
Webhooks para downstream	`POST /api/v1/webhooks` (CRUD, TENANT_ADMIN)	Disponible

La reference completa se auto-genera del OpenAPI spec en vivo. Ver la sección Reference.

El patrón “prepared transaction”

Muchas operaciones de escritura usan un flujo de 3 pasos:

POST /api/v1/<resource>/prepare: el servidor 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 flujo:

La clave privada del actor nunca toca la plataforma.
El servidor 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 flujo de wallet gestionada con alcance por API-key disponible. Hablanos si lo necesitás para un despliegue de producción.

Leer la chain

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

Reemplazá <API_BASE_URL> por la URL base de tu sandbox o de producción (la recibís en el correo de aprovisionamiento; ver Sandbox).

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

# Caminar el árbol de ancestros
curl -H "Authorization: Bearer $TOKEN" \
  "<API_BASE_URL>/api/v1/nfts/$TOKEN_ID/ancestry"

Qué NO está en la API de Tracium

Captura en campo: pertenece a Captia (PWA mobile + conectores de ingesta). Los operadores en campo no llaman a las APIs de Tracium directamente; usan Captia, que se encarga de enviar los eventos a Tracium.
Visor de Digital Product Passport: pertenece a Fidenta. Experiencia QR orientada al consumidor.
Aprovisionamiento de tenant y administración: herramientas internas, no expuestas 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: paquetes regulatorios
On-chain vs off-chain: el split de datos