Development Guide for Integrators
Use Actualog to exchange product information with your ERP, PIM, PLM, commerce platform, supplier portal or data service. You work through the public API, MCP and managed file exchanges. This guide explains the data model, source mappings and processing lifecycle you need to build an integration.
Choose the right integration path
| Path | Use it for |
|---|---|
| Public REST API | Deterministic reads, business commands, bulk-job submission, validation, operation status and authorized file retrieval. |
| Inbound Feeds | Repeatedly receiving files or datasets from an external source using a saved connection and mapping profile. |
| Outbound Feeds and exports | Delivering selected product, catalog, commercial and media data to another system, on demand or on a schedule. |
| MCP | Letting an authorized agent discover the data model, prepare mappings, investigate quality, enrich records and coordinate governed import or export operations. |
These paths share Actualog's business rules. An API request, a scheduled Feed and an MCP tool call do not create independent versions of the same product or bypass review requirements.
Use Public API Docs for exact HTTP methods, request and response schemas, pagination and error contracts. Discover MCP tools and their input schemas from the connected server. This guide explains their business meaning rather than defining a second wire format.
Establish identity and company scope
Your company supplies an authorized integration identity, the environment address and the permitted company scope. Public API requests use X-Client-Id and X-Client-Secret. Keep the secret in your integration service's protected configuration. Credential ownership, current permissions and company API entitlements determine which operations are allowed.
MCP uses delegated user authorization and approved scopes. Call get_actualog_context first to discover the identity, capabilities, permissions and guidance available to the agent. Request the relevant domain guidance before preparing changes. The scope of an approved connection remains distinct from permission to apply a particular change.
For example, a server-side client can inspect a category's active model before mapping incoming product values:
curl "$ACTUALOG_BASE_URL/api/categories/$CATEGORY_ID/effective-template/active" \
--header "X-Client-Id: $ACTUALOG_CLIENT_ID" \
--header "X-Client-Secret: $ACTUALOG_CLIENT_SECRET"
Use identifiers discovered in your environment. A company identifier in a request selects context; it does not grant access to that company.
Understand the data model
Actualog maintains shared canonical product information and separates it from a company's assortment, presentation and commercial operations.
| Object | Meaning for your integration |
|---|---|
| Company | The workspace, business participant and authorization context for company-owned operations. |
| Category and Effective Template | The product classification and its versioned description rules: Attributes, required values, units, permitted selections and identity policy. |
| Attribute and reference value | A typed characteristic and, where applicable, a controlled selection with a stable identity. |
| Product Group and Product | A family with shared values and its concrete variants. A standalone Product does not require an artificial Group. |
| Product Pack | An exact orderable or logistical configuration of a Product. Reusable packaging definitions describe its packaging. |
| Seller item and commercial Offer | A seller's SKU and commercial terms for an exact Pack, including price, currency and order rules. |
| Catalog | An assortment and its intended audience or purpose. Membership and commercial terms are separate. |
| Stock record | Availability for a company and exact Pack, with source, time and quantity semantics. |
| Media Asset | An image or document and its assignments to Products, Groups or other supported subjects. |
| Product Release and publication | A reviewed revision or published snapshot, separate from the current working record. |
Keep these boundaries in your own mapping. A manufacturer part number, an ERP item code, an Actualog Product ID and a seller SKU serve different purposes. A price change does not redefine a Product Pack or update warehouse stock. A Group is not an orderable concrete variant.
Company-specific content and commercial data retain their own ownership. Improvements to shared technical information follow the canonical governance process rather than silently becoming a private company's replacement for shared truth.
Read the model before mapping values
Resolve the intended product-level Category, active Effective Template, Attribute definitions, reference dictionaries and units. Distinguish the active model from a draft or candidate. Retain the template and mapping revisions used to prepare a change.
Category rules determine the applicable value type, requiredness, precision, permitted units, controlled selections, Group ownership and Variant axes. A reusable Universal Category supplies model rules; it is not automatically the destination for creating a concrete Product.
Map by stable identifiers and scoped codes. Translated labels help people recognize a value, but a translated label is not a reliable integration key. Keep Product identifiers, external classification codes and Attribute dictionary values as separate mappings. An external classification also carries its source and edition.
For multilingual text, specify the language of each supplied value. Updating a French description leaves other languages untouched. Numeric values retain their quantity and unit independently of the display language. Conversion and technical equivalence are explicit decisions, not consequences of translating a label.
Define the import task explicitly
Choose the intended operation before submitting data:
| Task | Required interpretation |
|---|---|
| Create Products in known Categories | Validate the supplied Category and identity. Reuse or report an existing match; do not enrich it implicitly under a create-only instruction. |
| Enrich existing Products | Resolve an Actualog Product ID or a typed external key, then prepare only the requested changes. An unknown explicit Product ID is an error, not permission to create. |
| Prepare an unfamiliar supplier source | Resolve unknown Categories, fields and identifiers, then apply the same explicit creation or enrichment rules. |
| Maintain Groups and Variants | Separate shared values from Variant values and materialize only combinations actually present in the source. |
| Maintain catalog assortment | Resolve the Catalog and target Products. Missing Products remain a separate decision. |
| Update prices and Offers | Resolve the seller, exact Pack, currency, price basis and applicable commercial terms. |
| Report stock | Declare the exact company and Pack, observation time, and whether the quantity is a snapshot or an event. |
| Attach images and documents | Resolve the subject and intended assignment; media filenames do not redefine product identity. |
Creation mode and change scope are separate settings. A translation-only update does not require a new full product description. A mixed package can contain related tasks, each with its own dependencies and results.
Prepare files and source mappings
Actualog reads delimited tables, Excel workbooks, JSON, NDJSON/JSONL, XML and related ZIP packages. Document and image extraction accepts sources such as PDF, DOCX, saved HTML and scans. A named exchange standard uses its registered adapter and edition; generic XML support does not define a BMEcat or other industry-standard contract.
Mappings describe the structure of your source. You can use wide tables, Attribute/value rows, joined sheets or files, nested objects, language dictionaries, Group/Variant hierarchies and media manifests. Define join keys and cardinality explicitly. Several rows can describe one logical Product, and one source record can generate several related operations.
Keep your source field names. Map them to Actualog fields, Attributes, languages, units and reference values in a saved profile. A field can be a lookup key, an expected-value check or a new identifier to assign; these roles must be declared separately.
AI assists with unresolved classification, field mapping, extraction and requested translation. Accepted identifiers and saved mappings remain deterministic. Preserve the source record, cell, page or document evidence for extracted facts and review ambiguous results before application.
Use Feeds for recurring exchange
A Feed combines a named source, company scope, transport connection, direction, schedule, task and versioned mapping. Inbound Feeds receive data; outbound Feeds deliver data; a bidirectional connection keeps the two directions and their ownership rules explicit.
Provide the integration owner with the endpoint, protocol, authentication method, remote path, file pattern, schedule and intended data scope. HTTP/HTTPS, FTP and SFTP connections use centrally managed credentials. Secrets are not returned with ordinary profile reads.
Each run pins a validated profile revision. It retains a run reference, source revision, timestamps, processing state and record-level outcomes. Connection testing checks transport access; parsing, mapping, validation, application and downstream delivery have their own results.
A scheduled synchronization compares the last accepted source values, current Actualog values and the new source values. This protects intervening manual edits and exposes conflicts. Seeing a record again does not mean its new value has been applied.
Define full snapshots and incremental changes explicitly. Missing records trigger reconciliation only within a declared complete, authoritative scope. Absence from a file does not automatically delete a canonical Product. Changes to source structure, identifiers, units, price basis or join relationships require mapping review rather than silent reinterpretation.
Validate, review and apply imports
An import progresses through source receipt, parsing, logical-record assembly, target resolution, normalization and validation. It then produces a preview of typed changes, including the target, expected revision, before/after values, dependencies, blockers and review requirements.
Known references reduce unnecessary inference. A supplied Category ID is checked rather than classified again. A supplied Product ID resolves the existing Product and its rules. Conflicting context and row values remain visible conflicts.
Apply these update semantics consistently:
- Missing: preserve the current value.
- Set: assign the supplied value, including meaningful zero or false values.
- Clear: explicitly remove a value where the field permits removal.
- Collections: add, remove or replace a declared scope explicitly.
Blank cells and null values do not silently authorize destructive clearing. A partial patch is validated against the resulting record. It is not rejected merely because unchanged fields were omitted from the source.
Actualog checks identity before canonical creation. Unresolved identity, conflicting identifiers and ambiguous matches remain reviewable. Ordinary enrichment does not silently change Category, Brand-defined identity, Variant axes or Group membership. Canonical conflicts produce reviewable proposals or claims with evidence.
The apply step rechecks permissions, current revisions and dependencies. The report identifies created, updated, unchanged, rejected and review-required outcomes and links them to their source records and actual targets.
Export structured data and publish outbound Feeds
Use JSON for structured product transfer: identities, Categories, template references, Group/Variant relationships, typed Attribute values, units, selected reference values, languages and media. Use CSV for an agreed flat projection. A flat report is not a lossless representation of every nested relationship.
Select explicit targets or a filtered scope, choose the required language and output profile, and run preflight. Queued exports freeze the selected targets and relevant mapping revision. Their status exposes progress, counts, errors, artifact metadata and authorized download information.
Choose the payload that matches the receiving system. A commerce export can combine Product descriptions, exact Packs, seller identifiers, prices, currency, order constraints and authoritative availability. Destination mappings define which identifier, classification, image and unit to use; an ambiguous selection requires a decision.
A published Feed provides a stable, revocable delivery address for the latest successful artifact. Scheduled regeneration uses the same validation and export process. A failed regeneration retains the previous successful artifact and records the failed run, so consumers can distinguish available content from fresh content.
Keep export generation, transfer, destination validation and publication as separate results. A successfully transferred file is not evidence that a marketplace accepted every item or made it publicly available.
Use MCP to prepare and operate integrations
MCP gives an authorized agent structured access to model discovery, source analysis, mapping, governed authoring, quality investigation and import/export operations. It can coordinate work across taxonomy, dictionaries, Products, Groups, media and catalog data using the same domain capabilities as other clients.
Start by reading context and domain guidance. Have the agent resolve actual IDs, inspect relevant templates and current values, explain its proposed changes and prepare a preview. Grant authority for a defined operation and scope, then inspect the saved outcome and affected records.
Follow pagination, coverage and revision indicators. Data that was not loaded is not an empty value. A model proposal, an activated template, actualized Products, approved content and a delivered Feed are separate milestones.
Use MCP for interactive investigation and controlled decisions. Use REST and managed Feeds for repeatable system-to-system execution and sustained bulk transfer. Accepted mappings and decisions are saved so later runs do not depend on reconstructing a conversation.
Make synchronization recoverable
Retain source keys, source record keys, mapping revisions, operation references and Actualog target identifiers. Use each operation's concurrency and idempotency contract. Recover a lost response from the saved outcome before submitting a new operation; reusing an idempotency key with different content is a conflict.
Inspect record-level results even when the request succeeds. Correct and retry failed work without repeating committed changes. Cancellation stops remaining work at a supported boundary; it does not erase completed operations. Disconnection does not undo an accepted job.
A practical ERP integration starts with a small representative batch, including a standalone Product, a Variant, a controlled value, a unit conversion, a translation and a rejected row. Verify the resulting records and outbound payload, replay the same source, introduce a conflicting manual edit, and confirm that correction and recovery preserve successful work before enabling the recurring Feed.