Marshal Fiscal API

Quickstart

1. Create a test key in Settings → Developer API. It works before your device is enrolled.
2. Ask for the taxpayer's tax table: GET /v1/ls/terminals/{id}/tax-codes, and use those tax_ids on your lines.
3. Post an invoice. With a test key it is filed at the Lekuka practice gateway and comes back fiscalized, with receipt numbers, a verification code and a QR link. Nothing reaches RSL.
4. Swap in a live key. Print fiscal.verification_code and a QR of fiscal.qr_url on the receipt.

# One Idempotency-Key per invoice; resend the SAME key to retry.
IDEM=$(uuidgen)
curl -X POST https://dev-pos-backoffice.marshal.co.ls/v1/ls/invoices \
  -H "X-Api-Key: $MARSHAL_API_KEY" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  -d '{"invoice_number":"INV-1001","lines":[{"description":"Maize meal 12.5kg","quantity":"2","unit_price":"115.00","tax_id":7},{"description":"Delivery","quantity":"1","unit_price":"50.00","tax_id":1,"is_service":true}],"payments":[{"method":"Cash","amount":"280.00"}]}'

Keys

• A business creates its keys in Settings → Developer API. mk_test_… keys file at the Lekuka practice gateway and never reach RSL (see Test mode); mk_live_… keys file for real.
• A key is shown once. Store it in your system's secret store, never in code or in a browser. We keep only its fingerprint.
• A key can be limited to chosen terminals and given an expiry. The developer settings show when and from where each key was last used.
• Scopes. A key holds only what it needs: documents:write (file), documents:read, terminals:write (enrol, open and close days), terminals:read and usage:read. New keys get all five; a reporting tool needs only the read scopes. A call outside them is 403 insufficient_scope. Each endpoint below names its scope.
• Allowed addresses. A key can be limited to IP addresses or ranges (e.g. 203.0.113.0/24), such as your office or your servers' outbound addresses. From anywhere else it is refused with 403 ip_not_allowed, even with the right key.
• Rotating. Press Rotate on the key: the new key is shown once and works at once, and the old one keeps working for the overlap you choose (7 days by default, up to 30), then answers 401 key_expired. Switch your system over within the overlap. Revoke stops a key immediately.

Retries and duplicates

Every POST sends an Idempotency-Key header: a new value for each operation (a UUID), kept with the invoice in your system. If the call times out or the connection drops, send it again with the same key: within 24 hours you get the first answer back (same status and body, with Idempotent-Replay: true) and nothing is filed twice. The same key with a different body is refused (422 idempotency_key_reused); a retry while the first request is still running gets 409 idempotency_in_progress: wait a few seconds and retry. A server error (5xx) is not kept, so retrying after one runs the request afresh.

Your invoice_number is the document's identity on its terminal. Sending the same document again — after a timeout, say — returns the original (200), never a second filing. The same number with different content is refused (409 idempotency_conflict): correct a filed document with a credit or debit note instead. RSL needs invoice numbers unique per taxpayer, so a number another terminal of the same business used is refused too (409 invoice_number_in_use).

Limits and timeouts

• 600 requests a minute per key. Every response says where you stand: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (seconds). Over the limit: 429 with Retry-After.
• Bodies are JSON (Content-Type: application/json), at most 2 MB. Unknown fields are refused, never ignored.
• Filing waits for RSL. If RSL is slow or down the answer is 202 Accepted with status queued: the document is numbered and signed and is filed as soon as RSL answers. Listen for the webhook (document.fiscalized, document.flagged or document.failed) or read the document again. Do not post it again as a new invoice. Give your HTTP client a timeout of 30 seconds or more.

Test mode

A test key files for real at the Lekuka practice gateway, a copy of RSL's gateway that Marshal runs. Nothing reaches RSL. Each of your terminals has a test terminal of its own there, so a test document never takes a number from a real receipt sequence or fiscal day. Test keys work before the business's fiscal device is enrolled.

• The document is kept. List, get, stats and the PDF work with the test key, and name your terminal's id. A live key never sees test documents, and a test key never sees live ones.
• It gets receipt numbers, a verification code and a QR link from the practice gateway. The QR opens a check at business.marshal.co.ls/practice-receipt, the way RSL's opens RSL's portal. The PDF is marked as a test.
• The practice gateway answers with RSL's validation codes (Red and Yellow RCPT…), so you can test how your system handles a flagged document.
• Credit and debit notes, fiscal days (open, close, and automatic days) and tax codes all work with the test key, on the test terminal.
• Webhooks reach your endpoints whose mode is test or both, with "test": true in the payload.
• Answers say "mode": "test" and "test": true. Test documents are never billed and never count as live use (GET /v1/usage shows them as test_documents).
• Check without filing: add ?dry_run=true to POST /v1/ls/invoices. The real checks, numbering and signing run and are then rolled back, with a sandbox key. Nothing is kept, and the answer has status validated and "dry_run": true. Test keys only.
• Test terminals always file online. Offline day files cannot be tested with a test key.

