# Custom Document Footer Text — API Guide for the Mobile App

Date: 2026-07-07
Applies to: WBMS mobile app (Flutter) thermal printing
Base URL: `https://billing.happyimart.com/api/v1`
Auth: Sanctum bearer token (same as all v1 endpoints)

## What this is

Company admins can now set custom text (announcements, payment channels,
office hours, disclaimers) that must be printed at the **bottom of each
printed document, just before the standard footer**. There is one text per
document type:

| Field                       | Printed on                          |
|-----------------------------|-------------------------------------|
| `reading_footer_text`       | Meter reading receipt               |
| `billing_footer_text`       | Billing statement / bill receipt    |
| `disconnection_footer_text` | Disconnection notice                |

The admin edits these in the web app under **Company Settings → Document
Text**.

## Where to get it

The fields live in the `settings` object of the company payload, which the
app already receives in three places:

1. `POST /auth/login` — embedded `company` object
2. `GET /company`
3. `GET /dashboard/summary` — embedded `company` object

No new endpoint and no new permissions: every role that can log in receives
these fields.

### Example response (trimmed)

```json
{
  "company": {
    "id": 3,
    "name": "Panganiban Water System",
    "settings": {
      "app_name": "Panganiban Water System",
      "show_logo_on_thermal": false,
      "show_qr_on_receipt": false,
      "reading_footer_text": "This is a reading acknowledgement, not an official bill.",
      "billing_footer_text": "Pay at the office or via GCash 0917-000-0000.\nBring this receipt when paying.",
      "disconnection_footer_text": "If payment has already been made, please disregard this notice."
    }
  }
}
```

## Rendering rules

1. **Placement**: print the text after the document's content (totals, QR
   code, staff info) and immediately **before** the standard footer lines
   (company contact info, "Generated:" timestamp, powered-by line).
2. **Empty means skip**: each field is `null` or an empty string when the
   company has not configured it. Print nothing — no blank block, no divider.
3. **Plain text only**: the value is plain text, max 1000 characters. Do not
   interpret HTML or markdown.
4. **Preserve line breaks**: `\n` in the value is a line break on the
   receipt.
5. **Suggested style** (to match the web thermal receipts): centered, small
   font, separated from the content above by a dashed rule.
6. **Freshness**: re-read the value from the company payload rather than a
   stale local cache; refreshing on login and on pull-to-refresh of the home
   screen is enough (the same rule as the other `settings` flags).

## Which text goes on which print job

- Printing a **reading receipt** after `POST /meter-readings`
  → `reading_footer_text`
- Printing a **bill** from a billing fetched via `GET /billings/{id}`
  (or after a reading is approved) → `billing_footer_text`
- Printing a **disconnection notice** for an overdue account
  → `disconnection_footer_text`

The web app prints the same texts on its A4 PDF bill, thermal bill,
disconnection notice letter, and thermal disconnection notice, so the mobile
output should match.