care-book-block-ultimate/specs/001-wordpress-plugin-para/contracts/admin-api.md

Admin API Contracts: Care Booking Block Plugin

Feature: WordPress Plugin para Controlo Seguro de Agendamentos KiviCare
Date: 2025-09-10
Type: WordPress AJAX API Contracts

AJAX Endpoints

1. Get Restrictions List

Endpoint: wp_ajax_care_booking_get_restrictions
Method: POST
Auth: WordPress nonce verification
Capability: manage_options

Request:

{
    "action": "care_booking_get_restrictions",
    "nonce": "wp_nonce_string",
    "restriction_type": "doctor|service|all",
    "doctor_id": 123 // Optional: for service restrictions
}

Response Success (200):

{
    "success": true,
    "data": {
        "restrictions": [
            {
                "id": 1,
                "restriction_type": "doctor",
                "target_id": 123,
                "doctor_id": null,
                "is_blocked": true,
                "created_at": "2025-09-10 10:00:00",
                "updated_at": "2025-09-10 10:00:00"
            }
        ],
        "total": 1
    }
}

Response Error (400/403):

{
    "success": false,
    "data": {
        "message": "Invalid nonce" | "Insufficient permissions" | "Invalid parameters"
    }
}

2. Toggle Restriction

Endpoint: wp_ajax_care_booking_toggle_restriction
Method: POST
Auth: WordPress nonce verification
Capability: manage_options

Request:

{
    "action": "care_booking_toggle_restriction",
    "nonce": "wp_nonce_string",
    "restriction_type": "doctor|service",
    "target_id": 123,
    "doctor_id": 456, // Required for service restrictions
    "is_blocked": true
}

Response Success (200):

{
    "success": true,
    "data": {
        "message": "Restriction updated successfully",
        "restriction": {
            "id": 1,
            "restriction_type": "doctor",
            "target_id": 123,
            "doctor_id": null,
            "is_blocked": true,
            "updated_at": "2025-09-10 10:05:00"
        }
    }
}

Response Error (400/403/500):

{
    "success": false,
    "data": {
        "message": "Failed to update restriction" | "Target not found" | "Database error"
    }
}

3. Bulk Update Restrictions

Endpoint: wp_ajax_care_booking_bulk_update
Method: POST
Auth: WordPress nonce verification
Capability: manage_options

Request:

{
    "action": "care_booking_bulk_update",
    "nonce": "wp_nonce_string",
    "restrictions": [
        {
            "restriction_type": "doctor",
            "target_id": 123,
            "is_blocked": true
        },
        {
            "restriction_type": "service",
            "target_id": 456,
            "doctor_id": 123,
            "is_blocked": false
        }
    ]
}

Response Success (200):

{
    "success": true,
    "data": {
        "message": "Bulk update completed",
        "updated": 2,
        "errors": []
    }
}

Response Error (400/500):

{
    "success": false,
    "data": {
        "message": "Partial failure in bulk update",
        "updated": 1,
        "errors": [
            {
                "restriction": {
                    "target_id": 456,
                    "restriction_type": "service"
                },
                "error": "Target not found in KiviCare"
            }
        ]
    }
}

4. Get KiviCare Entities

Endpoint: wp_ajax_care_booking_get_entities
Method: POST
Auth: WordPress nonce verification
Capability: manage_options

Request:

{
    "action": "care_booking_get_entities",
    "nonce": "wp_nonce_string",
    "entity_type": "doctors|services",
    "doctor_id": 123 // Optional: for services by doctor
}

Response Success (200):

{
    "success": true,
    "data": {
        "entities": [
            {
                "id": 123,
                "name": "Dr. João Silva",
                "email": "joao@clinic.com",
                "is_blocked": true // Current restriction status
            }
        ],
        "total": 1
    }
}

WordPress Hooks Integration Contracts

1. KiviCare Doctor List Filter

Hook: kc_get_doctors_for_booking
Type: WordPress Filter
Priority: 10

Input:

$doctors = [
    ['id' => 123, 'name' => 'Dr. João Silva', 'email' => 'joao@clinic.com'],
    ['id' => 124, 'name' => 'Dr. Maria Santos', 'email' => 'maria@clinic.com']
];

Output (filtered):

$doctors = [
    ['id' => 124, 'name' => 'Dr. Maria Santos', 'email' => 'maria@clinic.com']
    // Dr. João Silva removed if blocked
];

2. KiviCare Service List Filter

Hook: kc_get_services_by_doctor
Type: WordPress Filter
Priority: 10

Input:

$services = [
    ['id' => 456, 'name' => 'Consulta Geral', 'doctor_id' => 123],
    ['id' => 457, 'name' => 'Revisão', 'doctor_id' => 123]
];
$doctor_id = 123;

Output (filtered):

$services = [
    ['id' => 456, 'name' => 'Consulta Geral', 'doctor_id' => 123]
    // 'Revisão' removed if blocked for this doctor
];

CSS Injection Contract

Dynamic CSS Generation

Hook: wp_head
Priority: 20 (after theme styles)

Generated CSS:

/* Dynamic CSS based on current restrictions */
.kivicare-doctor[data-doctor-id="123"],
.kivicare-service[data-service-id="456"][data-doctor-id="123"] {
    display: none !important;
}

/* Fallback for different KiviCare markup patterns */
#doctor-123,
#service-456-doctor-123,
.doctor-selection option[value="123"],
.service-selection option[value="456"] {
    display: none !important;
}

Validation Contracts

Input Validation Rules

Doctor/Service Target Validation:

function validate_target_exists($target_id, $type) {
    // Must return boolean
    // true if target exists in KiviCare
    // false if target not found
}

Nonce Validation:

function validate_nonce($nonce, $action) {
    // WordPress standard nonce verification
    return wp_verify_nonce($nonce, $action);
}

Capability Validation:

function validate_user_capability() {
    // Check if user can manage options
    return current_user_can('manage_options');
}

Error Response Contracts

Standard Error Codes

• 400: Bad Request (invalid parameters)
• 403: Forbidden (insufficient permissions, invalid nonce)
• 404: Not Found (target entity not found)
• 500: Internal Server Error (database error, KiviCare not available)

Error Message Format

All error responses follow WordPress AJAX standard:

{
    "success": false,
    "data": {
        "message": "Human readable error message",
        "code": "ERROR_CODE_CONSTANT", // Optional
        "details": {} // Optional additional error context
    }
}

Performance Contracts

Response Time Targets

• Get Restrictions: < 200ms
• Toggle Restriction: < 300ms (includes cache invalidation)
• Bulk Update: < 500ms for up to 50 items
• Get Entities: < 400ms (with KiviCare data fetch)

Cache Invalidation Contract

When any restriction is modified:

1. Clear care_booking_doctors_blocked transient
2. Clear all care_booking_services_blocked_{doctor_id} transients
3. Update care_booking_restrictions_hash with new hash
4. Trigger WordPress action: care_booking_restrictions_updated

These contracts define the exact interface between the admin panel, the WordPress backend, and the frontend filtering system.