Expose Care service-token APIs to create queues and counters.

Specialty module activation needs idempotent queue/counter upserts
(by external_key or name+branch) plus soft deactivate, without
opening Queue admin for each Care specialty.

Co-authored-by: Cursor <cursoragent@cursor.com>

app/Http/Controllers/Api/BranchController.php

@@ -20,7 +20,13 @@ class BranchController extends Controller
         $branches = Branch::owned($this->ownerRef($request))
             ->where('organization_id', $this->organization($request)->id)
             ->orderBy('name')
-            ->get();
+            ->get()
+            ->map(fn (Branch $b) => [
+                'id' => $b->id,
+                'name' => $b->name,
+                'code' => $b->code,
+                'is_active' => $b->is_active,
+            ]);
 
         return response()->json(['data' => $branches]);
     }
@@ -31,25 +37,61 @@ class BranchController extends Controller
         $organization = $this->organization($request);
         $owner = $this->ownerRef($request);
 
-        $currentCount = Branch::owned($owner)->where('organization_id', $organization->id)->count();
-        abort_unless(app(PlanService::class)->canAddBranch($organization, $currentCount), 422, 'Branch limit reached for current plan.');
-
         $validated = $request->validate([
             'name' => ['required', 'string', 'max:255'],
             'code' => ['nullable', 'string', 'max:50'],
             'address' => ['nullable', 'string', 'max:500'],
             'phone' => ['nullable', 'string', 'max:50'],
+            'is_active' => ['nullable', 'boolean'],
         ]);
 
+        $existing = Branch::owned($owner)
+            ->where('organization_id', $organization->id)
+            ->whereRaw('LOWER(name) = ?', [strtolower($validated['name'])])
+            ->first();
+
+        if ($existing) {
+            $existing->update([
+                'code' => $validated['code'] ?? $existing->code,
+                'address' => $validated['address'] ?? $existing->address,
+                'phone' => $validated['phone'] ?? $existing->phone,
+                'is_active' => array_key_exists('is_active', $validated)
+                    ? (bool) $validated['is_active']
+                    : true,
+            ]);
+
+            return response()->json([
+                'data' => [
+                    'id' => $existing->id,
+                    'name' => $existing->name,
+                    'code' => $existing->code,
+                    'is_active' => $existing->is_active,
+                ],
+            ]);
+        }
+
+        $currentCount = Branch::owned($owner)->where('organization_id', $organization->id)->count();
+        abort_unless(app(PlanService::class)->canAddBranch($organization, $currentCount), 422, 'Branch limit reached for current plan.');
+
         $branch = Branch::create([
             'owner_ref' => $owner,
             'organization_id' => $organization->id,
-            ...$validated,
-            'is_active' => true,
+            'name' => $validated['name'],
+            'code' => $validated['code'] ?? null,
+            'address' => $validated['address'] ?? null,
+            'phone' => $validated['phone'] ?? null,
+            'is_active' => array_key_exists('is_active', $validated) ? (bool) $validated['is_active'] : true,
         ]);
 
         AuditLogger::record($owner, 'branch.created', $organization->id, $owner, Branch::class, $branch->id);
 
-        return response()->json(['data' => $branch], 201);
+        return response()->json([
+            'data' => [
+                'id' => $branch->id,
+                'name' => $branch->name,
+                'code' => $branch->code,
+                'is_active' => $branch->is_active,
+            ],
+        ], 201);
     }
 }

app/Http/Controllers/Api/CounterController.php

@@ -4,6 +4,7 @@ namespace App\Http\Controllers\Api;
 
 use App\Http\Controllers\Api\Concerns\ScopesApiToAccount;
 use App\Http\Controllers\Controller;
+use App\Models\Branch;
 use App\Models\Counter;
 use App\Models\ServiceQueue;
 use App\Services\Qms\AuditLogger;
@@ -22,16 +23,10 @@ class CounterController extends Controller
 
         $counters = Counter::owned($owner)
             ->where('organization_id', $organization->id)
-            ->with('serviceQueues')
+            ->with(['serviceQueues', 'branch'])
             ->orderBy('name')
             ->get()
