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

# Mappings

> Connect a device or a system as it is, the same day, without code: map the messages it already sends to wede operations

## Connect what you already have

Most equipment already sends messages: a payment terminal to its host, a charger to its management system, a meter or an industrial controller to a broker, a hospital system to its integration engine. A mapping tells wede which field of those messages fills each field of a wede operation. The messages are then sent to wede as they are, and each one becomes an operation exactly like any other: the same checks, the same protection against duplicates, the same [Devices](/concepts/devices.md) and [Reconciliation](/concepts/reconciliation.md).

There is no code to write on your side, and nothing changes on the equipment.

## Only what you map enters wede

A mapping lists the fields wede keeps. Everything else in each message is ignored and never stored. The sample messages you use to try a mapping are never stored either. Your organisation stays in control of what wede holds, field by field.

## What a mapping says

| wede field | Required | From your message |
| - | - | - |
| Operation type | Yes | A field, with a table of values (your value on the left, a type of your catalog on the right), or a fixed value |
| Message identity | Yes | One to five fields that together identify one message, for example terminal and STAN, or charger and session. A message sent again is a duplicate, never a second operation |
| Amount and currency | No | Decimal (12.50 or 12,50) or minor units (1250), and an ISO 4217 code |
| Direction | No | `in`, `out` or `neutral`, or your own words with a table of values |
| Reference and original reference | No | Your transaction or session reference, and for a reversal the reference of the operation it reverses |
| Quantity and unit | No | As captured, for example 12.4 `kW.h` or 351.2 `m3`; never converted |
| Captured at | No | The time on the device, in ISO 8601, epoch seconds or epoch milliseconds |
| Device | No | The device id or any identifier of the device |
| Sequence | No | The number the device gives each message, so you can prove nothing is missing |
| Other fields | No | Up to 30 fields of your message, kept under names you choose |

For JSON, a field is a path with dots (`data.amount`, `items.0.qty`); messages can arrive one at a time, as a list, or inside a list at a path you set. For CSV, a field is a column name, with a header line and the separator you choose.

wede never guesses. A required field without a value, a value that is not in its table, or a time or a number that cannot be read refuses that message with the field and the reason; the other messages go on.

## Versions

A mapping has a code and versions. A version never changes once saved: a change is a new version. One version is in use at a time, and the others are kept. An archived version stops being used and is kept for audit. Nothing is deleted.

## Sending messages

In the dashboard, Mappings shows the address of each mapping in use. Your systems, or the broker that receives the messages of your devices, send them there with your API key, up to 500 messages per request, handled in order:

```bash theme={null}
curl -X POST https://api.wede.pt/v1/ingest/ev-charger \
  -H "X-Wede-API-Key: $WEDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{ "evt": "TX_END", "cp": "CP-01", "tx": 991, "kwh": 12.4, "ts": 1760270400 }]'
```

CSV goes as text, with `Content-Type: text/csv`. The answer lists every message as `accepted`, `duplicate` or `rejected`, with the field and the reason. Each message counts toward the same limit per minute as `POST /v1/events`.

## Try before you use it

In the dashboard, paste a few real messages and press Try on sample: each message shows the operation it would become, or why it would be refused, before anything is saved. The same check is available from your systems with `POST /v1/mappings/preview`.

Mappings are managed by the people of your organisation who manage its integration. wede staff never see or manage them.


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