Doclin — API Documentation

Create User API

Endpoint

POST https://doclin.kazico.in/api/auth/create_user.php

Description

Create a new system user. Passwords are hashed server-side.

Headers

Key	Value
Content-Type	application/x-www-form-urlencoded

Request Parameters

Field	Type	Required	Description
username	string	Yes	Mobile number or name
password	string	Yes	Plain password (server hashes)
roles	string/array	Yes	Comma-separated or JSON array
created_by	string	Yes	Creator identifier
account_active	string	No	Defaults to "yes"

Example cURL

curl --location 'https://doclin.kazico.in/api/auth/create_user.php' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=admin' \
--data-urlencode 'password=pass@123' \
--data-urlencode 'roles=admin,doctor,pharmacy,reception' \
--data-urlencode 'created_by=system'

Example Response

{
  "status": "success",
  "message": "User created successfully",
  "user": { "id": 1, "username": "admin", "roles": ["admin","doctor","pharmacy","reception"], "account_active":"yes", "created_by":"system" }
}

Login (Issue Access & Refresh Tokens)

Endpoint

POST https://doclin.kazico.in/api/auth/login.php

Description

Authenticate user and return access (JWT) and refresh tokens plus user profile.

Headers

Key	Value
Content-Type	application/x-www-form-urlencoded

Request Parameters

Field	Type	Required	Description
username	string	Yes	Mobile number or name
password	string	Yes	User password

Example cURL

curl --location 'https://doclin.kazico.in/api/auth/login.php' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=admin' \
--data-urlencode 'password=pass@123'

Paste below line in Scripts tab in Postman to automatically use the active token all API

pm.environment.set("access_token", pm.response.json().access_token);

Example Response

{
  "status": "success",
  "message": "Login successful",
  "access_token": "",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "",
  "refresh_expires_at": "2025-12-20 13:55:00",
  "user": { "id": 1, "username": "admin", "roles": ["admin"], "account_active": "yes" }
}

Notes

Store refresh tokens securely (httpOnly cookie recommended).
Access token should be used in Authorization: Bearer <token> header.

Refresh Token

Endpoint

POST https://doclin.kazico.in/api/auth/refresh.php

Description

Exchange a valid refresh token for a new access token and a rotated refresh token.

Headers

Key	Value
Content-Type	application/x-www-form-urlencoded

Request Parameters

Field	Type	Required	Description
refresh_token	string	Yes	Refresh token received from login

Example cURL

curl --location 'https://doclin.kazico.in/api/auth/refresh.php' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token='

Example Response

{
  "status": "success",
  "access_token": "",
  "expires_in": 3600,
  "refresh_token": "",
  "refresh_expires_at": "2025-12-21 12:55:00"
}

Notes

Old refresh token is removed on rotation.
Access tokens are not auto-extended — always call this endpoint to reissue tokens.

Logout / Revoke Tokens

Endpoint

POST https://doclin.kazico.in/api/auth/logout.php

Description

Revoke access (blacklist JWT) and delete refresh token from DB.

Headers

Key	Value
Authorization	Bearer {{access_token}}
Content-Type	application/x-www-form-urlencoded

Request Parameters

Field	Type	Required	Description
refresh_token	string	No	Refresh token to revoke (optional)

Example cURL

curl --location 'https://doclin.kazico.in/api/auth/logout.php' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token='

Example Response

{ "status":"success", "message":"Logged out (tokens revoked)" }

Add Patient — Create Patient

Endpoint

POST https://doclin.kazico.in/api/patient/create.php

Description

Create a patient record. Returns autogenerated patient_id and patient_id_str.

Headers

Key	Value
Authorization	Bearer {{access_token}}
Content-Type	application/json

Request Parameters

Field	Type	Required	Description
first_name	string	Yes	Patient first name
last_name	string	Yes	Patient last name
gender	string	Yes	Male / Female / Other
mobile_no	string	Yes	Primary mobile number
date_of_birth	date	No	YYYY-MM-DD
age_years	int	No	Age in years

Example cURL

curl --location 'https://doclin.kazico.in/api/patient/create.php' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
  "first_name": "Rahul",
  "last_name": "Mehta",
  "gender": "Male",
  "mobile_no": "9876543210",
  "date_of_birth": "1990-02-14"
}'

Example Response

{
  "success": true,
  "message": "Patient created",
  "patient_id": 102,
  "patient_id_str": "P000102"
}

Add Patient — Step 1: Update

Endpoint

POST https://doclin.kazico.in/api/patient/update_step1.php

Description

Update primary patient fields (requires patient_id).

Headers

Key	Value
Authorization	Bearer {{access_token}}
Content-Type	application/json

Request Parameters

Field	Type	Required	Description
patient_id	int	Yes	ID returned from create
first_name	string	No	Patient first name
last_name	string	No	Patient last name
mobile_no	string	No	Primary mobile

Example cURL

