Zansync API Reference

Zansync is a ZRA VFMS compliance layer. Instead of integrating directly with the ZRA API — which requires managing separate authentication headers, two endpoint sets, and credential storage — you call Zansync once and we handle the ZRA communication on your behalf.

This documentation covers all available endpoints for both Basic VFMS (restaurants, bars, retail) and Hotel VFMS (accommodation lifecycle).

📘 Need API access? Register at zansync.com to receive your API key and onboarding. Test keys are issued immediately.

Base URLs

TESThttps://api.zansync.com/api/zs/v1 (test mode)

LIVEhttps://api.zansync.com/api/zs/v1 (production)

Authentication

All requests require your Zansync API key in the X-Zansync-Key header. Keys are issued per property. Sandbox/test keys may be raw alphanumeric strings or prefixed with zs_test_; production keys are prefixed with zs_live_.

# Include on every request
X-Zansync-Key: zs_live_your_key_here

⚠️ Never expose your API key in client-side JavaScript or public repositories.

Environments

The test environment connects to ZRA's official test servers with pre-loaded sandbox credentials. No real fiscal receipts are issued in test mode.

Environment	Base URL	Real Receipts
Test	api.zansync.com/api/zs/v1 use a zs_test_* key	No
Live	api.zansync.com/api/zs/v1 use a zs_live_* key	Yes

✓ Your test API key is pre-configured with ZRA sandbox credentials. No ZRA setup needed to start testing.

📋 To go live: request your production ZRA Integration ID & Token through your dashboard at admin.zansync.com/credentials. Our team forwards the request to ZRA on your behalf.

Basic VFMS

Use Basic VFMS endpoints to issue ZRA fiscal receipts for all non-accommodation sales — restaurants, bars, cafes, retail, and general services.

POST /v1/sales — Normal Sales

Issue a ZRA fiscal receipt for a standard walk-in customer transaction. Use for all taxable sales to individual customers.

POST/v1/salesWalk-in customer sale ▾

Parameter	Type		Description
reference	string	required	Your unique order/transaction ID
customer	string	required	Customer name. Use "Walk-in" for anonymous.
phone	string	optional	Customer phone number
currency	enum	required	TZS · USD · EURO
items	array	required	Array of sale items
items[].name	string	required	Item or service name
items[].price	number	required	Unit price (tax inclusive)
items[].quantity	number	required	Quantity sold
items[].discount	number	optional	Discount amount. Default 0.
items[].item_id	number	optional	0 for taxable items. Use ID from /v1/non-tax-items for exempt goods.

# Request
curl -X POST https://api.zansync.com/api/zs/v1/v1/sales \
  -H "X-Zansync-Key: zs_test_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ORD-1042",
    "customer": "Walk-in",
    "currency": "TZS",
    "items": [
      {"name":"Grilled Prawns","price":45000,"quantity":1,"item_id":0},
      {"name":"Fresh Juice","price":5000,"quantity":2,"item_id":0}
    ]
  }'

# Response 200
{
  "receipt_number": "213590000076220812",
  "response_number": "441514155",
  "z_number": "Z025608121",
  "tax_exclusive": 47826.09,
  "tax_amount": 7173.91,
  "total": 55000.00,
  "currency": "TZS",
  "business_name": "THE BOX BY ASHLEY",
  "qr_url": "http://102.223.7.131:6060/vfms/checkout-receipt-form/guest/213590000076",
  "issued_at": "2026-04-18T17:31:00+03:00",
  "status": "success"
}

POST /v1/btob — B2B Sales

For sales to ZRA-registered business customers. The buyer's ZRB registration number is required.

POST/v1/btobBusiness-to-business sale ▾

Parameter	Type		Description
reference	string	required	Unique transaction reference
zrb_number	string	required	Customer ZRB registration number (e.g. Z0025383974)
phone	string	required	Customer phone number
currency	enum	required	TZS · USD · EURO
items	array	required	Same structure as Normal Sales

POST /v1/institution — Institution Sales

For sales to government institutions and withholding agents. Tax is withheld and calculated separately per ZRA rules.

POST/v1/institutionGovernment / withholding agent sale ▾

Parameter	Type		Description
reference	string	required	Unique transaction reference
zrb_number	string	required	Institution ZRB registration number
phone	string	required	Institution phone number
currency	enum	required	TZS · USD · EURO
items	array	required	Same structure as Normal Sales

POST /v1/relief/check — Check Relief Number

Verify a special relief number issued by ZRA before processing a relief sale.

POST/v1/relief/checkVerify relief number ▾

