Crear Oferta de Servicio

Endpoint

POST /api/v2/oferta

Descripción

Crea una nueva oferta de servicio en el sistema TSALVA. La oferta será distribuida automáticamente a las centrales registradas que tengan cobertura en la ubicación especificada.

Funcionalidad:

• Registra una nueva solicitud de servicio
• Distribuye automáticamente a centrales con cobertura
• Permite recibir notificaciones de aceptación mediante webhook
• Valida coordenadas geográficas y disponibilidad de centrales

Autenticación

Authorization: Basic <credentials>

Parámetros de Entrada

Headers

Content-Type: application/json
Authorization: Basic <credentials>

Body (JSON)

Campo	Tipo	Requerido	Descripción
uuid	string (UUID)	Sí	Identificador único para la oferta de servicio
ciudad	string	Sí	Ciudad donde se solicita el servicio
departamento	string	Sí	Departamento o estado donde se solicita el servicio
latitudOrigen	number	Sí	Coordenada de latitud del punto de origen en formato decimal
longitudOrigen	number	Sí	Coordenada de longitud del punto de origen en formato decimal
direccionOrigen	string	Sí	Dirección completa del punto de origen
tipoServicio	string	Sí	Tipo de servicio solicitado (usar IDs de /api/v2/types)
descripcionServicio	string	Sí	Descripción detallada del servicio requerido
puntoReferenciaOrigen	string	No	Referencia del lugar de origen (ej. "Frente al centro comercial")
latitudDestino	number	No	Coordenada de latitud del punto de destino
longitudDestino	number	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
fechaCita	string (date)	No	Fecha programada (YYYY-MM-DD)
horaCita	string	No	Hora programada (HH:MM en formato 24h)
observaciones	string	No	Comentarios adicionales o instrucciones especiales

Ejemplo de Request

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "ciudad": "Medellín",
  "departamento": "Antioquia",
  "latitudOrigen": 6.2442,
  "longitudOrigen": -75.5812,
  "puntoReferenciaOrigen": "Frente al centro comercial El Tesoro",
  "direccionOrigen": "Carrera 25A #1A Sur-45",
  "latitudDestino": 6.2518,
  "longitudDestino": -75.5636,
  "puntoReferenciaDestino": "Hospital Pablo Tobón Uribe",
  "direccionDestino": "Calle 78B #69-240",
  "fechaCita": "2025-07-03",
  "horaCita": "14:30",
  "observaciones": "Vehículo con falla mecánica, requiere grúa especializada",
  "descripcionServicio": "Grúa liviana para traslado de automóvil averiado",
  "tipoServicio": "1"
}

Respuestas

✅ Éxito (200 Correcto)

{
  "status": true,
  "msg": "Se ha creado la oferta exitosamente"
}

❌ Error de Validación (400 Solicitud Incorrecta)

{
  "status": false,
  "msg": "UUID es requerido"
}

Errores comunes:

• UUID faltante o formato inválido
• Coordenadas en formato incorrecto
• Tipo de servicio no válido
• Ciudad/departamento no registrados

Error Interno (500 Error Interno del Servidor)

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

Webhook de Aceptación

TSALVA enviará un webhook cuando una central acepte la oferta.

Webhook Request (desde TSALVA hacia tu servidor)

PUT {webhook_url}
Content-Type: application/json

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "dniGestor": "98765432",
  "dniPrestador": "900123456",
  "nombrePrestador": "Central Norte SAS",
  "telefonoCentral": "+57 4 123-4567",
  "latitudTecnico": "6.2400",
  "longitudTecnico": "-75.5800",
  "identificadorTecnico": "TEC001",
  "dniTecnico": "12345678",
  "telefonoTecnico": "+57 300-123-4567",
  "tarifaEstimadaServicio": "85000",
  "tiempoLlegadaSitio": "25"
}

Tu respuesta esperada

{
  "received": true
}

Código de estado: 200 Correcto

Ejemplos de Código

cURL

curl -X POST "[URL_API]/api/v2/oferta" \
  --user "tu_usuario:tu_password" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "ciudad": "Medellín",
    "departamento": "Antioquia",
    "latitudOrigen": 6.2442,
    "longitudOrigen": -75.5812,
    "direccionOrigen": "Carrera 25A #1A Sur-45",
    "tipoServicio": "1",
    "descripcionServicio": "Grúa liviana para automóvil averiado"
  }'

JavaScript

const response = await fetch('[URL_API]/api/v2/oferta', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${btoa('usuario:password')}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    uuid: '123e4567-e89b-12d3-a456-426614174000',
    ciudad: 'Medellín',
    departamento: 'Antioquia',
    latitudOrigen: 6.2442,
    longitudOrigen: -75.5812,
    direccionOrigen: 'Carrera 25A #1A Sur-45',
    tipoServicio: '1',
    descripcionServicio: 'Grúa liviana para automóvil averiado'
  })
});

const result = await response.json();
console.log(result);

Python

import requests
from requests.auth import HTTPBasicAuth

data = {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "ciudad": "Medellín",
    "departamento": "Antioquia",
    "latitudOrigen": 6.2442,
    "longitudOrigen": -75.5812,
    "direccionOrigen": "Carrera 25A #1A Sur-45",
    "tipoServicio": "1",
    "descripcionServicio": "Grúa liviana para automóvil averiado"
}

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

result = response.json()
print(result)

Notas Importantes

🆔 UUID único

• El UUID debe ser único para cada oferta
• Se recomienda usar UUID v4
• No se pueden reutilizar UUIDs de ofertas anteriores

🌍 Coordenadas

• Formato decimal (WGS84)
• Latitud: -90 a 90
• Longitud: -180 a 180
• Precisión recomendada: 6 decimales

📞 Webhook URL

• Debe ser accesible públicamente (HTTPS recomendado)
• Timeout: 30 segundos
• TSALVA reintentará hasta 3 veces si no responde

Tipos de Servicio

• Consultar tipos disponibles en GET /api/v2/types
• Algunos tipos requieren destino obligatorio
• Otros solo requieren punto de origen

Flujo Siguiente

Después de crear una oferta exitosa:

1. Esperar webhook de aceptación
2. Asignar detalles con POST /api/v2/asignacion
3. Recibir webhooks de cambios de estado

---

Consejo

Usa coordenadas precisas para mejor cobertura de centrales. Una ubicación exacta aumenta las posibilidades de que una central cercana acepte la oferta.

Importante

Una vez creada la oferta, no se puede modificar. Para cambios, debes cancelar y crear una nueva oferta.