curl --location 'https://doclin.kazico.in/api/patient/update_step1.php' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
  "patient_id": 102,
  "first_name": "Rahul",
  "last_name": "M.",
  "mobile_no": "9999988888"
}'

Example Response

{
  "success": true,
  "message": "Step1 updated",
  "affected_rows": 1
}

Add Patient — Step 2: Personal Details

Endpoint

POST https://doclin.kazico.in/api/patient/update_step2.php

Description

Height, weight, blood group, address and similar personal fields.

Headers

Key	Value
Authorization	Bearer {{access_token}}
Content-Type	application/json

Request Parameters

Field	Type	Required	Description
patient_id	int	Yes	Patient id
height_cm	decimal	No	Height in cm
weight_kg	decimal	No	Weight in kg
blood_group	string	No	Blood group

Example cURL

curl --location 'https://doclin.kazico.in/api/patient/update_step2.php' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
  "patient_id": 102,
  "height_cm": 172,
  "weight_kg": 70,
  "blood_group": "O+"
}'

Example Response

{
  "success": true,
  "message": "Step2 updated"
}

Add Patient — Step 3: Lifestyle

Endpoint

POST https://doclin.kazico.in/api/patient/update_step3.php

Description

Smoking, alcohol, food preference, occupation and activity level.

Headers

Key	Value
Authorization	Bearer {{access_token}}
Content-Type	application/json

Request Parameters

Field	Type	Required	Description
patient_id	int	Yes	Patient id
smoking_habits	string	No	Daily / Occasionally / Never
food_preference	string	No	Veg / Non-Veg / Vegan
occupation	string	No	Profession

Example cURL

curl --location 'https://doclin.kazico.in/api/patient/update_step3.php' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
  "patient_id": 102,
  "smoking_habits": "Never",
  "food_preference": "Veg",
  "occupation": "Software Engineer"
}'

Example Response

{
  "success": true,
  "message": "Step3 updated"
}

Add Patient — Step 4: Medical History

Endpoint

POST https://doclin.kazico.in/api/patient/update_step4.php

Description

Chronic diseases, surgeries, family history etc.

Headers

Key	Value
Authorization	Bearer {{access_token}}
Content-Type	application/json

Request Parameters

Field	Type	Required	Description
patient_id	int	Yes	Patient id
chronic_diseases	text	No	Comma-separated or long text
surgeries	text	No	Surgeries history
family_history_json	json	No	Array (father/mother/siblings)

Example cURL

curl --location 'https://doclin.kazico.in/api/patient/update_step4.php' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
  "patient_id": 102,
  "chronic_diseases": "Hypertension",
  "family_history_json": ["Diabetes (Father)", "Asthma (Mother)"]
}'

Example Response

{
  "success": true,
  "message": "Step4 updated"
}

Add Patient — Step 5: Allergies

Endpoint

POST https://doclin.kazico.in/api/patient/update_step5.php

Description

Food, medicine and other allergies.

Headers

Key	Value
Authorization	Bearer {{access_token}}
Content-Type	application/json

Request Parameters

Field	Type	Required	Description
patient_id	int	Yes	Patient id
food_allergies	text	No	Food-based allergies
medicine_allergies	text	No	Medicine-based allergies

Example cURL

curl --location 'https://doclin.kazico.in/api/patient/update_step5.php' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
  "patient_id": 102,
  "food_allergies": "Peanuts",
  "medicine_allergies": "Penicillin"
}'

Example Response

{
  "success": true,
  "message": "Step5 updated"
}

Add Patient — Step 6: Birth History

Endpoint

POST https://doclin.kazico.in/api/patient/update_step6.php

Description

Birth details: delivery, gestation, birth weight, APGAR, etc.

Headers

Key	Value
Authorization	Bearer {{access_token}}
Content-Type	application/json

Request Parameters

Field	Type	Required	Description
patient_id	int	Yes	Patient id
mode_of_delivery	string	No	Normal / C-section etc.
birth_weight_kg	decimal	No	Birth weight

Example cURL

curl --location 'https://doclin.kazico.in/api/patient/update_step6.php' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
  "patient_id": 102,
  "mode_of_delivery": "Normal",
  "birth_weight_kg": 3.2
}'

Example Response

{
  "success": true,
  "message": "Step6 updated"
}

Uploads — Profile Photo Upload

Endpoint

POST https://doclin.kazico.in/api/patient/upload_profile.php

Description

Upload patient profile image; accepts multipart/form-data.

Headers

Key	Value
Authorization	Bearer {{access_token}}
Content-Type	multipart/form-data

Request Parameters (form)

Field	Type	Required	Description
patient_id	int	Yes	Patient ID
file	file	Yes	Image file (jpg/png/webp)
save_to_files_table	0/1	No	Insert record into patient_files

Example cURL

curl -F "patient_id=102" \
-F "file=@/path/to/photo.jpg" \
-F "save_to_files_table=1" \
-H "Authorization: Bearer {{access_token}}" \
"https://doclin.kazico.in/api/patient/upload_profile.php"

Example Response

{
  "success": true,
  "message": "Profile image uploaded",
  "file_path": "/uploads/patients/102/profile/profile_1732291282_ab12cd.png"
}

Uploads — ID Proof Upload

Endpoint

POST https://doclin.kazico.in/api/patient/upload_id_proof.php

Description

Upload patient ID proof (image or PDF) via multipart/form-data.

Headers

Key	Value
Authorization	Bearer {{access_token}}
Content-Type	multipart/form-data

Request Parameters (form)

Field	Type	Required	Description
patient_id	int	Yes	Patient ID
file	file	Yes	Image or PDF
proof_type	string	No	Aadhaar, PAN, Passport

Example cURL

curl -F "patient_id=102" \
-F "file=@/path/to/idproof.pdf" \
-F "proof_type=Aadhaar" \
-H "Authorization: Bearer {{access_token}}" \
"https://doclin.kazico.in/api/patient/upload_id_proof.php"

Example Response

{
  "success": true,
  "message": "ID proof uploaded",
  "file_path": "/uploads/patients/102/id_proof/id_aadhaar_1732291132_ef98aa.pdf"
}

List Patients API

Endpoint

GET https://doclin.kazico.in/api/patient/list.php

Description

Paginated list of patients with search and sorting options.

Headers

Key	Value
Authorization	Bearer <JWT_TOKEN>

Query Parameters

Parameter	Type	Default	Description
page	int	1	Page number
per_page	int	25	Results per page (max 200)
search	string	—	Search first/last name, mobile, ID
sort_by	string	created_at	id, first_name, last_name, created_at
sort_dir	string	desc	asc or desc

Example cURL

curl -X GET "https://doclin.kazico.in/api/patient/list.php" \
  -H "Authorization: Bearer <JWT_TOKEN>"

Example Response

{
  "success": true,
  "page": 1,
  "per_page": 25,
  "total": 123,
  "data": [
    {
      "id": 1,
      "patient_id_str": "PAT-0001",
      "first_name": "John",
      "last_name": "Doe",
      "mobile_no": "9876543210",
      "date_of_birth": "1990-01-01",
      "created_at": "2025-11-01 12:34:56"
    }
  ]
}

Patient Details API

Endpoint

GET https://doclin.kazico.in/api/patient/details.php

Description

Fetch full details of a single patient using id, patient_id_str, or mobile_no. Optional parameter skip_null can remove null fields from the response.

Headers

Key	Value
Authorization	Bearer <JWT Token>
Content-Type	application/json or application/x-www-form-urlencoded

Request Parameters

Field	Type	Required	Description
id	integer	No*	Primary numeric patient ID
patient_id_str	string	No*	External patient ID (e.g. `P000001`)
mobile_no	string	No*	Digits-only mobile number
skip_null	0 or 1	No	If `1`, all `null` fields are removed from `data` in the response.

* At least one of id, patient_id_str, mobile_no must be provided.

Example cURL

curl --location 'https://doclin.kazico.in/api/patient/details.php?id=1&skip_null=1' \
--header 'Authorization: Bearer <token>'

Example Response (skip_null = 1)

{
  "status": "success",
  "message": "Patient fetched successfully.",
  "data": {
    "id": 1,
    "first_name": "Rahul",
    "last_name": "M.",
    "gender": "Male",
    "mobile_no": "9999988888",
    "patient_id_str": "P000001",
    "register_for": "Self",
    "created_at": "2025-11-22 13:44:56",
    "updated_at": "2025-11-22 13:46:31"
  }
}

Possible Errors

{
  "status": "error",
  "message": "Patient not found."
}

{
  "status": "error",
  "message": "Missing identifier. Provide one of: id, patient_id_str, or mobile_no."
}

{
  "status": "error",
  "message": "Unauthorized / Invalid Token"
}

{
  "status": "error",
  "message": "Server error",
  "debug": "..."   // only in development
}

Settings — Clinics API

Endpoint

POST/GET/PUT/DELETE https://doclin.kazico.in/api/settings/clinics.php

Description

Manage clinic names and locations used across the Doclin system. Supports full CRUD operations.

Headers

Key	Value
Content-Type	application/x-www-form-urlencoded
Accept	application/json
Authorization	Bearer <JWT token>

Request Parameters

Field	Type	Required	Description
name	string	Yes (create)	Clinic name
location	string	No	Clinic address or location
id	int	Yes (for GET/PUT/DELETE)	ID passed as query (?id=1)

Example cURL — Create

curl --location 'https://doclin.kazico.in/api/settings/clinics.php' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'name=Ghansoli Clinic' \
--data-urlencode 'location=Ghansoli, Navi Mumbai'

Example cURL — List

curl --location 'https://doclin.kazico.in/api/settings/clinics.php' \
--header 'Authorization: Bearer {{access_token}}'

Example cURL — Get by ID

curl --location 'https://doclin.kazico.in/api/settings/clinics.php?id=1' \
--header 'Authorization: Bearer {{access_token}}'

Example cURL — Update

curl --location --request PUT 'https://doclin.kazico.in/api/settings/clinics.php?id=1' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'name=Updated Clinic' \
--data-urlencode 'location=New Address'

Example cURL — Delete

curl --location --request DELETE 'https://doclin.kazico.in/api/settings/clinics.php?id=1' \
--header 'Authorization: Bearer {{access_token}}'

Example Response

{
  "status": "success",
  "message": "Clinic created successfully",
  "data": { "id": 5, "name": "Ghansoli Clinic", "location": "Ghansoli, Navi Mumbai" }
}

Settings — Departments API

Endpoint

POST/GET/PUT/DELETE https://doclin.kazico.in/api/settings/departments.php

Description

Create and manage medical departments (e.g. Dermatology, Pediatrics). Supports full CRUD.

Headers

Key	Value
Content-Type	application/x-www-form-urlencoded
Accept	application/json
Authorization	Bearer <JWT token>

Request Parameters

Field	Type	Required	Description
name	string	Yes	Department name
id	int	Yes (GET/PUT/DELETE)	ID passed (?id=1)

Example cURL — Create

curl --location 'https://doclin.kazico.in/api/settings/departments.php' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'name=Dermatology'

Example cURL — List

curl --location 'https://doclin.kazico.in/api/settings/departments.php' \
--header 'Authorization: Bearer {{access_token}}'

Example cURL — Get by ID

curl --location 'https://doclin.kazico.in/api/settings/departments.php?id=1' \
--header 'Authorization: Bearer {{access_token}}'

Example cURL — Update

curl --location --request PUT 'https://doclin.kazico.in/api/settings/departments.php?id=1' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'name=Updated Department'

Example cURL — Delete

curl --location --request DELETE 'https://doclin.kazico.in/api/settings/departments.php?id=1' \
--header 'Authorization: Bearer {{access_token}}'

Example Response

{
  "status": "success",
  "message": "Department created",
  "data": { "id": 3, "name": "Dermatology" }
}

Settings — Doctors API

Endpoint

POST/GET/PUT/DELETE https://doclin.kazico.in/api/settings/doctors.php

Description

Manage doctor details including name, department, clinic assignment, phone, and email. Full CRUD supported. API responses include department and clinic names for display.

Headers

Key	Value
Content-Type	application/x-www-form-urlencoded
Accept	application/json
Authorization	Bearer <JWT token>

Request Parameters

Field	Type	Required	Description
name	string	Yes	Doctor's name
department_id	int	Yes	ID of department
clinic_id	int	Yes	Clinic ID
phone	string	No	Phone number
email	string	No	Email address
id	int	Yes (GET/PUT/DELETE)	ID passed (?id=1)

Example cURL — Create

curl --location 'https://doclin.kazico.in/api/settings/doctors.php' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'name=Dr. Rohan Mehta' \
--data-urlencode 'department_id=2' \
--data-urlencode 'clinic_id=1' \
--data-urlencode 'phone=9988776655' \
--data-urlencode 'email=rohan@example.com'

Example cURL — List

curl --location 'https://doclin.kazico.in/api/settings/doctors.php' \
--header 'Authorization: Bearer {{access_token}}'

Example cURL — Get by ID

curl --location 'https://doclin.kazico.in/api/settings/doctors.php?id=1' \
--header 'Authorization: Bearer {{access_token}}'

Example cURL — Update

curl --location --request PUT 'https://doclin.kazico.in/api/settings/doctors.php?id=1' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'clinic_id=2' \
--data-urlencode 'phone=9876501234'

Example cURL — Delete

curl --location --request DELETE 'https://doclin.kazico.in/api/settings/doctors.php?id=1' \
--header 'Authorization: Bearer {{access_token}}'

Example Response

{
  "status": "success",
  "message": "Doctor created",
  "data": {
    "id": 10,
    "name": "Dr. Rohan Mehta",
    "department_id": 2,
    "department_name": "Dermatology",
    "clinic_id": 1,
    "clinic_name": "Ghansoli Clinic",
    "phone": "9988776655",
    "email": "rohan@example.com"
  }
}

Schedule — Appointments API

Endpoint

https://doclin.kazico.in/api/schedule/appointments.php

Description

Unified REST endpoint for appointment scheduling. Appointments now store only patient_id — patient details come from the patients table.

Fields (request / response)

Field	Type	Description
id	int	Primary key
patient_id	int	Reference to patients.id (required)
clinic_id	int	Clinic id
doctor_id	int	Doctor id
appointment_type	string	Consultation / Follow-up / Teleconsult
duration_minutes	int	Duration in minutes
appointment_date	YYYY-MM-DD	Date
appointment_time	HH:MM	Time
case_id	int\|null	Optional case reference
service_type	string	Service / Procedure
notes	text	Notes
status	enum	Scheduled, Checked-In, Completed, Cancelled, No-Show
payment_status	enum	Paid, Unpaid, Concession
referral_status	enum	Paid, Unpaid, Concession
source	string	Walk-in, Phone, Online, etc.
external_reference	string	External id / partner reference
created_at	datetime	Record creation timestamp
updated_at	datetime	Last update timestamp
deleted_at	datetime\|null	Soft-delete timestamp (NULL if not deleted)

Notes

Do not pass patient name / mobile in appointment requests. Use patient_id.
Responses include a patient object with id, first_name, last_name, mobile_no, email and full_name.
Use prevent_overlaps: true in POST body to enable exact-match overlap checks (same doctor, date & time).

Create Appointment (POST)

curl --location 'https://doclin.kazico.in/api/schedule/appointments.php' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "patient_id": 42,
  "clinic_id": 1,
  "doctor_id": 12,
  "appointment_type": "Consultation",
  "duration_minutes": 20,
  "appointment_date": "2025-12-05",
  "appointment_time": "11:30",
  "service_type": "General Checkup",
  "notes": "First visit",
  "status": "Scheduled",
  "payment_status": "Unpaid",
  "referral_status": "Unpaid",
  "source": "Phone",
  "prevent_overlaps": true
}'

Example Response

{
  "message": "Appointment created",
  "id": 1254
}

Get Appointments (GET)

curl --location 'https://doclin.kazico.in/api/schedule/appointments.php?clinic_id=1&date=2025-12-05' \
--header 'Authorization: Bearer {{access_token}}'

Example Response

[
  {
    "id": 1254,
    "patient_id": 42,
    "clinic_id": 1,
    "doctor_id": 12,
    "appointment_date": "2025-12-05",
    "appointment_time": "11:30",
    "status": "Scheduled",
    "patient": {
      "id": 42,
      "title": "Ms.",
      "first_name": "Rita",
      "last_name": "Sharma",
      "mobile_no": "9876543210",
      "email": "rita@example.com",
      "full_name": "Ms. Rita Sharma"
    }
  }
]

Get Single Appointment (GET)

curl --location 'https://doclin.kazico.in/api/schedule/appointments.php?id=1254' \
--header 'Authorization: Bearer {{access_token}}'

Update Appointment (PUT)

curl --location --request PUT 'https://doclin.kazico.in/api/schedule/appointments.php?id=1254' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "appointment_time": "12:00",
  "status": "Checked-In",
  "payment_status": "Paid",
  "patient_id": 42
}'

Example Response

{
  "message": "Appointment updated",
  "rowCount": 1
}

Cancel Appointment (DELETE)

curl --location --request DELETE 'https://doclin.kazico.in/api/schedule/appointments.php?id=1254' \
--header 'Authorization: Bearer {{access_token}}'

Example Response

{
  "message": "Appointment cancelled (soft deleted)"
}

Vendors

Endpoint

https://doclin.kazico.in/api/settings/vendors.php

Description

Manage vendor records including name, addresses, contact details, GST information and status.

Fields

Field	Type	Required	Description
name	string	Yes	Vendor name
address	string	No	Primary address
billing_address	string	No	Billing address (optional)
contact_person	string	No	Primary contact person
email	string	No	Email address
mobile_number	string	No	Mobile number
company_number	string	No	Company / landline number
gst_number	string	No	GSTIN identifier
status	string	No	Active / Inactive

List Vendors

GET https://doclin.kazico.in/api/settings/vendors.php

Get Vendor

GET https://doclin.kazico.in/api/settings/vendors.php?id={id}

Create Vendor

POST https://doclin.kazico.in/api/settings/vendors.php

Update Vendor

PUT https://doclin.kazico.in/api/settings/vendors.php?id={id}

Delete Vendor

DELETE https://doclin.kazico.in/api/settings/vendors.php?id={id}

Example cURL (Create Vendor)

curl --location 'https://doclin.kazico.in/api/settings/vendors.php' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "name": "ABC Medical Supplies",
  "address": "Industrial Estate",
  "billing_address": "PO Box 22",
  "contact_person": "John Doe",
  "email": "contact@abc.com",
  "mobile_number": "9876543210",
  "company_number": "02212345678",
  "gst_number": "27AAAAA0000A1Z5",
  "status": "Active"
}'

Example Response

{
  "message": "Vendor created",
  "id": 12
}

Notes

All calls require Authorization: Bearer <access_token>.
DELETE may be replaced with status update for soft delete.

Vendor Search

Endpoint

POST https://doclin.kazico.in/api/settings/vendor_search.php

Description

Search vendors using any supported identifier. If an exact identifier is provided (id, gst_number, mobile_number, company_number), the API returns a single vendor. If only name is provided, the API returns multiple matches.

Search Parameters

Field	Type	Required	Description
id	int	No	Exact match by vendor ID
gst_number	string	No	Exact match GST number
mobile_number	string	No	Exact mobile number
company_number	string	No	Exact company phone / landline
name	string	No	Partial name match (returns list)
limit	int	No	Result limit for name searches (default 25)
skip_null	int	No	1 = remove NULL fields from response

Example cURL (Search by Name)

