Conectar sistemas con claves de API, webhooks y EPCIS

Claves de API

Una clave de API sirve para el acceso máquina a máquina. El secreto se muestra una vez y se guarda con hash, con un prefijo visible para identificarla y una marca de último uso que distingue una integración activa de una clave olvidada. Las claves caducan y pueden revocarse.

Los alcances determinan qué puede hacer una clave - leer o escribir sobre un recurso - y una clave actúa como el miembro que la creó a efectos de atribución, sin heredar su rol. Si el propietario de una clave ya no está, la clave no puede actuar: una pista de auditoría que no nombra a nadie no es una pista de auditoría.

Webhooks salientes

Un webhook suscribe tu destino a un conjunto de eventos. Cada entrega se firma, se reintenta con espera creciente si falla y se registra en un diario de entregas con el código de estado y el error, así que puedes decir a un socio que su destino devolvió un error en lugar de adivinar.

Una entrega guardada puede repetirse, que es lo que necesitas tras arreglar un destino. Eliminar un webhook elimina también su historial de entregas: exporta antes lo que debas conservar.

EPCIS 2.0

Una suscripción EPCIS es una consulta permanente sobre el flujo de eventos del ciclo de vida: qué tipos de evento, pasos de negocio, disposiciones, identificadores de producto, categorías o pasaportes quieres, y dónde enviarlos. Los eventos coincidentes se envían como eventos de objeto estándar.

Una suscripción se implementa como un webhook con filtro, así que hereda firma, reintentos, diario de entregas y repetición, y además el filtro nunca se elude. Usa la acción de prueba para demostrar un destino antes de confiar en él, y la recuperación acotada para poner al día el historial de un nuevo suscriptor.

Calidad del dato del flujo

Los eventos de ciclo de vida vienen de tus propias fichas y de capturas de socios que importas. Una importación es idempotente por identificador de evento, así que un socio que reintenta un lote no crea duplicados, y los eventos propios del sistema, como la puesta en servicio, se rechazan porque la plataforma ya los registra.

El cuerpo de entrega es un sobre de la plataforma; el evento de objeto estándar va dentro. Los destinatarios deben leer la carga en lugar de suponer un evento desnudo.

Antes de salir a producción

Da una clave distinta a cada integración, para que revocar una no rompa las demás. Apunta primero los webhooks a un destino de pruebas y revisa el diario de entregas, porque una firma que no coincide se depura mucho más fácil allí que en producción. Y mantén la clave fuera del control de versiones: la consola la muestra una única vez.

Centro de integración: mapeos y feeds

El centro de integración mantiene los pasaportes al día con una exportación de ERP, PIM o PLM. Un mapeo indica la columna con el SKU o GTIN y qué columna llena qué destino: un campo de producto (product.brand) o una ruta de datos del pasaporte (data.materials.0.recycled_percent), con conversión (número, unidad, fecha, sí/no, código de país) y tabla de valores.

Sube un archivo CSV o JSON y revisa las diferencias antes de aplicar: solo se escriben los valores distintos, en una nueva versión validada. Se puede configurar un feed https diario (token cifrado, nunca se vuelve a mostrar). La procedencia de cada campo indica el mapeo y la ejecución que lo escribieron.

Plantillas, XML, SFTP, OAuth y envío

Parte de una plantilla para SAP S/4HANA (API Product o IDoc MATMAS), SAP Business One, Dynamics 365 Business Central, NetSuite, Odoo, Akeneo, Pimcore, Salsify, Plytix o una lista de materiales PLM. Las fuentes pueden ser CSV, JSON o XML.

Los feeds se leen por HTTPS (GET, o POST con cuerpo para GraphQL, OData, SuiteQL) con token, credenciales, clave en una cabecera u OAuth 2.0, o por SFTP con contraseña o clave y huella de host fijada, cada hora o cada día. Tu sistema también puede enviar los registros con un token de envío, y un mapeo puede crear los productos que falten. Un mapeo de lista de materiales mantiene la estructura de componentes de cada producto padre, sin tocar los componentes introducidos a mano.

Exportación Asset Administration Shell (AAS)

Cada pasaporte se exporta como Asset Administration Shell en el formato JSON del metamodelo AAS V3: botón AAS export del pasaporte o GET /dpp/{id}/aas.json (versión publicada por defecto). Un pasaporte publicado ofrece además GET /public/dpp/{id}/aas.json con exactamente el contenido público.

