Agregar Dirección Adicional

Endpoint

POST /api/v2/add-address

Descripción

Permite añadir una nueva dirección o punto de parada dentro de un servicio ya asignado a una central. Útil para servicios que requieren múltiples paradas o cuando se necesita modificar la ruta durante la ejecución del servicio.

Casos de uso:

• Servicios con múltiples destinos
• Paradas adicionales durante el traslado
• Modificación de ruta por circunstancias especiales

Nota:

El servicio debe estar previamente asignado y activo.

Autenticación

Authorization: Basic <credentials>

Parámetros de Entrada

Body (JSON)

Campo	Tipo	Requerido	Descripción
uuid	string	Sí	UUID del servicio al que se agregará la nueva dirección
latitudDireccion	string	Sí	Coordenada de latitud de la nueva dirección
longitudDireccion	string	Sí	Coordenada de longitud de la nueva dirección
direccion	string	Sí	Dirección completa del nuevo punto
puntoReferenciaDireccion	string	No	Punto de referencia o descripción del lugar
observaciones	string	No	Instrucciones especiales para esta dirección adicional

Ejemplo de Request

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "latitudDireccion": "6.2500",
  "longitudDireccion": "-75.5700",
  "puntoReferenciaDireccion": "Estación de gasolina Texaco",
  "direccion": "Carrera 65 #45-30",
  "observaciones": "Parada adicional para cargar combustible antes del destino final"
}

Respuestas

Éxito (200 Correcto)

{
  "status": true,
  "msg": "Nueva dirección agregada exitosamente al servicio"
}

Error de Validación (400 Solicitud Incorrecta)

{
  "status": false,
  "msg": "Servicio no encontrado o no está activo"
}

Error Interno (500 Error Interno del Servidor)

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

Ejemplos de Código

cURL

curl -X POST "[URL_API]/api/v2/add-address" \
  --user "tu_usuario:tu_password" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "latitudDireccion": "6.2500",
    "longitudDireccion": "-75.5700",
    "direccion": "Carrera 65 #45-30",
    "observaciones": "Parada adicional para combustible"
  }'

JavaScript

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

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

// Uso
try {
  await agregarDireccion('123e4567-e89b-12d3-a456-426614174000', {
    latitudDireccion: '6.2500',
    longitudDireccion: '-75.5700',
    direccion: 'Carrera 65 #45-30',
    puntoReferenciaDireccion: 'Estación Texaco',
    observaciones: 'Parada para combustible'
  });
  
  console.log('Dirección agregada exitosamente');
} catch (error) {
  console.error('Error:', error.message);
}

Casos de Uso Típicos

Servicios de Carga

// Agregar múltiples puntos de recogida
const puntosRecogida = [
  {
    latitudDireccion: '6.2500',
    longitudDireccion: '-75.5700',
    direccion: 'Bodega Norte - Carrera 65 #45-30',
    observaciones: 'Recoger mercancía #001'
  },
  {
    latitudDireccion: '6.2600',
    longitudDireccion: '-75.5800',
    direccion: 'Bodega Sur - Calle 50 #30-15',
    observaciones: 'Recoger mercancía #002'
  }
];

for (const punto of puntosRecogida) {
  await agregarDireccion(servicioUuid, punto);
}

Servicios Médicos

// Agregar parada en farmacia
await agregarDireccion(servicioUuid, {
  latitudDireccion: '6.2450',
  longitudDireccion: '-75.5750',
  direccion: 'Farmacia Cruz Verde - Calle 70 #45-20',
  puntoReferenciaDireccion: 'Al lado del banco',
  observaciones: 'Recoger medicamentos según prescripción médica'
});

Servicios de Emergencia

// Agregar parada de emergencia
await agregarDireccion(servicioUuid, {
  latitudDireccion: '6.2480',
  longitudDireccion: '-75.5720',
  direccion: 'Estación de Servicio Shell',
  observaciones: 'Parada de emergencia - combustible agotado'
});

Limitaciones y Consideraciones

Estados Válidos

Solo se pueden agregar direcciones cuando el servicio está en estos estados:

• ACEPTADO
• EN_CAMINO
• EN_SITIO

Validaciones

• Las coordenadas deben estar en formato decimal
• La dirección debe ser específica y clara
• No se pueden agregar direcciones a servicios completados o cancelados

Notificaciones

Al agregar una dirección:

• La central asignada recibe notificación inmediata
• El técnico es informado del cambio en la ruta
• Se puede generar webhook de actualización

---

Recomendación

Agrega direcciones adicionales lo antes posible para dar tiempo al técnico de planificar la ruta óptima.

Importante

Algunas centrales pueden cobrar tarifas adicionales por paradas extra. Consulta las condiciones específicas con cada prestador.