API Penerimaan Documentation

Complete API documentation for managing revenue and income data

📌 Version: 1.0.1
🔒 Authentication: Bearer Token (API Key)
🌐 Base URL: http://localhost:2002
⚙️ Environment: development

Welcome to API Penerimaan

The API Penerimaan is a robust REST API designed to manage revenue and income data. It provides comprehensive endpoints for creating, reading, updating, and deleting penerimaan (revenue/income) records with built-in authentication, pagination, and advanced filtering capabilities.

Key Features

  • Bearer Token Authentication: Secure API access with Bearer token (API Key) in the Authorization header
  • RESTful Design: Standard HTTP methods for all operations
  • Pagination Support: Efficient data retrieval with customizable page sizes
  • Advanced Filtering: Search and filter by multiple criteria
  • Soft Deletes: Safe data deletion without permanent loss
  • Rate Limiting: Built-in rate limiting (100 requests per 15 minutes)
  • Error Handling: Comprehensive error responses with meaningful messages

API Response Format

All API responses follow a consistent JSON structure for easy integration.

Success Response Example 
{
  "success": true,
  "message": "Operation successful",
  "data": {
    "id": 1,
    "trxCode": "SPP-001",
    "date": "2026-05-12",
    "description": "Pendapatan SPP",
    "amount": 5000000,
    "type": "100",
    "unit": "SMA",
    "academic_year": "2026/2027"
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Supported Response Codes

  • 200 OK: Request succeeded
  • 201 Created: Resource successfully created
  • 400 Bad Request: Invalid request parameters or validation error
  • 401 Unauthorized: Missing or invalid authentication token
  • 403 Forbidden: Invalid API Key / permission error
  • 404 Not Found: Resource not found
  • 409 Conflict: Duplicate data or state conflict
  • 500 Internal Server Error: Server error

Quick Start

Get up and running with the API Penerimaan in just a few minutes.

1. Get Your API Key

Contact your system administrator to obtain an API key for authentication.

2. Create Your First Penerimaan Record

Use your API key in the Authorization header to create a new penerimaan record:

Create Request 
POST /penerimaan
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "trxCode": "SPP-001",
  "date": "2026-05-12",
  "description": "Pendapatan SPP Bulan Juni 2026",
  "amount": 5000000,
  "type": "100",
  "unit": "SMA",
  "academic_year": "2026/2027"
}

3. Retrieve Your Data

Fetch a list of penerimaan records with pagination:

List Request 
GET /penerimaan?page=1&limit=10&search=SPP
Authorization: Bearer YOUR_API_KEY

Authentication

The API Penerimaan uses Bearer Token authentication. All endpoints require a valid API key in the Authorization header. The API key is validated against active users in the api_penerimaan_user table (password_hash field, is_active = 1).

How to Authenticate

  1. Obtain your API key from the system administrator (stored as password_hash for your user)
  2. Include the API key in all requests using the Bearer scheme in the Authorization header
  3. Only active users (is_active = 1) are accepted

API Key Format

Include your API key in the Authorization header of every request:

Authorization Header 
Authorization: Bearer YOUR_API_KEY

Example Request

cURL Example 
curl -X GET "http://localhost:2002/penerimaan" \
  -H "Authorization: Bearer YOUR_API_KEY"

Security Best Practices

  • Never expose your API key in client-side code or version control
  • Always transmit API keys over HTTPS in production
  • Store API keys securely using environment variables or secret management services
  • Rotate your API keys periodically
  • Implement proper error handling for 401/403 responses

Create Penerimaan

POST /penerimaan

Create a new penerimaan (revenue/income) record. All fields are required.

Request Body
Parameter Type Required Description
trxCode string Yes Unique transaction code (must be unique)
date string (date) Yes Date in YYYY-MM-DD format
description string Yes Description of the revenue/income
amount number Yes Amount (must be positive number)
type string Yes Type code (e.g. 100, 200, 300, 400, 500, 600)
unit string Yes Unit name (e.g. SMA, SD, SMP)
academic_year string Yes Academic year (e.g. 2026/2027)
cURL 
curl -X POST http://localhost:2002/penerimaan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trxCode": "SPP-001",
    "date": "2026-05-12",
    "description": "Pendapatan SPP Bulan Juni 2026",
    "amount": 5000000,
    "type": "100",
    "unit": "SMA",
    "academic_year": "2026/2027"
  }'
