Citas

Gestión de citas de llamadas. Permite programar videollamadas con fecha y hora definidas. Requiere rol de attendant o superior.

Endpoints

Método	Endpoint	Descripción	Rol Mínimo
GET	/api/v1/appointments	Listar citas	attendant
POST	/api/v1/appointments	Crear cita	attendant
GET	/api/v1/appointments/:id	Buscar cita	attendant
PUT	/api/v1/appointments/:id	Actualizar cita	attendant
GET	/api/v1/appointments/conflicts	Verificar conflictos	attendant
POST	/api/v1/appointments/:id/confirm	Confirmar cita	attendant
POST	/api/v1/appointments/:id/cancel	Cancelar cita	attendant
POST	/api/v1/appointments/:id/complete	Marcar como completada	attendant
POST	/api/v1/appointments/:id/no-show	Marcar como no-show	attendant

---

Listar Citas

GET /api/v1/appointments

Query Parameters

Parámetro	Tipo	Predeterminado	Descripción
page	integer	1	Número de página
page_size	integer	20	Elementos por página
sort_by	string	scheduled_at	Campo para ordenamiento
sort_order	string	asc	Dirección del ordenamiento
status	string	-	Filtro: scheduled, confirmed, completed, cancelled, no_show
date_from	string	-	Fecha inicio (ISO 8601)
date_to	string	-	Fecha fin (ISO 8601)
user_id	uuid	-	Filtro por agente
department_id	uuid	-	Filtro por departamento

Ejemplo de Request

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"

Respuesta Exitosa (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
  }
}

---

Crear Cita

POST /api/v1/appointments

Request Body

Campo	Tipo	Obligatorio	Descripción
title	string	Sí	Título de la cita
description	string	No	Descripción detallada
scheduled_at	string	Sí	Fecha y hora (ISO 8601, futuro)
duration_minutes	integer	No	Duración en minutos (predeterminado: 30)
department_id	uuid	Sí	ID del departamento
user_id	uuid	No	ID del agente (predeterminado: usuario autenticado)
customer_id	uuid	No	ID del cliente existente
customer_name	string	Sí*	Nombre del cliente (si no se proporciona customer_id)
customer_email	string	No	Email del cliente
customer_phone	string	No	Teléfono del cliente
notes	string	No	Observaciones

Ejemplo de Request

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": "Reunião de apresentação",
      "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"
    }
  }'

Respuesta Exitosa (201)

{
  "data": {
    "id": "5d6e7f8a-9b0c-1234-efgh-567890123456",
    "title": "Reunião de apresentação",
    "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"
  }
}

---

Verificar Conflictos

Verifica si hay conflictos de horario para un agente.

GET /api/v1/appointments/conflicts

Query Parameters

Parámetro	Tipo	Obligatorio	Descripción
user_id	uuid	Sí	ID del agente
scheduled_at	string	Sí	Fecha y hora a verificar
duration_minutes	integer	No	Duración en minutos (predeterminado: 30)
exclude_id	uuid	No	ID de cita a excluir de la verificación

Ejemplo de Request

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"

Respuesta Exitosa (200)

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

---

Confirmar Cita

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

Ejemplo de Request

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"

---

Cancelar Cita

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

Request Body (opcional)

Campo	Tipo	Obligatorio	Descripción
reason	string	No	Motivo de la cancelación

Ejemplo de Request

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": "Cliente solicitou reagendamento"
  }'

---

Marcar como Completada

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

---

Marcar como No-Show

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

---

Estado de la Cita

Estado	Descripción
scheduled	Programada, esperando confirmación
confirmed	Confirmada por el agente o cliente
completed	Llamada realizada
cancelled	Cancelada
no_show	El cliente no se presentó