# Import a Captured Dump

Printing over a socket is the normal path, but it is not the only one. If you already have the bytes —
a capture from a real printer, a payload attached to a bug report, a fixture from your test suite —
you can feed them straight to a printer and look at the result. No socket, no application, no code.

This is the fastest way to answer "what does this dump actually draw?".

## In the web interface

1. Select the printer, or create one with the paper width you want to render against.
2. Open the **Operations** panel on the right and click **Import Doc**.
3. Either **drop a file** (or pick one), or **paste the bytes** into the field - a hex dump or
   base64, whichever you have.
4. The bytes go through the same parser a printed job goes through, and the document appears in the
   list exactly as if it had arrived over TCP — including any parse errors.

Make sure the printer's protocol matches the dump: ESC/POS data on an EPL printer renders nothing
useful. See [Printer protocols](/docs/protocols).

## Over the API

```bash
# base64
curl -sf -X POST "https://virtual-printer.online/api/printers/$PRINTER_ID/documents/import" \
  -H "Authorization: Bearer $ACCESS" \
  -H 'Content-Type: application/json' \
  -d "{\"Data\": \"$(base64 -w0 receipt.bin)\"}"

# a hex dump, with the format stated
curl -sf -X POST "https://virtual-printer.online/api/printers/$PRINTER_ID/documents/import" \
  -H "Authorization: Bearer $ACCESS" \
  -H 'Content-Type: application/json' \
  -d '{"Data": "1B 40 48 65 6C 6C 6F 0A", "Format": "Hex"}'
```

`Data` carries the bytes and `Format` is `"Hex"` or `"Base64"`. **`Format` is optional** — leave it out
and the format is detected — but see [Telling the two apart](#telling-the-two-apart) before relying on
that. The response is **204** on success and **400** with the reason otherwise. Then read the parsed
document back with `GET /api/printers/{id}/documents/canvas` — see
[Asserting on a receipt](/docs/ci-cd/assertions).

In a test suite this turns a byte dump into a regression test: keep the capture as a fixture, import
it, assert on the elements. It is also how a support case with an attached dump becomes something you
can look at, without reproducing whatever produced it.

## Accepted formats

| Input | Accepted |
|---|---|
| A binary file (`.bin`, `.prn`, raw capture) | Yes — drop it or select it |
| A hex dump (`1B 40 48 65 6C 6C 6F 0A`) | Yes — paste it, or send it with `"Format": "Hex"` |
| Base64 text | Yes — paste it, or send it in `Data` |

Whitespace is ignored in both text forms, so a dump copied out of a debugger, wrapped across lines or
run together all work. Escaped forms — `\x1B`, `0x1B, 0x40` — are not accepted; strip them to plain
hex digits first.

## Telling the two apart

The two formats overlap, and the overlap is a trap worth understanding.

Every hex digit is also a base64 character. A dump of an even number of bytes has a character count
that is a multiple of four, which makes it valid base64 as well — and the two readings produce
completely different bytes. `1B40` is two bytes as hex and three entirely different bytes as base64.

So:

- A dump written **with its bytes spaced apart** — `1B 40 48 65` — is read as hex. Base64 is not
  written that way, which is what makes the spacing a reliable signal.
- A payload valid as **only one** of the two is read as that one.
- A **run-together** payload valid as both is **refused**, in the dialog and in the API alike, with a
  message asking you to say which it is. Guessing there would import the wrong bytes silently, which is
  worse than an error.

In a script, the reliable thing is simply to state `Format`. In the dialog, the format selector does
the same, and the hint under the field tells you what your paste was recognised as and how many bytes
that comes to.

## What it is not

Import replays bytes into the parser. It does not exercise your application's socket handling,
timeouts or reconnects, because nothing is connected — for that, print over TCP as usual. See
[Choosing a test printer](/docs/concepts/choosing-a-test-printer).