-            ->map(fn (Counter $c) => [
-                'uuid' => $c->uuid,
-                'name' => $c->name,
-                'code' => $c->code,
-                'status' => $c->status,
-                'queues' => $c->serviceQueues->pluck('name'),
-            ]);
+            ->map(fn (Counter $c) => $this->serializeCounter($c));
 
         return response()->json(['data' => $counters]);
     }
@@ -45,30 +40,156 @@ class CounterController extends Controller
         $validated = $request->validate([
             'name' => ['required', 'string', 'max:255'],
             'code' => ['nullable', 'string', 'max:50'],
-            'branch_id' => ['required', 'integer'],
+            'branch_id' => ['nullable', 'integer'],
+            'branch_name' => ['nullable', 'string', 'max:255'],
             'department_id' => ['nullable', 'integer'],
             'queue_ids' => ['nullable', 'array'],
             'queue_ids.*' => ['uuid'],
+            'queue_uuids' => ['nullable', 'array'],
+            'queue_uuids.*' => ['uuid'],
+            'external_key' => ['nullable', 'string', 'max:191'],
+            'is_active' => ['nullable', 'boolean'],
         ]);
 
+        $branch = $this->resolveBranch($request, $organization->id, $owner, $validated);
+        abort_unless($branch, 422, 'A valid branch_id or branch_name is required.');
+
+        $externalKey = isset($validated['external_key']) ? trim((string) $validated['external_key']) : '';
+        if ($externalKey !== '') {
+            $existing = Counter::owned($owner)
+                ->where('organization_id', $organization->id)
+                ->where('settings->external_key', $externalKey)
+                ->first();
+
+            if ($existing) {
+                $existing->update([
+                    'name' => $validated['name'],
+                    'code' => $validated['code'] ?? $existing->code,
+                    'branch_id' => $branch->id,
+                    'department_id' => $validated['department_id'] ?? $existing->department_id,
+                    'is_active' => array_key_exists('is_active', $validated)
+                        ? (bool) $validated['is_active']
+                        : true,
+                    'settings' => array_merge($existing->settings ?? [], ['external_key' => $externalKey]),
+                ]);
+                $this->syncQueues($existing, $owner, $validated);
+                AuditLogger::record($owner, 'counter.updated', $organization->id, $owner, Counter::class, $existing->id);
+
+                return response()->json(['data' => $this->serializeCounter($existing->fresh(['serviceQueues', 'branch']))]);
+            }
+        }
+
         $counter = Counter::create([
             'owner_ref' => $owner,
             'organization_id' => $organization->id,
-            'branch_id' => $validated['branch_id'],
+            'branch_id' => $branch->id,
             'department_id' => $validated['department_id'] ?? null,
             'name' => $validated['name'],
             'code' => $validated['code'] ?? null,
             'status' => 'offline',
-            'is_active' => true,
+            'is_active' => array_key_exists('is_active', $validated) ? (bool) $validated['is_active'] : true,
+            'settings' => $externalKey !== '' ? ['external_key' => $externalKey] : null,
         ]);
 
-        if (! empty($validated['queue_ids'])) {
-            $queueIds = ServiceQueue::owned($owner)->whereIn('uuid', $validated['queue_ids'])->pluck('id');
-            $counter->serviceQueues()->sync($queueIds);
-        }
+        $this->syncQueues($counter, $owner, $validated);
 
         AuditLogger::record($owner, 'counter.created', $organization->id, $owner, Counter::class, $counter->id);
 
