# Orders API — Missing Backend Contracts (Backend Reply)

Reply to "Orders API — Missing Backend Contracts" (reviewed `04-company.md` +
the Postman collection). Both endpoints already existed
(`GET /api/v1/company/orders/{order_uuid}`, `.../accept-price`); this closes
the two gaps raised against them. No new routes were needed.

## 1. Complete Order Details Payload

`GET /api/v1/company/orders/{order_uuid}` now returns fully populated
`address`, `technician`, and `technician_attachments`, and `items[].service_id`
was already present (mapped from `OrderItem.category_id`) — confirmed below,
no change was needed there.

Real response, captured from a live seeded order:

```json
{
  "data": {
    "id": 63,
    "uuid": "f289882b-248c-4c2f-9f07-32008a9d644c",
    "order_number": "ORD-260907-NUZV",
    "status": "accepted",
    "address": {
      "id": 8,
      "title": "Other",
      "address": "1628 Jacklyn Trail Suite 512",
      "latitude": 24.658083,
      "longitude": 31.022606
    },
    "technician": {
      "id": 2,
      "name": "محمد أحمد",
      "image": null,
      "phone": "966500000005"
    },
    "items": [
      {
        "id": 175,
        "service_name": "Circuit Breaker Repair",
        "service_id": 10,
        "pricing_type": "fixed",
        "unit_price": "90.00",
        "quantity": 1,
        "line_total": "90.00",
        "is_quoted": false
      }
    ],
    "technician_attachments": [
      {
        "id": 1,
        "url": "https://example.com/work-proof.jpg",
        "type": "after",
        "note": "Completed work photo"
      }
    ]
  }
}
```

Notes on field sourcing:

- `address.latitude`/`.longitude` come from `addresses.lat`/`.lng` — the DB
  columns are named `lat`/`lng`, but the API always exposes the
  `latitude`/`longitude` keys shown above.
- `technician.image` is `Technician::personalPhoto()->url()` — `null` when
  the technician has no uploaded photo (shown above, this seeded technician
  has none). Not a bug — a real technician with a profile photo returns a URL
  here.
- `technician.phone` is the technician's linked user account phone
  (`technician.user.phone`) — technicians have no `phone` column of their own.
- `technician_attachments` is every row on `order_attachments` for this
  order (currently **all** attachments are technician-submitted — nothing in
  the codebase writes a company-submitted one, so the field name is accurate
  today). `type` is the real stored value —
  `before|after|report|issue|signature|other` (from the technician's upload
  form), not a MIME-type category like `"image"`/`"video"` — there's no MIME
  column on `order_attachments`, so a media-kind classification isn't
  available. Let us know if the app needs one; it'd require a schema change.
- `items[].service_id` — already present pre-existing (`OrderItemResource`),
  confirmed working for reorder.

**Call vs. chat clarification**: nothing in the codebase or BRD currently
restricts contacting the technician to support-chat-only, so `phone` is
returned unconditionally, enabling direct calling. If the business wants
chat-only, that's a policy decision for you to make — tell us and we'll gate
the field (e.g. behind a feature flag) rather than remove it outright.

## 2. Gateway Price Acceptance

`POST /api/v1/company/orders/{order_uuid}/accept-price` — the gateway path
(`payment_method` anything other than `"wallet"`) is **already fully
implemented**, not a stub, and it settles **synchronously**:

```php
// App\Services\Client\Commands\OrderCommandService (shared by Client + Company)
$payment = $this->gateway->charge($order, ['amount' => (float) $order->total_amount]);
```

`PaymentGatewayInterface` is bound directly to `DummyPaymentGateway`
(`app/Providers/CoreServiceProvider.php`) — a placeholder pending a real
gateway vendor decision (tracked in the BRD gap analysis, G-01/DEP-04; same
gap noted in the invoice-payments reply). `DummyPaymentGateway::charge()`
always succeeds immediately and `requiresRedirect()` is `false`.

**Answering your question directly: no `payment_url`/WebView flow exists or
is needed today** — the charge completes before the HTTP response is sent.
Success returns the updated order (same shape as `Show Order Details`);
failure returns:

```json
{"status": "fail", "message": "Payment failed.", "data": {"payment_id": 123}}
```

**This will change once a real gateway is integrated** — a synchronous
`charge()` becomes a redirect-based one the moment `requiresRedirect()`
returns `true` for that driver, at which point this endpoint's response
shape needs the `payment_url`/`expires_at`/status-check contract you
described (the same pattern already built for invoice payments in
`docs/company-invoice-payments-api.md`, section 2–3, ready to mirror here).
No action needed now — flagging so the contract change isn't a surprise
later.

## Files changed

- `app/Services/Client/Queries/OrderQueryService.php` — eager-load
  `technician.personalPhoto` and `attachments` for `show()` (shared by both
  Client and Company, since Company reuses this service directly).
- `app/Http/Resources/Client/Order/OrderDetailsResource.php` — populated
  `address`/`technician` fields, added `technician_attachments`.
- `app/Models/OrderAttachment.php` — added the missing `order()` relation
  (existed only from the `Order` side before).

Note: `app/Http/Resources/Company/Order/*` exist but are **not** wired into
the live `index`/`show` calls — the Company controller delegates to the
Client query service/resources directly (by design, per the existing code
comment: company and individual orders share one lifecycle). The fix above
was made in the Client resource so both roles get it; the unused Company
resource classes are a pre-existing gap, flagging for awareness, not
touched here.
