Fatoora API & ZATCA API Documentation | Simple Fatoora

Sign in Sign up

Simple Fatoora Developers

Simple Fatoora API V1

Use Simple Fatoora API V1 to connect invoicing, customer records, reports, and ZATCA Phase 2 workflows to your application.

Base URLhttps://api.simplefatoora.com/v1

Content typeJSON over HTTPS

Authentication

X-API-Key

Send your API key in the X-API-Key request header. Public account-access operations are marked separately.

X-API-Key: YOUR_API_KEY

Account & Access

POST/users/registration_intent

Create registration intent

Starts the email-verified account registration flow and returns a registration intent.

Public operationapplication/json

Request body

FieldTypeRequirement

registration_dataobjectRequired

registration_journey_idstringRequired

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "registration_intent": "registration-intent-token",
    "expires_in": 86400
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/users/registration_intent' \
  --header 'Accept-Language: en' \
  --header 'Content-Type: application/json' \
  --data '{
  "registration_data": {
    "email_id": "developer@example.com",
    "password": "example-password",
    "confirm_password": "example-password",
    "company_name": "Example Company",
    "terms_and_conditions": 1,
    "address": "Riyadh",
    "source": "api"
  },
  "registration_journey_id": "your-unique-registration-id"
}'

Request body

{
  "registration_data": {
    "email_id": "developer@example.com",
    "password": "example-password",
    "confirm_password": "example-password",
    "company_name": "Example Company",
    "terms_and_conditions": 1,
    "address": "Riyadh",
    "source": "api"
  },
  "registration_journey_id": "your-unique-registration-id"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "registration_intent": "registration-intent-token",
    "expires_in": 86400
  }
}

Account & Access

POST/users/email_send_otp

Send email OTP

Sends a one-time verification code to the supplied email address.

Public operationapplication/json

Request body

FieldTypeRequirement

email_idstring · emailRequired

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "message": "OTP sent successfully",
    "is_register": false
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/users/email_send_otp' \
  --header 'Accept-Language: en' \
  --header 'Content-Type: application/json' \
  --data '{
  "email_id": "developer@example.com"
}'

Request body

{
  "email_id": "developer@example.com"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "message": "OTP sent successfully",
    "is_register": false
  }
}

Account & Access

POST/users/email_verify_otp

Verify email OTP

Verifies the code sent to the email address. The verification is valid for the registration or password-reset flow.

Public operationapplication/json

Request body

FieldTypeRequirement

email_idstring · emailRequired

otpintegerRequired

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "message": "OTP verify successfully",
    "is_register": false
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/users/email_verify_otp' \
  --header 'Accept-Language: en' \
  --header 'Content-Type: application/json' \
  --data '{
  "email_id": "developer@example.com",
  "otp": 123456
}'

Request body

{
  "email_id": "developer@example.com",
  "otp": 123456
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "message": "OTP verify successfully",
    "is_register": false
  }
}

Account & Access

POST/users/register_from_intent

Complete registration

Creates the account after email verification and returns the account's live and sandbox API keys.

Public operationapplication/json

Request body

FieldTypeRequirement

registration_intentstringRequired

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "message": "Welcome to Simple Fatoora",
    "activation_method": "email_otp",
    "email_id": "developer@example.com",
    "first_name": "Developer",
    "last_name": "Account",
    "uuid": "session-uuid",
    "api_key": "live_api_key_example",
    "production_api_key": "live_api_key_example",
    "sandbox_api_key": "sandbox_api_key_example"
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/users/register_from_intent' \
  --header 'Accept-Language: en' \
  --header 'Content-Type: application/json' \
  --data '{
  "registration_intent": "registration-intent-from-first-step"
}'

Request body

{
  "registration_intent": "registration-intent-from-first-step"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "message": "Welcome to Simple Fatoora",
    "activation_method": "email_otp",
    "email_id": "developer@example.com",
    "first_name": "Developer",
    "last_name": "Account",
    "uuid": "session-uuid",
    "api_key": "live_api_key_example",
    "production_api_key": "live_api_key_example",
    "sandbox_api_key": "sandbox_api_key_example"
  }
}

Account & Access

POST/users/validate_user

Get API keys from credentials

Validates account credentials and returns the live and sandbox API keys.

Public operationapplication/json

Request body

FieldTypeRequirement

user_namestringRequired

user_passstring · passwordRequired

Responses

200Successful response

application/json

