# App Update Guide — RA Bill Number (27 Aug 2026)

**Audience:** Mobile app developers (Flutter / API clients)  
**Backend push:** `e3c5e3d` — *Changes in payment letter section related to RA_BILL_NUMBER and FINAL PRINT option*  
**API base:** `/api/v1`

This note covers **only what changed in the latest push**. For the earlier account-wise approval work, see [`APP_INTEGRATION_ACCOUNT_FLOW.md`](APP_INTEGRATION_ACCOUNT_FLOW.md). Full endpoint reference: [`MOBILE_API.md`](MOBILE_API.md).

---

## 1. What changed in this push

| Item | Mobile impact | Admin-only |
|------|---------------|------------|
| New field `ra_bill_number` on payment requests | **Yes — display & model** | Also shown in admin lists/print |
| Auto-assign on first successful submit | **Yes — read after submit** | — |
| Unique per project + vendor | Informational | — |
| Payment letter printout | **No API change** | Accounting → Print |

**No new endpoints. No request-body changes for create / update / approve.**  
Clients only need to **read and display** `ra_bill_number` where payment-request objects are returned.

---

## 2. What is RA Bill Number?

- **Type:** Plain integer (`1`, `2`, `3`, …) — not a formatted string.
- **Scope:** Unique within a **(project_id, vendor_id)** pair.
- **Assigned by:** Server only, on the **first successful submit**.
- **Immutable:** Once set, it never changes (including amendment re-submit).
- **Drafts:** Always `null` until first submit.

```text
Create draft          → ra_bill_number = null
First submit          → server sets next integer for that project + vendor
Amendment → re-submit → same number kept
Reject / cancel       → number stays on the letter (sequence may have gaps)
```

**Do not send `ra_bill_number` from the app.** The server ignores client values for this field; assignment happens inside submit.

---

## 3. When is it assigned?

Assigned inside:

- `POST /payment-requests/{id}/submit`
- or create with `"action": "submit"` (create + submit in one call)

Logic:

1. If the request already has `ra_bill_number` → leave it.
2. Else → `max(ra_bill_number)` for same `project_id` + `vendor_id` + 1 (starts at `1`).

Example: Project A + Vendor X already has RA `1` and `2` → next letter for that pair gets `3`.

---

## 4. Where the field appears in API responses

Add `ra_bill_number` to your DTOs / list tiles / detail screens.

| Endpoint | Presence |
|----------|----------|
| `GET /payment-requests` (list) | Yes — each row |
| `GET /payment-requests/{id}` (detail bundle) | Yes — header |
| `POST /payment-requests` (create response) | Yes — `null` if draft; set if `action=submit` |
| `POST /payment-requests/{id}/submit` | Yes — set after success (first submit) |
| `GET /approvals/inbox` | Yes |
| `GET /approvals/history` | Yes |
| `GET /dashboard` recent / pending lists | Yes |

### Example — list / inbox row (excerpt)

```json
{
  "id": 12,
  "request_no": "PR-20260827-00012-4",
  "project_id": 2,
  "account_id": 1,
  "account_name": "Civil Works",
  "vendor_id": 2,
  "vendor_name": "Acme Construction Pvt Ltd",
  "invoice_no": "INV-100",
  "invoice_amount": 50000.00,
  "ra_bill_number": 3,
  "status": "UNDER_APPROVAL",
  "current_level": 1,
  "max_level": 3
}
```

### Example — draft vs submitted

```json
// DRAFT
{ "request_no": "PR-...", "status": "DRAFT", "ra_bill_number": null }

// After first submit
{ "request_no": "PR-...", "status": "UNDER_APPROVAL", "ra_bill_number": 1 }
```

---

## 5. Flutter / client integration checklist

1. [ ] Add `int? raBillNumber` (or equivalent) to payment-request models.
2. [ ] Parse `ra_bill_number` from list, detail, inbox, history, and dashboard payloads.
3. [ ] **List / card UI:** show RA Bill when not null (e.g. `RA #3` next to invoice / request no).
4. [ ] **Detail UI:** show `—` or hide when `null` (draft); show integer after submit.
5. [ ] After `submit` (or create with `action=submit`), refresh detail and read the new value — do not invent it client-side.
6. [ ] On amendment re-submit, keep showing the same number (server does not change it).
7. [ ] Do **not** add `ra_bill_number` to create/update request bodies.
8. [ ] No changes required for approve / reject / return / attachments APIs for this release.

Suggested display labels:

| State | UI |
|-------|-----|
| `null` | Hide, or show `RA Bill: —` |
| `3` | `RA Bill No: 3` |

---

## 6. Sample flow (curl)

```bash
BASE=https://<host>
TOKEN=<incharge_jwt>

# Create draft — ra_bill_number will be null
curl -sS -X POST "$BASE/api/v1/payment-requests" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 2,
    "account_id": 1,
    "vendor_id": 2,
    "invoice_no": "INV-RA-TEST",
    "invoice_date": "2026-08-20",
    "invoice_amount": 10000,
    "action": "draft"
  }'

# Submit — response / subsequent GET includes ra_bill_number
curl -sS -X POST "$BASE/api/v1/payment-requests/{id}/submit" \
  -H "Authorization: Bearer $TOKEN"

curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/v1/payment-requests/{id}"
# → data.ra_bill_number is an integer (e.g. 1)
```

---

## 7. Admin print (FYI — not a mobile task)

Accounts team can print a payment letter from **Admin → Accounting** for fully approved requests (`APPROVED` / payment statuses).

- Route: `GET /admin/accounting/print/{id}`
- Includes project, account, vendor, invoice, amounts, and **approval levels** (with SKIPPED peers).
- **No mobile API** for print. App only needs to surface `ra_bill_number` so users see the same serial accounts use on the printout.

---

## 8. Breaking vs non-breaking

| Change | Breaking? |
|--------|-----------|
| Extra response field `ra_bill_number` | **Non-breaking** if client ignores unknown fields |
| Required UI display of RA Bill | Product requirement — treat as **must implement** |
| New mobile endpoints | None |
| Changed auth / approval payloads | None |

Clients that strictly decode JSON into fixed structs should add the optional field to avoid decode failures if your stack rejects unknown keys (rare in Dart `json_serializable` with defaults).

---

## 9. Related docs

| Doc | Purpose |
|-----|---------|
| [`APP_INTEGRATION_ACCOUNT_FLOW.md`](APP_INTEGRATION_ACCOUNT_FLOW.md) | Account-wise create/approve (prior major change) |
| [`MOBILE_API.md`](MOBILE_API.md) | Full API reference (includes `ra_bill_number` notes) |
| `docs/migrations/20260827_ra_bill_number.sql` | DB migration for this field |

---

## 10. Quick Q&A

**Q: Can two different vendors on the same project both have RA Bill `1`?**  
A: Yes. Uniqueness is per **project + vendor**.

**Q: Can we edit RA Bill from the app?**  
A: No.

**Q: Does reject free the number for reuse?**  
A: No. The number stays on that letter; the next submit for that project+vendor gets the next integer (gaps are OK).

**Q: Create with `action: "submit"` — is RA assigned immediately?**  
A: Yes, on that first successful submit path.