Pawsitive Future Pawsitive FutureDeveloper docs

post_vouchers_batches_by_id_print

Changes data · you confirm first

Calls POST /api/vouchers/batches/{id}/print as the signed-in person · REST reference

Print a physical voucher batch from its id alone

Sends the batch's live vouchers that no printer has accepted yet — a batch created without printing, or a retry after a failed print — to the office printer. Needs NO body: the codes are read by batch id from the DAL, never supplied by a client. voucherIds may NARROW the print to named vouchers of the batch (a retry of a reprint's failed replacement); each must be one the print would send anyway, or nothing is printed (409 NOT_PRINTABLE). A voucher a printer already accepted is never sent again (a second copy of a live code is a second claim on its budget); paper for one of those is a reprint (POST /api/vouchers/{id}/reprint, or /batches/{id}/reprint for the whole batch). Voided, expired, reprinted and in-redemption vouchers are never printed. Only PHYSICAL batches print. Every voucher the print covered is recorded SUBMITTED or PRINT_FAILED, and the batch records the attempt in its metadata. Answers 202, not 200: SUBMITTED means the printer ACCEPTED the job, not that paper came out. An accepted print ISSUES every voucher it carried, in the write that records it — CREATED through ASSIGNED, one already ISSUED left as it is, issued to the bearer with no contact — so the public voucher check reads it AVAILABLE; a failed print issues nothing. If the job was accepted but could not be recorded, the answer is still SUBMITTED, with code PRINT_STATUS_NOT_RECORDED: nothing was recorded or issued. A printer failure answers 502 with a code (PRINTER_UNREACHABLE, PRINTER_AUTH_REJECTED, PRINTER_TLS_UNVERIFIED, PRINTER_REJECTED_JOB); a sheet we could not produce answers 500 PRINT_FAILED; no printer configured answers 503 PRINTER_NOT_CONFIGURED; nothing left to print answers 409 NOTHING_TO_PRINT. Requires execute:CreateVoucherBatchCommand, the minting permission; platform staff are admitted as on every gate.

Arguments

ArgumentTypeDescription
idpathstring (uuid)requiredInventory batch id.
bodyJSONobjectThe request body, as a JSON object. Its fields are listed below.

Fields of body

FieldTypeDescription
voucherIdsarray of string (uuid)Print only these vouchers of the batch. Distinct UUIDs; each must be a live voucher of the batch that no printer has accepted.

Example call

A client sends this over the MCP session; Claude and other agents build it for you. The values are placeholders — the shape is real.

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "post_vouchers_batches_by_id_print",
    "arguments": {
      "id": "11111111-1111-4111-8111-111111111111",
      "body": {
        "voucherIds": [
          "11111111-1111-4111-8111-111111111111"
        ]
      }
    }
  }
}
Confirmation
The client shows the person the exact request and waits. Nothing runs until they tick Make this change. See Reading and changing.

Result

On success (HTTP 202) the tool returns one text item holding the API's JSON, pretty-printed.

The printer accepted the job. print.error is set only if the vouchers could not be marked as sent.

json
{
  "batchId": "11111111-1111-4111-8111-111111111111",
  "print": {
    "status": "SUBMITTED",
    "code": "PRINTER_UNREACHABLE",
    "error": "string",
    "jobId": 1,
    "vouchers": 1
  }
}

Fields

FieldTypeDescription
batchIdstring (uuid)
printobject
print.code"PRINTER_UNREACHABLE" | "PRINTER_AUTH_REJECTED" | "PRINTER_TLS_UNVERIFIED" | "PRINTER_REJECTED_JOB" | "PRINTER_NOT_CONFIGURED" | "PRINT_FAILED" | … (7 values)Machine-readable reason for error.
print.errorstringCurated and safe to show. On FAILED and NOT_CONFIGURED; on SUBMITTED only when the job was accepted but could not be recorded — its vouchers were then neither marked as sent nor issued.
print.jobIdintegerThe printer's job id, on SUBMITTED.
print.status"SUBMITTED" | "FAILED" | "NOT_REQUESTED" | "NOT_CONFIGURED"SUBMITTED: the printer ACCEPTED the job (accepted, not paper confirmed), and the vouchers it carried are ISSUED — unless code is PRINT_STATUS_NOT_RECORDED. FAILED: nothing was printed or issued. NOT_REQUESTED: no print was asked for, or the batch is DIGITAL. NOT_CONFIGURED: a print was asked for and this server has no printer.
print.vouchersintegerHow many vouchers the print covered. Absent when none was attempted.

When it fails

A failed call returns isError: true with the API's message as text. A change the person declines, or lets time out, also comes back this way and nothing changes.

400

The request was malformed or failed a guard.

403

Authenticated, but the caller holds none of the required permissions.

404

No such resource — or none this caller may see.

409

The resource is not in a state that allows this operation.

502

The printer failed — it could not be reached, or refused the credential, the TLS pin or the job. Nothing was printed; the vouchers are recorded PRINT_FAILED.

What the model is shown

This is the tool exactly as the server lists it in tools/list. The description starts with the REST call it makes.

json
{
  "name": "post_vouchers_batches_by_id_print",
  "description": "POST /api/vouchers/batches/{id}/print — Sends the batch's live vouchers that no printer has accepted yet — a batch created without printing, or a retry after a failed print — to the office printer. Needs NO body: the codes are read by batch id from the DAL, never supplied by a client. `voucherIds` may NARROW the print to named vouchers of the batch (a retry of a reprint's failed replacement); each must be one the print would send anyway, or nothing is printed (409 `NOT_PRINTABLE`). A voucher a printer already accepted is never sent again (a second copy of a live code is a second claim on its budget); paper for one of those is a reprint (`POST /api/vouchers/{id}/reprint`, or `/batches/{id}/reprint` for the whole batch). Voided, expired, reprinted and in-redemption vouchers are never printed. Only PHYSICAL batches print. Every voucher the print covered is recorded SUBMITTED or PRINT_FAILED, and the batch records the attempt in its metadata. Answers 202, not 200: SUBMITTED means the printer ACCEPTED the job, not that paper came out. An accepted print ISSUES every voucher it carried, in the write that records it — CREATED through ASSIGNED, one already ISSUED left as it is, issued to the bearer with no contact — so the public voucher check reads it AVAILABLE; a failed print issues nothing. If the job was accepted but could not be recorded, the answer is still SUBMITTED, with `code` `PRINT_STATUS_NOT_RECORDED`: nothing was recorded or issued. A printer failure answers 502 with a `code` (`PRINTER_UNREACHABLE`, `PRINTER_AUTH_REJECTED`, `PRINTER_TLS_UNVERIFIED`, `PRINTER_REJECTED_JOB`); a sheet we could not produce answers 500 `PRINT_FAILED`; no printer configured answers 503 `PRINTER_NOT_CONFIGURED`; nothing left to print answers 409 `NOTHING_TO_PRINT`. Requires `execute:CreateVoucherBatchCommand`, the minting permission; platform staff are admitted as on every gate.\n\nThis changes data. The person is asked to confirm it before it runs, and nothing happens if they decline.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Inventory batch id."
      },
      "body": {
        "type": "string",
        "description": "The JSON request body: { voucherIds: array of string (Print only these vouchers of the batch.) }"
      }
    },
    "required": [
      "id"
    ]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": false
  }
}