curl --location 'https://doclin.kazico.in/api/settings/vendor_search.php' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "name": "medical",
  "limit": 10
}'

Example cURL (Search by GST Number)

curl --location 'https://doclin.kazico.in/api/settings/vendor_search.php' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "gst_number": "27AAAAA0000A1Z5"
}'

Example Response (Exact Match)

{
  "status": "success",
  "message": "Vendor fetched successfully.",
  "data": {
    "id": 12,
    "name": "ABC Medical Supplies",
    "mobile_number": "9876543210",
    "gst_number": "27AAAAA0000A1Z5",
    "contact_person": "John Doe",
    "status": "Active"
  }
}

Example Response (Multiple Matches)

{
  "status": "success",
  "message": "Vendors search results.",
  "count": 2,
  "data": [
    {
      "id": 12,
      "name": "ABC Medical Supplies",
      "mobile_number": "9876543210"
    },
    {
      "id": 15,
      "name": "Medical Traders Pvt Ltd",
      "mobile_number": "9876512345"
    }
  ]
}

Notes

If id, gst_number, mobile_number, or company_number is provided, API returns a single vendor.
name triggers partial search and returns multiple results.
All requests require Authorization: Bearer <access_token>.
skip_null=1 strips NULL fields from response.

Medicines — CRUD

Endpoint

https://doclin.kazico.in/api/settings/medicines.php

Description

Full CRUD for medicines. Uses a single table to store product/brand/compound, packaging info (units per strip, strips per box, units per pack), pricing (purchase price, MRP), discount and GST info, and canonical stock in base units. Authentication is required — send Authorization: Bearer <access_token>.

Key Fields

Field	Type	Required	Description
product_name	string	Yes	e.g. Dolo 650
brand_name	string	Yes	Manufacturer
compound_name	string	Yes	Active ingredient
base_unit	string	No	Smallest unit (tablet, capsule, ml). Set for tab/cap products.
units_per_strip	int	No	e.g. 10 (for blister/strip)
strips_per_box	int	No	e.g. 10 (for boxes containing strips)
units_per_pack	int	No	Explicit total units per pack (optional)
default_selling	string	No	Default selling granularity: 'unit'/'strip'/'pack'
purchase_price, mrp	decimal	No	Pricing
default_discount, max_discount, gst_rate	decimal	No	Discount & tax rules
stock_base_units	bigint	No	Authoritative stock in base units (tablets)

Example cURL — Create (tablets in box)

curl --location 'https://doclin.kazico.in/api/settings/medicines.php' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "product_name":"Dolo 650",
  "brand_name":"Pfizer",
  "compound_name":"Paracetamol",
  "base_unit":"tablet",
  "pack_type":"box",
  "units_per_strip":10,
  "strips_per_box":10,
  "default_selling":"strip",
  "purchase_price":10.00,
  "mrp":20.00,
  "default_discount":5.00,
  "gst_rate":12.00,
  "max_discount":15.00,
  "stock_base_units":125
}'

Example cURL — Update

curl --location --request PUT 'https://doclin.kazico.in/api/settings/medicines.php?id=123' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{ "stock_base_units": 200 }'

Notes

All requests require Authorization: Bearer <access_token>.
Prefer using the dedicated stock API (stock movements ledger) to change stock_base_units; seeding on create is allowed.
default_selling controls UI/pos defaults: some SKUs sell by unit, some by strip or pack.

Medicines — Search

Endpoint

https://doclin.kazico.in/api/settings/medicines_search.php

Description

Authenticated search — prefix & partial matching across product, brand and compound. Uses stock_base_units to compute availability and a human-friendly stock_display. If a matched product has zero stock, the API returns alternatives from the same compound with stock > 0.

Parameters

Field	Type	Required	Description
q	string	No	Search query
limit	int	No	Default 20
pref_stock	int	No	1 = show in-stock items first
barcode	string	No	Lookup by packaging barcode

Example cURL — Search

curl --location 'https://doclin.kazico.in/api/settings/medicines_search.php?q=para&pref_stock=1&limit=10' \
--header 'Authorization: Bearer {{access_token}}'

Example Response

{
  "query":"dolo",
  "count":1,
  "results":[
    {
      "id":199,
      "product_name":"Dolo 650",
      "brand_name":"Pfizer",
      "compound_name":"Paracetamol",
      "stock_base_units":125,
      "stock_display":"1 box, 2 strips, 5 tablets"
    }
  ],
  "alternatives":[
    {
      "id":200,
      "product_name":"Paracip 650",
      "brand_name":"Lupin",
      "compound_name":"Paracetamol",
      "stock_base_units":50,
      "stock_display":"5 strips"
    }
  ]
}

Notes

Search requires authentication.
stock_display is computed from packaging fields and stock_base_units.
Frontends should use default_selling to decide whether to show unit/strip/pack sell button by default.

Stock Movement API

Endpoint

POST https://doclin.kazico.in/api/stock/move.php

Description