Parameter	Type		Description
relief_number	string	required	Customer special relief number issued by ZRA

POST /v1/relief/save — Save Relief Sale

Process a relief sale after verifying the relief number. Use the relief_id returned from the check endpoint.

POST/v1/relief/saveIssue relief sale receipt ▾

Parameter	Type		Description
relief_id	number	required	ID returned from /v1/relief/check

GET /v1/non-tax-items — Non-Taxable Items

Retrieve the current ZRA list of exempt (non-taxable) items. Use the returned id values as item_id in sales requests for exempt goods. No request body required.

GET/v1/non-tax-itemsZRA exempt item list ▾

# Response
[
{"id":219, "name":"SEAFOOD", "unit":"No", "taxable":false},
{"id":216, "name":"RICE", "unit":"No", "taxable":false}
]

POST /v1/seaport/local — Seaport Local Sales

For seaport ticketing agents issuing receipts for passengers travelling locally (Unguja–Pemba) or to Mainland.

POST/v1/seaport/localLocal passenger sale ▾

Parameter	Type		Description
reference	string	required	Unique transaction reference
ticket_number	string	required	Ticket number from your system
customer	string	required	Passenger name (LOCAL or MAINLAND)
phone	string	required	Customer phone
currency	enum	required	TZS · USD
departure_date	datetime	required	ISO 8601 departure datetime
items	array	required	Ticket items with name, price, quantity

POST /v1/seaport/foreign — Seaport Foreign Charge

For charging foreign passengers travelling outside Tanzania. Provide number of passengers and reference number.

POST/v1/seaport/foreignForeign passenger charge ▾

Parameter	Type		Description
no_pax	integer	required	Number of passengers
reference	string	required	Unique transaction reference

POST /v1/seaport/foreign — Seaport Foreign Charge

Charge foreign passengers travelling outside Tanzania via seaport. Provide the number of passengers and a unique reference.

POST/v1/seaport/foreignForeign passenger charge ▾

Parameter	Type		Description
no_pax	integer	required	Number of foreign passengers
reference	string	required	Unique transaction reference

GET /v1/error/report — Error Correction Status

Retrieve the status of submitted error corrections. Filter by review status to see what is pending, approved, rejected, or under verification.

GET/v1/error/reportList error correction submissions ▾

Parameter	Type		Description
status	string	optional	0 (all) · Pendings · Approved · Rejected · Verification. Default: 0

POST /v1/error — Error Correction

Submit a correction when a receipt was issued in error. ZRA will cancel the old receipt and log the new correct one.

POST/v1/errorCancel and correct a receipt ▾

Parameter	Type		Description
old_receipt	string	required	Incorrect receipt number to cancel
new_receipt	string	required	Replacement correct receipt number
reason	string	required	Reason for correction
email	string	required	Taxpayer email for ZRA notification
phone	string	required	Taxpayer phone number

Hotel VFMS

Hotel VFMS manages the full accommodation lifecycle — check-in through fiscal checkout. ZRA calculates infrastructure tax automatically per guest per night from the moment of check-in. The fiscal receipt is generated at checkout.

ℹ️ Hotel VFMS requires the Professional or Enterprise plan. Every guest must use a unique reference at check-in — store this to use in all subsequent endpoints for that guest stay.

POST /v1/hotel/checkin — Guest Check-In

Register a guest with ZRA at check-in. ZRA begins calculating infrastructure tax from this moment. Must be called at the time of physical check-in.

POST/v1/hotel/checkinRegister guest with ZRA ▾

Parameter	Type		Description
reference	string	required	Your unique booking reference. Store this — needed for checkout.
room_name	string	required	Room number or name
room_id	integer	required	Your internal room ID
price	number	required	Nightly accommodation price (tax inclusive)
discount	number	optional	Discount amount. Default 0.
currency	enum	required	USD · TZS · EURO
checkin_date	datetime	required	ISO 8601 (e.g. 2026-04-18T14:00:00Z)
payment_package	string	required	AI (All Inclusive) · FB (Full Board) · BB (Bed & Breakfast) · HB (Half Board)
source	enum	required	DIRECT · TOUR_OPERATOR
tour_reg_no	string	conditional	Required if source is TOUR_OPERATOR. Tour operator ZRA registration number.
guests	array	required	Array of guest objects
guests[].full_name	string	required	Guest full name
guests[].document_type	string	required	PASSPORT · NIDA · ZANID
guests[].document_no	string	required	Document number. Store this — needed for checkout.
guests[].country	string	required	Guest country of origin
guests[].arrival_date	string	required	Date of arrival in Zanzibar (yyyy-mm-dd)

