API Penerimaan Documentation

Quick Start

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

1. Get Your API Token

First, authenticate with your credentials to get a JWT token:

POST /auth/login
Content-Type: application/json

{
  "username": "your-username",
  "password": "your-password"
}

{
  "success": true,
  "message": "Login berhasil",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

2. Create Your First Penerimaan Record

Use the token from step 1 to create a new penerimaan record:

POST /penerimaan
Authorization: Bearer {your-token}
Content-Type: application/json

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

3. Retrieve Your Data

Fetch a list of penerimaan records with pagination:

GET /penerimaan?page=1&limit=10&search=SPP
Authorization: Bearer {your-token}

Authentication

The API Penerimaan uses JWT (JSON Web Tokens) for authentication. All endpoints (except login and auth check) require a valid JWT token in the Authorization header.

How to Authenticate

1. Send your credentials to the login endpoint
2. Receive a JWT token in the response
3. Include the token in all subsequent requests using the Bearer scheme

Token Format

Include your token in the Authorization header of every request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Expiration

Tokens have a limited lifetime. If your token expires, you'll receive a 401 Unauthorized response. Simply login again to get a new token.

Security Best Practices

• Never expose your API token in client-side code or version control
• Always transmit tokens over HTTPS
• Rotate your credentials periodically
• Use environment variables to store sensitive information
• Implement proper error handling for 401 responses

Authentication Endpoints

curl -X POST ${BASE_URL}/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

{
  "success": true,
  "message": "Login berhasil",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInVzZXJuYW1lIjoiYWRtaW4iLCJpYXQiOjE2MjMzODAwMDAwMDB9.signature"
  }
}

{
  "success": false,
  "message": "Username atau password salah",
  "error": "INVALID_CREDENTIALS"
}

Create Penerimaan

curl -X POST ${BASE_URL}/penerimaan \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trxCode": "SPP-001",
    "date": "2026-05-12",
    "description": "Pendapatan SPP Bulan Juni 2026",
    "amount": 5000000,
    "type": "100"
  }'

{
  "success": true,
  "data": {
    "id": 1,
    "trxCode": "SPP-001",
    "date": "2026-05-12",
    "description": "Pendapatan SPP Bulan Juni 2026",
    "amount": 5000000,
    "type": "100"
  }
}

{
  "success": false,
  "message": "Kode transaksi sudah digunakan",
  "error": "DUPLICATE_TRX_CODE"
}

List Penerimaan

curl -X GET "${BASE_URL}/penerimaan?page=1&limit=10&search=SPP" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": [
    {
      "id": 1,
      "trxCode": "SPP-001",
      "date": "2026-05-12",
      "description": "Pendapatan SPP Bulan Juni 2026",
      "amount": 5000000,
      "type": "100",
      "created_at": "2026-05-12T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 50,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Get Penerimaan Detail

curl -X GET ${BASE_URL}/penerimaan/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": {
    "id": 1,
    "trxCode": "SPP-001",
    "date": "2026-05-12",
    "description": "Pendapatan SPP Bulan Juni 2026",
    "amount": 5000000,
    "type": "100",
    "created_at": "2026-05-12T10:30:00Z",
    "updated_at": "2026-05-12T10:30:00Z"
  }
}

Update Penerimaan

curl -X PUT ${BASE_URL}/penerimaan/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trxCode": "SPP-001",
    "date": "2026-05-15",
    "description": "Pendapatan SPP Bulan Juni 2026 (Updated)",
    "amount": 6000000,
    "type": "100"
  }'

{
  "success": true,
  "data": {
    "id": 1,
    "trxCode": "SPP-001",
    "date": "2026-05-15",
    "description": "Pendapatan SPP Bulan Juni 2026 (Updated)",
    "amount": 6000000,
    "type": "100",
    "message": "Data penerimaan berhasil diperbarui"
  }
}

Delete Penerimaan

