Refactor Customer API Endpoints and Update Documentation

- Changed customer-related API endpoints to improve clarity and consistency, including renaming and restructuring routes.
- Removed unused query parameters and handlers, streamlining the customer management functionality.
- Updated customer entity and forms to reflect new example values for enhanced API documentation clarity.
- Enhanced response structures to return customer entities directly, simplifying the response handling in API endpoints.
- Updated API documentation to reflect changes in endpoint structure and response formats, ensuring consistency for API consumers.
This commit is contained in:
n.nakhostin
2025-09-06 16:08:53 +03:30
parent 05e7b50ec4
commit e848b625ce
9 changed files with 432 additions and 4437 deletions
+33 -669
View File
@@ -435,48 +435,6 @@ definitions:
is_verified:
type: boolean
type: object
customer.Address:
properties:
address_type:
description: billing, shipping, etc.
type: string
city:
type: string
country:
type: string
is_default:
type: boolean
postal_code:
type: string
state:
type: string
street:
type: string
type: object
customer.AddressForm:
properties:
address_type:
type: string
city:
type: string
country:
type: string
is_default:
type: boolean
postal_code:
type: string
state:
type: string
street:
type: string
type: object
customer.AssignCompaniesForm:
properties:
company_ids:
items:
type: string
type: array
type: object
customer.AuthResponse:
properties:
access_token:
@@ -495,100 +453,29 @@ definitions:
name:
type: string
type: object
customer.ContactPerson:
properties:
email:
type: string
first_name:
type: string
full_name:
type: string
is_primary:
type: boolean
last_name:
type: string
mobile:
type: string
phone:
type: string
position:
type: string
type: object
customer.ContactPersonForm:
properties:
email:
type: string
first_name:
type: string
full_name:
type: string
is_primary:
type: boolean
last_name:
type: string
mobile:
type: string
phone:
type: string
position:
type: string
type: object
customer.CreateCustomerForm:
properties:
address:
allOf:
- $ref: '#/definitions/customer.AddressForm'
description: Address information
annual_revenue:
type: number
business_type:
description: Business information
type: string
company_ids:
description: Company assignments
items:
type: string
type: array
contact_person:
allOf:
- $ref: '#/definitions/customer.ContactPersonForm'
description: Contact person (for company customers)
currency:
type: string
email:
example: user@opplens.com
type: string
employee_count:
type: integer
first_name:
description: Individual customer fields
type: string
founded_year:
type: integer
full_name:
type: string
industry:
type: string
language:
description: Preferences and settings
type: string
last_name:
type: string
mobile:
example: User
type: string
password:
example: User!1234
type: string
phone:
type: string
registration_number:
description: Company customer fields
type: string
tax_id:
type: string
timezone:
example: "+1234567890"
type: string
type:
example: individual
type: string
username:
example: user
type: string
type: object
customer.CustomerListResponse:
@@ -597,89 +484,49 @@ definitions:
items:
$ref: '#/definitions/customer.CustomerResponse'
type: array
limit:
type: integer
offset:
type: integer
total:
type: integer
total_pages:
type: integer
meta:
$ref: '#/definitions/response.Meta'
type: object
customer.CustomerResponse:
properties:
address:
$ref: '#/definitions/customer.Address'
annual_revenue:
type: number
business_type:
type: string
companies:
description: Company relationships
items:
$ref: '#/definitions/customer.CompanySummary'
type: array
compliance_notes:
type: string
contact_person:
$ref: '#/definitions/customer.ContactPerson'
created_at:
companyIDs:
items:
type: string
type: array
createdAt:
type: integer
created_by:
type: string
currency:
type: string
email:
type: string
employee_count:
type: integer
first_name:
type: string
founded_year:
type: integer
full_name:
fullName:
type: string
id:
type: string
industry:
type: string
is_compliant:
type: boolean
is_verified:
type: boolean
language:
type: string
last_name:
type: string
mobile:
lastLoginAt:
type: integer
password:
type: string
phone:
type: string
registration_number:
description: Company customer fields
type: string
status:
type: string
tax_id:
type: string
timezone:
type: string
type:
type: string
updated_at:
updatedAt:
type: integer
updated_by:
type: string
username:
type: string
type: object
customer.LoginForm:
properties:
password:
example: Nima.1998
example: App!1234
type: string
username:
example: nakhostin
example: app
type: string
type: object
customer.RefreshTokenForm:
@@ -687,90 +534,40 @@ definitions:
refresh_token:
type: string
type: object
customer.RemoveCompaniesForm:
properties:
company_ids:
items:
type: string
type: array
type: object
customer.SuspendCustomerForm:
properties:
reason:
type: string
type: object
customer.UpdateCustomerForm:
properties:
address:
allOf:
- $ref: '#/definitions/customer.AddressForm'
description: Address information
annual_revenue:
type: number
business_type:
description: Business information
type: string
company_ids:
description: Company assignments
items:
type: string
type: array
company_name:
description: Company customer fields
type: string
contact_person:
allOf:
- $ref: '#/definitions/customer.ContactPersonForm'
description: Contact person (for company customers)
currency:
type: string
email:
example: user@opplens.com
type: string
employee_count:
type: integer
first_name:
description: Individual customer fields
type: string
founded_year:
type: integer
full_name:
example: User
type: string
industry:
type: string
language:
description: Preferences and settings
type: string
last_name:
type: string
mobile:
password:
example: User!1234
type: string
phone:
type: string
registration_number:
type: string
tax_id:
type: string
timezone:
example: "+1234567890"
type: string
type:
example: individual
type: string
username:
example: user
type: string
type: object
customer.UpdateCustomerStatusForm:
customer.UpdateStatusForm:
properties:
reason:
example: Customer is active
type: string
status:
example: active
type: string
type: object
customer.UpdateCustomerVerificationForm:
properties:
compliance_notes:
type: string
is_compliant:
type: boolean
is_verified:
type: boolean
type: object
feedback.CompanyFeedbackStatsResponse:
properties:
company_id:
@@ -2477,26 +2274,6 @@ paths:
in: query
name: company_id
type: string
- description: Filter by industry
in: query
name: industry
type: string
- description: Filter by verification status
in: query
name: is_verified
type: boolean
- description: Filter by compliance status
in: query
name: is_compliant
type: boolean
- description: Filter by preferred language
in: query
name: language
type: string
- description: Filter by preferred currency
in: query
name: currency
type: string
- default: 20
description: Number of customers per page (1-100)
in: query
@@ -2733,131 +2510,6 @@ paths:
summary: Update customer information
tags:
- Admin-Customers
/admin/v1/customers/{id}/activate:
post:
consumes:
- application/json
description: Activate a suspended customer account
parameters:
- description: Customer ID
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: Customer activated successfully
schema:
$ref: '#/definitions/response.APIResponse'
"400":
description: Bad request - Invalid customer ID
schema:
$ref: '#/definitions/response.APIResponse'
"404":
description: Not found - Customer not found
schema:
$ref: '#/definitions/response.APIResponse'
"500":
description: Internal server error
schema:
$ref: '#/definitions/response.APIResponse'
security:
- BearerAuth: []
summary: Activate customer
tags:
- Admin-Customers
/admin/v1/customers/{id}/companies/assign:
post:
consumes:
- application/json
description: Assign one or more companies to a specific customer.
parameters:
- description: Customer ID
in: path
name: id
required: true
type: string
- description: List of company IDs to assign
in: body
name: companies
required: true
schema:
$ref: '#/definitions/customer.AssignCompaniesForm'
produces:
- application/json
responses:
"200":
description: Companies assigned successfully
schema:
$ref: '#/definitions/response.APIResponse'
"400":
description: Bad request - Invalid input data
schema:
$ref: '#/definitions/response.APIResponse'
"404":
description: Not found - Customer not found
schema:
$ref: '#/definitions/response.APIResponse'
"422":
description: Validation error - Invalid request data
schema:
$ref: '#/definitions/response.APIResponse'
"500":
description: Internal server error
schema:
$ref: '#/definitions/response.APIResponse'
security:
- BearerAuth: []
summary: Assign companies to a customer
tags:
- Admin-Customers
/admin/v1/customers/{id}/companies/remove:
post:
consumes:
- application/json
description: Remove one or more companies from a specific customer.
parameters:
- description: Customer ID
in: path
name: id
required: true
type: string
- description: List of company IDs to remove
in: body
name: companies
required: true
schema:
$ref: '#/definitions/customer.RemoveCompaniesForm'
produces:
- application/json
responses:
"200":
description: Companies removed successfully
schema:
$ref: '#/definitions/response.APIResponse'
"400":
description: Bad request - Invalid input data
schema:
$ref: '#/definitions/response.APIResponse'
"404":
description: Not found - Customer not found
schema:
$ref: '#/definitions/response.APIResponse'
"422":
description: Validation error - Invalid request data
schema:
$ref: '#/definitions/response.APIResponse'
"500":
description: Internal server error
schema:
$ref: '#/definitions/response.APIResponse'
security:
- BearerAuth: []
summary: Remove companies from a customer
tags:
- Admin-Customers
/admin/v1/customers/{id}/status:
patch:
consumes:
@@ -2874,7 +2526,7 @@ paths:
name: status
required: true
schema:
$ref: '#/definitions/customer.UpdateCustomerStatusForm'
$ref: '#/definitions/customer.UpdateStatusForm'
produces:
- application/json
responses:
@@ -2903,294 +2555,6 @@ paths:
summary: Update customer status
tags:
- Admin-Customers
/admin/v1/customers/{id}/suspend:
post:
consumes:
- application/json
description: Suspend a customer account with optional reason
parameters:
- description: Customer ID
in: path
name: id
required: true
type: string
- description: Suspension information
in: body
name: suspension
required: true
schema:
$ref: '#/definitions/customer.SuspendCustomerForm'
produces:
- application/json
responses:
"200":
description: Customer suspended successfully
schema:
$ref: '#/definitions/response.APIResponse'
"400":
description: Bad request - Invalid input data
schema:
$ref: '#/definitions/response.APIResponse'
"404":
description: Not found - Customer not found
schema:
$ref: '#/definitions/response.APIResponse'
"422":
description: Validation error - Invalid request data
schema:
$ref: '#/definitions/response.APIResponse'
"500":
description: Internal server error
schema:
$ref: '#/definitions/response.APIResponse'
security:
- BearerAuth: []
summary: Suspend customer
tags:
- Admin-Customers
/admin/v1/customers/{id}/verification:
patch:
consumes:
- application/json
description: Update customer verification and compliance status
parameters:
- description: Customer ID
in: path
name: id
required: true
type: string
- description: Verification status update
in: body
name: verification
required: true
schema:
$ref: '#/definitions/customer.UpdateCustomerVerificationForm'
produces:
- application/json
responses:
"200":
description: Customer verification updated successfully
schema:
$ref: '#/definitions/response.APIResponse'
"400":
description: Bad request - Invalid input data
schema:
$ref: '#/definitions/response.APIResponse'
"404":
description: Not found - Customer not found
schema:
$ref: '#/definitions/response.APIResponse'
"422":
description: Validation error - Invalid request data
schema:
$ref: '#/definitions/response.APIResponse'
"500":
description: Internal server error
schema:
$ref: '#/definitions/response.APIResponse'
security:
- BearerAuth: []
summary: Update customer verification status
tags:
- Admin-Customers
/admin/v1/customers/{id}/verify:
post:
consumes:
- application/json
description: Mark a customer as verified
parameters:
- description: Customer ID
in: path
name: id
required: true
type: string
produces:
- application/json
responses:
"200":
description: Customer verified successfully
schema:
$ref: '#/definitions/response.APIResponse'
"400":
description: Bad request - Invalid customer ID
schema:
$ref: '#/definitions/response.APIResponse'
"404":
description: Not found - Customer not found
schema:
$ref: '#/definitions/response.APIResponse'
"500":
description: Internal server error
schema:
$ref: '#/definitions/response.APIResponse'
security:
- BearerAuth: []
summary: Verify customer
tags:
- Admin-Customers
/admin/v1/customers/company/{companyId}:
get:
consumes:
- application/json
description: Retrieve all customers associated with a specific company
parameters:
- description: Company ID
in: path
name: companyId
required: true
type: string
- description: 'Number of customers to return (default: 10, max: 100)'
in: query
name: limit
type: integer
- description: 'Number of customers to skip (default: 0)'
in: query
name: offset
type: integer
produces:
- application/json
responses:
"200":
description: Customers retrieved successfully
schema:
allOf:
- $ref: '#/definitions/response.APIResponse'
- properties:
data:
items:
$ref: '#/definitions/customer.CustomerResponse'
type: array
type: object
"400":
description: Bad request - Invalid company ID
schema:
$ref: '#/definitions/response.APIResponse'
"500":
description: Internal server error
schema:
$ref: '#/definitions/response.APIResponse'
security:
- BearerAuth: []
summary: Get customers by company ID
tags:
- Admin-Customers
/admin/v1/customers/status/{status}:
get:
consumes:
- application/json
description: Retrieve customers filtered by their account status (active, inactive,
suspended, or pending). Useful for administrative monitoring and management.
parameters:
- description: Customer status
enum:
- active
- inactive
- suspended
- pending
in: path
name: status
required: true
type: string
- default: 20
description: Number of customers per page (1-100)
in: query
maximum: 100
minimum: 1
name: limit
type: integer
- default: 0
description: Number of customers to skip for pagination
in: query
minimum: 0
name: offset
type: integer
produces:
- application/json
responses:
"200":
description: Customers retrieved successfully
schema:
allOf:
- $ref: '#/definitions/response.APIResponse'
- properties:
data:
items:
$ref: '#/definitions/customer.CustomerResponse'
type: array
meta:
$ref: '#/definitions/response.Meta'
type: object
"400":
description: Bad request - Invalid customer status
schema:
$ref: '#/definitions/response.APIResponse'
"500":
description: Internal server error
schema:
$ref: '#/definitions/response.APIResponse'
security:
- BearerAuth: []
summary: Get customers by status
tags:
- Admin-Customers
/admin/v1/customers/type/{type}:
get:
consumes:
- application/json
description: Retrieve customers filtered by their type (individual, company,
or government). Useful for administrative reporting and management.
parameters:
- description: Customer type
enum:
- individual
- company
- government
in: path
name: type
required: true
type: string
- default: 20
description: Number of customers per page (1-100)
in: query
maximum: 100
minimum: 1
name: limit
type: integer
- default: 0
description: Number of customers to skip for pagination
in: query
minimum: 0
name: offset
type: integer
produces:
- application/json
responses:
"200":
description: Customers retrieved successfully
schema:
allOf:
- $ref: '#/definitions/response.APIResponse'
- properties:
data:
items:
$ref: '#/definitions/customer.CustomerResponse'
type: array
meta:
$ref: '#/definitions/response.Meta'
type: object
"400":
description: Bad request - Invalid customer type
schema:
$ref: '#/definitions/response.APIResponse'
"500":
description: Internal server error
schema:
$ref: '#/definitions/response.APIResponse'
security:
- BearerAuth: []
summary: Get customers by type
tags:
- Admin-Customers
/admin/v1/feedback:
get:
consumes: