Asignación Directa de Servicio

Endpoint

POST /api/v3/asignacion-directa

Descripción

Permite crear un servicio completo y asignarlo directamente a una central específica, sin pasar por el proceso de ofertamiento. 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 la central identificada por su NIT (dniPrestador).
Información completa del servicio y cliente en una sola petición.
La central debe tener habilitada la asignación directa (direct_assignment).

Requisito de la central

La central debe tener habilitada la asignación directa en app.tsalva.com. De lo contrario la petición es rechazada.

Autenticación

Este endpoint usa autenticación HTTP Basic (autValidator).

Authorization: Basic <credentials>

Parámetros de Entrada

Body (JSON)

Campos obligatorios

Campo	Tipo	Requerido	Descripción
`uuid`	`string`	Sí	Identificador único para este servicio. No puede haberse usado antes en otra asignación directa.
`tipoServicio`	`string`	Sí	Tipo de servicio (usar IDs de `/api/v3/types`).
`codigoServicio`	`string`	Sí	Código/número de autorización del servicio.
`dniPrestador`	`string`	Sí	NIT de la central prestadora a la que se asigna el servicio.

Ubicaciones

Campo	Tipo	Requerido	Descripción
`latitudOrigen`	`string`	Sí*	Latitud del punto de origen.
`longitudOrigen`	`string`	Sí*	Longitud del punto de origen.
`direccionOrigen`	`string`	Sí*	Dirección de origen. Se usa para geocodificar cuando no se envían coordenadas.
`puntoReferenciaOrigen`	`string`	No	Referencia del lugar de origen.
`latitudDestino`	`string`	No	Latitud del punto de destino.
`longitudDestino`	`string`	No	Longitud del punto de destino.
`direccionDestino`	`string`	No	Dirección de destino (se geocodifica si `latitudDestino` viene vacía).
`puntoReferenciaDestino`	`string`	No	Referencia del lugar de destino.
`ciudad`	`string`	No	Ciudad (informativa; la ciudad real se deriva de la geocodificación).
`departamento`	`string`	No	Departamento (informativo; se deriva de la geocodificación).

*Debe enviarse el origen como coordenadas (latitudOrigen/longitudOrigen) o como direccionOrigen. Si no se logra obtener información de origen se responde con error 400.

Programación

Campo	Tipo	Requerido	Descripción
`fechaCita`	`string`	No	Fecha de la cita. Si viene vacía o en el pasado se usa la fecha/hora actual. Acepta formatos `YYYY-MM-DD` o `DD/MM/YYYY`.
`horaCita`	`string`	No	Hora de la cita (`HH:mm`). Por defecto `00:00` si no se envía.
`observaciones`	`string`	No	Observaciones adicionales del servicio.
`timezone`	`string`	No	Zona horaria.

Códigos, generador y riesgo

Campo	Tipo	Requerido	Descripción
`codigoSolicitud`	`string`	No	Número de movimiento/solicitud. Si el integrador genera movimiento automáticamente y no se envía, se genera un consecutivo.
`dniGenerador`	`string`	No	Documento del generador del servicio. Por defecto el NIT del usuario autenticado.
`riesgo`	`string`	No	Número de póliza o identificador del riesgo (se guarda como placa/licencia del vehículo).

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 del vehículo (se recorta a 50 caracteres).
`marcaVehiculo`	`string`	No	Marca del vehículo.
`tipoTransimisionVehiculo`	`string`	No	Tipo de transmisión del vehículo.

Nombre exacto del campo

El campo de transmisión en el código es tipoTransimisionVehiculo (con esa ortografía). Envíalo exactamente así.

Ejemplo de Request

json

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "dniPrestador": "900123456",
  "dniGenerador": "98765432",
  "tipoServicio": "1",
  "codigoServicio": "GOT00356",
  "codigoSolicitud": "ABO0036",
  "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",

  "fechaCita": "2025-07-03",
  "horaCita": "16:30",
  "observaciones": "Vehículo en carril de emergencia, requiere atención urgente",
  "riesgo": "POL-2025-001234",

  "primerNombre": "Carlos",
  "segundoNombre": "Andrés",
  "primerApellido": "Rodríguez",
  "segundoApellido": "García",
  "telefonoSolicitante": "3001234567",
  "telefonoSolicitante2": "3012345678",

  "claseVehiculo": "Automóvil",
  "marcaVehiculo": "Toyota",
  "tipoTransimisionVehiculo": "Automática"
}

Respuestas

Éxito (200)

json

{
  "status": true,
  "msg": "EL SERVICIO DE GRÚA LIVIANA HA SIDO ASIGNADO EXITOSAMENTE A NOMBRE CENTRAL, CÓDIGO DE SERVICIO: GOT00356 - CÓDIGO DE SOLICITUD: ABO0036",
  "codigoServicio": "GOT00356",
  "codigoSolicitud": "ABO0036"
}

El fragmento - CÓDIGO DE SOLICITUD: ... solo aparece cuando existe un número de movimiento. codigoSolicitud en la respuesta corresponde al mov_number generado o recibido.

Campo obligatorio faltante (400)

Según el campo ausente, el mensaje será uno de:

json

{ "status": false, "msg": "NO SE RECIBIÓ EL CAMPO 'uuid', REQUERIDO PARA EJECUTAR LA ASIGNACIÓN DIRECTA DEL SERVICIO" }

json

{ "status": false, "msg": "NO SE RECIBIÓ EL CAMPO 'tipoServicio', REQUERIDO PARA EJECUTAR LA ASIGNACIÓN DIRECTA DEL SERVICIO" }

