Asignación Directa de Servicio

Endpoint

POST /api/v2/asignacion-directa

Descripción

Permite crear un servicio completo y asignarlo directamente a una central específica, sin pasar por el proceso de ofertamiento. Esta funcionalidad es útil para servicios pre-acordados o cuando se conoce previamente qué central atenderá el servicio.

Características:

Creación instantánea sin proceso de ofertamiento
Asignación directa a central específica mediante DNI del prestador
Información completa del servicio y cliente en una sola petición
🔢 Generación automática de códigos de servicio y solicitud

Ventajas:

Menor tiempo de procesamiento
📅 Ideal para servicios programados
Control directo sobre la asignación

Autenticación

Authorization: Basic <credentials>

Parámetros de Entrada

Body (JSON)

Campos del Servicio

Campo	Tipo	Requerido	Descripción
`uuid`	`string` (UUID)	Sí	Identificador único para este servicio
`dniPrestador`	`string`	Sí	NIT o documento de la central prestadora
`dniGenerador`	`string`	No	Documento del usuario que genera el servicio
`tipoServicio`	`string`	Sí	Tipo de servicio (usar IDs de `/api/v2/types`)
`descripcionServicio`	`string`	Sí	Descripción detallada del servicio requerido

Ubicaciones

Campo	Tipo	Requerido	Descripción
`latitudOrigen`	`string`	Sí	Coordenada de latitud del punto de origen
`longitudOrigen`	`string`	Sí	Coordenada de longitud del punto de origen
`puntoReferenciaOrigen`	`string`	No	Referencia del lugar de origen
`direccionOrigen`	`string`	Sí	Dirección completa del punto de origen
`latitudDestino`	`string`	No	Coordenada de latitud del punto de destino
`longitudDestino`	`string`	No	Coordenada de longitud del punto de destino
`puntoReferenciaDestino`	`string`	No	Referencia del lugar de destino
`direccionDestino`	`string`	No	Dirección completa del punto de destino
`ciudad`	`string`	Sí	Ciudad donde se prestará el servicio
`departamento`	`string`	Sí	Departamento donde se prestará el servicio

Programación

Campo	Tipo	Requerido	Descripción
`fechaCita`	`string`	No	Fecha programada para el servicio
`horaCita`	`string`	No	Hora programada para el servicio
`observaciones`	`string`	No	Observaciones adicionales sobre el servicio

Códigos y Cliente

Campo	Tipo	Requerido	Descripción
`codigoServicio`	`string`	No	Código único del servicio (se genera automáticamente si no se envía)
`codigoSolicitud`	`string`	No	Código adicional para servicios con múltiples consecutivos
`riesgo`	`string`	No	Número de póliza o identificador del riesgo

Datos del Cliente

Campo	Tipo	Requerido	Descripción
`primerNombre`	`string`	No	Primer nombre del solicitante
`segundoNombre`	`string`	No	Segundo nombre del solicitante
`primerApellido`	`string`	No	Primer apellido del solicitante
`segundoApellido`	`string`	No	Segundo apellido del solicitante
`telefonoSolicitante`	`string`	No	Teléfono principal del solicitante
`telefonoSolicitante2`	`string`	No	Teléfono alternativo del solicitante

Datos del Vehículo

Campo	Tipo	Requerido	Descripción
`claseVehiculo`	`string`	No	Clase o tipo del vehículo
`marcaVehiculo`	`string`	No	Marca del vehículo
`tipoTransmisionVehiculo`	`string`	No	Tipo de transmisión del vehículo

Ejemplo de Request

