## How to Use in Postman

### Step 1: Get Authentication Token

__Request:__

- __Method:__ `POST`
- __URL:__ `http://localhost/pagecaptureservice/public/auth/token`
- __Headers:__ `Content-Type: application/json`
- __Body (JSON):__

```json
{
  "api_key": "test_api_key_12345",
  "secret_key": "test_secret_key_67890_very_secure"
}
```

__Response:__

```json
{
  "success": true,
  "data": {
    "success": true,
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "expires_in": 86400,
    "token_type": "Bearer"
  },
  "timestamp": "2025-05-29T06:24:37+00:00"
}
```

### Step 2: Use Token for Protected Endpoints

Copy the `token` value and use it in the Authorization header for all subsequent requests:

__Header:__ `Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...`

### Step 3: Example API Calls

1. __Get all listings:__

   - `GET http://localhost/pagecaptureservice/public/listings`
   - Add Authorization header
   Sample response:
   {
    "success": true,
    "data": [
        {
            "listingId": "LST-ARCHIVE-001-20241101",
            "title": "Wayne County, Michigan - Birth Records (1850-1875)",
            "archive": "Michigan State Archive",
            "issuedDate": "2024-10-15 08:00:00",
            "status": "In Progress",
            "notes": "Listing approved for capture project P2024-MI-005.",
            "id": 4,
            "listedItems": []
        },
        {
            "listingId": "005009407",
            "title": "Dumaguete Birth Recrods, Negros Oriental, Philippines",
            "archive": "Negros Oriental Birth 1990 - 2005",
            "issuedDate": "2025-05-29 16:07:46",
            "status": "In Progress",
            "notes": "Listing approved for capture ID 005009407.",
            "id": 5,
            "listedItems": [
                {
                    "itemIdentifier": "005009407_001_M9C1-DWG_00001.jpg",
                    "listingDescription": "Volume 8 - Births 1990 - 2005",
                    "recordType": "Birth certificate",
                    "startDate": "1990",
                    "endDate": "2005",
                    "volume": "8",
                    "expectedCount": 0,
                    "reconciliationStatus": null,
                    "reconciliationNotes": null,
                    "capturedFolderId": "005009407",
                    "capturedSequenceNumber": 0
                },
                {
                    "itemIdentifier": "005009407_001_M9C1-DWG_00002.jpg",
                    "listingDescription": "Volume 8 - Births 1990 - 2005",
                    "recordType": "Birth certificate",
                    "startDate": "1990",
                    "endDate": "2005",
                    "volume": "8",
                    "expectedCount": 0,
                    "reconciliationStatus": null,
                    "reconciliationNotes": null,
                    "capturedFolderId": "005009407",
                    "capturedSequenceNumber": 0
                },
                {
                    "itemIdentifier": "005009407_001_M9C1-DWG_00003.jpg",
                    "listingDescription": "Volume 8 - Births 1990 - 2005",
                    "recordType": "Birth certificate",
                    "startDate": "1990",
                    "endDate": "2005",
                    "volume": "8",
                    "expectedCount": 0,
                    "reconciliationStatus": null,
                    "reconciliationNotes": null,
                    "capturedFolderId": "005009407",
                    "capturedSequenceNumber": 0
                },
                {
                    "itemIdentifier": "005009407_001_M9C1-DWG_00004.jpg",
                    "listingDescription": "Volume 8 - Births 1990 - 2005",
                    "recordType": "Birth certificate",
                    "startDate": "1990",
                    "endDate": "2005",
                    "volume": "8",
                    "expectedCount": 0,
                    "reconciliationStatus": null,
                    "reconciliationNotes": null,
                    "capturedFolderId": "005009407",
                    "capturedSequenceNumber": 0
                },
                {
                    "itemIdentifier": "005009407_001_M9C1-DWG_00005.jpg",
                    "listingDescription": "Volume 8 - Births 1990 - 2005",
                    "recordType": "Birth certificate",
                    "startDate": "1990",
                    "endDate": "2005",
                    "volume": "8",
                    "expectedCount": 0,
                    "reconciliationStatus": null,
                    "reconciliationNotes": null,
                    "capturedFolderId": "005009407",
                    "capturedSequenceNumber": 0
                },
                {
                    "itemIdentifier": "005009407_001_M9C1-DWG_00006.jpg",
                    "listingDescription": "Volume 8 - Births 1990 - 2005",
                    "recordType": "Birth certificate",
                    "startDate": "1990",
                    "endDate": "2005",
                    "volume": "8",
                    "expectedCount": 0,
                    "reconciliationStatus": null,
                    "reconciliationNotes": null,
                    "capturedFolderId": "005009407",
                    "capturedSequenceNumber": 0
                },
                {
                    "itemIdentifier": "005009407_001_M9C1-DWG_00007.jpg",
                    "listingDescription": "Volume 8 - Births 1990 - 2005",
                    "recordType": "Birth certificate",
                    "startDate": "1990",
                    "endDate": "2005",
                    "volume": "8",
                    "expectedCount": 0,
                    "reconciliationStatus": null,
                    "reconciliationNotes": null,
                    "capturedFolderId": "005009407",
                    "capturedSequenceNumber": 0
                },
                {
                    "itemIdentifier": "005009407_001_M9C1-DWG_00008.jpg",
                    "listingDescription": "Volume 8 - Births 1990 - 2005",
                    "recordType": "Birth certificate",
                    "startDate": "1990",
                    "endDate": "2005",
                    "volume": "8",
                    "expectedCount": 0,
                    "reconciliationStatus": null,
                    "reconciliationNotes": null,
                    "capturedFolderId": "005009407",
                    "capturedSequenceNumber": 0
                },
                {
                    "itemIdentifier": "005009407_001_M9C1-DWG_00009.jpg",
                    "listingDescription": "Volume 8 - Births 1990 - 2005",
                    "recordType": "Birth certificate",
                    "startDate": "1990",
                    "endDate": "2005",
                    "volume": "8",
                    "expectedCount": 0,
                    "reconciliationStatus": null,
                    "reconciliationNotes": null,
                    "capturedFolderId": "005009407",
                    "capturedSequenceNumber": 0
                },
                {
                    "itemIdentifier": "005009407_001_M9C1-DWG_000010.jpg",
                    "listingDescription": "Volume 8 - Births 1990 - 2005",
                    "recordType": "Birth certificate",
                    "startDate": "1990",
                    "endDate": "2005",
                    "volume": "8",
                    "expectedCount": 0,
                    "reconciliationStatus": null,
                    "reconciliationNotes": null,
                    "capturedFolderId": "005009407",
                    "capturedSequenceNumber": 0
                },
                {
                    "itemIdentifier": "005009407_001_M9C1-DWG_000011.jpg",
                    "listingDescription": "Volume 8 - Births 1990 - 2005",
                    "recordType": "Birth certificate",
                    "startDate": "1990",
                    "endDate": "2005",
                    "volume": "8",
                    "expectedCount": 0,
                    "reconciliationStatus": null,
                    "reconciliationNotes": null,
                    "capturedFolderId": "005009407",
                    "capturedSequenceNumber": 0
                }
            ]
        }
    ],
    "pagination": {
        "total": 2,
        "limit": 50,
        "offset": 0,
        "has_more": false
    },
    "timestamp": "2025-05-29T09:34:04+00:00"
}

