> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guides, Mappings, and Callbacks

> Publish reviewed guide and transformation revisions, then deliver document callbacks with exact-byte verification and stable event identity.

Guide policy, JSON transformations, item/location cross-references, and callback subscriptions
serve different purposes. Version each deliberately and retain the configuration used by
an actual operation.

## Edit the partner guide

The console guide editor and `/v1/partners/{id}/guide` expose the saved validation rules,
explicit overlay, and revision. Draft validation checks syntax and policy without publishing.
Publication is a full replacement with `expected_revision`, `validation`, explicit `overlay`
(or `null` to clear), and an optional note. Omitted validation fields are removed; unknown
fields are rejected. Stale revisions return 409; invalid drafts return 422.

Immutable snapshots support diff and restoration. Restore an earlier definition as a new
reviewed revision; do not treat it as permission to overwrite another editor's changes.
Guide publication does not establish that the rules match a licensed/current counterparty
guide or that the counterparty has accepted a transmission.

## Publish mappings with regression fixtures

Mapping definitions use JSON pointers for source fields, recursive arrays, lookup tables,
required/default rules, and exact decimal-string multiplication. Preview transforms input
without delivery. Publication requires PostgreSQL, an expected version, review note, and
positive/negative fixtures; it records an immutable revision after fixture checks pass.

| Route | Purpose |
| - | - |
| `POST /v1/mappings/preview` | Try an unsaved definition against sample input |
| `GET /v1/mappings/{partner_id}/{name}` | Latest 100 immutable revisions |
| `POST /v1/mappings/{partner_id}/{name}` | Publish after fixtures pass; stale head returns 409 |
| `POST /v1/mappings/{partner_id}/{name}/{version}/transform` | Apply an explicitly pinned revision |

A deterministic preview can be as small as:

```json theme={null}
{
  "definition": {
    "fields": [
      { "target": "order_number", "source": "/po_number", "required": true },
      { "target": "amount", "source": "/amount", "factor": "0.01", "required": true }
    ],
    "arrays": []
  },
  "input": { "po_number": "PO-123", "amount": "2450" }
}
```

Pin the intended revision in the actual consuming integration; publishing a definition does
not automatically bind every ERP connector to it. Item and location cross-references under
`/v1/partners/{id}/xref/` are separate identities to inspect/import/export deliberately.

## Deliver document callbacks

Customer callbacks currently describe document-recorded events, not every transport or
business-status transition. Subscriptions require PostgreSQL and connection encryption.
Saving a subscription creates a new immutable endpoint/key revision. Work accepted earlier
retains its original event ID, payload, endpoint, and signing revision.

Inspect `/v1/callback-deliveries` and each event's `/history` before retrying held work.
Pause and permanent revision revocation are different actions; a revoked current revision
must be rotated before re-enabling it. Already claimed requests may be in flight.
Callbacks are at-least-once; receiver deduplication needs durable event-ID storage.

| Header | Meaning |
| - | - |
| `x-stateset-event-id` | Stable delivery/event identity |
| `x-stateset-timestamp` | Integer Unix timestamp for this attempt |
| `x-stateset-key-version` | Original subscription signing revision |
| `x-stateset-signature` | `v1=<hex HMAC-SHA256>` over timestamp + `.` + event ID + `.` + exact body bytes |

The source JavaScript client includes the verifier. Run this example beside your
`stateset-edi` source checkout:

```js theme={null}
import { verifyCallback } from './stateset-edi/sdk/index.js';

export async function authenticateCallback(rawBody, headers, originalRevisionSecret) {
  return verifyCallback({
    secret: originalRevisionSecret,
    eventId: headers['x-stateset-event-id'],
    timestamp: headers['x-stateset-timestamp'],
    signature: headers['x-stateset-signature'],
    body: rawBody,
  });
}
```

Use the secret for the identified revision, verify before JSON parsing, enforce the time
window, and atomically deduplicate authenticated event IDs with your application effect.
The helper's default timestamp tolerance is 300 seconds. Re-serialized JSON changes bytes.
A valid signature authenticates the request; a receiver HTTP 2xx is not proof that an ERP
completed the business operation. See [CLI and SDK](/stateset-edi/cli-and-sdk).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.