This endpoint handles all changes to medicine stock. Every inbound or outbound quantity is logged in the stock ledger and the medicines.stock_base_units snapshot is updated in a single atomic transaction.

Supports two methods:

Packaging-aware updates (packs / strips / units)
Direct base-unit delta (change_in_base_units)

Also accepts an optional amount to record the monetary value of the movement. Authentication is required for all requests.

Parameters

Field	Type	Required	Description
medicine_id	int	Yes	Medicine to update
change_type	string	No	`in` = add stock, `out` = subtract stock. If omitted, direction inferred from values.
qty_packs	int	No	Packs/boxes count
qty_strips	int	No	Strips count
qty_units	int	No	Loose units (tablets/capsules)
change_in_base_units	int	No	Direct delta (+/-). Overrides packaging calculations.
reason	string	No	Reason for change (purchase, sale, adjustment, invoice, return...)
reference	string	No	PO number, Invoice number, etc.
amount	decimal	No	Monetary value of the movement (optional)

Stock Behaviour

The API converts all packaging into base units (e.g., tablets).
The movement is recorded in stock_movements.
The medicine's stock_base_units is updated inside the same transaction.
The response includes updated stock_display (boxes, strips, units).

Example cURL — Inbound (Purchase)

curl --location 'https://doclin.kazico.in/api/stock/move.php' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "medicine_id": 123,
  "change_type": "in",
  "qty_packs": 2,
  "qty_strips": 0,
  "qty_units": 0,
  "reason": "purchase",
  "reference": "PO-123",
  "amount": 1800.50
}'

Example cURL — Outbound (Invoice / Billing)

curl --location 'https://doclin.kazico.in/api/stock/move.php' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "medicine_id": 123,
  "change_type": "out",
  "qty_strips": 1,
  "qty_units": 3,
  "reason": "invoice",
  "reference": "INV-456",
  "amount": 150.00
}'

Example cURL — Direct Base Units Change

curl --location 'https://doclin.kazico.in/api/stock/move.php' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "medicine_id": 123,
  "change_in_base_units": -15,
  "reason": "sale",
  "reference": "INV-789",
  "amount": 120.00
}'

Example Response

{
  "success": true,
  "movement": {
    "medicine_id": 123,
    "packaging_context": "1 strips, 3 units",
    "change_in_base_units": -13,
    "reason": "invoice",
    "reference": "INV-456"
  },
  "new_stock": 112,
  "medicine": {
    "id": 123,
    "product_name": "Dolo 650",
    "stock_base_units": 112,
    "stock_display": "1 box, 1 strip, 2 tablets"
  }
}

Notes

Either send packaging quantities OR change_in_base_units.
If both are sent, change_in_base_units takes precedence.
Stock never becomes inconsistent because movement + medicine update use the same transaction.
amount can be used later for valuation, weighted average costing, supplier reports, etc.

Invoice API

Endpoints

GET    https://doclin.kazico.in/api/invoice/invoices.php
GET    https://doclin.kazico.in/api/invoice/invoices.php?id={invoice_id}
POST   https://doclin.kazico.in/api/invoice/invoices.php
PUT    https://doclin.kazico.in/api/invoice/invoices.php?id={invoice_id}
DELETE https://doclin.kazico.in/api/invoice/invoices.php?id={invoice_id}

Description

REST API for managing pharmacy invoices with full stock integration.

The API enforces server-side calculations, packaging-aware quantities, and authoritative stock movements through /api/stock/move.php.

DELETE does not physically remove data. It performs an invoice cancellation workflow and reverses stock for all invoice items.

Authentication is required for all requests.

Invoice Master Parameters (POST / PUT)

Field	Type	Required	Description
invoice_no	string	Yes	Unique invoice number
invoice_date	date	Yes	Invoice date (YYYY-MM-DD)
customer_id	int	Yes	Customer ID
doctor_id	int	Yes	Doctor ID
grand_total	decimal	Yes	Total amount (validated server-side)
paid_amount	decimal	No	Amount paid (default 0)

Invoice Item Parameters

Field	Type	Required	Description
medicine_id	int	Yes	Medicine ID (authoritative)
qty_packs	int	No	Packaging quantity (exactly one qty field required)
qty_strips	int	No	Packaging quantity (exactly one qty field required)
qty_units	int	No	Loose units (exactly one qty field required)
discount_percent	decimal	Yes	Discount percentage

Computed & Derived Fields

Base units are computed using packaging_helpers.php.
Unit rate, GST %, and pricing are fetched from the medicines table.
Line totals are calculated server-side.
grand_total must exactly match the sum of computed line totals.
payment_status is derived:
- UNPAID → paid = 0
- PARTIAL → paid < grand_total
- PAID → paid ≥ grand_total

Invoice Lifecycle & Stock Behaviour

POST — Creates invoice and reduces stock.
PUT — Updates invoice and reconciles stock using quantity differences.
DELETE — Cancels invoice and reverses stock fully.
No invoice is physically deleted; cancelled invoices remain for audit.

Example cURL — Create Invoice

