Formato de requests y respuestas

JSON, el envelope de respuesta y las convenciones de datos de la API.

La API es REST sobre HTTPS y habla JSON en ambas direcciones: los bodies de request van con Content-Type: application/json y las respuestas vuelven en JSON. No hay soporte de XML ni de otros formatos.

Envelope de respuesta

Las respuestas exitosas siguen esta forma:

{
  "status": "success",
  "data": { "...": "el recurso o la lista pedida" }
}

• status — "success" en éxito.
• data — el payload: un objeto o un array según la operación.

Algunas operaciones legacy responden con otra forma (por ejemplo, solo status, o el recurso directo sin envelope). La referencia de la API muestra el esquema exacto de cada respuesta; ante la duda, esa es la fuente autoritativa.

Los errores tienen su propio contrato, con un campo code estable para hacer branching — está documentado en Códigos de error.

Convenciones de datos

Dato	Convención
Identificadores	ObjectId de MongoDB en string de 24 hex ("665f1c2e8b1a4c0012a3b4c5"), en el campo _id
Fechas	Strings ISO 8601 en UTC ("2026-07-30T14:25:00.000Z")
Coordenadas	Grados decimales, latitude y longitude numéricos

Paginación

Los endpoints de listado que paginan declaran sus parámetros (típicamente page y limit) en la referencia de la API. La paginación no es universal: los listados que no declaran parámetros de página devuelven el conjunto completo filtrado por tu cliente.

Compatibilidad

Podemos agregar campos nuevos a las respuestas sin previo aviso. Tu integración debe ignorar los campos que no conozca; no va a haber remociones ni cambios de tipo sin comunicación previa.