DTOs Reference
Request body schemas for the ZATCA API endpoints (API key–authenticated only). Dashboard-only endpoints are not documented here.
AddressDto
AddressDto
| Field | Type | Required | Description |
|---|---|---|---|
| street | string | Yes | — |
| city | string | Yes | — |
| postal_code | string | No | — |
| country | string | Yes | — |
SellerDto
SellerDto
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Seller legal name |
| name_ar | string | No | Arabic name |
| vat_number | string | Yes | VAT registration number |
| address | AddressDto | Yes | Seller address |
Nested: AddressDto
| Field | Type | Required | Description |
|---|---|---|---|
| street | string | Yes | — |
| city | string | Yes | — |
| postal_code | string | No | — |
| country | string | Yes | — |
LineItemDto
LineItemDto
| Field | Type | Required | Description |
|---|---|---|---|
| description | string | Yes | Item description |
| description_ar | string | No | — |
| quantity | number | Yes | Min 0.0001 |
| unit_price | number | Yes | In SAR |
| vat_category | "S" | "Z" | "E" | "O" | No | VAT category code |
BuyerAddressDto
BuyerAddressDto
| Field | Type | Required | Description |
|---|---|---|---|
| street | string | Yes | — |
| city | string | Yes | — |
| postal_code | string | No | — |
| country | string | Yes | — |
BuyerDto
BuyerDto
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | — |
| name_ar | string | No | — |
| vat_number | string | Yes | — |
| address | BuyerAddressDto | Yes | — |
Nested: BuyerAddressDto
| Field | Type | Required | Description |
|---|---|---|---|
| street | string | Yes | — |
| city | string | Yes | — |
| postal_code | string | No | — |
| country | string | Yes | — |
CreateSimplifiedInvoiceDto
CreateSimplifiedInvoiceDto
| Field | Type | Required | Description |
|---|---|---|---|
| egs_unit_id | string | Yes | Active EGS unit ID |
| invoice_number | string | Yes | — |
| invoice_date | string | Yes | YYYY-MM-DD |
| invoice_time | string | Yes | HH:mm:ss |
| seller | SellerDto | Yes | — |
| line_items | LineItemDto[] | Yes | — |
| currency | string | No | Default: SAR |
CreateStandardInvoiceDto
Extends CreateSimplifiedInvoiceDto with buyer.
CreateStandardInvoiceDto
| Field | Type | Required | Description |
|---|---|---|---|
| …(all CreateSimplifiedInvoiceDto fields) | — | Yes | — |
| buyer | BuyerDto | Yes | Required for B2B |
CreateCreditNoteDto / CreateDebitNoteDto
CreateCreditNoteDto (same for CreateDebitNoteDto)
| Field | Type | Required | Description |
|---|---|---|---|
| egs_unit_id | string | Yes | — |
| invoice_number | string | Yes | — |
| invoice_date | string | Yes | — |
| invoice_time | string | Yes | — |
| original_invoice_uuid | string | Yes | UUID of original invoice |
| reason | string | Yes | — |
| reason_ar | string | No | — |
| seller | SellerDto | Yes | — |
| buyer | BuyerDto | No | Required if original was B2B |
| line_items | LineItemDto[] | Yes | — |
| currency | string | No | — |
EGS & compliance
CreateEgsDto
| Field | Type | Required | Description |
|---|---|---|---|
| unit_name | string | Yes | — |
| invoice_type | "standard" | "simplified" | "both" | No | Default: simplified |
| otp | string | No | — |
| phase | 1 | 2 | No | Default: 2 |
RequestProductionDto
| Field | Type | Required | Description |
|---|---|---|---|
| otp | string | Yes | ZATCA OTP for production CSID |
ComplianceTestDto
| Field | Type | Required | Description |
|---|---|---|---|
| egs_unit_id | string | Yes | — |
API keys & webhooks
CreateApiKeyDto
| Field | Type | Required | Description |
|---|---|---|---|
| label | string | No | Max 100 chars |
| prefix | "zatca_live_" | "zatca_test_" | No | Default: zatca_test_ |
WebhookConfigDto
| Field | Type | Required | Description |
|---|---|---|---|
| webhook_url | string | null | No | HTTPS; max 500 chars |
| webhook_secret | string | null | No | Max 64 chars |