{
  "status": true,
  "api_key": "live_api_key_example",
  "production_api_key": "live_api_key_example",
  "sandbox_api_key": "sandbox_api_key_example",
  "response": "Validated successfully"
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/users/validate_user' \
  --header 'Accept-Language: en' \
  --header 'Content-Type: application/json' \
  --data '{
  "user_name": "developer@example.com",
  "user_pass": "example-password"
}'

Request body

{
  "user_name": "developer@example.com",
  "user_pass": "example-password"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "api_key": "live_api_key_example",
  "production_api_key": "live_api_key_example",
  "sandbox_api_key": "sandbox_api_key_example",
  "response": "Validated successfully"
}

Account & Access

POST/users/validate_user_api_key

Validate API key

Validates one account API key and returns the account's live and sandbox API keys.

Public operationapplication/json

Request body

FieldTypeRequirement

api_keystringRequired

Responses

200Successful response

application/json

{
  "status": true,
  "api_key": "live_api_key_example",
  "production_api_key": "live_api_key_example",
  "sandbox_api_key": "sandbox_api_key_example",
  "active_environment": "live",
  "response": "Validated successfully"
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/users/validate_user_api_key' \
  --header 'Accept-Language: en' \
  --header 'Content-Type: application/json' \
  --data '{
  "api_key": "your-api-key"
}'

Request body

{
  "api_key": "your-api-key"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "api_key": "live_api_key_example",
  "production_api_key": "live_api_key_example",
  "sandbox_api_key": "sandbox_api_key_example",
  "active_environment": "live",
  "response": "Validated successfully"
}

Account & Access

POST/users/update_password

Reset password

Sets a new password using the password-reset UUID returned after email verification.

Public operationapplication/json

Request body

FieldTypeRequirement

uuidstringRequired

passwordstring · passwordRequired

confirm_passwordstring · passwordRequired

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "message": "Password updated successfully",
    "user_id": 123
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/users/update_password' \
  --header 'Accept-Language: en' \
  --header 'Content-Type: application/json' \
  --data '{
  "uuid": "password-reset-uuid",
  "password": "new-example-password",
  "confirm_password": "new-example-password"
}'

Request body

{
  "uuid": "password-reset-uuid",
  "password": "new-example-password",
  "confirm_password": "new-example-password"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "message": "Password updated successfully",
    "user_id": 123
  }
}

Business Profile

GET/users/get_profile

Get business profile

Returns business details and invoice display settings for the authenticated account.

API key required

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "user_id": 123,
    "company_name": "Example Company",
    "email_id": "developer@example.com",
    "address": "Riyadh",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "tax_setup_status": "vat_registered",
    "tax_registration_status": "vat_registered",
    "is_vat_registered": true,
    "environment": "live",
    "is_sandbox": false,
    "production_api_key": "live_api_key_example",
    "sandbox_api_key": "sandbox_api_key_example",
    "send_mail": 1,
    "client_send_mail": 1
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request GET \
  --url 'https://api.simplefatoora.com/v1/users/get_profile' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY'

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "user_id": 123,
    "company_name": "Example Company",
    "email_id": "developer@example.com",
    "address": "Riyadh",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "tax_setup_status": "vat_registered",
    "tax_registration_status": "vat_registered",
    "is_vat_registered": true,
    "environment": "live",
    "is_sandbox": false,
    "production_api_key": "live_api_key_example",
    "sandbox_api_key": "sandbox_api_key_example",
    "send_mail": 1,
    "client_send_mail": 1
  }
}

Business Profile

POST/users/update_profile

Update business profile

Updates business details and supported invoice display settings.

API key requiredapplication/json

Request body

FieldTypeRequirement

first_namestringOptional

last_namestringOptional

company_namestringOptional

addressstringOptional

country_codestringOptional

mobile_numberstringOptional

tax_setup_statusstringOptional

company_registration_numberstringOptional

company_vat_numberstringOptional

notesstringOptional

footer_textstringOptional

send_mailintegerOptional

client_send_mailintegerOptional

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "message": "Profile updated successfully",
    "user_id": 123
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/users/update_profile' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "company_name": "Example Company",
  "address": "Riyadh",
  "company_registration_number": "1010000000",
  "company_vat_number": "300000000000003",
  "notes": "Thank you for your business",
  "footer_text": "Example Company",
  "send_mail": 1,
  "client_send_mail": 1
}'

Request body

{
  "company_name": "Example Company",
  "address": "Riyadh",
  "company_registration_number": "1010000000",
  "company_vat_number": "300000000000003",
  "notes": "Thank you for your business",
  "footer_text": "Example Company",
  "send_mail": 1,
  "client_send_mail": 1
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "message": "Profile updated successfully",
    "user_id": 123
  }
}

Business Profile

POST/users/upload_profile_image

Upload company logo

Uploads a JPEG, PNG, WebP, or GIF logo and applies it to the business profile.

API key requiredmultipart/form-data

Request body

FieldTypeRequirement

filestring · binaryRequired

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "url": "https://example.com/company-logo.png"
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/users/upload_profile_image' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@company-logo.png'

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "url": "https://example.com/company-logo.png"
  }
}

Clients

GET/client/kyc_category_list

List client categories

Returns available client KYC categories.

API key required

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "categories": [
      {
        "id": 1,
        "title": "Retail",
        "ar_title": "التجزئة",
        "position": 1,
        "status": 1
      }
    ]
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request GET \
  --url 'https://api.simplefatoora.com/v1/client/kyc_category_list' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY'

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "categories": [
      {
        "id": 1,
        "title": "Retail",
        "ar_title": "التجزئة",
        "position": 1,
        "status": 1
      }
    ]
  }
}

Clients

POST/client/create

Create client

Creates a client record for future invoices and documents.

API key requiredapplication/json

Request body

FieldTypeRequirement

first_namestringRequired

email_idstring · emailOptional

mobile_numberstringRequired

country_codestringRequired

addressstringOptional

company_registration_numberstringOptional

company_vat_numberstringOptional