curl -X POST https://api.zansync.com/api/zs/v1/v1/hotel/checkin \
  -H "X-Zansync-Key: zs_test_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "BK-2026-0418",
    "room_name": "Ocean Suite 12", "room_id": 12,
    "price": 150, "currency": "USD",
    "checkin_date": "2026-04-18T14:00:00Z",
    "payment_package": "BB", "source": "DIRECT",
    "guests": [{
      "full_name": "John Smith",
      "document_type": "PASSPORT",
      "document_no": "GBP123456",
      "country": "UNITED KINGDOM",
      "arrival_date": "2026-04-18"
    }]
  }'

POST /v1/hotel/change-room — Change Room

Notify ZRA when a guest moves to a different room. Tax recalculates based on the new room rate from that point.

POST/v1/hotel/change-roomGuest room change ▾

Parameter	Type		Description
reference	string	required	Unique reference for this change event
document_no	string	required	Guest document number from check-in
room_name	string	required	New room name or number
room_id	integer	required	New room ID
price	number	required	New room nightly rate
currency	enum	required	USD · TZS · EURO

POST /v1/hotel/change-price — Change Room Price

Update the nightly rate for one or more rooms without changing the room assignment.

POST/v1/hotel/change-priceUpdate room rate ▾

Parameter	Type		Description
rooms	array	required	Array of room price updates
rooms[].room_id	integer	required	Room ID to update
rooms[].price	number	required	New nightly rate

POST /v1/hotel/change-room-price — Update Room Rate(s)

Update the nightly rate for one or more rooms. Accepts an array so you can adjust multiple rooms in a single call.

POST/v1/hotel/change-room-priceUpdate room nightly rate ▾

Parameter	Type		Description
rooms	array	required	Array of `{ room_id, price }` objects
rooms[].room_id	integer	required	Room ID
rooms[].price	number	required	New nightly rate

GET /v1/hotel/currency-rates — ZRA Currency Rates

Returns the daily ZRA reference rates: USD/TZS, EURO/TZS, USD/EURO. Cached on the server side; safe to call frequently.

GET/v1/hotel/currency-ratesDaily ZRA exchange rates ▾

No request parameters. Returns { rate_usd_tzs, rate_euro_tzs, rate_usd_euro, fetched_at }.

POST /v1/hotel/report — Accommodation Report

Pull a date-range report of all accommodation receipts issued for your property. Useful for reconciliation and monthly summaries.

POST/v1/hotel/reportDate-range receipt report ▾

Parameter	Type		Description
start_date	date	required	YYYY-MM-DD
end_date	date	required	YYYY-MM-DD, ≥ start_date

POST /v1/hotel/service — Hotel Services

Issue a ZRA receipt for hotel extras — restaurant meals, spa, laundry, or any service charged to a checked-in guest or walk-in customer.

POST/v1/hotel/serviceRestaurant or hotel extra ▾

Parameter	Type		Description
reference	string	required	Unique reference for this service transaction
document_no	string	conditional	Guest document number — required for checked-in guest charges (types CR, CS)
currency	enum	required	USD · TZS · EURO
type	enum	required	CR — restaurant, checked-in guest · CS — other service, checked-in guest · WR — restaurant, walk-in · WS — other service, walk-in
items	array	required	Items with name, price, quantity, discount

POST /v1/hotel/add-guest — Add Guest

Add an additional guest to an already occupied room after initial check-in.

POST/v1/hotel/add-guestAdd guest to occupied room ▾

Parameter	Type		Description
reference	string	required	Unique reference for this addition
first_guest_document	string	required	Document number of the primary guest already in the room
full_name	string	required	New guest full name
document_type	string	required	PASSPORT · NIDA · ZANID
document_no	string	required	New guest document number
country	string	required	Guest country of origin
arrival_date	string	required	Date of arrival in Zanzibar (yyyy-mm-dd)

POST /v1/hotel/checkout — Guest Checkout

Check out one or more guests and generate the full ZRA fiscal receipt. This is the final step — ZRA calculates all nights, infrastructure tax, and services into one official receipt.

POST/v1/hotel/checkoutGenerate ZRA fiscal checkout receipt ▾

Parameter	Type		Description
document_numbers	array	required	Array of guest document numbers to check out
currency	enum	required	USD · TZS · EURO

# Request
{ "document_numbers": ["GBP123456"], "currency": "USD" }

