{ "openapi": "3.0.0", "info": { "title": "WEAF Company Uganda Ltd API", "description": "# WEAF EFRIS API\n\nThe WEAF EFRIS API is developed and owned by Weaf Company Uganda Limited. It provides a simplified and ready-to-use solution for businesses and developers who need to integrate their systems with Uganda Revenue Authority's Electronic Fiscal Receipting and Invoicing System (EFRIS).\n\nWith this API, you don't need to handle complex implementationsβ€”just follow a few simple steps to get started:\n\n## πŸš€ Getting Started\n\n### 1. Signup\nCreate an account at [weafcompany.com/login](https://weafcompany.com/login).\n\n### 2. Create a Company\nAfter signing up, register your company profile inside the platform.\n\n### 3. Generate Access Tokens\nObtain access tokens that will allow you to connect and test the API.\n\n### 4. Testing Environment\nYou can immediately start testing the API using the provided sandbox environment.\n\n### 5. Production Access\nTo move to production, you are required to:\n- Subscribe to a plan and make payment.\n- Complete the configuration process.\n- After approval, you can begin using the API in production.\n\nThis documentation provides details of all available endpoints, request/response formats, and usage guidelines.\n\n---\n\n## πŸ” Authentication Guide\n\n### Step 1: Generate Your Access Token\n1. Use the **Generate API Access Token** endpoint below\n2. Provide your email and password credentials\n3. Set your desired token expiration period (1-365 days)\n4. Give your token a descriptive name\n5. Copy the returned token value\n\n### Step 2: Use Your Token in Swagger UI\n1. Click the **πŸ”‘ Authorize** button at the top of this page\n2. In the **bearerAuth** section, enter your token in the **Value** field\n3. **Important**: Enter ONLY the token value (without 'Bearer ' prefix)\n4. Click **Authorize** to save your token\n5. Click **Close** to return to the API documentation\n\n### Step 3: Make API Calls\n- All protected endpoints will now use your token automatically\n- Your token will be included in the Authorization header as: `Bearer {your_token}`\n- You can see the lock icon πŸ”’ next to endpoints that require authentication\n\n### πŸ”„ Token Refresh Process\nWhen your token is about to expire:\n1. Use the **Refresh API Access Token** endpoint\n2. Pass your current token in the request body\n3. **For Swagger UI**: Also pass your current token in the Bearer token field above\n4. Get a new token with extended expiration\n5. Update your authorization with the new token\n\n## 🌐 Environment Selection\n\nThe API supports targeting different environments (e.g., Sandbox vs. Production) for multi-environment companies. You can specify the desired environment using one of the following two options:\n\n### Option 1: HTTP Header (Recommended)\nPass the environment name in the custom request header:\n- **Header Name**: `X-Environment`\n- **Allowed Values**: `Production` or `Sandbox` (case-insensitive)\n\n### Option 2: Request Parameter (Query or Body)\nPass the environment name as a request parameter:\n- **Parameter Name**: `environment` or `deploymentEnvironment`\n- **Allowed Values**: `Production` or `Sandbox` (case-insensitive)\n\n*Important: Specifying the environment is needed (and will be mandatory in the future) to ensure requests are routed to the correct Sandbox or Production instance.*\n\n## πŸš€ Key Features\n\n### Authentication & Security\n- **Secure Token-Based Authentication**: Generate and manage API access tokens with customizable expiration periods\n- **User Management**: Complete user authentication and authorization system\n- **Company Access Control**: Multi-company support with role-based access permissions\n\n### EFRIS Integration\n- **Taxpayer Search**: Real-time taxpayer information retrieval from URA systems\n- **Receipt Management**: Generate and manage electronic fiscal receipts\n- **Compliance Reporting**: Automated tax compliance and reporting features\n\n### SSL Certificate Management\n- **Certificate Generation**: Automated SSL certificate creation and management\n- **Certificate Validation**: Real-time certificate status monitoring\n- **Download & Installation**: Secure certificate download and installation guides\n\n### Company Management\n- **Multi-Company Support**: Manage multiple business entities from a single account\n- **Business Information**: Complete company profile and registration data management\n- **Document Management**: Secure storage and retrieval of business documents\n\n## πŸ”§ Technical Specifications\n\n- **API Version**: 1.0.0\n- **Protocol**: HTTPS (Production) / HTTP (Development)\n- **Authentication**: Bearer Token\n- **Data Format**: JSON\n- **Rate Limiting**: Applied per user/company\n- **Response Format**: Standardized JSON with status codes\n\n## πŸ›‘οΈ Security & Compliance\n\n- **Data Encryption**: All data transmission encrypted using TLS 1.3\n- **GDPR Compliant**: Full compliance with data protection regulations\n- **Audit Logging**: Comprehensive API request logging and monitoring\n- **Access Control**: Role-based permissions and company-level data isolation\n\n## πŸ“ž Support & Documentation\n\nFor technical support, API documentation, or business inquiries, please contact our team.", "contact": { "name": "WEAF Company Uganda Ltd", "url": "https://weafcompany.com", "email": "services@weafcompany.com" }, "license": { "name": "Proprietary License", "url": "https://weafcompany.com/" }, "version": "1.0.0" }, "servers": [ { "url": "https://weafcompany.com", "description": "Production Server (Default)" }, { "url": "http://localhost:8000", "description": "Local Development 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" } }, "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.\n\n**Important for Swagger UI users:**\n1. First, add your current token to the Bearer token field using the 'Authorize' button above\n2. Then use this endpoint to refresh your token\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/{tin}/sync-products": { "post": { "tags": [ "EFRIS" ], "summary": "Fetch Products from EFRIS", "description": "Retrieve and search your company's products from the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to fetch a complete list of your products or search for specific products using various filters. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send search parameters in the specified JSON format\n4. **Response Handling**: Check the response status and message for success/error details\n\n## Search & Filter Options\n- **Fetch All Products**: Send empty strings for all parameters to retrieve all products\n- **Search by Product Code**: Provide a specific `goodsCode` to find a particular product\n- **Search by Product Name**: Use `goodsName` to search for products by name (supports partial matching)\n- **Pagination**: Use `pageSize` and `pageNo` to control the number of results and page navigation\n\n## Important Notes\n- This endpoint forwards requests to the inner EFRIS API\n- All requests are logged for audit purposes\n- Response times are tracked for performance monitoring\n- Failed requests are logged with detailed error information\n- **Token Parameter**: When you provide a token in the query parameter, it will be automatically used in the Authorization header as 'Bearer {token}'", "operationId": "syncProductsWithEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "requestBody": { "description": "Product search and filter parameters - Use empty strings for parameters you don't want to filter by. Send all empty strings to fetch all products.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "goodsCode": { "type": "string", "description": "Specific product code to search for (leave empty to fetch all products)", "example": "" }, "goodsName": { "type": "string", "description": "Product name to search for - supports partial matching (leave empty to fetch all products)", "example": "" }, "pageSize": { "type": "string", "description": "Number of products to return per page (leave empty for default page size)", "example": "" }, "pageNo": { "type": "string", "description": "Page number for pagination (leave empty for first page)", "example": "" }, "environment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" }, "deploymentEnvironment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" } } }, "example": { "goodsCode": "", "goodsName": "", "pageSize": "", "pageNo": "" } } } }, "responses": { "200": { "description": "Products fetched successfully from EFRIS", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "0" }, "returnMessage": { "type": "string", "example": "SUCCESS" } } }, "data": { "type": "object", "description": "Fetched product data from EFRIS including product details, pagination info, and metadata" } } } } } }, "401": { "description": "Authentication failed - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "INVALID_TOKEN" } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Token not found or inactive" } } } } } } } }, "403": { "description": "Access denied - Company not configured or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "03" }, "returnMessage": { "type": "string", "example": "Company with TIN [1015264035] is not found in your account. Please add this company to your account first." } } }, "data": { "type": "object", "properties": { "tin": { "type": "string", "example": "1015264035" }, "status": { "type": "string", "example": "not_configured" }, "action_required": { "type": "string", "example": "Add this company to your account" } } } } } } } }, "500": { "description": "Internal server error or EFRIS API error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "500" }, "returnMessage": { "type": "string", "example": "EFRIS API configuration not found." } } }, "data": { "type": "string", "example": "EFRIS API configuration not found." } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/goods-and-services": { "get": { "tags": [ "EFRIS" ], "summary": "Get Goods and Services", "description": "Retrieve goods and services for a company from EFRIS. Uses the same authentication and TIN path parameter as sync-products. Retries up to 3 times on transient errors.", "operationId": "getGoodsAndServices", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "500": { "description": "Server Error" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "EFRIS" ], "summary": "Fetch Products from EFRIS (POST alias)", "description": "POST alias of sync-products. Retrieve and search your company's products from the EFRIS system. Uses the same controller as sync-products and expects the same request body.", "operationId": "postGoodsAndServicesSyncProductsAlias", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "requestBody": { "description": "Product search and filter parameters - Same as /sync-products. Use empty strings for parameters you don't want to filter by. Send all empty strings to fetch all products.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "goodsCode": { "type": "string", "description": "Specific product code to search for (leave empty to fetch all products)", "example": "" }, "goodsName": { "type": "string", "description": "Product name to search for - supports partial matching (leave empty to fetch all products)", "example": "" }, "pageSize": { "type": "string", "description": "Number of products to return per page (leave empty for default page size)", "example": "" }, "pageNo": { "type": "string", "description": "Page number for pagination (leave empty for first page)", "example": "" }, "environment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" }, "deploymentEnvironment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" } } }, "example": { "goodsCode": "", "goodsName": "", "pageSize": "", "pageNo": "" } } } }, "responses": { "200": { "description": "Products fetched successfully from EFRIS" }, "401": { "description": "Authentication failed - Invalid or missing token" }, "403": { "description": "Forbidden - TIN not configured or inactive" }, "500": { "description": "Server Error" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/register-product": { "post": { "tags": [ "EFRIS" ], "summary": "Register Product with EFRIS", "description": "Register new products or update existing products with the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to submit product information to URA for tax compliance and fiscal receipting purposes. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send product data in the specified JSON format with products array\n4. **Response Handling**: Check the response status and message for success/error details\n\n## Product Registration Details\n- **New Registration**: Set `operationType` to \"101\" or omit it (default)\n- **Update Existing**: Set `operationType` to \"102\"\n- **Required Fields**: goodsName, goodsCode, measureUnit, unitPrice, currency, commodityCategoryId, haveExciseTax, description, stockPrewarning, havePieceUnit\n- **Optional Fields**: pieceMeasureUnit, pieceUnitPrice, packageScaledValue, pieceScaledValue, exciseDutyCode, operationType\n- **Exports (Customs Fields)**: For exports, include `customsMeasureUnit`, `customsScaledValue`, `customsUnitPrice`, `packageScaledValueCustoms`. When updating existing exported items, set `operationType` to \"102\" and provide these fields to keep customs data in sync.\n\n## Sample Categories\n\n### Services Categories\n| Category Code | Category Name |\n|---------------|----------------|\n| 90101501 | Restaurants |\n| 81111810 | Software coding service |\n\n### Inventory Products Categories\n| Category Code | Category Name |\n|---------------|----------------|\n| 50202306 | Soft drinks |\n| 53131619 | Cosmetics |\n| 95141708 | Office kitchen |\n| 11121604 | Soft timber |\n\n## Important Instructions\n- **Commodity Category**: You must pass the `commodityCategoryCode` (not the name) in your request\n- **Empty Fields**: For fields that have empty strings, or values like \"102\" or \"101\", maintain them if you don't have the information unless your business specifically works with them\n- **Required Fields**: Ensure all mandatory fields are properly filled\n\n## Unit of Measure Handling\n\n### Single Unit of Measure (1 unit)\nIf your item supports only 1 unit of measure, leave the following fields as shown:\n```json\n{\n \"pieceMeasureUnit\": \"\",\n \"havePieceUnit\": \"102\",\n \"pieceUnitPrice\": \"\",\n \"packageScaledValue\": \"\",\n \"pieceScaledValue\": \"\"\n}\n```\n\n### Dual Unit of Measure (2 units)\nIf your item supports 2 units of measure:\n- Set `havePieceUnit` to `\"101\"`\n- Fill in the respective fields with actual data\n\n**Complete Request Body Example for 2 Units:**\n```json\n{\n \"goodsName\": \"Sample Deemed Item\",\n \"goodsCode\": \"Sample Deemed Item\",\n \"measureUnit\": \"DZN\",\n \"unitPrice\": \"10000\",\n \"currency\": \"101\",\n \"commodityCategoryId\": \"10111301\",\n \"haveExciseTax\": \"102\",\n \"description\": \"1\",\n \"stockPrewarning\": \"1\",\n \"pieceMeasureUnit\": \"PCE\",\n \"havePieceUnit\": \"101\",\n \"pieceUnitPrice\": \"1000\",\n \"packageScaledValue\": \"1\",\n \"pieceScaledValue\": \"12\",\n \"exciseDutyCode\": \"\",\n \"operationType\": \"101\"\n}\n```\n\n**Field Explanations for 2 Units:**\n- `measureUnit`: \"DZN\" (Dozen - main unit)\n- `unitPrice`: \"10000\" (Price per dozen)\n- `pieceMeasureUnit`: \"PCE\" (Piece - secondary unit)\n- `havePieceUnit`: \"101\" (Yes, supports 2 units)\n- `pieceUnitPrice`: \"1000\" (Price per piece)\n- `packageScaledValue`: \"1\" (1 dozen)\n- `pieceScaledValue`: \"12\" (Equals 12 pieces)\n- `currency`: \"101\" (Uganda Shillings)", "operationId": "registerProductWithEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "description": "Array of products to register with EFRIS", "items": { "type": "object", "properties": { "goodsName": { "type": "string", "description": "Product name", "example": "Sample Deemed Item" }, "goodsCode": { "type": "string", "description": "Product code", "example": "Sample Deemed Item" }, "measureUnit": { "type": "string", "description": "Unit of measure (e.g., PCE, KG, L)", "example": "PCE" }, "unitPrice": { "type": "string", "description": "Unit price", "example": "33000" }, "currency": { "type": "string", "description": "Currency code", "example": "101" }, "commodityCategoryId": { "type": "string", "description": "Commodity category ID", "example": "10111301" }, "haveExciseTax": { "type": "string", "description": "Excise tax indicator (101=Yes, 102=No)", "example": "102" }, "description": { "type": "string", "description": "Product description", "example": "1" }, "stockPrewarning": { "type": "string", "description": "Stock pre-warning level", "example": "10" }, "pieceMeasureUnit": { "type": "string", "description": "Piece measure unit (optional)", "example": "" }, "havePieceUnit": { "type": "string", "description": "Piece unit indicator (101=Yes, 102=No)", "example": "102" }, "pieceUnitPrice": { "type": "string", "description": "Piece unit price (optional)", "example": "" }, "packageScaledValue": { "type": "string", "description": "Package scaled value (optional)", "example": "" }, "customsMeasureUnit": { "type": "string", "description": "Customs measure unit for exports (e.g., KGM)", "example": "KGM" }, "customsScaledValue": { "type": "string", "description": "Customs scaled value for exports (e.g., quantity in customs unit)", "example": "12" }, "customsUnitPrice": { "type": "string", "description": "Customs unit price for exports", "example": "2000000" }, "packageScaledValueCustoms": { "type": "string", "description": "Package scaled value for customs/export packaging", "example": "1" }, "pieceScaledValue": { "type": "string", "description": "Piece scaled value (optional)", "example": "" }, "exciseDutyCode": { "type": "string", "description": "Excise duty code (optional)", "example": "" }, "operationType": { "type": "string", "description": "Operation type (101=New registration, 102=Update existing) - Optional", "example": "102" } }, "required": [ "goodsName", "goodsCode", "measureUnit", "unitPrice", "currency", "commodityCategoryId", "haveExciseTax", "description", "stockPrewarning", "havePieceUnit" ] } }, "environment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" }, "deploymentEnvironment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" } }, "required": [ "products" ] } } } }, "responses": { "200": { "description": "Product registered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "0" }, "returnMessage": { "type": "string", "example": "SUCCESS" } } }, "data": { "type": "object", "description": "Registration response data from EFRIS" } } } } } }, "400": { "description": "Bad Request - Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "400" }, "returnMessage": { "type": "string", "example": "Products array is required in request body." } } }, "data": { "type": "string", "example": "Products array is required in request body." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "AUTHORIZATION_HEADER_MISSING" } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Authorization header is required" } } } } } } } }, "403": { "description": "Forbidden - Company not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "03" }, "returnMessage": { "type": "string", "example": "Company with TIN [1015264035] is not found in your account. Please add this company to your account first." } } }, "data": { "type": "object", "properties": { "tin": { "type": "string", "example": "1015264035" }, "status": { "type": "string", "example": "not_configured" }, "action_required": { "type": "string", "example": "Add this company to your account" } } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "500" }, "returnMessage": { "type": "string", "example": "An error occurred while processing the request." } } }, "data": { "type": "string", "example": "An error occurred while processing the request." } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/increase-stock": { "post": { "tags": [ "EFRIS" ], "summary": "Increase Stock with EFRIS", "description": "Increase stock levels for products in the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to record stock increases through various methods such as local purchases, imports, manufacturing, or opening stock. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send stock increase data in the specified JSON format\n4. **Response Handling**: Check the response status and message for success/error details\n\n## Stock In Types\n- **101**: Import\n- **102**: Local Purchase\n- **103**: Manufacture/Assembling\n- **104**: Opening Stock (called once after registering new item)\n\n## Important Rules\n- If `stockInType` is **103** (Manufacture/Assembling):\n - `supplierName` must be empty\n - `supplierTin` must be empty\n- If `stockInType` is **NOT 103** (Import, Local Purchase, or Opening Stock):\n - `productionBatchNo` must be empty\n - `productionDate` must be empty\n- For all other stock types, supplier information is required\n\n## Request Body Structure\n- **invoiceNo**: (Optional) Your own unique reference for this submission. Acts as an idempotency key to prevent duplicate stock increases β€” see the section below.\n- **remarks**: Additional notes about the stock increase\n- **stockInDate**: Date of stock increase (YYYY-MM-DD format)\n- **stockInType**: Type of stock increase (101, 102, 103, or 104)\n- **stockInItem**: Array of items with their quantities (supports decimals) and prices\n- **supplierName**: Name of the supplier (empty for type 103)\n- **supplierTin**: TIN of the supplier (empty for type 103)\n- **productionBatchNo**: Batch number for manufactured items (required for type 103, must be empty for all other types)\n- **productionDate**: Production date for manufactured items (required for type 103, must be empty for all other types)\n\n## Preventing Duplicate Stock Increases (invoiceNo)\nThe optional `invoiceNo` makes this call **safe to retry**, exactly like an invoice reference:\n- **Provide a unique `invoiceNo`** (any string you generate β€” e.g. your GRN or purchase reference) to protect a submission against being processed twice.\n- If a submission with that same `invoiceNo` **already succeeded** for your company (in the same environment), the duplicate is **ignored** and the **original successful result is returned** β€” stock is **NOT** increased again.\n- If a previous attempt with that `invoiceNo` **failed**, you are **allowed to resubmit** it (only successful submissions are locked).\n- If you **omit `invoiceNo`**, the request is processed normally with **no** duplicate protection (every call increases stock).\n- The check is scoped to **company TIN + environment**, so the same reference can be safely reused between **Sandbox** and **Production**. `invoiceNo` is used internally only and is **not** forwarded to URA/EFRIS.", "operationId": "increaseStockWithEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "stockInDate", "stockInType", "stockInItem" ], "properties": { "invoiceNo": { "type": "string", "description": "Optional client reference for this stock increase. When supplied it acts as an idempotency key (scoped to your company TIN and environment): once a submission with this invoiceNo succeeds, any later submission with the same invoiceNo is blocked and the original result is replayed. A previously failed submission with the same invoiceNo may be resubmitted. Omit it to process without duplicate protection.", "example": "" }, "remarks": { "type": "string", "description": "Additional remarks about the stock increase", "example": "" }, "branchId": { "type": "string", "description": "Branch ID - Only include if you have valid EFRIS branch IDs that belong to the current taxpayer", "example": "", "default": "" }, "stockInDate": { "type": "string", "format": "date", "description": "Date of stock increase in YYYY-MM-DD format", "example": "2025-09-05" }, "stockInType": { "type": "string", "description": "Type of stock increase: 101=Import, 102=Local Purchase, 103=Manufacture/Assembling, 104=Opening Stock", "enum": [ "101", "102", "103", "104" ], "example": "102" }, "stockInItem": { "type": "array", "description": "Array of items to increase stock for", "items": { "type": "object", "required": [ "itemCode", "quantity", "unitPrice" ], "properties": { "itemCode": { "type": "string", "description": "Code or name of the item", "example": "Sample Deemed Item" }, "quantity": { "type": "number", "description": "Quantity of items to add to stock (supports decimal values)", "example": 5000.5 }, "unitPrice": { "type": "number", "description": "Unit price of the item", "example": 2000 }, "measureUnit": { "type": "string", "description": "Unit of measure (e.g., PCE, KG, L). If not provided, will be fetched from efris items table", "example": "PCE" } } } }, "supplierName": { "type": "string", "description": "Name of the supplier (must be empty for stockInType 103)", "example": "Kikubo" }, "supplierTin": { "type": "string", "description": "TIN of the supplier (must be empty for stockInType 103)", "example": "1017196458" }, "productionBatchNo": { "type": "string", "description": "Production batch number (required for stockInType 103, must be empty for all other types)", "example": "" }, "productionDate": { "type": "string", "format": "date", "description": "Production date (required for stockInType 103, must be empty for all other types)", "example": "" }, "environment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" }, "deploymentEnvironment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" } } }, "example": { "invoiceNo": "STKIN-0001", "remarks": "", "branchId": "", "stockInDate": "2025-09-05", "stockInType": "102", "stockInItem": [ { "itemCode": "Sample Deemed Item", "quantity": 5000.5, "unitPrice": 2000, "measureUnit": "PCE" } ], "supplierName": "Kikubo", "supplierTin": "1017196458", "productionBatchNo": "", "productionDate": "" } } } }, "responses": { "200": { "description": "Stock increased successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Stock increased successfully" } } }, "data": { "type": "object", "description": "Stock increase response data from EFRIS" } } } } } }, "400": { "description": "Bad request - Invalid input data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "01" }, "returnMessage": { "type": "string", "example": "Invalid request data" } } } } } } } }, "401": { "description": "Authentication failed - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "Authentication failed" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "99" }, "returnMessage": { "type": "string", "example": "Internal server error" } } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/decrease-stock": { "post": { "tags": [ "EFRIS" ], "summary": "Decrease Stock with EFRIS", "description": "Decrease stock levels for products in the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to record stock decreases through various adjustment types such as expired goods, damaged goods, personal use, raw materials, or other reasons. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send stock decrease data in the specified JSON format\n4. **Response Handling**: Check the response status and message for success/error details\n\n## Adjust Types\n- **101**: Expired Goods\n- **102**: Damaged Goods\n- **103**: Personal Uses\n- **104**: Others (Please specify)\n- **105**: Raw Material(s)\n\n## Important Rules\n- If `adjustType` is **104** (Others):\n - `remarks` field cannot be empty - you must specify the reason\n- `adjustType` cannot be empty and must be one of the valid values\n- All other adjust types can have optional remarks\n\n## Request Body Structure\n- **remarks**: Additional notes about the stock decrease (required for adjustType 104)\n- **stockInItem**: Array of items with their quantities (supports decimals) and prices\n- **adjustType**: Type of stock adjustment (101, 102, 103, 104, or 105)", "operationId": "decreaseStockWithEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "stockInItem", "adjustType" ], "properties": { "remarks": { "type": "string", "description": "Additional remarks about the stock decrease (required for adjustType 104)", "example": "these things are expired man" }, "branchId": { "type": "string", "description": "Branch ID - Only include if you have valid EFRIS branch IDs that belong to the current taxpayer", "example": "", "default": "" }, "stockInItem": { "type": "array", "description": "Array of items to decrease stock for", "items": { "type": "object", "required": [ "quantity", "itemCode", "unitPrice" ], "properties": { "quantity": { "type": "number", "description": "Quantity of items to decrease from stock (supports decimal values)", "example": 2000.5 }, "itemCode": { "type": "string", "description": "Code or name of the item", "example": "Sample Deemed Item" }, "unitPrice": { "type": "number", "description": "Unit price of the item", "example": 30000 }, "itemName": { "type": "string", "description": "Name of the item (optional)", "example": null }, "measureUnit": { "type": "string", "description": "Unit of measure (e.g., PCE, KG, L). If not provided, will be fetched from efris items table", "example": "PCE" } } } }, "adjustType": { "type": "string", "description": "Type of stock adjustment: 101=Expired Goods, 102=Damaged Goods, 103=Personal Uses, 104=Others, 105=Raw Material(s)", "enum": [ "101", "102", "103", "104", "105" ], "example": "105" }, "environment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" }, "deploymentEnvironment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" } } }, "example": { "remarks": "these things are expired man", "branchId": "", "stockInItem": [ { "quantity": 2000.5, "itemCode": "Sample Deemed Item", "unitPrice": 30000, "itemName": null, "measureUnit": "PCE" } ], "adjustType": "105" } } } }, "responses": { "200": { "description": "Stock decreased successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Stock decreased successfully" } } }, "data": { "type": "object", "description": "Stock decrease response data from EFRIS" } } } } } }, "400": { "description": "Bad request - Invalid input data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "01" }, "returnMessage": { "type": "string", "example": "Invalid request data" } } } } } } } }, "401": { "description": "Authentication failed - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "Authentication failed" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "99" }, "returnMessage": { "type": "string", "example": "Internal server error" } } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/transfer-stock": { "post": { "tags": [ "EFRIS" ], "summary": "Transfer Stock between Branches with EFRIS", "description": "Transfer stock between branches in the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to move stock from one branch to another with proper tracking and validation. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send stock transfer data in the specified JSON format\n4. **Response Handling**: Check the response status and message for success/error details\n\n## Transfer Type Codes\n- **101**: Out of Stock Adjust\n- **102**: Error Adjust\n- **103**: Others (Please Specify)\n\n## Important Rules\n- **sourceBranchId** and **destinationBranchId** cannot be the same\n- **transferTypeCode** supports multiple selections separated by commas (e.g., '101,102')\n- If **transferTypeCode** contains **103** (Others):\n - **remarks** field cannot be empty - you must specify the reason\n- All other transfer types can have optional remarks\n\n## Request Body Structure\n- **goodsStockTransfer**: Transfer details including source/destination branches and transfer type\n- **goodsStockTransferItem**: Array of items to transfer with quantities and remarks", "operationId": "transferStockWithEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1000167000" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "goodsStockTransfer", "goodsStockTransferItem" ], "properties": { "goodsStockTransfer": { "type": "object", "required": [ "sourceBranchId", "destinationBranchId", "transferTypeCode" ], "properties": { "sourceBranchId": { "type": "string", "description": "The branchId of the source branch of the goods", "example": "243532684710600061" }, "destinationBranchId": { "type": "string", "description": "The branchId of the destination branch for the goods", "example": "231491647800100113" }, "transferTypeCode": { "type": "string", "description": "Transfer type code(s): 101=Out of Stock Adjust, 102=Error Adjust, 103=Others. Support multiple selections separated by commas (e.g., '101,102')", "example": "101" }, "remarks": { "type": "string", "description": "Additional remarks about the transfer (required for transferTypeCode 103)", "example": "Others" } } }, "goodsStockTransferItem": { "type": "array", "description": "Array of items to transfer between branches", "items": { "type": "object", "required": [ "itemCode", "quantity" ], "properties": { "itemCode": { "type": "string", "description": "Code or name of the item to transfer", "example": "2GB Mifi" }, "quantity": { "type": "string", "description": "Quantity of items to transfer", "example": "10" }, "remarks": { "type": "string", "description": "Additional remarks for this specific item", "example": "Others" } } } }, "environment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" }, "deploymentEnvironment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" } } }, "example": { "goodsStockTransfer": { "sourceBranchId": "243532684710600061", "destinationBranchId": "231491647800100113", "transferTypeCode": "101", "remarks": "Others" }, "goodsStockTransferItem": [ { "itemCode": "2GB Mifi", "quantity": "10", "remarks": "Others" } ] } } } }, "responses": { "200": { "description": "Stock transferred successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Stock transferred successfully" } } }, "data": { "type": "object", "description": "Stock transfer response data from EFRIS" } } } } } }, "400": { "description": "Bad request - Invalid input data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "01" }, "returnMessage": { "type": "string", "example": "Invalid request data" } } } } } } } }, "401": { "description": "Authentication failed - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "Authentication failed" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "99" }, "returnMessage": { "type": "string", "example": "Internal server error" } } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/registration-details": { "get": { "tags": [ "EFRIS" ], "summary": "Get Registration Details from EFRIS", "description": "Retrieve company registration details from the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to fetch comprehensive registration information for a specific company including business details, tax information, and compliance status. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send GET request with TIN parameter in the URL path\n4. **Response Handling**: Check the response status and message for success/error details\n\n## What You'll Get\n- Company registration information\n- Tax identification details\n- Business registration status\n- Compliance information\n- EFRIS integration status", "operationId": "getRegistrationDetailsFromEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "responses": { "200": { "description": "Registration details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Registration details retrieved successfully" } } }, "data": { "type": "object", "description": "Company registration details from EFRIS", "properties": { "tin": { "type": "string", "description": "Tax Identification Number", "example": "1015264035" }, "businessName": { "type": "string", "description": "Registered business name", "example": "WEAF Company Uganda Ltd" }, "registrationStatus": { "type": "string", "description": "Business registration status", "example": "Active" }, "registrationDate": { "type": "string", "format": "date", "description": "Date of business registration", "example": "2020-01-15" }, "businessType": { "type": "string", "description": "Type of business", "example": "Limited Company" }, "address": { "type": "string", "description": "Business address", "example": "Kampala, Uganda" }, "phone": { "type": "string", "description": "Business phone number", "example": "+256700000000" }, "email": { "type": "string", "format": "email", "description": "Business email address", "example": "info@weafcompany.com" }, "efrisStatus": { "type": "string", "description": "EFRIS integration status", "example": "Active" } } } } } } } }, "400": { "description": "Bad request - Invalid TIN or request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "01" }, "returnMessage": { "type": "string", "example": "Invalid request data" } } } } } } } }, "401": { "description": "Authentication failed - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "Authentication failed" } } } } } } } }, "403": { "description": "Forbidden - Company not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "03" }, "returnMessage": { "type": "string", "example": "COMPANY_NOT_FOUND_OR_INACTIVE" } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Company with TIN [1015264035] is not found in your account. Please add this company to your account first." }, "tin": { "type": "string", "example": "1015264035" }, "status": { "type": "string", "example": "not_configured" }, "action_required": { "type": "string", "example": "Add this company to your account" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "99" }, "returnMessage": { "type": "string", "example": "Internal server error" } } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/branches": { "get": { "tags": [ "EFRIS" ], "summary": "Get All Branches from EFRIS", "description": "Retrieve all branches for a company from the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to fetch a complete list of all branches associated with the company TIN. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send GET request with TIN parameter in the URL path\n4. **Response Handling**: Check the response status and message for success/error details\n\n## What You'll Get\n- List of all branches associated with the company\n- Branch IDs and names\n- Branch location information\n- Branch status and configuration details\n\n## Important Notes\n- This endpoint forwards requests to the inner EFRIS API\n- All requests are logged for audit purposes\n- Response times are tracked for performance monitoring\n- Failed requests are logged with detailed error information\n- **Token Parameter**: When you provide a token in the query parameter, it will be automatically used in the Authorization header as 'Bearer {token}'", "operationId": "getBranchesFromEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "responses": { "200": { "description": "Branches retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Branches retrieved successfully" } } }, "data": { "type": "object", "description": "Branches information from EFRIS including branch details, IDs, names, and locations" } } } } } }, "400": { "description": "Bad request - Invalid TIN or request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "01" }, "returnMessage": { "type": "string", "example": "Invalid request data" } } } } } } } }, "401": { "description": "Authentication failed - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "Authentication failed" } } } } } } } }, "403": { "description": "Forbidden - Company not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "03" }, "returnMessage": { "type": "string", "example": "COMPANY_NOT_FOUND_OR_INACTIVE" } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Company with TIN [1015264035] is not found in your account. Please add this company to your account first." }, "tin": { "type": "string", "example": "1015264035" }, "status": { "type": "string", "example": "not_configured" }, "action_required": { "type": "string", "example": "Add this company to your account" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "99" }, "returnMessage": { "type": "string", "example": "Internal server error" } } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/excise-duty": { "get": { "tags": [ "EFRIS" ], "summary": "Get Excise Duty Information from EFRIS", "description": "Retrieve excise duty information from the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to fetch comprehensive excise duty details for a specific company including duty rates, classifications, and compliance information. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send GET request with TIN parameter in the URL path\n4. **Response Handling**: Check the response status and message for success/error details\n\n## What You'll Get\n- Excise duty rates and classifications\n- Duty calculation information\n- Compliance status\n- Tax obligations\n- EFRIS integration status", "operationId": "getExciseDutyFromEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "responses": { "200": { "description": "Excise duty information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "Excise duty information retrieved successfully" } } }, "data": { "type": "object", "description": "Excise duty information from EFRIS", "properties": { "tin": { "type": "string", "description": "Tax Identification Number", "example": "1015264035" }, "exciseDutyRates": { "type": "array", "description": "List of excise duty rates and classifications", "items": { "type": "object", "properties": { "classification": { "type": "string", "description": "Product classification code", "example": "2203.00.00" }, "description": { "type": "string", "description": "Product description", "example": "Beer made from malt" }, "dutyRate": { "type": "number", "description": "Excise duty rate percentage", "example": 60 }, "unit": { "type": "string", "description": "Unit of measurement", "example": "Litre" } } } }, "complianceStatus": { "type": "string", "description": "Excise duty compliance status", "example": "Compliant" }, "lastUpdated": { "type": "string", "format": "date-time", "description": "Last update timestamp", "example": "2024-01-15T10:30:00Z" } } } } } } } }, "400": { "description": "Bad request - Invalid TIN or request data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "01" }, "returnMessage": { "type": "string", "example": "Invalid request data" } } } } } } } }, "401": { "description": "Authentication failed - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "Authentication failed" } } } } } } } }, "403": { "description": "Forbidden - Company not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "03" }, "returnMessage": { "type": "string", "example": "COMPANY_NOT_FOUND_OR_INACTIVE" } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Company with TIN [1015264035] is not found in your account. Please add this company to your account first." }, "tin": { "type": "string", "example": "1015264035" }, "status": { "type": "string", "example": "not_configured" }, "action_required": { "type": "string", "example": "Add this company to your account" } } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "99" }, "returnMessage": { "type": "string", "example": "Internal server error" } } } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/generate-fiscal-invoice": { "post": { "tags": [ "EFRIS" ], "summary": "Generate Fiscal Invoice with EFRIS", "description": "Generate fiscal invoices with the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to create compliant fiscal invoices for tax reporting and compliance purposes. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n- All items must be registered in the EFRIS system (use sync-products endpoint first)\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send invoice data in the specified JSON format\n4. **Response Handling**: Check the response status and message for success/error details\n\n## Required Field Validations\n\n### Seller Details (Required)\n- **placeOfBusiness**: Place of business address (required)\n- **referenceNo**: Reference number (required)\n- **issuedDate**: Invoice issue date and time (required)\n- **branchId**: ⚠️ **IMPORTANT**: Only include if you have valid EFRIS branch IDs that belong to the current taxpayer. If you don't have valid branch IDs or are unsure, omit this field completely to avoid validation errors.\n\n### Buyer Details (Required)\n- **buyerBusinessName**: Buyer business name (always required)\n- **buyerTin**: Required when buyerType is '0' or '3', optional when buyerType is '1' or '2'\n\n### Items (Required)\n- **itemCode**: Item code (required) - must exist in EFRIS items database\n- **unitPrice**: Unit price (required) - must be greater than 0\n- **quantity**: Quantity (required) - must be greater than 0\n- **total**: Total amount (required) - must equal unitPrice Γ— quantity\n\n## Business Logic & Validations\n\n### Flag Validations\n- **deemedFlag**: Must be either 1 or 2 (default: 2)\n- **discountFlag**: Must be either 1 or 2 (default: 2)\n- **exciseFlag**: Must be either 1 or 2 (default: 2)\n\n### Discount Logic\n- **discountFlag = 0 or 2**: discountTotal = \"\" (empty string)\n- **discountFlag = 1**: discountTotal must be greater than 0\n- **Percentage Support**: If discountTotal contains '%', it will be calculated as a percentage of the total amount\n\n### Tax Rule Logic\n- **Default Tax Rules** (from EFRIS items database):\n - If `isExempt = 101`: taxRule = 'EXEMPT'\n - If `isZeroRate = 101`: taxRule = 'ZERORATED'\n - Otherwise: taxRule = 'STANDARD'\n- **Deemed Logic**: If `deemedFlag = 1`, taxRule becomes 'DEEMED'\n- **Consistency Check**: If taxRule is 'DEEMED', deemedFlag must be 1\n\n### Deemed Project Auto-Obtainment\n- **Automatic**: If `deemedFlag = 1` but `vatProjectName` or `vatProjectId` is missing, the system will automatically:\n 1. Extract `buyerTin` from invoice data\n 2. Query `efris_items` table for `commodityCategoryCode`\n 3. Call the deemed project API to get project details\n 4. Auto-populate `vatProjectName` and `vatProjectId`\n- **Error Handling**: If no deemed projects are found, returns error asking user to ensure buyer TIN is configured with deemed projects\n\n### Excise Duty Validation\n- **When exciseFlag = 1**:\n - `exciseDutyCode` is required\n - Code must exist in `excise_duties` table\n - If code is a `parent_code`, system will automatically use the parent's `excise_duty_code`\n\n### Unit of Measure Logic\n- **Default**: Uses `unitOfMeasure` from request or `measureUnit` from EFRIS items\n- **Override**: If `havePieceUnit = 102` in EFRIS items, uses `measureUnit` from EFRIS items\n\n### Data Type Conversions\n- **Automatic Type Conversion**: All values are automatically converted to appropriate types (int, float, string)\n- **Null Handling**: Null values are converted to appropriate defaults (empty strings, 0, etc.)\n- **Default Values**:\n - `invoiceType`: 1 (if not provided)\n - `invoiceKind`: 1 (if not provided)\n - `paymentMode`: 101 (if not provided)\n - `currency`: 'UGX' (if not provided)\n - `deemedFlag`: 2 (if not provided)\n - `discountFlag`: 2 (if not provided)\n - `exciseFlag`: 2 (if not provided)\n\n## Error Response Format\nAll validation errors return a standardized JSON format:\n```json\n{\n \"data\": \"Error message describing the specific validation failure\",\n \"status\": {\n \"returnCode\": \"400\",\n \"returnMessage\": \"Error message describing the specific validation failure\"\n }\n}\n```\n\n## Important Notes\n- This endpoint forwards requests to the inner EFRIS API\n- All requests are logged for audit purposes\n- Response times are tracked for performance monitoring\n- Failed requests are logged with detailed error information\n- **Token Parameter**: When you provide a token in the query parameter, it will be automatically used in the Authorization header as 'Bearer {token}'\n- **Branch ID Error**: If you get \"branchId does not belong to current taxpayer\" error, remove the `branchId` field from your request\n- **Item Registration**: Ensure all items are registered in EFRIS using the sync-products endpoint before generating invoices\n- **Multi-tenancy**: All item lookups are filtered by company TIN to ensure data isolation", "operationId": "generateFiscalInvoiceWithEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sellerDetails": { "type": "object", "description": "Seller details for the invoice. Note: Only include 'branchId' if you have valid EFRIS branch IDs that belong to the current taxpayer, otherwise omit this field to avoid validation errors.", "properties": { "placeOfBusiness": { "type": "string", "description": "Place of business address", "example": "Wandera. Plot 28" }, "referenceNo": { "type": "string", "description": "Reference number", "example": "HDK637G" }, "issuedDate": { "type": "string", "description": "Invoice issue date and time", "example": "12/09/2024 21:11:08" }, "branchId": { "type": "string", "description": "Branch ID - Only include if you have valid EFRIS branch IDs that belong to the current taxpayer", "example": "", "default": "" }, "remarks": { "type": "string", "description": "Additional remarks or notes for the invoice", "example": "Special order" } }, "required": [ "placeOfBusiness", "referenceNo", "issuedDate" ] }, "basicInformation": { "type": "object", "properties": { "operator": { "type": "string", "description": "Operator name", "example": "Wandera" }, "currency": { "type": "string", "description": "Currency code", "example": "UGX" }, "invoiceType": { "type": "integer", "description": "Invoice type", "example": 1 }, "invoiceKind": { "type": "integer", "description": "Invoice kind", "example": 1 }, "paymentMode": { "type": "string", "description": "Payment mode", "example": "101" }, "invoiceIndustryCode": { "type": "string", "description": "Invoice industry code", "example": "101" } }, "required": [ "operator", "currency", "invoiceType", "invoiceKind", "paymentMode", "invoiceIndustryCode" ] }, "buyerDetails": { "type": "object", "properties": { "buyerTin": { "type": "string", "description": "Buyer TIN", "example": "1017196396" }, "buyerBusinessName": { "type": "string", "description": "Buyer business name", "example": "Wandera" }, "buyerAddress": { "type": "string", "description": "Buyer address", "example": "Kampala Road" }, "buyerEmail": { "type": "string", "description": "Buyer email", "example": "Wandera@road.com" }, "buyerLinePhone": { "type": "string", "description": "Buyer line phone", "example": "0756508361" }, "buyerMobilePhone": { "type": "string", "description": "Buyer mobile phone", "example": "0783291062" }, "buyerType": { "type": "string", "description": "Buyer type", "example": "0" }, "buyerNinBrn": { "type": "string", "description": "Buyer NIN/BRN", "example": "" }, "buyerPassportNum": { "type": "string", "description": "Buyer passport number", "example": "" } }, "required": [ "buyerTin", "buyerBusinessName", "buyerAddress", "buyerEmail", "buyerLinePhone", "buyerMobilePhone", "buyerType" ] }, "itemsBought": { "type": "array", "description": "Array of items purchased", "items": { "type": "object", "properties": { "itemCode": { "type": "string", "description": "Item code", "example": "Sample Deemed Item" }, "quantity": { "type": "number", "description": "Quantity", "example": 1 }, "unitPrice": { "type": "number", "description": "Unit price", "example": 2000000 }, "total": { "type": "number", "description": "Total amount", "example": 2000000 }, "taxForm": { "type": "string", "description": "Tax form", "example": "101" }, "taxRule": { "type": "string", "description": "Tax rule (STANDARD=18%, EXEMPT=0%, ZERORATED=0%)", "example": "STANDARD" }, "netAmount": { "type": "number", "description": "Net amount", "example": 1695000 }, "discountFlag": { "type": "integer", "description": "Discount flag (1=has discount, 2=no discount)", "example": 1 }, "deemedFlag": { "type": "integer", "description": "Deemed flag", "example": 2 }, "discountTotal": { "type": "string", "description": "Discount total (empty string if no discount)", "example": "5000" }, "exciseFlag": { "type": "string", "description": "Excise flag", "example": "2" }, "exciseRate": { "type": "string", "description": "Excise rate", "example": "" }, "exciseUnit": { "type": "string", "description": "Excise unit", "example": "" }, "exciseTax": { "type": "string", "description": "Excise tax", "example": "" }, "exciseCurrency": { "type": "string", "description": "Excise currency", "example": "UGX" } }, "required": [ "itemCode", "quantity", "unitPrice", "total", "taxForm", "taxRule", "netAmount", "discountFlag", "deemedFlag", "exciseFlag", "exciseCurrency" ] } } }, "required": [ "sellerDetails", "basicInformation", "buyerDetails", "itemsBought" ] }, "environment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" }, "deploymentEnvironment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "Fiscal invoice generated successfully. Extract the invoiceNumber, antifakeCode, and qrCode from the response for your invoice printout.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } } }, "data": { "type": "object", "description": "Invoice generation response data from EFRIS", "properties": { "basicInformation": { "type": "object", "description": "Basic invoice information", "properties": { "antifakeCode": { "type": "string", "description": "Anti-fake code for invoice validation - REQUIRED for printout", "example": "97532788341320080942" }, "invoiceNo": { "type": "string", "description": "Invoice number - REQUIRED for printout", "example": "325041520978" }, "issuedDate": { "type": "string", "description": "Invoice issue date", "example": "01/10/2025 10:21:20" }, "operator": { "type": "string", "description": "Operator name", "example": "Wandera" } } }, "summary": { "type": "object", "description": "Invoice summary information", "properties": { "qrCode": { "type": "string", "description": "QR code URL for invoice validation - REQUIRED for printout", "example": "https://efristest.ura.go.ug/site_new/#/invoiceValidation?invoiceNo=325041520978&antiFakeCode=97532788341320080942" }, "grossAmount": { "type": "string", "description": "Gross amount", "example": "1995000" }, "netAmount": { "type": "string", "description": "Net amount", "example": "1690677.96" }, "taxAmount": { "type": "string", "description": "Tax amount", "example": "304322.04" } } }, "sellerDetails": { "type": "object", "description": "Seller information", "properties": { "businessName": { "type": "string", "description": "Business name", "example": "KIYAAN INVESTMENTS (U) LTD" }, "tin": { "type": "string", "description": "Tax Identification Number", "example": "1015264035" }, "address": { "type": "string", "description": "Business address", "example": "150 SIXTH STREET NEXT TO KCB BANK INDUSTRIAL AREA KAMPALA" } } }, "buyerDetails": { "type": "object", "description": "Buyer information", "properties": { "buyerBusinessName": { "type": "string", "description": "Buyer business name", "example": "WEAF COMPANY UGANDA LIMITED" }, "buyerTin": { "type": "string", "description": "Buyer TIN", "example": "1017196396" }, "buyerAddress": { "type": "string", "description": "Buyer address", "example": "Kampala Road" } } }, "goodsDetails": { "type": "array", "description": "Array of goods/services in the invoice", "items": { "type": "object", "properties": { "item": { "type": "string", "description": "Item name", "example": "Sample Deemed Item" }, "itemCode": { "type": "string", "description": "Item code", "example": "Sample Deemed Item" }, "qty": { "type": "string", "description": "Quantity", "example": "1" }, "unitPrice": { "type": "string", "description": "Unit price", "example": "2000000" }, "total": { "type": "string", "description": "Total amount", "example": "2000000" }, "tax": { "type": "string", "description": "Tax amount", "example": "305084.75" } } } } } } } }, "example": { "status": { "returnCode": "00", "returnMessage": "SUCCESS" }, "data": { "basicInformation": { "antifakeCode": "97532788341320080942", "invoiceNo": "325041520978", "issuedDate": "01/10/2025 10:21:20", "operator": "Wandera" }, "summary": { "qrCode": "https://efristest.ura.go.ug/site_new/#/invoiceValidation?invoiceNo=325041520978&antiFakeCode=97532788341320080942", "grossAmount": "1995000", "netAmount": "1690677.96", "taxAmount": "304322.04" }, "sellerDetails": { "businessName": "KIYAAN INVESTMENTS (U) LTD", "tin": "1015264035", "address": "150 SIXTH STREET NEXT TO KCB BANK INDUSTRIAL AREA KAMPALA" }, "buyerDetails": { "buyerBusinessName": "WEAF COMPANY UGANDA LIMITED", "buyerTin": "1017196396", "buyerAddress": "Kampala Road" } } } } } }, "400": { "description": "Bad Request - Invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "400" }, "returnMessage": { "type": "string", "example": "Data object is required in request body." } } }, "data": { "type": "string", "example": "Data object is required in request body." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "AUTHORIZATION_HEADER_MISSING" } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Authorization header is required" } } } } } } } }, "403": { "description": "Forbidden - Company not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "03" }, "returnMessage": { "type": "string", "example": "Company with TIN [1015264035] is not found in your account. Please add this company to your account first." } } }, "data": { "type": "object", "properties": { "tin": { "type": "string", "example": "1015264035" }, "status": { "type": "string", "example": "not_configured" }, "action_required": { "type": "string", "example": "Add this company to your account" } } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "500" }, "returnMessage": { "type": "string", "example": "An error occurred while processing the request." } } }, "data": { "type": "string", "example": "An error occurred while processing the request." } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/generate-fiscal-receipt": { "post": { "tags": [ "EFRIS" ], "summary": "Generate Fiscal Receipt with EFRIS", "description": "Generate fiscal receipts with the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to create compliant fiscal receipts for tax reporting and compliance purposes. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n- All items must be registered in the EFRIS system (use sync-products endpoint first)\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send receipt data in the specified JSON format\n4. **Response Handling**: Check the response status and message for success/error details\n\n## Required Field Validations\n\n### Seller Details (Required)\n- **referenceNo**: Reference number (required)\n- **issuedDate**: Receipt issue date and time (required)\n\n### Basic Information (Required)\n- **operator**: Operator name (required)\n- **currency**: Currency code (default: UGX)\n- **paymentMode**: Payment mode (default: 101)\n- **invoiceIndustryCode**: Invoice industry code (default: 101)\n- **isPreview**: Preview flag (0 or 1, default: 0)\n- **isRefund**: Refund flag (0 or 1, default: 0)\n\n### Buyer Details (Required)\n- **buyerTin**: Buyer TIN (required)\n- **buyerBusinessName**: Buyer business name (required)\n- **buyerLegalName**: Buyer legal name (required)\n- **buyerType**: Buyer type (required)\n- **buyerAddress**: Buyer address (required)\n- **buyerEmail**: Buyer email (required)\n- **buyerLinePhone**: Buyer line phone (required)\n- **buyerMobilePhone**: Buyer mobile phone (required)\n\n### Items (Required)\n- **itemCode**: Item code or name (required) - must exist in EFRIS items database (searches by goodsCode or goodsName)\n- **quantity**: Quantity (required) - must be greater than 0\n- **unitPrice**: Unit price (required) - must be greater than 0\n- **total**: Total amount (required) - must equal unitPrice Γ— quantity\n- **unitOfMeasure**: Unit of measure (optional - will be fetched from EFRIS items if not provided)\n- **discountFlag**: Discount flag (1=has discount, 2=no discount, default: 2)\n- **discountTotal**: Discount amount (required if discountFlag=1, empty string if discountFlag=2)\n\n## Business Logic & Validations\n\n### Discount Logic\n- **discountFlag = 2**: discountTotal = \"\" (empty string)\n- **discountFlag = 1**: discountTotal must be provided and greater than 0\n- **Percentage Support**: If discountTotal contains '%', it will be calculated as a percentage of the total amount\n- Discounts are processed automatically before payment calculation\n\n### Payment Calculation (Auto-Computed)\n- **payWay**: This field is automatically computed by the API and should NOT be passed by the user\n- The API calculates the total payment amount based on:\n - Sum of all item totals (after discounts are applied)\n - Payment mode from basicInformation\n- If payWay is provided in the request, it will be automatically removed and recomputed\n\n### Item Lookup Logic\n- **Flexible Matching**: The system searches for items by both `goodsCode` and `goodsName`\n- If an item is found by name, the `itemCode` in the request is automatically replaced with the correct `goodsCode` from the database\n- **Unit of Measure**: If not provided, uses `measureUnit` from EFRIS items database\n- **Item Validation**: All items must exist in the `efris_items` table for the company TIN\n\n### Data Type Conversions\n- **Automatic Type Conversion**: All values are automatically converted to appropriate types (int, float, string)\n- **Null Handling**: Null values are converted to appropriate defaults (empty strings, 0, etc.)\n- **Default Values**:\n - `currency`: 'UGX' (if not provided)\n - `paymentMode`: '101' (if not provided)\n - `invoiceIndustryCode`: '101' (if not provided)\n - `isPreview`: '0' (if not provided)\n - `isRefund`: '0' (if not provided)\n - `buyerType`: '1' (if not provided)\n - `discountFlag`: '2' (if not provided)\n\n## Error Response Format\nAll validation errors return a standardized JSON format:\n```json\n{\n \"data\": \"Error message describing the specific validation failure\",\n \"status\": {\n \"returnCode\": \"400\",\n \"returnMessage\": \"Error message describing the specific validation failure\"\n }\n}\n```\n\n## Important Notes\n- This endpoint forwards requests to the inner EFRIS API\n- All requests are logged for audit purposes\n- Response times are tracked for performance monitoring\n- Failed requests are logged with detailed error information\n- **Token Parameter**: When you provide a token in the query parameter, it will be automatically used in the Authorization header as 'Bearer {token}'\n- **Item Registration**: Ensure all items are registered in EFRIS using the sync-products endpoint before generating receipts\n- **Multi-tenancy**: All item lookups are filtered by company TIN to ensure data isolation\n- **Auto-Computed Fields**: Do not include `payWay` in your request - it will be automatically calculated and added", "operationId": "generateFiscalReceiptWithEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1017196396" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "sellerDetails", "basicInformation", "buyerDetails", "itemsBought" ], "properties": { "sellerDetails": { "type": "object", "description": "Seller details for the receipt", "required": [ "referenceNo", "issuedDate" ], "properties": { "referenceNo": { "type": "string", "description": "Reference number", "example": "DWHDK620" }, "issuedDate": { "type": "string", "description": "Receipt issue date and time", "example": "12/09/2024 21:11:08" }, "branchId": { "type": "string", "description": "Branch ID - Only include if you have valid EFRIS branch IDs that belong to the current taxpayer", "example": "", "default": "" }, "remarks": { "type": "string", "description": "Additional remarks or notes for the receipt", "example": "Special order" } } }, "basicInformation": { "type": "object", "description": "Basic receipt information", "required": [ "operator", "currency", "paymentMode", "invoiceIndustryCode" ], "properties": { "operator": { "type": "string", "description": "Operator name", "example": "Wandera" }, "currency": { "type": "string", "description": "Currency code", "example": "UGX" }, "paymentMode": { "type": "string", "description": "Payment mode", "example": "101" }, "invoiceIndustryCode": { "type": "string", "description": "Invoice industry code", "example": "101" }, "isPreview": { "type": "string", "description": "Preview flag (0=No, 1=Yes)", "enum": [ "0", "1" ], "example": "0" }, "isRefund": { "type": "string", "description": "Refund flag (0=No, 1=Yes)", "enum": [ "0", "1" ], "example": "0" } } }, "buyerDetails": { "type": "object", "description": "Buyer details for the receipt", "required": [ "buyerTin", "buyerBusinessName", "buyerLegalName", "buyerType", "buyerAddress", "buyerEmail", "buyerLinePhone", "buyerMobilePhone" ], "properties": { "buyerTin": { "type": "string", "description": "Buyer TIN", "example": "1009609781" }, "buyerBusinessName": { "type": "string", "description": "Buyer business name", "example": "Wandera" }, "buyerLegalName": { "type": "string", "description": "Buyer legal name", "example": "Wandera" }, "buyerType": { "type": "string", "description": "Buyer type", "example": "1" }, "buyerAddress": { "type": "string", "description": "Buyer address", "example": "Kampala Road" }, "buyerEmail": { "type": "string", "format": "email", "description": "Buyer email", "example": "Wandera@road.com" }, "buyerLinePhone": { "type": "string", "description": "Buyer line phone", "example": "0756508361" }, "buyerMobilePhone": { "type": "string", "description": "Buyer mobile phone", "example": "0783291062" } } }, "itemsBought": { "type": "array", "description": "Array of items purchased. Note: itemCode can be either goodsCode or goodsName - the system will automatically find and use the correct goodsCode.", "minItems": 1, "items": { "type": "object", "required": [ "itemCode", "quantity", "unitPrice", "total" ], "properties": { "itemCode": { "type": "string", "description": "Item code or name (searches by goodsCode or goodsName in EFRIS database)", "example": "24523" }, "quantity": { "type": "number", "description": "Quantity of items", "minimum": 0.01, "example": 1 }, "unitPrice": { "type": "number", "description": "Unit price", "minimum": 0.01, "example": 2000000 }, "total": { "type": "number", "description": "Total amount (should equal unitPrice Γ— quantity)", "minimum": 0.01, "example": 2000000 }, "unitOfMeasure": { "type": "string", "description": "Unit of measure (e.g., KGM, PCE, L). If not provided, will be fetched from EFRIS items database", "example": "KGM" }, "discountFlag": { "type": "string", "description": "Discount flag (1=has discount, 2=no discount)", "enum": [ "1", "2" ], "example": "1" }, "discountTotal": { "type": "string", "description": "Discount amount (required if discountFlag=1, empty string if discountFlag=2). Supports percentage values (e.g., '10%')", "example": "500000" } } } } } }, "environment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" }, "deploymentEnvironment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" } } }, "example": { "data": { "sellerDetails": { "referenceNo": "DWHDK620", "issuedDate": "12/09/2024 21:11:08" }, "basicInformation": { "operator": "Wandera", "currency": "UGX", "paymentMode": "101", "invoiceIndustryCode": "101", "isPreview": "0", "isRefund": "0" }, "buyerDetails": { "buyerTin": "1009609781", "buyerBusinessName": "Wandera", "buyerLegalName": "Wandera", "buyerType": "1", "buyerAddress": "Kampala Road", "buyerEmail": "Wandera@road.com", "buyerLinePhone": "0756508361", "buyerMobilePhone": "0783291062" }, "itemsBought": [ { "itemCode": "24523", "quantity": 1, "unitPrice": 2000000, "total": 2000000, "unitOfMeasure": "KGM", "discountFlag": "1", "discountTotal": "500000" } ] } } } } }, "responses": { "200": { "description": "Fiscal receipt generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } } }, "data": { "type": "object", "description": "Receipt generation response data from EFRIS" } } } } } }, "400": { "description": "Bad Request - Invalid request body or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "400" }, "returnMessage": { "type": "string", "example": "Data object is required in request body. Please ensure your request contains a \"data\" object with the receipt information." } } }, "data": { "type": "string", "example": "Data object is required in request body. Please ensure your request contains a \"data\" object with the receipt information." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "AUTHORIZATION_HEADER_MISSING" } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Authorization header is required" } } } } } } } }, "403": { "description": "Forbidden - Company not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "03" }, "returnMessage": { "type": "string", "example": "Company with TIN [1017196396] is not found in your account. Please add this company to your account first." } } }, "data": { "type": "object", "properties": { "tin": { "type": "string", "example": "1017196396" }, "status": { "type": "string", "example": "not_configured" }, "action_required": { "type": "string", "example": "Add this company to your account" } } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "500" }, "returnMessage": { "type": "string", "example": "An error occurred while processing the request." } } }, "data": { "type": "string", "example": "An error occurred while processing the request." } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/apply-for-creditnote": { "post": { "tags": [ "EFRIS" ], "summary": "Apply for Credit Note (Cancel or Refund Invoice) with EFRIS", "description": "Apply for a credit note to cancel or refund an invoice with the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to cancel invoices or request refunds for various reasons such as product returns, cancellations, invoice errors, or waivers. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n- Valid invoice number that exists in EFRIS\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send credit note application data in the specified JSON format\n4. **Response Handling**: Check the response status and message for success/error details\n\n## Reason Codes (dictionaryrefundReason)\n- **101**: Return of products due to expiry or damage, etc.\n- **102**: Cancellation of the purchase.\n- **103**: Invoice amount wrongly stated due to miscalculation of price, tax, or discounts, etc.\n- **104**: Partial or complete waive off of the product sale after the invoice is generated and sent to customer.\n- **105**: Others (Please specify)\n\n## Required Fields\n- **generalInfo**: Object containing credit note application details\n - **oriInvoiceNo**: Invoice number of the invoice being cancelled (required)\n - **reasonCode**: Reason code for cancellation (101-105) (required)\n - **reason**: Description of the reason for cancellation (required)\n - **invoiceApplyCategoryCode**: Must be \"101\" (required)\n - **remarks**: Additional remarks (optional)\n - **sellersReferenceNo**: Reference number of the credit note (required)\n\n## Important Notes\n- This endpoint forwards requests to the inner EFRIS API\n- All requests are logged for audit purposes\n- Response times are tracked for performance monitoring\n- Failed requests are logged with detailed error information\n- **Token Parameter**: When you provide a token in the query parameter, it will be automatically used in the Authorization header as 'Bearer {token}'\n- **Invoice Validation**: The invoice number must exist in EFRIS and belong to the company\n- **Reference Number**: The sellersReferenceNo should be unique for each credit note application", "operationId": "applyForCreditNoteWithEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "generalInfo" ], "properties": { "generalInfo": { "type": "object", "description": "Credit note application information", "required": [ "oriInvoiceNo", "reasonCode", "reason", "invoiceApplyCategoryCode", "sellersReferenceNo" ], "properties": { "oriInvoiceNo": { "type": "string", "description": "Invoice number of the invoice being cancelled", "example": "325042480522" }, "reasonCode": { "type": "string", "description": "Reason code for cancellation: 101=Return of products, 102=Cancellation of purchase, 103=Invoice amount wrongly stated, 104=Partial or complete waive off, 105=Others", "enum": [ "101", "102", "103", "104", "105" ], "example": "102" }, "reason": { "type": "string", "description": "Description of the reason for cancellation", "example": "Cancellation of the purchase." }, "invoiceApplyCategoryCode": { "type": "string", "description": "Invoice apply category code (must be 101)", "enum": [ "101" ], "example": "101" }, "remarks": { "type": "string", "description": "Additional remarks about the credit note application", "example": "sdgds" }, "sellersReferenceNo": { "type": "string", "description": "Reference number of the credit note", "example": "40V2" } } }, "environment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" }, "deploymentEnvironment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" } } }, "example": { "generalInfo": { "oriInvoiceNo": "325042480522", "reasonCode": "102", "reason": "Cancellation of the purchase.", "invoiceApplyCategoryCode": "101", "remarks": "sdgds", "sellersReferenceNo": "40V2" } } } } }, "responses": { "200": { "description": "Credit note application submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } } }, "data": { "type": "object", "description": "Credit note application response from EFRIS", "properties": { "referenceNo": { "type": "string", "description": "Reference number of the credit note", "example": "26PL023007440" } } } } }, "example": { "status": { "returnCode": "00", "returnMessage": "SUCCESS" }, "data": { "referenceNo": "26PL023007440" } } } } }, "400": { "description": "Bad Request - Invalid request body or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "400" }, "returnMessage": { "type": "string", "example": "generalInfo is required in request body." } } }, "data": { "type": "string", "example": "generalInfo is required in request body." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "AUTHORIZATION_HEADER_MISSING" } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Authorization header is required" } } } } } } } }, "403": { "description": "Forbidden - Company not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "03" }, "returnMessage": { "type": "string", "example": "Company with TIN [1015264035] is not found in your account. Please add this company to your account first." } } }, "data": { "type": "object", "properties": { "tin": { "type": "string", "example": "1015264035" }, "status": { "type": "string", "example": "not_configured" }, "action_required": { "type": "string", "example": "Add this company to your account" } } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "500" }, "returnMessage": { "type": "string", "example": "An error occurred while processing the request." } } }, "data": { "type": "string", "example": "An error occurred while processing the request." } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/invoice-receipt-query": { "post": { "tags": [ "EFRIS" ], "summary": "Query Invoice Receipts from EFRIS", "description": "Query and retrieve invoice receipts from the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to search for invoices based on various criteria such as buyer information, date range, and invoice type. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send query parameters in the specified JSON format\n4. **Response Handling**: Check the response status and message for success/error details\n\n## Query Parameters\n- **buyerLegalName**: Search by buyer's legal name (optional)\n- **startDate**: Start date for date range query (optional)\n- **endDate**: End date for date range query (optional)\n- **invoiceKind**: Type of invoice to query (required)\n- **pageNo**: Page number for pagination (required)\n- **pageSize**: Number of results per page (required)\n\n## Important Notes\n- This endpoint forwards requests to the inner EFRIS API\n- All requests are logged for audit purposes\n- Response times are tracked for performance monitoring\n- Failed requests are logged with detailed error information\n- **Token Parameter**: When you provide a token in the query parameter, it will be automatically used in the Authorization header as 'Bearer {token}'", "operationId": "invoiceReceiptQueryWithEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "buyerLegalName": { "type": "string", "description": "Buyer's legal name to search for (optional)", "example": "" }, "startDate": { "type": "string", "description": "Start date for date range query (optional)", "example": "" }, "endDate": { "type": "string", "description": "End date for date range query (optional)", "example": "" }, "invoiceKind": { "type": "string", "description": "Type of invoice to query", "example": "1" }, "pageNo": { "type": "string", "description": "Page number for pagination", "example": "1" }, "pageSize": { "type": "string", "description": "Number of results per page", "example": "10" }, "environment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" }, "deploymentEnvironment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" } }, "required": [ "invoiceKind", "pageNo", "pageSize" ] } } } }, "responses": { "200": { "description": "Invoice receipt query completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } } }, "data": { "type": "object", "description": "Invoice receipt query results from EFRIS" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "AUTHORIZATION_HEADER_MISSING" } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Authorization header is required" } } } } } } } }, "403": { "description": "Forbidden - Company not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "03" }, "returnMessage": { "type": "string", "example": "Company with TIN [1015264035] is not found in your account. Please add this company to your account first." } } }, "data": { "type": "object", "properties": { "tin": { "type": "string", "example": "1015264035" }, "status": { "type": "string", "example": "not_configured" }, "action_required": { "type": "string", "example": "Add this company to your account" } } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "500" }, "returnMessage": { "type": "string", "example": "An error occurred while processing the request." } } }, "data": { "type": "string", "example": "An error occurred while processing the request." } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/query-purchase-invoices": { "post": { "tags": [ "EFRIS" ], "summary": "Query Purchase Invoices from EFRIS", "description": "Query and retrieve purchase invoices from the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to search for purchase invoices based on seller information and date range. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send query parameters in the specified JSON format\n4. **Response Handling**: Check the response status and message for success/error details\n\n## Query Parameters\n- **sellerTinOrNin**: Seller's Tax Identification Number or National ID (optional - pass empty string if not provided)\n- **sellerLegalOrBusinessName**: Seller's legal or business name (optional - pass empty string if not provided)\n- **startDate**: Start date for date range query in yyyy-MM-dd format (optional - pass empty string if not provided)\n- **endDate**: End date for date range query in yyyy-MM-dd format (optional - pass empty string if not provided)\n\n## Date Format\n- **Format**: yyyy-MM-dd (e.g., 2024-01-01)\n- **Validation**: Dates must be in the specified format. Invalid date formats will result in validation errors.\n\n## Important Notes\n- This endpoint forwards requests to the inner EFRIS API\n- All requests are logged for audit purposes\n- Response times are tracked for performance monitoring\n- Failed requests are logged with detailed error information\n- **Token Parameter**: When you provide a token in the query parameter, it will be automatically used in the Authorization header as 'Bearer {token}'\n- **Empty Fields**: All fields are optional. Pass empty strings (\"\") for fields you don't want to filter by", "operationId": "queryPurchaseInvoicesWithEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sellerTinOrNin": { "type": "string", "description": "Seller's Tax Identification Number or National ID (optional - pass empty string if not provided)", "example": "1009837013" }, "sellerLegalOrBusinessName": { "type": "string", "description": "Seller's legal or business name (optional - pass empty string if not provided)", "example": "CLASSY TRENDS BOUTIQUE" }, "startDate": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date for date range query in yyyy-MM-dd format (optional - pass empty string if not provided)", "example": "2024-01-01" }, "endDate": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date for date range query in yyyy-MM-dd format (optional - pass empty string if not provided)", "example": "2024-12-31" }, "environment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" }, "deploymentEnvironment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" } } }, "example": { "sellerTinOrNin": "1009837013", "sellerLegalOrBusinessName": "CLASSY TRENDS BOUTIQUE", "startDate": "2024-01-01", "endDate": "2024-12-31" } } } }, "responses": { "200": { "description": "Purchase invoice query completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } } }, "data": { "type": "object", "description": "Purchase invoice query results from EFRIS" } } } } } }, "400": { "description": "Bad Request - Invalid request body or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "01" }, "returnMessage": { "type": "string", "example": "VALIDATION_ERROR" } } }, "data": { "type": "object", "properties": { "errors": { "type": "object", "description": "Validation error details", "example": { "startDate": [ "The startDate must be in yyyy-MM-dd format." ], "endDate": [ "The endDate must be in yyyy-MM-dd format." ] } } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "AUTHORIZATION_HEADER_MISSING" } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Authorization header is required" } } } } } } } }, "403": { "description": "Forbidden - Company not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "03" }, "returnMessage": { "type": "string", "example": "Company with TIN [1015264035] is not found in your account. Please add this company to your account first." } } }, "data": { "type": "object", "properties": { "tin": { "type": "string", "example": "1015264035" }, "status": { "type": "string", "example": "not_configured" }, "action_required": { "type": "string", "example": "Add this company to your account" } } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "500" }, "returnMessage": { "type": "string", "example": "An error occurred while processing the request." } } }, "data": { "type": "string", "example": "An error occurred while processing the request." } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/invoice-details/{invoiceNo}": { "get": { "tags": [ "EFRIS" ], "summary": "Get Invoice Details from EFRIS", "description": "Retrieve detailed information for a specific invoice from the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to fetch complete invoice details including all items, tax information, and validation data using the invoice number. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n- Valid invoice number\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Invoice Number**: Provide the invoice number in the URL path\n4. **Response Handling**: Check the response status and message for success/error details\n\n## Path Parameters\n- **tin**: Company Tax Identification Number (TIN) - Must be configured in your account\n- **invoiceNo**: Invoice number to retrieve details for\n\n## Important Notes\n- This endpoint forwards requests to the inner EFRIS API\n- All requests are logged for audit purposes\n- Response times are tracked for performance monitoring\n- Failed requests are logged with detailed error information\n- **Token Parameter**: When you provide a token in the query parameter, it will be automatically used in the Authorization header as 'Bearer {token}'", "operationId": "getInvoiceDetailsFromEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "invoiceNo", "in": "path", "description": "Invoice number to retrieve details for", "required": true, "schema": { "type": "string", "example": "324036555841" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "responses": { "200": { "description": "Invoice details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } } }, "data": { "type": "object", "description": "Complete invoice details from EFRIS including all items, tax information, and validation data" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "AUTHORIZATION_HEADER_MISSING" } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Authorization header is required" } } } } } } } }, "403": { "description": "Forbidden - Company not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "03" }, "returnMessage": { "type": "string", "example": "Company with TIN [1015264035] is not found in your account. Please add this company to your account first." } } }, "data": { "type": "object", "properties": { "tin": { "type": "string", "example": "1015264035" }, "status": { "type": "string", "example": "not_configured" }, "action_required": { "type": "string", "example": "Add this company to your account" } } } } } } } }, "404": { "description": "Not Found - Invoice not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "04" }, "returnMessage": { "type": "string", "example": "Invoice not found" } } }, "data": { "type": "string", "example": "Invoice with number 324036555841 not found" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "500" }, "returnMessage": { "type": "string", "example": "An error occurred while processing the request." } } }, "data": { "type": "string", "example": "An error occurred while processing the request." } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/search-taxpayer": { "post": { "tags": [ "EFRIS" ], "summary": "Search Taxpayer Details from EFRIS", "description": "Search taxpayer details from the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to look up taxpayer information using TIN or NIN/BRN. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send search parameters in the specified JSON format\n4. **Response Handling**: Check the response status and message for success/error details\n\n## Search Parameters\n- **tin**: Tax Identification Number to search for (required)\n- **ninBrn**: National ID or Business Registration Number (optional)\n\n## Important Notes\n- This endpoint forwards requests to the inner EFRIS API\n- All requests are logged for audit purposes\n- Response times are tracked for performance monitoring\n- Failed requests are logged with detailed error information\n- **Token Parameter**: When you provide a token in the query parameter, it will be automatically used in the Authorization header as 'Bearer {token}'", "operationId": "searchTaxpayerWithEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tin": { "type": "string", "description": "Tax Identification Number to search for", "example": "1017196396" }, "ninBrn": { "type": "string", "description": "National ID or Business Registration Number (optional)", "example": "" }, "environment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" }, "deploymentEnvironment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" } }, "required": [ "tin" ] } } } }, "responses": { "200": { "description": "Taxpayer details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "00" }, "returnMessage": { "type": "string", "example": "SUCCESS" } } }, "data": { "type": "object", "description": "Taxpayer details from EFRIS including business information, contact details, and status" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "02" }, "returnMessage": { "type": "string", "example": "AUTHORIZATION_HEADER_MISSING" } } }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Authorization header is required" } } } } } } } }, "403": { "description": "Forbidden - Company not found or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "03" }, "returnMessage": { "type": "string", "example": "Company with TIN [1015264035] is not found in your account. Please add this company to your account first." } } }, "data": { "type": "object", "properties": { "tin": { "type": "string", "example": "1015264035" }, "status": { "type": "string", "example": "not_configured" }, "action_required": { "type": "string", "example": "Add this company to your account" } } } } } } } }, "404": { "description": "Not Found - Taxpayer not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "04" }, "returnMessage": { "type": "string", "example": "Taxpayer not found" } } }, "data": { "type": "string", "example": "Taxpayer with TIN 1017196396 not found" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "500" }, "returnMessage": { "type": "string", "example": "An error occurred while processing the request." } } }, "data": { "type": "string", "example": "An error occurred while processing the request." } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/query-taxpayer-deemed-project": { "post": { "tags": [ "EFRIS" ], "summary": "Query Taxpayer Deemed Project from EFRIS", "description": "Query deemed projects for a specific taxpayer from the EFRIS (Electronic Fiscal Receipting and Invoicing Solution) system. This endpoint allows you to retrieve information about deemed projects associated with a taxpayer's TIN. The endpoint requires proper authentication and the company TIN must be configured in your account.\n\n## Prerequisites\n- Valid API access token\n- Company TIN must be configured in your account\n- Company must be active\n\n## Usage Instructions\n1. **Authentication**: \n - **Option A**: Login to your account and generate a token on the dashboard\n - **Option B**: Login via the API under Authentication and obtain the token to be using\n\n Please note, you must have registered for an account, if not, [click here to register](/register){:target=\"_blank\"}\n\n Testing API is free but production, you must have an active subscription, or login and subscribe\n2. **Company Setup**: Ensure the TIN is added to your account and activated\n3. **Request Format**: Send POST request with TIN in the URL path and request body with optional commodity category codes\n4. **Response**: Returns deemed project information from EFRIS\n\n## Request Parameters\n- **tin**: Tax Identification Number (required in URL path)\n- **commodityCategoryCode**: Comma-separated list of commodity category codes (optional)\n\n## Use Cases\n- **Deemed Project Lookup**: Query deemed projects for specific taxpayers\n- **Commodity Filtering**: Filter results by commodity category codes\n- **Compliance**: Verify deemed project information for tax compliance\n\n## Important Notes\n- This endpoint forwards requests to the inner EFRIS API\n- All requests are logged for audit purposes\n- Response times are tracked for performance monitoring\n- Failed requests are logged with detailed error information\n- **Token Parameter**: When you provide a token in the query parameter, it will be automatically used in the Authorization header as 'Bearer {token}'", "operationId": "queryTaxpayerDeemedProjectWithEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tin": { "type": "string", "description": "Tax Identification Number (automatically set from URL path)", "example": "1017196396" }, "commodityCategoryCode": { "type": "string", "description": "Comma-separated list of commodity category codes (optional)", "example": "10111301,10101501" }, "environment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" }, "deploymentEnvironment": { "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "type": "string", "enum": [ "Production", "Sandbox" ], "example": "Sandbox", "default": "Sandbox" } }, "required": [ "tin" ] } } } }, "responses": { "200": { "description": "Taxpayer deemed project query completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "0" }, "returnMessage": { "type": "string", "example": "Taxpayer deemed project query completed successfully" } } }, "data": { "type": "object", "description": "Deemed project information from EFRIS including project details and commodity information" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "401" }, "returnMessage": { "type": "string", "example": "Unauthorized - Invalid or missing token" } } }, "data": { "type": "string", "example": "Unauthorized - Invalid or missing token" } } } } } }, "403": { "description": "Forbidden - TIN not configured or inactive", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "03" }, "returnMessage": { "type": "string", "example": "Company with TIN [1015264035] is not found in your account. Please add this company to your account first." } } }, "data": { "type": "object", "properties": { "tin": { "type": "string", "example": "1015264035" }, "status": { "type": "string", "example": "not_configured" }, "action_required": { "type": "string", "example": "Add this company to your account" } } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "returnCode": { "type": "string", "example": "500" }, "returnMessage": { "type": "string", "example": "An error occurred while processing the request." } } }, "data": { "type": "string", "example": "An error occurred while processing the request." } } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/{tin}/master-data": { "get": { "tags": [ "EFRIS" ], "summary": "Fetch Master Data from EFRIS", "description": "Retrieve master data configuration from the EFRIS system. This endpoint allows you to fetch the raw master data which includes various system parameters and configuration details for the taxpayer. The endpoint requires proper authentication and the company TIN must be configured in your account.", "operationId": "fetchMasterDataFromEfris", "parameters": [ { "name": "tin", "in": "path", "description": "Company Tax Identification Number (TIN) - Must be configured in your account", "required": true, "schema": { "type": "string", "example": "1015264035" } }, { "name": "token", "in": "query", "description": "API Access Token - This token will be automatically used in the Authorization header. You can also set it globally using the Authorize button above.", "required": false, "schema": { "type": "string", "default": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw", "example": "4MzipIh4RL8Gqnl0ueDpO3qisHijb7ZmW6sMgexmXR5fpxQ6y9172vfzH5UrGaBw" }, "x-swagger-ui": { "description": "Enter your access token here. It will be automatically added to the Authorization header as 'Bearer {token}' when you make the request.", "auto-authorize": true } }, { "name": "X-Environment", "in": "header", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } }, { "name": "environment", "in": "query", "description": "Target environment (Needed/Required, e.g., Production or Sandbox)", "required": false, "schema": { "type": "string", "enum": [ "Production", "Sandbox" ], "default": "Sandbox" } } ], "responses": { "200": { "description": "Master data retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized - Invalid or missing token" }, "403": { "description": "Forbidden - Company TIN not configured or inactive" }, "500": { "description": "Internal Server Error - EFRIS system error" } }, "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. Includes user authentication, company access control, and comprehensive security features." }, { "name": "EFRIS", "description": "πŸ›οΈ EFRIS Integration - Electronic Fiscal Receipting and Invoicing Solution integration with Uganda Revenue Authority (URA). Search taxpayers, generate fiscal receipts, manage compliance reporting, and automate tax-related business processes." } ] }