230 lines
4.2 KiB
Markdown
230 lines
4.2 KiB
Markdown
# V2 Command API
|
|
|
|
Use `command-api-v2` for write actions that change business state.
|
|
|
|
Base URL:
|
|
|
|
```text
|
|
https://krow-command-api-v2-e3g6witsvq-uc.a.run.app
|
|
```
|
|
|
|
## 1) Required headers
|
|
|
|
```http
|
|
Authorization: Bearer <firebase-id-token>
|
|
Idempotency-Key: <unique-per-user-action>
|
|
Content-Type: application/json
|
|
```
|
|
|
|
## 2) Route summary
|
|
|
|
| Method | Route | Purpose |
|
|
| --- | --- | --- |
|
|
| `POST` | `/commands/orders/create` | Create order with shifts and roles |
|
|
| `POST` | `/commands/orders/:orderId/update` | Update mutable order fields |
|
|
| `POST` | `/commands/orders/:orderId/cancel` | Cancel order and related eligible records |
|
|
| `POST` | `/commands/shifts/:shiftId/assign-staff` | Assign workforce to shift role |
|
|
| `POST` | `/commands/shifts/:shiftId/accept` | Accept an assigned shift |
|
|
| `POST` | `/commands/shifts/:shiftId/change-status` | Move shift to a new valid status |
|
|
| `POST` | `/commands/attendance/clock-in` | Record clock-in event |
|
|
| `POST` | `/commands/attendance/clock-out` | Record clock-out event |
|
|
| `POST` | `/commands/businesses/:businessId/favorite-staff` | Add favorite staff |
|
|
| `DELETE` | `/commands/businesses/:businessId/favorite-staff/:staffId` | Remove favorite staff |
|
|
| `POST` | `/commands/assignments/:assignmentId/reviews` | Create or update staff review |
|
|
| `GET` | `/readyz` | Ready check |
|
|
|
|
## 3) Order create
|
|
|
|
```text
|
|
POST /commands/orders/create
|
|
```
|
|
|
|
Request body:
|
|
|
|
```json
|
|
{
|
|
"tenantId": "uuid",
|
|
"businessId": "uuid",
|
|
"vendorId": "uuid",
|
|
"orderNumber": "ORD-1001",
|
|
"title": "Cafe Event Staffing",
|
|
"serviceType": "EVENT",
|
|
"shifts": [
|
|
{
|
|
"shiftCode": "SHIFT-1",
|
|
"title": "Morning Shift",
|
|
"startsAt": "2026-03-12T08:00:00.000Z",
|
|
"endsAt": "2026-03-12T16:00:00.000Z",
|
|
"requiredWorkers": 2,
|
|
"roles": [
|
|
{
|
|
"roleCode": "BARISTA",
|
|
"roleName": "Barista",
|
|
"workersNeeded": 2
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## 4) Order update
|
|
|
|
```text
|
|
POST /commands/orders/:orderId/update
|
|
```
|
|
|
|
Required body fields:
|
|
- `tenantId`
|
|
- at least one mutable field such as `title`, `description`, `vendorId`, `serviceType`, `startsAt`, `endsAt`, `locationName`, `locationAddress`, `latitude`, `longitude`, `notes`, `metadata`
|
|
|
|
You can also send `null` to clear nullable fields.
|
|
|
|
## 5) Order cancel
|
|
|
|
```text
|
|
POST /commands/orders/:orderId/cancel
|
|
```
|
|
|
|
Example request:
|
|
|
|
```json
|
|
{
|
|
"tenantId": "uuid",
|
|
"reason": "Client cancelled"
|
|
}
|
|
```
|
|
|
|
## 6) Shift assign staff
|
|
|
|
```text
|
|
POST /commands/shifts/:shiftId/assign-staff
|
|
```
|
|
|
|
Example request:
|
|
|
|
```json
|
|
{
|
|
"tenantId": "uuid",
|
|
"shiftRoleId": "uuid",
|
|
"workforceId": "uuid",
|
|
"applicationId": "uuid"
|
|
}
|
|
```
|
|
|
|
## 7) Shift accept
|
|
|
|
```text
|
|
POST /commands/shifts/:shiftId/accept
|
|
```
|
|
|
|
Example request:
|
|
|
|
```json
|
|
{
|
|
"shiftRoleId": "uuid",
|
|
"workforceId": "uuid"
|
|
}
|
|
```
|
|
|
|
## 8) Shift status change
|
|
|
|
```text
|
|
POST /commands/shifts/:shiftId/change-status
|
|
```
|
|
|
|
Example request:
|
|
|
|
```json
|
|
{
|
|
"tenantId": "uuid",
|
|
"status": "PENDING_CONFIRMATION",
|
|
"reason": "Waiting for worker confirmation"
|
|
}
|
|
```
|
|
|
|
Allowed status values:
|
|
- `DRAFT`
|
|
- `OPEN`
|
|
- `PENDING_CONFIRMATION`
|
|
- `ASSIGNED`
|
|
- `ACTIVE`
|
|
- `COMPLETED`
|
|
- `CANCELLED`
|
|
|
|
## 9) Attendance
|
|
|
|
### Clock in
|
|
|
|
```text
|
|
POST /commands/attendance/clock-in
|
|
```
|
|
|
|
### Clock out
|
|
|
|
```text
|
|
POST /commands/attendance/clock-out
|
|
```
|
|
|
|
Example request body for both:
|
|
|
|
```json
|
|
{
|
|
"assignmentId": "uuid",
|
|
"sourceType": "NFC",
|
|
"sourceReference": "iphone-15-pro-max",
|
|
"nfcTagUid": "NFC-DEMO-ANA-001",
|
|
"deviceId": "device-123",
|
|
"latitude": 37.422,
|
|
"longitude": -122.084,
|
|
"accuracyMeters": 8,
|
|
"capturedAt": "2026-03-11T17:15:00.000Z"
|
|
}
|
|
```
|
|
|
|
## 10) Favorite staff
|
|
|
|
### Add favorite
|
|
|
|
```text
|
|
POST /commands/businesses/:businessId/favorite-staff
|
|
```
|
|
|
|
### Remove favorite
|
|
|
|
```text
|
|
DELETE /commands/businesses/:businessId/favorite-staff/:staffId
|
|
```
|
|
|
|
Request body when adding:
|
|
|
|
```json
|
|
{
|
|
"tenantId": "uuid",
|
|
"staffId": "uuid"
|
|
}
|
|
```
|
|
|
|
## 11) Staff review
|
|
|
|
```text
|
|
POST /commands/assignments/:assignmentId/reviews
|
|
```
|
|
|
|
Example request:
|
|
|
|
```json
|
|
{
|
|
"tenantId": "uuid",
|
|
"businessId": "uuid",
|
|
"staffId": "uuid",
|
|
"rating": 5,
|
|
"reviewText": "Strong shift performance",
|
|
"tags": ["punctual", "professional"]
|
|
}
|
|
```
|
|
|
|
## 12) Live status
|
|
|
|
These routes were live-tested on `2026-03-11` against the deployed dev service and `krow-sql-v2`.
|