201 Created 
{
  "success": true,
  "data": {
    "id": 1,
    "trxCode": "SPP-001",
    "date": "2026-05-12",
    "description": "Pendapatan SPP Bulan Juni 2026",
    "amount": 5000000,
    "type": "100",
    "unit": "SMA",
    "academic_year": "2026/2027"
  }
}
409 Conflict 
{
  "success": false,
  "message": "Kode transaksi sudah digunakan",
  "error": "DUPLICATE_TRX_CODE"
}

List Penerimaan

GET /penerimaan

Retrieve a paginated list of penerimaan records with optional search and filtering.

Query Parameters
Parameter Type Default Description
page integer 1 Page number for pagination
limit integer 10 Items per page
search string - Search in description or trx_code
sort_field string id Field to sort by (id, date, amount, created_at)
sort_order string DESC Sort order (ASC or DESC)
date_from string (date) - Filter from date (YYYY-MM-DD)
date_to string (date) - Filter to date (YYYY-MM-DD)
type string - Filter by type
unit string - Filter by unit
academic_year string - Filter by academic year (e.g. 2026/2027)
cURL 
curl -X GET "http://localhost:2002/penerimaan?page=1&limit=10&search=SPP" \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "trxCode": "SPP-001",
      "date": "2026-05-12",
      "description": "Pendapatan SPP Bulan Juni 2026",
      "amount": 5000000,
      "type": "100",
      "unit": "SMA",
      "academic_year": "2026/2027",
      "created_at": "2026-05-12T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 50,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Get Penerimaan Detail

GET /penerimaan/:id

Retrieve a single penerimaan record by ID.

Path Parameters
Parameter Type Description
id integer Penerimaan ID
cURL 
curl -X GET http://localhost:2002/penerimaan/1 \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK 
{
  "success": true,
  "data": {
    "id": 1,
    "trxCode": "SPP-001",
    "date": "2026-05-12",
    "description": "Pendapatan SPP Bulan Juni 2026",
    "amount": 5000000,
    "type": "100",
    "unit": "SMA",
    "academic_year": "2026/2027",
    "created_at": "2026-05-12T10:30:00Z",
    "updated_at": "2026-05-12T10:30:00Z"
  }
}

Update Penerimaan

PUT /penerimaan/:id

Update an existing penerimaan record. All fields are required.

Path Parameters
Parameter Type Description
id integer Penerimaan ID
Request Body
Parameter Type Required Description
trxCode string Yes Transaction code
date string (date) Yes Date in YYYY-MM-DD format
description string Yes Description
amount number Yes Amount (positive number)
type string Yes Type code
unit string Yes Unit name
academic_year string Yes Academic year (e.g. 2026/2027)
cURL 
curl -X PUT http://localhost:2002/penerimaan/1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trxCode": "SPP-001",
    "date": "2026-05-15",
    "description": "Pendapatan SPP Bulan Juni 2026 (Updated)",
    "amount": 6000000,
    "type": "100",
    "unit": "SMA",
    "academic_year": "2026/2027"
  }'
200 OK 
{
  "success": true,
  "data": {
    "id": 1,
    "trxCode": "SPP-001",
    "date": "2026-05-15",
    "description": "Pendapatan SPP Bulan Juni 2026 (Updated)",
    "amount": 6000000,
    "type": "100",
    "unit": "SMA",
    "academic_year": "2026/2027",
    "message": "Data penerimaan berhasil diperbarui"
  }
}

