TABLE OF CONTENTS

• Invoice Flow
• Endpoint 1: Generate E-Invoice
  • URL: {{base_url}}/api/v2/einvoices/zatca/generate
  • HTTP Method: POST
  • Description:
  • Payload:
  • Response:
  • Sample response:
• Endpoint 2: Check E-Invoice Status
  • URL: {{base_url}}/api/v2/einvoices/zatca/ask
  • HTTP Method: GET
  • Description:
  • Query Parameter:
  • Response:
  • Sample Request
  • Webhook Data

Invoice Flow

This document outlines the API endpoints and their functionalities related to the generation and status checking of e-invoices compliant with ZATCA standards. The provided endpoints facilitate the submission of invoice data, tracking of processing status, and retrieval of generated invoices.

These endpoints offer a seamless workflow for clients to efficiently manage their invoicing processes, ensuring compliance and transparency throughout the invoicing lifecycle.

Endpoint 1: Generate E-Invoice

URL: {{base_url}}/api/v2/einvoices/zatca/generate

HTTP Method: POST

Description:

This endpoint allows clients to submit data for generating an e-invoice that is compliant with ZATCA. The data will be added to a queue system for processing.

Payload:

This is additional data on the existing payload. 

• webhook_url (url, optional) : endpoint where the invoice response will be received

• webhook_token : (string , required with webhook_url) secret token we'll be utilizing it in the request header under the API_AUTHENTICATION key

Response:

• Status Code: 200 OK

• Content Type: JSON

• Body:  

Sample response:

{   "id": 90,   "status": "IN QUEUE",   "message": "Invoice has been received",   "qr_string": "AQZLdXphbWECDzMxMDE0NTQ1MzgwMDAwMwMTMjAyNC0wNC0wMVQxMTo1NToxNwQDMTU4BQUyMC42MQYsOTM1b3hDaVl3VnNyeVdkam0vNjBadldqVUZQUTVkQ2NSeXlnbTFGejJZST0HYE1FWUNJUURIVFROMTgwaGhJRkdsMDZXamNhWVEycURMRzdJUndEaXBqaXhTSWhDRXlBSWhBTHk4UWE4RFFmMEU4WW56S0hhcW0yOWVYd21ibjZpM05pY3dPbXhQa1pHUghYMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE+R7mUm9nok7lfwb44GG0cW79nNxD0jVlNhiG04fN/ca/hsNOxw1u/7vjzNWFFSOqeEu5XQJpQ6gnWe4K3YF2LwlGMEQCIBh7wnM3mvtJuG0q7CGeW6HLir7Ixpo5jHc9xaCQ3XkLAiA7dZWP7VuWAHvyeZ79Z7CnuVEbSlZ0o8rKIVflNkdK5w==" }

Endpoint 2: Check E-Invoice Status

URL: {{base_url}}/api/v2/einvoices/zatca/ask

HTTP Method: GET

Description:

This endpoint allows clients to check the status of the previously submitted e-invoice by generation request identified by {id}.

Query Parameter:

• {invoices} (array): The unique identifier for the invoice generation request.

Response:

• Status Code: 200 OK

• Content Type: JSON

• Body:  

Sample Request

Sample response if the request is still in queue:

Sample response if the request processing has started but not finished:

Sample response if the request has been completed:

Webhook Data

The following Json sample shows what will be sent via webhooks to the receiving URLs.

Once the invoice is completed, the invoice response data will be sent out.