Customer API

The Customer API allows you to create optical customers with their personal information, prescription data, and manage customer records. This endpoint supports file uploads for prescriptions and other documents.

This endpoint uses multipart/form-data format to support file uploads. Make sure to include the proper headers when making requests.

Endpoint Details

Base URL: https://j-optic.fly.dev

Required Headers

x-store-id: <store_id>
Authorization: Bearer <token>

Create Customer

Endpoint

Endpoint: POST /customer
Content-Type: multipart/form-data

Request Structure

The request uses multipart/form-data format with:

jsonData: A JSON string containing the customer data
Files: Optional prescription documents or attachments uploaded with specific field names

Customer Data Structure

The jsonData field must contain a JSON string with the following structure:

Field	Type	Required	Description
`customerData`	object	✅ Yes	Personal information of the customer
`address`	object	No	Customer address details
`opticData`	object	No	Optical prescription measurements

CustomerData Object

Field	Type	Required	Description
`firstName`	string	✅ Yes	Customer’s first name
`lastName`	string	✅ Yes	Customer’s last name
`email`	string	✅ Yes	Customer’s email address (unique)
`phoneNumber`	string	✅ Yes	Customer’s phone number
`dateOfBirth`	string (ISO Date)	✅ Yes	Date of birth in ISO format
`sex`	string	✅ Yes	Gender: “male” or “female”

Address Object

Field	Type	Required	Description
`street`	string	No	Street address
`city`	string	No	City name
`zipCode`	string	No	Postal/ZIP code
`state`	string	No	State or province

OpticData Object

Contains vision prescription data for different viewing distances:

Field	Type	Required	Description
`distanceVision`	object	No	Distance vision prescription
`intermediateVision`	object	No	Intermediate vision prescription
`nearVision`	object	No	Near vision prescription

Each vision object contains rightEye and leftEye with:

sph (sphere): Spherical power
cyl (cylinder): Cylindrical power
axis: Axis measurement

Create Customer Examples

Example 1: Create Customer with Full Optical Data

curl -X POST https://j-optic.fly.dev/customer \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>" \
  -F 'jsonData={
    "customerData": {
      "firstName": "Layla",
      "lastName": "Hassan",
      "email": "[email protected]",
      "phoneNumber": "+1-555-0199",
      "dateOfBirth": "1992-05-12T00:00:00.000Z",
      "sex": "female"
    },
    "address": {
      "street": "123 Vision Ave",
      "city": "Casablanca",
      "zipCode": "20000",
      "state": "MA"
    },
    "opticData": {
      "distanceVision": {
        "rightEye": { "sph": "-1.25", "cyl": "-0.25", "axis": "90" },
        "leftEye": { "sph": "-1.00", "cyl": "-0.25", "axis": "85" }
      },
      "intermediateVision": {
        "rightEye": { "sph": "-0.75", "cyl": "0", "axis": "0" },
        "leftEye": { "sph": "-0.75", "cyl": "0", "axis": "0" }
      },
      "nearVision": {
        "rightEye": { "sph": "-0.50", "cyl": "0", "axis": "0" },
        "leftEye": { "sph": "-0.50", "cyl": "0", "axis": "0" }
      }
    }
  }' \
  -F '[email protected]' \
  -F '[email protected]'

Success Response:

{
  "customer": {
    "id": "customer-uuid",
    "isActive": true,
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z",
    "deletedAt": null
  },
  "localData": {
    "id": "local-data-uuid",
    "firstName": "Layla",
    "lastName": "Hassan",
    "email": "[email protected]",
    "phoneNumber": "+1-555-0199",
    "dateOfBirth": "1992-05-12T00:00:00.000Z",
    "sex": "female",
    "customerId": "customer-uuid"
  }
}

Example 2: Create Customer with Minimal Data

curl -X POST https://j-optic.fly.dev/customer \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>" \
  -F 'jsonData={
    "customerData": {
      "firstName": "Ahmed",
      "lastName": "Benali",
      "email": "[email protected]",
      "phoneNumber": "+212-6-12345678",
      "dateOfBirth": "1985-08-20T00:00:00.000Z",
      "sex": "male"
    }
  }'

Get All Customers

Endpoint

Endpoint: GET /customer

Query Parameters

Parameter	Type	Required	Default	Description
`search`	string	No	-	Search by first name, last name, or username
`name`	string	No	-	Filter by specific name (first or last)
`isActive`	boolean	No	-	Filter by active status
`page`	number	No	1	Page number for pagination
`limit`	number	No	10	Number of records per page
`sortBy`	string	No	createdAt	Sort field: “name”, “status”, “createdAt”, “updatedAt”
`sortOrder`	string	No	desc	Sort order: “asc” or “desc”

Get Customers Examples

Example 1: Get All Customers (Default Pagination)

curl -X GET "https://j-optic.fly.dev/customer" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Example 2: Search Customers with Filters

curl -X GET "https://j-optic.fly.dev/customer?search=Hassan&isActive=true&page=1&limit=20&sortBy=name&sortOrder=asc" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Success Response:

