Agregar Dirección Adicional

Endpoint

POST /api/v3/add-address

Descripción

Permite añadir una nueva dirección (tarea/parada) a un servicio ya asignado a una central. La dirección se agrega como una nueva tarea del servicio en la central.

Casos de uso:

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

Nota:

El servicio debe existir y estar asociado a una central que use app.tsalva.com como gestor de campo.

Autenticación

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

Authorization: Basic <credentials>

Parámetros de Entrada

Body (JSON)

Campo	Tipo	Requerido	Descripción
uuid	string	Sí	UUID del servicio/oferta al que se agregará la nueva dirección.
latitudDireccion	string	Sí*	Latitud de la nueva dirección.
longitudDireccion	string	Sí*	Longitud de la nueva dirección.
direccion	string	Sí*	Dirección textual. Se usa para geocodificar cuando no se envían coordenadas.
puntoReferenciaDireccion	string	No	Punto de referencia o instrucciones del lugar.
observaciones	string	No	Nota/observación que se registra en el servicio.

*Debe enviarse la ubicación como coordenadas (latitudDireccion/longitudDireccion) o como direccion. Si latitudDireccion viene vacía o nula se geocodifica a partir de direccion.

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)

{
  "status": true,
  "msg": "SE HA AGREGADO LA DIRECCIÓN AL SERVICIO",
  "codigoTarea": "<código base64 del servicio-tarea>"
}

codigoTarea es una cadena en Base64 que codifica serviceId-taskNumber-idTarea.

Falta el UUID (400)

{
  "status": false,
  "msg": "El campo 'uuid' es requerido"
}

Oferta no encontrada (403)

{
  "status": false,
  "msg": "NO FUE ENCONTRADA LA OFERTA BAJO ID DE SERVICIO #[<uuid>]"
}

Central no usa app.tsalva.com (403)

{
  "status": false,
  "msg": "LA CENTRAL CON NIT <nit>. NO USA app.tsalva.com COMO SU GESTOR DE CAMPO, NO ES POSIBLE AGREGAR UNA NUEVA DIRECCIÓN"
}

No se pudo obtener la dirección (400)

{
  "status": false,
  "msg": "NO FUE POSIBLE OBTENER LA INFORMACIÓN DE LA DIRECCIÓN, REVISE LA ESTRUCTURA DE LA COORDENADA, DEBE SER DE TIPO DECIMAL, EJEMPLO: 4.1234567, -74.1234567"
}

Servicio asociado no identificado (403)

{
  "status": false,
  "msg": "LO SENTIMOS NO PUDIMOS IDENTIFICAR EL SERVICIO ASOCIADO A LA OFERTA, POR FAVOR CONTACTE A SOPORTE TÉCNICO"
}

Dirección duplicada (400)

Cuando ya existe una tarea con la misma dirección y coordenadas:

{
  "status": false,
  "msg": "YA EXISTE UNA DIRECCIÓN CON LA MISMA INFORMACIÓN EN EL SERVICIO, POR FAVOR VERIFIQUE Y VUELVA A INTENTAR"
}

No se pudo agregar la dirección (501)

{
  "status": false,
  "msg": "LO SENTIMOS, OCURRIÓ UN ERROR DE NUESTRA PARTE Y NO PUDO AGREGARSE LA DIRECCIÓN AL SERVICIO"
}

Ejemplos de Código

cURL

curl -X POST "[URL_API]/api/v3/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/v3/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 {
  const resultado = 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('Código de tarea:', resultado.codigoTarea);
} catch (error) {
  console.error('Error:', error.message);
}

Python

import requests
from requests.auth import HTTPBasicAuth

def agregar_direccion(servicio_uuid, nueva_direccion):
    payload = {'uuid': servicio_uuid, **nueva_direccion}

    response = requests.post(
        '[URL_API]/api/v3/add-address',
        auth=HTTPBasicAuth('usuario', 'password'),
        json=payload
    )

    result = response.json()

    if not result['status']:
        raise Exception(result['msg'])

    return result

# Uso
try:
    resultado = agregar_direccion('123e4567-e89b-12d3-a456-426614174000', {
        'latitudDireccion': '6.2500',
        'longitudDireccion': '-75.5700',
        'direccion': 'Carrera 65 #45-30',
        'observaciones': 'Parada para combustible'
    })
    print("Código de tarea:", resultado['codigoTarea'])
except Exception as e:
    print(f"Error: {e}")

Comportamiento

Al agregar una dirección de forma exitosa:

• Se crea una nueva tarea en el servicio (numerada como la siguiente disponible).
• Si el servicio tiene proveedor asignado, se replica la tarea al proveedor.
• Se registra un evento de auditoría y, si se envían observaciones, se agrega una nota.
• La central recibe una notificación web de "NUEVA DIRECCIÓN AGREGADA".

---

Recomendación

Envía las coordenadas en formato decimal (por ejemplo 6.2500, -75.5700) para evitar errores de geocodificación.

Importante

No se puede agregar una dirección idéntica (misma dirección y coordenadas) a la de una tarea ya existente del servicio.