For platforms or as white label

If you're a platform or a marketplace, you can issue ZATCA-compliant phase 2 invoices on the behalf of your customers using the Connected Account feature.

The Connected Account API allows you to onboard your customers to Fatoora programmatically, without them having the need to create an account on Wafeq. It is a one time setup where they just need to provide you with an OTP from their Fatoora portal, and by registering them, you will then be able to issue invoices on their behalf and report them to ZATCA.

For example, say you're an e-commerce platform that lets merchants create online stores. You'd like to offer your merchants the ability to issue Phase 2 invoices for orders placed by their customers. You will use the Connected Account API to have them connect their Fatoora portal and start issuing invoices on their behalf.

Here's how you would use Connected Accounts to report an invoice on behalf of your customer:

Create connected account for your customer:
To create a connected account for your customer; use your API-Key from your Wafeq account along with your customer’s address details and theirtax_registration_number.
In the request response, you will receive the customer's created connected account id that will be used in step 2.

curl --request POST \
     --url https://api.wafeq.com/v1/zatca/connected-accounts/ \
     --header 'Authorization: Api-Key <Your API Key>' \
     --header 'Content-Type: application/json' \
     --data '
{
  "name": "ABCD Inc",
  "address": "Anas Bin Malik, Al Malqa",
  "city": "Riyadh",
  "country": "SA",
  "business_category": "Manufacturing",
  "tax_registration_number": "311111111111113"
}
'

Register a device on behalf of the connected account:
Ask your customer to obtain an OTP from their Fatoora portal and by using your API-Key and your customer connected account ID in X-ZATCA-Connected-Account-ID in the request header you can register a device on their behalf.

curl --request POST \
     --url https://api.wafeq.com/v1/zatca/devices/register/ \
     --header 'Authorization: Api-Key <Your API Key>' \
     --header 'Content-Type: application/json' \
     --header 'X-ZATCA-Environment: production' \
     --header 'X-ZATCA-Connected-Account-ID: <ID of the connected account from step 1>' \
     --data '
{
  "common_name": "Device 1",
  "otp": "111111"
}
'

Report an invoice on behalf of the connected account:
Now that your customer's connected account is created and have a registered device, you can proceed with reporting an invoice on their behalf using:
• Your API-Key in the request header.
• Your customer connected account ID in the X-ZATCA-Connected-Account-ID in the request header.
• Your customer CRN in the document.supplier.identication.valuein the request body.

curl --request POST \
     --url https://api.wafeq.com/v1/zatca/invoices/report/ \
     --header 'Authorization: Api-Key <Your API Key>' \
     --header 'Content-Type: application/json' \
     --header 'X-ZATCA-Environment: production' \
     --header 'X-ZATCA-Connected-Account-ID: <ID of the connected account from step 1>' \
     --data '
{

"language": "ar",
  "document": {
    "currency": "SAR",
    "supplier": {
      "address": {
        "country": "SA",
        "building": "1234",
        "city": "City",
        "district": "Disctrict",
        "postal_code": "12345",
        "street": "Street"
      },
      "identification": {
        "type": "CRN",
        "value": "0123456789"
      },
      "name": "Your Customer Name"
    },
    "tax_amount_type": "E",
    "tax_total": 0,
    
    ..... END CLIENT DETAILS
    
    "customer": {
      "address": {
        "country": "SA",
        "building": "Building",
        "city": "City",
        "district": "Disctrict",
        "postal_code": "12345",
        "street": "Street"
      },
      "identification": {
        "type": "CRN",
        "value": "3111111113"
      },
      "tax_registration_number": "3111111113",
      "name": "Your customer client name"
    }
  }
}
  
}
'