Endpoints

Base URL https://dev-pos-backoffice.marshal.co.ls. Send the key as X-Api-Key or Authorization: Bearer.

{
  "buyer": {
    "name": "Acme (Pty) Ltd",
    "tin": "200012345-6"
  },
  "invoice_number": "INV-1002",
  "lines": [
    {
      "description": "Consulting, September",
      "is_service": true,
      "quantity": "1",
      "tax_category": "standard",
      "unit_price": "5750.00"
    }
  ]
}

{
  "invoice_number": "CN-0001",
  "lines": [
    {
      "original_line": 1,
      "quantity": "1",
      "unit_price": "115.00"
    }
  ],
  "original_invoice_number": "INV-1001",
  "reason": "Damaged bag returned",
  "settlement": "Cash",
  "type": "credit_note"
}

{
  "invoice_number": "INV-1001",
  "lines": [
    {
      "description": "Maize meal 12.5kg",
      "quantity": "2",
      "tax_id": 7,
      "unit_price": "115.00"
    },
    {
      "description": "Delivery",
      "is_service": true,
      "quantity": "1",
      "tax_id": 1,
      "unit_price": "50.00"
    }
  ],
  "payments": [
    {
      "amount": "280.00",
      "method": "Cash"
    }
  ]
}

Objects

Amounts. Every amount in an answer is a decimal string with two places ("230.00"), never a binary float, so totals reconcile to the cent in any language. In requests, send quantities and amounts as decimal strings (recommended) or numbers, with at most four decimals. Tax rates are numbers (15 = 15%).

Webhooks

Add endpoints in Settings → Developer API. Each event is a POST with Marshal-Event, Marshal-Delivery and Marshal-Signature: t=…,v1=…. Answer 2xx within 10 seconds; anything else is retried with backoff for about two days. The same event can arrive twice — use the delivery id to ignore repeats.

Rotating an endpoint's secret keeps the old one signing for 24 hours: the header then carries a v1= for each secret. Accept a delivery when any v1 matches (as below), and switch your stored secret within the day.

Events: document.fiscalized, document.flagged, document.failed, document.validated (a test key on a server without the practice gateway), fiscal_day.closed, fiscal_day.close_failed, offline_file.processed, ping. An endpoint receives test events when its mode is test or both.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a Buffer or string).
// While a secret is being rotated the header carries one v1 per secret:
// accept the delivery when any of them matches.
function verify(rawBody, header, secret) {
  const pairs = header.split(",").map((p) => p.split("="));
  const t = pairs.find(([k]) => k === "t")?.[1];
  const sigs = pairs.filter(([k]) => k === "v1").map(([, v]) => v);
  const expected = Buffer.from(crypto.createHmac("sha256", secret)
    .update(`${t}.${rawBody}`).digest("hex"));
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && sigs.some((v) => v.length === expected.length && crypto.timingSafeEqual(expected, Buffer.from(v)));
}

Errors

One shape for every error — our stated equivalent of RFC 9457 problem details. code is for your program, message for a person, fields maps each wrong field to its problem. Quote requestId to support; send your own X-Request-Id to set it.

{
  "error": {
    "code": "validation_failed",
    "message": "The document has 1 problem(s); see details.",
    "details": [{ "field": "lines[0].tax_id", "message": "tax_id 99 is not in this taxpayer's tax table" }],
    "fields": { "lines[0].tax_id": "tax_id 99 is not in this taxpayer's tax table" },
    "requestId": "5f25c421-3e42-4eac-8bc2-ab3e62e065ad"
  },
  "request_id": "5f25c421-3e42-4eac-8bc2-ab3e62e065ad"
}

RSL's codes

RSL's own codes are passed through unchanged: in fiscal.validation_errors when RSL accepted a document with an error (status flagged), or in error.rule when the API stopped the document before filing (rejected_by_rulebook — nothing was numbered or filed). A Red document is corrected with a credit note; Yellow is a warning.

Notes for integrators

The pattern is the same everywhere: when your system posts a sale document, send it here with your own document number as invoice_number; keep the verification_code and qr_url that come back and print them on the document. Map your taxes once to the terminal's tax_ids. Only Lesotho (ls) is live; send only Lesotho companies' documents.