Delete Penerimaan

DELETE /penerimaan/:id

Delete (soft delete) a penerimaan record. The record will be marked as deleted but not permanently removed.

Path Parameters
Parameter Type Description
id integer Penerimaan ID
cURL 
curl -X DELETE http://localhost:2002/penerimaan/1 \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK 
{
  "success": true,
  "message": "Data penerimaan berhasil dihapus"
}

Error Handling

The API returns consistent error responses with meaningful messages and error codes.

Error Response Structure

Error Response Format 
{
  "success": false,
  "message": "Human-readable error message",
  "error": "ERROR_CODE",
  "fields": ["field1", "field2"]
}

Common Error Codes

  • VALIDATION_ERROR: Invalid or missing required fields
  • MISSING_API_KEY: No API key provided in request
  • INVALID_API_KEY: The provided API key is not valid
  • API_KEY_NOT_CONFIGURED: Server configuration error
  • DUPLICATE_TRX_CODE: Transaction code already exists
  • NOT_FOUND: Resource not found
  • DATA_ALREADY_JOURNALIZED: Record is journalized and cannot be modified

Example Error Responses

Validation Error (400) 
{
  "success": false,
  "message": "Field wajib diisi",
  "error": "VALIDATION_ERROR",
  "fields": ["trxCode", "date", "amount"]
}
Unauthorized (401) 
{
  "success": false,
  "message": "Access denied. No API key provided.",
  "error": "MISSING_API_KEY"
}
Forbidden (403) 
{
  "success": false,
  "message": "Invalid API key.",
  "error": "INVALID_API_KEY"
}

Pagination

List endpoints support pagination to efficiently handle large datasets.

Pagination Parameters

  • page: Page number (starts from 1)
  • limit: Items per page (default: 10)

Pagination Response

All paginated endpoints return pagination metadata:

Pagination Object 
{
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 125,
    "totalPages": 13,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Filtering & Search

The list endpoint supports multiple filtering and search options.

Search

Use the search parameter to search across multiple fields:

Search Example 
GET /penerimaan?search=SPP
Authorization: Bearer YOUR_API_KEY

Date Range Filtering

Filter records by date range using date_from and date_to:

Date Range Example 
GET /penerimaan?date_from=2026-01-01&date_to=2026-12-31
Authorization: Bearer YOUR_API_KEY

Type Filtering

Filter by specific type:

Type Filter Example 
GET /penerimaan?type=100
Authorization: Bearer YOUR_API_KEY

Sorting

Sort results by any field in ascending or descending order:

Sorting Example 
GET /penerimaan?sort_field=date&sort_order=DESC
Authorization: Bearer YOUR_API_KEY

Combined Filters

Combine multiple filters for precise results:

Combined Example 
GET /penerimaan?search=SPP&type=100&date_from=2026-01-01&sort_field=amount&sort_order=DESC&page=1&limit=20
Authorization: Bearer YOUR_API_KEY

Best Practices

1. API Key Management

  • Store API keys securely (use environment variables or secret management services)
  • Never expose API keys in client-side code, logs, or version control
  • Rotate API keys periodically
  • Use HTTPS for all API requests
  • Monitor API key usage for unauthorized access

2. Error Handling

  • Always check the success field in responses
  • Implement retry logic for network failures
  • Handle rate limiting (429) with exponential backoff
  • Log errors with context for debugging

3. Performance Optimization

  • Use pagination to limit response size
  • Implement caching for frequently accessed data
  • Use specific filters to reduce result sets

4. Data Validation

  • Validate data on the client before sending requests
  • Use proper date formats (YYYY-MM-DD)
  • Ensure amounts are positive numbers
  • Check for unique transaction codes before creation

5. Rate Limiting

  • Respect the 100 requests per 15 minutes limit
  • Implement request queuing for high-volume operations
  • Monitor rate limit headers in responses