2. __Get specific listing:__

   - `GET http://localhost/pagecaptureservice/public/listings/LST-ARCHIVE-001-20241101`
   - Add Authorization header
   Sample response
   {
    "success": true,
    "data": {
        "listingId": "005009407",
        "title": "Dumaguete Birth Recrods, Negros Oriental, Philippines",
        "archive": "Negros Oriental Birth 1990 - 2005",
        "issuedDate": "2025-05-29 16:07:46",
        "status": "In Progress",
        "notes": "Listing approved for capture ID 005009407.",
        "listedItems": [
            {
                "itemIdentifier": "005009407_001_M9C1-DWG_00001.jpg",
                "listingDescription": "Volume 8 - Births 1990 - 2005",
                "recordType": "Birth certificate",
                "startDate": "1990",
                "endDate": "2005",
                "volume": "8",
                "expectedCount": 0,
                "reconciliationStatus": null,
                "reconciliationNotes": null,
                "capturedFolderId": "005009407",
                "capturedSequenceNumber": 0
            },
            {
                "itemIdentifier": "005009407_001_M9C1-DWG_00002.jpg",
                "listingDescription": "Volume 8 - Births 1990 - 2005",
                "recordType": "Birth certificate",
                "startDate": "1990",
                "endDate": "2005",
                "volume": "8",
                "expectedCount": 0,
                "reconciliationStatus": null,
                "reconciliationNotes": null,
                "capturedFolderId": "005009407",
                "capturedSequenceNumber": 0
            },
            {
                "itemIdentifier": "005009407_001_M9C1-DWG_00003.jpg",
                "listingDescription": "Volume 8 - Births 1990 - 2005",
                "recordType": "Birth certificate",
                "startDate": "1990",
                "endDate": "2005",
                "volume": "8",
                "expectedCount": 0,
                "reconciliationStatus": null,
                "reconciliationNotes": null,
                "capturedFolderId": "005009407",
                "capturedSequenceNumber": 0
            },
            {
                "itemIdentifier": "005009407_001_M9C1-DWG_00004.jpg",
                "listingDescription": "Volume 8 - Births 1990 - 2005",
                "recordType": "Birth certificate",
                "startDate": "1990",
                "endDate": "2005",
                "volume": "8",
                "expectedCount": 0,
                "reconciliationStatus": null,
                "reconciliationNotes": null,
                "capturedFolderId": "005009407",
                "capturedSequenceNumber": 0
            },
            {
                "itemIdentifier": "005009407_001_M9C1-DWG_00005.jpg",
                "listingDescription": "Volume 8 - Births 1990 - 2005",
                "recordType": "Birth certificate",
                "startDate": "1990",
                "endDate": "2005",
                "volume": "8",
                "expectedCount": 0,
                "reconciliationStatus": null,
                "reconciliationNotes": null,
                "capturedFolderId": "005009407",
                "capturedSequenceNumber": 0
            },
            {
                "itemIdentifier": "005009407_001_M9C1-DWG_00006.jpg",
                "listingDescription": "Volume 8 - Births 1990 - 2005",
                "recordType": "Birth certificate",
                "startDate": "1990",
                "endDate": "2005",
                "volume": "8",
                "expectedCount": 0,
                "reconciliationStatus": null,
                "reconciliationNotes": null,
                "capturedFolderId": "005009407",
                "capturedSequenceNumber": 0
            },
            {
                "itemIdentifier": "005009407_001_M9C1-DWG_00007.jpg",
                "listingDescription": "Volume 8 - Births 1990 - 2005",
                "recordType": "Birth certificate",
                "startDate": "1990",
                "endDate": "2005",
                "volume": "8",
                "expectedCount": 0,
                "reconciliationStatus": null,
                "reconciliationNotes": null,
                "capturedFolderId": "005009407",
                "capturedSequenceNumber": 0
            },
            {
                "itemIdentifier": "005009407_001_M9C1-DWG_00008.jpg",
                "listingDescription": "Volume 8 - Births 1990 - 2005",
                "recordType": "Birth certificate",
                "startDate": "1990",
                "endDate": "2005",
                "volume": "8",
                "expectedCount": 0,
                "reconciliationStatus": null,
                "reconciliationNotes": null,
                "capturedFolderId": "005009407",
                "capturedSequenceNumber": 0
            },
            {
                "itemIdentifier": "005009407_001_M9C1-DWG_00009.jpg",
                "listingDescription": "Volume 8 - Births 1990 - 2005",
                "recordType": "Birth certificate",
                "startDate": "1990",
                "endDate": "2005",
                "volume": "8",
                "expectedCount": 0,
                "reconciliationStatus": null,
                "reconciliationNotes": null,
                "capturedFolderId": "005009407",
                "capturedSequenceNumber": 0
            },
            {
                "itemIdentifier": "005009407_001_M9C1-DWG_000010.jpg",
                "listingDescription": "Volume 8 - Births 1990 - 2005",
                "recordType": "Birth certificate",
                "startDate": "1990",
                "endDate": "2005",
                "volume": "8",
                "expectedCount": 0,
                "reconciliationStatus": null,
                "reconciliationNotes": null,
                "capturedFolderId": "005009407",
                "capturedSequenceNumber": 0
            },
            {
                "itemIdentifier": "005009407_001_M9C1-DWG_000011.jpg",
                "listingDescription": "Volume 8 - Births 1990 - 2005",
                "recordType": "Birth certificate",
                "startDate": "1990",
                "endDate": "2005",
                "volume": "8",
                "expectedCount": 0,
                "reconciliationStatus": null,
                "reconciliationNotes": null,
                "capturedFolderId": "005009407",
                "capturedSequenceNumber": 0
            }
        ]
    },
    "timestamp": "2025-05-29T09:34:35+00:00"
}

