API objects

Request and response shapes used by the invoice API. Required means Esnad rejects the request (HTTP 400) if the value is missing or invalid. Optional fields may still be needed for a clean Fatoora result — missing or wrong formats often become zatca_warnings on HTTP 200.

How to read this page

Each section is a reusable shape. Create endpoints compose these objects. Presence reflects what Esnad enforces today — not ZATCA’s ideal document. Compliance fields on responses are under Responses.

The Address object

Used for seller and buyer national addresses. When you send an address object, street, city, and country are required. Building, district, and postal code are optional for Esnad; Fatoora may still return BR-KSA-09 / BR-KSA-37 / BR-KSA-66 warnings if they are missing or wrong.

Attribute	Type	Presence	Description
street	string	Required	Street name.
building_number	string	Optional	ZATCA expects 4 digits for SA (BR-KSA-37). Omitted or short values are accepted by Esnad and passed to Fatoora.
district	string	Optional	District / CitySubdivisionName. Recommended for SA.
city	string	Required	City name.
postal_code	string	Optional	ZATCA expects 5 digits for SA (BR-KSA-66). Invalid formats pass through to Fatoora.
country	string	Required	ISO country code, typically "SA".

The Seller object

Attribute	Type	Presence	Description
name	string	Required	Seller legal name.
name_ar	string	Optional	Arabic name.
vat_number	string	Required	15-digit VAT starting and ending with 3. Must match the company profile when profile VAT is set (SELLER_VAT_MISMATCH).
cr_number	string	Optional	Commercial Registration for schemeID=CRN. Do not send VAT here. Falls back to company profile; one of the two must be present (SELLER_CRN_REQUIRED).
address	Address	Optional	Optional on the request when a Saudi address is already on the company profile (invoice fields override profile per field). Otherwise Esnad returns MISSING_SELLER_ADDRESS.

The Buyer object

Required on standard (B2B) invoices. VAT goes in PartyTaxScheme; optional cr_number is PartyIdentification CRN.

Attribute	Type	Presence	Description
name	string	Required	—
name_ar	string	Optional	—
vat_number	string	Required	15-digit VAT starting and ending with 3.
cr_number	string	Optional	Buyer CRN. VAT-shaped values may yield Fatoora BR-KSA-F-08 warnings.
address	Address	Required	Buyer national address.

The Line item object

Attribute	Type	Presence	Description
description	string	Required	Item description.
description_ar	string	Optional	—
quantity	number	Required	Must be greater than 0.
unit_price	number	Required	Unit price in SAR.
vat_category	"S" \| "Z" \| "E" \| "O"	Optional	Default S (15%). Z/E/O use 0%. Unknown letters → INVALID_VAT_CATEGORY.
vat_exemption_code	string	Optional	Recommended for Z/E/O (e.g. VATEX-SA-32). Missing/wrong codes are validated by Fatoora (e.g. BR-KSA-69), not API validation errors.

Create simplified invoice

Attribute	Type	Presence	Description
egs_unit_id	string	Required	Active EGS unit.
invoice_number	string	Required	—
invoice_date	string	Required	YYYY-MM-DD
invoice_time	string	Required	HH:mm or HH:mm:ss.
seller	Seller	Required	—
line_items	Line item[]	Required	At least one line (EMPTY_LINE_ITEMS).
currency	string	Optional	Defaults to SAR when omitted.

Create standard invoice

Body for POST /v1/invoices/standard. Extends simplified create with a required buyer for B2B clearance.

Attribute	Type	Presence	Description
egs_unit_id	string	Required	Active EGS unit.
invoice_number	string	Required	—
invoice_date	string	Required	YYYY-MM-DD
invoice_time	string	Required	HH:mm or HH:mm:ss.
seller	Seller	Required	—
buyer	Buyer	Required	Buyer party. Must include name, vat_number, and address (MISSING_BUYER_DATA / INVALID_BUYER_VAT).
line_items	Line item[]	Required	At least one line (EMPTY_LINE_ITEMS).
currency	string	Optional	Defaults to SAR when omitted.

Credit / debit note

Attribute	Type	Presence	Description
egs_unit_id	string	Required	Active EGS unit.
invoice_number	string	Required	—
invoice_date	string	Required	YYYY-MM-DD
invoice_time	string	Required	HH:mm or HH:mm:ss.
original_invoice_uuid	string	Required	UUID of the original invoice.
reason	string	Required	—
reason_ar	string	Optional	—
seller	Seller	Required	—
buyer	Buyer	Optional	Optional on the request shape; required when the original invoice was standard/B2B (BUYER_REQUIRED_FOR_B2B_NOTE).
line_items	Line item[]	Required	At least one line (EMPTY_LINE_ITEMS).
currency	string	Optional	Defaults to SAR when omitted.

Invoice response (create / GET)

Always includes compliance fields. See Responses.

Attribute	Type	Presence	Description
invoice_id	string	Required	Esnad invoice id.
uuid	string	Required	Invoice UUID (ZATCA).
status	string	Required	queued \| submitted \| reported \| cleared \| failed \| …
zatca_compliant	boolean	Required	false when Fatoora returned warnings.
zatca_warning_count	number	Required	—
zatca_warnings	array	Required	{ code, message, category? }[]
resubmit	boolean	Required	false when accepted with warnings — do not resend same number/uuid.
message	string	Optional	Present when warnings exist or when queued (202).

Warning object

{
  "code": "BR-KSA-37",
  "message": "The seller address building number must contain 4 digits.",
  "category": "KSA"
}

EGS & keys

Create EGS

Attribute	Type	Presence	Description
unit_name	string	Required	—
invoice_type	"standard" \| "simplified" \| "both"	Optional	Default simplified.
otp	string	Optional	—
phase	1 \| 2	Optional	Default 2.
environment	"sandbox" \| "production"	Optional	Must match API key mode if set.

Create API key

Attribute	Type	Presence	Description
label	string	Optional	Max 100 chars.
prefix	"zatca_live_" \| "zatca_test_"	Optional	Default zatca_test_.

Endpoint reference: Invoices