category_idstringOptional

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "message": "User created successfully",
    "user_id": 123
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/client/create' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "first_name": "Example Customer",
  "email_id": "customer@example.com",
  "mobile_number": "500000000",
  "country_code": "+966",
  "address": "Riyadh",
  "company_registration_number": "1010000000",
  "company_vat_number": "300000000000003"
}'

Request body

{
  "first_name": "Example Customer",
  "email_id": "customer@example.com",
  "mobile_number": "500000000",
  "country_code": "+966",
  "address": "Riyadh",
  "company_registration_number": "1010000000",
  "company_vat_number": "300000000000003"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "message": "User created successfully",
    "user_id": 123
  }
}

Clients

POST/client/update

Update client

Updates an existing client record. Include the client id with the fields to change.

API key requiredapplication/json

Request body

FieldTypeRequirement

idintegerRequired

first_namestringOptional

email_idstring · emailOptional

mobile_numberstringOptional

country_codestringOptional

addressstringOptional

company_registration_numberstringOptional

company_vat_numberstringOptional

category_idstringOptional

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "message": "User updated successfully",
    "user_id": 123
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/client/update' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": 123,
  "first_name": "Updated Customer",
  "address": "Jeddah"
}'

Request body

{
  "id": 123,
  "first_name": "Updated Customer",
  "address": "Jeddah"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "message": "User updated successfully",
    "user_id": 123
  }
}

Clients

GET/client/get_byid/{client_id}

Get client

Returns one client owned by the authenticated account.

API key required

Parameters

FieldLocationTypeRequirement

client_idpathintegerRequired

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "id": 123,
    "user_id": 123,
    "first_name": "Example Customer",
    "email_id": "customer@example.com",
    "mobile_number": "500000000",
    "country_code": "+966",
    "address": "Riyadh",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "status": 1
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request GET \
  --url 'https://api.simplefatoora.com/v1/client/get_byid/123' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY'

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "id": 123,
    "user_id": 123,
    "first_name": "Example Customer",
    "email_id": "customer@example.com",
    "mobile_number": "500000000",
    "country_code": "+966",
    "address": "Riyadh",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "status": 1
  }
}

Clients

POST/client/get_all

List clients

Returns clients owned by the authenticated account with optional pagination and search.

API key requiredapplication/json

Request body

FieldTypeRequirement

pageintegerOptional

per_pageintegerOptional

limitintegerOptional

search_keystringOptional

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "users": [
      {
        "id": 123,
        "full_name": "Example Customer",
        "email_id": "customer@example.com",
        "mobile_number": "500000000",
        "country_code": "+966",
        "address": "Riyadh",
        "client_type": 2
      }
    ],
    "pagination_meta": {
      "current_page": 1,
      "pages": 1,
      "per_page": 20,
      "total": 1
    }
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/client/get_all' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "page": 1,
  "per_page": 20,
  "search_key": ""
}'

Request body

{
  "page": 1,
  "per_page": 20,
  "search_key": ""
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "users": [
      {
        "id": 123,
        "full_name": "Example Customer",
        "email_id": "customer@example.com",
        "mobile_number": "500000000",
        "country_code": "+966",
        "address": "Riyadh",
        "client_type": 2
      }
    ],
    "pagination_meta": {
      "current_page": 1,
      "pages": 1,
      "per_page": 20,
      "total": 1
    }
  }
}

Clients

DELETE/client/delete/{client_id}

Delete client

Deletes one client owned by the authenticated account.

API key required

Parameters

FieldLocationTypeRequirement

client_idpathintegerRequired

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "message": "User deleted successfully"
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request DELETE \
  --url 'https://api.simplefatoora.com/v1/client/delete/123' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY'

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "message": "User deleted successfully"
  }
}

Products

GET/invoice/products/search

Search products

Searches previously used products by name or description.

API key required

Parameters

FieldLocationTypeRequirement

search_keyquerystringOptional

limitqueryintegerOptional

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "products": [
      {
        "id": 123,
        "product_id": "P0001",
        "description": "Example item",
        "unit_price": 100,
        "vat_percent": 15,
        "last_used_on": "2026-08-30T20:41:45"
      }
    ]
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request GET \
  --url 'https://api.simplefatoora.com/v1/invoice/products/search?search_key=value&limit=value' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY'

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "products": [
      {
        "id": 123,
        "product_id": "P0001",
        "description": "Example item",
        "unit_price": 100,
        "vat_percent": 15,
        "last_used_on": "2026-08-30T20:41:45"
      }
    ]
  }
}

Products

POST/invoice/products/list

List products

Returns products previously used by the authenticated account.

API key requiredapplication/json

Request body

FieldTypeRequirement

pageintegerOptional

per_pageintegerOptional

limitintegerOptional

search_keystringOptional

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "products": [
      {
        "id": 123,
        "product_id": "P0001",
        "description": "Example item",
        "unit_price": 100,
        "vat_percent": 15,
        "last_used_on": "2026-08-30T20:41:45"
      }
    ]
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/invoice/products/list' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "limit": 20
}'

Request body

{
  "limit": 20
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "products": [
      {
        "id": 123,
        "product_id": "P0001",
        "description": "Example item",
        "unit_price": 100,
        "vat_percent": 15,
        "last_used_on": "2026-08-30T20:41:45"
      }
    ]
  }
}