curl -X DELETE ${BASE_URL}/penerimaan/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "message": "Data penerimaan berhasil dihapus"
}

Error Handling

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

Error Response Structure

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

Common Error Codes

• VALIDATION_ERROR: Invalid or missing required fields
• INVALID_CREDENTIALS: Wrong username or password
• ACCOUNT_INACTIVE: User account is not active
• DUPLICATE_TRX_CODE: Transaction code already exists
• NOT_FOUND: Resource not found
• DATA_ALREADY_JOURNALIZED: Record is journalized and cannot be modified
• BCRYPT_ERROR: Password verification system error

Example Error Responses

{
  "success": false,
  "message": "Field wajib diisi",
  "error": "VALIDATION_ERROR",
  "fields": ["trxCode", "date", "amount"]
}

{
  "success": false,
  "message": "Token tidak valid atau sudah kadaluarsa",
  "error": "INVALID_TOKEN"
}

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": {
    "page": 1,
    "limit": 10,
    "total": 125,
    "totalPages": 13,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Example: Paginating Through Results

async function fetchAllPages() {
  let page = 1;
  let allData = [];
  
  while (true) {
    const response = await fetch(
      ${BASE_URL}/penerimaan?page=&limit=50,
      {
        headers: {
          'Authorization': 'Bearer YOUR_TOKEN'
        }
      }
    );
    
    const result = await response.json();
    allData = allData.concat(result.data);
    
    if (!result.pagination.hasNextPage) break;
    page++;
  }
  
  return allData;
}

Filtering & Search

The list endpoint supports multiple filtering and search options.

Search

Use the search parameter to search across multiple fields:

GET /penerimaan?search=SPP
Authorization: Bearer YOUR_TOKEN

Date Range Filtering

Filter records by date range using date_from and date_to:

GET /penerimaan?date_from=2026-01-01&date_to=2026-12-31
Authorization: Bearer YOUR_TOKEN

Type Filtering

Filter by specific type:

GET /penerimaan?type=100
Authorization: Bearer YOUR_TOKEN

Sorting

Sort results by any field in ascending or descending order:

GET /penerimaan?sort_field=date&sort_order=DESC
Authorization: Bearer YOUR_TOKEN

Combined Filters

Combine multiple filters for precise results:

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

Best Practices

1. Token Management

• Store tokens securely (use environment variables or secure storage)
• Never expose tokens in client-side code or logs
• Implement automatic token refresh on 401 responses
• Use HTTPS for all API requests

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
• Batch operations when possible

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
• Use webhooks or polling intervals appropriately

Example: Robust API Client

class PenerimaanAPI {
  constructor(baseURL, token) {
    this.baseURL = baseURL;
    this.token = token;
  }

  async request(endpoint, options = {}) {
    try {
      const response = await fetch(${this.baseURL}, {
        ...options,
        headers: {
          'Authorization': Bearer ,
          'Content-Type': 'application/json',
          ...options.headers
        }
      });

      const data = await response.json();

      if (!data.success) {
        throw new Error(data.message || 'Request failed');
      }

      return data;
    } catch (error) {
      console.error('API Error:', error);
      throw error;
    }
  }

  async create(penerimaanData) {
    return this.request('/penerimaan', {
      method: 'POST',
      body: JSON.stringify(penerimaanData)
    });
  }

  async list(params = {}) {
    const query = new URLSearchParams(params).toString();
    return this.request(/penerimaan?);
  }

  async get(id) {
    return this.request(/penerimaan/);
  }

  async update(id, data) {
    return this.request(/penerimaan/, {
      method: 'PUT',
      body: JSON.stringify(data)
    });
  }

  async delete(id) {
    return this.request(/penerimaan/, {
      method: 'DELETE'
    });
  }
}

// Usage
const api = new PenerimaanAPI('${BASE_URL}', 'YOUR_TOKEN');
const result = await api.list({ page: 1, limit: 10 });