{ "info": { "_postman_id": "6a3bb77519d96", "name": "WEAF MRA EIS API", "description": "Comprehensive API for WEAF Company Malawi - Integrated with Malawi Revenue Authority (MRA) EIS system.\r\n * \r\n * With this API, you don't need to handle complex implementations\u2014just follow a few simple steps to get started:\n\n\ud83d\udcd6 **API Readable Documentation:** [https://weafcompany.com/api/malawi/documentation](https://weafcompany.com/api/malawi/documentation)\r\n * \r\n * ## \ud83d\ude80 Getting Started\r\n * 1. **Signup**\r\n * Create an account at [weafcompany.com/login](https://weafcompany.com/login).\r\n * \r\n * 2. **Create a Company**\r\n * After signing up, register your company profile inside the platform.\r\n * \r\n * 3. **Generate Access Tokens**\r\n * Obtain access tokens that will allow you to connect and test the API.\r\n * \r\n * 4. **Testing Environment**\r\n * You can immediately start testing the API using the provided sandbox environment.\r\n * \r\n * 5. **Production Access**\r\n * To move to production, you are required to:\r\n * - Subscribe to a plan and make payment.\r\n * - Complete the configuration process.\r\n * - After approval, you can begin using the API in production.\r\n * \r\n * This documentation provides details of all available endpoints, request/response formats, and usage guidelines.\r\n * \r\n * ## \ud83d\udd10 Authentication Guide\r\n * \r\n * ### Step 1: Generate Your Access Token\r\n * 1. Use the **Generate API Access Token** endpoint below\r\n * 2. Provide your email and password credentials\r\n * 3. Set your desired token expiration period (1-365 days)\r\n * 4. Give your token a descriptive name\r\n * 5. Copy the returned token value\r\n * \r\n * ### Step 2: Use Your Token in Swagger UI\r\n * 1. Click the **\ud83d\udd11 Authorize** button at the top of this page\r\n * 2. In the **bearerAuth** section, enter your token in the **Value** field\r\n * 3. **Important**: Enter ONLY the token value (without 'Bearer ' prefix)\r\n * 4. Click **Authorize** to save your token\r\n * 5. Click **Close** to return to the API documentation\r\n * \r\n * ### Step 3: Make API Calls\r\n * - All protected endpoints will now use your token automatically\r\n * - Your token will be included in the Authorization header as: `Bearer {your_token}`\r\n * - You can see the lock icon \ud83d\udd12 next to endpoints that require authentication\r\n * \r\n * ### \ud83d\udd04 Token Refresh Process\r\n * When your token is about to expire:\r\n * 1. Use the **Refresh API Access Token** endpoint\r\n * 2. Pass your current token in the request body\r\n * 3. **For Swagger UI**: Also pass your current token in the Bearer token field above\r\n * 4. Get a new token with extended expiration\r\n * 5. Update your authorization with the new token", "version": "1.0.0", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "item": [ { "name": "Authentication", "item": [ { "name": "Generate API Access Token", "description": "Authenticate a user and generate an API access token for programmatic access to the system. This endpoint validates user credentials and creates a secure token that can be used for subsequent API calls. The token provides access to company-specific data and operations based on the user's permissions.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/auth/generate-token", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "auth", "generate-token" ] }, "body": { "mode": "raw", "raw": "{\n \"username\": \"user@example.com\",\n \"password\": \"SecurePassword123!\",\n \"expiry_days\": 30,\n \"token_name\": \"Mobile App Integration\",\n \"tin\": null\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Token generated successfully - Authentication successful", "status": "Token generated successfully - Authentication successful", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"SUCCESS\"\n },\n \"data\": {\n \"token\": \"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4\",\n \"token_name\": \"Mobile App Integration\",\n \"expires_at\": \"2024-11-30T10:30:00.000000Z\",\n \"expires_in_days\": 30,\n \"user\": {\n \"id\": 1,\n \"name\": \"John Doe\",\n \"email\": \"user@example.com\",\n \"companies_count\": 2\n },\n \"companies\": [\n {\n \"id\": 1,\n \"business_name\": \"ABC Company Ltd\",\n \"tin\": \"1000251604\",\n \"environment\": \"production\"\n }\n ],\n \"usage_info\": {\n \"total_requests\": 0,\n \"last_used\": null,\n \"created_at\": \"2024-10-30T10:30:00.000000Z\"\n }\n }\n}" }, { "name": "400 - Validation Error - Invalid request data", "status": "Validation Error - Invalid request data", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"01\",\n \"returnMessage\": \"VALIDATION_ERROR\"\n },\n \"data\": {\n \"errors\": {\n \"username\": [\n \"The username field is required.\"\n ],\n \"password\": [\n \"The password must be at least 6 characters.\"\n ],\n \"expiry_days\": [\n \"The expiry days must be between 1 and 365.\"\n ],\n \"token_name\": [\n \"The token name field is required.\"\n ]\n }\n }\n}" }, { "name": "401 - Authentication Failed - Invalid credentials", "status": "Authentication Failed - Invalid credentials", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"02\",\n \"returnMessage\": \"USER_NOT_FOUND\"\n },\n \"data\": {}\n}" }, { "name": "403 - Access Forbidden - User account restrictions", "status": "Access Forbidden - User account restrictions", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"03\",\n \"returnMessage\": \"NO_COMPANIES_FOUND\"\n },\n \"data\": {\n \"message\": \"User has no companies associated with their account\"\n }\n}" }, { "name": "500 - Internal Server Error - System error occurred", "status": "Internal Server Error - System error occurred", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"99\",\n \"returnMessage\": \"INTERNAL_SERVER_ERROR\"\n },\n \"data\": {\n \"message\": \"An unexpected error occurred while generating the token\"\n }\n}" } ] }, { "name": "Validate access token", "description": "Validate an existing access token and get user/company information", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/auth/validate-token", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "auth", "validate-token" ] }, "body": { "mode": "raw", "raw": "{\n \"token\": \"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Token is valid", "status": "Token is valid", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"SUCCESS\"\n },\n \"data\": {\n \"token_valid\": true,\n \"token_name\": \"My API Token\",\n \"expires_at\": \"2024-11-30T10:30:00.000000Z\",\n \"user\": {\n \"id\": 1,\n \"name\": \"John Doe\",\n \"email\": \"user@example.com\"\n },\n \"companies\": [\n {\n \"id\": 1,\n \"business_name\": \"ABC Company Ltd\",\n \"tin\": \"1000251604\",\n \"environment\": \"production\"\n }\n ]\n }\n}" }, { "name": "400 - Validation error", "status": "Validation error", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"01\",\n \"returnMessage\": \"VALIDATION_ERROR\"\n },\n \"data\": {\n \"errors\": {}\n }\n}" }, { "name": "401 - Invalid or expired token", "status": "Invalid or expired token", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"04\",\n \"returnMessage\": \"INVALID_OR_EXPIRED_TOKEN\"\n },\n \"data\": null\n}" }, { "name": "500 - Internal server error", "status": "Internal server error", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"99\",\n \"returnMessage\": \"INTERNAL_SERVER_ERROR\"\n },\n \"data\": {\n \"message\": \"An unexpected error occurred while validating the token\"\n }\n}" } ] }, { "name": "Refresh API Access Token", "description": "Refresh an existing access token to get a new token with extended expiration period. This endpoint allows you to extend the validity of your current token without re-authenticating with username and password. The new token will have a longer expiration period and the old token will be invalidated.\r\n\r\n**Important for Swagger UI users:**\r\n1. First, add your current token to the Bearer token field using the 'Authorize' button above\r\n2. Then use this endpoint to refresh your token\r\n3. The old token will be passed in both the request body AND the Authorization header", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/auth/refresh-token", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "auth", "refresh-token" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"expiry_days\": 60,\n \"token_name\": \"Refreshed Mobile App Token\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Token refreshed successfully", "status": "Token refreshed successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"TOKEN_REFRESHED_SUCCESSFULLY\"\n },\n \"data\": {\n \"new_token\": \"b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4\",\n \"old_token\": \"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4\",\n \"token_name\": \"Refreshed Mobile App Token\",\n \"expires_at\": \"2024-12-30T10:30:00.000000Z\",\n \"expires_in_days\": 60,\n \"user\": {\n \"id\": 1,\n \"name\": \"John Doe\",\n \"email\": \"user@example.com\"\n },\n \"companies\": [\n {\n \"id\": 1,\n \"business_name\": \"ABC Company Ltd\",\n \"tin\": \"1000251604\"\n }\n ],\n \"refresh_info\": {\n \"refreshed_at\": \"2024-10-30T10:30:00.000000Z\",\n \"old_token_expired_at\": \"2024-11-30T10:30:00.000000Z\",\n \"extension_days\": 30\n }\n }\n}" }, { "name": "400 - Validation Error - Invalid request data", "status": "Validation Error - Invalid request data", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"01\",\n \"returnMessage\": \"VALIDATION_ERROR\"\n },\n \"data\": {\n \"errors\": {\n \"expiry_days\": [\n \"The expiry days must be between 1 and 365.\"\n ],\n \"token_name\": [\n \"The token name field is required.\"\n ]\n }\n }\n}" }, { "name": "401 - Authentication Failed - Invalid or expired token", "status": "Authentication Failed - Invalid or expired token", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"02\",\n \"returnMessage\": \"INVALID_TOKEN\"\n },\n \"data\": {}\n}" }, { "name": "403 - Access Forbidden - Token refresh not allowed", "status": "Access Forbidden - Token refresh not allowed", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"03\",\n \"returnMessage\": \"TOKEN_REFRESH_DISABLED\"\n },\n \"data\": {}\n}" }, { "name": "500 - Internal Server Error - System error occurred", "status": "Internal Server Error - System error occurred", "code": 500, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"99\",\n \"returnMessage\": \"INTERNAL_SERVER_ERROR\"\n },\n \"data\": {\n \"message\": \"An unexpected error occurred while refreshing the token\"\n }\n}" } ] } ] }, { "name": "Malawi MRA Configuration", "item": [ { "name": "Sync latest configurations (Malawi MRA)", "description": "Synchronize the latest terminal configurations from Malawi Revenue Authority (MRA) EIS system. This updates tax rates, terminal settings, and taxpayer configuration. Requires an activated terminal.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/sync-latest-configurations?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "sync-latest-configurations" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Configurations synced successfully", "status": "Configurations synced successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Retrieved latest configurations\"\n },\n \"data\": {\n \"globalConfiguration\": {},\n \"terminalConfiguration\": {},\n \"taxpayerConfiguration\": {}\n }\n}" }, { "name": "400 - Bad request - invalid parameters or missing terminal", "status": "Bad request - invalid parameters or missing terminal", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Terminal not found - Please activate the terminal first", "status": "Terminal not found - Please activate the terminal first", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "403 - Forbidden - Company inactive, license expired, or environment mismatch", "status": "Forbidden - Company inactive, license expired, or environment mismatch", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] } ] }, { "name": "Malawi MRA Onboarding", "item": [ { "name": "Activate terminal (Malawi MRA)", "description": "Activate a new terminal with Malawi Revenue Authority (MRA) EIS system. Returns JWT tokens and security configurations on success.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/activate-terminal?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "activate-terminal" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalActivationCode\": \"816Q-3VZP-6ZZY-K9Y5\",\n \"platformInfo\": {\n \"platform\": {\n \"osName\": \"Microsoft Windows 10 Pro\",\n \"osVersion\": \"10.0.19045\",\n \"osBuild\": \"19045\",\n \"macAddress\": \"2E-CF-D9-E8-84-EE\"\n },\n \"pos\": {\n \"productID\": \"sera\",\n \"productVersion\": \"v3.0\"\n }\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Terminal activated successfully", "status": "Terminal activated successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"SUCCESS\"\n },\n \"data\": {\n \"message\": \"Terminal Activated successfully\",\n \"terminal\": {\n \"terminalId\": \"uuid-string\",\n \"status\": \"activated\",\n \"activationDate\": \"2024-01-01T00:00:00Z\"\n }\n }\n}" }, { "name": "400 - Activation failed", "status": "Activation failed", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"01\",\n \"returnMessage\": \"Terminal already activated\"\n }\n}" }, { "name": "401 - Unauthorized - Invalid or missing Bearer token", "status": "Unauthorized - Invalid or missing Bearer token", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "403 - Forbidden - Company mismatch or account inactive", "status": "Forbidden - Company mismatch or account inactive", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Confirm terminal activation (Malawi MRA)", "description": "Confirm a terminal activation with Malawi Revenue Authority (MRA) EIS system. This finalizes the terminal setup after initial activation.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/confirm-terminal-activation?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "confirm-terminal-activation" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Terminal confirmation successful", "status": "Terminal confirmation successful", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"SUCCESS\"\n },\n \"data\": {\n \"message\": \"Terminal is now fully activated and ready for use!\",\n \"confirmed\": true\n },\n \"http_status\": 200\n}" }, { "name": "400 - Confirmation failed", "status": "Confirmation failed", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "401 - Unauthorized - Invalid or missing Bearer token", "status": "Unauthorized - Invalid or missing Bearer token", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "403 - Forbidden - Company mismatch or account inactive", "status": "Forbidden - Company mismatch or account inactive", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Get configured terminals (Malawi MRA)", "description": "Retrieve all configured and activated terminals for a given TIN from the WEAF backend database.", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/terminals", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "terminals" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] } }, "response": [ { "name": "200 - Terminals retrieved successfully", "status": "Terminals retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"SUCCESS\"\n },\n \"data\": [\n {\n \"terminal_id\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"terminal_label\": \"Main Till\",\n \"terminal_position\": \"1\",\n \"status\": \"activated\",\n \"jwt_token\": \"eyJhbGciOiJIUzUxMiJ9...\",\n \"secret_key\": \"...\",\n \"site_id\": \"...\",\n \"site_name\": \"...\",\n \"activation_date\": \"2024-01-01T00:00:00Z\"\n }\n ],\n \"http_status\": 200\n}" }, { "name": "401 - Unauthorized - Invalid or missing Bearer token", "status": "Unauthorized - Invalid or missing Bearer token", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "403 - Forbidden - Company mismatch or account inactive", "status": "Forbidden - Company mismatch or account inactive", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Request New Terminal Token (Malawi MRA)", "description": "Retrieve the latest terminal security credentials (JWT token and Secret Key) from the MRA system. This is required when your current session has expired (indicated by a 401 Unauthorized response or MRA statusCode -2). The local database is automatically updated with the new credentials.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/request-new-terminal-token?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "request-new-terminal-token" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"siteId\": \"CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Terminal tokens retrieved and updated successfully", "status": "Terminal tokens retrieved and updated successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Latest terminal token retrieved successfully\"\n },\n \"data\": {\n \"secretKey\": \"719c248c608abd142e359c444c413441eb58e0b\",\n \"jwtToken\": \"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...\"\n }\n}" }, { "name": "400 - Failed to retrieve tokens or missing required fields", "status": "Failed to retrieve tokens or missing required fields", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"01\",\n \"returnMessage\": \"siteId is required in request body\"\n }\n}" }, { "name": "401 - MRA Session Expired: You are not authorised.", "status": "MRA Session Expired: You are not authorised.", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Company or Terminal not found", "status": "Company or Terminal not found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] } ] }, { "name": "Malawi MRA Utilities", "item": [ { "name": "Get terminal site products (Malawi MRA)", "description": "Retrieve products and services for a specific terminal site from Malawi Revenue Authority (MRA) EIS system.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/get-site-terminal-products?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "get-site-terminal-products" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"siteId\": \"CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce\",\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Products retrieved successfully", "status": "Products retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Products and services retrieved successfully.\"\n },\n \"data\": [\n {\n \"productCode\": \"string\",\n \"productName\": \"string\",\n \"description\": \"string\",\n \"quantity\": 0,\n \"unitOfMeasure\": \"string\",\n \"price\": 0,\n \"siteId\": \"string\",\n \"productExpiryDate\": \"string\",\n \"minimumStockLevel\": 0,\n \"taxRateId\": \"string\",\n \"isProduct\": true\n }\n ]\n}" }, { "name": "400 - Bad request - invalid parameters", "status": "Bad request - invalid parameters", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Terminal not found or not activated", "status": "Terminal not found or not activated", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Get warehouse products (Malawi MRA)", "description": "Retrieve warehouse inventory products with pagination from Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal with valid JWT credentials.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/get-warehouse-products?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "get-warehouse-products" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"page\": 1,\n \"pageSize\": 50\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Warehouse products retrieved successfully", "status": "Warehouse products retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Warehouse inventory retrieved successfully\"\n },\n \"data\": {\n \"stocks\": [\n {\n \"barcode\": \"string\",\n \"productName\": \"string\",\n \"productDescription\": \"string\",\n \"currentQuantity\": 0,\n \"uom\": \"string\",\n \"price\": 0\n }\n ],\n \"total\": 0,\n \"page\": 0,\n \"pageSize\": 0\n }\n}" }, { "name": "400 - Bad request - invalid parameters or missing terminal credentials", "status": "Bad request - invalid parameters or missing terminal credentials", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Terminal not found - Please activate the terminal first", "status": "Terminal not found - Please activate the terminal first", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Check TIN Authorization Requirement (Malawi MRA)", "description": "Check if a specific TIN requires a purchase authorization code from the Malawi Revenue Authority (MRA).", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/check-tin-authorization-requirement?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "check-tin-authorization-requirement" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"siteId\": \"CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce\",\n \"target_tin\": \"12345678\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Status retrieved successfully", "status": "Status retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"SUCCESS\"\n },\n \"data\": {\n \"tin\": \"12345678\",\n \"tinExists\": true,\n \"requiresAuthorizationCode\": false\n }\n}" }, { "name": "401 - Unauthorized or Session Expired", "status": "Unauthorized or Session Expired", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Terminal not found", "status": "Terminal not found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Check Terminal Unblock Status (Malawi MRA)", "description": "Check if a specific terminal is currently unblocked by the Malawi Revenue Authority (MRA). Uses the stored terminal UUID for the provided siteId.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/check-terminal-unblock-status?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "check-terminal-unblock-status" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"siteId\": \"CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce\",\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Unblock status retrieved successfully", "status": "Unblock status retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Terminal unblock status retrieved successfully\"\n },\n \"data\": {\n \"isUnblocked\": true\n }\n}" }, { "name": "401 - Unauthorized or Session Expired", "status": "Unauthorized or Session Expired", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Terminal not found", "status": "Terminal not found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Get Terminal Blocking Message (Malawi MRA)", "description": "Retrieve detailed information about why a terminal might be blocked by the Malawi Revenue Authority (MRA). Uses the stored terminal UUID for the provided siteId.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/get-terminal-blocking-message?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "get-terminal-blocking-message" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"siteId\": \"CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce\",\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Blocking details retrieved successfully", "status": "Blocking details retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Terminal blocking details retrieved successfully\"\n },\n \"data\": {\n \"isBlocked\": false,\n \"blockingReason\": null,\n \"blockedAt\": \"0001-01-01T00:00:00\"\n }\n}" }, { "name": "401 - Unauthorized or Session Expired", "status": "Unauthorized or Session Expired", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Terminal not found", "status": "Terminal not found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Validate VAT5 Certificate (Malawi MRA)", "description": "Validate a VAT5 certificate with the Malawi Revenue Authority (MRA) EIS system. This check ensures the certificate is valid, matches the project and terminal, and hasn't exceeded its quantity.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/validate-vat5-certificate?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "validate-vat5-certificate" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"siteId\": \"CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce\",\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"projectNumber\": \"PRJ-2024-001\",\n \"certificateNumber\": \"VAT5-987654\",\n \"quantity\": 100\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Certificate validation response from MRA", "status": "Certificate validation response from MRA", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"SUCCESS\"\n },\n \"data\": {\n \"projectNumber\": \"string\",\n \"vat5CertificateNumber\": \"string\",\n \"quantity\": 0,\n \"dateOfIssue\": \"string\",\n \"dateOfExpiry\": \"string\",\n \"isValid\": true\n }\n}" }, { "name": "401 - Unauthorized or Session Expired", "status": "Unauthorized or Session Expired", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "403 - Terminal Blocked", "status": "Terminal Blocked", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Terminal not found", "status": "Terminal not found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] } ] }, { "name": "Malawi MRA Sales Management", "item": [ { "name": "Generate Tax Receipt (Malawi MRA)", "description": "Submit a sales transaction to the Malawi Revenue Authority (MRA) EIS system. This endpoint simplifies the integration process by handling complex tax calculations, invoice numbering, and MRA data formatting automatically.\n\n## \ud83d\ude80 Overview\nThe WEAF MRA API takes away the burden of calculating VAT, taxable amounts, and constructing the complex `invoiceSummary` object. You only need to provide basic transaction details, and our backend handles the rest, ensuring compliance with MRA EIS standards.\n\n## \ud83d\udccb Prerequisites\n- **Valid API Access Token**: Use the Authentication endpoints to obtain one.\n- **TIN Configuration**: Your company TIN must be added and activated in your account.\n- **Terminal Setup**: A terminal must be activated (`terminalId`) to provide the necessary MRA credentials.\n- **Site ID**: The site ID where the transaction originated.\n\n## \ud83d\udcca Global Configuration - Tax Rates\nThe following tax rates are supported by the MRA EIS system and should be used in the `taxRateId` field:\n\n| ID | Tax Rate Name | Rate % | Charge Mode |\n|:---|:---|:---|:---|\n| **A** | Standard Rated | 16.5% | Item |\n| **B** | Zero Rated | 0% | Item |\n| **E** | Exempt | 0% | Item |\n\n## \u26a1 Simplification & Automation\n- **Auto-Calculations**: You don't need to specify `totalVAT`, `taxableAmount`, or construct the `invoiceSummary` object. Our system calculates these based on your line items.\n- **Flexible Discounts**: The `discount` field accepts both absolute amounts (e.g., `100.50`) and percentage strings (e.g., `'10%'`).\n- **VAT-Inclusive Pricing**: Provide the regular shelf price in `unitPrice`. The system automatically back-calculates VAT using the formula: `totalVAT = (total * rate) / (100 + rate)`.\n\n## \ud83d\udee0\ufe0f Business Logic & Validations\n- **Duplicate Prevention**: Requests with the same `referenceNo` and `terminalId` are blocked to prevent duplicate invoice generation.\n- **Terminal Scoping**: Each request is strictly scoped to the provided terminal and site, ensuring data integrity.\n- **Invoice Numbering**: Unique MRA-compliant invoice numbers are generated server-side.\n\n## \u26a0\ufe0f Important Notes* ## \u00e2\u0161\u00a0\u00ef\u00b8\u008f Important Notes\n- **Testing**: Use the `deploymentEnvironment` query parameter (`Sandbox` or `Production`) to switch between MRA instances.\n- **Payload**: Keep your request payload clean; only the simplified fields listed in the request schema are required.\n- **Logging**: All requests and responses are logged for audit and troubleshooting.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/generate-tax-receipt?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "generate-tax-receipt" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"referenceNo\": \"REF-1001\",\n \"invoiceHeader\": {\n \"invoiceDateTime\": \"2026-03-25T19:56:03.000Z\",\n \"sellerTIN\": \"20154457\",\n \"siteId\": \"CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce\",\n \"globalConfigVersion\": 1,\n \"taxpayerConfigVersion\": 1051,\n \"terminalConfigVersion\": 1,\n \"paymentMethod\": \"Cash\",\n \"buyerTIN\": \"12345678\",\n \"buyerName\": \"John Doe\",\n \"buyerAuthorizationCode\": \"AUTH-999\",\n \"isExport\": false,\n \"isReliefSupply\": false,\n \"vat5CertificateDetails\": {\n \"id\": 0,\n \"projectNumber\": \"PRJ-123\",\n \"certificateNumber\": \"CERT-456\",\n \"quantity\": 10\n }\n },\n \"invoiceLineItems\": [\n {\n \"productCode\": \"260306145930\",\n \"description\": \"MDF LAMINATED\",\n \"unitPrice\": 1000,\n \"quantity\": 1,\n \"discount\": \"10%\",\n \"taxRateId\": \"A\",\n \"taxRate\": \"16.5\",\n \"isProduct\": true\n }\n ],\n \"invoiceSummary\": {\n \"offlineSignature\": \"\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Tax receipt generated successfully", "status": "Tax receipt generated successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Generate Tax Receipt DEBUG (Malawi MRA)", "description": "Debug endpoint for generating a tax receipt. Returns the formatted payload that would be sent to the MRA EIS system without actually sending it. Use this to verify your payload structure and calculations before live submission.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/generate-tax-receipt-debug?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "generate-tax-receipt-debug" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"referenceNo\": \"REF-2026-DEBUG-001\",\n \"invoiceHeader\": {\n \"sellerTIN\": \"20154457\",\n \"buyerTIN\": \"12345678\",\n \"buyerName\": \"John Doe\",\n \"isReliefSupply\": false,\n \"vat5CertificateDetails\": {\n \"id\": 1,\n \"projectNumber\": \"PRJ-123\",\n \"certificateNumber\": \"CERT-456\",\n \"quantity\": 10.5\n }\n },\n \"invoiceLineItems\": [\n {\n \"productCode\": \"260306145930\",\n \"description\": \"MDF LAMINATED\",\n \"unitPrice\": 1000,\n \"quantity\": 2,\n \"taxRateId\": \"A\"\n }\n ],\n \"invoiceSummary\": {\n \"offlineSignature\": \"\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Debug payload generated successfully", "status": "Debug payload generated successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"DEBUG: Prepared MRA Payload\"\n },\n \"data\": {\n \"mra_payload\": {}\n }\n}" } ] }, { "name": "Generate Tax Receipt OFFLINE SIMULATION (Malawi MRA)", "description": "Simulates an offline transaction generation. This endpoint computes the required offlineSignature and constructs the local validationURL exactly as a frontend POS should. Use this to verify your local signature implementation.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/generate-tax-receipt-offline?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "generate-tax-receipt-offline" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"referenceNo\": \"REF-1001\",\n \"invoiceHeader\": {\n \"invoiceDateTime\": \"2026-03-25T19:56:03.000Z\",\n \"sellerTIN\": \"20154457\",\n \"siteId\": \"CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce\",\n \"paymentMethod\": \"Cash\",\n \"isExport\": false,\n \"isReliefSupply\": false,\n \"vat5CertificateDetails\": {\n \"id\": 0,\n \"projectNumber\": \"PRJ-123\",\n \"certificateNumber\": \"CERT-456\",\n \"quantity\": 10\n }\n },\n \"invoiceLineItems\": [\n {\n \"productCode\": \"260306145930\",\n \"description\": \"MDF LAMINATED\",\n \"unitPrice\": 1000,\n \"quantity\": 1,\n \"taxRateId\": \"A\",\n \"taxRate\": \"16.5\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Offline payload simulated successfully", "status": "Offline payload simulated successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"OFFLINE SIMULATION: Success\"\n },\n \"data\": {\n \"invoiceNumber\": \"Cs3-B-JY3E-BA\",\n \"offlineSignature\": \"p-Xy...\",\n \"validationURL\": \"https://...\",\n \"mraPayload\": {}\n }\n}" } ] }, { "name": "Query Local Receipts (Malawi MRA)", "description": "Retrieve a list of tax receipts generated for a specific company (TIN) and site, stored in the local database.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/query-local-receipts", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "query-local-receipts" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"siteId\": \"CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce\",\n \"startDate\": \"\",\n \"endDate\": \"\",\n \"status\": \"\",\n \"referenceNo\": \"\",\n \"invoiceNumber\": \"\",\n \"pageSize\": 20,\n \"pageNo\": 1\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - List of receipts", "status": "List of receipts", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "401 - Unauthorized - Authorization header missing or invalid", "status": "Unauthorized - Authorization header missing or invalid", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"02\",\n \"returnMessage\": \"AUTHORIZATION_HEADER_MISSING\"\n },\n \"data\": \"Authorization header is required\"\n}" } ] }, { "name": "Get Last Online Transaction (Malawi MRA)", "description": "Retrieve the last successfully submitted online transaction from the MRA system for a specific terminal. This simplifies reconciliation by confirming what the MRA side has recorded.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/last-online-transaction?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "last-online-transaction" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Last online transaction retrieved successfully", "status": "Last online transaction retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Get Last Offline Transaction (Malawi MRA)", "description": "Retrieve the last successfully submitted offline transaction from the MRA system for a specific terminal.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/last-offline-transaction?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "last-offline-transaction" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Last offline transaction retrieved successfully", "status": "Last offline transaction retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Query Void/Refunded Receipts (Malawi MRA)", "description": "Retrieve a list of voided or refunded tax receipts directly from the Malawi Revenue Authority (MRA) system. This endpoint allows for tracking the status of cancellation requests across different time periods.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/query-void-receipts?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "query-void-receipts" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"invoiceNumber\": \"Cs3-B-JY3E-BA\",\n \"startDate\": \"2026-03-25T00:00:00.000Z\",\n \"endDate\": \"2026-03-27T00:00:00.000Z\",\n \"page\": 1,\n \"pageSize\": 10\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Void receipts retrieved successfully", "status": "Void receipts retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Void requests retrieved successfully\"\n },\n \"data\": {\n \"items\": [\n {\n \"invoiceNumber\": \"Cs3-B-JY3E-BA\",\n \"requestReason\": \"refund\",\n \"issueDate\": \"2026-03-25\",\n \"requestedBy\": \"20154457\",\n \"requestedOn\": \"2026-03-26T14:26:44.95\",\n \"status\": \"Pending\",\n \"approvedOn\": null,\n \"rejectedReason\": null,\n \"referenceNo\": \"REF-1008\"\n }\n ],\n \"page\": 1,\n \"pageSize\": 10,\n \"totalCount\": 1\n },\n \"http_status\": 200\n}" } ] }, { "name": "Cancel Sales Receipt (Void) (Malawi MRA)", "description": "Submit a request to void/cancel an already submitted sales receipt in the MRA EIS system. Requires approval on the MRA side.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/cancel-sales-receipt?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "cancel-sales-receipt" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"invoiceNumber\": \"Cs3-B-JY3E-BA\",\n \"reason\": \"refund\",\n \"referenceNo\": \"REF-1008\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Void request submitted successfully", "status": "Void request submitted successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Query Local Void Requests (Malawi MRA)", "description": "Retrieve a list of void requests stored in our local database for tracking and reconciliation.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/query-local-void-requests", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "query-local-void-requests" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"status\": \"\",\n \"invoiceNumber\": \"\",\n \"referenceNo\": \"\",\n \"pageSize\": 20,\n \"pageNo\": 1\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - List of void requests", "status": "List of void requests", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Validate Buyer Authorization Code (Malawi MRA)", "description": "Validate an authorization code issued by MRA for a specific buyer/reason. This is used when a buyer claims to be purchasing on behalf of an organization or for specific tax-exempt purposes.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/validate-buyer-auth-code?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "validate-buyer-auth-code" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"authorizationCode\": \"070847437E52\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Validation result", "status": "Validation result", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Validation code found\"\n },\n \"data\": {\n \"isValidAuthorizationCode\": true,\n \"authorizationCode\": \"070847437E52\",\n \"authorizationReason\": \"Purchasing on behalf of the organisation\",\n \"generatedBy\": \"20154457-Taxpayer Business\",\n \"generatedOn\": \"2026-03-31T19:49:07.503\",\n \"expiresOn\": \"2026-04-05T19:49:07.503\",\n \"usedOn\": null\n },\n \"http_status\": 200\n}" }, { "name": "400 - Validation error or MRA error", "status": "Validation error or MRA error", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Company or Terminal not found", "status": "Company or Terminal not found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Get Invoice Details By Number (Malawi MRA)", "description": "Retrieve full details of a specific tax receipt from the MRA system using its invoice number. This endpoint returns the complete invoice header, line items, and summary details as recorded by MRA.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/get-invoice-by-number?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "get-invoice-by-number" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"invoiceNumber\": \"Cs3-B-JY3X-B\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Invoice retrieved successfully", "status": "Invoice retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Invoice retrieved successfully.\"\n },\n \"data\": {\n \"dateSubmitted\": \"2026-04-13T08:34:16.57\",\n \"validationURL\": \"https://eservices.mra.mw/doc/v/?vc=96261031813297&c=96354665619a43458b4e011930e5507e\",\n \"invoiceHeader\": {},\n \"invoiceLineItems\": [\n {}\n ],\n \"invoiceSummary\": {}\n },\n \"http_status\": 200\n}" }, { "name": "401 - Unauthorized - Authorization header missing or invalid", "status": "Unauthorized - Authorization header missing or invalid", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Company or Terminal not found", "status": "Company or Terminal not found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Process Credit or Debit Note (Malawi MRA)", "description": "Generate a credit note (if the total is lower) or a debit note (if the total is higher) against an existing invoice. Our system automatically recalculates tax components and simplifies the submission process.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/process-credit-debit-note?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "process-credit-debit-note" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"referenceNo\": \"REF-CD-1002\",\n \"reasonForAdjustment\": \"Return of damaged goods\",\n \"invoiceHeader\": {\n \"invoiceNumber\": \"Cs3-B-JY3X-B\",\n \"invoiceDateTime\": \"2026-04-16T10:22:14.527Z\",\n \"sellerTIN\": \"20154457\",\n \"siteId\": \"CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce\",\n \"paymentMethod\": \"Cash\",\n \"isExport\": false,\n \"isReliefSupply\": false,\n \"vat5CertificateDetails\": {\n \"id\": 0,\n \"projectNumber\": \"PRJ-123\",\n \"certificateNumber\": \"CERT-456\",\n \"quantity\": 10\n }\n },\n \"invoiceLineItems\": [\n {\n \"productCode\": \"260306145930\",\n \"description\": \"MDF LAMINATED\",\n \"unitPrice\": 1000,\n \"quantity\": 1,\n \"discount\": \"0\",\n \"taxRateId\": \"A\",\n \"isProduct\": true\n }\n ],\n \"invoiceSummary\": {\n \"offlineSignature\": \"\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Note processed successfully", "status": "Note processed successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Processed successfully\"\n },\n \"data\": {},\n \"http_status\": 200\n}" }, { "name": "400 - MRA Processing Error (e.g., Original invoice not found)", "status": "MRA Processing Error (e.g., Original invoice not found)", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "401 - Unauthorized - Terminal session expired", "status": "Unauthorized - Terminal session expired", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Process Credit/Debit Note DEBUG (Malawi MRA)", "description": "Debug endpoint for processing a credit or debit note. Returns the formatted payload that would be sent to the MRA EIS system without actually sending it.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/process-credit-debit-note-debug?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "process-credit-debit-note-debug" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"referenceNo\": \"REF-ADJ-001\",\n \"reasonForAdjustment\": \"Return of goods\",\n \"invoiceHeader\": {\n \"invoiceNumber\": \"Cs3-B-JY3E-BA\",\n \"sellerTIN\": \"20154457\",\n \"isReliefSupply\": false\n },\n \"invoiceLineItems\": [\n {\n \"productCode\": \"260306145930\",\n \"description\": \"MDF LAMINATED\",\n \"unitPrice\": 1000,\n \"quantity\": 1,\n \"taxRateId\": \"A\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Debug payload generated successfully", "status": "Debug payload generated successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"DEBUG: Prepared MRA Payload for Credit/Debit Note\"\n },\n \"data\": {}\n}" } ] } ] }, { "name": "Malawi MRA Stock Management", "item": [ { "name": "Get stock adjustment reasons (Malawi MRA)", "description": "Retrieve available stock adjustment reasons from Malawi Revenue Authority (MRA) EIS system. These reasons are used when adjusting inventory quantities.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/stock-adjustment-reasons?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "stock-adjustment-reasons" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Stock adjustment reasons retrieved successfully", "status": "Stock adjustment reasons retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Adjustment reasons retrieved successfully\"\n },\n \"data\": [\n {\n \"description\": \"Theft\"\n }\n ]\n}" }, { "name": "400 - Bad request - invalid parameters or missing terminal", "status": "Bad request - invalid parameters or missing terminal", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Terminal not found - Please activate the terminal first", "status": "Terminal not found - Please activate the terminal first", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "403 - Forbidden - Company inactive, license expired, or environment mismatch", "status": "Forbidden - Company inactive, license expired, or environment mismatch", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Get suppliers (Malawi MRA)", "description": "Retrieve available suppliers from Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal and valid JWT token.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/get-suppliers?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "get-suppliers" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Suppliers retrieved successfully", "status": "Suppliers retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Suppliers retrieved successfully\"\n },\n \"data\": [\n {\n \"supplierId\": 346,\n \"supplierName\": \"Raiply\",\n \"supplierContactEmail\": null,\n \"supplierContactPhone\": \"022222222\",\n \"supplierTin\": \"20154457\"\n }\n ],\n \"http_status\": 200\n}" }, { "name": "400 - Bad request - invalid parameters or missing terminal", "status": "Bad request - invalid parameters or missing terminal", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Terminal not found - Please activate the terminal first", "status": "Terminal not found - Please activate the terminal first", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "403 - Forbidden - Company inactive, license expired, or environment mismatch", "status": "Forbidden - Company inactive, license expired, or environment mismatch", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Get units of measure (Malawi MRA)", "description": "Retrieve available units of measure from Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal and valid JWT token.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/get-units-of-measure?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "get-units-of-measure" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Units of measure retrieved successfully", "status": "Units of measure retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Units of measure retrieved successfully\"\n },\n \"data\": [\n {\n \"unitOfMeasure\": \"Piece\",\n \"unitOfMeasureDescription\": \"Piece\"\n }\n ],\n \"http_status\": 200\n}" }, { "name": "400 - Bad request - invalid parameters or missing terminal", "status": "Bad request - invalid parameters or missing terminal", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Terminal not found - Please activate the terminal first", "status": "Terminal not found - Please activate the terminal first", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "403 - Forbidden - Company inactive, license expired, or environment mismatch", "status": "Forbidden - Company inactive, license expired, or environment mismatch", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Get HS codes (Malawi MRA)", "description": "Retrieve available Harmonized System (HS) codes from Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal and valid JWT token.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/get-hs-codes?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "get-hs-codes" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - HS codes retrieved successfully", "status": "HS codes retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"HS codes retrieved successfully\"\n },\n \"data\": [\n {\n \"code\": \"01012100\",\n \"description\": \"Pure-bred breeding horses\",\n \"taxRateId\": \"1\"\n }\n ],\n \"http_status\": 200\n}" }, { "name": "400 - Bad request - invalid parameters or missing terminal", "status": "Bad request - invalid parameters or missing terminal", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Terminal not found - Please activate the terminal first", "status": "Terminal not found - Please activate the terminal first", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "403 - Forbidden - Company inactive, license expired, or environment mismatch", "status": "Forbidden - Company inactive, license expired, or environment mismatch", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Add a new product (Malawi MRA)", "description": "Add a new product to master products and create zero-quantity warehouse inventory for the taxpayer on the Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal and valid JWT token.

Sample HS Codes:
HS CodeDescriptionTax Rate
94061010GREEN HOUSES OF WOODE
94061090OTHER PREFABRICATED BUILDINGSE
94062000MODULAR BUILDING UNITS, OF STEELA
94069000OTHER PREFABRICATED BUILDINGSA

Sample UOM Codes:
UOMDescription
DRDrum
%Percentage
%OPer mille
DDay
", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/add-product?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "add-product" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"barcode\": \"260306145930\",\n \"hsCode\": \"94062000\",\n \"name\": \"Breeding Horse Premium\",\n \"description\": \"Premium breeding horses from local farm\",\n \"uom\": \"DR\",\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Product added successfully", "status": "Product added successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Product added successfully\"\n },\n \"data\": {\n \"productId\": 12345,\n \"barcode\": \"260306145930\",\n \"hsCode\": \"01012100\",\n \"taxRateId\": \"1\",\n \"name\": \"Breeding Horse Premium\",\n \"description\": \"Premium breeding horses from local farm\",\n \"uom\": \"Piece\"\n },\n \"http_status\": 200\n}" }, { "name": "400 - Bad request - invalid parameters or validation errors", "status": "Bad request - invalid parameters or validation errors", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Terminal not found - Please activate the terminal first", "status": "Terminal not found - Please activate the terminal first", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "403 - Forbidden - Company inactive, license expired, or environment mismatch", "status": "Forbidden - Company inactive, license expired, or environment mismatch", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Submit Stock Adjustment (Malawi MRA)", "description": "Submit a stock adjustment request to the Malawi Revenue Authority (MRA) EIS system. Use this for adjustments like Theft, Damage, Loss, etc. Requires an activated terminal and valid JWT token.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/stock-adjustment?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "stock-adjustment" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"purchaseOrderNumber\": \"PO-ADJ-001\",\n \"barcode\": \"260306145930\",\n \"quantity\": 1,\n \"adjustmentReason\": \"Theft\",\n \"adjustmentType\": \"Decrease\",\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"siteId\": \"CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce\",\n \"taxpayerRemarks\": \"Inventory audit adjustment\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Stock adjustment submitted successfully", "status": "Stock adjustment submitted successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "400 - Bad request - invalid parameters", "status": "Bad request - invalid parameters", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Stock Adjustment DEBUG (Malawi MRA)", "description": "Debug endpoint for stock adjustment. Returns the formatted payload that would be sent to the MRA EIS system without actually sending it.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/stock-adjustment-debug?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "stock-adjustment-debug" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"purchaseOrderNumber\": \"PO-DEBUG-001\",\n \"barcode\": \"260306145930\",\n \"quantity\": 10,\n \"adjustmentReason\": \"Damaged goods\",\n \"adjustmentType\": \"Decrease\",\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"siteId\": \"CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce\",\n \"taxpayerRemarks\": \"Debug simulation\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Debug payload generated successfully", "status": "Debug payload generated successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"DEBUG: Prepared MRA Stock Adjustment Payload\"\n },\n \"data\": {}\n}" } ] }, { "name": "Submit Informal Purchase (Malawi MRA)", "description": "Submit an informal purchase request to the Malawi Revenue Authority (MRA) EIS system. This is typically used to increase stock from non-VAT registered suppliers. Requires an activated terminal and valid JWT token.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/increase-descrease-stock-request?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "increase-descrease-stock-request" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"supplierId\": 346,\n \"deliveryNoteNumber\": \"DN-2026-001\",\n \"receivingDate\": \"2026-03-26T10:00:00.000Z\",\n \"purchaseOrderNumber\": \"PO-2026-001\",\n \"receivedBy\": \"John Doe\",\n \"totalItems\": 1,\n \"totalQuantity\": 50,\n \"totalValue\": 500000,\n \"notes\": \"Informal timber purchase\",\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"items\": [\n {\n \"itemCode\": \"260306145930\",\n \"description\": \"MDF LAMINATED\",\n \"quantityOrdered\": 50,\n \"quantityReceived\": 50,\n \"unitOfMeasure\": \"Piece\",\n \"unitPrice\": 10000,\n \"totalPrice\": 500000,\n \"isFinishedProduct\": true\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Informal purchase submitted successfully", "status": "Informal purchase submitted successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Query Stock Adjustments (Malawi MRA)", "description": "Retrieve a list of stock adjustments stored in the local database.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/query-stock-adjustments", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "query-stock-adjustments" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"purchaseOrderNumber\": \"\",\n \"status\": \"\",\n \"pageSize\": 20,\n \"pageNo\": 1\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - List of stock adjustments", "status": "List of stock adjustments", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Check Product Status (Malawi MRA)", "description": "Retrieve detailed stock information, tax rates, and descriptions for a specific product directly from the MRA system.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/check-product-status?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "check-product-status" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"productId\": \"260306145930\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Product status retrieved successfully", "status": "Product status retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Stock Transfer (Malawi MRA)", "description": "Transfer inventory from warehouse to site or between sites. Requires an activated terminal and valid JWT token.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/stock-transfer?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "stock-transfer" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"fromWarehouseToSite\": true,\n \"fromSiteId\": \"warehouse-001\",\n \"toSiteId\": \"CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce\",\n \"items\": [\n {\n \"barcode\": \"260306145930\",\n \"quantity\": 10,\n \"price\": 1000\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Stock transfer processed successfully", "status": "Stock transfer processed successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Stock transfer processed successfully\"\n },\n \"data\": {},\n \"http_status\": 200\n}" }, { "name": "400 - Bad request - invalid parameters", "status": "Bad request - invalid parameters", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "403 - Forbidden - Company error or environment mismatch", "status": "Forbidden - Company error or environment mismatch", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Not Found - Terminal or company not found", "status": "Not Found - Terminal or company not found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Get Raw Materials (Malawi MRA)", "description": "Retrieve a paginated list of raw materials from the Malawi Revenue Authority (MRA) EIS system. This refers to goods that are used as inputs for production processes.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/get-raw-materials?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "get-raw-materials" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"page\": 1,\n \"pageSize\": 50\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Raw materials retrieved successfully", "status": "Raw materials retrieved successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"SUCCESS\"\n },\n \"data\": [\n {}\n ],\n \"http_status\": 200\n}" }, { "name": "401 - Unauthorized - Session expired", "status": "Unauthorized - Session expired", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Company or Terminal not found", "status": "Company or Terminal not found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Submit Raw Material Conversion (Malawi MRA)", "description": "Submit a production conversion request to the Malawi Revenue Authority (MRA) EIS system. This endpoint records the processing of raw materials into finished goods, ensuring inventory levels are adjusted accordingly for both input and output products.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/submit-raw-material-conversion?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "submit-raw-material-conversion" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\",\n \"productionBatchId\": \"BATCH-2026-001\",\n \"productionDate\": \"2026-04-16T09:52:52.772Z\",\n \"rawMaterials\": [\n {\n \"productId\": \"RM-001\",\n \"productName\": \"Timber Log\",\n \"availableQuantity\": 10.5,\n \"usedQuantity\": 2\n }\n ],\n \"finishedProducts\": [\n {\n \"quantity\": 5,\n \"unitOfMeasure\": \"Piece\",\n \"expiryDate\": \"2027-04-16T09:52:52.772Z\",\n \"productDescription\": \"MDF Board\",\n \"barcode\": \"260306145930\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Conversion submitted successfully", "status": "Conversion submitted successfully", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Raw material conversion submitted successfully\"\n },\n \"data\": {},\n \"http_status\": 200\n}" }, { "name": "400 - MRA Validation Error or Processing Error", "status": "MRA Validation Error or Processing Error", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"01\",\n \"returnMessage\": \"Raw material string not found in warehouse\"\n },\n \"data\": {\n \"mra_status_code\": -2,\n \"errors\": {\n \"FinishedProducts[0].Quantity\": [\n \"Quantity must be greater than 0\"\n ]\n }\n },\n \"http_status\": 400\n}" }, { "name": "401 - Unauthorized - Terminal session expired", "status": "Unauthorized - Terminal session expired", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" }, { "name": "404 - Company or Terminal not found", "status": "Company or Terminal not found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "" } ] }, { "name": "Ping MRA Server (Malawi MRA)", "description": "Check the connectivity between the WEAF system and the Malawi Revenue Authority (MRA) EIS system. This endpoint verifies that the terminal is correctly activated and the JWT token is valid for the selected environment.", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/api/v1/{{tin}}/ping-server?deploymentEnvironment=%7B%7BdeploymentEnvironment%7D%7D", "host": [ "{{base_url}}" ], "path": [ "api", "v1", "{{tin}}", "ping-server" ], "query": [ { "key": "deploymentEnvironment", "value": "{{deploymentEnvironment}}", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_token}}", "type": "string" } ] }, "body": { "mode": "raw", "raw": "{\n \"terminalId\": \"193760fb-cddc-40ed-b0fb-f08f8720f86c\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 - Ping successful", "status": "Ping successful", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": {\n \"returnCode\": \"00\",\n \"returnMessage\": \"Pong\"\n },\n \"data\": {}\n}" } ] } ] } ], "variable": [ { "key": "base_url", "value": "http://localhost:8000", "type": "string" }, { "key": "api_token", "value": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "type": "string" }, { "key": "tin", "value": "20154457", "type": "string" }, { "key": "deploymentEnvironment", "value": "Sandbox", "type": "string" }, { "key": "isMalawi", "value": true, "type": "string" } ] }