Invoices & Documents

POST/invoice/create

Create invoice or document

Creates a simplified invoice, standard invoice, purchase invoice, credit note, or debit note. ZATCA processing follows the account and API-key environment.

API key requiredapplication/json

Request body

FieldTypeRequirement

invoice_typeintegerRequired

client_typeintegerOptional

taxes_includedintegerOptional

client_idintegerOptional

client_namestringOptional

client_addressstringOptional

client_email_idstring · emailOptional

client_vat_numberstringOptional

date_timestringOptional

reference_numberstringOptional

created_typestringOptional

source_uidstringOptional

invoice_detailarray<object>Required

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "message": "Invoice created successfully",
    "id": 123,
    "invoice_number": "U123-1001",
    "invoice": "https://example.com/invoices/U123-1001.pdf",
    "pdf_ready": true,
    "pdf_download_url": "https://api.example.com/v1/invoice/pdf/123",
    "xml_available": true,
    "xml_archive_state": "reported",
    "xml_download_url": "https://api.example.com/v1/invoice/xml/123",
    "qrcode": "https://example.com/invoices/U123-1001-qr.png",
    "seller_name": "Example Company",
    "seller_vat_number": "300000000000003",
    "seller_address": "Riyadh",
    "vat": 15,
    "total": 115,
    "date_time": "2026-08-30 23:41:18",
    "environment": "live"
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/invoice/create' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "invoice_type": 0,
  "client_type": 2,
  "taxes_included": 0,
  "client_name": "Example Customer",
  "client_address": "Riyadh",
  "client_email_id": "customer@example.com",
  "reference_number": "POS-1001",
  "invoice_detail": [
    {
      "description": "Example item",
      "unit_price": 100,
      "quantity": 1,
      "vat_percent_product": 15,
      "discount_percent": 0
    }
  ],
  "created_type": "api"
}'

Request body

{
  "invoice_type": 0,
  "client_type": 2,
  "taxes_included": 0,
  "client_name": "Example Customer",
  "client_address": "Riyadh",
  "client_email_id": "customer@example.com",
  "reference_number": "POS-1001",
  "invoice_detail": [
    {
      "description": "Example item",
      "unit_price": 100,
      "quantity": 1,
      "vat_percent_product": 15,
      "discount_percent": 0
    }
  ],
  "created_type": "api"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "message": "Invoice created successfully",
    "id": 123,
    "invoice_number": "U123-1001",
    "invoice": "https://example.com/invoices/U123-1001.pdf",
    "pdf_ready": true,
    "pdf_download_url": "https://api.example.com/v1/invoice/pdf/123",
    "xml_available": true,
    "xml_archive_state": "reported",
    "xml_download_url": "https://api.example.com/v1/invoice/xml/123",
    "qrcode": "https://example.com/invoices/U123-1001-qr.png",
    "seller_name": "Example Company",
    "seller_vat_number": "300000000000003",
    "seller_address": "Riyadh",
    "vat": 15,
    "total": 115,
    "date_time": "2026-08-30 23:41:18",
    "environment": "live"
  }
}

Invoices & Documents

POST/invoice/get_all

List invoices and documents

Returns documents for the API-key environment with pagination and filters.

API key requiredapplication/json

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "invoices": [
      {
        "id": 123,
        "invoice_number": "U123-1001",
        "invoice_type": 0,
        "date_time": "2026-08-30 23:41:18",
        "reference_number": "POS-1001",
        "total": 115,
        "invoice": "https://example.com/invoices/U123-1001.pdf",
        "pdf_ready": true,
        "pdf_download_url": "https://api.example.com/v1/invoice/pdf/123",
        "xml_available": true,
        "xml_archive_state": "reported",
        "xml_download_url": "https://api.example.com/v1/invoice/xml/123",
        "environment": "live",
        "is_test": false
      }
    ],
    "pagination_meta": {
      "current_page": 1,
      "pages": 1,
      "per_page": 20,
      "total": 1
    }
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/invoice/get_all' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "page": 1,
  "per_page": 20,
  "include_all_invoice_types": 1
}'

Request body

{
  "page": 1,
  "per_page": 20,
  "include_all_invoice_types": 1
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "invoices": [
      {
        "id": 123,
        "invoice_number": "U123-1001",
        "invoice_type": 0,
        "date_time": "2026-08-30 23:41:18",
        "reference_number": "POS-1001",
        "total": 115,
        "invoice": "https://example.com/invoices/U123-1001.pdf",
        "pdf_ready": true,
        "pdf_download_url": "https://api.example.com/v1/invoice/pdf/123",
        "xml_available": true,
        "xml_archive_state": "reported",
        "xml_download_url": "https://api.example.com/v1/invoice/xml/123",
        "environment": "live",
        "is_test": false
      }
    ],
    "pagination_meta": {
      "current_page": 1,
      "pages": 1,
      "per_page": 20,
      "total": 1
    }
  }
}

Invoices & Documents

GET/invoice/get_byid/{document_id}

Get invoice or document

Returns one document owned by the authenticated account.

API key required

Parameters

FieldLocationTypeRequirement

