Marshal Fiscal API

Fiscalise invoices with the tax authority from any system. Version 1.0.0.

Send an invoice; Marshal validates it against the taxpayer's own tax table, numbers and signs it on your fiscal device, files it with the tax authority and returns the fiscal details (receipt numbers, verification code, QR link).

Keys. mk_test_… keys are a full sandbox: documents go through the real validation, numbering and signing, then are rolled back — nothing reaches the tax authority and they are never billed. mk_live_… keys file for real.

Idempotency. Your invoice_number is the idempotency key, per terminal and mode. Re-sending the same number with the same content returns the original document (HTTP 200, header Idempotent-Replay: true); the same number with different content is refused with 409 idempotency_conflict. It is always safe to retry after a timeout.

Corrections. An issued invoice can never be changed. Correct it with a credit_note or debit_note that names it in original_invoice_number.

Errors always have the shape {"error": {"code", "message", "details"?}, "request_id"}.

Webhooks are signed: Marshal-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>.

curl -X POST https://dev-pos-backoffice.marshal.co.ls/v1/ls/invoices \
  -H "X-Api-Key: $MARSHAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice_number":"INV-1001","lines":[{"description":"Maize meal 12.5kg","quantity":2,"unit_price":115,"tax_id":7},{"description":"Delivery","quantity":1,"unit_price":50,"tax_id":1,"is_service":true}],"payments":[{"method":"Cash","amount":280}]}'

{
  "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
    }
  ]
}

{
  "invoice_number": "CN-0001",
  "lines": [
    {
      "original_line": 1,
      "quantity": 1,
      "unit_price": 115
    }
  ],
  "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
    },
    {
      "description": "Delivery",
      "is_service": true,
      "quantity": 1,
      "tax_id": 1,
      "unit_price": 50
    }
  ],
  "payments": [
    {
      "amount": 280,
      "method": "Cash"
    }
  ]
}

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a Buffer or string)
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

{
  "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" }]
  },
  "request_id": "5f25c421-3e42-4eac-8bc2-ab3e62e065ad"
}