{ "openapi": "3.0.0", "info": { "title": "WEAF Company Malawi 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โ€”just follow a few simple steps to get started:\r\n * \r\n * ## ๐Ÿš€ 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 * ## ๐Ÿ” 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 **๐Ÿ”‘ 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 ๐Ÿ”’ next to endpoints that require authentication\r\n * \r\n * ### ๐Ÿ”„ 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", "contact": { "name": "WEAF Company Malawi Support", "email": "services@weafcompany.com" }, "version": "1.0.0" }, "servers": [ { "url": "http://localhost:8000", "description": "Local Development Server" }, { "url": "https://weafcompany.com", "description": "Production Server" } ], "paths": { "/api/v1/auth/generate-token": { "post": { "tags": [ "Authentication" ], "summary": "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.", "operationId": "987b6c041f2d3914c91bc47672700122", "requestBody": { "description": "User credentials and token configuration parameters", "required": true, "content": { "application/json": { "schema": { "required": [ "username", "password", "expiry_days", "token_name" ], "properties": { "username": { "description": "User's email address used for authentication. Must be a valid email format and correspond to an existing user account in the system.", "type": "string", "format": "email", "example": "user@example.com" }, "password": { "description": "User's account password. Must be at least 6 characters long and match the user's stored password hash.", "type": "string", "format": "password", "example": "SecurePassword123!" }, "expiry_days": { "description": "Number of days until the token expires. Must be between 1 and 365 days. Recommended: 30 days for optimal security. Longer periods increase security risk.", "type": "integer", "maximum": 365, "minimum": 1, "example": 30 }, "token_name": { "description": "Human-readable name for the token to help identify its purpose, usage, or associated application. Maximum 255 characters. Useful for token management and security auditing.", "type": "string", "maxLength": 255, "example": "Mobile App Integration" }, "tin": { "description": "Optional TIN to restrict the token to a single company. If not provided, the token will have access to all companies associated with the user.", "type": "string", "maxLength": 20, "example": null, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Token generated successfully - Authentication successful", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Response status information indicating successful operation", "properties": { "returnCode": { "description": "Success code indicating the authentication and token generation completed successfully", "type": "string", "example": "00" }, "returnMessage": { "description": "Human-readable success message confirming token generation", "type": "string", "example": "SUCCESS" } }, "type": "object" }, "data": { "description": "Token information, user details, and associated company data", "properties": { "token": { "description": "64-character hexadecimal access token. Use this token in the 'Authorization' header for subsequent API requests in the format: 'Bearer {token}'", "type": "string", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4" }, "token_name": { "description": "The descriptive name assigned to this token during creation for identification and management purposes", "type": "string", "example": "Mobile App Integration" }, "expires_at": { "description": "ISO 8601 formatted timestamp indicating when the token will expire. After this time, the token becomes invalid and a new one must be generated.", "type": "string", "format": "date-time", "example": "2024-11-30T10:30:00.000000Z" }, "expires_in_days": { "description": "Number of days remaining until token expiration, calculated from the current date", "type": "integer", "example": 30 }, "user": { "description": "Authenticated user information", "properties": { "id": { "description": "Unique identifier of the authenticated user", "type": "integer", "example": 1 }, "name": { "description": "Full name of the authenticated user", "type": "string", "example": "John Doe" }, "email": { "description": "Email address of the authenticated user (same as the username used for login)", "type": "string", "example": "user@example.com" }, "companies_count": { "description": "Total number of companies associated with this user account", "type": "integer", "example": 2 } }, "type": "object" }, "companies": { "description": "List of companies associated with the authenticated user", "type": "array", "items": { "properties": { "id": { "description": "Unique identifier of the company", "type": "integer", "example": 1 }, "business_name": { "description": "Official business name of the company", "type": "string", "example": "ABC Company Ltd" }, "tin": { "description": "Tax Identification Number (TIN) of the company", "type": "string", "example": "1000251604" }, "environment": { "description": "Environment type: 'production' for live operations, 'sandbox' for testing", "type": "string", "enum": [ "production", "sandbox" ], "example": "production" } }, "type": "object" } }, "usage_info": { "description": "Token usage statistics and metadata", "properties": { "total_requests": { "description": "Total number of API requests made using this token (initially 0 for new tokens)", "type": "integer", "example": 0 }, "last_used": { "description": "ISO 8601 formatted timestamp of the last API request using this token (null for new tokens)", "type": "string", "example": null, "nullable": true }, "created_at": { "description": "ISO 8601 formatted timestamp indicating when the token was created", "type": "string", "format": "date-time", "example": "2024-10-30T10:30:00.000000Z" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation Error - Invalid request data", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Error status information", "properties": { "returnCode": { "description": "Validation error code indicating request data validation failed", "type": "string", "example": "01" }, "returnMessage": { "description": "Indicates that the request data failed validation rules", "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" }, "data": { "description": "Validation error details with field-specific messages", "properties": { "errors": { "description": "Object containing field-specific validation error messages. Each field that failed validation will have an array of error messages.", "type": "object", "example": { "username": [ "The username field is required." ], "password": [ "The password must be at least 6 characters." ], "expiry_days": [ "The expiry days must be between 1 and 365." ], "token_name": [ "The token name field is required." ] } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Authentication Failed - Invalid credentials", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Authentication error status", "properties": { "returnCode": { "description": "Authentication error code indicating credential validation failed", "type": "string", "example": "02" }, "returnMessage": { "description": "Specific authentication error: 'USER_NOT_FOUND' when the email address doesn't exist in the system, 'INVALID_PASSWORD' when the email exists but the password is incorrect", "type": "string", "enum": [ "USER_NOT_FOUND", "INVALID_PASSWORD" ], "example": "USER_NOT_FOUND" } }, "type": "object" }, "data": { "description": "No additional data provided for authentication errors to maintain security", "type": "object", "nullable": true } }, "type": "object" } } } }, "403": { "description": "Access Forbidden - User account restrictions", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Access forbidden status", "properties": { "returnCode": { "description": "Access forbidden error code indicating user account restrictions", "type": "string", "example": "03" }, "returnMessage": { "description": "Specific access restriction: 'NO_COMPANIES_FOUND' when user has no associated companies, 'ACCOUNT_SUSPENDED' when account is suspended, 'ACCOUNT_INACTIVE' when account is inactive", "type": "string", "enum": [ "NO_COMPANIES_FOUND", "ACCOUNT_SUSPENDED", "ACCOUNT_INACTIVE" ], "example": "NO_COMPANIES_FOUND" } }, "type": "object" }, "data": { "description": "Additional information about the access restriction", "properties": { "message": { "description": "Human-readable explanation of why access was denied", "type": "string", "example": "User has no companies associated with their account" } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error - System error occurred", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Server error status", "properties": { "returnCode": { "description": "Internal server error code indicating an unexpected system error", "type": "string", "example": "99" }, "returnMessage": { "description": "Indicates an unexpected system error occurred during token generation", "type": "string", "example": "INTERNAL_SERVER_ERROR" } }, "type": "object" }, "data": { "description": "Error details (only in development environment)", "properties": { "message": { "description": "Detailed error message (only shown in development environment for debugging purposes)", "type": "string", "example": "An unexpected error occurred while generating the token" } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/v1/auth/validate-token": { "post": { "tags": [ "Authentication" ], "summary": "Validate access token", "description": "Validate an existing access token and get user/company information", "operationId": "a8173d93bfdaa3f77af8422f39c02684", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "token" ], "properties": { "token": { "description": "64-character access token", "type": "string", "maxLength": 64, "minLength": 64, "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4" } }, "type": "object" } } } }, "responses": { "200": { "description": "Token is valid", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } }, "type": "object" }, "data": { "properties": { "token_valid": { "type": "boolean", "example": true }, "token_name": { "type": "string", "example": "My API Token" }, "expires_at": { "type": "string", "format": "date-time", "example": "2024-11-30T10:30:00.000000Z" }, "user": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "user@example.com" } }, "type": "object" }, "companies": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "business_name": { "type": "string", "example": "ABC Company Ltd" }, "tin": { "type": "string", "example": "1000251604" }, "environment": { "type": "string", "example": "production" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "01" }, "returnMessage": { "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" }, "data": { "properties": { "errors": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "04" }, "returnMessage": { "type": "string", "example": "INVALID_OR_EXPIRED_TOKEN" } }, "type": "object" }, "data": { "type": "string", "example": null, "nullable": true } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "99" }, "returnMessage": { "type": "string", "example": "INTERNAL_SERVER_ERROR" } }, "type": "object" }, "data": { "properties": { "message": { "type": "string", "example": "An unexpected error occurred while validating the token" } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/v1/auth/refresh-token": { "post": { "tags": [ "Authentication" ], "summary": "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", "operationId": "e7effffad81d43535c7bad0b99aac84e", "requestBody": { "description": "Token refresh parameters", "required": true, "content": { "application/json": { "schema": { "required": [ "expiry_days", "token_name" ], "properties": { "expiry_days": { "description": "Number of days until the new token expires. Must be between 1 and 365 days. Recommended: 60-90 days for refreshed tokens.", "type": "integer", "maximum": 365, "minimum": 1, "example": 60 }, "token_name": { "description": "New descriptive name for the refreshed token. Maximum 255 characters. This helps identify the refreshed token in your token management.", "type": "string", "maxLength": 255, "example": "Refreshed Mobile App Token" } }, "type": "object" } } } }, "responses": { "200": { "description": "Token refreshed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Response status information", "properties": { "returnCode": { "description": "Success code indicating the token refresh completed successfully", "type": "string", "example": "00" }, "returnMessage": { "description": "Success message confirming token refresh", "type": "string", "example": "TOKEN_REFRESHED_SUCCESSFULLY" } }, "type": "object" }, "data": { "description": "New token information and metadata", "properties": { "new_token": { "description": "New 64-character hexadecimal access token. Use this token in the 'Authorization' header for subsequent API requests.", "type": "string", "example": "b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4" }, "old_token": { "description": "The previous token that has been invalidated and should no longer be used", "type": "string", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4" }, "token_name": { "description": "The new name assigned to the refreshed token", "type": "string", "example": "Refreshed Mobile App Token" }, "expires_at": { "description": "ISO 8601 formatted timestamp indicating when the new token will expire", "type": "string", "format": "date-time", "example": "2024-12-30T10:30:00.000000Z" }, "expires_in_days": { "description": "Number of days remaining until the new token expires", "type": "integer", "example": 60 }, "user": { "description": "Authenticated user information", "properties": { "id": { "description": "Unique identifier of the user", "type": "integer", "example": 1 }, "name": { "description": "Full name of the user", "type": "string", "example": "John Doe" }, "email": { "description": "Email address of the user", "type": "string", "example": "user@example.com" } }, "type": "object" }, "companies": { "description": "List of companies associated with the user", "type": "array", "items": { "properties": { "id": { "description": "Unique identifier of the company", "type": "integer", "example": 1 }, "business_name": { "description": "Official business name of the company", "type": "string", "example": "ABC Company Ltd" }, "tin": { "description": "Tax Identification Number (TIN) of the company", "type": "string", "example": "1000251604" } }, "type": "object" } }, "refresh_info": { "description": "Information about the token refresh operation", "properties": { "refreshed_at": { "description": "ISO 8601 formatted timestamp indicating when the token was refreshed", "type": "string", "format": "date-time", "example": "2024-10-30T10:30:00.000000Z" }, "old_token_expired_at": { "description": "ISO 8601 formatted timestamp indicating when the old token was originally set to expire", "type": "string", "format": "date-time", "example": "2024-11-30T10:30:00.000000Z" }, "extension_days": { "description": "Number of additional days added to the token expiration", "type": "integer", "example": 30 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation Error - Invalid request data", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Error status information", "properties": { "returnCode": { "description": "Validation error code", "type": "string", "example": "01" }, "returnMessage": { "description": "Indicates that the request data failed validation", "type": "string", "example": "VALIDATION_ERROR" } }, "type": "object" }, "data": { "description": "Validation error details", "properties": { "errors": { "description": "Object containing field-specific validation error messages", "type": "object", "example": { "expiry_days": [ "The expiry days must be between 1 and 365." ], "token_name": [ "The token name field is required." ] } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Authentication Failed - Invalid or expired token", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Authentication error status", "properties": { "returnCode": { "description": "Authentication error code", "type": "string", "example": "02" }, "returnMessage": { "description": "Specific authentication error: 'INVALID_TOKEN' when token format is invalid, 'TOKEN_EXPIRED' when token has expired, 'TOKEN_NOT_FOUND' when token doesn't exist", "type": "string", "enum": [ "INVALID_TOKEN", "TOKEN_EXPIRED", "TOKEN_NOT_FOUND" ], "example": "INVALID_TOKEN" } }, "type": "object" }, "data": { "description": "No additional data provided for authentication errors", "type": "object", "nullable": true } }, "type": "object" } } } }, "403": { "description": "Access Forbidden - Token refresh not allowed", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Access forbidden status", "properties": { "returnCode": { "description": "Access forbidden error code", "type": "string", "example": "03" }, "returnMessage": { "description": "Indicates that token refresh is not allowed for this user or token", "type": "string", "example": "TOKEN_REFRESH_DISABLED" } }, "type": "object" }, "data": { "description": "No additional data provided for access forbidden errors", "type": "object", "nullable": true } }, "type": "object" } } } }, "500": { "description": "Internal Server Error - System error occurred", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Server error status", "properties": { "returnCode": { "description": "Internal server error code", "type": "string", "example": "99" }, "returnMessage": { "description": "Indicates an unexpected system error occurred during token refresh", "type": "string", "example": "INTERNAL_SERVER_ERROR" } }, "type": "object" }, "data": { "description": "Error details (only in development environment)", "properties": { "message": { "description": "Detailed error message (only shown in development environment)", "type": "string", "example": "An unexpected error occurred while refreshing the token" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/sync-latest-configurations": { "post": { "tags": [ "Malawi MRA Configuration" ], "summary": "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.", "operationId": "f78aefa4e2e1ac0c09a61925263dd6af", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' for testing or 'Production' for live", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId" ], "properties": { "terminalId": { "description": "Terminal ID from activation (used to fetch JWT token)", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" } }, "type": "object" } } } }, "responses": { "200": { "description": "Configurations synced successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Retrieved latest configurations" } }, "type": "object" }, "data": { "properties": { "globalConfiguration": { "type": "object" }, "terminalConfiguration": { "type": "object" }, "taxpayerConfiguration": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request - invalid parameters or missing terminal" }, "404": { "description": "Terminal not found - Please activate the terminal first" }, "403": { "description": "Forbidden - Company inactive, license expired, or environment mismatch" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/activate-terminal": { "post": { "tags": [ "Malawi MRA Onboarding" ], "summary": "Activate terminal (Malawi MRA)", "description": "Activate a new terminal with Malawi Revenue Authority (MRA) EIS system. Returns JWT tokens and security configurations on success.", "operationId": "3a520f0287c8252e3116cabcce27904f", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - determines which API endpoint to use. Must be either 'Sandbox' for testing or 'Production' for live transactions.", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalActivationCode", "platformInfo" ], "properties": { "terminalActivationCode": { "description": "Activation code provided by MRA", "type": "string", "example": "816Q-3VZP-6ZZY-K9Y5" }, "platformInfo": { "required": [ "platform", "pos" ], "properties": { "platform": { "properties": { "osName": { "type": "string", "example": "Microsoft Windows 10 Pro" }, "osVersion": { "type": "string", "example": "10.0.19045" }, "osBuild": { "type": "string", "example": "19045" }, "macAddress": { "type": "string", "example": "2E-CF-D9-E8-84-EE" } }, "type": "object" }, "pos": { "properties": { "productID": { "type": "string", "example": "sera" }, "productVersion": { "type": "string", "example": "v3.0" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Terminal activated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } }, "type": "object" }, "data": { "properties": { "message": { "type": "string", "example": "Terminal Activated successfully" }, "terminal": { "properties": { "terminalId": { "type": "string", "example": "uuid-string" }, "status": { "type": "string", "example": "activated" }, "activationDate": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Activation failed", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "01" }, "returnMessage": { "type": "string", "example": "Terminal already activated" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" }, "403": { "description": "Forbidden - Company mismatch or account inactive" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/confirm-terminal-activation": { "post": { "tags": [ "Malawi MRA Onboarding" ], "summary": "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.", "operationId": "b7ca17498757a4e903e293267c5353a9", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - determines which API endpoint to use. Must be either 'Sandbox' for testing or 'Production' for live transactions.", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId" ], "properties": { "terminalId": { "description": "Terminal ID to confirm", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" } }, "type": "object" } } } }, "responses": { "200": { "description": "Terminal confirmation successful", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } }, "type": "object" }, "data": { "properties": { "message": { "type": "string", "example": "Terminal is now fully activated and ready for use!" }, "confirmed": { "type": "boolean", "example": true } }, "type": "object" }, "http_status": { "type": "integer", "example": 200 } }, "type": "object" } } } }, "400": { "description": "Confirmation failed" }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" }, "403": { "description": "Forbidden - Company mismatch or account inactive" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/terminals": { "get": { "tags": [ "Malawi MRA Onboarding" ], "summary": "Get configured terminals (Malawi MRA)", "description": "Retrieve all configured and activated terminals for a given TIN from the WEAF backend database.", "operationId": "017613d05ff4004a7c663be3cf74ff65", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "responses": { "200": { "description": "Terminals retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } }, "type": "object" }, "data": { "type": "array", "items": { "properties": { "terminal_id": { "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "terminal_label": { "type": "string", "example": "Main Till" }, "terminal_position": { "type": "string", "example": "1" }, "status": { "type": "string", "example": "activated" }, "jwt_token": { "type": "string", "example": "eyJhbGciOiJIUzUxMiJ9..." }, "secret_key": { "type": "string", "example": "..." }, "site_id": { "type": "string", "example": "..." }, "site_name": { "type": "string", "example": "..." }, "activation_date": { "type": "string", "format": "date-time" } }, "type": "object" } }, "http_status": { "type": "integer", "example": 200 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" }, "403": { "description": "Forbidden - Company mismatch or account inactive" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/get-site-terminal-products": { "post": { "tags": [ "Malawi MRA Utilities" ], "summary": "Get terminal site products (Malawi MRA)", "description": "Retrieve products and services for a specific terminal site from Malawi Revenue Authority (MRA) EIS system.", "operationId": "d57771d05f8069576d0f4772548792d5", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' for testing or 'Production' for live", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "siteId", "terminalId" ], "properties": { "siteId": { "description": "Site ID from terminal configuration", "type": "string", "example": "CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce" }, "terminalId": { "description": "Terminal ID from activation", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" } }, "type": "object" } } } }, "responses": { "200": { "description": "Products retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Products and services retrieved successfully." } }, "type": "object" }, "data": { "type": "array", "items": { "properties": { "productCode": { "type": "string" }, "productName": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "number" }, "unitOfMeasure": { "type": "string" }, "price": { "type": "number" }, "siteId": { "type": "string" }, "productExpiryDate": { "type": "string" }, "minimumStockLevel": { "type": "number" }, "taxRateId": { "type": "string" }, "isProduct": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Bad request - invalid parameters" }, "404": { "description": "Terminal not found or not activated" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/get-warehouse-products": { "post": { "tags": [ "Malawi MRA Utilities" ], "summary": "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.", "operationId": "d5310c902693864bc93122f3428e872c", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' for testing or 'Production' for live", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId" ], "properties": { "terminalId": { "description": "Terminal ID from activation", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "page": { "description": "Page number for pagination", "type": "integer", "default": 1, "example": 1 }, "pageSize": { "description": "Number of items per page", "type": "integer", "default": 50, "example": 50 } }, "type": "object" } } } }, "responses": { "200": { "description": "Warehouse products retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Warehouse inventory retrieved successfully" } }, "type": "object" }, "data": { "properties": { "stocks": { "type": "array", "items": { "properties": { "barcode": { "type": "string" }, "productName": { "type": "string" }, "productDescription": { "type": "string" }, "currentQuantity": { "type": "number" }, "uom": { "type": "string" }, "price": { "type": "number" } }, "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request - invalid parameters or missing terminal credentials" }, "404": { "description": "Terminal not found - Please activate the terminal first" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/request-new-terminal-token": { "post": { "tags": [ "Malawi MRA Onboarding" ], "summary": "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.", "operationId": "a4bb52743515b7a6fb83454f237398cf", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' or 'Production'", "required": false, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "siteId" ], "properties": { "siteId": { "description": "The site ID of the terminal to refresh tokens for", "type": "string", "example": "CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce" } }, "type": "object" } } } }, "responses": { "200": { "description": "Terminal tokens retrieved and updated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Latest terminal token retrieved successfully" } }, "type": "object" }, "data": { "properties": { "secretKey": { "type": "string", "example": "719c248c608abd142e359c444c413441eb58e0b" }, "jwtToken": { "type": "string", "example": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..." } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Failed to retrieve tokens or missing required fields", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "01" }, "returnMessage": { "type": "string", "example": "siteId is required in request body" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "MRA Session Expired: You are not authorised." }, "404": { "description": "Company or Terminal not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/check-tin-authorization-requirement": { "post": { "tags": [ "Malawi MRA Utilities" ], "summary": "Check TIN Authorization Requirement (Malawi MRA)", "description": "Check if a specific TIN requires a purchase authorization code from the Malawi Revenue Authority (MRA).", "operationId": "46a60243932032c01370a6c7fcf98188", "parameters": [ { "name": "tin", "in": "path", "description": "Sellers's TIN (the authenticated company)", "required": true, "schema": { "type": "string", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA environment (Sandbox or Production)", "required": false, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ] } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "siteId", "target_tin" ], "properties": { "siteId": { "description": "Site ID of the terminal to use for authorization", "type": "string", "example": "CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce" }, "target_tin": { "description": "The TIN to check for authorization requirement", "type": "string", "example": "12345678" } }, "type": "object" } } } }, "responses": { "200": { "description": "Status retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } }, "type": "object" }, "data": { "properties": { "tin": { "type": "string", "example": "12345678" }, "tinExists": { "type": "boolean", "example": true }, "requiresAuthorizationCode": { "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized or Session Expired" }, "404": { "description": "Terminal not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/check-terminal-unblock-status": { "post": { "tags": [ "Malawi MRA Utilities" ], "summary": "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.", "operationId": "81f44bf8815047a194e2e15623800f9d", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (Authenticated company)", "required": true, "schema": { "type": "string", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA environment (Sandbox or Production)", "required": false, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ] } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "siteId" ], "properties": { "siteId": { "description": "Site ID of the terminal to check", "type": "string", "example": "CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce" }, "terminalId": { "description": "Optional: Manual terminal UUID to check. If provided, Site ID will only be used for JWT authentication.", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" } }, "type": "object" } } } }, "responses": { "200": { "description": "Unblock status retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Terminal unblock status retrieved successfully" } }, "type": "object" }, "data": { "properties": { "isUnblocked": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized or Session Expired" }, "404": { "description": "Terminal not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/get-terminal-blocking-message": { "post": { "tags": [ "Malawi MRA Utilities" ], "summary": "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.", "operationId": "8551f977bdbad8e39e9bb48bd8976d52", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (Authenticated company)", "required": true, "schema": { "type": "string", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA environment (Sandbox or Production)", "required": false, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ] } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "siteId" ], "properties": { "siteId": { "description": "Site ID of the terminal to check", "type": "string", "example": "CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce" }, "terminalId": { "description": "Optional: Manual terminal UUID to check. If provided, Site ID will only be used for JWT authentication.", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" } }, "type": "object" } } } }, "responses": { "200": { "description": "Blocking details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Terminal blocking details retrieved successfully" } }, "type": "object" }, "data": { "properties": { "isBlocked": { "type": "boolean", "example": false }, "blockingReason": { "type": "string", "example": null, "nullable": true }, "blockedAt": { "type": "string", "example": "0001-01-01T00:00:00" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized or Session Expired" }, "404": { "description": "Terminal not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/validate-vat5-certificate": { "post": { "tags": [ "Malawi MRA Utilities" ], "summary": "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.", "operationId": "4ccce694a594e7a3b91f73ed124b14f2", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' or 'Production'", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "siteId", "projectNumber", "certificateNumber", "quantity" ], "properties": { "siteId": { "description": "Site ID of the terminal to use", "type": "string", "example": "CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce" }, "terminalId": { "description": "Optional: Manual terminal UUID to check. If provided, Site ID will only be used for JWT authentication.", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "projectNumber": { "description": "VAT5 Project Number", "type": "string", "example": "PRJ-2024-001" }, "certificateNumber": { "description": "VAT5 Certificate Number", "type": "string", "example": "VAT5-987654" }, "quantity": { "description": "Quantity being validated against the certificate", "type": "number", "example": 100 } }, "type": "object" } } } }, "responses": { "200": { "description": "Certificate validation response from MRA", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } }, "type": "object" }, "data": { "properties": { "projectNumber": { "type": "string", "nullable": true }, "vat5CertificateNumber": { "type": "string", "nullable": true }, "quantity": { "type": "number" }, "dateOfIssue": { "type": "string", "nullable": true }, "dateOfExpiry": { "type": "string", "nullable": true }, "isValid": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized or Session Expired" }, "403": { "description": "Terminal Blocked" }, "404": { "description": "Terminal not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/generate-tax-receipt": { "post": { "tags": [ "Malawi MRA Sales Management" ], "summary": "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## ๐Ÿš€ 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## ๐Ÿ“‹ 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## ๐Ÿ“Š 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## โšก 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## ๐Ÿ› ๏ธ 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## โš ๏ธ Important Notes* ## รขลกย รฏยธย 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.", "operationId": "ead27ef16aa4104fcd898fd1ea702d62", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' for testing or 'Production' for live", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId", "referenceNo", "invoiceHeader", "invoiceLineItems" ], "properties": { "terminalId": { "description": "Terminal ID from activation (used to fetch JWT token)", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "referenceNo": { "description": "Your internal reference number", "type": "string", "example": "REF-1001" }, "invoiceHeader": { "properties": { "invoiceDateTime": { "type": "string", "format": "date-time", "example": "2026-03-25T19:56:03.000Z" }, "sellerTIN": { "type": "string", "example": "20154457" }, "siteId": { "type": "string", "example": "CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce" }, "globalConfigVersion": { "type": "integer", "example": 1 }, "taxpayerConfigVersion": { "type": "integer", "example": 1051 }, "terminalConfigVersion": { "type": "integer", "example": 1 }, "paymentMethod": { "type": "string", "example": "Cash" }, "buyerTIN": { "description": "Buyer's Taxpayer Identification Number", "type": "string", "example": "12345678" }, "buyerName": { "description": "Buyer's Legal Name", "type": "string", "example": "John Doe" }, "buyerAuthorizationCode": { "description": "MRA-issued Authorization Code for the buyer", "type": "string", "example": "AUTH-999" }, "isExport": { "type": "boolean", "example": false }, "isReliefSupply": { "type": "boolean", "example": false }, "vat5CertificateDetails": { "properties": { "id": { "type": "integer", "example": 0 }, "projectNumber": { "type": "string", "example": "PRJ-123" }, "certificateNumber": { "type": "string", "example": "CERT-456" }, "quantity": { "type": "number", "example": 10 } }, "type": "object" } }, "type": "object" }, "invoiceLineItems": { "type": "array", "items": { "properties": { "productCode": { "type": "string", "example": "260306145930" }, "description": { "type": "string", "example": "MDF LAMINATED" }, "unitPrice": { "description": "Price including VAT", "type": "number", "format": "float", "example": 1000 }, "quantity": { "type": "integer", "example": 1 }, "discount": { "description": "Discount amount or percentage (e.g. '100' or '10%')", "type": "string", "example": "10%" }, "taxRateId": { "type": "string", "enum": [ "A", "B", "E" ], "example": "A" }, "taxRate": { "description": "Tax rate [Required for rate A]. Supports decimal (0.165), percentage (16.5), or string ('16.5%')", "type": "string", "example": "16.5" }, "isProduct": { "type": "boolean", "example": true } }, "type": "object" } }, "invoiceSummary": { "properties": { "offlineSignature": { "description": "MRA Offline Signature (Required for offline synchronization)", "type": "string", "example": "" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tax receipt generated successfully" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/generate-tax-receipt-debug": { "post": { "tags": [ "Malawi MRA Sales Management" ], "summary": "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.", "operationId": "6d56bfe5e3e601a2072ad46a8a62ea76", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' or 'Production'", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ] } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId", "referenceNo", "invoiceHeader", "invoiceLineItems" ], "properties": { "terminalId": { "type": "string", "format": "uuid", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "referenceNo": { "type": "string", "example": "REF-2026-DEBUG-001" }, "invoiceHeader": { "properties": { "sellerTIN": { "type": "string", "example": "20154457" }, "buyerTIN": { "type": "string", "example": "12345678", "nullable": true }, "buyerName": { "type": "string", "example": "John Doe", "nullable": true }, "isReliefSupply": { "type": "boolean", "example": false }, "vat5CertificateDetails": { "properties": { "id": { "type": "integer", "example": 1 }, "projectNumber": { "type": "string", "example": "PRJ-123" }, "certificateNumber": { "type": "string", "example": "CERT-456" }, "quantity": { "type": "number", "example": 10.5 } }, "type": "object", "nullable": true } }, "type": "object" }, "invoiceLineItems": { "type": "array", "items": { "properties": { "productCode": { "type": "string", "example": "260306145930" }, "description": { "type": "string", "example": "MDF LAMINATED" }, "unitPrice": { "type": "number", "format": "float", "example": 1000 }, "quantity": { "type": "number", "example": 2 }, "taxRateId": { "type": "string", "example": "A" } }, "type": "object" } }, "invoiceSummary": { "properties": { "offlineSignature": { "type": "string", "example": "", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Debug payload generated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "DEBUG: Prepared MRA Payload" } }, "type": "object" }, "data": { "properties": { "mra_payload": { "type": "object" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/generate-tax-receipt-offline": { "post": { "tags": [ "Malawi MRA Sales Management" ], "summary": "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.", "operationId": "a4b90654a834095d3c4cae71f33be853", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' for testing or 'Production' for live", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId", "referenceNo", "invoiceHeader", "invoiceLineItems" ], "properties": { "terminalId": { "description": "Terminal ID from activation", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "referenceNo": { "description": "Your internal reference number", "type": "string", "example": "REF-1001" }, "invoiceHeader": { "properties": { "invoiceDateTime": { "type": "string", "format": "date-time", "example": "2026-03-25T19:56:03.000Z" }, "sellerTIN": { "type": "string", "example": "20154457" }, "siteId": { "type": "string", "example": "CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce" }, "paymentMethod": { "type": "string", "example": "Cash" }, "isExport": { "type": "boolean", "example": false }, "isReliefSupply": { "type": "boolean", "example": false }, "vat5CertificateDetails": { "properties": { "id": { "type": "integer", "example": 0 }, "projectNumber": { "type": "string", "example": "PRJ-123" }, "certificateNumber": { "type": "string", "example": "CERT-456" }, "quantity": { "type": "number", "example": 10 } }, "type": "object" } }, "type": "object" }, "invoiceLineItems": { "type": "array", "items": { "properties": { "productCode": { "type": "string", "example": "260306145930" }, "description": { "type": "string", "example": "MDF LAMINATED" }, "unitPrice": { "type": "number", "format": "float", "example": 1000 }, "quantity": { "type": "integer", "example": 1 }, "taxRateId": { "type": "string", "example": "A" }, "taxRate": { "type": "string", "example": "16.5" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Offline payload simulated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "OFFLINE SIMULATION: Success" } }, "type": "object" }, "data": { "properties": { "invoiceNumber": { "type": "string", "example": "Cs3-B-JY3E-BA" }, "offlineSignature": { "type": "string", "example": "p-Xy..." }, "validationURL": { "type": "string", "example": "https://..." }, "mraPayload": { "type": "object" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/query-local-receipts": { "post": { "tags": [ "Malawi MRA Sales Management" ], "summary": "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.", "operationId": "e87fababed3f39d79c4f78461ad1b273", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "token", "in": "query", "description": "API access token for authentication (optional if Bearer token is provided)", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "siteId" ], "properties": { "siteId": { "description": "MRA Site ID", "type": "string", "example": "CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce" }, "startDate": { "description": "Filter by start date (YYYY-MM-DD)", "type": "string", "example": "" }, "endDate": { "description": "Filter by end date (YYYY-MM-DD)", "type": "string", "example": "" }, "status": { "type": "string", "enum": [ "success", "failed", "" ], "example": "" }, "referenceNo": { "description": "Filter by reference number", "type": "string", "example": "" }, "invoiceNumber": { "description": "Filter by invoice number", "type": "string", "example": "" }, "pageSize": { "type": "integer", "example": 20 }, "pageNo": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "List of receipts" }, "401": { "description": "Unauthorized - Authorization header missing or invalid", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "AUTHORIZATION_HEADER_MISSING" } }, "type": "object" }, "data": { "type": "string", "example": "Authorization header is required" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/last-online-transaction": { "post": { "tags": [ "Malawi MRA Sales Management" ], "summary": "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.", "operationId": "8b8dc1923ea929f8d7f42b26044c8665", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' or 'Production'", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId" ], "properties": { "terminalId": { "description": "Terminal ID from activation", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" } }, "type": "object" } } } }, "responses": { "200": { "description": "Last online transaction retrieved successfully" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/last-offline-transaction": { "post": { "tags": [ "Malawi MRA Sales Management" ], "summary": "Get Last Offline Transaction (Malawi MRA)", "description": "Retrieve the last successfully submitted offline transaction from the MRA system for a specific terminal.", "operationId": "b6d5e625d5152a27502d8174db8e31bb", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' or 'Production'", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId" ], "properties": { "terminalId": { "description": "Terminal ID from activation", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" } }, "type": "object" } } } }, "responses": { "200": { "description": "Last offline transaction retrieved successfully" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/query-void-receipts": { "post": { "tags": [ "Malawi MRA Sales Management" ], "summary": "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.", "operationId": "487e5ccfacaa87b17137f71398b818d5", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId" ], "properties": { "terminalId": { "description": "Terminal ID from activation", "type": "string", "format": "uuid", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "invoiceNumber": { "description": "Filter by a specific MRA invoice number", "type": "string", "example": "Cs3-B-JY3E-BA" }, "startDate": { "description": "Start date for query range (YYYY-MM-DD or ISO 8601)", "type": "string", "format": "date-time", "example": "2026-03-25T00:00:00.000Z" }, "endDate": { "description": "End date for query range (YYYY-MM-DD or ISO 8601)", "type": "string", "format": "date-time", "example": "2026-03-27T00:00:00.000Z" }, "page": { "description": "Page number for pagination", "type": "integer", "default": 1, "example": 1 }, "pageSize": { "description": "Number of records per page", "type": "integer", "default": 10, "example": 10 } }, "type": "object" } } } }, "responses": { "200": { "description": "Void receipts retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Void requests retrieved successfully" } }, "type": "object" }, "data": { "properties": { "items": { "type": "array", "items": { "properties": { "invoiceNumber": { "type": "string", "example": "Cs3-B-JY3E-BA" }, "requestReason": { "type": "string", "example": "refund" }, "issueDate": { "type": "string", "example": "2026-03-25" }, "requestedBy": { "type": "string", "example": "20154457" }, "requestedOn": { "type": "string", "format": "date-time", "example": "2026-03-26T14:26:44.95" }, "status": { "type": "string", "example": "Pending" }, "approvedOn": { "type": "string", "example": null }, "rejectedReason": { "type": "string", "example": null }, "referenceNo": { "type": "string", "example": "REF-1008" } }, "type": "object" } }, "page": { "type": "integer", "example": 1 }, "pageSize": { "type": "integer", "example": 10 }, "totalCount": { "type": "integer", "example": 1 } }, "type": "object" }, "http_status": { "type": "integer", "example": 200 } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/cancel-sales-receipt": { "post": { "tags": [ "Malawi MRA Sales Management" ], "summary": "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.", "operationId": "eea07766dd5fda7c0e9acd813ef7609b", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId", "invoiceNumber", "reason" ], "properties": { "terminalId": { "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "invoiceNumber": { "description": "The MRA invoice number to void", "type": "string", "example": "Cs3-B-JY3E-BA" }, "reason": { "description": "Reason for cancellation/void", "type": "string", "example": "refund" }, "referenceNo": { "description": "Optional internal reference number", "type": "string", "example": "REF-1008" } }, "type": "object" } } } }, "responses": { "200": { "description": "Void request submitted successfully" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/query-local-void-requests": { "post": { "tags": [ "Malawi MRA Sales Management" ], "summary": "Query Local Void Requests (Malawi MRA)", "description": "Retrieve a list of void requests stored in our local database for tracking and reconciliation.", "operationId": "13ebf355926e8cd98864da0c3e0f84b3", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "enum": [ "Pending", "Approved", "Failed" ], "example": "" }, "invoiceNumber": { "type": "string", "example": "" }, "referenceNo": { "type": "string", "example": "" }, "pageSize": { "type": "integer", "example": 20 }, "pageNo": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "List of void requests" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/validate-buyer-auth-code": { "post": { "tags": [ "Malawi MRA Sales Management" ], "summary": "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.", "operationId": "0031eff3b7e6c52c2aea66b8c261f91e", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' or 'Production'", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId", "authorizationCode" ], "properties": { "terminalId": { "description": "Terminal ID from activation", "type": "string", "format": "uuid", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "authorizationCode": { "description": "The MRA authorization code to validate", "type": "string", "example": "070847437E52" } }, "type": "object" } } } }, "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Validation code found" } }, "type": "object" }, "data": { "properties": { "isValidAuthorizationCode": { "type": "boolean", "example": true }, "authorizationCode": { "type": "string", "example": "070847437E52" }, "authorizationReason": { "type": "string", "example": "Purchasing on behalf of the organisation" }, "generatedBy": { "type": "string", "example": "20154457-Taxpayer Business" }, "generatedOn": { "type": "string", "format": "date-time", "example": "2026-03-31T19:49:07.503" }, "expiresOn": { "type": "string", "format": "date-time", "example": "2026-04-05T19:49:07.503" }, "usedOn": { "type": "string", "format": "date-time", "example": null } }, "type": "object" }, "http_status": { "type": "integer", "example": 200 } }, "type": "object" } } } }, "400": { "description": "Validation error or MRA error" }, "404": { "description": "Company or Terminal not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/get-invoice-by-number": { "post": { "tags": [ "Malawi MRA Sales Management" ], "summary": "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.", "operationId": "75f39c80698339e81d446df3740d06b5", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' or 'Production'", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ] } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId", "invoiceNumber" ], "properties": { "terminalId": { "description": "Terminal ID from activation", "type": "string", "format": "uuid", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "invoiceNumber": { "description": "The MRA invoice number to retrieve", "type": "string", "example": "Cs3-B-JY3X-B" } }, "type": "object" } } } }, "responses": { "200": { "description": "Invoice retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Invoice retrieved successfully." } }, "type": "object" }, "data": { "properties": { "dateSubmitted": { "type": "string", "format": "date-time", "example": "2026-04-13T08:34:16.57" }, "validationURL": { "type": "string", "example": "https://eservices.mra.mw/doc/v/?vc=96261031813297&c=96354665619a43458b4e011930e5507e" }, "invoiceHeader": { "type": "object" }, "invoiceLineItems": { "type": "array", "items": { "type": "object" } }, "invoiceSummary": { "type": "object" } }, "type": "object" }, "http_status": { "type": "integer", "example": 200 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Authorization header missing or invalid" }, "404": { "description": "Company or Terminal not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/process-credit-debit-note": { "post": { "tags": [ "Malawi MRA Sales Management" ], "summary": "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.", "operationId": "b910d82c85c16c2554e5a804768a95eb", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' or 'Production'", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ] } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId", "referenceNo", "reasonForAdjustment", "invoiceHeader", "invoiceLineItems" ], "properties": { "terminalId": { "description": "Terminal ID from activation", "type": "string", "format": "uuid", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "referenceNo": { "description": "Unique reference for this adjustment", "type": "string", "example": "REF-CD-1002" }, "reasonForAdjustment": { "description": "Description of why the credit/debit note is being issued", "type": "string", "example": "Return of damaged goods" }, "invoiceHeader": { "required": [ "invoiceNumber", "sellerTIN" ], "properties": { "invoiceNumber": { "description": "The original invoice number being adjusted", "type": "string", "example": "Cs3-B-JY3X-B" }, "invoiceDateTime": { "type": "string", "format": "date-time", "example": "2026-04-16T10:22:14.527Z" }, "sellerTIN": { "type": "string", "example": "20154457" }, "siteId": { "type": "string", "example": "CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce" }, "paymentMethod": { "type": "string", "example": "Cash" }, "isExport": { "type": "boolean", "example": false }, "isReliefSupply": { "type": "boolean", "example": false }, "vat5CertificateDetails": { "properties": { "id": { "type": "integer", "example": 0 }, "projectNumber": { "type": "string", "example": "PRJ-123" }, "certificateNumber": { "type": "string", "example": "CERT-456" }, "quantity": { "type": "number", "example": 10 } }, "type": "object" } }, "type": "object" }, "invoiceLineItems": { "type": "array", "items": { "properties": { "productCode": { "type": "string", "example": "260306145930" }, "description": { "type": "string", "example": "MDF LAMINATED" }, "unitPrice": { "type": "number", "format": "float", "example": 1000 }, "quantity": { "type": "integer", "example": 1 }, "discount": { "type": "string", "example": "0" }, "taxRateId": { "type": "string", "enum": [ "A", "B", "E" ], "example": "A" }, "isProduct": { "type": "boolean", "example": true } }, "type": "object" } }, "invoiceSummary": { "properties": { "offlineSignature": { "description": "MRA Offline Signature (Required for offline synchronization)", "type": "string", "example": "" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Note processed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Processed successfully" } }, "type": "object" }, "data": { "type": "object" }, "http_status": { "type": "integer", "example": 200 } }, "type": "object" } } } }, "400": { "description": "MRA Processing Error (e.g., Original invoice not found)" }, "401": { "description": "Unauthorized - Terminal session expired" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/process-credit-debit-note-debug": { "post": { "tags": [ "Malawi MRA Sales Management" ], "summary": "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.", "operationId": "f0f0b720251b0ef56b402d04f7cee057", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' or 'Production'", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ] } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId", "referenceNo", "reasonForAdjustment", "invoiceHeader", "invoiceLineItems" ], "properties": { "terminalId": { "type": "string", "format": "uuid", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "referenceNo": { "type": "string", "example": "REF-ADJ-001" }, "reasonForAdjustment": { "type": "string", "example": "Return of goods" }, "invoiceHeader": { "properties": { "invoiceNumber": { "type": "string", "example": "Cs3-B-JY3E-BA" }, "sellerTIN": { "type": "string", "example": "20154457" }, "isReliefSupply": { "type": "boolean", "example": false } }, "type": "object" }, "invoiceLineItems": { "type": "array", "items": { "properties": { "productCode": { "type": "string", "example": "260306145930" }, "description": { "type": "string", "example": "MDF LAMINATED" }, "unitPrice": { "type": "number", "format": "float", "example": 1000 }, "quantity": { "type": "number", "example": 1 }, "taxRateId": { "type": "string", "example": "A" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Debug payload generated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "DEBUG: Prepared MRA Payload for Credit/Debit Note" } }, "type": "object" }, "data": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/stock-adjustment-reasons": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "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.", "operationId": "0a8c3679a3a85c5da234d8c357f1c3c1", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' for testing or 'Production' for live", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId" ], "properties": { "terminalId": { "description": "Terminal ID from activation (used to fetch JWT token)", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" } }, "type": "object" } } } }, "responses": { "200": { "description": "Stock adjustment reasons retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Adjustment reasons retrieved successfully" } }, "type": "object" }, "data": { "type": "array", "items": { "properties": { "description": { "type": "string", "example": "Theft" } }, "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Bad request - invalid parameters or missing terminal" }, "404": { "description": "Terminal not found - Please activate the terminal first" }, "403": { "description": "Forbidden - Company inactive, license expired, or environment mismatch" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/get-suppliers": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "Get suppliers (Malawi MRA)", "description": "Retrieve available suppliers from Malawi Revenue Authority (MRA) EIS system. Requires an activated terminal and valid JWT token.", "operationId": "afb6360ba68ff6708a16520f0116e64d", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' for testing or 'Production' for live", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId" ], "properties": { "terminalId": { "description": "Terminal ID from activation (used to fetch JWT token)", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" } }, "type": "object" } } } }, "responses": { "200": { "description": "Suppliers retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Suppliers retrieved successfully" } }, "type": "object" }, "data": { "type": "array", "items": { "properties": { "supplierId": { "type": "integer", "example": 346 }, "supplierName": { "type": "string", "example": "Raiply" }, "supplierContactEmail": { "type": "string", "example": null, "nullable": true }, "supplierContactPhone": { "type": "string", "example": "022222222" }, "supplierTin": { "type": "string", "example": "20154457" } }, "type": "object" } }, "http_status": { "type": "integer", "example": 200 } }, "type": "object" } } } }, "400": { "description": "Bad request - invalid parameters or missing terminal" }, "404": { "description": "Terminal not found - Please activate the terminal first" }, "403": { "description": "Forbidden - Company inactive, license expired, or environment mismatch" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/get-units-of-measure": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "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.", "operationId": "63fafb944f552cf6113f7c61cba53a60", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' for testing or 'Production' for live", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId" ], "properties": { "terminalId": { "description": "Terminal ID from activation (used to fetch JWT token)", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" } }, "type": "object" } } } }, "responses": { "200": { "description": "Units of measure retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Units of measure retrieved successfully" } }, "type": "object" }, "data": { "type": "array", "items": { "properties": { "unitOfMeasure": { "type": "string", "example": "Piece" }, "unitOfMeasureDescription": { "type": "string", "example": "Piece" } }, "type": "object" } }, "http_status": { "type": "integer", "example": 200 } }, "type": "object" } } } }, "400": { "description": "Bad request - invalid parameters or missing terminal" }, "404": { "description": "Terminal not found - Please activate the terminal first" }, "403": { "description": "Forbidden - Company inactive, license expired, or environment mismatch" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/get-hs-codes": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "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.", "operationId": "f92ba1a1b5f515a04a0759469b18cd32", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' for testing or 'Production' for live", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId" ], "properties": { "terminalId": { "description": "Terminal ID from activation (used to fetch JWT token)", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" } }, "type": "object" } } } }, "responses": { "200": { "description": "HS codes retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "HS codes retrieved successfully" } }, "type": "object" }, "data": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "01012100" }, "description": { "type": "string", "example": "Pure-bred breeding horses" }, "taxRateId": { "type": "string", "example": "1" } }, "type": "object" } }, "http_status": { "type": "integer", "example": 200 } }, "type": "object" } } } }, "400": { "description": "Bad request - invalid parameters or missing terminal" }, "404": { "description": "Terminal not found - Please activate the terminal first" }, "403": { "description": "Forbidden - Company inactive, license expired, or environment mismatch" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/add-product": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "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
", "operationId": "c28593a5f05a7a4321fb8e4e13ef12ac", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' for testing or 'Production' for live", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "barcode", "hsCode", "name", "uom", "terminalId" ], "properties": { "barcode": { "description": "Product barcode / item code", "type": "string", "example": "260306145930" }, "hsCode": { "description": "Harmonized System (HS) code. Sample HS codes: 94061010 (GREEN HOUSES OF WOOD, Tax Rate E), 94061090 (OTHER PREFABRICATED BUILDINGS, Tax Rate E), 94062000 (MODULAR BUILDING UNITS, OF STEEL, Tax Rate A), 94069000 (OTHER PREFABRICATED BUILDINGS, Tax Rate A)", "type": "string", "example": "94062000" }, "name": { "description": "Product name", "type": "string", "example": "Breeding Horse Premium" }, "description": { "description": "Optional product description", "type": "string", "example": "Premium breeding horses from local farm" }, "uom": { "description": "Unit of Measure (UOM) code. Sample UOMs: DR (Drum), % (Percentage), %O (Per mille), D (Day)", "type": "string", "example": "DR" }, "terminalId": { "description": "Terminal ID from activation (used to fetch JWT token)", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" } }, "type": "object" } } } }, "responses": { "200": { "description": "Product added successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Product added successfully" } }, "type": "object" }, "data": { "properties": { "productId": { "type": "integer", "example": 12345 }, "barcode": { "type": "string", "example": "260306145930" }, "hsCode": { "type": "string", "example": "01012100" }, "taxRateId": { "type": "string", "example": "1" }, "name": { "type": "string", "example": "Breeding Horse Premium" }, "description": { "type": "string", "example": "Premium breeding horses from local farm" }, "uom": { "type": "string", "example": "Piece" } }, "type": "object" }, "http_status": { "type": "integer", "example": 200 } }, "type": "object" } } } }, "400": { "description": "Bad request - invalid parameters or validation errors" }, "404": { "description": "Terminal not found - Please activate the terminal first" }, "403": { "description": "Forbidden - Company inactive, license expired, or environment mismatch" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/stock-adjustment": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "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.", "operationId": "63917820ecf42746be402af1def0c60c", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' for testing or 'Production' for live", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "barcode", "quantity", "adjustmentReason", "adjustmentType", "terminalId", "purchaseOrderNumber" ], "properties": { "purchaseOrderNumber": { "description": "Your unique reference for this adjustment", "type": "string", "example": "PO-ADJ-001" }, "barcode": { "description": "Product barcode / item code", "type": "string", "example": "260306145930" }, "quantity": { "description": "Quantity to adjust", "type": "number", "example": 1 }, "adjustmentReason": { "description": "Reason for adjustment (see /stock-adjustment-reasons)", "type": "string", "example": "Theft" }, "adjustmentType": { "type": "string", "enum": [ "Increase", "Decrease" ], "example": "Decrease" }, "terminalId": { "description": "Terminal ID from activation", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "siteId": { "description": "Optional Site ID (overrides terminal site if provided)", "type": "string", "example": "CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce" }, "taxpayerRemarks": { "description": "Optional remarks", "type": "string", "example": "Inventory audit adjustment" } }, "type": "object" } } } }, "responses": { "200": { "description": "Stock adjustment submitted successfully" }, "400": { "description": "Bad request - invalid parameters" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/stock-adjustment-debug": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "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.", "operationId": "6f5d66419c50aac9a7af2387cad78a7f", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' or 'Production'", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ] } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "purchaseOrderNumber", "barcode", "quantity", "adjustmentReason", "adjustmentType", "terminalId" ], "properties": { "purchaseOrderNumber": { "type": "string", "example": "PO-DEBUG-001" }, "barcode": { "type": "string", "example": "260306145930" }, "quantity": { "type": "number", "example": 10 }, "adjustmentReason": { "type": "string", "example": "Damaged goods" }, "adjustmentType": { "type": "string", "enum": [ "Increase", "Decrease" ], "example": "Decrease" }, "terminalId": { "type": "string", "format": "uuid", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "siteId": { "type": "string", "example": "CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce", "nullable": true }, "taxpayerRemarks": { "type": "string", "example": "Debug simulation", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Debug payload generated successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "DEBUG: Prepared MRA Stock Adjustment Payload" } }, "type": "object" }, "data": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/increase-descrease-stock-request": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "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.", "operationId": "f6b47d0f94d5a841f2b0f0db4c950715", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' for testing or 'Production' for live", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "supplierId", "deliveryNoteNumber", "receivingDate", "receivedBy", "totalItems", "totalQuantity", "totalValue", "items", "terminalId", "notes" ], "properties": { "supplierId": { "type": "integer", "example": 346 }, "deliveryNoteNumber": { "type": "string", "example": "DN-2026-001" }, "receivingDate": { "type": "string", "format": "date-time", "example": "2026-03-26T10:00:00.000Z" }, "purchaseOrderNumber": { "type": "string", "example": "PO-2026-001" }, "receivedBy": { "type": "string", "example": "John Doe" }, "totalItems": { "type": "integer", "example": 1 }, "totalQuantity": { "type": "integer", "example": 50 }, "totalValue": { "type": "number", "format": "float", "example": 500000 }, "notes": { "type": "string", "example": "Informal timber purchase" }, "terminalId": { "description": "Terminal ID from activation (used to fetch JWT token)", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "items": { "type": "array", "items": { "properties": { "itemCode": { "type": "string", "example": "260306145930" }, "description": { "type": "string", "example": "MDF LAMINATED" }, "quantityOrdered": { "type": "integer", "example": 50 }, "quantityReceived": { "type": "integer", "example": 50 }, "unitOfMeasure": { "type": "string", "example": "Piece" }, "unitPrice": { "type": "number", "format": "float", "example": 10000 }, "totalPrice": { "type": "number", "format": "float", "example": 500000 }, "isFinishedProduct": { "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Informal purchase submitted successfully" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/query-stock-adjustments": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "Query Stock Adjustments (Malawi MRA)", "description": "Retrieve a list of stock adjustments stored in the local database.", "operationId": "2ced5be97e2e96bb26bedd50e0dd6717", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "purchaseOrderNumber": { "type": "string", "example": "" }, "status": { "type": "string", "enum": [ "success", "failed", "" ], "example": "" }, "pageSize": { "type": "integer", "example": 20 }, "pageNo": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "List of stock adjustments" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/check-product-status": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "Check Product Status (Malawi MRA)", "description": "Retrieve detailed stock information, tax rates, and descriptions for a specific product directly from the MRA system.", "operationId": "0828cca1ccb6ab82637bacf73b3dea8e", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId", "productId" ], "properties": { "terminalId": { "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "productId": { "description": "Barcode or product code", "type": "string", "example": "260306145930" } }, "type": "object" } } } }, "responses": { "200": { "description": "Product status retrieved successfully" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/stock-transfer": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "Stock Transfer (Malawi MRA)", "description": "Transfer inventory from warehouse to site or between sites. Requires an activated terminal and valid JWT token.", "operationId": "3fbd64f171cab0b977cd6b45ffbe9f51", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457", "example": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' for testing or 'Production' for live", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ], "example": "Sandbox" } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId" ], "properties": { "terminalId": { "description": "Terminal ID from activation (used to fetch JWT token)", "type": "string", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "fromWarehouseToSite": { "description": "Flag indicating if transfer is from warehouse to site", "type": "boolean", "example": true }, "fromSiteId": { "description": "Source site or warehouse ID", "type": "string", "example": "warehouse-001" }, "toSiteId": { "description": "Destination site ID", "type": "string", "example": "CHecab1e71-dc53-4aa6-a5b3-2332fc41bcce" }, "items": { "type": "array", "items": { "properties": { "barcode": { "description": "Product barcode", "type": "string", "example": "260306145930" }, "quantity": { "description": "Quantity to transfer", "type": "number", "example": 10 }, "price": { "description": "Unit price of the item", "type": "number", "example": 1000 } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Stock transfer processed successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Stock transfer processed successfully" } }, "type": "object" }, "data": { "type": "object", "nullable": true }, "http_status": { "type": "integer", "example": 200 } }, "type": "object" } } } }, "400": { "description": "Bad request - invalid parameters" }, "403": { "description": "Forbidden - Company error or environment mismatch" }, "404": { "description": "Not Found - Terminal or company not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/get-raw-materials": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "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.", "operationId": "23fb2f98b5b0ffb7d65401dbe0efdb21", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' or 'Production'", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ] } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId" ], "properties": { "terminalId": { "description": "Terminal ID from activation", "type": "string", "format": "uuid", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "page": { "description": "Page number to retrieve", "type": "integer", "default": 1, "example": 1 }, "pageSize": { "description": "Number of items per page (max 200)", "type": "integer", "default": 50, "example": 50 } }, "type": "object" } } } }, "responses": { "200": { "description": "Raw materials retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } }, "type": "object" }, "data": { "type": "array", "items": { "type": "object" } }, "http_status": { "type": "integer", "example": 200 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Session expired" }, "404": { "description": "Company or Terminal not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/submit-raw-material-conversion": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "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.", "operationId": "fd1e2c438fb00ced5ae3ee13af9f4fac", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' or 'Production'", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ] } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId", "productionBatchId", "productionDate", "rawMaterials", "finishedProducts" ], "properties": { "terminalId": { "description": "Terminal ID from activation", "type": "string", "format": "uuid", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" }, "productionBatchId": { "description": "Unique batch identifier for this production run", "type": "string", "example": "BATCH-2026-001" }, "productionDate": { "description": "The date and time production occurred", "type": "string", "format": "date-time", "example": "2026-04-16T09:52:52.772Z" }, "rawMaterials": { "description": "List of raw materials consumed", "type": "array", "items": { "properties": { "productId": { "type": "string", "example": "RM-001" }, "productName": { "type": "string", "example": "Timber Log" }, "availableQuantity": { "type": "number", "format": "float", "example": 10.5 }, "usedQuantity": { "type": "number", "format": "float", "example": 2 } }, "type": "object" } }, "finishedProducts": { "description": "List of finished products generated", "type": "array", "items": { "properties": { "quantity": { "type": "number", "format": "float", "example": 5 }, "unitOfMeasure": { "type": "string", "example": "Piece" }, "expiryDate": { "type": "string", "format": "date-time", "example": "2027-04-16T09:52:52.772Z" }, "productDescription": { "type": "string", "example": "MDF Board" }, "barcode": { "type": "string", "example": "260306145930" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Conversion submitted successfully", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Raw material conversion submitted successfully" } }, "type": "object" }, "data": { "type": "object", "nullable": true }, "http_status": { "type": "integer", "example": 200 } }, "type": "object" } } } }, "400": { "description": "MRA Validation Error or Processing Error", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "01" }, "returnMessage": { "type": "string", "example": "Raw material string not found in warehouse" } }, "type": "object" }, "data": { "properties": { "mra_status_code": { "type": "integer", "example": -2 }, "errors": { "type": "object", "example": { "FinishedProducts[0].Quantity": [ "Quantity must be greater than 0" ] } } }, "type": "object" }, "http_status": { "type": "integer", "example": 400 } }, "type": "object" } } } }, "401": { "description": "Unauthorized - Terminal session expired" }, "404": { "description": "Company or Terminal not found" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/{tin}/ping-server": { "post": { "tags": [ "Malawi MRA Stock Management" ], "summary": "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.", "operationId": "ec3e4364051572bbe0438eed9f827ba3", "parameters": [ { "name": "tin", "in": "path", "description": "Taxpayer Identification Number (e.g., 20154457)", "required": true, "schema": { "type": "string", "default": "20154457" } }, { "name": "deploymentEnvironment", "in": "query", "description": "MRA deployment environment - 'Sandbox' or 'Production'", "required": true, "schema": { "type": "string", "default": "Sandbox", "enum": [ "Sandbox", "Production" ] } }, { "name": "token", "in": "query", "description": "API access token for authentication", "required": true, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "terminalId" ], "properties": { "terminalId": { "type": "string", "format": "uuid", "example": "193760fb-cddc-40ed-b0fb-f08f8720f86c" } }, "type": "object" } } } }, "responses": { "200": { "description": "Ping successful", "content": { "application/json": { "schema": { "properties": { "status": { "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Pong" } }, "type": "object" }, "data": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "description": "Enter your access token", "bearerFormat": "JWT", "scheme": "bearer" } } }, "tags": [ { "name": "Authentication", "description": "๐Ÿ” Authentication & Authorization - Secure token-based authentication system for API access. Generate, validate, and manage access tokens with customizable expiration periods." }, { "name": "Malawi MRA Onboarding", "description": "๐Ÿ‡ฒ๐Ÿ‡ผ Malawi MRA Onboarding - Terminal activation and integration with Malawi Revenue Authority (MRA) EIS system. Manage terminal setup, JWT token acquisition, and security configuration for Malawi-based businesses." }, { "name": "Malawi MRA Utilities", "description": "๐Ÿ‡ฒ๐Ÿ‡ผ Malawi MRA Utilities - Common utility endpoints like warehouse product retrieval and security configuration." }, { "name": "Malawi MRA Configuration", "description": "๐Ÿ‡ฒ๐Ÿ‡ผ Malawi MRA Configuration - Manage terminal settings, tax rates, and global configuration from MRA." }, { "name": "Malawi MRA Stock Management", "description": "๐Ÿ‡ฒ๐Ÿ‡ผ Malawi MRA Stock Management - Inventory and supplier management for Malawi EIS." }, { "name": "Malawi MRA Sales Management", "description": "๐Ÿ‡ฒ๐Ÿ‡ผ Malawi MRA Sales Management - Sales transaction and tax receipt generation for Malawi EIS." } ] }