-        return response()->json(['data' => ['uuid' => $counter->uuid, 'name' => $counter->name]], 201);
+        return response()->json(['data' => $this->serializeCounter($counter->fresh(['serviceQueues', 'branch']))], 201);
+    }
+
+    public function update(Request $request, Counter $counter): JsonResponse
+    {
+        $this->authorizeAbility($request, 'counters.manage');
+        $this->authorizeOwner($request, $counter);
+
+        $validated = $request->validate([
+            'name' => ['sometimes', 'string', 'max:255'],
+            'code' => ['nullable', 'string', 'max:50'],
+            'is_active' => ['sometimes', 'boolean'],
+            'queue_ids' => ['nullable', 'array'],
+            'queue_ids.*' => ['uuid'],
+            'queue_uuids' => ['nullable', 'array'],
+            'queue_uuids.*' => ['uuid'],
+        ]);
+
+        $counter->update(array_filter([
+            'name' => $validated['name'] ?? null,
+            'code' => array_key_exists('code', $validated) ? $validated['code'] : null,
+            'is_active' => array_key_exists('is_active', $validated) ? (bool) $validated['is_active'] : null,
+        ], fn ($v) => $v !== null));
+
+        if (array_key_exists('queue_ids', $validated) || array_key_exists('queue_uuids', $validated)) {
+            $this->syncQueues($counter, $this->ownerRef($request), $validated);
+        }
+
+        AuditLogger::record(
+            $this->ownerRef($request),
+            'counter.updated',
+            $counter->organization_id,
+            $this->ownerRef($request),
+            Counter::class,
+            $counter->id,
+        );
+
+        return response()->json(['data' => $this->serializeCounter($counter->fresh(['serviceQueues', 'branch']))]);
+    }
+
+    /**
+     * @param  array<string, mixed>  $validated
+     */
+    protected function resolveBranch(Request $request, int $organizationId, string $owner, array $validated): ?Branch
+    {
+        if (! empty($validated['branch_id'])) {
+            return Branch::owned($owner)
+                ->where('organization_id', $organizationId)
+                ->where('id', (int) $validated['branch_id'])
+                ->first();
+        }
+
+        $branchName = trim((string) ($validated['branch_name'] ?? ''));
+        if ($branchName === '') {
+            return null;
+        }
+
+        return Branch::owned($owner)
+            ->where('organization_id', $organizationId)
+            ->whereRaw('LOWER(name) = ?', [strtolower($branchName)])
+            ->first();
+    }
+
+    /**
+     * @param  array<string, mixed>  $validated
+     */
+    protected function syncQueues(Counter $counter, string $owner, array $validated): void
+    {
+        $uuids = $validated['queue_uuids'] ?? $validated['queue_ids'] ?? null;
+        if ($uuids === null) {
+            return;
+        }
+
+        $queueIds = ServiceQueue::owned($owner)->whereIn('uuid', $uuids)->pluck('id');
+        $counter->serviceQueues()->sync($queueIds);
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    protected function serializeCounter(Counter $c): array
+    {
+        return [
+            'uuid' => $c->uuid,
+            'name' => $c->name,
+            'code' => $c->code,
+            'status' => $c->status,
+            'is_active' => $c->is_active,
+            'branch' => $c->branch?->name,
+            'external_key' => data_get($c->settings, 'external_key'),
+            'queues' => $c->serviceQueues->map(fn (ServiceQueue $q) => [
+                'uuid' => $q->uuid,
+                'name' => $q->name,
+                'prefix' => $q->prefix,
+            ])->values()->all(),
+        ];
     }
 }

app/Http/Controllers/Api/ServiceQueueController.php

@@ -4,8 +4,10 @@ namespace App\Http\Controllers\Api;
 
 use App\Http\Controllers\Api\Concerns\ScopesApiToAccount;
 use App\Http\Controllers\Controller;
-use App\Models\Counter;
+use App\Models\Branch;
 use App\Models\ServiceQueue;
+use App\Services\Qms\AuditLogger;
+use App\Services\Qms\PlanService;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 
@@ -24,19 +26,144 @@ class ServiceQueueController extends Controller
             ->with(['branch', 'department'])
             ->orderBy('name')
             ->get()
-            ->map(fn (ServiceQueue $q) => [
-                'uuid' => $q->uuid,
-                'name' => $q->name,
-                'prefix' => $q->prefix,
-                'strategy' => $q->strategy,
-                'is_active' => $q->is_active,
-                'is_paused' => $q->is_paused,
-                'branch' => $q->branch?->name,
-            ]);
+            ->map(fn (ServiceQueue $q) => $this->serializeQueue($q));
 
         return response()->json(['data' => $queues]);
     }
 
