Appointments

Management of call appointments. Allows scheduling video calls with defined date and time. Requires attendant role or above.

Endpoints

Method	Endpoint	Description	Minimum Role
GET	/api/v1/appointments	List appointments	attendant
POST	/api/v1/appointments	Create appointment	attendant
GET	/api/v1/appointments/:id	Get appointment	attendant
PUT	/api/v1/appointments/:id	Update appointment	attendant
GET	/api/v1/appointments/conflicts	Check conflicts	attendant
POST	/api/v1/appointments/:id/confirm	Confirm appointment	attendant
POST	/api/v1/appointments/:id/cancel	Cancel appointment	attendant
POST	/api/v1/appointments/:id/complete	Mark as completed	attendant
POST	/api/v1/appointments/:id/no-show	Mark as no-show	attendant

---

List Appointments

GET /api/v1/appointments

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
page_size	integer	20	Items per page
sort_by	string	scheduled_at	Sort field
sort_order	string	asc	Sort direction
status	string	-	Filter: scheduled, confirmed, completed, cancelled, no_show
date_from	string	-	Start date (ISO 8601)
date_to	string	-	End date (ISO 8601)
user_id	uuid	-	Filter by agent
department_id	uuid	-	Filter by department

Request Example

curl -X GET "https://voki.avanter.com.br/api/v1/appointments?date_from=2026-02-18&status=scheduled" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

{
  "data": [
    {
      "id": "4c5d6e7f-8a9b-0123-defg-456789012345",
      "title": "Consulta de acompanhamento",
      "description": "Retorno sobre tratamento iniciado em janeiro",
      "status": "scheduled",
      "scheduled_at": "2026-02-20T10:00:00Z",
      "duration_minutes": 30,
      "department_id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
      "department_name": "Suporte Técnico",
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_name": "João Silva",
      "customer_id": "2a3b4c5d-6e7f-8901-bcde-f23456789012",
      "customer_name": "Carlos Ferreira",
      "customer_email": "carlos@email.com",
      "customer_phone": "+5511999998888",
      "notes": null,
      "inserted_at": "2026-02-15T10:00:00Z",
      "updated_at": "2026-02-15T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "page_size": 20,
    "total_pages": 1,
    "total_count": 1
  }
}

---

Create Appointment

POST /api/v1/appointments

Request Body

Field	Type	Required	Description
title	string	Yes	Appointment title
description	string	No	Detailed description
scheduled_at	string	Yes	Date and time (ISO 8601, must be in the future)
duration_minutes	integer	No	Duration in minutes (default: 30)
department_id	uuid	Yes	Department ID
user_id	uuid	No	Agent ID (default: authenticated user)
customer_id	uuid	No	Existing customer ID
customer_name	string	Yes*	Customer name (if customer_id not provided)
customer_email	string	No	Customer email
customer_phone	string	No	Customer phone
notes	string	No	Notes

Request Example

curl -X POST https://voki.avanter.com.br/api/v1/appointments \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment": {
      "title": "Presentation meeting",
      "scheduled_at": "2026-02-25T14:00:00Z",
      "duration_minutes": 45,
      "department_id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
      "customer_name": "Roberto Lima",
      "customer_email": "roberto@email.com",
      "customer_phone": "+5511966665544"
    }
  }'

Success Response (201)

{
  "data": {
    "id": "5d6e7f8a-9b0c-1234-efgh-567890123456",
    "title": "Presentation meeting",
    "status": "scheduled",
    "scheduled_at": "2026-02-25T14:00:00Z",
    "duration_minutes": 45,
    "department_id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
    "department_name": "Suporte Técnico",
    "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user_name": "João Silva",
    "customer_id": "6e7f8a9b-0c1d-2345-fghi-678901234567",
    "customer_name": "Roberto Lima",
    "customer_email": "roberto@email.com",
    "customer_phone": "+5511966665544",
    "inserted_at": "2026-02-18T16:00:00Z",
    "updated_at": "2026-02-18T16:00:00Z"
  }
}

---

Check Conflicts

Checks for scheduling conflicts for an agent.

GET /api/v1/appointments/conflicts

Query Parameters

Parameter	Type	Required	Description
user_id	uuid	Yes	Agent ID
scheduled_at	string	Yes	Date and time to check
duration_minutes	integer	No	Duration in minutes (default: 30)
exclude_id	uuid	No	Appointment ID to exclude from check

Request Example

curl -X GET "https://voki.avanter.com.br/api/v1/appointments/conflicts?user_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&scheduled_at=2026-02-25T14:00:00Z&duration_minutes=45" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

Success Response (200)

{
  "data": {
    "has_conflicts": false,
    "conflicts": []
  }
}

---

Confirm Appointment

POST /api/v1/appointments/:id/confirm

Request Example

curl -X POST https://voki.avanter.com.br/api/v1/appointments/4c5d6e7f-8a9b-0123-defg-456789012345/confirm \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter"

---

Cancel Appointment

POST /api/v1/appointments/:id/cancel

Request Body (optional)

Field	Type	Required	Description
reason	string	No	Cancellation reason

Request Example

curl -X POST https://voki.avanter.com.br/api/v1/appointments/4c5d6e7f-8a9b-0123-defg-456789012345/cancel \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Tenant: avanter" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer requested rescheduling"
  }'

---

Mark as Completed

POST /api/v1/appointments/:id/complete

---

Mark as No-Show

POST /api/v1/appointments/:id/no-show

---

Appointment Status

Status	Description
scheduled	Scheduled, awaiting confirmation
confirmed	Confirmed by agent or customer
completed	Call completed
cancelled	Cancelled
no_show	Customer did not show up