document_idpathintegerRequired

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "id": 123,
    "invoice_number": "U123-1001",
    "invoice_type": 0,
    "date_time": "2026-08-30 23:41:18",
    "reference_number": "POS-1001",
    "seller_name": "Example Company",
    "seller_vat_number": "300000000000003",
    "buyer_name": "Example Customer",
    "buyer_email_id": "customer@example.com",
    "sub_total": 100,
    "vat": 15,
    "total": 115,
    "invoice": "https://example.com/invoices/U123-1001.pdf",
    "qrcode": "https://example.com/invoices/U123-1001-qr.png",
    "pdf_ready": true,
    "pdf_download_url": "https://api.example.com/v1/invoice/pdf/123",
    "xml_available": true,
    "xml_archive_state": "reported",
    "xml_download_url": "https://api.example.com/v1/invoice/xml/123",
    "environment": "live",
    "invoice_details": [
      {
        "description": "Example item",
        "unit_price": 100,
        "quantity": 1,
        "vat_percent": 15,
        "vat": 15,
        "total": 115
      }
    ]
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request GET \
  --url 'https://api.simplefatoora.com/v1/invoice/get_byid/123' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY'

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "id": 123,
    "invoice_number": "U123-1001",
    "invoice_type": 0,
    "date_time": "2026-08-30 23:41:18",
    "reference_number": "POS-1001",
    "seller_name": "Example Company",
    "seller_vat_number": "300000000000003",
    "buyer_name": "Example Customer",
    "buyer_email_id": "customer@example.com",
    "sub_total": 100,
    "vat": 15,
    "total": 115,
    "invoice": "https://example.com/invoices/U123-1001.pdf",
    "qrcode": "https://example.com/invoices/U123-1001-qr.png",
    "pdf_ready": true,
    "pdf_download_url": "https://api.example.com/v1/invoice/pdf/123",
    "xml_available": true,
    "xml_archive_state": "reported",
    "xml_download_url": "https://api.example.com/v1/invoice/xml/123",
    "environment": "live",
    "invoice_details": [
      {
        "description": "Example item",
        "unit_price": 100,
        "quantity": 1,
        "vat_percent": 15,
        "vat": 15,
        "total": 115
      }
    ]
  }
}

Invoices & Documents

GET/invoice/pdf/{document_id}

Download invoice PDF

Downloads the PDF for one issued document owned by the API-key account. Use download=1 for attachment disposition.

API key required

Parameters

FieldLocationTypeRequirement

document_idpathintegerRequired

downloadqueryintegerOptional

Request body

This operation has no request body.

Responses

200PDF binary response

application/pdf

%PDF binary document

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request GET \
  --url 'https://api.simplefatoora.com/v1/invoice/pdf/123?download=value' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY'

Response exampleapplication/pdf

Status 200

%PDF binary document

Invoices & Documents

GET/invoice/xml/{document_id}

Download XML

Downloads the XML for an eligible Phase 2 tax document owned by the API-key account.

API key required

Parameters

FieldLocationTypeRequirement

document_idpathintegerRequired

Request body

This operation has no request body.

Responses

200Final XML binary response

application/xml

<?xml version="1.0"?><Invoice>...</Invoice>

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request GET \
  --url 'https://api.simplefatoora.com/v1/invoice/xml/123' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY'

Response exampleapplication/xml

Status 200

<?xml version="1.0"?><Invoice>...</Invoice>

Invoices & Documents

POST/invoice/archive/export

Export invoice archive

Downloads a ZIP containing the selected PDF or eligible final XML documents plus manifest.csv. The API key selects live or sandbox data. A maximum of 250 available files and 50 MB is allowed per request; use a smaller date range when needed.

API key requiredapplication/json

Request body

FieldTypeRequirement

formatstringRequired

start_datestring · dateOptional

end_datestring · dateOptional

invoice_typesarray<integer>Optional

Responses

200ZIP archive response

application/zip

Binary ZIP archive with documents and manifest.csv

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/invoice/archive/export' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "format": "xml",
  "start_date": "2026-01-01",
  "end_date": "2026-01-31",
  "invoice_types": [
    0,
    1,
    3,
    4
  ]
}'

Request body

{
  "format": "xml",
  "start_date": "2026-01-01",
  "end_date": "2026-01-31",
  "invoice_types": [
    0,
    1,
    3,
    4
  ]
}

Response exampleapplication/zip

Status 200

Binary ZIP archive with documents and manifest.csv

Quotations

POST/drafts/create

Create quotation

Creates a quotation. The quotation document is supplied as a JSON-encoded string in json_data.

API key requiredapplication/json

Request body

FieldTypeRequirement

json_datastringRequired

environmentstringOptional

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "message": "Draft created successfully",
    "id": 123
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/drafts/create' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "json_data": "{\"document_kind\":\"quotation\",\"client_type\":2,\"client_name\":\"Example Customer\",\"client_address\":\"Riyadh\",\"client_email_id\":\"customer@example.com\",\"invoice_detail\":[{\"description\":\"Example item\",\"unit_price\":100,\"quantity\":1,\"vat_percent\":15,\"discount_percent\":0}]}",
  "environment": "live"
}'

Request body