+    public function store(Request $request): JsonResponse
+    {
+        $this->authorizeAbility($request, 'queues.manage');
+        $owner = $this->ownerRef($request);
+        $organization = $this->organization($request);
+
+        $validated = $request->validate([
+            'name' => ['required', 'string', 'max:255'],
+            'description' => ['nullable', 'string', 'max:1000'],
+            'branch_id' => ['nullable', 'integer'],
+            'branch_name' => ['nullable', 'string', 'max:255'],
+            'department_id' => ['nullable', 'integer'],
+            'color' => ['nullable', 'string', 'max:20'],
+            'prefix' => ['required', 'string', 'max:10'],
+            'strategy' => ['nullable', 'string', 'in:'.implode(',', array_keys(config('qms.queue_strategies')))],
+            'avg_service_seconds' => ['nullable', 'integer', 'min:60', 'max:7200'],
+            'max_capacity' => ['nullable', 'integer', 'min:1'],
+            'is_active' => ['nullable', 'boolean'],
+            'external_key' => ['nullable', 'string', 'max:191'],
+        ]);
+
+        $branch = $this->resolveBranch($organization->id, $owner, $validated);
+        abort_unless($branch, 422, 'A valid branch_id or branch_name is required.');
+
+        $externalKey = isset($validated['external_key']) ? trim((string) $validated['external_key']) : '';
+        if ($externalKey !== '') {
+            $existing = ServiceQueue::owned($owner)
+                ->where('organization_id', $organization->id)
+                ->where('settings->external_key', $externalKey)
+                ->first();
+
+            if ($existing) {
+                $existing->update([
+                    'name' => $validated['name'],
+                    'description' => $validated['description'] ?? $existing->description,
+                    'branch_id' => $branch->id,
+                    'department_id' => $validated['department_id'] ?? $existing->department_id,
+                    'color' => $validated['color'] ?? $existing->color,
+                    'prefix' => $validated['prefix'],
+                    'strategy' => $validated['strategy'] ?? $existing->strategy,
+                    'avg_service_seconds' => $validated['avg_service_seconds'] ?? $existing->avg_service_seconds,
+                    'max_capacity' => $validated['max_capacity'] ?? $existing->max_capacity,
+                    'is_active' => array_key_exists('is_active', $validated)
+                        ? (bool) $validated['is_active']
+                        : true,
+                    'settings' => array_merge($existing->settings ?? [], ['external_key' => $externalKey]),
+                ]);
+                AuditLogger::record($owner, 'service_queue.updated', $organization->id, $owner, ServiceQueue::class, $existing->id);
+
+                return response()->json(['data' => $this->serializeQueue($existing->fresh(['branch', 'department']))]);
+            }
+        }
+
+        // Fall back to name + branch match so Care/manual admin create do not duplicate.
+        $byName = ServiceQueue::owned($owner)
+            ->where('organization_id', $organization->id)
+            ->where('branch_id', $branch->id)
+            ->whereRaw('LOWER(name) = ?', [strtolower($validated['name'])])
+            ->first();
+
+        if ($byName) {
+            $settings = $byName->settings ?? [];
+            if ($externalKey !== '') {
+                $settings['external_key'] = $externalKey;
+            }
+            $byName->update([
+                'prefix' => $validated['prefix'],
+                'strategy' => $validated['strategy'] ?? $byName->strategy,
+                'is_active' => array_key_exists('is_active', $validated) ? (bool) $validated['is_active'] : true,
+                'settings' => $settings !== [] ? $settings : $byName->settings,
+            ]);
+            AuditLogger::record($owner, 'service_queue.updated', $organization->id, $owner, ServiceQueue::class, $byName->id);
+
+            return response()->json(['data' => $this->serializeQueue($byName->fresh(['branch', 'department']))]);
+        }
+
+        $currentCount = ServiceQueue::owned($owner)->where('organization_id', $organization->id)->count();
+        abort_unless(
+            app(PlanService::class)->canAddQueue($organization, $currentCount),
+            422,
+            'Queue limit reached for current plan.',
+        );
+
+        $queue = ServiceQueue::create([
+            'owner_ref' => $owner,
+            'organization_id' => $organization->id,
+            'branch_id' => $branch->id,
+            'department_id' => $validated['department_id'] ?? null,
+            'name' => $validated['name'],
+            'description' => $validated['description'] ?? null,
+            'color' => $validated['color'] ?? '#4f46e5',
+            'prefix' => $validated['prefix'],
+            'strategy' => $validated['strategy'] ?? 'fifo',
+            'avg_service_seconds' => $validated['avg_service_seconds'] ?? 300,
+            'max_capacity' => $validated['max_capacity'] ?? null,
+            'is_active' => array_key_exists('is_active', $validated) ? (bool) $validated['is_active'] : true,
+            'settings' => $externalKey !== '' ? ['external_key' => $externalKey] : null,
+        ]);
+
+        AuditLogger::record($owner, 'service_queue.created', $organization->id, $owner, ServiceQueue::class, $queue->id);
+
+        return response()->json(['data' => $this->serializeQueue($queue->fresh(['branch', 'department']))], 201);
+    }
+
+    public function update(Request $request, ServiceQueue $serviceQueue): JsonResponse
+    {
+        $this->authorizeAbility($request, 'queues.manage');
+        $this->authorizeOwner($request, $serviceQueue);
+
+        $validated = $request->validate([
+            'name' => ['sometimes', 'string', 'max:255'],
+            'description' => ['nullable', 'string', 'max:1000'],
+            'prefix' => ['sometimes', 'string', 'max:10'],
+            'strategy' => ['sometimes', 'string', 'in:'.implode(',', array_keys(config('qms.queue_strategies')))],
+            'is_active' => ['sometimes', 'boolean'],
+            'avg_service_seconds' => ['nullable', 'integer', 'min:60', 'max:7200'],
+            'max_capacity' => ['nullable', 'integer', 'min:1'],
+        ]);
+
+        $serviceQueue->update($validated);
+
+        AuditLogger::record(
+            $this->ownerRef($request),
+            'service_queue.updated',
+            $serviceQueue->organization_id,
+            $this->ownerRef($request),
+            ServiceQueue::class,
+            $serviceQueue->id,
+        );
+
+        return response()->json(['data' => $this->serializeQueue($serviceQueue->fresh(['branch', 'department']))]);
+    }
+
     public function waiting(Request $request, ServiceQueue $serviceQueue): JsonResponse
     {
         $this->authorizeAbility($request, 'queues.view');
@@ -68,4 +195,44 @@ class ServiceQueueController extends Controller
 
         return response()->json(['data' => ['uuid' => $queue->uuid, 'is_paused' => $queue->is_paused]]);
     }
