JoFotara API documentation

1. Get access

Create a partner account, sign in, and open Integration keys. Copy the token when it is created and save it in your backend’s secret store. Ask an administrator to add invoice allowance.

Your API key identifies the partner account that owns the submission and provides its invoice balance.

2. Send a sandbox invoice

Save the sample JSON below as invoice.json. Generate your own UUID once per invoice and keep it stable across retries. The sample date must be today or earlier in Jordan.

{
  "id": "INV-2026-001",
  "uuid": "39c1aaed-33fa-4b15-9f12-201bb351cbe9",
  "icv": "1",
  "issueDate": "2026-10-01",
  "invoiceType": "StandardIncome",
  "salesPaymentMethod": "CashGeneralSalesInvoice",
  "currency": "JOD",
  "supplier": {
    "taxNumber": "11111111",
    "name": "Example supplier",
    "incomeSourceSequence": "22222222"
  },
  "buyer": {},
  "lines": [{
    "id": "1",
    "name": "Service",
    "quantity": 1,
    "unitPrice": 10,
    "discount": 0,
    "taxRate": 16,
    "taxCategory": "S",
    "specialTaxAmount": 0
  }]
}

curl -X POST "https://jordanapi.avtax.net/api/v2/invoices" \
  -H "Partner-Api-Key: $PARTNER_API_KEY" \
  -H "X-Sandbox-Mode: true" \
  -H "Content-Type: application/json" \
  --data-binary @invoice.json

Sandbox runs the same local invoice checks and returns unsigned XML in xmlBase64. It does not contact JoFotara, create a government signature, or store XML in Cloudflare. Save the returned XML; an identical submission retry regenerates it. Each successful sandbox invoice consumes one allowance unit. This sample calculates JOD 1.600 VAT and JOD 11.600 payable.

3. Submit a live invoice

Replace all sample supplier and invoice fields with real data. Set X-Sandbox-Mode: false or omit it, and add the supplier’s government credentials.

Gov-Client-Id: supplier-government-client-id
Gov-Client-Secret: supplier-government-secret

Keep credentials on your backend and send them over HTTPS. They are forwarded only for the current submission; they are not stored in the invoice record. Never include them in invoice JSON or your request logs.

The supplier tax number and income-source sequence must be correct for that supplier’s JoFotara credentials. Our locally entered invoice details do not independently prove taxpayer authorization; JoFotara remains the authority for acceptance.

Understand the result before retrying

An identical retry with the same partner, mode, UUID and content returns the existing result. It does not contact JoFotara again. Never use a new UUID to retry an unresolved invoice: the government may already have accepted it.

GET /api/v2/invoices/{uuid}
Partner-Api-Key: your-integration-key
X-Sandbox-Mode: true-or-false

Retrieve XML and convert it back to JSON

These calls require only Partner-Api-Key and consume no invoice allowance. They remain available with a zero balance. For status reads, use the original submission’s live/sandbox mode. Sandbox XML downloads return 404 because no XML is archived.

Live XML is stored privately in Cloudflare R2 and automatically deleted after 90 days (about 3 months) from acceptance. Download your own copy before expiry. Invoice history and allowance records remain available after the XML files are removed. xmlSource and the download header X-Invoice-Xml-Source distinguish Government signed XML, Generated XML and Sandbox XML. A generated or sandbox document is not proof of government acceptance or a valid signature.

Parsing is a conversion utility. It does not verify signatures, acceptance or ownership. The decoded XML limit is 1 MiB, with a maximum depth of 32 and 50,000 reader nodes.

Invoice rules for this route

Invoice validation follows JoFotara technical guide version 1.5. Supported currency: JOD; no exchange-rate conversion is performed.

• Invoice type: StandardIncome for an invoice; ReturnedIncome for a credit note.
• Sales payment method: send the enum name, such as CashGeneralSalesInvoice, AccountsReceivableGeneralSalesInvoice, or CashIncomeBill. Swagger lists the supported methods. The API converts these names into JoFotara codes when generating XML.
• VAT: allowed rates are 0, 1, 2, 3, 4, 5, 7, 8, 10 and 16. Use S with positive rates, O for zero-rated, and Z for exempt lines. Non-local general/special invoices require 0% and O.
• Special tax: provide its amount per line. VAT is calculated as (quantity × unitPrice − discount + specialTaxAmount) × taxRate / 100.
• Discount: provide a total amount for each line. Distribute invoice-wide discounts among lines in your source system first.
• Precision: quantity, price, discount and special tax accept up to 9 decimal places. Calculated amounts use 9 decimals, midpoint away from zero; totals sum those line amounts. The guide’s stated rounding difference is at most 0.001.
• Buyer name: required for receivable invoices, and cash invoices strictly above JOD 10,000. Exactly JOD 10,000 does not trigger the cash threshold.
• Development areas: require buyer.idType: "TN" and the buyer’s tax number; the government’s exemption eligibility must also be valid.
• ICV: your taxpayer-managed sequential numeric counter. Keep it consistent across the taxpayer’s systems.

Returns

Include originalInvoice with its id, uuid, total and reason. For live returns, the original accepted invoice must be available in this partner’s v2 archive. Sandbox returns use retained validation metadata to apply the same buyer, supplier, price, tax and quantity checks without storing XML. Preserve its supplier, sales payment method, currency, line IDs, descriptions and unit prices.

Use positive returned quantities, prorate line discounts, and supply the correct special-tax amount. Earlier accepted and unresolved returns reserve quantities, preventing a new return from exceeding the original quantity. Returns for originals outside the v2 archive or past its retention period cannot be verified by this route.

Errors and request limits

Platform limits: 2 MiB request body; 1 MiB XML; up to 1,000 invoice lines; 120 requests per minute and 8 concurrent requests per partner; 600 requests per minute per source IP. Invoice allowance is separate from these request limits.