Notas de integracion

Estas notas recogen comportamientos reales de la API que no se deducen leyendo el contrato. Todas estan verificadas contra el ambiente de produccion desde una integracion en uso.

La disponibilidad del catalogo llega desactualizada

GET /external/tramos devuelve contadores de cupo (libres, librescoche, libresmoto) que no estan al dia. En una medicion del 28 de septiembre de 2026, para el tramo 474 y en el mismo instante:

Peticion	libres	librescoche
GET /external/tramo/474	22	22
GET /external/tramos	7	7

Quien lea el cupo del catalogo se va a equivocar

Los contadores del catalogo son orientativos. Para decidir si hay o no hay cupo en un tramo hay que consultarlo individualmente con GET /external/tramo/{tramo_id}, que si devuelve el dato vigente.

Esto matiza la recomendacion de cachear el catalogo cinco minutos: sirve para geometria, nombres y horarios, que cambian poco, pero no para disponibilidad.

Parametro de ruta, no query string

Varios endpoints identifican el recurso en la ruta. La forma con query string no falla de manera evidente: en algunos casos devuelve un error enganoso.

Endpoint	Forma correcta
Consultar placa	GET /external/placa/{placa}
Consultar vehiculo	GET /external/vehiculo/{vehiculo_id}
Consultar tramo	GET /external/tramo/{tramo_id}
Pagar reserva	PUT /external/reserva-pagar/{reserva_id}
Cancelar reserva	PUT /external/reserva-cancelar/{reserva_id}
Extender reserva	PUT /external/reserva-extender/{reserva_id}
Cerrar sancion	PUT /external/sancion-cerrar/{sancion_id}
Pagar sancion	PUT /external/sancion-pagar/{sancion_id}

Error enganoso en placas

GET /external/placa?placa=ABC123 responde La placa no existe aunque la placa si exista. Usar siempre GET /external/placa/ABC123.

GET con cuerpo JSON

GET /external/cliente-email lee el email del cuerpo JSON, no del query string. Enviarlo como parametro de consulta provoca un HTTP 500 en el servidor.

curl -X GET "https://api-dev.zonaparqueo.com/external/cliente-email" \
  -H "Authorization: Token ABC123:XYZ789" \
  -H "Content-Type: application/json" \
  -d '{"email": "cliente@ejemplo.com"}'

Cuerpo vs. query en /external/vehiculos

Al contrario que el anterior, GET /external/vehiculos si lee los filtros del query string. Enviarlos en el cuerpo hace que el servidor los ignore en silencio y devuelva una pagina global sin filtrar, con codigo 200.

Consecuencia real

Este comportamiento provoco en produccion que la placa de un ciudadano quedara vinculada a un vehiculo inactivo cualquiera. Enviar siempre cliente_id (y placa si aplica) como parametros de consulta, y verificar que las filas devueltas correspondan al cliente.

id no filtra el catalogo

GET /external/tramos?id=474 ignora el parametro en silencio y devuelve el catalogo completo, con codigo 200. No hay error ni aviso: la respuesta simplemente trae los cientos de tramos. Confirmado por el proveedor y medido el 28 de septiembre de 2026 (5 muestras): mediana de 10,25 s con el parametro frente a 10,55 s sin el, es decir, la misma peticion.

Para consultar un tramo puntual, cualquiera de estas dos formas sirve y tarda unas siete veces menos:

Peticion	Mediana
GET /external/tramo/474	1,36 s
GET /external/tramo?id=474	1,41 s
GET /external/tramos?id=474	10,25 s (el catalogo entero)

El nombre del endpoint de precios

La ruta es /external/tramo-precios-estacionar, en plural. La forma singular tramo-precio-estacionar devuelve HTTP 404.

Orden obligatorio al pagar una sancion

Una sancion abierta no se puede pagar: el servidor responde no se puede pagar porque no esta cerrada. Hay que cerrarla primero.

1. PUT /external/sancion-cerrar/{sancion_id}
2. PUT /external/sancion-pagar/{sancion_id}

Cerrar una sancion ya cerrada es inofensivo, asi que el paso 1 se puede ejecutar siempre.

tramos-cercanos ya funciona

GET /external/tramos-cercanos estuvo caido entre junio y septiembre de 2026, devolviendo HTTP 500 en todas las consultas por una columna activado ambigua en el WHERE de la consulta tramo LEFT JOIN horario. Ya opera con normalidad.

Verificado el 26 de septiembre de 2026: responde 200 y sus distancias coinciden al metro con un calculo de haversine independiente hecho sobre las coordenadas del propio catalogo (13 de 13), sin omitir ningun tramo activo dentro del radio.

Si tu integracion tiene un workaround que filtra el catalogo completo por distancia del lado del cliente, ya puedes retirarlo: es el camino mas lento (unos 10 s por consulta frente a 2,6 a 5,1 s del endpoint).

Horarios de operacion

Ni tramos-cercanos ni el catalogo aplican el horario de operacion. Para mostrar solo tramos operativos hay que filtrar del lado del consumidor por inicio_garantizado / fin_garantizado y activo_domingo, en hora local de Bogota (UTC-5, sin horario de verano). Los tramos sin horario definido se tratan como siempre abiertos.

Tiempos de respuesta

La API es lenta y conviene dimensionar los tiempos de espera del cliente en consecuencia. Medido el 28 de septiembre de 2026:

Endpoint	Tiempo
/external/tramos (catalogo, ~654 KB)	~10 s
/external/tramos-cercanos	2,6 a 5,1 s
/external/tramo/{id}	~1,4 s
/external/placa/{placa}	~2 s

El proveedor esta evaluando paginar el catalogo para bajar ese tiempo. Los endpoints que no aparecen en la tabla no se midieron.

Detalles menores

• El filtro de estado de /external/reservas se llama Estado, con E mayuscula.
• /external/reservas acepta tambien tramo_id: combinado con Estado=1 devuelve las placas actualmente parqueadas en ese tramo.
• En reserva-pagar, enviar_recibo: true hace que el sistema envie el recibo oficial por correo al cliente.
• minutos debe ser multiplo de 10 tanto al crear como al extender una reserva.

---

Origen de los datos de esta guia: mediciones propias contra api.zonaparqueo.com los dias 26 y 28 de septiembre de 2026 (5 muestras por endpoint), la respuesta del proveedor del 28 de septiembre al caso 26783728, y la integracion en produccion verificada contra los endpoints en uso.