# Response 200 — full ZRA fiscal receipt
{
  "report_number": "381418072277",
  "total_amount": 300.00,
  "total_tax": 32.61,
  "total_infrastructure": 20.00,
  "days": 2,
  "z_number": "Z025608121",
  "business_name": "FUMBA BEACH LODGE",
  "qr_url": "http://102.223.7.131:6060/vfms/checkout-receipt-form/guest/381418072277",
  "status": "success"
}

POST /v1/hotel/booking — Tour-Operator Advance Booking

Record an advance booking from a Tour Operator (B2B). Reserves rooms with payment scheduled before guest arrival. Use this before the guest physically arrives; use /hotel/booking/checkin on arrival to convert into an actual fiscal check-in.

POST/v1/hotel/bookingTO advance booking ▾

Parameter	Type		Description
reference	string	required	Unique reference for this booking
booking_company	string	required	Tour-operator company name
reg_number	string	required	Tour operator ZRA / TIN registration number
currency	enum	required	TZS · USD · EURO
start_date	date	required	Expected check-in date (YYYY-MM-DD)
end_date	date	required	Expected check-out date (YYYY-MM-DD)
rooms	array	required	Array of `{ room_id, days, price, discount? }`
guests	array	optional	Array of guest objects (full_name, document_type, document_no, country)

POST /v1/hotel/booking/checkin — Convert Advance Booking to Check-In

Convert a prior advance booking (from /hotel/booking) into an actual fiscal check-in when the guest arrives. Validates the prepayment and issues the accommodation receipt.

POST/v1/hotel/booking/checkinAdvance-payment check-in ▾

Parameter	Type		Description
reference	string	required	Unique reference for this check-in event
booking_number	string	required	Booking number from prior `/hotel/booking` call
receipt_no	string	optional	Advance-payment receipt number
room_id	integer	required	Room ID
room_name	string	required	Room name/number
price	number	required	Nightly rate
currency	enum	required	TZS · USD · EURO
check_in	datetime	required	Actual check-in time (ISO 8601 or YYYY-MM-DD)
check_out	datetime	required	Expected check-out time
guests	array	required	Array of guest objects

POST /v1/hotel/change-profile — Change Guest Profile

Correct guest information if it was entered incorrectly at check-in.

POST/v1/hotel/change-profileCorrect guest information ▾

Parameter	Type		Description
reference	string	required	Unique reference for this correction
old_document_no	string	required	Original incorrect document number
new_document_no	string	required	Correct document number
full_name	string	required	Guest full name
document_type	string	required	PASSPORT · NIDA · ZANID
country	string	required	Guest country of origin

Response Codes

Zansync returns standard HTTP codes. ZRA-specific error details are included in the response body under error.

Code	Meaning	Action
200	Success	Receipt issued. Use receipt_number and qr_url in your printout.
201	Created — pending ZRA	Logged by Zansync. Retry or poll for status.
400	Bad Request	Invalid parameters. Check error field in response body.
401	Unauthorized	Invalid or missing X-Zansync-Key header.
403	Forbidden	Your plan does not include this endpoint.
500	ZRA Server Error	ZRA is temporarily unavailable. Zansync retries automatically. Retry after 30s.

Receipt Print Requirements

ZRA requires specific fields on every printed or digital receipt. All required values are returned in Zansync API responses.

Field	Zansync Response Key
ZRA Receipt Number	receipt_number	required on receipt
Z-Number	z_number	required on receipt
Business Name	business_name	required on receipt
TIN Number	tin_number	required on receipt
Tax Exclusive Amount	tax_exclusive	required on receipt
Tax Amount	tax_amount	required on receipt
Total Amount	total	required on receipt
Issue Date	issued_at	required on receipt
QR Code	qr_url	required on receipt

⚠️ A scannable QR code generated from qr_url is mandatory on every receipt. Customers and ZRA inspectors use it to verify authenticity.

Webhooks

Register a webhook endpoint to receive ZRA receipt data pushed to your server the moment a receipt is issued — no polling required. Contact [email protected] to register your webhook URL, or configure it in your admin dashboard at admin.zansync.com.

# Webhook POST payload sent to your endpoint
{
  "event": "receipt.issued",
  "property_id": "your_property_id",
  "reference": "ORD-1042",
  "receipt_number": "213590000076220812",
  "z_number": "Z025608121",
  "tax_amount": 7173.91,
  "total": 55000.00,
  "qr_url": "http://102.223.7.131:6060/vfms/checkout-receipt-form/guest/...",
  "issued_at": "2026-04-18T17:31:00+03:00"
}

✓ Zansync signs all webhook payloads with an X-Zansync-Signature header. Verify this on your server to ensure the payload is genuine.

Questions? [email protected] · zansync.com