Cancelar Servicio

Endpoint

POST /api/v2/cancelacion

Descripción

Permite cancelar un servicio que ya ha sido asignado a una central. La cancelación puede realizarse en cualquier estado del servicio antes de su finalización.

Casos de uso:

• Cancelación por parte del cliente
• Cancelación por circunstancias imprevistas
• Cancelación por fuerza mayor

Autenticación

Authorization: Basic <credentials>

Parámetros de Entrada

Body (JSON)

Campo	Tipo	Requerido	Descripción
idServicio	string	Sí	Identificador único del servicio a cancelar
razon	string	No	Motivo o razón de la cancelación del servicio
codigoSolicitud	string	❌*	Código adicional para servicios con múltiples consecutivos

*Requerido únicamente para servicios con múltiples consecutivos (2 o más códigos de seguimiento)

Ejemplo de Request

{
  "idServicio": "TSV202507030001",
  "razon": "Cliente solucionó el problema por cuenta propia",
  "codigoSolicitud": "MOV01"
}

Ejemplo Básico (servicio simple)

{
  "idServicio": "TSV202507030001",
  "razon": "Cliente canceló el servicio"
}

Respuestas

Éxito (200 Correcto)

{
  "status": true,
  "msg": "Servicio cancelado exitosamente y notificación enviada a la central asignada"
}

Error de Validación (400 Solicitud Incorrecta)

{
  "status": false,
  "msg": "Servicio no encontrado o ya ha sido finalizado"
}

Errores comunes:

• ID de servicio no existe
• Servicio ya completado o cancelado
• Código de solicitud requerido pero no proporcionado
• Servicio no asignado a ninguna central

Error Interno (500 Error Interno del Servidor)

{
  "status": false,
  "msg": "Ha ocurrido un error interno del servidor, por favor intenta más tarde"
}

Estados que Permiten Cancelación

Estado	Se puede cancelar	Descripción
Aceptado	Sí	Central aceptó pero técnico no asignado
Técnico asignado	Sí	Técnico asignado pero no en camino
En camino	Sí	Técnico en camino al sitio
En sitio	Sí	Técnico llegó al lugar
En proceso	No	Servicio en ejecución
Completado	No	Servicio finalizado exitosamente
Cancelado	No	Ya cancelado anteriormente

Ejemplos de Código

cURL

# Cancelación simple
curl -X POST "[URL_API]/api/v2/cancelacion" \
  --user "tu_usuario:tu_password" \
  -H "Content-Type: application/json" \
  -d '{
    "idServicio": "TSV202507030001",
    "razon": "Cliente canceló el servicio"
  }'

# Cancelación con código de solicitud
curl -X POST "[URL_API]/api/v2/cancelacion" \
  --user "tu_usuario:tu_password" \
  -H "Content-Type: application/json" \
  -d '{
    "idServicio": "TSV202507030001",
    "razon": "Cambio de ubicación del cliente",
    "codigoSolicitud": "MOV01"
  }'

JavaScript

const cancelarServicio = async (idServicio, razon, codigoSolicitud = null) => {
  const body = {
    idServicio,
    razon
  };
  
  if (codigoSolicitud) {
    body.codigoSolicitud = codigoSolicitud;
  }

  const response = await fetch('[URL_API]/api/v2/cancelacion', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${btoa('usuario:password')}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  });

  const result = await response.json();
  
  if (!result.status) {
    throw new Error(result.msg);
  }
  
  return result;
};

// Ejemplos de uso
try {
  // Cancelación simple
  await cancelarServicio(
    'TSV202507030001', 
    'Cliente solucionó el problema'
  );
  
  // Cancelación con código adicional
  await cancelarServicio(
    'TSV202507030001', 
    'Cambio de ubicación', 
    'MOV01'
  );
  
  console.log('Servicio cancelado exitosamente');
} catch (error) {
  console.error('Error al cancelar:', error.message);
}

Python

import requests
from requests.auth import HTTPBasicAuth

def cancelar_servicio(id_servicio, razon, codigo_solicitud=None):
    url = '[URL_API]/api/v2/cancelacion'
    
    data = {
        'idServicio': id_servicio,
        'razon': razon
    }
    
    if codigo_solicitud:
        data['codigoSolicitud'] = codigo_solicitud
    
    response = requests.post(
        url,
        auth=HTTPBasicAuth('usuario', 'password'),
        json=data
    )
    
    result = response.json()
    
    if not result['status']:
        raise Exception(result['msg'])
    
    return result

# Ejemplos de uso
try:
    # Cancelación simple
    resultado = cancelar_servicio(
        'TSV202507030001',
        'Cliente canceló el servicio'
    )
    
    print(f"Éxito: {resultado['msg']}")
    
except Exception as error:
    print(f"Error: {error}")

Servicios con Múltiples Consecutivos

Para servicios que tienen múltiples códigos de seguimiento asociados, es necesario especificar el codigoSolicitud:

¿Cuándo usar codigoSolicitud?

flowchart TD
    A[¿Servicio tiene múltiples consecutivos?] --> B{¿2 o más códigos?}
    B -->|Sí| C[codigoSolicitud REQUERIDO]
    B -->|No| D[codigoSolicitud OPCIONAL]
    
    C --> E[Ejemplo: TSV001 + MOV01]
    D --> F[Ejemplo: Solo TSV001]

Ejemplo de servicio múltiple:

{
  "idServicio": "TSV202507030001",
  "codigoSolicitud": "MOV01",
  "razon": "Cancelación del movimiento específico MOV01"
}

Efectos de la Cancelación

Notificaciones Automáticas

• ✅ La central asignada recibe notificación inmediata
• ✅ El técnico es liberado para otros servicios
• ✅ Se genera webhook de cambio de estado

Estado Final

• El servicio queda marcado como Cancelado
• No se puede reactivar una vez cancelado
• Queda registro histórico de la cancelación

Razones Comunes de Cancelación

Razón	Descripción
Cliente solucionó el problema	Cliente resolvió por cuenta propia
Cambio de ubicación	Cliente se trasladó a otro lugar
Servicio ya no requerido	Cliente ya no necesita el servicio
Fuerza mayor	Circunstancias imprevistas
Error en la solicitud	Información incorrecta en la oferta

---

Importante

La cancelación es irreversible. Una vez cancelado un servicio, no se puede reactivar. Si necesitas el servicio nuevamente, debes crear una nueva oferta.

Buena Práctica

Siempre proporciona una razón clara para la cancelación. Esto ayuda a las centrales a entender el motivo y mejorar sus procesos.