# Connector API examples

These examples use the authenticated Connector API. Replace the placeholders before sending the requests in Postman.

## Postman variables

```text
base_url       = https://erp.example.com
access_token   = YOUR_AUTH_TOKEN
job_sheet_id   = 456
item_id        = 789
```

For every request below, add:

```text
Authorization: Bearer {{access_token}}
Accept: application/json
```

The job sheet must belong to the authenticated token user's business.

## Purchase-request maintenance note

```http
POST {{base_url}}/connector/api/maintenance-notes/create
Content-Type: application/json
```

```json
{
  "job_sheet_id": 456,
  "content": "Please purchase the approved parts",
  "category_status": "purchase_req"
}
```

This endpoint creates only the purchase-request maintenance note. It does not create or accept informational-product rows.

## Informational products

### List all rows for a job sheet

```http
GET {{base_url}}/connector/api/jobsheets/{{job_sheet_id}}/informational-products
```

The response includes every informational-product row attached directly to that job sheet. `line_total` is calculated from `unit_price * quantity`; it is not stored.

### Create informational products list

```http
POST {{base_url}}/connector/api/jobsheets/{{job_sheet_id}}/informational-products
Content-Type: application/json
```

```json
{
  "informational_products": [
    {
      "product_name": "Front brake pad",
      "product_status": "black",
      "unit_price": 125.5,
      "quantity": 2,
      "note": "Customer requested genuine parts",
      "client_approval": true,
      "approved_at": "2026-08-30 12:30:00",
      "approved_by": "Customer 1001",
      "approval_source": "portal"
    },
    {
      "product_name": "Oil filter",
      "product_status": "orange",
      "unit_price": 25,
      "quantity": 1,
      "note": null,
      "client_approval": true
    }
  ]
}
```

Each row is linked only to the job sheet and has no maintenance-note or purchase-request relationship. This is a **replace** operation: all current informational rows for the job sheet are deleted and the supplied rows are created atomically, including rows where `client_approval` is `false`. The Purchase Requests modal displays only rows whose `client_approval` is `true`.

When there is no `purchase_req` maintenance note for the job sheet, this endpoint creates one automatically so that the ERP Purchase Requests modal can display the list. The response includes `maintenance_note_id` and `maintenance_note_created` to identify that note and whether it was created by this request.

### Update one row

```http
PUT {{base_url}}/connector/api/jobsheets/{{job_sheet_id}}/informational-products/{{item_id}}
Content-Type: application/json
```

Product name, unit price, quantity, and client approval are required. `product_status` accepts `black`, `red`, or `orange` and defaults to `black` when omitted:

```json
{
  "product_name": "Front brake pad - genuine",
  "product_status": "orange",
  "unit_price": 130,
  "quantity": 2,
  "note": "Approved replacement",
  "client_approval": true,
  "approved_at": "2026-08-30 13:00:00",
  "approved_by": "Workshop manager",
  "approval_source": "workshop"
}
```

### Delete one row

```http
DELETE {{base_url}}/connector/api/jobsheets/{{job_sheet_id}}/informational-products/{{item_id}}
```

Example response:

```json
{
  "success": true,
  "message": "Informational product deleted successfully"
}
```

## Customer signature

### Upload signature as base64 JSON only

```http
POST {{base_url}}/connector/api/jobsheets/{{job_sheet_id}}/customer-signature
Content-Type: application/json
```

```json
{
  "signature_base64": "data:image/png;base64,iVBORw0KGgoAAA..."
}
```

The upload accepts JPEG, PNG, or WebP images up to 5 MB. Multipart/file uploads are rejected. A signature upload replaces the previous managed signature for that job sheet.

### Read signature from the job-sheet show API

```http
GET {{base_url}}/connector/api/jobsheets/{{job_sheet_id}}
```

The show response includes `customer_signature_base64` as a data URI, for example `data:image/png;base64,...`. It is `null` when the job sheet has no signature. Storage paths and URLs are not exposed.

## Validation errors

Validation failures return HTTP `422` with an `errors` object. An inaccessible, non-purchase-request, missing-job-sheet, or mismatched note returns HTTP `404`.