curl --location 'https://doclin.kazico.in/api/invoice/invoices.php' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "invoice_no": "INV-1001",
  "invoice_date": "2025-01-10",
  "customer_id": 21,
  "doctor_id": 5,
  "grand_total": 1180.00,
  "paid_amount": 1000.00,
  "items": [
    {
      "medicine_id": 12,
      "qty_strips": 1,
      "discount_percent": 5
    },
    {
      "medicine_id": 8,
      "qty_units": 10,
      "discount_percent": 0
    }
  ]
}'

Example cURL — Get Invoice

curl --location 'https://doclin.kazico.in/api/invoice/invoices.php?id=123' \
--header 'Authorization: Bearer {{access_token}}'

Example cURL — Update Invoice

curl --location 'https://doclin.kazico.in/api/invoice/invoices.php?id=123' \
--request PUT \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "grand_total": 950.00,
  "items": [
    {
      "medicine_id": 12,
      "qty_units": 5,
      "discount_percent": 5
    }
  ]
}'

Example cURL — Cancel Invoice (DELETE)

curl --location 'https://doclin.kazico.in/api/invoice/invoices.php?id=123' \
--request DELETE \
--header 'Authorization: Bearer {{access_token}}'

Example Response

{
  "success": true,
  "invoice_id": 123,
  "payment_status": "PARTIAL"
}

Notes

Exactly one quantity field must be sent per item.
Frontend values are never trusted for calculations.
All stock changes go through /api/stock/move.php.
Cancelled invoices cannot be modified.
This design preserves auditability and stock integrity.

Invoice Returns API

Endpoints

GET    https://doclin.kazico.in/api/invoice/returns.php
GET    https://doclin.kazico.in/api/invoice/returns.php?id={return_id}
GET    https://doclin.kazico.in/api/invoice/returns.php?invoice_id={invoice_id}
POST   https://doclin.kazico.in/api/invoice/returns.php
PUT    https://doclin.kazico.in/api/invoice/returns.php?id={return_id}
DELETE https://doclin.kazico.in/api/invoice/returns.php?id={return_id}

Description

REST API for handling medicine returns against invoices.

The return system supports partial returns, maintains full audit history, and ensures accurate stock reconciliation using the central stock movement engine.

Returns never modify the original invoice.
All returned quantities are recorded as separate return documents.

DELETE does not remove data. It performs a return cancellation workflow and reverses stock accordingly.

Authentication is required for all requests.

Return Master Parameters (POST / PUT)

Field	Type	Required	Description
invoice_id	int	Yes	Original invoice ID
return_no	string	Yes (POST)	Unique return number
return_date	date	Yes	Return date (YYYY-MM-DD)
reason	string	No	Reason for return

Return Item Parameters

Field	Type	Required	Description
medicine_id	int	Yes	Medicine being returned
qty_packs	int	No	Packaging quantity (exactly one qty field required)
qty_strips	int	No	Packaging quantity (exactly one qty field required)
qty_units	int	No	Loose units (exactly one qty field required)

Validation Rules

Exactly one quantity field must be provided per item.
Returned quantity cannot exceed sold quantity minus already returned quantity.
Base units are calculated using packaging_helpers.php.
Refund amount is calculated server-side using the original invoice unit rate.

Return Lifecycle & Stock Behaviour

POST — Creates return and adds stock back.
PUT — Updates return and reconciles stock using quantity differences.
DELETE — Cancels return and removes stock again.
No return is physically deleted; cancelled returns remain for audit.

Example cURL — Create Return

curl --location 'https://doclin.kazico.in/api/invoice/returns.php' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "invoice_id": 123,
  "return_no": "RET-1001",
  "return_date": "2025-01-15",
  "reason": "Customer returned unused medicine",
  "items": [
    {
      "medicine_id": 12,
      "qty_strips": 2
    }
  ]
}'

Example cURL — Get Return

curl --location 'https://doclin.kazico.in/api/invoice/returns.php?id=10' \
--header 'Authorization: Bearer {{access_token}}'

Example cURL — Get Returns for Invoice

curl --location 'https://doclin.kazico.in/api/invoice/returns.php?invoice_id=123' \
--header 'Authorization: Bearer {{access_token}}'

Example cURL — Update Return

curl --location 'https://doclin.kazico.in/api/invoice/returns.php?id=10' \
--request PUT \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
  "items": [
    {
      "medicine_id": 12,
      "qty_units": 5
    }
  ]
}'

Example cURL — Cancel Return (DELETE)

curl --location 'https://doclin.kazico.in/api/invoice/returns.php?id=10' \
--request DELETE \
--header 'Authorization: Bearer {{access_token}}'

Example Response

{
  "success": true,
  "return_id": 10,
  "refund_amount": 320.00
}

Notes

Returns do not alter original invoices.
All stock changes go through /api/stock/move.php.
Partial and multiple returns per invoice are supported.
Cancelled returns cannot be modified.
This design ensures inventory accuracy and audit compliance.