{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"5db308df-8888-4040-b6a7-33b8f957c2f4","name":"API_Client","description":"# API_Client Documentation\n\n## Overview\n\nThe API_Client collection exposes Perkle Integration API endpoints for authentication, brands, product details, balance checks, order placement, order status checks, and voucher retrieval. Use the Generate Bearer Code request to obtain an access token and include it as a Bearer token for subsequent requests. Available endpoints include: Generate Bearer Code (auth), Brands, Product, Balance Check, Order, Order Status Check, and Get Voucher.\n\n## Getting started\n\n- Use the API_client environment for example variable values (secrets masked).\n    \n- Set/verify these variables:\n    \n    - host: Base URL for the API ([https://preprod-svc.perkle.store](https://preprod-svc.perkle.store))\n        \n    - email / password: Valid credentials for authentication\n        \n    - bearerToken: Will be populated automatically after a successful auth call\n        \n\n## Authentication\n\nType: Bearer Token\n\nInstructions:\n\n1. Call POST {{host}}/perkle-svc/api/v2/integration/auth with valid email and password.\n    \n2. On success, the request’s test script stores `res.data.accessToken` to the environment variable `bearerToken`.\n    \n3. Subsequent requests include header: `Authorization: Bearer {{bearerToken}}`.\n    \n\nVariables used: `host`, `email`, `password`, `bearerToken`\n\n### Authentication Flow\n\n1) POST /perkle-svc/api/v2/integration/auth — Exchange credentials for access token.  \n2) Use the token in the Authorization header for Brands, Product, Balance, Order, Order Status Check, and Voucher endpoints.\n\n---\n\n## Endpoints\n\n### Generate Bearer Code — POST {{host}}/perkle-svc/api/v2/integration/auth\n\nPurpose: Obtain an access token for subsequent API calls.\n\nHeaders:\n\n- Content-Type: application/json\n    \n\nBody (raw JSON):\n\n``` json\n{\n  \"email\": {{email}},\n  \"password\": {{password}}\n}\n\n ```\n\nTests:\n\n- Asserts 200 OK and saves `data.accessToken` to environment variable `bearerToken`.\n    \n\nExample Successful Response (200):\n\n``` json\n{\n  \"data\": {\n    \"accessToken\": \"<jwt>\",\n    \"expiresIn\": 3600,\n    \"tokenType\": \"Bearer\"\n  },\n  \"message\": \"Access token generated successfully\",\n  \"timestamp\": \"<iso-timestamp>\",\n  \"status\": \"SUCCESS\"\n}\n\n ```\n\nSaved examples include unauthorized scenarios for invalid credentials or missing body.\n\n---\n\n### Brands — GET {{host}}/perkle-svc/api/v2/integration/brands\n\nPurpose: List available brands.  \nAuth: Bearer {{bearerToken}}\n\n---\n\n### Product — GET {{host}}/perkle-svc/api/v2/integration/product/:productId\n\nPurpose: Retrieve details for a specific product ID.  \nPath variables: `:productId`  \nAuth: Bearer {{bearerToken}}\n\n---\n\n### Balance Check — GET {{host}}/perkle-svc/api/v2/integration/balance}\n\nPurpose: Retrieve wallet or account balance.  \nAuth: Bearer {{bearerToken}}\n\n---\n\n### Order — POST {{host}}/perkle-svc/api/v2/integration/order\n\nPurpose: Create a new order for a specific product and quantity.  \nAuth: Bearer {{bearerToken}}\n\nHeaders:\n\n- Content-Type: application/json\n    \n- Authorization: Bearer {{bearerToken}}\n    \n\nBody (raw JSON):\n\n``` json\n{\n  \"productId\": \"<string>\",\n  \"quantity\": 1,\n  \"referenceId\": \"<string>\"\n}\n\n ```\n\nExample Request:\n\n``` http\nPOST {{host}}/perkle-svc/api/v2/integration/order\nAuthorization: Bearer {{bearerToken}}\nContent-Type: application/json\n{\n  \"productId\": \"UAT_S36Q19_RTPTONAQV998-YP\",\n  \"quantity\": 2,\n  \"referenceId\": \"REF-2024-12-001\"\n}\n\n ```\n\nExample Successful Response (200):\n\n``` json\n{\n    \"data\": {\n        \"referenceId\": \"ff240a92-cf-13bbb\",\n        \"orderId\": \"NCX0000001\"\n    },\n    \"message\": \"Order has been created and queued for processing.\",\n    \"timestamp\": \"2025-12-18T05:41:59.723Z\",\n    \"status\": \"SUCCESS\"\n}\n\n ```\n\nNotes:\n\n- Ensure sufficient balance before placing an order.\n    \n- Idempotency: reuse the same referenceId to avoid duplicate orders.\n    \n- Store the orderId for downstream APIs\n    \n\n---\n\n### Order Status Check — GET {{host}}/perkle-svc/api/v2/integration/order/status?orderId=\"orderid\"\n\nPurpose: Retrieve the current fulfillment status of a previously created order.  \nPath variables: `:orderId` (UUID-like).  \nAuth: Bearer {{bearerToken}}\n\nHeaders:\n\n- Authorization: Bearer {{bearerToken}}\n    \n\nExample Request:\n\n``` http\ncurl --location '/perkle-svc/api/v2/integration/order/status?orderId=NCX0000001' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJkNTljOTY0Yy04MGYzLTQ2ZDctYWIxMy1kODIyNzFhOTU2YTYiLCJlbWFpbCI6ImRoYW5hcGFuZGkrYXBpQG5lb2tyZWQudGVjaCIsInJvbGUiOiJBUElfQ0xJRU5UIiwiaWF0IjoxNzY1Nzg0MDIzLCJleHAiOjE3NjU3ODc2MjN9.hBFgKX_Rt9or4aweHHmldjhgZp2TrB2g7K7mBeFQhj8'\n\n ```\n\nExample Successful Response (200):\n\n``` json\n{\n    \"data\": {\n        \"orderId\": \"NCX0000001\",\n        \"status\": \"DELIVERED\"\n    },\n    \"message\": \"Order status fetched successfully\",\n    \"timestamp\": \"<iso-timestamp>\",\n    \"status\": \"SUCCESS\"\n}\n\n ```\n\nNotes:\n\n- Poll this endpoint until a terminal state: DELIVERED, PARTIAL_DELIVERED, or FAILED.\n    \n- Order status values are limited to: PROCESSING, DELIVERED, PARTIAL_DELIVERED, FAILED.\n    \n\n---\n\n### Voucher — GET {{host}}/perkle-svc/api/v2/integration/voucher/:orderId\n\nPurpose: Retrieve voucher or fulfillment details for a completed order.  \nPath variables: `:orderId` (UUID-like).  \nAuth: Bearer {{bearerToken}}\n\nHeaders:\n\n- Authorization: Bearer {{bearerToken}}\n    \n\nExample Request:\n\n``` http\nGET {{host}}/perkle-svc/api/v2/integration/voucher?orderId=NCX0000001&page=1&size=10\nAuthorization: Bearer {{bearerToken}}\n\n ```\n\nExample Successful Response (200):\n\n``` json\n{\n  \"data\": {\n    \"orderId\": \"4f2a9b10-6d1a-4b1c-9a2e-3f5e7c9a1b23\",\n    \"vouchers\": [\n      {\n        \"code\": \"<sensitive-not-logged>\",\n        \"pin\": \"<sensitive-not-logged>\",\n        \"expiresAt\": \"2026-12-31T23:59:59Z\"\n      }\n    ]\n  },\n  \"message\": \"Voucher details\",\n  \"timestamp\": \"<iso-timestamp>\",\n  \"status\": \"SUCCESS\"\n}\n\n ```\n\nNotes:\n\n- Only available once status is DELIVERED.\n    \n- Treat voucher fields as sensitive: do not log or store raw values.\n    \n- If pagination applies, use `page` and `size` query params (integers).\n    \n\n---\n\n## Notes\n\n- Replace path variables like `:productId` with a valid value.\n    \n- Ensure `host` points to the correct environment (sandbox/uat/prod).\n    \n- **Order Status API** is polled every **4 minutes**, up to a maximum of **3 attempts**\n    \n- **Product and brand data** should be fetched and stored in your database, and the data should be refreshed by calling our APIs **once every 4 days** to keep it up to date..\n    \n\n## Run in Postman\n\nUse the Run in Postman button to quickly import and run this collection along with the linked environment:\n\n<a href=\"https://god.gw.postman.com/run-collection/49786156-5db308df-8888-4040-b6a7-33b8f957c2f4\"><img src=\"https://run.pstmn.io/button.svg\"></a>","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"49786156","team":11303169,"collectionId":"5db308df-8888-4040-b6a7-33b8f957c2f4","publishedId":"2sB3Wqsz4F","public":true,"publicUrl":"https://api-docs.perkle.store","privateUrl":"https://go.postman.co/documentation/49786156-5db308df-8888-4040-b6a7-33b8f957c2f4","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"006769"},"documentationLayout":"classic-single-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/3d54edb4-d406-4030-bae9-1852321c6a05/UGVya2xlIGxvZ28gYmxhY2sgMS5wbmc=","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"006769"}},{"name":"light","logo":"https://content.pstmn.io/924f49e2-ce38-4e3c-a830-c5db88b68d65/UGVya2xlIGxvZ28gMS5wbmc=","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"006769"}}]}},"version":"8.11.8","publishDate":"2025-11-04T10:11:31.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/924f49e2-ce38-4e3c-a830-c5db88b68d65/UGVya2xlIGxvZ28gMS5wbmc=","logoDark":"https://content.pstmn.io/3d54edb4-d406-4030-bae9-1852321c6a05/UGVya2xlIGxvZ28gYmxhY2sgMS5wbmc="}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/39f355a52cf03e21b724d244470bfde4bf61d844e8445be6ef59921e3f10134f","favicon":"https://perkle.store/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://api-docs.perkle.store/view/metadata/2sB3Wqsz4F"}