json

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "dniPrestador": "900123456",
  "dniGenerador": "98765432",
  "tipoServicio": "1",
  "descripcionServicio": "Grúa liviana para vehículo averiado en autopista",
  
  "latitudOrigen": "6.2442",
  "longitudOrigen": "-75.5812",
  "puntoReferenciaOrigen": "Autopista Norte Km 15, frente a estación de servicio",
  "direccionOrigen": "Autopista Norte Km 15",
  "latitudDestino": "6.2518",
  "longitudDestino": "-75.5636",
  "puntoReferenciaDestino": "Taller mecánico Los Ángeles",
  "direccionDestino": "Calle 78B #69-240",
  "ciudad": "Medellín",
  "departamento": "Antioquia",
  
  "fechaCita": "2025-07-03",
  "horaCita": "16:30",
  "observaciones": "Vehículo en carril de emergencia, requiere atención urgente",
  
  "codigoServicio": "GOT00356",
  "codigoSolicitud": "ABO0036",
  "riesgo": "POL-2025-001234",
  
  "primerNombre": "Carlos",
  "segundoNombre": "Andrés",
  "primerApellido": "Rodríguez",
  "segundoApellido": "García",
  "telefonoSolicitante": "+57 300-123-4567",
  "telefonoSolicitante2": "+57 301-234-5678",
  
  "claseVehiculo": "Automóvil",
  "marcaVehiculo": "Toyota",
  "tipoTransmisionVehiculo": "Automática"
}

Respuestas

Éxito (200 Correcto)

json

{
  "status": true,
  "msg": "El servicio 'GOT00356' ha sido asignado exitosamente a la central Prestadora Norte SAS",
  "codigoServicio": "GOT00356",
  "codigoSolicitud": "ABO0036"
}

Error de Restricción (403 Forbidden)

json

{
  "status": false,
  "msg": "No se cumple la condición de cobertura geográfica para la asignación"
}

Restricciones comunes:

Central no tiene cobertura en la ubicación
Central no está activa o disponible
Tipo de servicio no ofrecido por la central
Horario fuera del rango de operación

Error de Validación (400 Solicitud Incorrecta)

json

{
  "status": false,
  "msg": "DNI del prestador es requerido"
}

Errores comunes:

DNI del prestador faltante o inválido
UUID duplicado
Coordenadas en formato incorrecto
Tipo de servicio no válido

Ejemplos de Código

cURL

bash

curl -X POST "[URL_API]/api/v2/asignacion-directa" \
  --user "tu_usuario:tu_password" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "dniPrestador": "900123456",
    "tipoServicio": "1",
    "descripcionServicio": "Grúa liviana urgente",
    "latitudOrigen": "6.2442",
    "longitudOrigen": "-75.5812",
    "direccionOrigen": "Autopista Norte Km 15",
    "ciudad": "Medellín",
    "departamento": "Antioquia"
  }'

JavaScript

javascript

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

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

// Uso
try {
  const resultado = await crearAsignacionDirecta({
    uuid: '123e4567-e89b-12d3-a456-426614174000',
    dniPrestador: '900123456',
    tipoServicio: '1',
    descripcionServicio: 'Grúa liviana para automóvil',
    latitudOrigen: '6.2442',
    longitudOrigen: '-75.5812',
    direccionOrigen: 'Autopista Norte Km 15',
    ciudad: 'Medellín',
    departamento: 'Antioquia',
    primerNombre: 'Carlos',
    primerApellido: 'Rodríguez',
    telefonoSolicitante: '+57 300-123-4567'
  });
  
  console.log('Servicio asignado:', resultado.codigoServicio);
} catch (error) {
  console.error('Error:', error.message);
}

Python

python

import requests
from requests.auth import HTTPBasicAuth

def crear_asignacion_directa(datos_servicio):
    response = requests.post(
        '[URL_API]/api/v2/asignacion-directa',
        auth=HTTPBasicAuth('usuario', 'password'),
        json=datos_servicio
    )
    
    result = response.json()
    
    if not result['status']:
        raise Exception(result['msg'])
    
    return result

# Uso
try:
    datos = {
        'uuid': '123e4567-e89b-12d3-a456-426614174000',
        'dniPrestador': '900123456',
        'tipoServicio': '1',
        'descripcionServicio': 'Grúa liviana urgente',
        'latitudOrigen': '6.2442',
        'longitudOrigen': '-75.5812',
        'direccionOrigen': 'Autopista Norte Km 15',
        'ciudad': 'Medellín',
        'departamento': 'Antioquia'
    }
    
    resultado = crear_asignacion_directa(datos)
    print(f"Servicio creado: {resultado['codigoServicio']}")
    
except Exception as e:
    print(f"Error: {e}")

Cuándo Usar Asignación Directa

Casos Recomendados

Servicios programados: Citas médicas, traslados planificados
Acuerdos preestablecidos: Central específica para ciertos clientes
Emergencias dirigidas: Cuando se conoce la central más cercana
Servicios corporativos: Contratos con prestadores específicos

