> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ugps.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

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

## 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.