# Chicken Counting API Documentation

**Version:** 2.0
**Last Updated:** March 5, 2026
**Base URL:** `http://103.215.13.55:5001/api`

---

## Overview

The Chicken Counting API allows external systems to submit chicken population counts per kandang (coop) per date. The API uses a simple upsert mechanism — calling the endpoint multiple times with the same date and kandang will replace the previous record with the latest data.

---

## Authentication

All requests require an API key via the `X-API-Key` header.

```http
X-API-Key: cpa_e8cfeeabaa6997a1ecd4239cee6a9cc59cf43f96cfd58463
```

| Header      | Value                                                  |
| ----------- | ------------------------------------------------------ |
| `X-API-Key` | `cpa_e8cfeeabaa6997a1ecd4239cee6a9cc59cf43f96cfd58463` |

---

## API Endpoint

### Submit / Update Chicken Count

**Endpoint:** `POST /api/chicken-counting`

**Headers:**

```http
Content-Type: application/json
X-API-Key: cpa_e8cfeeabaa6997a1ecd4239cee6a9cc59cf43f96cfd58463
```

**Request Body:**

```json
{
  "date": "2026-03-01",
  "kandang": "kandang-atas",
  "filename": "farm_sukawarna_5b_ch1_main_20260301145938_20260301151559.mp4",
  "total_count": 5612
}
```

**Required Fields:**

| Field         | Type    | Description                                                                                                                                                           |
| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `date`        | string  | Date in `YYYY-MM-DD` format                                                                                                                                           |
| `kandang`     | string  | Slug of the kandang name (e.g. `kandang-atas`, `kandang-bawah`). Matched against the kandangs table by normalizing the name: lowercase + spaces replaced with dashes. |
| `total_count` | integer | Chicken count (must be >= 0)                                                                                                                                          |

**Optional Fields:**

| Field      | Type   | Description                 |
| ---------- | ------ | --------------------------- |
| `filename` | string | Source video/image filename |

**Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "id": 1,
    "date": "2026-03-01",
    "kandangId": 1,
    "kandangName": "Kandang Atas",
    "filename": "farm_sukawarna_5b_ch1_main_20260301145938_20260301151559.mp4",
    "totalCount": 5612,
    "createdAt": "2026-03-01T14:59:38.000Z",
    "updatedAt": "2026-03-01T14:59:38.000Z"
  }
}
```

**Upsert Behavior:**

If a record with the same `date` + `kandang` already exists, the `total_count` and `filename` will be updated. The `createdAt` remains unchanged while `updatedAt` reflects the latest call.

---

## Error Handling

All error responses follow this format:

```json
{
  "success": false,
  "error": "Human-readable error message"
}
```

**Error Responses:**

| Status | Error                   | Description                                                       |
| ------ | ----------------------- | ----------------------------------------------------------------- |
| 401    | API key required        | `X-API-Key` header not provided                                   |
| 401    | Invalid API key         | API key not found or incorrect                                    |
| 400    | Missing required fields | `date`, `kandang`, or `total_count` not provided                  |
| 400    | Kandang not found       | The `kandang` slug doesn't match any kandang name in the database |
| 400    | Invalid date format     | Must be `YYYY-MM-DD`                                              |
| 400    | Invalid total_count     | Must be a non-negative number                                     |
| 500    | Internal server error   | Server error                                                      |

---

## Code Examples

### cURL

```bash
curl -X POST http://103.215.13.55:5001/api/chicken-counting \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cpa_e8cfeeabaa6997a1ecd4239cee6a9cc59cf43f96cfd58463" \
  -d '{
    "date": "2026-03-01",
    "kandang": "kandang-atas",
    "filename": "farm_sukawarna_5b_ch1_main_20260301145938_20260301151559.mp4",
    "total_count": 5612
  }'
```

### Python

```python
import requests

BASE_URL = "http://103.215.13.55:5001/api"

API_KEY = "cpa_e8cfeeabaa6997a1ecd4239cee6a9cc59cf43f96cfd58463"

response = requests.post(
    f"{BASE_URL}/chicken-counting",
    headers={"X-API-Key": API_KEY},
    json={
        "date": "2026-03-01",
        "kandang": "kandang-atas",
        "filename": "farm_sukawarna_5b_ch1_main_20260301145938_20260301151559.mp4",
        "total_count": 5612
    }
)

print(response.json())
```

### JavaScript

```javascript
const API_KEY = 'cpa_e8cfeeabaa6997a1ecd4239cee6a9cc59cf43f96cfd58463';

const response = await fetch('http://103.215.13.55:5001/api/chicken-counting', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY,
  },
  body: JSON.stringify({
    date: '2026-03-01',
    kandang: 'kandang-atas',
    filename: 'farm_sukawarna_5b_ch1_main_20260301145938_20260301151559.mp4',
    total_count: 5612,
  }),
});

const result = await response.json();
// Use `result` here.
```