# Patron API Documentation — DLRL Koha

Base URL: http://14.139.92.12/dlrl_koha_api/
Auth: HTTP Basic — username `test` / password `test@2024`
Header: `Authorization: Basic dGVzdDp0ZXN0QDIwMjQ=`
Content-Type: `application/json`
Clean URLs: no `index.php` required

Method | Endpoint
--- | ---
POST | /api/patron/upsert
GET | /api/patron/view
GET | /api/patron/view?cardnumber=XXX
GET | /api/patron/overdue
GET | /api/patron/overdue?cardnumber=XXX
POST | /api/patron/delete

## 1. Upsert Patron — POST /api/patron/upsert

### Rules

Mode | Rule
--- | ---
Insert | If cardnumber does not exist → send full patron JSON
Update | If exists → cardnumber mandatory; send only keys to change
Multiple | Put one or many objects inside "data": [ ... ]

Insert mandatory: cardnumber, surname, firstname, categorycode, userid, password

Optional borrower fields: title, othernames, initials, streetnumber, address, address2, city, state, zipcode, country, email, phone, dateofbirth, dateenrolled, dateexpiry, sex, branchcode (default DLRL)

Image: imagefile (base64 data URI) + optional mimetype (e.g. image/png)

### Borrower attribute codes

Code | Example
--- | ---
DESIG | SCIENTIS-E
DIV | MV-3
RT | No

Note: JSON must be valid. Do not leave a trailing comma after the last property.

### Full insert example

    {
      "data": [
        {
          "cardnumber": "CQR40",
          "surname": "VVVV",
          "firstname": "K",
          "title": "CQR40",
          "othernames": "VK",
          "initials": "K",
          "streetnumber": "123",
          "address": "Coimbatore",
          "address2": "",
          "city": "Mettupalayam",
          "state": "TamilNadu",
          "zipcode": "641301",
          "country": "India",
          "email": "vk123@gmail.com",
          "phone": "1234567890",
          "dateofbirth": "2000-01-01",
          "categorycode": "2CQR",
          "dateenrolled": "2024-09-19",
          "dateexpiry": "2040-09-19",
          "sex": "M",
          "userid": "CQR40",
          "password": "CQR40",
          "imagefile": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/...",
          "mimetype": "image/png",
          "DESIG": "SCIENTIS-E",
          "DIV": "MV-3",
          "RT": "No"
        }
      ]
    }

### Partial update example

    {
      "data": [
        {
          "cardnumber": "CQR40",
          "email": "new.email@gmail.com",
          "phone": "9876543210",
          "DESIG": "SCIENTIST"
        }
      ]
    }

### Success response

    {
      "status": true,
      "message": "All patrons processed successfully.",
      "success_count": 1,
      "failed_count": 0,
      "results": [
        {
          "success": true,
          "index": 0,
          "cardnumber": "CQR40",
          "borrowernumber": 101,
          "action": "insert",
          "message": "Patron inserted successfully."
        }
      ]
    }

`action` is `insert` or `update`. Each patron is saved in a DB transaction (borrowers + patronimage + borrower_attributes).

## 2. View Patron — GET /api/patron/view

- All patrons: `/api/patron/view`
- One patron: `/api/patron/view?cardnumber=CQR40`

Returns borrower fields (password excluded), imagefile (base64), mimetype, flat attributes DESIG / DIV / RT, and codes_attributes list.

## 3. Overdue — GET /api/patron/overdue

- All: `/api/patron/overdue`
- One: `/api/patron/overdue?cardnumber=CQR40`

Designation = borrower_attributes where code = `DESIG`.

Columns: S_No, ID_No, Name, Designation, Acc_No, Title, Author, Issue_Date, Due_Date, Overdue_Days

## 4. Delete Patron — POST /api/patron/delete

cardnumber is mandatory. Deletes in order: patronimage → borrower_attributes → borrowers.

    {
      "data": [
        { "cardnumber": "CQR40" }
      ]
    }

## Common error messages

Message | Cause
--- | ---
Authorization header is required... | Missing Basic Auth
Invalid username or password. | Bad credentials
Invalid JSON body: ... | Malformed JSON (check trailing commas)
cardnumber is mandatory... | Missing cardnumber
Insert failed. Missing mandatory field(s): ... | Incomplete insert
imagefile is not valid base64 data. | Bad image payload
Cardnumber "X" not found. Nothing deleted. | Delete target missing
Database connection failed... | Wrong DB config

## Server checklist

1. PHP 8.2+ (mysqli, mbstring, intl, json)
2. Apache mod_rewrite + AllowOverride All
3. App.php → baseURL and indexPage = ''
4. Database.php → Koha DB credentials
5. writable/ folder writable
6. public/.htaccess → RewriteBase /dlrl_koha_api/