+
+    /**
+     * @param  array<string, mixed>  $validated
+     */
+    protected function resolveBranch(int $organizationId, string $owner, array $validated): ?Branch
+    {
+        if (! empty($validated['branch_id'])) {
+            return Branch::owned($owner)
+                ->where('organization_id', $organizationId)
+                ->where('id', (int) $validated['branch_id'])
+                ->first();
+        }
+
+        $branchName = trim((string) ($validated['branch_name'] ?? ''));
+        if ($branchName === '') {
+            return null;
+        }
+
+        return Branch::owned($owner)
+            ->where('organization_id', $organizationId)
+            ->whereRaw('LOWER(name) = ?', [strtolower($branchName)])
+            ->first();
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    protected function serializeQueue(ServiceQueue $q): array
+    {
+        return [
+            'uuid' => $q->uuid,
+            'name' => $q->name,
+            'prefix' => $q->prefix,
+            'strategy' => $q->strategy,
+            'is_active' => $q->is_active,
+            'is_paused' => $q->is_paused,
+            'branch' => $q->branch?->name,
+            'external_key' => data_get($q->settings, 'external_key'),
+        ];
+    }
 }

routes/api.php

@@ -31,6 +31,8 @@ Route::prefix('v1/public')->group(function () {
 
 Route::middleware(['auth:sanctum', 'qms.setup'])->prefix('v1')->group(function () {
     Route::get('/queues', [ServiceQueueController::class, 'index'])->name('api.queues.index');
+    Route::post('/queues', [ServiceQueueController::class, 'store'])->name('api.queues.store');
+    Route::patch('/queues/{serviceQueue}', [ServiceQueueController::class, 'update'])->name('api.queues.update');
     Route::get('/queues/{serviceQueue}/waiting', [ServiceQueueController::class, 'waiting'])->name('api.queues.waiting');
     Route::post('/queues/{serviceQueue}/pause', [ServiceQueueController::class, 'pause'])->name('api.queues.pause');
     Route::post('/queues/{serviceQueue}/resume', [ServiceQueueController::class, 'resume'])->name('api.queues.resume');
@@ -43,6 +45,7 @@ Route::middleware(['auth:sanctum', 'qms.setup'])->prefix('v1')->group(function (
 
     Route::get('/counters', [CounterController::class, 'index'])->name('api.counters.index');
     Route::post('/counters', [CounterController::class, 'store'])->name('api.counters.store');
+    Route::patch('/counters/{counter}', [CounterController::class, 'update'])->name('api.counters.update');
 
     Route::get('/appointments', [AppointmentController::class, 'index'])->name('api.appointments.index');
     Route::post('/appointments', [AppointmentController::class, 'store'])->name('api.appointments.store');
@@ -68,7 +71,12 @@ Route::middleware(['auth.service:qms'])->prefix('v1')->group(function () {
 });
 
 Route::middleware(['auth.service:qms', 'qms.integration'])->prefix('v1')->group(function () {
+    Route::get('/branches', [BranchController::class, 'index'])->name('api.service.branches.index');
+    Route::post('/branches', [BranchController::class, 'store'])->name('api.service.branches.store');
+
     Route::get('/queues', [ServiceQueueController::class, 'index'])->name('api.service.queues.index');
+    Route::post('/queues', [ServiceQueueController::class, 'store'])->name('api.service.queues.store');
+    Route::patch('/queues/{serviceQueue}', [ServiceQueueController::class, 'update'])->name('api.service.queues.update');
     Route::get('/queues/{serviceQueue}/waiting', [ServiceQueueController::class, 'waiting'])->name('api.service.queues.waiting');
     Route::post('/queues/{serviceQueue}/call-next', [TicketController::class, 'callNext'])->name('api.service.queues.call-next');
 
@@ -76,6 +84,8 @@ Route::middleware(['auth.service:qms', 'qms.integration'])->prefix('v1')->group(
     Route::post('/tickets/{ticket}/action', [TicketController::class, 'action'])->name('api.service.tickets.action');
 
     Route::get('/counters', [CounterController::class, 'index'])->name('api.service.counters.index');
+    Route::post('/counters', [CounterController::class, 'store'])->name('api.service.counters.store');
+    Route::patch('/counters/{counter}', [CounterController::class, 'update'])->name('api.service.counters.update');
     Route::get('/counters/{counter}/console', [ConsoleApiController::class, 'show'])->name('api.service.counters.console');
     Route::post('/counters/{counter}/console', [ConsoleApiController::class, 'action'])->name('api.service.counters.console.action');
 });

tests/Feature/CareIntegrationTest.php

@@ -97,4 +97,115 @@ class CareIntegrationTest extends TestCase
         $this->assertSame('uuid', (new Counter)->getRouteKeyName());
         $this->assertSame('uuid', (new ServiceQueue)->getRouteKeyName());
     }
+
+    public function test_care_can_create_queue_and_counter_idempotently(): void
+    {
+        $owner = 'care-owner-uuid';
+        $headers = $this->careHeaders($owner);
+        $this->provisionCareOrg($owner);
+
+        $queueResponse = $this->postJson('/api/v1/queues', [
+            'owner' => $owner,
+            'name' => 'Dentistry',
+            'prefix' => 'DEN',
+            'branch_name' => 'Main',
+            'external_key' => 'care:specialty:dentistry:queue:1',
+            'strategy' => 'fifo',
+        ], $headers)
+            ->assertCreated()
+            ->assertJsonPath('data.name', 'Dentistry')
+            ->assertJsonPath('data.external_key', 'care:specialty:dentistry:queue:1');
+
+        $queueUuid = $queueResponse->json('data.uuid');
+
+        $this->postJson('/api/v1/queues', [
+            'owner' => $owner,
+            'name' => 'Dentistry Desk',
+            'prefix' => 'DEN',
+            'branch_name' => 'Main',
+            'external_key' => 'care:specialty:dentistry:queue:1',
+            'strategy' => 'fifo',
+        ], $headers)
+            ->assertOk()
+            ->assertJsonPath('data.uuid', $queueUuid)
+            ->assertJsonPath('data.name', 'Dentistry Desk');
+
+        $this->assertSame(1, ServiceQueue::owned($owner)->count());
+
+        $counterResponse = $this->postJson('/api/v1/counters', [
+            'owner' => $owner,
+            'name' => 'Dentistry counter',
+            'branch_name' => 'Main',
+            'queue_uuids' => [$queueUuid],
+            'external_key' => 'care:specialty:dentistry:counter:1',
+        ], $headers)
+            ->assertCreated()
+            ->assertJsonPath('data.name', 'Dentistry counter')
+            ->assertJsonPath('data.branch', 'Main')
+            ->assertJsonPath('data.queues.0.uuid', $queueUuid);
+
+        $counterUuid = $counterResponse->json('data.uuid');
+
+        $this->postJson('/api/v1/counters', [
+            'owner' => $owner,
+            'name' => 'Dentistry counter',
+            'branch_name' => 'Main',
+            'queue_uuids' => [$queueUuid],
+            'external_key' => 'care:specialty:dentistry:counter:1',
+        ], $headers)
+            ->assertOk()
+            ->assertJsonPath('data.uuid', $counterUuid);
+
+        $this->assertSame(1, Counter::owned($owner)->count());
+
+        $this->getJson('/api/v1/counters?owner='.$owner, $headers)
+            ->assertOk()
+            ->assertJsonPath('data.0.uuid', $counterUuid)
+            ->assertJsonPath('data.0.branch', 'Main')
+            ->assertJsonPath('data.0.queues.0.name', 'Dentistry Desk');
+    }
+
+    public function test_care_can_soft_deactivate_counter(): void
+    {
+        $owner = 'care-owner-uuid';
+        $headers = $this->careHeaders($owner);
+        $organization = $this->provisionCareOrg($owner);
+        $branch = Branch::owned($owner)->where('organization_id', $organization->id)->firstOrFail();
+        $counter = Counter::create([
+            'owner_ref' => $owner,
+            'organization_id' => $organization->id,
+            'branch_id' => $branch->id,
+            'name' => 'Eye care counter',
+            'status' => 'offline',
+            'is_active' => true,
+        ]);
+
+        $this->patchJson('/api/v1/counters/'.$counter->uuid, [
+            'owner' => $owner,
+            'is_active' => false,
+        ], $headers)
+            ->assertOk()
+            ->assertJsonPath('data.is_active', false);
+
+        $this->assertFalse($counter->fresh()->is_active);
+        $this->assertDatabaseHas('queue_counters', ['id' => $counter->id]);
+    }
+
+    public function test_care_can_ensure_branch_by_name_idempotently(): void
+    {
+        $owner = 'care-owner-uuid';
+        $headers = $this->careHeaders($owner);
+        $this->provisionCareOrg($owner);
+
+        // Free plan is capped at 1 branch; provision already created Main — upsert must not duplicate.
+        $this->postJson('/api/v1/branches', [
+            'owner' => $owner,
+            'name' => 'Main',
+        ], $headers)
+            ->assertOk()
+            ->assertJsonPath('data.name', 'Main')
+            ->assertJsonPath('data.is_active', true);
+
+        $this->assertSame(1, Branch::owned($owner)->count());
+    }
 }