Asignar Servicio

Endpoint

POST /api/v3/asignacion

Descripción

Genera el servicio en la central que aceptó la oferta, con los datos del solicitante y del vehículo. La oferta debe existir y haber sido aceptada por una central; al asignar, se crea el registro del servicio, sus tareas (origen y, si aplica, destino), la tarifa estimada y se notifica al técnico asignado.

Proceso

1. La oferta debe haber sido previamente aceptada por una central.
2. Se envían los datos del solicitante y del vehículo.
3. TSALVA crea el servicio en la central y lo deja listo para su ejecución.

Autenticación

Este endpoint usa autenticación HTTP Basic (autValidator). Consulta Autenticación para el detalle de errores 401 / 403.

Authorization: Basic <credentials>

Parámetros de Entrada

Body (JSON)

Campo	Tipo	Requerido	Descripción
uuid	string (UUID)	Sí	UUID de la oferta previamente aceptada.
codigoServicio	string	Sí	Número de autorización del servicio (se usa como identificador en la central).
riesgo	string	No	Placa o identificador del riesgo/vehículo. Se registra como licencia del vehículo.
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.
claseVehiculo	string	No	Clase del vehículo.
marcaVehiculo	string	No	Marca del vehículo.
tipoTransimisionVehiculo	string	No	Tipo de transmisión del vehículo. Nombre del campo tal cual lo espera la API.
observaciones	string	No	Observaciones del servicio. Si no está vacío, se registra como nota del servicio.
codigoSolicitud	string	No	Número de solicitud/movimiento asociado al servicio.
global	number	No	Identificador de ofertamiento global. Por defecto 0.
internal	number	No	Identificador de ofertamiento interno. Por defecto 0.

Nombre de campo exacto

El campo de transmisión del vehículo se llama tipoTransimisionVehiculo (así, con la grafía que espera la API). Envíalo con ese nombre exacto.

Ejemplo de Request

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "codigoServicio": "TSV202507030001",
  "codigoSolicitud": "SOL-0001",
  "riesgo": "ABC123",
  "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",
  "tipoTransimisionVehiculo": "Automática",
  "observaciones": "Cliente prefiere contacto vía WhatsApp"
}

Respuestas

Éxito (200 Correcto)

{
  "status": true,
  "msg": "SERVICIO HA SIDO ASIGNADO EXITOSAMENTE NOMBRE_DE_LA_CENTRAL"
}

Si el servicio con ese codigoServicio ya estaba registrado en la central, se actualiza la oferta y se responde:

{
  "status": true,
  "msg": "El servicio con número de autorización TSV202507030001 ya se encuentra registrado en la central NOMBRE_DE_LA_CENTRAL. La oferta ha sido actualizada correctamente."
}

Oferta o Central No Identificada (403 Prohibido)

Cuando la oferta no se encuentra (nota: el mensaje viene en el campo status):

{
  "status": "Lo sentimos, la oferta con identificador [123e4567-e89b-12d3-a456-426614174000] no fue encontrada en el ecosistema del Gestor TSALVA, no es posible procesar la asignación del servicio."
}

Cuando no se puede identificar la central que respondió la oferta:

{
  "status": false,
  "msg": "Lo sentimos, no fue posible identificar la central que respondió a las oferta, no es posible procesar la asignación del servicio."
}

Error de Validación (400 Solicitud Incorrecta)

Dirección de origen inválida o no procesable:

{
  "status": false,
  "msg": "La dirección de origen proporcionada no es válida o no se pudo procesar. Por favor verifique e intente nuevamente la asignación del servicio."
}

No fue posible generar el registro del servicio en la central:

{
  "status": false,
  "msg": "LO SENTIMOS NO FUE POSIBLE GENERAR EL REGISTRO DEL SERVICIO EN LA CENTRAL"
}

Error Interno (500 Error Interno del Servidor)

{
  "status": false,
  "msg": "OCURRIÓ UN ERROR AL PROCESAR LA ASIGNACIÓN DEL SERVICIO"
}

Ejemplos de Código

cURL

curl -X POST "[URL_API]/api/v3/asignacion" \
  --user "tu_usuario:tu_password" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "codigoServicio": "TSV202507030001",
    "riesgo": "ABC123",
    "primerNombre": "Carlos",
    "primerApellido": "Rodríguez",
    "telefonoSolicitante": "+57 300-123-4567"
  }'

JavaScript

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

  return await response.json();
};

// Uso
const resultado = await asignarServicio({
  uuid: '123e4567-e89b-12d3-a456-426614174000',
  codigoServicio: 'TSV202507030001',
  riesgo: 'ABC123',
  primerNombre: 'Carlos',
  primerApellido: 'Rodríguez',
  telefonoSolicitante: '+57 300-123-4567'
});

console.log(resultado.msg);

Python

import requests
from requests.auth import HTTPBasicAuth

data = {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "codigoServicio": "TSV202507030001",
    "riesgo": "ABC123",
    "primerNombre": "Carlos",
    "primerApellido": "Rodríguez",
    "telefonoSolicitante": "+57 300-123-4567"
}

response = requests.post(
    '[URL_API]/api/v3/asignacion',
    auth=HTTPBasicAuth('usuario', 'password'),
    json=data
)

print(response.json())

Flujo Oferta → Asignación

sequenceDiagram
    participant C as Cliente (Ofertante)
    participant API as TSALVA API
    participant Central
    participant WH as Webhook

    C->>API: 1. POST /api/v3/oferta
    API-->>C: 200 Oferta recibida
    API->>Central: Distribuir oferta a técnicos
    Central->>API: Técnico acepta la oferta
    API->>WH: 2. PUT webhook de aceptación
    WH-->>API: 200 recibido
    C->>API: 3. POST /api/v3/asignacion
    API->>Central: Crear servicio y notificar técnico
    API-->>C: 200 Servicio asignado

Validaciones Importantes

UUID y estado de la oferta

• La oferta debe existir para la credencial (mismo nit); de lo contrario se responde 403 con el mensaje en el campo status.
• Debe existir la central que aceptó la oferta.

Código de servicio

• codigoServicio se usa como número de autorización del servicio en la central.
• Si ya existe un servicio con ese número, la oferta se actualiza y no se duplica.

---

Siguiente paso

Después de asignar el servicio, comenzarás a recibir los webhooks de cambios de estado.