{ "openapi": "3.0.0", "info": { "title": "SimpleISP API", "description": "This is the API documentation for SimpleISP. Please note a valid API Key is required to access any of the API URLs.", "version": "1.0" }, "paths": { "/api/clients": { "get": { "tags": [ "Clients" ], "summary": "Get All Clients", "description": "Retrieve a list of all clients with their associated services.\nA valid API key (`x-api-key`) must be included in the request `header` for authentication.", "operationId": "getAllClients", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "TotalClients": { "description": "Total number of clients", "type": "integer", "example": 225 }, "OnlineServicesRevenue": { "description": "Total revenue from online services", "type": "number", "format": "float", "example": 0 }, "ActiveServicesRevenue": { "description": "Total revenue from active services", "type": "number", "format": "float", "example": 2500 }, "InactiveServicesRevenue": { "description": "Total revenue from inactive services", "type": "number", "format": "float", "example": 0 }, "clients": { "type": "array", "items": { "properties": { "client_info": { "$ref": "#/components/schemas/ClientService" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] }, "post": { "tags": [ "Clients" ], "summary": "Create New Client", "description": "Create a new client.\n\nThis endpoint allows creating a new client with the provided data in the request body.\nA valid API key (`x-api-key`) must be included in the request `header` for authentication.", "operationId": "createClient", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Client data", "required": true, "content": { "application/json": { "schema": { "properties": { "firstname": { "type": "string", "example": "John" }, "lastname": { "type": "string", "example": "Doe" }, "username": { "type": "string", "example": "johndoe" }, "email": { "type": "string", "example": "john@example.com" }, "password": { "type": "string", "example": "password" }, "location": { "type": "string", "example": "New York" }, "latitude": { "type": "string", "example": "40.7128" }, "longitude": { "type": "string", "example": "-74.0060" }, "phone": { "type": "string", "example": "1234567890" }, "category": { "type": "string", "enum": [ "individual", "business" ], "example": "individual" }, "billingType": { "type": "string", "enum": [ "monthly", "recurring" ], "example": "monthly" }, "birthday": { "type": "string", "example": "1990-01-01" }, "identification": { "type": "string", "example": "ID123" }, "avatar": { "type": "string", "example": "avatar.jpg" }, "info": { "type": "string", "example": "Additional information" }, "tags": { "type": "array", "items": { "type": "string", "example": "tag1" } } }, "type": "object" } } } }, "responses": { "422": { "description": "Validation Error: Invalid input data", "content": { "application/json": { "schema": {}, "example": { "errors": { "field_name": [ "error_message" ] } } } } }, "500": { "description": "Internal Server Error: Failed to create client", "content": { "application/json": { "schema": {}, "example": { "message": "Internal Server Error: Failed to create client" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/clients/{username}": { "get": { "tags": [ "Clients" ], "summary": "Get Client Details", "description": "Display the specific client data.\n\nThis GET endpoint retrieves detailed information about a specific `client` identified by their `username`. \nA valid API key (`x-api-key`) must be included in the request `header` for authentication. \nThe `username` parameter in the `URI` specifies the target client whose details will be retrieved. \nUpon successful execution, a `200` response is returned, client data. \nIf the requested client is not found, a 404 response is returned with a corresponding error message. \nError responses also handle unauthorized access and rate limit exceeded scenarios with appropriate error messages.", "operationId": "getClientDetails", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Client username", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 4 }, "firstname": { "type": "string", "example": "John" }, "lastname": { "type": "string", "example": "Doe" }, "username": { "type": "string", "example": "270653" }, "email": { "type": "string", "example": "john.doe@example.com" }, "location": { "type": "string", "example": "New York" }, "latitude": { "type": "string", "example": "40.7128" }, "longitude": { "type": "string", "example": "-74.0060" }, "phone": { "type": "string", "example": "1234567890" }, "category": { "type": "string", "example": "individual" }, "billingType": { "type": "string", "example": "monthly" }, "birthday": { "type": "string", "example": "1990-01-01" }, "identification": { "type": "string", "example": "ABC123" }, "avatar": { "type": "string", "example": "http://example.com/avatar.jpg" }, "type": { "type": "string", "example": "client" }, "text_pass": { "type": "string", "example": "password" }, "info": { "description": "Additional information", "properties": { "key": { "type": "string", "example": "value" } }, "type": "object" }, "email_verified_at": { "type": "string", "format": "date-time", "example": "2024-04-02T10:46:54.000000Z" }, "created_at": { "type": "string", "format": "date-time", "example": "2023-05-27T11:26:22.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-04-02T10:46:54.000000Z" }, "wallet_balance": { "type": "string", "example": "0" }, "status": { "type": "string", "example": "Active" }, "tags_data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 56 }, "name": { "type": "string", "example": "Tag Name 1" } }, "type": "object" } }, "services": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 37 }, "user_id": { "type": "integer", "example": 4 }, "package_id": { "type": "integer", "example": 6 }, "nas_id": { "type": "integer", "example": 1 }, "price": { "type": "string", "example": "3500.00" }, "username": { "type": "string", "example": "270653" }, "cleartextpassword": { "type": "string", "example": "password" }, "ipaddress": { "type": "string", "example": "102.100.0.5" }, "is_active": { "type": "integer", "example": 1 }, "renewal": { "type": "string", "example": "2024-03-27" }, "expiry": { "type": "string", "example": "2024-04-09T21:00:00.000000Z" }, "description": { "type": "string", "example": "Service description" }, "grace_expiry": { "type": "string", "example": "2024-04-09T21:00:00.000000Z" }, "deleted_at": { "type": "string", "format": "date-time", "example": null }, "created_at": { "type": "string", "format": "date-time", "example": "2023-10-05T19:14:58.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-03-29T21:22:19.000000Z" }, "mac_address": { "type": "string", "example": "00:0a:95:9d:68:16" }, "type": { "type": "string", "example": "PPP" }, "info": { "properties": { "changed": { "type": "string", "example": "2024-03-30" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Not Found: Client not found", "content": { "application/json": { "schema": {}, "example": { "message": "client not found" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] }, "put": { "tags": [ "Clients" ], "summary": "Update Client Data", "description": "Update the specified client data.\n\nThis endpoint allows updating the information of a specific `client` identified by their `username`.\nIt expects a JSON payload containing the new data to be updated. The `username` parameter in the `URI`\ndetermines which `client's` data will be updated. Authentication is required, and it expects a valid API key (`x-api-key`) to be included in the request header\nUnauthorized requests are handled with a `401` response, and rate-limit exceeded scenarios are managed with a `429` response, each accompanied by appropriate error messages.", "operationId": "updateClient", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "The client being updated username/account number", "required": true, "schema": { "type": "string" }, "example": "example_username" } ], "requestBody": { "description": "New client data", "required": true, "content": { "application/json": { "schema": { "required": [ "firstname", "category", "billingType" ], "properties": { "firstname": { "type": "string", "example": "John" }, "lastname": { "type": "string", "example": "Doe", "nullable": true }, "username": { "type": "string", "example": "example_username" }, "email": { "type": "string", "example": "john@example.com", "nullable": true }, "password": { "type": "string", "example": "new_password", "nullable": true }, "location": { "type": "string", "nullable": true }, "latitude": { "type": "string", "nullable": true }, "longitude": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "category": { "type": "string", "enum": [ "individual", "business" ], "example": "individual" }, "billingType": { "type": "string", "enum": [ "monthly", "recurring" ], "example": "monthly" }, "birthday": { "type": "string", "nullable": true }, "identification": { "type": "string", "nullable": true }, "avatar": { "type": "string", "nullable": true }, "info": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string", "example": "tag1" }, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": {}, "example": { "id": 1, "firstname": "John", "lastname": "Doe", "username": "example_username", "email": "john@example.com", "location": "New York", "latitude": "40.7128", "longitude": "-74.0060", "phone": "+1234567890", "category": "individual", "billingType": "monthly", "birthday": "1990-01-01", "identification": "12345", "avatar": "avatar_url", "info": "Additional information", "tags": [ "tag1", "tag2" ] } } } }, "400": { "description": "Bad Request: Validation error", "content": { "application/json": { "schema": {}, "example": { "errors": { "username": [ "The username field is required." ] } } } } }, "404": { "description": "Not Found: Client not found", "content": { "application/json": { "schema": {}, "example": { "message": "client not found" } } } }, "422": { "description": "Unprocessable Entity: Validation error", "content": { "application/json": { "schema": {}, "example": { "errors": { "password": [ "The password must be at least 8 characters." ] } } } } }, "500": { "description": "Internal Server Error: Failed to update client", "content": { "application/json": { "schema": {}, "example": { "message": "Internal Server Error: Failed to update client" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/clients/{username}/transactions": { "get": { "tags": [ "Clients" ], "summary": "Get Transactions", "description": "Get transactions for a specific client.\n\nThis GET endpoint retrieves `transactions` for a specific `client` identified by their `username`. \nA valid API key (`x-api-key`) must be included in the request `header` for authentication. \nThe `username` parameter in the `URI` specifies the target client whose transactions will be retrieved. \nUpon successful execution, a `200` response is returned, containing an array of transactions. \nIf the requested client is not found, a 404 response is returned with a corresponding error message. \nError responses also handle unauthorized access and rate limit exceeded scenarios with appropriate error messages.", "operationId": "getTransactions", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username of the client", "required": true, "schema": { "type": "string" }, "example": "john_doe" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "description": "Transaction ID", "type": "integer" }, "type": { "description": "Transaction type", "type": "string" }, "amount": { "description": "Transaction amount", "type": "number", "format": "float" }, "meta": { "description": "Additional metadata", "type": "object" }, "created_at": { "description": "Transaction creation timestamp", "type": "string", "format": "date-time" }, "updated_at": { "description": "Transaction update timestamp", "type": "string", "format": "date-time" } }, "type": "object" } } } } }, "404": { "description": "Not Found: Client not found", "content": { "application/json": { "schema": {}, "example": { "message": "client not found" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/clients/{username}/payment": { "post": { "tags": [ "Clients" ], "summary": "Manually add payment to client account", "description": "Update user wallet balance by adding payment.\n\nThis POST endpoint enables the manual addition of payments to a client's account. \nA valid API key (`x-api-key`) must be included in the request header for authentication. \nThe `username` parameter in the URI specifies the target client whose account will receive the payment. \nThe request body should contain a JSON payload with the `amount` property indicating the amount to be deposited. \nOptionally, the `reference` property can be included to provide a reference for the payment, and the `description` property allows for a description of the payment.\nUpon successful execution, a `200` response is returned, confirming that the client's wallet was successfully credited. \nThe response includes a message confirming the credit, the updated wallet balance, and a `notification_result` object containing details about any SMS or email notifications sent. \nIf the request fails validation, a `400` response is returned, detailing the validation error. \nIn case of an internal server error during payment processing, a 500 response is returned. Additionally, error responses handle unauthorized access and rate limit exceeded scenarios with appropriate error messages.", "operationId": "AddClientPayment", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username of the client", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount" ], "properties": { "amount": { "description": "Amount to deposit", "type": "number", "example": "100.00" }, "reference": { "description": "Reference for the payment (optional)", "type": "string", "example": "123456" }, "description": { "description": "Description of the payment (optional)", "type": "string", "example": "Payment description" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Client wallet successfully credited" }, "wallet": { "description": "Client wallet balance after credit", "type": "number", "format": "float", "example": "300" }, "notification_result": { "properties": { "smssent": { "type": "string", "example": "Sms was sent successfully using sms gateway" }, "smsfailed": { "type": "string", "example": "" }, "emailsent": { "type": "string", "example": "" }, "emailfailed": { "type": "string", "example": "" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Validation failed" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Payment processing failed" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/clients/{username}/update-wallet-balance": { "put": { "tags": [ "Clients" ], "summary": "Modify clients's wallet balance", "description": "Update user wallet balance\n\nThis endpoint allows for the `modification` of a client's `wallet balance`. \nA valid API key (`x-api-key`) must be included in the request `header` for authentication. \nThe `username` parameter in the `URI` specifies the target client whose wallet balance is to be updated. \nThe request body must contain a JSON payload with the `newWalletBalance` property, indicating the new wallet balance to be set. \nUpon successful execution, a `200` response is returned, indicating that the wallet balance was updated successfully. \nThe response includes a status message confirming the update and the updated wallet balance. \nIf the request fails validation, a `400` response is returned, detailing the validation error. \nIn case the specified client is `not found`, a `404` response is returned. \nAdditionally, error responses handle unauthorized access and rate limit exceeded scenarios with appropriate error messages.", "operationId": "UpdateWalletBalance", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username of the client", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "newWalletBalance" ], "properties": { "newWalletBalance": { "description": "New wallet balance", "type": "number", "example": "100.00" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "Wallet balance updated successfully" }, "wallet_balance": { "description": "Updated wallet balance", "type": "number", "example": "100.00" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Validation failed" } }, "type": "object" } } } }, "404": { "description": "Client not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Client not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/clients/{username}/invoices": { "get": { "tags": [ "Clients" ], "summary": "Get Invoices", "description": "Get invoices for a specific client.\n\nThis GET endpoint retrieves `invoices` associated with a specific `client` identified by their `username`. \nThe `username` parameter in the `URI` denotes the target `client`. \nAccessing the endpoint requires a valid API key (`x-api-key`) provided in the request `header` for authentication. \nUpon successful retrieval, a `200` response delivers an array of `invoice` objects containing details such as invoice ID, user ID, service ID, invoice number, amount, status, due date, and timestamps of creation and last update. \nIn case the specified client is not found, a `404` response is returned. Additionally, error responses handle scenarios of unauthorized access and rate limit exceeded with appropriate error messages.", "operationId": "getInvoices", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username of the client", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 135 }, "user_id": { "type": "integer", "example": 4 }, "service_id": { "type": "integer", "example": 37 }, "invoice_number": { "type": "string", "example": "INV-15789846" }, "amount": { "type": "string", "example": "2500.00" }, "status": { "type": "string", "example": "paid" }, "due_date": { "type": "string", "example": "2024-03-16" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-03-09T08:27:27.000000Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-03-09T08:27:27.000000Z" } }, "type": "object" } } } } }, "404": { "description": "client not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "client not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/clients/{username}/statistics": { "get": { "tags": [ "Clients" ], "summary": "Get usage statistics for a service", "description": "Get usage statistics for specific service\n\nUpon successful invocation of the endpoint, you receive an instance of the `client` details, together with their subscibed `services`. \nIn addition to the client data, you also receive the total `download` and `upload` usage in (`GB`), the usage period, for the selected service, in the last `12 month` period grouped per `month`.\nAuthentication is required, and it expects a valid API key (`x-api-key`) to be included in the request header\nUnauthorized requests are handled with a `401` response, and rate-limit exceeded scenarios are managed with a `429` response, each accompanied by appropriate error messages.", "operationId": "getUsageStatistics", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username of the client", "required": true, "schema": { "type": "string" } }, { "name": "interface", "in": "query", "description": "Username of the service being queried", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "client": { "type": "array", "items": { "properties": { "client_info": { "$ref": "#/components/schemas/ClientService" } }, "type": "object" } }, "download": { "description": "Total download in GB", "type": "number", "format": "float" }, "upload": { "description": "Total upload in GB", "type": "number", "format": "float" }, "period": { "description": "Usage period", "type": "array", "items": { "properties": { "month": { "description": "Usage month", "type": "string" }, "GB_in": { "description": "Download in GB", "type": "number", "format": "float" }, "GB_out": { "description": "Upload in GB", "type": "number", "format": "float" } }, "type": "object" } }, "selectedService": { "description": "Selected service", "type": "string" }, "selectedPeriod": { "description": "Selected period", "type": "string" } }, "type": "object" } } } }, "404": { "description": "Client not found or has no services", "content": { "application/json": { "schema": { "properties": { "error": { "description": "Error message", "type": "string", "example": "Client not found or has no services" } }, "type": "object" } } } }, "400": { "description": "Selected service does not match Client", "content": { "application/json": { "schema": { "properties": { "error": { "description": "Error message", "type": "string", "example": "Selected service does not match Client" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/clients/statistics/daily": { "get": { "tags": [ "Clients" ], "summary": "Get daily usage statistics for a specific service and month", "description": "Get daily usage statistics for a specific service and month\n\nUpon successful invocation of the endpoint, you receive an instance of the `service` details, together with thee `client`.\nIn addition, it retrieves daily usage `statistics` for the `service` and month. \nIt provides information about the total `download` and `upload` data in gigabytes (`GB`) \nalong with usage statistics for each `day` in the specified `month`. Authentication is required, and it expects a valid API key (`x-api-key`) to be included in the request header\nUnauthorized requests are handled with a `401` response, and rate-limit exceeded scenarios are managed with a `429` response, each accompanied by appropriate error messages.", "operationId": "viewStats", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "service", "in": "query", "description": "Username of the service", "required": true, "schema": { "type": "string" } }, { "name": "month", "in": "query", "description": "Month and year in the format 'Year-Month' (e.g., '2023-October')", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "properties": { "service": { "description": "Detailed information about the service and its client", "properties": { "id": { "type": "integer", "example": 7 }, "user_id": { "type": "integer", "example": 6 }, "package_id": { "type": "integer", "example": 3 }, "nas_id": { "type": "integer", "example": 1 }, "price": { "type": "string", "example": "2000.00" }, "username": { "type": "string", "example": "john_doe" }, "cleartextpassword": { "type": "string", "example": "new_password" }, "ipaddress": { "type": "string", "example": "192.168.1.100" }, "is_active": { "type": "integer", "example": 1 }, "renewal": { "type": "string", "example": null }, "expiry": { "type": "string", "example": "2024-04-06T21:00:00.000000Z" }, "description": { "type": "string", "example": "Updated PPPoE service new one" }, "grace_expiry": { "type": "string", "example": null }, "deleted_at": { "type": "string", "example": null }, "created_at": { "type": "string", "example": "2024-04-05T23:29:35.000000Z" }, "updated_at": { "type": "string", "example": "2024-04-06T00:47:06.000000Z" }, "mac_address": { "type": "string", "example": null }, "type": { "type": "string", "example": "PPP" }, "info": { "type": "string", "example": null }, "client": { "description": "Client information", "properties": { "id": { "type": "integer", "example": 6 }, "firstname": { "type": "string", "example": "John" }, "lastname": { "type": "string", "example": "Doe" }, "username": { "type": "string", "example": "574781" }, "email": { "type": "string", "example": "doe@mail.com" }, "location": { "type": "string", "example": null }, "latitude": { "type": "string", "example": "10.2163179" }, "longitude": { "type": "string", "example": "36.7391117" }, "phone": { "type": "string", "example": null }, "category": { "type": "string", "example": "individual" }, "billingType": { "type": "string", "example": "monthly" }, "birthday": { "type": "string", "example": null }, "identification": { "type": "string", "example": null }, "avatar": { "type": "string", "example": null }, "type": { "type": "string", "example": "client" }, "text_pass": { "type": "string", "example": null }, "info": { "type": "string", "example": null }, "email_verified_at": { "type": "string", "example": null }, "created_at": { "type": "string", "example": "2023-05-29T09:37:44.000000Z" }, "updated_at": { "type": "string", "example": "2024-03-29T18:09:15.000000Z" } }, "type": "object" } }, "type": "object" }, "download": { "description": "Total download in GB", "type": "number", "format": "float" }, "upload": { "description": "Total upload in GB", "type": "number", "format": "float" }, "period": { "description": "Usage period", "type": "array", "items": { "properties": { "date": { "description": "Date in 'Month Day, Year' format", "type": "string" }, "Download": { "description": "Download in GB", "type": "number", "format": "float" }, "Upload": { "description": "Upload in GB", "type": "number", "format": "float" } }, "type": "object" } }, "selectedService": { "description": "Selected service", "type": "string" }, "selectedMonthYear": { "description": "Selected month and year", "type": "string" }, "selectedPeriod": { "description": "Selected period", "type": "string" } }, "type": "object" } } } }, "400": { "description": "Bad request or invalid month-year format", "content": { "application/json": { "schema": { "properties": { "error": { "description": "Error message", "type": "string", "example": "Invalid month-year format. Please use the format 'Month-Year' (e.g., '2023-October')" } }, "type": "object" } } } }, "404": { "description": "Service not found", "content": { "application/json": { "schema": { "properties": { "error": { "description": "Error message", "type": "string", "example": "Service not found" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "error": { "description": "Error message", "type": "string", "example": "Internal server error occurred" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/clients/{username}/communication": { "get": { "tags": [ "Clients" ], "summary": "Get client communication details", "description": "Retrieve messages sent to a client\n\nThis endpoint retrieves `communication` details for a specified `client` in the system. Authentication is required, and it expects a valid API key (`x-api-key`) to be included in the request header. \nThe client's `username` is provided as a path parameter to identify the client. Upon successful execution, a `200` response is returned, containing JSON data with information about the client, their messages, and available templates. \nIf the specified client is not found, a `404` response is returned. Unauthorized requests are handled with a `401` response, and rate-limit exceeded scenarios are managed with a `429` response, each accompanied by appropriate error messages.", "operationId": "GetClientCommunication", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username of the client", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "properties": { "client": { "type": "array", "items": { "properties": { "id": { "type": "integer", "format": "int64" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "username": { "type": "string" }, "email": { "type": "string", "format": "email" }, "location": { "type": "string" }, "latitude": { "type": "string" }, "longitude": { "type": "string" }, "phone": { "type": "string" }, "category": { "type": "string" }, "billingType": { "type": "string" }, "birthday": { "type": "string", "format": "date" }, "identification": { "type": "string" }, "avatar": { "type": "string" }, "text_pass": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "sender": { "type": "string" }, "message": { "type": "string" }, "gateway": { "type": "string" }, "messageId": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "templates": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "Client not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Client not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/clients/{username}/send-message": { "post": { "tags": [ "Clients" ], "summary": "Send a message to a client", "description": "Send message to a client\n\nThis POST endpoint serves the purpose of facilitating the sending of messages to clients within the system. \nUpon invocation, the endpoint requires the inclusion of a valid API key (`x-api-key`) in the request `header` for authentication. \nIt expects the client's `username` to be provided as a path parameter. The request body, formatted as `JSON`, must contain the message to be sent, with the `message` property being `mandatory`. \nUpon successful execution, a `200` response signifies that the message was delivered successfully. \nHowever, various error responses are also defined to handle scenarios such as validation failures, client not found, or internal server issues. \nFunctionally, the endpoint verifies if SMS messaging is enabled and if the configured SMS gateway is operational before attempting message delivery. \nOverall, this endpoint provides a structured and secure means of communication with clients.", "operationId": "SendClientMessage", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username of the client", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Your message here" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "properties": { "success": { "type": "string", "example": "Message sent successfully" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Validation failed" } }, "type": "object" } } } }, "404": { "description": "Client not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Client not found" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Failed to send Message. Kindly make sure the SMS gateway is configured correctly" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/clients/delete": { "delete": { "tags": [ "Clients" ], "summary": "Delete the specified client from the system", "description": "Delete a client from the system\n\nThis DELETE endpoint enables the removal of a specified client from the system. \nA valid API key (`x-api-key`) must be included in the request header for authentication. \nThe client's `username`, provided as a post parameter, identifies the `client` to be deleted. \nThe endpoint returns a `200` response upon successful deletion, with a message indicating the successful deletion of the client. \nIn cases where the client cannot be deleted due to associated services, a `400` response is returned along with an error message specifying the reason. \nAdditionally, a `404` response is returned if the specified client is not found. The endpoint also handles unauthorized requests with a `401` response and rate-limit exceeded scenarios with a `429` response, providing appropriate error messages for each case.", "operationId": "Delete Client", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "query", "description": "The username of the client to be deleted", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Client deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Client deleted successfully" } }, "type": "object" } } } }, "400": { "description": "Cannot delete client because they have associated services", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Cannot delete client because they have associated services" } }, "type": "object" } } } }, "404": { "description": "client not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "client not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/services/client/{username}/save-pppoe-service": { "post": { "tags": [ "Services" ], "summary": "Create new PPPoE service for a client", "description": "This endpoint allows users to save DHCP service information for a client. Ensure to pass the ID of the `NAS` and the ID of the `package`. If you do not want to bill the `installationFee`, make sure to remove that field from the input. If you dont include the `price` input, the user is automatically assigned the price of the selected package. A valid API key (`x-api-key`) must be included in the request `header` for authentication. ", "operationId": "savePPPoEService", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username of the client", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "PPPoE service data to be saved", "required": true, "content": { "application/json": { "schema": { "required": [ "package", "nas", "username", "password", "ipaddress" ], "properties": { "package": { "description": "ID of the package", "type": "integer" }, "price": { "description": "Price of the service", "type": "integer" }, "nas": { "description": "ID of the NAS", "type": "integer" }, "ipaddress": { "description": "IP address", "type": "string" }, "username": { "description": "Username", "type": "string" }, "password": { "description": "Password", "type": "string" }, "description": { "description": "Description of the service", "type": "string" }, "tags": { "description": "List of tags", "type": "array", "items": { "type": "string" } }, "installationFee": { "description": "Installation fee", "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Service saved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Status of the operation", "type": "string", "example": "success" }, "message": { "description": "Success message", "type": "string", "example": "PPPoE service added successfully" } }, "type": "object" } } } }, "400": { "description": "Bad request or Validation Error", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Status of the operation", "type": "string", "example": "error" }, "message": { "description": "Error message", "type": "string", "example": "Validation error" }, "errors": { "description": "Validation errors", "properties": { "ipaddress": { "type": "array", "items": { "type": "string" }, "example": [ "The ipaddress must be a valid IP address." ] }, "username": { "type": "array", "items": { "type": "string" }, "example": [ "The username has already been taken." ] }, "password": { "type": "array", "items": { "type": "string" }, "example": [ "The password field is required." ] } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Client or package not found", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Status of the operation", "type": "string", "example": "error" }, "message": { "description": "Error message", "type": "string", "example": "Client or package not found" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Status of the operation", "type": "string", "example": "error" }, "message": { "description": "Error message", "type": "string", "example": "Internal server error occurred" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/services/client/{username}/save-dhcp-service": { "post": { "tags": [ "Services" ], "summary": "Create new DHCP service for a client", "description": "This endpoint allows users to save DHCP service information for a client. Ensure to pass the ID of the `NAS` and the ID of the `package`. If you do not want to bill the `installationFee`, make sure to remove that field from the input. If you dont include the `price` input, the user is automatically assigned the price of the selected package. A valid API key (`x-api-key`) must be included in the request `header` for authentication. ", "operationId": "saveDHCPService", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username of the Service", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "DHCP service data to be saved", "required": true, "content": { "application/json": { "schema": { "required": [ "package", "nas", "macaddress", "ipaddress" ], "properties": { "package": { "description": "ID of the package", "type": "integer" }, "price": { "description": "Price of the service", "type": "integer" }, "nas": { "description": "ID of the NAS", "type": "integer" }, "ipaddress": { "description": "IP address", "type": "string" }, "macaddress": { "description": "MAC address", "type": "string" }, "description": { "description": "Description of the service", "type": "string" }, "tags": { "description": "List of tags", "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Service saved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Status of the operation", "type": "string", "example": "success" }, "message": { "description": "Success message", "type": "string", "example": "DHCP service added successfully" } }, "type": "object" } } } }, "400": { "description": "Bad request or Validation Error", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Status of the operation", "type": "string", "example": "error" }, "message": { "description": "Error message", "type": "string", "example": "Validation error" }, "errors": { "description": "Validation errors", "properties": { "ipaddress": { "type": "array", "items": { "type": "string" }, "example": [ "The ipaddress must be a valid IP address." ] }, "macaddress": { "type": "array", "items": { "type": "string" }, "example": [ "The macaddress has already been taken." ] } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Client or package not found", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Status of the operation", "type": "string", "example": "error" }, "message": { "description": "Error message", "type": "string", "example": "Client or package not found" } }, "type": "object" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Status of the operation", "type": "string", "example": "error" }, "message": { "description": "Error message", "type": "string", "example": "Internal server error occurred" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/services/{username}/update-pppoe-service": { "put": { "tags": [ "Services" ], "summary": "Update PPPoE service for a client", "description": "Update PPPoE service details for a client. Ensure to pass the ID of the `NAS` and the ID of the `package`. If you dont include the `price` input, the user is automatically assigned the price of the selected package. A valid API key (`x-api-key`) must be included in the request `header` for authentication. ", "operationId": "updatePppoeService", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Service username", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Updated PPPoE service data", "required": true, "content": { "application/json": { "schema": { "required": [ "package", "nas", "username", "password", "ipaddress" ], "properties": { "package": { "description": "ID of the package", "type": "integer" }, "price": { "description": "Price of the service", "type": "integer" }, "nas": { "description": "ID of the NAS", "type": "integer" }, "ipaddress": { "description": "IP address", "type": "string" }, "username": { "description": "Username", "type": "string" }, "password": { "description": "Password", "type": "string" }, "description": { "description": "Description of the service", "type": "string" }, "tags": { "description": "List of tags", "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "404": { "description": "Service not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Service not found" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Internal Server Error" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/services/{username}/update-dhcp-service": { "put": { "tags": [ "Services" ], "summary": "Update DHCP service for a client", "description": "Update DHCP service details for a client. Ensure to pass the ID of the `NAS` and the ID of the `package`. If you dont include the `price` input, the user is automatically assigned the price of the selected package. A valid API key (`x-api-key`) must be included in the request `header` for authentication.", "operationId": "updateDHCPService", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Service username", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Updated DHCP service data", "required": true, "content": { "application/json": { "schema": { "required": [ "package", "nas", "macaddress", "ipaddress" ], "properties": { "package": { "description": "ID of the package", "type": "integer" }, "price": { "description": "Price of the service", "type": "integer" }, "nas": { "description": "ID of the NAS", "type": "integer" }, "ipaddress": { "description": "IP address", "type": "string" }, "macaddress": { "description": "MAC address", "type": "string" }, "description": { "description": "Description of the service", "type": "string" }, "tags": { "description": "List of tags", "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "404": { "description": "Client, DHCP service, Package, or NAS not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Client, DHCP service, Package, or NAS not found" } }, "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Validation error" }, "errors": { "properties": { "package": { "type": "array", "items": { "type": "string", "example": "The package field is required." } } }, "type": "object" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Internal Server Error" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/services/client/{username}": { "get": { "tags": [ "Services" ], "summary": "Retrieve Client Services", "description": "This GET endpoint serves the purpose of retrieving all services associated with a specific `Client`, identified by their unique username. The `username` represents the username of the `client` whose services are to be retrieved. A valid API key (`x-api-key`) must be included in the request `header` for authentication. Upon successful authentication, the endpoint returns a JSON response containing details of the user's services. The response includes a status indicator to signify the success of the operation, denoted by `success`. Accompanying the status indicator is an array of service objects encapsulating information about each service associated with the specified user. In the event that the requested user is not found in the system, a `404` response is returned, along with an error message indicating the absence of the user. Additionally, robust error handling mechanisms are implemented to handle unauthorized access attempts or scenarios where the rate limit for requests is exceeded. In such cases, appropriate error responses are returned,", "operationId": "getUserServices", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username of the client", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User services retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Status of the operation", "type": "string", "example": "success" }, "services": { "description": "List of user services", "type": "array", "items": { "description": "User service data", "type": "object" } } }, "type": "object" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Status of the operation", "type": "string", "example": "error" }, "message": { "description": "Error message", "type": "string", "example": "User not found" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/services/{username}/details": { "get": { "tags": [ "Services" ], "summary": "Retrieve Service Details by Username", "description": "This GET endpoint facilitates the retrieval of detailed information regarding a specific `service` identified by its unique `username`. A valid API key (`x-api-key`) must be included in the request `header` for authentication. Upon successful authentication, the endpoint returns comprehensive details of the service associated with the provided username. A `200` response indicate successful operation completion, while a `404` response signifies that the service was not found. In case of an internal server error, a `500` response is returned. ", "operationId": "getServiceDetailsByUsername", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username of the service", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Service details retrieved successfully", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Status of the operation", "type": "string", "example": "success" }, "service": { "description": "Service details", "properties": { "id": { "description": "Service ID", "type": "integer", "example": 71 }, "user_id": { "description": "User ID", "type": "integer", "example": 4 }, "package_id": { "description": "Package ID", "type": "integer", "example": 3 }, "nas_id": { "description": "NAS ID", "type": "integer", "example": 1 }, "price": { "description": "Price of the service", "type": "string", "example": "2000.00" }, "username": { "description": "Username of the service", "type": "string", "example": "kelvin" }, "password": { "description": "Password of the service", "type": "string", "example": "murithi" }, "ip_address": { "description": "IP address assigned to the service", "type": "string", "example": "10.10.3.5" }, "status": { "description": "Status of the service", "type": "string", "example": "active" }, "expiry": { "description": "Expiry date of the service", "type": "string", "example": "2024-04-05T21:00:00.000000Z" }, "description": { "description": "Description of the service", "type": "string", "example": "Home internet" }, "grace_expiry": { "description": "Grace expiry of the service", "type": "string", "example": null }, "mac_address": { "description": "MAC address associated with the service", "type": "string", "example": null }, "type": { "description": "Type of the service", "type": "string", "example": "PPPOE" }, "info": { "description": "Additional information about the service", "type": "string", "example": null }, "deleted_at": { "description": "Deletion timestamp of the service", "type": "string", "example": null }, "created_at": { "description": "Creation timestamp of the service", "type": "string", "example": "2024-04-05T14:08:42.000000Z" }, "updated_at": { "description": "Last update timestamp of the service", "type": "string", "example": "2024-04-05T14:08:42.000000Z" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Service not found", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Status of the operation", "type": "string", "example": "error" }, "message": { "description": "Error message", "type": "string", "example": "Service not found" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "description": "Status of the operation", "type": "string", "example": "error" }, "message": { "description": "Error message", "type": "string", "example": "Internal Server Error" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } }, "/api/services/{username}/delete-service": { "delete": { "tags": [ "Services" ], "summary": "Delete a service ", "description": "This DELETE endpoint serves to delete a specific `service` associated with a given `username`. A valid API key (`x-api-key`) must be included in the request `header` for authentication. Once authenticated, the service identified by the provided username is deleted from the system. In cases where the requested service cannot be found, a `404` response is returned along with a descriptive error message indicating the absence of the service. Moreover, if the service to be deleted is currently `active`, the endpoint prevents deletion and responds with a `400` status code, accompanied by an explanatory message. In the event of an error, such as a model not found exception or an unexpected server error, the endpoint responds with a JSON object containing the relevant error status code and a detailed error message.", "operationId": "deleteService", "parameters": [ { "name": "x-api-key", "in": "header", "description": "API key is required. Example: 3fe15d2c7749b0f4e8d7211a33dbb28c2957e6678e4f472c9cde0836e9a912b7", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Service username", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Service deleted successfully" } }, "type": "object" } } } }, "404": { "description": "Service not found", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Service not found" } }, "type": "object" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Internal Server Error" } }, "type": "object" } } } }, "401": { "description": "Unauthorized: API key is missing, invalid, or rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4002, "message": "Invalid or inactive API key." } } } }, "429": { "description": "Too Many Requests: Rate limit exceeded", "content": { "application/json": { "schema": {}, "example": { "code": 4003, "message": "Too many requests. Please try again later." } } } } }, "security": [ { "x-api-key": [] } ] } } }, "components": { "schemas": { "Client": { "title": "Client", "description": "Client object", "properties": { "id": { "type": "integer", "example": 4 }, "firstname": { "type": "string", "example": "John" }, "lastname": { "type": "string", "example": "Doe" }, "username": { "type": "string", "example": "270653" }, "email": { "type": "string", "example": "johndoe@gmail.com" }, "location": { "type": "string", "nullable": true }, "latitude": { "type": "string", "example": "-11.224234" }, "longitude": { "type": "string", "example": "45.7312161" }, "phone": { "type": "string", "example": "04256668225" }, "category": { "type": "string", "example": "individual" }, "billingType": { "type": "string", "example": "monthly" }, "birthday": { "type": "string", "format": "date", "nullable": true }, "identification": { "type": "string", "nullable": true }, "avatar": { "type": "string", "nullable": true }, "info": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "wallet_balance": { "type": "number", "format": "float", "example": 200 }, "status": { "type": "string", "example": "No Service" }, "tags_data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } } }, "type": "object" }, "ClientService": { "title": "ClientService", "description": "ClientService object", "properties": { "id": { "type": "integer", "example": 4 }, "firstname": { "type": "string", "example": "John" }, "lastname": { "type": "string", "example": "Doe" }, "username": { "type": "string", "example": "270653" }, "email": { "type": "string", "example": "admin@admin.com" }, "location": { "type": "string", "nullable": true }, "latitude": { "type": "string", "example": "10.224234" }, "longitude": { "type": "string", "example": "42.7312161" }, "phone": { "type": "string", "example": "25555585455" }, "category": { "type": "string", "example": "individual" }, "billingType": { "type": "string", "example": "monthly" }, "birthday": { "type": "string", "format": "date", "nullable": true }, "identification": { "type": "string", "nullable": true }, "avatar": { "type": "string", "nullable": true }, "info": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "wallet_balance": { "type": "number", "format": "float", "example": 200 }, "status": { "type": "string", "example": "Active" }, "tags_data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } }, "type": "object" }, "Service": { "title": "Service", "description": "Service object", "properties": { "id": { "type": "integer", "example": 6 }, "user_id": { "type": "integer", "example": 6 }, "package_id": { "type": "integer", "example": 2 }, "nas_id": { "type": "integer", "example": 1 }, "price": { "type": "number", "format": "float", "example": 500 }, "username": { "type": "string", "example": "string" }, "cleartextpassword": { "type": "string", "nullable": true }, "ipaddress": { "type": "string", "example": "192.168.0.2" }, "is_active": { "type": "integer", "example": 1 }, "renewal": { "type": "string", "format": "date-time", "nullable": true }, "expiry": { "type": "string", "format": "date-time", "example": "2024-04-06T21:00:00.000000Z" }, "description": { "type": "string", "example": "string" }, "grace_expiry": { "type": "string", "format": "date-time", "nullable": true }, "deleted_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "mac_address": { "type": "string", "example": "string" }, "type": { "type": "string", "example": "DHCP" }, "info": { "type": "string", "nullable": true } }, "type": "object" } } }, "externalDocs": { "description": "Get Postman Collection", "url": "https://link-to-your-postman-collection" } }