3. __With query parameters:__

   - `GET http://localhost/pagecaptureservice/public/listings?limit=10&format=json&status=In Progress`
   - Add Authorization header

4. __Update reconciliation status:__

   - `PATCH http://localhost/pagecaptureservice/public/listings/LST-ARCHIVE-001-20241101/reconciliation`
   - Add Authorization header
   - Body with reconciliation data

5. Get listed items per listing ID
   GET http://localhost/pagecaptureservice/public/listings/{listingId}/items
   - Add Authorization header
   Sample response:
   {
    "success": true,
    "data": [
        {
            "itemIdentifier": "005009407_001_M9C1-DWG_00001.jpg",
            "listingDescription": "Volume 8 - Births 1990 - 2005",
            "recordType": "Birth certificate",
            "startDate": "1990",
            "endDate": "2005",
            "volume": "8",
            "expectedCount": 0,
            "reconciliationStatus": null,
            "reconciliationNotes": null,
            "capturedFolderId": "005009407",
            "capturedSequenceNumber": 0,
            "id": 10,
            "listingFk": 5
        },
        {
            "itemIdentifier": "005009407_001_M9C1-DWG_00002.jpg",
            "listingDescription": "Volume 8 - Births 1990 - 2005",
            "recordType": "Birth certificate",
            "startDate": "1990",
            "endDate": "2005",
            "volume": "8",
            "expectedCount": 0,
            "reconciliationStatus": null,
            "reconciliationNotes": null,
            "capturedFolderId": "005009407",
            "capturedSequenceNumber": 0,
            "id": 11,
            "listingFk": 5
        },
        {
            "itemIdentifier": "005009407_001_M9C1-DWG_00003.jpg",
            "listingDescription": "Volume 8 - Births 1990 - 2005",
            "recordType": "Birth certificate",
            "startDate": "1990",
            "endDate": "2005",
            "volume": "8",
            "expectedCount": 0,
            "reconciliationStatus": null,
            "reconciliationNotes": null,
            "capturedFolderId": "005009407",
            "capturedSequenceNumber": 0,
            "id": 12,
            "listingFk": 5
        },
        {
            "itemIdentifier": "005009407_001_M9C1-DWG_00004.jpg",
            "listingDescription": "Volume 8 - Births 1990 - 2005",
            "recordType": "Birth certificate",
            "startDate": "1990",
            "endDate": "2005",
            "volume": "8",
            "expectedCount": 0,
            "reconciliationStatus": null,
            "reconciliationNotes": null,
            "capturedFolderId": "005009407",
            "capturedSequenceNumber": 0,
            "id": 13,
            "listingFk": 5
        },
        {
            "itemIdentifier": "005009407_001_M9C1-DWG_00005.jpg",
            "listingDescription": "Volume 8 - Births 1990 - 2005",
            "recordType": "Birth certificate",
            "startDate": "1990",
            "endDate": "2005",
            "volume": "8",
            "expectedCount": 0,
            "reconciliationStatus": null,
            "reconciliationNotes": null,
            "capturedFolderId": "005009407",
            "capturedSequenceNumber": 0,
            "id": 14,
            "listingFk": 5
        },
        {
            "itemIdentifier": "005009407_001_M9C1-DWG_00006.jpg",
            "listingDescription": "Volume 8 - Births 1990 - 2005",
            "recordType": "Birth certificate",
            "startDate": "1990",
            "endDate": "2005",
            "volume": "8",
            "expectedCount": 0,
            "reconciliationStatus": null,
            "reconciliationNotes": null,
            "capturedFolderId": "005009407",
            "capturedSequenceNumber": 0,
            "id": 15,
            "listingFk": 5
        },
        {
            "itemIdentifier": "005009407_001_M9C1-DWG_00007.jpg",
            "listingDescription": "Volume 8 - Births 1990 - 2005",
            "recordType": "Birth certificate",
            "startDate": "1990",
            "endDate": "2005",
            "volume": "8",
            "expectedCount": 0,
            "reconciliationStatus": null,
            "reconciliationNotes": null,
            "capturedFolderId": "005009407",
            "capturedSequenceNumber": 0,
            "id": 16,
            "listingFk": 5
        },
        {
            "itemIdentifier": "005009407_001_M9C1-DWG_00008.jpg",
            "listingDescription": "Volume 8 - Births 1990 - 2005",
            "recordType": "Birth certificate",
            "startDate": "1990",
            "endDate": "2005",
            "volume": "8",
            "expectedCount": 0,
            "reconciliationStatus": null,
            "reconciliationNotes": null,
            "capturedFolderId": "005009407",
            "capturedSequenceNumber": 0,
            "id": 17,
            "listingFk": 5
        },
        {
            "itemIdentifier": "005009407_001_M9C1-DWG_00009.jpg",
            "listingDescription": "Volume 8 - Births 1990 - 2005",
            "recordType": "Birth certificate",
            "startDate": "1990",
            "endDate": "2005",
            "volume": "8",
            "expectedCount": 0,
            "reconciliationStatus": null,
            "reconciliationNotes": null,
            "capturedFolderId": "005009407",
            "capturedSequenceNumber": 0,
            "id": 18,
            "listingFk": 5
        },
        {
            "itemIdentifier": "005009407_001_M9C1-DWG_000010.jpg",
            "listingDescription": "Volume 8 - Births 1990 - 2005",
            "recordType": "Birth certificate",
            "startDate": "1990",
            "endDate": "2005",
            "volume": "8",
            "expectedCount": 0,
            "reconciliationStatus": null,
            "reconciliationNotes": null,
            "capturedFolderId": "005009407",
            "capturedSequenceNumber": 0,
            "id": 19,
            "listingFk": 5
        },
        {
            "itemIdentifier": "005009407_001_M9C1-DWG_000011.jpg",
            "listingDescription": "Volume 8 - Births 1990 - 2005",
            "recordType": "Birth certificate",
            "startDate": "1990",
            "endDate": "2005",
            "volume": "8",
            "expectedCount": 0,
            "reconciliationStatus": null,
            "reconciliationNotes": null,
            "capturedFolderId": "005009407",
            "capturedSequenceNumber": 0,
            "id": 20,
            "listingFk": 5
        }
    ],
    "pagination": {
        "total": 11,
        "limit": 50,
        "offset": 0,
        "has_more": false
    },
    "timestamp": "2025-05-29T09:26:03+00:00"
}

## ✅ Verified Working Features

All tests are now passing:

- ✅ Token generation (HTTP 200)
- ✅ Health check without auth (HTTP 200)
- ✅ Protected endpoints with auth (HTTP 200)
- ✅ Authentication rejection without token (HTTP 401)
- ✅ Query parameters and filtering (HTTP 200)
- ✅ Multiple response formats (JSON/XML)

The API is now fully functional with proper authentication flow!