No Recomendado Para

Servicios urgentes sin central definida: Mejor usar ofertamiento
Cobertura incierta: Cuando no sabes si la central atiende la zona
Comparación de precios: El ofertamiento permite mejores tarifas

Flujo de Asignación Directa

mermaid

sequenceDiagram
    participant Cliente
    participant API as TSALVA API
    participant Central as Central Específica
    participant Webhook as Cliente Webhook

    Cliente->>API: POST /api/v2/asignacion-directa
    Note over Cliente,API: Todos los datos en una petición
    
    API->>Central: Asignar servicio directamente
    API-->>Cliente: Confirmación con códigos
    
    Central->>API: Aceptar/rechazar servicio
    
    opt Si central acepta
        API->>Webhook: Webhook de aceptación
        Central->>API: Cambios de estado
        API->>Webhook: Webhooks de progreso
    end
    
    opt Si central rechaza
        API->>Webhook: Webhook de rechazo
        Note over Cliente,Central: Servicio no se ejecuta
    end

Validaciones y Restricciones

Validación de DNI Prestador

javascript

async function validarPrestador(dniPrestador, ubicacion) {
  // Verificar que el prestador existe
  const prestador = await obtenerPrestador(dniPrestador);
  if (!prestador) {
    throw new Error('Prestador no encontrado');
  }
  
  // Verificar cobertura geográfica
  const tieneCobertura = await verificarCobertura(
    prestador.id, 
    ubicacion.ciudad, 
    ubicacion.departamento
  );
  
  if (!tieneCobertura) {
    throw new Error('Prestador no tiene cobertura en la ubicación');
  }
  
  return prestador;
}

Generación Automática de Códigos

Si no proporcionas codigoServicio, el sistema genera uno automáticamente:

Formato: [PREFIJO][FECHA][CONSECUTIVO]
Ejemplo: TSV20250703001

Comparación: Asignación Directa vs Ofertamiento

Aspecto	Asignación Directa	Ofertamiento
Velocidad	Inmediata	Espera aceptación
Control	Central específica	Distribución automática
Tarifas	Tarifa del prestador	Competencia de precios
Disponibilidad	Depende del prestador	Múltiples opciones
Complejidad	Una sola petición	Múltiples pasos

Recomendación

Usa asignación directa cuando tengas acuerdos preestablecidos con centrales específicas o para servicios programados donde conoces previamente qué prestador debe atender.

Importante

La central puede rechazar la asignación directa si no tiene capacidad o cobertura. Siempre maneja el caso de rechazo en tu lógica de negocio.

Asignación Directa de Servicio ​

Endpoint ​

Descripción ​

Características: ​

Ventajas: ​

Autenticación ​

Parámetros de Entrada ​

Body (JSON) ​

Campos del Servicio ​

Ubicaciones ​

Programación ​

Códigos y Cliente ​

Datos del Cliente ​

Datos del Vehículo ​

Ejemplo de Request ​

Respuestas ​

Éxito (200 Correcto) ​

Error de Restricción (403 Forbidden) ​

Error de Validación (400 Solicitud Incorrecta) ​

Ejemplos de Código ​

cURL ​

JavaScript ​

Python ​

Cuándo Usar Asignación Directa ​

Casos Recomendados ​

No Recomendado Para ​

Flujo de Asignación Directa ​

Validaciones y Restricciones ​

Validación de DNI Prestador ​

Generación Automática de Códigos ​

Comparación: Asignación Directa vs Ofertamiento ​

Asignación Directa de Servicio

Endpoint

Descripción

Características:

Ventajas:

Autenticación

Parámetros de Entrada

Body (JSON)

Campos del Servicio

Ubicaciones

Programación

Códigos y Cliente

Datos del Cliente

Datos del Vehículo

Ejemplo de Request

Respuestas

Éxito (200 Correcto)

Error de Restricción (403 Forbidden)

Error de Validación (400 Solicitud Incorrecta)

Ejemplos de Código

cURL

JavaScript

Python

Cuándo Usar Asignación Directa

Casos Recomendados

No Recomendado Para

Flujo de Asignación Directa

Validaciones y Restricciones

Validación de DNI Prestador

Generación Automática de Códigos

Comparación: Asignación Directa vs Ofertamiento