OpenAPI Specification
openapi: 3.0.0
info:
title: Earnipay Invoicing App Customers API
description: FIRS-compliant e-invoicing platform API
version: '1.0'
contact: {}
servers: []
tags:
- name: Customers
description: Customer management for invoicing
paths:
/v1/customers:
post:
description: Create a new customer for the current business. Customer names must be unique per business.
operationId: CustomerController_createCustomer_v1
parameters:
- name: businessId
required: true
in: query
description: Business ID (passed as query parameter or extracted from context)
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomerDto'
responses:
'201':
description: Customer created successfully
'400':
description: Bad Request - Invalid input data
'401':
description: Unauthorized
'403':
description: Forbidden - No access to this business
'409':
description: Conflict - Customer name already exists
security:
- JWT-auth: []
summary: Create new customer
tags:
- Customers
get:
description: Retrieve paginated list of customers with search, filter, and sort capabilities.
operationId: CustomerController_getCustomers_v1
parameters:
- name: businessId
required: true
in: query
description: Business ID
schema:
type: string
- name: page
required: false
in: query
description: Page number
schema:
minimum: 1
default: 1
example: 1
type: number
- name: limit
required: false
in: query
description: Items per page (max 100)
schema:
minimum: 1
maximum: 100
default: 20
example: 20
type: number
- name: search
required: false
in: query
description: Search in name, business name, TIN, email
schema:
example: John Doe
type: string
- name: dateFrom
required: false
in: query
description: Filter by creation date from (YYYY-MM-DD)
schema:
example: '2024-01-01'
type: string
- name: dateTo
required: false
in: query
description: Filter by creation date to (YYYY-MM-DD)
schema:
example: '2024-12-31'
type: string
- name: sortBy
required: false
in: query
description: Sort field
schema:
enum:
- name
- businessName
- createdAt
- updatedAt
type: string
- name: sortOrder
required: false
in: query
description: Sort order
schema:
enum:
- asc
- desc
type: string
responses:
'200':
description: Customers retrieved successfully
'401':
description: Unauthorized
'403':
description: Forbidden - No access to this business
security:
- JWT-auth: []
summary: Get customers list
tags:
- Customers
/v1/customers/{id}:
get:
description: Retrieve detailed information about a specific customer.
operationId: CustomerController_getCustomerById_v1
parameters:
- name: id
required: true
in: path
description: Customer ID
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
responses:
'200':
description: Customer details retrieved successfully
'401':
description: Unauthorized
'403':
description: Forbidden - No access to this customer's business
'404':
description: Customer not found
security:
- JWT-auth: []
summary: Get customer details
tags:
- Customers
patch:
description: Update customer information. Customer name must remain unique per business.
operationId: CustomerController_updateCustomer_v1
parameters:
- name: id
required: true
in: path
description: Customer ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCustomerDto'
responses:
'200':
description: Customer updated successfully
'400':
description: Bad Request - Invalid input data
'401':
description: Unauthorized
'403':
description: Forbidden - No access to this customer's business
'404':
description: Customer not found
'409':
description: Conflict - Customer name already exists
security:
- JWT-auth: []
summary: Update customer
tags:
- Customers
delete:
description: Soft delete a customer. Historical invoices with this customer will remain intact.
operationId: CustomerController_deleteCustomer_v1
parameters:
- name: id
required: true
in: path
description: Customer ID
schema:
type: string
responses:
'200':
description: Customer deleted successfully
'401':
description: Unauthorized
'403':
description: Forbidden - No access to this customer's business
'404':
description: Customer not found
security:
- JWT-auth: []
summary: Delete customer
tags:
- Customers
components:
schemas:
UpdateCustomerDto:
type: object
properties:
name:
type: string
description: Customer name (person or contact name)
example: John Doe
minLength: 2
maxLength: 200
businessName:
type: string
description: Business/Company name
example: Acme Corporation Ltd
minLength: 2
maxLength: 200
tin:
type: string
description: Tax Identification Number (TIN)
example: 12345678-0001
email:
type: string
description: Customer email address
example: john.doe@example.com
phone:
type: string
description: Customer phone number
example: '+2348012345678'
address:
type: string
description: Street address
example: 123 Lagos Street
city:
type: string
description: City
example: Lagos
state:
type: string
description: State/Province
example: Lagos State
country:
type: string
description: Country
example: Nigeria
postalCode:
type: string
description: Postal code
example: '100001'
CreateCustomerDto:
type: object
properties:
name:
type: string
description: Customer name (person or contact name)
example: John Doe
minLength: 2
maxLength: 200
businessName:
type: string
description: Business/Company name (if customer is a business)
example: Acme Corporation Ltd
minLength: 2
maxLength: 200
tin:
type: string
description: Tax Identification Number (TIN)
example: 12345678-0001
email:
type: string
description: Customer email address
example: john.doe@example.com
phone:
type: string
description: Customer phone number
example: '+2348012345678'
address:
type: string
description: Street address
example: 123 Lagos Street
city:
type: string
description: City
example: Lagos
state:
type: string
description: State/Province
example: Lagos State
country:
type: string
description: Country
example: Nigeria
default: Nigeria
postalCode:
type: string
description: Postal code
example: '100001'
required:
- name
securitySchemes:
JWT-auth:
scheme: bearer
bearerFormat: JWT
type: http
name: JWT
description: Enter JWT token
in: header
API-Key:
type: apiKey
in: header
name: X-API-Key
description: API Key for third-party integrations