jofotara-kit

اقرأ الدليل بالعربية

The JoFotara sandbox that doesn't exist — plus a document builder, a safe submission client, a validator and an AI agent skill.

JoFotara (فوترة, Jordan's ISTD e-invoicing system) has no test environment. The only way to see if your XML is right is to send a real invoice with real credentials and create a real tax record. jofotara-kit lets you get the shape right locally first:

• build — turns plain sale data into a valid invoice or return: tax-inclusive prices, line and order discounts, exempt and zero-rated lines, buyer rules, and partial returns that add up to the invoice exactly. From TypeScript/JavaScript, or from any language through JSON.
• send — submits documents and sorts every answer into accepted, rejected, unknown or not sent, so a timeout is never mistaken for a rejection and resent as a duplicate tax record.
• validate — lints JoFotara UBL 2.1 XML against the rules of the official ISTD technical guide (v1.4): type names, tax categories S/Z/O and allowed VAT rates, buyer IDs, totals formulas, return references and the extra fields sales returns need. Every finding cites the manual page and says how to fix it.
• serve — a local mock of POST /core/invoices/: same path, same Client-Id / Secret-Key headers, same {"invoice": base64} body, EINV_STATUS / EINV_RESULTS / EINV_QR-shaped responses. It remembers what it accepted, so duplicates, returns against unknown invoices and over-returns across several partial returns are rejected, line by line.
• template — prints sales and income invoices and (partial) returns, cash and receivable, in the manual's shape.
• Agent skill — teaches Claude Code, Cursor, Devin, Codex & co. how JoFotara works and makes them validate their own output instead of guessing.

Not affiliated with the Income and Sales Tax Department. Passing jofotara-kit means "passes known rules", not "accepted by ISTD".

Quick start

npx jofotara-kit template invoice > invoice.xml
npx jofotara-kit validate invoice.xml
npx jofotara-kit serve --port 8080

Then point your integration's base URL at http://127.0.0.1:8080 instead of https://backend.jofotara.gov.jo. Nothing else changes.

curl -s http://127.0.0.1:8080/core/invoices/ \
  -H "Client-Id: test" -H "Secret-Key: test" -H "Content-Type: application/json" \
  -d "$(npx jofotara-kit template invoice --body)"

To use it from your code, tests or CI, install it (Node.js 22.18 or later):

npm install jofotara-kit

Build documents

Describe the sale; the builder does the JoFotara math and writes XML that passes every rule.

import { buildInvoice, buildCreditNote } from 'jofotara-kit';

const invoice = buildInvoice({
  id: 'INV-1001', icv: 57,                       // your number and your invoice counter
  seller: { taxNumber: '…', name: '…', incomeSourceSequence: '…' },
  pricesIncludeTax: true,                        // shelf prices; VAT is taken out exactly
  lines: [
    { name: 'Coffee', quantity: 3, unitPrice: 2.5, taxRate: 16, discount: { percent: 10 } },
    { name: 'Bread', quantity: 2, unitPrice: 0.75, taxRate: 0, taxCategory: 'Z' },
  ],
  orderDiscount: { amount: 1 },                  // spread over the lines for you
});
// invoice.xml, invoice.body (the request body to POST), invoice.document (every computed amount)

const ret = buildCreditNote({
  original: storedInvoiceXml,                    // the XML you sent and stored
  previousReturns: [storedReturnXml],            // earlier returns against it
  lines: [{ lineId: 1, quantity: 1 }],           // or 'all' for everything not yet returned
  reason: 'Customer return', id: 'RET-1001', icv: 58,
});

What it takes care of:

• Money — exact arithmetic in micro-JOD, amounts written with six decimals. With pricesIncludeTax, each line's amount plus VAT equals what the customer paid, exactly.
• Tax categories — S at an allowed rate; a 0% line must say Z (exempt) or O (zero-rated). Rates outside the manual's list are refused before any XML exists.
• Buyers — a walk-in buyer (TN 0, "Cash customer") by default; a named buyer is required for receivables and cash sales above 10,000 JOD.
• Returns — built from the original XML alone: original line numbers, names, prices, categories, buyer and type name are mirrored, sales returns get their extra fields, returned quantities are tracked across returns (over-returns are refused), and the last return of a line takes exactly what is left, so the returns always add up to the invoice.
• Errors — a BuildError whose code is the rule the input would break, e.g. JOF-STA-005 for an over-return.

Keep the uuid of every document you send: a retry after a timeout must reuse the same XML. readDocument(xml) reads any stored JoFotara document back into plain amounts.

Special sales (013/023) follow the manual's formulas (p.56-80) but have not been verified against the live API yet; builds report this in warnings.

From any language

jofotara-kit build takes the same fields as JSON, so PHP, .NET, Python or Java code can shell out to it:

npx jofotara-kit build invoice.json > INV-1001.xml
npx jofotara-kit build invoice.json --body     # the request body instead of XML
npx jofotara-kit build invoice.json --json     # {xml, body, document, warnings}

A return names its original (and earlier returns) by path, relative to the JSON file:

{
  "type": "credit-note",
  "original": "INV-1001.xml",
  "previousReturns": ["RET-1000.xml"],
  "lines": [{ "lineId": 1, "quantity": 1 }],
  "reason": "Customer return",
  "id": "RET-1001",
  "icv": 58
}

A build error exits with status 1 and prints the rule id and the reason.

Send documents

The dangerous part of going live is not the XML — it is the answer. A timeout does not mean the invoice was rejected; resending a new document for the same sale can create a duplicate tax record. The client sorts every submission into one of four outcomes:

import { createClient, JOFOTARA_PRODUCTION_URL } from 'jofotara-kit';

const jofotara = createClient({
  baseUrl: 'http://127.0.0.1:8080',   // required: the local mock, or JOFOTARA_PRODUCTION_URL on purpose
  clientId: process.env.JOFOTARA_CLIENT_ID!,
  secretKey: process.env.JOFOTARA_SECRET_KEY!,
});

const outcome = await jofotara.submit(invoice);   // XML, request body, or a build result

| outcome.status | When | What to do | |---|---|---| | accepted | HTTP success and an explicit success status and a QR code | Store outcome.qr and outcome.raw; print the QR on the invoice. | | rejected | Explicit rejection (NOT_SUBMITTED, ERROR, an error list) and no sign of acceptance — also when it arrives with HTTP 200 | Show outcome.errors, fix, send again. | | unknown | Timeout, dropped connection, unreadable or HTML response, 5xx, success without a QR, contradictory answers | Do not send a new document for this sale. Check the portal; to retry, send this exact XML again (same UUID). | | not-sent | The document failed validation, or the server could not be reached at all (DNS, connection refused) | Nothing was recorded; fix and send. |

The client validates before sending (validateBeforeSending: false turns that off), never retries on its own, and never puts the secret key in an outcome. classifyResponse(status, body) applies the same rules to a response you received with your own HTTP code.

From the command line, documents are sent in order and sending stops at the first one that is not accepted, so a return is never sent after its invoice failed:

npx jofotara-kit serve &                                  # the local mock
npx jofotara-kit send INV-1001.xml RET-1001.xml           # goes to the mock by default

send --production goes to https://backend.jofotara.gov.jo and takes the credentials only from the JOFOTARA_CLIENT_ID and JOFOTARA_SECRET_KEY environment variables. Exit status: 0 accepted, 1 rejected or not sent, 3 unknown.

MCP server

Give any MCP client (Claude Code, Cursor, Devin, Windsurf, …) direct access to the validator:

{
  "mcpServers": {
    "jofotara": { "command": "npx", "args": ["-y", "jofotara-kit", "mcp"] }
  }
}

Tools: build_invoice, build_credit_note, validate_invoice, get_template, list_rules, explain_rule.

Install the agent skill

npx skills add balwahidi/jofotara-kit

Or copy skills/jofotara into your agent's skills folder (.claude/skills/, .devin/skills/, .cursor/skills/, …).

Commands

| Command | What it does | |---|---| | build [input.json] [--body \| --json] | Build an invoice or return from JSON (see Build documents). Reads stdin if no file. Exit 1 on build errors. | | send <files...> [--production \| --base-url URL] [--json] [--timeout MS] [--no-validate] | Send documents in order and classify each answer (see Send documents). Mock by default; credentials from the environment. | | validate [files...] [--json] | Validate XML, a {"invoice": base64} request body, or bare base64. Reads stdin if no files. Exit 1 on errors. | | serve [--port] [--host] [--client-id] [--secret-key] [--reject-status] | Run the mock. With --client-id/--secret-key only those credentials pass. --reject-status 200 tests "HTTP 200 but rejected" handling. | | template <name> [--body] | Print a sample XML, or its JSON request body. Names below. | | rules [--json] | List every rule. | | mcp | MCP server over stdio. |

Templates:

| Name | Type | Document | |---|---|---| | invoice | 388 / 012 | Sales invoice, cash (S, Z and O lines) | | credit-note | 381 / 012 | Partial sales return | | receivable-invoice | 388 / 022 | Sales invoice, receivable (named buyer) | | receivable-credit-note | 381 / 022 | Partial return of a receivable sales invoice | | income-invoice | 388 / 011 | Income invoice, cash (no VAT) | | income-credit-note | 381 / 011 | Partial income return | | income-receivable-invoice | 388 / 021 | Income invoice, receivable (named buyer) | | income-receivable-credit-note | 381 / 021 | Partial return of a receivable income invoice |

Mock extras: GET /_kit/invoices lists accepted documents, DELETE /_kit/invoices resets. Mock responses add a JOFOTARA_KIT key with full findings and fixes; everything else mirrors the real response shape. The mock QR decodes to JOFOTARA-KIT MOCK|NOT A TAX DOCUMENT|….

Use in CI

# have your test suite write the XML your integration generates to out/, then:
npx jofotara-kit validate out/*.xml

Or as a library:

import { validate } from 'jofotara-kit';

const report = validate(xml);
if (!report.ok) throw new Error(report.findings.map((f) => `${f.rule}: ${f.message}`).join('\n'));

Where the rules come from

Every rule states its source:

| Source | Meaning | |---|---| | manual p.N | Stated in the ISTD technical guide for the e-invoicing API, v1.4 (2023-12-01), page N. | | verified | Observed on the live API and contributed back with a redacted response. | | inferred | Follows from UBL 2.1 or accounting common sense; not in the manual. |

Run npx jofotara-kit rules for the full list.

Scope

The builder, the validator and the mock cover all six document families in the manual, in JOD: income (011/021), general sales (012/022) and special sales (013/023), each as new invoice (388) and return (381) — full, partial and multiple returns. Special sales are not yet verified against the live API. Templates cover income and general sales.

Contributing

The most valuable contribution is a real JoFotara response — especially a rejection the kit didn't predict — with the XML (redacted: tax numbers, names, income source sequence) and the response body. That is how inferred rules become verified. Never share your Client-Id or Secret-Key.

npm install
npm test
npm run build

License

MIT