{
  "json_data": "{\"document_kind\":\"quotation\",\"client_type\":2,\"client_name\":\"Example Customer\",\"client_address\":\"Riyadh\",\"client_email_id\":\"customer@example.com\",\"invoice_detail\":[{\"description\":\"Example item\",\"unit_price\":100,\"quantity\":1,\"vat_percent\":15,\"discount_percent\":0}]}",
  "environment": "live"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "message": "Draft created successfully",
    "id": 123
  }
}

Quotations

POST/drafts/update

Update quotation

Updates an existing quotation and its JSON-encoded document data.

API key requiredapplication/json

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "message": "Draft updated successfully"
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/drafts/update' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": 123,
  "json_data": "{\"document_kind\":\"quotation\",\"client_type\":2,\"client_name\":\"Example Customer\",\"client_address\":\"Riyadh\",\"client_email_id\":\"customer@example.com\",\"invoice_detail\":[{\"description\":\"Updated example item\",\"unit_price\":100,\"quantity\":1,\"vat_percent\":15,\"discount_percent\":0}]}",
  "environment": "live"
}'

Request body

{
  "id": 123,
  "json_data": "{\"document_kind\":\"quotation\",\"client_type\":2,\"client_name\":\"Example Customer\",\"client_address\":\"Riyadh\",\"client_email_id\":\"customer@example.com\",\"invoice_detail\":[{\"description\":\"Updated example item\",\"unit_price\":100,\"quantity\":1,\"vat_percent\":15,\"discount_percent\":0}]}",
  "environment": "live"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "message": "Draft updated successfully"
  }
}

Quotations

POST/drafts/get_all

List quotations

Returns quotations for the selected API-key environment.

API key requiredapplication/json

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "drafts": [
      {
        "id": 123,
        "environment": "sandbox",
        "created_on": "2026-08-30 20:41:45",
        "json_data": "{\"document_kind\":\"quotation\",\"client_name\":\"Example Customer\",\"invoice_detail\":[{\"description\":\"Example item\",\"unit_price\":100,\"quantity\":1}]}"
      }
    ],
    "pagination_meta": {
      "current_page": 1,
      "pages": 1,
      "per_page": 20,
      "total": 1
    }
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/drafts/get_all' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "page": 1,
  "per_page": 20,
  "search_key": "",
  "document_kind": "quotation"
}'

Request body

{
  "page": 1,
  "per_page": 20,
  "search_key": "",
  "document_kind": "quotation"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "drafts": [
      {
        "id": 123,
        "environment": "sandbox",
        "created_on": "2026-08-30 20:41:45",
        "json_data": "{\"document_kind\":\"quotation\",\"client_name\":\"Example Customer\",\"invoice_detail\":[{\"description\":\"Example item\",\"unit_price\":100,\"quantity\":1}]}"
      }
    ],
    "pagination_meta": {
      "current_page": 1,
      "pages": 1,
      "per_page": 20,
      "total": 1
    }
  }
}

Quotations

GET/drafts/get_byid/{quotation_id}

Get quotation

Returns one quotation owned by the authenticated account.

API key required

Parameters

FieldLocationTypeRequirement

quotation_idpathintegerRequired

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "id": 123,
    "environment": "sandbox",
    "status": 1,
    "created_on": "2026-08-30 20:41:45",
    "json_data": "{\"document_kind\":\"quotation\",\"client_name\":\"Example Customer\",\"invoice_detail\":[{\"description\":\"Example item\",\"unit_price\":100,\"quantity\":1}]}"
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request GET \
  --url 'https://api.simplefatoora.com/v1/drafts/get_byid/123' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY'

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "id": 123,
    "environment": "sandbox",
    "status": 1,
    "created_on": "2026-08-30 20:41:45",
    "json_data": "{\"document_kind\":\"quotation\",\"client_name\":\"Example Customer\",\"invoice_detail\":[{\"description\":\"Example item\",\"unit_price\":100,\"quantity\":1}]}"
  }
}

Quotations

GET/drafts/quotation_pdf/{quotation_id}

Download quotation PDF

Returns the quotation PDF. Set download to 1 to request a file attachment.

API key required

Parameters

FieldLocationTypeRequirement

quotation_idpathintegerRequired

downloadqueryintegerOptional

Request body

This operation has no request body.

Responses

200Quotation PDF

application/pdf

%PDF-1.7 (binary PDF content)

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request GET \
  --url 'https://api.simplefatoora.com/v1/drafts/quotation_pdf/123?download=value' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY'

Response exampleapplication/pdf

Status 200

%PDF-1.7 (binary PDF content)

Quotations

DELETE/drafts/delete/{quotation_id}

Delete quotation

Deletes one quotation owned by the authenticated account.

API key required

Parameters

FieldLocationTypeRequirement

quotation_idpathintegerRequired

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "message": "Draft deleted successfully"
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request DELETE \
  --url 'https://api.simplefatoora.com/v1/drafts/delete/123' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY'

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "message": "Draft deleted successfully"
  }
}

Reports

POST/invoice/get_dashboard

Get dashboard summary

Returns dashboard totals and recent activity for the API-key environment.

