{ "openapi": "3.0.0", "info": { "title": "Solar SaaS Multi-tenant API", "description": "Multi-tenant SaaS API (Laravel Sanctum). Roles: super admin (platform), tenant admin (app admin), service user (app user). App login succeeds only with an active, non-blocked membership and active tenant. Super admin may suspend a tenant or block a user globally; tenant admin may block service users (`POST /tenant-admin/service-users/{id}/block`) — blocked users cannot log in or use `/app/*`. Login/me return `user.membership` (single object). Currency: INR.", "version": "1.0.0" }, "servers": [ { "url": "https://app.marwarmechanization.com/public", "description": "Set APP_URL in .env (e.g. http://localhost:8888/solar/public for MAMP)" } ], "paths": { "/api/app/dashboard": { "get": { "tags": [ "App" ], "operationId": "appDashboard", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project_id", "in": "query", "description": "Optional: show dashboard totals for one assigned project only", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Service user dashboard: assigned projects, earnings, received payouts, holds, available request amount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dashboard" } } } } } } }, "/api/app/masters": { "get": { "tags": [ "App" ], "operationId": "appMasters", "parameters": [ { "$ref": "#/components/parameters/XTenantId" } ], "responses": { "200": { "description": "Solar panels and inverters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MastersResponse" } } } } } } }, "/api/app/files/upload": { "post": { "tags": [ "App" ], "operationId": "appFileUpload", "parameters": [ { "$ref": "#/components/parameters/XTenantId" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Returns `{ \"key\": \"...\" }`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } } } } } }, "/api/app/projects": { "get": { "tags": [ "App" ], "operationId": "appProjectsIndex", "parameters": [ { "$ref": "#/components/parameters/XTenantId" } ], "responses": { "200": { "description": "Projects assigned to or created by the service user; each includes financials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pagination" } } } } } }, "post": { "tags": [ "App" ], "operationId": "appProjectsStore", "parameters": [ { "$ref": "#/components/parameters/XTenantId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "customer_name", "kw", "project_cost", "bill_to_customer" ], "properties": { "customer_name": { "type": "string" }, "kw": { "type": "number" }, "project_cost": { "type": "number" }, "bill_to_customer": { "description": "Must be > project_cost when project_cost > 0; may be 0 when project_cost is 0", "type": "number" }, "customer_phone": { "type": "string" }, "customer_email": { "type": "string" }, "address": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "pincode": { "type": "string" }, "solar_panel_id": { "type": "integer" }, "inverter_id": { "type": "integer" }, "commission_per_kw_override": { "type": "number" } }, "type": "object" } } } }, "responses": { "201": { "description": "Created as pending_approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } } } }, "/api/app/projects/{project}": { "get": { "tags": [ "App" ], "operationId": "appProjectsShow", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } } }, "patch": { "tags": [ "App" ], "operationId": "appProjectsUpdate", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "customer_name": { "type": "string" }, "kw": { "type": "number" }, "project_cost": { "type": "number" }, "bill_to_customer": { "description": "Must be > project_cost when project_cost > 0; may be 0 when project_cost is 0", "type": "number" }, "customer_phone": { "type": "string" }, "customer_email": { "type": "string" }, "address": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "pincode": { "type": "string" }, "solar_panel_id": { "type": "integer" }, "inverter_id": { "type": "integer" }, "commission_per_kw_override": { "type": "number" } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated while pending_approval only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "422": { "description": "PROJECT_NOT_EDITABLE when approved, completed, or rejected" } } } }, "/api/app/projects/{project}/media": { "patch": { "tags": [ "App" ], "operationId": "appProjectsMedia", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "photos_site_blank": { "type": "string" }, "photos_structure": { "type": "string" }, "photos_solar_plate": { "type": "string" }, "photos_meter_final": { "type": "string" }, "other_documents": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated (assigned user; pending_approval or approved only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } } } }, "/api/app/payments": { "get": { "tags": [ "App" ], "operationId": "appPaymentsIndex", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project_id", "in": "query", "description": "Filter payments by one assigned project", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "Payments for assigned projects only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pagination" } } } } } } }, "/api/app/payments/{payment}": { "get": { "tags": [ "App" ], "operationId": "appPaymentsShow", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "payment", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } } } } }, "/api/app/payments/{payment}/comments": { "get": { "tags": [ "App" ], "operationId": "appPaymentsCommentsIndex", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "payment", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated comments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pagination" } } } } } }, "post": { "tags": [ "App" ], "operationId": "appPaymentsCommentsStore", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "payment", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment created", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/app/payout-accounts": { "get": { "tags": [ "App" ], "operationId": "appPayoutAccountsIndex", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "bank", "upi" ] } } ], "responses": { "200": { "description": "Own saved bank/UPI payout accounts; filter with ?type=bank or ?type=upi", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutAccount" } } } } } } }, "post": { "tags": [ "App" ], "operationId": "appPayoutAccountsStore", "parameters": [ { "$ref": "#/components/parameters/XTenantId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "bank", "upi" ] }, "label": { "type": "string" }, "account_holder_name": { "description": "Required for bank", "type": "string" }, "bank_account": { "description": "Required for bank", "type": "string" }, "ifsc": { "description": "Required for bank", "type": "string" }, "bank_name": { "description": "Required for bank", "type": "string" }, "branch_name": { "description": "Required for bank", "type": "string" }, "upi_id": { "description": "Required for upi", "type": "string" }, "is_default": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "201": { "description": "Payout account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutAccount" } } } }, "422": { "description": "Validation error" } } } }, "/api/app/payout-accounts/{payoutAccount}": { "get": { "tags": [ "App" ], "operationId": "appPayoutAccountsShow", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "payoutAccount", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payout account detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutAccount" } } } } } }, "delete": { "tags": [ "App" ], "operationId": "appPayoutAccountsDestroy", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "payoutAccount", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } }, "patch": { "tags": [ "App" ], "operationId": "appPayoutAccountsUpdate", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "payoutAccount", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "enum": [ "bank", "upi" ] }, "label": { "type": "string" }, "account_holder_name": { "type": "string" }, "bank_account": { "type": "string" }, "ifsc": { "type": "string" }, "bank_name": { "type": "string" }, "branch_name": { "type": "string" }, "upi_id": { "type": "string" }, "is_default": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Payout account updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutAccount" } } } } } } }, "/api/app/projects/{project}/ledger": { "get": { "tags": [ "App" ], "operationId": "appProjectLedger", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Balances: payable cap, credits, holds, available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerSummary" } } } } } } }, "/api/app/payout-requests": { "get": { "tags": [ "App" ], "operationId": "appPayoutRequestsAllIndex", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project_id", "in": "query", "description": "Filter own payout requests by one assigned project", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "rejected" ] } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "Own payout requests across projects; use project_id for project-wise filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pagination" } } } } } } }, "/api/app/projects/{project}/payout-requests": { "get": { "tags": [ "App" ], "operationId": "appPayoutRequestsIndex", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Own payout requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pagination" } } } } } }, "post": { "tags": [ "App" ], "operationId": "appPayoutRequestsStore", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "payout_method" ], "properties": { "payout_type": { "description": "standard (default) or gst", "type": "string", "enum": [ "standard", "gst" ] }, "amount": { "description": "Required for standard payouts only; do not send for GST (total is computed as net_amount + gst_amount)", "type": "number" }, "net_amount": { "description": "Required for GST payouts only", "type": "number" }, "gst_amount": { "description": "Required for GST payouts only; reduces project GST liability on approval", "type": "number" }, "bill_copy_key": { "description": "Optional for GST payouts only; from POST /api/app/files/upload", "type": "string" }, "payout_method": { "type": "string", "enum": [ "bank", "upi" ] }, "account_holder_name": { "type": "string" }, "bank_account": { "type": "string" }, "ifsc": { "type": "string" }, "bank_name": { "type": "string" }, "branch_name": { "type": "string" }, "upi_id": { "type": "string" }, "note": { "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "description": "Pending request (amount on hold)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutRequest" } } } }, "422": { "description": "INSUFFICIENT_AVAILABLE, GST_LIABILITY_EXCEEDED, or when bill_copy_key sent: INVALID_BILL_COPY_KEY / BILL_COPY_NOT_FOUND" } } } }, "/api/app/payout-requests/{payoutRequest}": { "get": { "tags": [ "App" ], "operationId": "appPayoutRequestsShow", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "payoutRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Own payout request detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutRequest" } } } } } } }, "/api/auth/login": { "post": { "tags": [ "Auth" ], "description": "Authenticate with **username** or **email** plus password.", "operationId": "authLogin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "login", "password" ], "properties": { "login": { "type": "string", "example": "superadmin" }, "password": { "type": "string", "format": "password" }, "device_name": { "type": "string", "example": "iphone" }, "fcm_token": { "description": "Optional; send together with device_id to register for push", "type": "string" }, "device_id": { "description": "Stable app installation id (e.g. UUID); required if fcm_token is sent", "type": "string" }, "platform": { "description": "Optional: ios, android, etc.", "type": "string", "example": "android" } }, "type": "object" } } } }, "responses": { "200": { "description": "Token issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthLoginResponse" } } } }, "401": { "description": "Invalid credentials" }, "403": { "description": "User blocked, tenant suspended, or no active tenant access" }, "422": { "description": "Validation error" } }, "security": [] } }, "/api/auth/logout": { "post": { "tags": [ "Auth" ], "operationId": "authLogout", "responses": { "200": { "description": "Logged out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/auth/me": { "get": { "tags": [ "Auth" ], "operationId": "authMe", "responses": { "200": { "description": "Current user and active membership", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthUser" } } } }, "403": { "description": "Account inactive (blocked user or suspended tenant)" }, "401": { "description": "Unauthenticated" } } } }, "/api/super-admin/tenants": { "get": { "tags": [ "SuperAdmin" ], "operationId": "superAdminTenantsIndex", "responses": { "200": { "description": "Paginated tenants", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pagination" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not super admin" } } }, "post": { "tags": [ "SuperAdmin" ], "operationId": "superAdminTenantsStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "tenant_name", "tenant_email", "password", "default_commission_per_kw" ], "properties": { "tenant_name": { "description": "Company / tenant name (also used as primary admin display name)", "type": "string" }, "tenant_email": { "description": "Tenant contact email (primary admin login email)", "type": "string", "format": "email" }, "tenant_phone": { "type": "string", "nullable": true }, "username": { "description": "Optional; defaults to email local-part if omitted", "type": "string" }, "password": { "description": "Primary tenant admin app password", "type": "string", "format": "password" }, "default_commission_per_kw": { "description": "INR per kW", "type": "number" }, "max_service_users": { "type": "integer", "example": 2 } }, "type": "object" } } } }, "responses": { "201": { "description": "Tenant created; primary tenant admin uses tenant name/email/phone", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Tenant" }, { "properties": { "tenant_users": { "type": "array", "items": { "$ref": "#/components/schemas/TenantUser" } } }, "type": "object" } ] } } } }, "422": { "description": "Validation error" } } } }, "/api/super-admin/tenants/{tenant}": { "get": { "tags": [ "SuperAdmin" ], "operationId": "superAdminTenantsShow", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Tenant detail", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Tenant" }, { "properties": { "tenant_users": { "type": "array", "items": { "$ref": "#/components/schemas/TenantUser" } } }, "type": "object" } ] } } } }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "SuperAdmin" ], "operationId": "superAdminTenantsUpdate", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "tenant_name": { "type": "string" }, "tenant_email": { "type": "string", "nullable": true }, "tenant_phone": { "type": "string", "nullable": true }, "max_service_users": { "type": "integer" }, "default_commission_per_kw": { "type": "number" } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Tenant" }, { "properties": { "tenant_users": { "type": "array", "items": { "$ref": "#/components/schemas/TenantUser" } } }, "type": "object" } ] } } } } } } }, "/api/super-admin/tenants/{tenant}/suspend": { "post": { "tags": [ "SuperAdmin" ], "operationId": "superAdminTenantsSuspend", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Suspended; tokens revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } } } } }, "/api/super-admin/tenants/{tenant}/activate": { "post": { "tags": [ "SuperAdmin" ], "operationId": "superAdminTenantsActivate", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } } } } }, "/api/super-admin/tenants/{tenant}/admins": { "get": { "tags": [ "SuperAdmin" ], "operationId": "superAdminTenantAdminsIndex", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Tenant admins for this tenant (app login role tenant_admin)", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantUser" } } } } } } }, "post": { "tags": [ "SuperAdmin" ], "operationId": "superAdminTenantAdminsStore", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "username", "password" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "username": { "type": "string" }, "password": { "type": "string", "format": "password" } }, "type": "object" } } } }, "responses": { "201": { "description": "Additional tenant admin; can sign in via POST /auth/login", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUser" } } } }, "422": { "description": "Validation error" } } } }, "/api/super-admin/tenants/{tenant}/admins/{tenantUser}/block": { "post": { "tags": [ "SuperAdmin" ], "operationId": "superAdminTenantAdminsBlock", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "tenantUser", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Tenant admin membership blocked; tokens revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUser" } } } } } } }, "/api/super-admin/tenants/{tenant}/admins/{tenantUser}/unblock": { "post": { "tags": [ "SuperAdmin" ], "operationId": "superAdminTenantAdminsUnblock", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "tenantUser", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Unblocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUser" } } } } } } }, "/api/super-admin/users/{user}/block": { "post": { "tags": [ "SuperAdmin" ], "operationId": "superAdminUsersBlock", "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "User blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } } } } }, "/api/super-admin/users/{user}/unblock": { "post": { "tags": [ "SuperAdmin" ], "operationId": "superAdminUsersUnblock", "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "User unblocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } } } } }, "/api/tenant-admin/dashboard": { "get": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminDashboard", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project_id", "in": "query", "description": "Optional: show dashboard totals for one project only", "required": false, "schema": { "type": "integer" } }, { "name": "user_id", "in": "query", "description": "Optional: show dashboard totals for one service user only", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Tenant-wide dashboard: project counts, customer receipts, payouts, commission, holds, balances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dashboard" } } } } } } }, "/api/tenant-admin/masters": { "get": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminMasters", "parameters": [ { "$ref": "#/components/parameters/XTenantId" } ], "responses": { "200": { "description": "Solar panels and inverters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MastersResponse" } } } } } } }, "/api/tenant-admin/files/upload": { "post": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminFileUpload", "parameters": [ { "$ref": "#/components/parameters/XTenantId" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Returns JSON `{ \"key\": \"uploads/{tenant_id}/uuid.ext\" }`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } } } } } }, "/api/tenant-admin/service-users": { "get": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminServiceUsersIndex", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "user_id", "in": "query", "schema": { "type": "integer" } }, { "name": "is_blocked", "in": "query", "schema": { "type": "boolean" } }, { "name": "can_comment_on_payments", "in": "query", "schema": { "type": "boolean" } }, { "name": "q", "in": "query", "description": "Search name, email, username, phone", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantUser" } } } } } } }, "post": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminServiceUsersStore", "parameters": [ { "$ref": "#/components/parameters/XTenantId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "username", "password" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string", "format": "password" }, "can_comment_on_payments": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUser" } } } }, "422": { "description": "Limit or validation" } } } }, "/api/tenant-admin/service-users/{tenantUser}": { "patch": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminServiceUsersUpdate", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "tenantUser", "in": "path", "description": "`tenant_user.id`", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "username": { "type": "string" }, "password": { "description": "Optional; when changed, existing service-user API tokens are revoked", "type": "string", "format": "password" }, "can_comment_on_payments": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated service user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUser" } } } }, "422": { "description": "Validation error" } } } }, "/api/tenant-admin/service-users/{tenantUser}/block": { "post": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminServiceUsersBlock", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "tenantUser", "in": "path", "description": "`tenant_user.id`", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Blocked; revokes API tokens. User cannot log in or call `/app/*` (403 USER_BLOCKED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUser" } } } } } } }, "/api/tenant-admin/service-users/{tenantUser}/unblock": { "post": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminServiceUsersUnblock", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "tenantUser", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Unblocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUser" } } } } } } }, "/api/tenant-admin/projects": { "get": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminProjectsIndex", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "user_id", "in": "query", "description": "Filter by assigned service user id", "schema": { "type": "integer" } }, { "name": "assigned_user_id", "in": "query", "schema": { "type": "integer" } }, { "name": "created_by_user_id", "in": "query", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending_approval", "approved", "completed", "rejected" ] } }, { "name": "city", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "created_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "created_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "description": "Search customer name, phone, email, address, pincode", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "Paginated projects; each project includes financials summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pagination" } } } } } }, "post": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminProjectsStore", "parameters": [ { "$ref": "#/components/parameters/XTenantId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "customer_name", "kw", "project_cost", "bill_to_customer", "assigned_user_id" ], "properties": { "customer_name": { "type": "string" }, "kw": { "type": "number" }, "project_cost": { "description": "INR", "type": "number" }, "bill_to_customer": { "description": "Must be > project_cost when project_cost > 0; may be 0 when project_cost is 0", "type": "number" }, "gst_amount": { "description": "Optional override; otherwise auto-calculated from margin", "type": "number" }, "customer_phone": { "type": "string" }, "customer_email": { "type": "string" }, "address": { "type": "string" }, "state": { "type": "string" }, "city": { "type": "string" }, "pincode": { "type": "string" }, "solar_panel_id": { "type": "integer" }, "inverter_id": { "type": "integer" }, "commission_per_kw_override": { "type": "number" }, "assigned_user_id": { "description": "Service user in this tenant", "type": "integer" } }, "type": "object" } } } }, "responses": { "201": { "description": "Project created (approved)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } } } }, "/api/tenant-admin/projects/{project}": { "get": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminProjectsShow", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } } }, "patch": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminProjectsUpdate", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "customer_name": { "type": "string" }, "kw": { "type": "number" }, "project_cost": { "type": "number" }, "bill_to_customer": { "description": "Changing this recalculates gst_amount unless gst_amount is also sent", "type": "number" }, "gst_amount": { "description": "Manual GST hold; ledger recalculates from stored value", "type": "number" }, "assigned_user_id": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "422": { "description": "PROJECT_COMPLETED_LOCKED or INVALID_BILL_TO_CUSTOMER" } } } }, "/api/tenant-admin/projects/{project}/media": { "patch": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminProjectsMedia", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "photos_site_blank": { "description": "Comma-separated upload keys", "type": "string" }, "photos_structure": { "type": "string" }, "photos_solar_plate": { "type": "string" }, "photos_meter_final": { "type": "string" }, "other_documents": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } } } }, "/api/tenant-admin/projects/{project}/approve": { "post": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminProjectsApprove", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } } } }, "/api/tenant-admin/projects/{project}/complete": { "post": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminProjectsComplete", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Completed; allowed only from approved status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "422": { "description": "Project is not approved" } } } }, "/api/tenant-admin/projects/{project}/reject": { "post": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminProjectsReject", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } } } }, "/api/tenant-admin/payments": { "get": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminPaymentsIndex", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project_id", "in": "query", "schema": { "type": "integer" } }, { "name": "user_id", "in": "query", "description": "Filter by project assigned service user id", "schema": { "type": "integer" } }, { "name": "assigned_user_id", "in": "query", "schema": { "type": "integer" } }, { "name": "created_by_user_id", "in": "query", "schema": { "type": "integer" } }, { "name": "payout_request_id", "in": "query", "schema": { "type": "integer" } }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "credit", "debit" ] } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "customer_credit", "payout_debit" ] } }, { "name": "payment_date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "payment_date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "min_amount", "in": "query", "schema": { "type": "number" } }, { "name": "max_amount", "in": "query", "schema": { "type": "number" } }, { "name": "q", "in": "query", "description": "Search receiver, description, reference", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "Paginated payments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pagination" } } } } } }, "post": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminPaymentsStore", "parameters": [ { "$ref": "#/components/parameters/XTenantId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "project_id", "amount", "payment_date" ], "properties": { "project_id": { "type": "integer" }, "amount": { "description": "Customer payment received (credit only)", "type": "number" }, "receiver_name": { "type": "string" }, "payment_date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "utr_or_reference": { "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "description": "Customer credit logged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "422": { "description": "Debit not allowed (use payout request approve)" } } } }, "/api/tenant-admin/payments/{payment}": { "get": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminPaymentsShow", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "payment", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } } } }, "delete": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminPaymentsDestroy", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "payment", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } }, "patch": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminPaymentsUpdate", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "payment", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "direction": { "type": "string", "enum": [ "credit", "debit" ] }, "amount": { "type": "number" } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } } } } }, "/api/tenant-admin/projects/{project}/financials": { "get": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminProjectFinancials", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "user_id", "in": "query", "description": "Optional assigned service user guard/filter", "schema": { "type": "integer" } }, { "name": "payout_status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected" ] } }, { "name": "payout_method", "in": "query", "schema": { "type": "string", "enum": [ "bank", "upi" ] } }, { "name": "payment_date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "payment_date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "created_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "created_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "min_amount", "in": "query", "schema": { "type": "number" } }, { "name": "max_amount", "in": "query", "schema": { "type": "number" } }, { "name": "q", "in": "query", "description": "Search financial list references and beneficiary text", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ledger summary, credits, payout requests, debits", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/LedgerSummary" }, { "properties": { "credits": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "payout_requests": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutRequest" } }, "payout_debits": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "counts": { "type": "object" } }, "type": "object" } ] } } } } } } }, "/api/tenant-admin/payout-requests": { "get": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminPayoutRequestsIndex", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "project_id", "in": "query", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected" ] } }, { "name": "user_id", "in": "query", "description": "Filter by service user id", "schema": { "type": "integer" } }, { "name": "payout_method", "in": "query", "schema": { "type": "string", "enum": [ "bank", "upi" ] } }, { "name": "payout_type", "in": "query", "schema": { "type": "string", "enum": [ "standard", "gst" ] } }, { "name": "created_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "created_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "min_amount", "in": "query", "schema": { "type": "number" } }, { "name": "max_amount", "in": "query", "schema": { "type": "number" } }, { "name": "q", "in": "query", "description": "Search beneficiary details, note, reference", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "Paginated payout requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pagination" } } } } } } }, "/api/tenant-admin/payout-requests/{payoutRequest}": { "get": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminPayoutRequestsShow", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "payoutRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payout request detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutRequest" } } } } } } }, "/api/tenant-admin/payout-requests/{payoutRequest}/approve": { "post": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminPayoutRequestsApprove", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "payoutRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "utr_or_reference" ], "properties": { "utr_or_reference": { "type": "string" }, "payment_date": { "type": "string", "format": "date" } }, "type": "object" } } } }, "responses": { "200": { "description": "Approved; debit payment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutRequest" } } } } } } }, "/api/tenant-admin/payout-requests/{payoutRequest}/reject": { "post": { "tags": [ "TenantAdmin" ], "operationId": "tenantAdminPayoutRequestsReject", "parameters": [ { "$ref": "#/components/parameters/XTenantId" }, { "name": "payoutRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Rejected; hold released", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutRequest" } } } } } } } }, "components": { "schemas": { "MessageResponse": { "properties": { "message": { "type": "string", "example": "Logged out" } }, "type": "object" }, "UploadResponse": { "properties": { "key": { "type": "string", "example": "uploads/1/01HZX2Y7Z9N8WQ.jpg" } }, "type": "object" }, "Tenant": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Marwar Mechanization Pvt Ltd" }, "email": { "type": "string", "example": "marwarmechanization@gmail.com", "nullable": true }, "phone": { "type": "string", "example": "8003621369", "nullable": true }, "status": { "type": "string", "example": "active" }, "max_service_users": { "type": "integer", "example": 5 }, "default_commission_per_kw": { "type": "string", "example": "1000.0000" }, "created_at": { "type": "string", "example": "2026-05-25T09:30:00.000000Z", "nullable": true }, "updated_at": { "type": "string", "example": "2026-05-25T09:30:00.000000Z", "nullable": true } }, "type": "object" }, "User": { "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Marwar Mechanization Pvt Ltd" }, "username": { "type": "string", "example": "marwar" }, "email": { "type": "string", "example": "marwarmechanization@gmail.com" }, "phone": { "type": "string", "example": "8003621369", "nullable": true }, "is_super_admin": { "type": "boolean", "example": false }, "is_blocked": { "type": "boolean", "example": false } }, "type": "object" }, "Membership": { "properties": { "id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 1 }, "role": { "type": "string", "example": "tenant_admin" }, "tenant": { "$ref": "#/components/schemas/Tenant" } }, "type": "object" }, "AuthUser": { "allOf": [ { "$ref": "#/components/schemas/User" }, { "properties": { "membership": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/Membership" } ] } }, "type": "object" } ] }, "AuthLoginResponse": { "properties": { "token": { "type": "string", "example": "1|plain-text-sanctum-token" }, "token_type": { "type": "string", "example": "Bearer" }, "user": { "$ref": "#/components/schemas/AuthUser" } }, "type": "object" }, "TenantUser": { "properties": { "id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 2 }, "role": { "type": "string", "example": "service_user" }, "is_blocked": { "type": "boolean", "example": false }, "blocked_reason": { "type": "string", "nullable": true }, "can_comment_on_payments": { "type": "boolean", "example": true }, "abilities": { "type": "array", "items": { "type": "string" }, "nullable": true }, "user": { "$ref": "#/components/schemas/User" } }, "type": "object" }, "Project": { "properties": { "id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 1 }, "created_by_user_id": { "type": "integer", "example": 3 }, "assigned_user_id": { "type": "integer", "example": 3 }, "status": { "type": "string", "example": "approved", "enum": [ "pending_approval", "approved", "completed", "rejected" ] }, "customer_name": { "type": "string", "example": "Customer Name" }, "kw": { "type": "string", "example": "3.000" }, "project_cost": { "type": "string", "example": "180000.00" }, "bill_to_customer": { "description": "Customer bill amount; default GST = bill_to_customer × PROJECT_GST_RATE", "type": "string", "example": "220000.00" }, "gst_amount": { "description": "Stored GST liability; tenant admin may override", "type": "string", "example": "19580.00" }, "gst_rate_default": { "description": "Current config rate for new auto-calculations", "type": "number", "example": 0.089 }, "gst_rate_effective": { "description": "gst_amount ÷ bill_to_customer on this project", "type": "number", "example": 0.089 }, "customer_phone": { "type": "string", "nullable": true }, "customer_email": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "pincode": { "type": "string", "nullable": true }, "commission_per_kw_override": { "type": "string", "example": "1000.0000", "nullable": true }, "photos_site_blank": { "description": "Comma-separated upload keys", "type": "string", "nullable": true }, "photos_structure": { "description": "Comma-separated upload keys", "type": "string", "nullable": true }, "photos_solar_plate": { "description": "Comma-separated upload keys", "type": "string", "nullable": true }, "photos_meter_final": { "description": "Comma-separated upload keys", "type": "string", "nullable": true }, "other_documents": { "type": "array", "items": { "type": "object" }, "nullable": true }, "media": { "properties": { "photos_site_blank": { "type": "string", "nullable": true }, "photos_structure": { "type": "string", "nullable": true }, "photos_solar_plate": { "type": "string", "nullable": true }, "photos_meter_final": { "type": "string", "nullable": true }, "other_documents": { "type": "array", "items": { "type": "object" } } }, "type": "object", "nullable": true }, "assigned_user": { "oneOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true }, "creator": { "oneOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true }, "solar_panel": { "type": "object", "nullable": true }, "inverter": { "type": "object", "nullable": true }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" }, "nullable": true }, "payout_requests": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutRequest" }, "nullable": true }, "financials": { "description": "Tenant admin: ProjectFinancials. Service user app API: ServiceUserProjectFinancials.", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ProjectFinancials" }, { "$ref": "#/components/schemas/ServiceUserProjectFinancials" } ] } }, "type": "object" }, "Payment": { "properties": { "id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 1 }, "project_id": { "type": "integer", "example": 1 }, "created_by_user_id": { "type": "integer", "example": 2 }, "direction": { "type": "string", "example": "credit" }, "type": { "type": "string", "example": "customer_credit" }, "payout_request_id": { "type": "integer", "nullable": true }, "beneficiary_snapshot": { "type": "object", "nullable": true }, "amount": { "type": "string", "example": "124000.00" }, "receiver_name": { "type": "string", "nullable": true }, "payment_date": { "type": "string", "format": "date", "example": "2026-05-25" }, "description": { "type": "string", "nullable": true }, "utr_or_reference": { "type": "string", "example": "UTR123456", "nullable": true }, "project": { "$ref": "#/components/schemas/Project" } }, "type": "object" }, "PayoutRequest": { "properties": { "id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 1 }, "project_id": { "type": "integer", "example": 1 }, "requested_by_user_id": { "type": "integer", "example": 3 }, "amount": { "description": "Total payout; for GST type = net_amount + gst_amount", "type": "string", "example": "50000.00" }, "payout_type": { "type": "string", "example": "standard", "enum": [ "standard", "gst" ] }, "net_amount": { "type": "string", "example": "20000.00", "nullable": true }, "gst_amount": { "description": "GST component of payout request", "type": "string", "example": "5000.00", "nullable": true }, "bill_copy_key": { "type": "string", "example": "uploads/1/uuid.pdf", "nullable": true }, "status": { "type": "string", "example": "pending" }, "payout_method": { "type": "string", "example": "upi" }, "account_holder_name": { "type": "string", "example": "Service User", "nullable": true }, "bank_account": { "type": "string", "nullable": true }, "ifsc": { "type": "string", "nullable": true }, "bank_name": { "type": "string", "nullable": true }, "branch_name": { "type": "string", "nullable": true }, "upi_id": { "type": "string", "example": "service@upi", "nullable": true }, "note": { "type": "string", "nullable": true }, "reviewed_by_user_id": { "type": "integer", "nullable": true }, "reviewed_at": { "type": "string", "nullable": true }, "rejection_reason": { "type": "string", "nullable": true }, "payment_id": { "type": "integer", "nullable": true }, "utr_or_reference": { "type": "string", "nullable": true }, "project": { "$ref": "#/components/schemas/Project" }, "payment": { "oneOf": [ { "$ref": "#/components/schemas/Payment" } ], "nullable": true } }, "type": "object" }, "PayoutAccount": { "properties": { "id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 3 }, "type": { "type": "string", "example": "bank" }, "label": { "type": "string", "example": "Main SBI account", "nullable": true }, "account_holder_name": { "type": "string", "example": "Service User", "nullable": true }, "bank_account": { "type": "string", "example": "1234567890", "nullable": true }, "ifsc": { "type": "string", "example": "SBIN0001234", "nullable": true }, "bank_name": { "type": "string", "example": "SBI", "nullable": true }, "branch_name": { "type": "string", "example": "Main Branch", "nullable": true }, "upi_id": { "type": "string", "example": "service@upi", "nullable": true }, "is_default": { "type": "boolean", "example": true }, "created_at": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true } }, "type": "object" }, "ProjectFinancials": { "properties": { "project_cost": { "type": "number", "example": 180000 }, "bill_to_customer": { "type": "number", "example": 220000 }, "margin_amount": { "type": "number", "example": 40000 }, "gst_amount": { "type": "number", "example": 19580 }, "gst_recovered_via_payouts": { "type": "number", "example": 5000 }, "remaining_gst_liability": { "type": "number", "example": 14580 }, "protected_amount": { "type": "number", "example": 17580 }, "commission_amount": { "type": "number", "example": 3000 }, "tenant_total_income": { "type": "number", "example": 22580 }, "payable_to_service_user": { "type": "number", "example": 162420 }, "customer_received": { "type": "number", "example": 124000 }, "paid_to_service_user": { "type": "number", "example": 50000 }, "pending_payout_hold": { "type": "number", "example": 0 }, "cash_balance": { "type": "number", "example": 74000 }, "customer_receivable_remaining": { "type": "number", "example": 56000 }, "service_user_payable_remaining": { "type": "number", "example": 127000 }, "available_to_request": { "type": "number", "example": 77000 } }, "type": "object" }, "ServiceUserProjectFinancials": { "properties": { "project_cost": { "type": "number", "example": 180000 }, "bill_to_customer": { "type": "number", "example": 200000 }, "margin_amount": { "type": "number", "example": 20000 }, "gst_amount": { "type": "number", "example": 0 }, "gst_recovered_via_payouts": { "type": "number", "example": 5000 }, "remaining_gst_liability": { "type": "number", "example": 5680 }, "protected_amount": { "type": "number", "example": 3000 }, "commission_amount": { "type": "number", "example": 3000 }, "payable_to_service_user": { "type": "number", "example": 177000 }, "customer_received_by_tenant": { "type": "number", "example": 124000 }, "received_from_tenant": { "type": "number", "example": 50000 }, "pending_payout_hold": { "type": "number", "example": 0 }, "customer_receivable_remaining": { "type": "number", "example": 56000 }, "service_user_payable_remaining": { "type": "number", "example": 127000 }, "available_to_request": { "type": "number", "example": 77000 } }, "type": "object" }, "DashboardFinancials": { "description": "Unified financial summary for dashboard (tenant admin or service user).", "properties": { "total_project_amount": { "type": "number", "example": 180000 }, "approved_project_amount": { "type": "number", "example": 180000 }, "completed_project_amount": { "type": "number", "example": 0 }, "earning_project_amount": { "type": "number", "example": 180000 }, "commission_amount": { "type": "number", "example": 3000 }, "gst_amount": { "type": "number", "example": 0 }, "gst_recovered_via_payouts": { "type": "number", "example": 5000 }, "remaining_gst_liability": { "type": "number", "example": 5680 }, "protected_amount": { "type": "number", "example": 3000 }, "tenant_total_income": { "description": "Tenant admin dashboard", "type": "number", "example": 3000 }, "payable_to_service_user": { "type": "number", "example": 177000 }, "customer_received": { "description": "Tenant admin dashboard", "type": "number", "example": 124000 }, "paid_to_service_user": { "description": "Tenant admin dashboard", "type": "number", "example": 50000 }, "customer_received_by_tenant": { "description": "Service user dashboard", "type": "number", "example": 124000 }, "received_from_tenant": { "description": "Service user dashboard", "type": "number", "example": 50000 }, "pending_payout_hold": { "type": "number", "example": 0 }, "cash_balance": { "description": "Tenant admin dashboard", "type": "number", "example": 74000 }, "customer_receivable_remaining": { "type": "number", "example": 56000 }, "service_user_payable_remaining": { "type": "number", "example": 127000 }, "available_to_request": { "type": "number", "example": 77000 } }, "type": "object" }, "LedgerSummary": { "properties": { "project_id": { "type": "integer", "example": 1 }, "currency": { "type": "string", "example": "INR" }, "project_cost": { "type": "number", "example": 180000 }, "bill_to_customer": { "type": "number", "example": 220000 }, "margin_amount": { "type": "number", "example": 40000 }, "gst_amount": { "type": "number", "example": 19580 }, "gst_recovered_via_payouts": { "type": "number", "example": 5000 }, "remaining_gst_liability": { "type": "number", "example": 14580 }, "protected_amount": { "type": "number", "example": 17580 }, "commission_amount": { "type": "number", "example": 3000 }, "tenant_total_income": { "type": "number", "example": 22580 }, "payable_cap_to_service_user": { "type": "number", "example": 162420 }, "total_credit_received": { "type": "number", "example": 124000 }, "total_paid_to_service_user": { "type": "number", "example": 50000 }, "pending_payout_hold": { "type": "number", "example": 0 }, "available_to_request": { "type": "number", "example": 77000 }, "remaining_expected_from_customer": { "type": "number", "example": 56000 }, "remaining_to_pay_service_user": { "type": "number", "example": 127000 }, "kw": { "type": "number", "example": 3 }, "commission_per_kw_effective": { "type": "number", "example": 1000 } }, "type": "object" }, "Dashboard": { "properties": { "role": { "type": "string", "example": "tenant_admin" }, "currency": { "type": "string", "example": "INR" }, "tenant": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Marwar Mechanization Pvt Ltd" }, "status": { "type": "string", "example": "active" } }, "type": "object" }, "filters": { "properties": { "project_id": { "description": "Tenant admin: any tenant project. Service user: assigned project only.", "type": "integer", "example": 1, "nullable": true }, "user_id": { "description": "Tenant admin only", "type": "integer", "example": 3, "nullable": true } }, "type": "object" }, "projects": { "properties": { "total": { "type": "integer", "example": 10 }, "pending_approval": { "type": "integer", "example": 2 }, "approved": { "type": "integer", "example": 7 }, "completed": { "type": "integer", "example": 1 }, "rejected": { "type": "integer", "example": 1 }, "total_kw": { "type": "number", "example": 30 }, "total_project_cost": { "type": "number", "example": 1800000 }, "approved_project_cost": { "type": "number", "example": 1260000 }, "completed_project_cost": { "type": "number", "example": 180000 }, "earning_project_cost": { "type": "number", "example": 1440000 } }, "type": "object" }, "financials": { "$ref": "#/components/schemas/DashboardFinancials" }, "payout_requests": { "properties": { "total": { "type": "integer", "example": 3 }, "pending": { "type": "object", "example": { "count": 1, "amount": 10000 } }, "approved": { "type": "object", "example": { "count": 1, "amount": 50000 } }, "rejected": { "type": "object", "example": { "count": 1, "amount": 5000 } } }, "type": "object" }, "service_users": { "type": "object", "example": { "total": 5, "active": 4, "blocked": 1 }, "nullable": true }, "recent": { "type": "object" } }, "type": "object" }, "MastersResponse": { "properties": { "solar_panels": { "type": "array", "items": { "type": "object" } }, "inverters": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "Pagination": { "properties": { "current_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "type": "object" } }, "first_page_url": { "type": "string", "nullable": true }, "from": { "type": "integer", "example": 1, "nullable": true }, "last_page": { "type": "integer", "example": 1 }, "last_page_url": { "type": "string", "nullable": true }, "links": { "type": "array", "items": { "type": "object" } }, "next_page_url": { "type": "string", "nullable": true }, "path": { "type": "string", "example": "https://app.marwarmechanization.com/public/api/tenant-admin/projects" }, "per_page": { "type": "integer", "example": 50 }, "prev_page_url": { "type": "string", "nullable": true }, "to": { "type": "integer", "example": 1, "nullable": true }, "total": { "type": "integer", "example": 1 } }, "type": "object" } }, "parameters": { "XTenantId": { "name": "X-Tenant-ID", "in": "header", "description": "Optional. Not required for normal tenant admin / service user logins — the Bearer token resolves your tenant automatically. Only needed when one user belongs to multiple tenants and wants to switch context.", "required": false, "schema": { "type": "integer" } } }, "securitySchemes": { "sanctum": { "type": "http", "description": "Token from POST /auth/login (field `token`).", "bearerFormat": "Sanctum personal access token", "scheme": "bearer" } } }, "security": [ { "sanctum": [] } ], "tags": [ { "name": "Auth", "description": "Login and session" }, { "name": "SuperAdmin", "description": "Super admin" }, { "name": "TenantAdmin", "description": "Tenant admin (mobile app admin role)" }, { "name": "App", "description": "Service user (mobile app user role)" } ] }