{
  "data": [
    {
      "id": "customer-uuid",
      "name": "Layla Hassan",
      "userName": "[email protected]",
      "groups": [
        {
          "id": "group-uuid",
          "name": "VIP Customers"
        }
      ],
      "isLocal": true,
      "status": "active",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}

Example 3: Get Active Customers Only

curl -X GET "https://j-optic.fly.dev/customer?isActive=true&sortBy=createdAt&sortOrder=desc" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Response Structures

Create Customer Response

{
  "customer": {
    "id": "customer-uuid",
    "isActive": true,
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z",
    "deletedAt": null
  },
  "localData": {
    "id": "local-data-uuid",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "phoneNumber": "string",
    "dateOfBirth": "ISO date string",
    "sex": "male | female",
    "customerId": "customer-uuid"
  }
}

Get Customers Response

{
  "data": [
    {
      "id": "customer-uuid",
      "name": "Full Name",
      "userName": "[email protected]",
      "groups": [
        {
          "id": "group-uuid",
          "name": "Group Name"
        }
      ],
      "isLocal": true,
      "status": "active | unactive",
      "createdAt": "ISO date string",
      "updatedAt": "ISO date string"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  }
}

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid input data or missing required fields",
  "error": "Bad Request"
}

403 Forbidden

{
  "statusCode": 403,
  "message": "You do not have access to this store",
  "error": "Forbidden"
}

409 Conflict

{
  "statusCode": 409,
  "message": "Customer with this email already exists",
  "error": "Conflict"
}

500 Internal Server Error

{
  "statusCode": 500,
  "message": "Failed to create customer",
  "error": "Internal Server Error"
}

Important Notes

Store Access Requirements

Create Customer

Requires user to be an owner of the store
Validates userStoreRelation for active owner relationship
Missing ownership raises ForbiddenException

Get Customers

Requires user to have access to the store
Can be owner or have assigned role/permissions
Store access is validated via userStoreRelation

Email Handling

Email addresses are trimmed and stored as provided
Email must be unique per store
Duplicate emails result in ConflictException (409)

File Uploads

Supported Files

Upload prescription documents, ID cards, or related files
Grouped by fieldname

Optional Upload

Files are optional for customer creation
Basic customer data sufficient

Customer Status

Customers are created with isActive: true by default
Status can be filtered in GET requests using isActive parameter
Deleted customers have deletedAt timestamp (soft delete)

Name Display Logic

The customer name follows this fallback order:

firstName + lastName from local data
userName from user table
Placeholder value if neither available

Pagination

Default Behavior
Custom Pagination

{
  page: 1,
  limit: 10,
  sortBy: "createdAt",
  sortOrder: "desc"
}

Returns 10 most recent customers by default

{
  page: 2,
  limit: 50,
  sortBy: "name",
  sortOrder: "asc"
}

Customize page size and sorting

Summary

Authenticate

Obtain JWT token and ensure store access

Prepare Customer Data

Structure JSON with required customer information

Create Customer

POST request with multipart form data

Retrieve Customers

GET request with optional filters and pagination

Handle Response

Process customer data and pagination metadata

This API provides comprehensive customer management for optical stores, including prescription data storage, file uploads, and flexible querying with pagination and filtering capabilities.

Purchase Invoice API

Create purchase invoices and manage inventory

Store Management

Manage stores and permissions

J-optic

​Customer API

​Endpoint Details

​Required Headers

​Create Customer

​Endpoint

​Request Structure

​Customer Data Structure

​CustomerData Object

​Address Object

​OpticData Object

​Create Customer Examples

​Example 1: Create Customer with Full Optical Data

​Example 2: Create Customer with Minimal Data

​Get All Customers

​Endpoint

​Query Parameters

​Get Customers Examples

​Example 1: Get All Customers (Default Pagination)

​Example 2: Search Customers with Filters

​Example 3: Get Active Customers Only

​Response Structures

​Create Customer Response

​Get Customers Response

​Error Responses

​400 Bad Request

​403 Forbidden

​409 Conflict

​500 Internal Server Error

​Important Notes

​Store Access Requirements

​Email Handling

​File Uploads

Supported Files

Optional Upload

​Customer Status

​Name Display Logic

​Pagination

​Summary

Purchase Invoice API

Store Management

Customer API

Endpoint Details

Required Headers

Create Customer

Endpoint

Request Structure

Customer Data Structure

CustomerData Object

Address Object

OpticData Object

Create Customer Examples

Example 1: Create Customer with Full Optical Data

Example 2: Create Customer with Minimal Data

Get All Customers

Endpoint

Query Parameters

Get Customers Examples

Example 1: Get All Customers (Default Pagination)

Example 2: Search Customers with Filters

Example 3: Get Active Customers Only

Response Structures

Create Customer Response

Get Customers Response

Error Responses

400 Bad Request

403 Forbidden

409 Conflict

500 Internal Server Error

Important Notes

Store Access Requirements

Email Handling

File Uploads

Customer Status

Name Display Logic

Pagination

Summary