API key requiredapplication/json

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "membership_count": {
      "purchase_count": 1,
      "invoice_count": "50000",
      "used_count": 12,
      "invoice_left": "49988"
    },
    "invoice_datat": {
      "total_invoice_count": 12,
      "last_month_invoice_count": 4,
      "total_sale": 1150,
      "last_month_sale": 460,
      "vat_payable": 150,
      "vat_receivable": 0,
      "environment": "live"
    },
    "zatca_hold": {
      "is_holding_now": false
    }
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/invoice/get_dashboard' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{}'

Request body

{}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "membership_count": {
      "purchase_count": 1,
      "invoice_count": "50000",
      "used_count": 12,
      "invoice_left": "49988"
    },
    "invoice_datat": {
      "total_invoice_count": 12,
      "last_month_invoice_count": 4,
      "total_sale": 1150,
      "last_month_sale": 460,
      "vat_payable": 150,
      "vat_receivable": 0,
      "environment": "live"
    },
    "zatca_hold": {
      "is_holding_now": false
    }
  }
}

Reports

POST/invoice/get_report

Get sales report

Returns sales-report data for a date range and document type.

API key requiredapplication/json

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "revenue_dashboard": [
      {
        "date": "2026-08-30",
        "invoice_count": 4,
        "total": 460,
        "vat": 60
      }
    ]
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/invoice/get_report' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "start_date": "2026-01-01",
  "end_date": "2026-01-31",
  "type": "invoice"
}'

Request body

{
  "start_date": "2026-01-01",
  "end_date": "2026-01-31",
  "type": "invoice"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "revenue_dashboard": [
      {
        "date": "2026-08-30",
        "invoice_count": 4,
        "total": 460,
        "vat": 60
      }
    ]
  }
}

Reports

POST/invoice/get_vat_return_report

Get VAT return report

Returns VAT-return figures for a date range.

API key requiredapplication/json

Request body

FieldTypeRequirement

start_datestring · dateRequired

end_datestring · dateRequired

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "sale_sub_total": 1000,
    "sale_vat": 150,
    "sale_discount": 0,
    "purchase_sub_total": 200,
    "purchase_vat": 30,
    "purchase_discount": 0,
    "credit_total": 0,
    "debit_total": 0,
    "vat_out": 150,
    "vat_in": 30,
    "vat_payable": 120
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/invoice/get_vat_return_report' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "start_date": "2026-01-01",
  "end_date": "2026-03-31"
}'

Request body

{
  "start_date": "2026-01-01",
  "end_date": "2026-03-31"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "sale_sub_total": 1000,
    "sale_vat": 150,
    "sale_discount": 0,
    "purchase_sub_total": 200,
    "purchase_vat": 30,
    "purchase_discount": 0,
    "credit_total": 0,
    "debit_total": 0,
    "vat_out": 150,
    "vat_in": 30,
    "vat_payable": 120
  }
}

ZATCA Phase 2

GET/zatca-phase2/status

Get Phase 2 status

Returns the current ZATCA Phase 2 onboarding state for the API-key environment.

API key required

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "status": "draft",
    "status_label": "Draft",
    "next_step": "review_info",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request GET \
  --url 'https://api.simplefatoora.com/v1/zatca-phase2/status' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY'

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "status": "draft",
    "status_label": "Draft",
    "next_step": "review_info",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}

ZATCA Phase 2

POST/zatca-phase2/save-draft

Save Phase 2 draft

Saves the establishment and device information used for Phase 2 onboarding.

API key requiredapplication/json

Request body

FieldTypeRequirement

source_channelstringOptional

company_namestringRequired

organization_namestringRequired

organization_identifierstringRequired

organization_unit_namestringRequired

company_registration_numberstringRequired

company_vat_numberstringRequired

industry_business_categorystringRequired

street_namestringRequired

building_numberstringRequired

districtstringRequired

citystringRequired

postal_codestringRequired

country_namestringRequired

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "status": "draft",
    "status_label": "Draft",
    "next_step": "review_info",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/zatca-phase2/save-draft' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "source_channel": "api",
  "company_name": "Example Company",
  "organization_name": "Example Company",
  "organization_identifier": "300000000000003",
  "organization_unit_name": "Riyadh Branch",
  "company_registration_number": "1010000000",
  "company_vat_number": "300000000000003",
  "industry_business_category": "Retail",
  "street_name": "Example Street",
  "building_number": "1234",
  "district": "Example District",
  "city": "Riyadh",
  "postal_code": "12345",
  "country_name": "SA"
}'

Request body

{
  "source_channel": "api",
  "company_name": "Example Company",
  "organization_name": "Example Company",
  "organization_identifier": "300000000000003",
  "organization_unit_name": "Riyadh Branch",
  "company_registration_number": "1010000000",
  "company_vat_number": "300000000000003",
  "industry_business_category": "Retail",
  "street_name": "Example Street",
  "building_number": "1234",
  "district": "Example District",
  "city": "Riyadh",
  "postal_code": "12345",
  "country_name": "SA"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "status": "draft",
    "status_label": "Draft",
    "next_step": "review_info",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}

ZATCA Phase 2

POST/zatca-phase2/generate-csr

Generate CSR

Generates the certificate signing request for the supplied Phase 2 business data.

API key requiredapplication/json

Request body

FieldTypeRequirement

source_channelstringOptional

company_namestringRequired

organization_namestringRequired

organization_identifierstringRequired

organization_unit_namestringRequired

company_registration_numberstringRequired

