Cancelar Agendas

Permite cancelar una o múltiples agendas en estado Asignada (A) mediante una única petición, indicando la causal de cancelación y, si se desea, observaciones. Este endpoint está diseñado para operaciones en lote (batch), permitiendo cancelar hasta 10,000 registros por petición.

Método: PATCH

Endpoint

https://api.ventasremotas.com/v1/appointments/cancel

Nota

Es necesario el envío del token de acceso Subscription-Key para hacer uso de este endpoint. Para ver cómo generar el token, vea Activación Suscripción a RSales API.

Encabezados de la solicitud

Header	Valor	Descripción
Content-Type	application/json	Indica que los datos se envían en formato JSON
Accept	application/json	Indica que la respuesta debe estar en formato JSON
Subscription-Key	{subscription_key}	Clave de suscripción para acceder a la API
Authorization	Bearer {access_token}	Token de acceso obtenido del endpoint /token

---

Parámetros del Cuerpo (Body)

El body debe ser un array de objetos, donde cada objeto representa una agenda a cancelar.

Límites

Parámetro	Valor	Descripción
Mínimo de items	1	El array no puede estar vacío
Máximo de items	10,000	Número máximo de agendas por petición

Campos

El cuerpo (Body) de la solicitud debe enviarse en formato JSON y debe incluir un array con los siguientes parámetros.

Importante

Los campos requeridos deben estar presentes en cada objeto del array. El campo cancellation_observations es opcional: puede omitirse o enviarse con valor null.

Campo	Tipo	Nulo	Restricciones	Descripción
code	int	No	Mayor o igual a 1	Código de la agenda a cancelar (campo code de Listar Agendas)
cancellation_reason	string (max 50)	No	Debe coincidir con la descripción de una causal activa de tipo Cancelación de Agenda de la empresa (sin distinguir mayúsculas de minúsculas)	Descripción de la causal de cancelación, tal como aparece en la plataforma
cancellation_observations	string (max 100)	Sí	Opcional	Observaciones adicionales de la cancelación

Formato de tipos de dato

• int: Número entero. Ejemplo: 1001.
• string (max N): Cadena de texto con longitud máxima de N caracteres.

Causales de cancelación

Las causales válidas son las que la empresa tiene registradas y activas en la plataforma R-Sales con el tipo Cancelación de Agenda. Se envía la descripción de la causal tal como aparece allí. La comparación no distingue mayúsculas de minúsculas, pero el resto del texto (acentos, espacios y signos) debe ser idéntico. La agenda cancelada conserva el texto exacto registrado en la plataforma en el campo cancellation_reason de Listar Agendas, igual que una cancelación hecha desde la plataforma.

---

Ejemplo de Solicitud

Aquí tienes un ejemplo de cómo debería quedar el cuerpo de la solicitud en formato JSON:

[
  {
    "code": 1001,
    "cancellation_reason": "CLIENTE NO DISPONIBLE",
    "cancellation_observations": "El cliente solicitó reprogramar la visita"
  },
  {
    "code": 1002,
    "cancellation_reason": "Dirección errónea"
  }
]

---

Ejemplo de Respuesta

200 - OK

{
    "statusCode": 200,
    "message": "Appointments cancelled successfully"
}

Comportamiento de cancelación

• Solo se cancelan las agendas que se encuentren en estado A (Asignada).
• La agenda cancelada queda en estado I con la causal en cancellation_reason (texto exacto registrado en la plataforma), las observaciones en cancellation_observations y la fecha de modificación (updated_at) del momento de la cancelación.
• La agenda cancelada sigue siendo consultable con Listar Agendas filtrando por state=I.

Status 400

{
    "statusCode": 400,
    "errors": [
        {
            "message": "Invalid JSON in request body"
        }
    ]
}

Status 415

{
    "statusCode": 415,
    "errors": [
        {
            "message": "Content-Type: application/json is required"
        }
    ]
}

Status 422

Errores globales (estructura del body)

Si el body no es un array:

{
    "statusCode": 422,
    "errors": [
        {
            "message": "Request body must be an array"
        }
    ]
}

Si el array está vacío:

{
    "statusCode": 422,
    "errors": [
        {
            "message": "Request body cannot be empty"
        }
    ]
}

Si excede el límite de 10,000 items:

{
    "statusCode": 422,
    "errors": [
        {
            "message": "Array exceeds maximum limit of 10000 items"
        }
    ]
}

Errores por item (validación de campos)

Los errores se agrupan por el índice del item en el array. Si algún item es inválido, no se cancela ninguna agenda:

{
    "statusCode": 422,
    "errors": [
        {
            "index": 0,
            "errors": [
                {
                    "field": "cancellation_reason",
                    "message": "Field is required"
                }
            ]
        },
        {
            "index": 2,
            "errors": [
                {
                    "field": "code",
                    "message": "Field must be a valid integer"
                }
            ]
        }
    ]
}

Errores por item (causal no registrada)

La causal de cada item se compara, sin distinguir mayúsculas de minúsculas, con las causales activas de tipo Cancelación de Agenda de la empresa. Cada item cuya causal no coincida se informa con su índice y la lista de causales válidas:

{
    "statusCode": 422,
    "errors": [
        {
            "index": 1,
            "errors": [
                {
                    "field": "cancellation_reason",
                    "message": "Value must be one of: CLIENTE NO DISPONIBLE, Dirección errónea, Incapacidad del funcionario"
                }
            ]
        }
    ]
}

Tipos de Errores de Validación por Campo

Errores de presencia y nulidad:

Error	Descripción
Field is required	El campo no fue enviado en el objeto (la clave no existe)
Field cannot be null or empty	El campo fue enviado con valor null o vacío y no acepta nulos
Unknown field	Se envió un campo que no existe en la configuración
Item must be an object	Un elemento del array no es un objeto JSON

Errores de tipo de dato:

Error	Descripción
Field must be of type integer	El valor de code no es un número entero
Field must be a valid integer	El texto enviado en code no representa un entero
Field must be a string	El valor no es una cadena de texto

Errores de rango:

Error	Descripción
Field must be greater than or equal to 1	El valor de code es menor que 1

Errores de longitud:

Error	Descripción
Field exceeds maximum length of 50 characters	La causal excede la longitud máxima permitida
Field exceeds maximum length of 100 characters	Las observaciones exceden la longitud máxima

Errores de valores permitidos:

Error	Descripción
Value must be one of: ...	La causal no coincide con la descripción de una causal activa de tipo Cancelación de Agenda de la empresa; el mensaje lista las causales válidas
No active cancellation reasons are configured for the company	La empresa no tiene causales activas de tipo Cancelación de Agenda; debe registrarlas en la plataforma

Status 423

{
    "statusCode": 423,
    "errors": [
        {
            "message": "Resource is locked and cannot be accessed."
        }
    ]
}

Recurso bloqueado

Este error ocurre cuando otra operación de cancelación de agendas con la misma Subscription-Key está en progreso. Espere a que la operación anterior finalice e intente nuevamente.

Status 500

Error de conexión a base de datos

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Error connecting to database"
        }
    ]
}

Error de operación en base de datos

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Database operation failed"
        }
    ]
}

Error en Redis

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Redis operation failed"
        }
    ]
}

Error en validaciones

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Unexpected error in the validations"
        }
    ]
}

Error inesperado

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Unexpected error"
        }
    ]
}

Error del Servidor

Estos errores indican problemas internos en el servidor, la base de datos o el servicio de cache. Si persisten, contacta al equipo de soporte.