json

{ "status": false, "msg": "NO SE RECIBIÓ EL CAMPO 'codigoServicio', REQUERIDO PARA EJECUTAR LA ASIGNACIÓN DIRECTA DEL SERVICIO" }

json

{ "status": false, "msg": "NO SE RECIBIÓ EL CAMPO 'dniPrestador', REQUERIDO PARA EJECUTAR LA ASIGNACIÓN DIRECTA DEL SERVICIO" }

UUID ya utilizado (403)

json

{
  "status": true,
  "msg": "EL UUID DE ASIGNACIÓN DIRECTA '<uuid>' YA FUE UTILIZADO EN UNA ASIGNACIÓN PREVIA"
}

Central no encontrada (400)

json

{
  "status": false,
  "msg": "NO SE ENCONTRÓ LA CENTRAL BAJO NIT [<dniPrestador>]"
}

Central sin asignación directa habilitada (403)

json

{
  "status": false,
  "msg": "LA CENTRAL NOMBRE CENTRAL. NO TIENE HABILITADA LA ASIGNACIÓN DIRECTA EN APP.TSALVA.COM, NO ES POSIBLE ASIGNARLE ESTE SERVICIO."
}

No se pudo obtener el origen (400)

json

{
  "status": false,
  "msg": "NO SE PUDO OBTENER LA INFORMACIÓN DE LA DIRECCIÓN DE ORIGEN"
}

Servicio ya registrado en la central (403)

json

{
  "status": false,
  "msg": "LA CENTRAL NOMBRE CENTRAL YA TIENE REGISTRADO EL SERVICIO BAJO EL NÚMERO DE AUTORIZACIÓN <codigoServicio>"
}

Cuando el integrador genera movimiento y se envía codigoSolicitud:

json

{
  "status": false,
  "msg": "LA CENTRAL NOMBRE CENTRAL YA TIENE REGISTRADO EL SERVICIO BAJO EL NÚMERO DE AUTORIZACIÓN <codigoServicio> Y EL NÚMERO DE MOVIMIENTO <codigoSolicitud>"
}

Generador no encontrado (403)

json

{
  "status": false,
  "msg": "NO SE ENCONTRÓ EL GENERADOR <dniGenerador>"
}

Error al generar el servicio (500)

json

{
  "status": false,
  "msg": "ERROR AL GENERAR EL SERVICIO EN LA CENTRAL"
}

Error interno (500)

json

{
  "status": false,
  "msg": "ERROR AL PROCESAR LA ASIGNACIÓN DIRECTA",
  "error": "<detalle del error>"
}

Ejemplos de Código

cURL

bash

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

JavaScript

javascript

const crearAsignacionDirecta = async (datosServicio) => {
  const response = await fetch('[URL_API]/api/v3/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',
    codigoServicio: 'GOT00356',
    descripcionServicio: 'Grúa liviana para automóvil',
    latitudOrigen: '6.2442',
    longitudOrigen: '-75.5812',
    direccionOrigen: 'Autopista Norte Km 15',
    primerNombre: 'Carlos',
    primerApellido: 'Rodríguez',
    telefonoSolicitante: '3001234567'
  });

  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/v3/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',
        'codigoServicio': 'GOT00356',
        'descripcionServicio': 'Grúa liviana urgente',
        'latitudOrigen': '6.2442',
        'longitudOrigen': '-75.5812',
        'direccionOrigen': 'Autopista Norte Km 15'
    }

    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

Servicios programados: citas y traslados planificados.
Acuerdos preestablecidos: central específica para ciertos clientes.
Emergencias dirigidas: cuando se conoce la central que debe atender.
Servicios corporativos: contratos con prestadores específicos.

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. Consulta Tipos de Servicio para obtener los IDs válidos de tipoServicio.

Importante

El uuid no puede reutilizarse: si ya fue usado en una asignación directa previa la petición es rechazada.

Asignación Directa de Servicio ​

Endpoint ​

Descripción ​

Características: ​

Autenticación ​

Parámetros de Entrada ​

Body (JSON) ​

Campos obligatorios ​

Ubicaciones ​

Programación ​

Códigos, generador y riesgo ​

Datos del Cliente ​

Datos del Vehículo ​

Ejemplo de Request ​

Respuestas ​

Éxito (200) ​

Campo obligatorio faltante (400) ​

UUID ya utilizado (403) ​

Central no encontrada (400) ​

Central sin asignación directa habilitada (403) ​

No se pudo obtener el origen (400) ​

Servicio ya registrado en la central (403) ​

Generador no encontrado (403) ​

Error al generar el servicio (500) ​

Error interno (500) ​

Ejemplos de Código ​

cURL ​

JavaScript ​

Python ​

Cuándo Usar Asignación Directa ​

Asignación Directa de Servicio

Endpoint

Descripción

Características:

Autenticación

Parámetros de Entrada

Body (JSON)

Campos obligatorios

Ubicaciones

Programación

Códigos, generador y riesgo

Datos del Cliente

Datos del Vehículo

Ejemplo de Request

Respuestas

Éxito (200)

Campo obligatorio faltante (400)

UUID ya utilizado (403)

Central no encontrada (400)

Central sin asignación directa habilitada (403)

No se pudo obtener el origen (400)

Servicio ya registrado en la central (403)

Generador no encontrado (403)

Error al generar el servicio (500)

Error interno (500)

Ejemplos de Código

cURL

JavaScript

Python

Cuándo Usar Asignación Directa