El shell incluye un submodelo Nameplate (identificador semántico Digital Nameplate), un submodelo DigitalProductPassport con todos los datos y un submodelo Components que referencia los shells de los componentes. Fuera de Nameplate, los submodelos usan identificadores de la plataforma sin afirmar conformidad con una plantilla IDTA.

Referencia página por página

Estas páginas se revisaron en la consola de la organización el 8 de octubre de 2026 con una organización de ejemplo aislada. Los controles pueden variar según el rol, el plan, el estado del registro y los proveedores configurados. Las explicaciones prácticas y los nombres de los controles siguientes siguen la interfaz en inglés revisada.

API keys (/settings/api-keys)

API keys give integrations scoped access to organization endpoints and can expire independently of a browser session.

Name a key for one integration and choose the smallest scope set that supports its specific endpoints. Copy the secret at creation into the intended secure system because the raw value is not displayed later. Use status and last-used information to retire unused credentials; a key cannot exceed its creator's current access.

The full secret is not retrievable after creation.

Controles y opciones

• Give the key a name and optional expiry in days.
• Select only the scopes the integration needs, then Create key and copy the secret once.
• Inspect the key list for status and last use; revoke an unused or exposed key.
• A member-created key is limited by that member's current role and workspace access.

Webhooks (/settings/webhooks)

Event subscriptions send signed organization events to your HTTPS endpoint and keep delivery attempts for troubleshooting.

Subscribe an HTTPS receiver to only the event types it needs and store the signing secret in that receiver. After adding the endpoint, inspect delivery attempts and response codes to see whether it accepted events. Replaying a failed attempt may deliver a duplicate, so the receiver should deduplicate and verify signatures before processing.

A successful HTTP delivery means the endpoint accepted the event, not that its downstream processing succeeded.

Controles y opciones

• Enter an HTTPS endpoint and signing secret, or let the system generate a secret.
• Choose the event types the receiver actually needs, then Add webhook.
• Inspect deliveries for response codes and retry history; replay a failed attempt after fixing the receiver.
• Rotate a compromised secret and confirm the receiver accepts the new signature.

EPCIS subscriptions (/settings/epcis)

An EPCIS subscription pushes matching lifecycle events to a standing partner endpoint.

Define a destination and narrow the subscription query so a partner receives only relevant GTINs, categories, steps, dispositions, or event types. Send a sample to confirm endpoint and signature handling, then inspect deliveries during live use. Backfill and replay can resend events, so the receiver must deduplicate by event identity.

Subscribers should deduplicate by event identity; delivery is retried.

Controles y opciones

• Name the subscription, set Destination URL and optional signing secret.
• Limit the query by category, GTIN, event type, business step or disposition.
• Create the subscription and send a sample before depending on live delivery.
• Inspect the log, bounded backfill and replay controls when a receiver misses events.

Integration hub (/integration-hub)

Mappings translate ERP, PIM or PLM records into product fields, passport paths or component lines using a declared key and transforms.

Define how one source record identifies a product before mapping fields, then preview the transformation on a representative file. Record-to-field and bill-of-material mappings have different row meanings, so choose the kind that matches the source. Keep feed credentials in their dedicated fields and apply a run only after reviewing proposed writes and validation errors.

Applied differences pass schema validation and become audited passport versions.

Controles y opciones

• Start from a template or blank mapping; choose records or BOM kind and CSV, JSON or XML source.
• Select SKU or GTIN key field and source column, then add source-to-target rules with transforms and optional value maps.
• Configure optional HTTPS or SFTP feed and manual, hourly or daily schedule; credentials are write-only.
• Save mapping, then preview a sample before any write.

Mapping detail (/integration-hub/[id])

A saved mapping has preview, execution, feed and push controls plus run history.

Preview a file or feed against the saved mapping and inspect record-level matches, proposed differences, and rejections. Run the mapping only when the preview matches the intended products; changed passport data creates audited revisions. After a run, compare applied and skipped counts, then use history to investigate a particular source row without editing earlier provenance.

Do not paste source credentials into support messages or free-text mapping fields.

Controles y opciones

• Upload a source file and Preview changes to inspect per-record matches, errors and proposed writes.
• Run only after reviewing; changed passport fields create new versions, while unchanged values are skipped.
• Feed and push can fetch a scheduled source or issue a scoped push token for the source system.
• Edit rules and Save mapping with revision protection; inspect Run history for applied and rejected rows.
• Delete mapping requires confirmation and does not erase earlier run provenance.