company_vat_numberstringRequired

industry_business_categorystringRequired

street_namestringRequired

building_numberstringRequired

districtstringRequired

citystringRequired

postal_codestringRequired

country_namestringRequired

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "status": "awaiting_otp",
    "status_label": "Awaiting OTP",
    "next_step": "enter_otp",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123,
    "csr_generated_on": "2026-08-30T20:42:00Z",
    "csr_expires_on": "2026-08-31T20:42:00Z"
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/zatca-phase2/generate-csr' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "source_channel": "api",
  "company_name": "Example Company",
  "organization_name": "Example Company",
  "organization_identifier": "300000000000003",
  "organization_unit_name": "Riyadh Branch",
  "company_registration_number": "1010000000",
  "company_vat_number": "300000000000003",
  "industry_business_category": "Retail",
  "street_name": "Example Street",
  "building_number": "1234",
  "district": "Example District",
  "city": "Riyadh",
  "postal_code": "12345",
  "country_name": "SA"
}'

Request body

{
  "source_channel": "api",
  "company_name": "Example Company",
  "organization_name": "Example Company",
  "organization_identifier": "300000000000003",
  "organization_unit_name": "Riyadh Branch",
  "company_registration_number": "1010000000",
  "company_vat_number": "300000000000003",
  "industry_business_category": "Retail",
  "street_name": "Example Street",
  "building_number": "1234",
  "district": "Example District",
  "city": "Riyadh",
  "postal_code": "12345",
  "country_name": "SA"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "status": "awaiting_otp",
    "status_label": "Awaiting OTP",
    "next_step": "enter_otp",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123,
    "csr_generated_on": "2026-08-30T20:42:00Z",
    "csr_expires_on": "2026-08-31T20:42:00Z"
  }
}

ZATCA Phase 2

POST/zatca-phase2/submit-otp

Submit ZATCA OTP

Submits the OTP generated in the ZATCA portal to continue onboarding.

API key requiredapplication/json

Request body

FieldTypeRequirement

source_channelstringOptional

otpstringRequired

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "status": "production_issued",
    "status_label": "Integrated",
    "next_step": "completed",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": true,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": true,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123,
    "activated_on": "2026-08-30T20:48:00Z",
    "production_issued_on": "2026-08-30T20:48:00Z"
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/zatca-phase2/submit-otp' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "source_channel": "api",
  "otp": "123456"
}'

Request body

{
  "source_channel": "api",
  "otp": "123456"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "status": "production_issued",
    "status_label": "Integrated",
    "next_step": "completed",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": true,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": true,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123,
    "activated_on": "2026-08-30T20:48:00Z",
    "production_issued_on": "2026-08-30T20:48:00Z"
  }
}

ZATCA Phase 2

POST/zatca-phase2/retry-compliance

Retry compliance checks

Retries the Phase 2 compliance-document checks after a recoverable onboarding result.

API key requiredapplication/json

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "status": "production_issued",
    "status_label": "Integrated",
    "next_step": "completed",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": true,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": true,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/zatca-phase2/retry-compliance' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{}'

Request body

{}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "status": "production_issued",
    "status_label": "Integrated",
    "next_step": "completed",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": true,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": true,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}

ZATCA Phase 2

POST/zatca-phase2/refresh-status

Refresh Phase 2 status

Refreshes the Phase 2 state from the current onboarding records.

API key requiredapplication/json

Request body

This operation has no request body.

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "status": "awaiting_otp",
    "status_label": "Awaiting OTP",
    "next_step": "enter_otp",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/zatca-phase2/refresh-status' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{}'

Request body

{}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "status": "awaiting_otp",
    "status_label": "Awaiting OTP",
    "next_step": "enter_otp",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": false,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}

ZATCA Phase 2

POST/zatca-phase2/renew

Renew Phase 2 integration

Starts a controlled renewal of the account's Phase 2 integration.

API key requiredapplication/json

Request body

FieldTypeRequirement

source_channelstringOptional

Responses

200Successful response

application/json

{
  "status": true,
  "response": {
    "status": "awaiting_otp",
    "status_label": "Awaiting OTP",
    "next_step": "enter_otp",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": true,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}

400Invalid request data

application/json

{
  "status": false,
  "response": [
    "Invalid request data."
  ]
}

403API key is missing or invalid

application/json

{
  "status": false,
  "response": "Invalid API key"
}

Request examplecURL

api.simplefatoora.com

curl --request POST \
  --url 'https://api.simplefatoora.com/v1/zatca-phase2/renew' \
  --header 'Accept-Language: en' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "source_channel": "api"
}'

Request body

{
  "source_channel": "api"
}

Response exampleapplication/json

Status 200

{
  "status": true,
  "response": {
    "status": "awaiting_otp",
    "status_label": "Awaiting OTP",
    "next_step": "enter_otp",
    "environment": "sandbox",
    "is_sandbox": true,
    "is_integrated": false,
    "is_renewal_flow": true,
    "can_manage": true,
    "can_refresh": true,
    "can_renew": false,
    "can_retry_compliance_checks": false,
    "company_name": "Example Company",
    "company_registration_number": "1010000000",
    "company_vat_number": "300000000000003",
    "source": "api",
    "user_id": 123
  }
}