Pawsitive Future Pawsitive FutureDeveloper docs

post_vouchers_by_id_issue

Changes data · you confirm first

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

Issue a voucher to a beneficiary and email its QR code

Walks the voucher CREATED → ASSIGNED → ISSUED (each hop validated by the state machine), then generates the QR payload and emails it. A voucher already in ISSUED is re-sent; a voucher in any other state is refused with 409. Issuing assigns the voucher to NO clinic: it stays with the org holding it (its batch's distributor, or the platform), and any clinic takes it when the bearer presents it (POST /api/vouchers/{id}/verify). PARTIAL SUCCESS IS A REAL OUTCOME HERE: when the write succeeds but the email does not, the answer is 502 carrying the voucher id, state and qrPayload alongside error, so the caller can deliver it another way. That 502 body is deliberately NOT the canon error body, which would drop those fields.

Arguments

ArgumentTypeDescription
idpathstring (uuid)requiredVoucher id.
bodyJSONobjectrequiredThe request body, as a JSON object. Its fields are listed below.

Fields of body

FieldTypeDescription
emailstring (email)requiredBeneficiary address the QR is delivered to. Missing or empty answers 400.
phonestringRecorded as the contact phone on the ISSUED transition. Not used for delivery.

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_by_id_issue",
    "arguments": {
      "id": "11111111-1111-4111-8111-111111111111",
      "body": {
        "email": "name@example.org",
        "phone": "string"
      }
    }
  }
}
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 200) the tool returns one text item holding the API's JSON, pretty-printed.

Voucher issued and the QR email accepted by the mail transport.

json
{
  "code": "string",
  "deliveredTo": "name@example.org",
  "id": "11111111-1111-4111-8111-111111111111",
  "qrPayload": "string",
  "state": "ISSUED",
  "emailMessageId": "string"
}

Fields

FieldTypeDescription
codestringThe voucher code as it was BEFORE the transition (read pre-issue).
deliveredTostring (email)Echo of the request email.
emailMessageIdstringTransport message id; absent when the transport reported none.
idstring (uuid)
qrPayloadstringThe verification URL encoded in the QR image.
state"ISSUED"Hardcoded literal, not read back from the voucher.

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

PARTIAL SUCCESS. The voucher IS issued and persisted; only the email failed. The body is not the canon error shape — it carries the payload needed to deliver the voucher by another route, and a retry of this endpoint would re-send rather than re-issue.

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_by_id_issue",
  "description": "POST /api/vouchers/{id}/issue — Walks the voucher CREATED → ASSIGNED → ISSUED (each hop validated by the state machine), then generates the QR payload and emails it. A voucher already in ISSUED is re-sent; a voucher in any other state is refused with 409. Issuing assigns the voucher to NO clinic: it stays with the org holding it (its batch's distributor, or the platform), and any clinic takes it when the bearer presents it (`POST /api/vouchers/{id}/verify`). PARTIAL SUCCESS IS A REAL OUTCOME HERE: when the write succeeds but the email does not, the answer is 502 carrying the voucher `id`, `state` and `qrPayload` alongside `error`, so the caller can deliver it another way. That 502 body is deliberately NOT the canon error body, which would drop those fields.\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": "Voucher id."
      },
      "body": {
        "type": "string",
        "description": "The JSON request body: { email*: string (Beneficiary address the QR is delivered to.); phone: string (Recorded as the contact phone on the ISSUED transition.) }"
      }
    },
    "required": [
      "id",
      "body"
    ]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": false
  }
}