# naqrat.sa API ## Welcome to [نقرات](https://naqrat.sa) API Guide: > This documentation will describe on how the Naqrat API works, you will find all the details and endpoints here. From sending event to reading high event match quality responses from your ad account, the sky is the limit. Do you need a endpoint our API doesn't already cover? Just let us know, and we'll add it to the API. Get started → # Authorization ## **Get your API token** Login to your account and navigate to your [profile](https://dashboard.naqrat.sa/my-profile) to generate a new API token. You can name your API token so you are aware of where the token is being used, this way you can recognize and delete it later when you do not need it anymore. ### **Authorize with API** The token you have received (a very long string) can be used as a `bearer` token against our API. ``` Authorization: Bearer API_TOKEN_HERE ``` In this cURL example we demonstrate how to authenticate with our API: ```bash $ curl \\ -H 'Authorization: Bearer n3h4bZK1bCbQ2EBpibvWykSzP7aJuuXeJz...' \\ -H 'Accept: application/json' \\ -H 'Content-Type: application/json' ``` > 💡 {event\_name} is name for event that you would send to us currently support these events: * addtocart * viewcontent * checkout * purchase # Headers Make sure every request has these 2 headers included: ``` Accept: application/json Content-Type: application/json ``` We would appreciate if you also include your user agent in the headers, this header should accurately describe the nature of the API call where it is coming from: `User-Agent: 'domain.com'` # URL ## URL This is the base URL for our API: ``` https://api.naqrat.sa/api/ ``` # Send Purchase Event #### POST purchase ``` https://api.naqrat.sa/api/purchase ``` #### Purchase API This API endpoint allows you to send a purchase event order through the specified merchant when a customer completes the order process on your site. **Request Body** * `merchant` (Number): The ID of the merchant. * `created_at` (String): The timestamp of the purchase creation. * `cookiesocial` (Object): Contains social media tracking parameters. * `scid` (String): Social media campaign ID. * `fbp` (String): Facebook Pixel ID. * `fbc` (String): Facebook Click ID. * `ttclid` (String): Twitter Click ID. * `ttp` (String): TikTok Pixel ID. * `ga` (String): Google Analytics ID. * `twclid` (String): Twitter Click ID. * `data` (Object): Contains customer, ecommerce, and page data. * `customer` (Object): Information about the customer. * `phone` (Number): Customer's phone number. * `email_hashed` (String): Hashed customer email. * `phone_hashed` (String): Hashed customer phone number. * `name` (String): Customer's name. * `products` (Array): Ecommerce event and purchase details. * `id` (Number): Product ID. * `category` (String): Product category. * `price` (String): Product price. * `quantity` (Number): Quantity of the product. * `currencyCode` (Object): Information about the page. * `event_id` (Number): Unique event ID **Response** * `status` (String): Status of the purchase. * `message` (String): Additional message related to the purchase. * `products_count` (Number): Number of products in the purchase. * `created_at` (String): Timestamp of the purchase response creation. **AUTHORIZATION** Bearer Token *** **Token** `` **HEADERS** *** Accept `application/json` *** Body (json) ```json { "merchant": 1539686597, "created_at":"2023-12-21 12:09:49", "cookiesocial":{ "scid":"test pxil", "fbp":"facebook pxil", "fbc":"facebook pxil", "ttclid":"facebook pxil", "ttp":"facebook pxil", "ga":"facebook pxil", "twclid":"facebook pxil" }, "data":{ "customer":{ "phone":201123036886, "email_hashed":"as@gmail.com (hash sha256)", "phone_hashed":"201123036886 (hash sha256)", "name":"Ahmed Saed", }, "products":[ { "id": 12789, "category": "فستان", "price": "127", "quantity": 4 }, { "id": 12547, "category": "فستان", "price": "80", "quantity": 2 }, ], "revenue": 209, "currencyCode": "SAR", "event_id": 54687642 } } ``` **Example Request:** ```bash curl --location 'https://api.naqrat.sa/api/purchase' \ --header 'Accept: application/json' \ --data-raw '{ "merchant": 1539686597, "created_at":"2023-12-21 12:09:49", "cookiesocial":{ "scid":"test pxil", "fbp":"facebook pxil", "fbc":"facebook pxil", "ttclid":"facebook pxil", "ttp":"facebook pxil", "ga":"facebook pxil", "twclid":"facebook pxil" }, "data":{ "customer":{ "phone":201123036886, "email_hashed":"as@gmail.com (hash sha256)", "phone_hashed":"201123036886 (hash sha256)", "name":"Ahmed Saed", }, "products":[ { "id": 12789, "category": "فستان", "price": "127", "quantity": 4 }, { "id": 12547, "category": "فستان", "price": "80", "quantity": 2 }, ], "revenue": 209, "currencyCode": "SAR", "event_id": 54687642 } }' ``` #### Response *** Upon successful execution, the API will return a status 200 with the following response: ```json { "data": { "status": "", "message": "", "products_count": 0, "created_at": "" } } ``` # Send AddToCart Event #### POST AddToCart ``` https://api.naqrat.sa/api/addtocart ``` #### AddToCart API This API endpoint allows you to send a AddToCart event through the specified merchant when a customer adds any product to his cart on your site. **Request Body** * `merchant` (Number): The ID of the merchant. * `created_at` (String): The timestamp of the purchase creation. * `cookiesocial` (Object): Contains social media tracking parameters. * `scid` (String): Social media campaign ID. * `fbp` (String): Facebook Pixel ID. * `fbc` (String): Facebook Click ID. * `ttclid` (String): Twitter Click ID. * `ttp` (String): TikTok Pixel ID. * `ga` (String): Google Analytics ID. * `twclid` (String): Twitter Click ID. * `data` (Object): Contains customer, ecommerce, and page data. * `customer` (Object): Information about the customer. * `phone` (Number): Customer's phone number. * `email_hashed` (String): Hashed customer email. * `phone_hashed` (String): Hashed customer phone number. * `name` (String): Customer's name. * `products` (Array): Ecommerce event and purchase details. * `id` (Number): Product ID. * `category` (String): Product category. * `price` (String): Product price. * `quantity` (Number): Quantity of the product. * `currencyCode` (Object): Information about the page. * `event_id` (Number): Unique event ID. **Response** * `status` (String): Status of the purchase. * `message` (String): Additional message related to the purchase. * `products_count` (Number): Number of products in the purchase. * `created_at` (String): Timestamp of the purchase response creation. **AUTHORIZATION** Bearer Token *** **Token** `` **HEADERS** *** Accept `application/json` *** Body ```json { "merchant": 1539686597, "created_at":"2023-12-21 12:09:49", "cookiesocial":{ "scid":"test pxil", "fbp":"facebook pxil", "fbc":"facebook pxil", "ttclid":"facebook pxil", "ttp":"facebook pxil", "ga":"facebook pxil", "twclid":"facebook pxil" }, "data":{ "customer":{ "phone":201123036886, "email_hashed":"as@gmail.com (hash sha256)", "phone_hashed":"201123036886 (hash sha256)", "name":"Ahmed Saed", }, "products":[ { "id": 12789, "category": "فستان", "price": "127", "quantity": 4 } ], "total_price": 127, "currencyCode": "SAR", "event_id": 662fa119 } } ``` **Example Request:** ```bash curl --location 'https://api.naqrat.sa/api/addtocart' \ --header 'Accept: application/json' \ --data-raw '{ "merchant": 1539686597, "created_at":"2023-12-21 12:09:49", "cookiesocial":{ "scid":"test pxil", "fbp":"facebook pxil", "fbc":"facebook pxil", "ttclid":"facebook pxil", "ttp":"facebook pxil", "ga":"facebook pxil", "twclid":"facebook pxil" }, "data":{ "customer":{ "phone":201123036886, "email_hashed":"as@gmail.com (hash sha256)", "phone_hashed":"201123036886 (hash sha256)", "name":"Ahmed Saed", }, "products":[ { "id": 12789, "category": "فستان", "price": "127", "quantity": 4 } ], "total_price": 127, "currencyCode": "SAR", "event_id": 662fa119 } }' ``` #### Response *** Upon successful execution, the API will return a status 200 with the following response: ```json { "data": { "status": "", "message": "", "products_count": 0, "created_at": "" } } ``` # Send ViewContent Event #### POST ViewContent ``` https://api.naqrat.sa/api/viewcontent ``` #### ViewContent API This API endpoint allows you to send a ViewContent event through the specified merchant when a customer views certain content within your site **Request Body** * `merchant` (Number): The ID of the merchant. * `created_at` (String): The timestamp of the purchase creation. * `cookiesocial` (Object): Contains social media tracking parameters. * `scid` (String): Social media campaign ID. * `fbp` (String): Facebook Pixel ID. * `fbc` (String): Facebook Click ID. * `ttclid` (String): Twitter Click ID. * `ttp` (String): TikTok Pixel ID. * `ga` (String): Google Analytics ID. * `twclid` (String): Twitter Click ID. * `data` (Object): Contains customer, ecommerce, and page data. * `customer` (Object): Information about the customer. * `phone` (Number): Customer's phone number. * `email_hashed` (String): Hashed customer email. * `phone_hashed` (String): Hashed customer phone number. * `name` (String): Customer's name. * `products` (Array): Ecommerce event and purchase details. * `id` (Number): Product ID. * `category` (String): Product category. * `price` (String): Product price. * `quantity` (Number): Quantity of the product. * `currencyCode` (Object): Information about the page. * `event_id` (Number): Unique event ID. **Response** * `status` (String): Status of the purchase. * `message` (String): Additional message related to the purchase. * `products_count` (Number): Number of products in the purchase. * `created_at` (String): Timestamp of the purchase response creation. **AUTHORIZATION** Bearer Token *** **Token** `` **HEADERS** *** Accept `application/json` *** Body ```json { "merchant": 1539686597, "created_at":"2023-12-21 12:09:49", "cookiesocial":{ "scid":"test pxil", "fbp":"facebook pxil", "fbc":"facebook pxil", "ttclid":"facebook pxil", "ttp":"facebook pxil", "ga":"facebook pxil", "twclid":"facebook pxil" }, "data":{ "customer":{ "phone":201123036886, "email_hashed":"as@gmail.com (hash sha256)", "phone_hashed":"201123036886 (hash sha256)", "name":"Ahmed Saed", }, "products":[ { "id": 12789, "category": "فستان", "price": "127", "quantity": 4 } ], "total_price": 127, "currencyCode": "SAR", "event_id": 662fa119 } } ``` **Example Request:** ```bash curl --location 'https://api.naqrat.sa/api/viewcontent' \ --header 'Accept: application/json' \ --data-raw '{ "merchant": 1539686597, "created_at":"2023-12-21 12:09:49", "cookiesocial":{ "scid":"test pxil", "fbp":"facebook pxil", "fbc":"facebook pxil", "ttclid":"facebook pxil", "ttp":"facebook pxil", "ga":"facebook pxil", "twclid":"facebook pxil" }, "data":{ "customer":{ "phone":201123036886, "email_hashed":"as@gmail.com (hash sha256)", "phone_hashed":"201123036886 (hash sha256)", "name":"Ahmed Saed", }, "products":[ { "id": 12789, "category": "فستان", "price": "127", "quantity": 4 } ], "total_price": 127, "currencyCode": "SAR", "event_id": 662fa119 } }' ``` #### Response *** Upon successful execution, the API will return a status 200 with the following response: ```json { "data": { "status": "", "message": "", "products_count": 0, "created_at": "" } } ``` # Send Checkout Event #### POST Checkout ``` https://api.naqrat.sa/api/checkout ``` #### Purchase API This API endpoint allows you to send a Checkout event when the customer starts the purchasing process and goes to the shopping cart. **Request Body** * `merchant` (Number): The ID of the merchant. * `created_at` (String): The timestamp of the purchase creation. * `cookiesocial` (Object): Contains social media tracking parameters. * `scid` (String): Social media campaign ID. * `fbp` (String): Facebook Pixel ID. * `fbc` (String): Facebook Click ID. * `ttclid` (String): Twitter Click ID. * `ttp` (String): TikTok Pixel ID. * `ga` (String): Google Analytics ID. * `twclid` (String): Twitter Click ID. * `data` (Object): Contains customer, ecommerce, and page data. * `customer` (Object): Information about the customer. * `phone` (Number): Customer's phone number. * `email_hashed` (String): Hashed customer email. * `phone_hashed` (String): Hashed customer phone number. * `name` (String): Customer's name. * `products` (Array): Ecommerce event and purchase details. * `id` (Number): Product ID. * `category` (String): Product category. * `price` (String): Product price. * `quantity` (Number): Quantity of the product. * `currencyCode` (Object): Information about the page. * `event_id` (Number): Unique event ID. **Response** * `status` (String): Status of the purchase. * `message` (String): Additional message related to the purchase. * `products_count` (Number): Number of products in the purchase. * `created_at` (String): Timestamp of the purchase response creation. **AUTHORIZATION** Bearer Token *** **Token** `` **HEADERS** *** Accept `application/json` *** Body ```json { "merchant": 1539686597, "created_at":"2023-12-21 12:09:49", "cookiesocial":{ "scid":"test pxil", "fbp":"facebook pxil", "fbc":"facebook pxil", "ttclid":"facebook pxil", "ttp":"facebook pxil", "ga":"facebook pxil", "twclid":"facebook pxil" }, "data":{ "customer":{ "phone":201123036886, "email_hashed":"as@gmail.com (hash sha256)", "phone_hashed":"201123036886 (hash sha256)", "name":"Ahmed Saed", }, "products":[ { "id": 12789, "category": "فستان", "price": "127", "quantity": 4 }, { "id": 12547, "category": "فستان", "price": "80", "quantity": 2 }, ], "revenue": 209, "currencyCode": "SAR", "event_id": 54687642 } } ``` **Example Request:** ```bash curl --location 'https://api.naqrat.sa/api/checkout' \ --header 'Accept: application/json' \ --data-raw '{ "merchant": 1539686597, "created_at":"2023-12-21 12:09:49", "cookiesocial":{ "scid":"test pxil", "fbp":"facebook pxil", "fbc":"facebook pxil", "ttclid":"facebook pxil", "ttp":"facebook pxil", "ga":"facebook pxil", "twclid":"facebook pxil" }, "data":{ "customer":{ "phone":201123036886, "email_hashed":"as@gmail.com (hash sha256)", "phone_hashed":"201123036886 (hash sha256)", "name":"Ahmed Saed", }, "products":[ { "id": 12789, "category": "فستان", "price": "127", "quantity": 4 } ], "total_price": 127, "currencyCode": "SAR", "event_id": 662fa119 } }' ``` #### Response *** Upon successful execution, the API will return a status 200 with the following response: ```json { "data": { "status": "", "message": "", "products_count": 0, "created_at": "" } } ```