# MLS Cielo: especificación del archivo (v1, 16 de octubre de 2026)

Mandas un archivo con **las propiedades que tú o tu empresa representan**. No se aceptan propiedades copiadas de otros portales ni de terceros. Si la propiedad no es tuya para publicarla, no va en el archivo.

## Cómo se envía

```
curl -X POST "https://cieloinmuebles.com/api/ci/mls/import?dry_run=1" \
  -H "Authorization: Bearer cmls_TU_LLAVE" \
  -H "Content-Type: text/csv" \
  --data-binary @propiedades.csv
```

- `?dry_run=1` revisa todo y no guarda nada. Quítalo para publicar.
- Formatos: CSV (coma, punto y coma o tabulador), JSON (`[...]` o `{"listings":[...]}`) y XML sencillo (`<propiedades><propiedad>...</propiedad></propiedades>`).
- Máximo 2,000 filas y 5 MB por envío. Máximo 30 envíos por hora.
- La llave te la da Cielo Inmuebles al abrir tu prueba de 7 días. Tu llave es tuya: no la compartas.
- Mandar otra vez la misma `referencia` **actualiza** la propiedad; no la duplica.
- Las filas con errores se te devuelven con el motivo y se saltan; las buenas sí se publican.

## Campos

| Campo (español / inglés) | Obligatorio | Notas |
|---|---|---|
| `referencia` / `ref`, `id`, `codigo` | sí | Tu código interno. Es lo que identifica la propiedad cuando la actualizas. |
| `tipo` / `type` | sí | casa, departamento, condominio, villa, terreno, lote, rancho, finca, local, oficina, bodega, edificio... |
| `ciudad` / `city` | sí | Ciudad o municipio. |
| `pais` / `country` | no | MX, CR, PA, GT, SV, HN, NI, EC. Si lo omites se usa el país de tu cuenta. |
| `provincia` / `state` | no | Provincia, departamento o estado. |
| `zona` / `neighborhood`, `colonia`, `proyecto` | no | Colonia, barrio, desarrollo o proyecto. |
| `titulo` / `title` | no | Si falta, lo armamos ("Casa en venta en ..."). |
| `descripcion` / `description` | no | Teléfonos, correos y enlaces de WhatsApp se reemplazan: los compradores te escriben por el formulario del sitio. |
| `precio` / `price` | no | Solo número. Sin precio se muestra "Precio a consultar". |
| `moneda` / `currency` | no | USD (por defecto) o MXN. Otras monedas, convierte a USD. |
| `recamaras`, `banos`, `construccion_m2`, `terreno_m2` | no | Números. |
| `vista_mar` / `ocean_view` | no | si / no. |
| `latitud`, `longitud` / `lat`, `lng` | no | Las dos o ninguna. |
| `fotos` / `photos` | no | Direcciones `https://` separadas por `|`. Hasta 30. |
| `url` / `source_url` | no | El anuncio original en tu sitio. Solo se conserva si su dominio está en los dominios permitidos de tu cuenta. |
| `estatus` / `status` | no | activo (por defecto), vendido, inactivo. Vendido o inactivo oculta la propiedad; nunca se borra. |
| `coop`, `coop_pct`, `nota_coop` | no | `coop`=si abre la propiedad a co-corretaje; `coop_pct` es el porcentaje (0 a 100) de tus honorarios que ofreces a la inmobiliaria que traiga al comprador. |

## Co-corretaje

- El porcentaje **no** aparece en ninguna página pública. Solo lo ven los miembros de MLS Cielo, en `GET /api/ci/mls/listings`.
- El acuerdo es entre las dos inmobiliarias. Cielo Inmuebles no es parte de ese acuerdo ni recibe nada de él.

## Reglas

1. Solo propiedades que representas. Si un dueño pide que se retire una, la retiramos el mismo día hábil.
2. Una propiedad ya reclamada por su dueño en Cielo Inmuebles no se modifica por archivo.
3. Etiquetas pagadas (Premier, Destacada) no se tocan por archivo.
4. Alquileres: todavía no. Solo ventas en esta versión.
5. Si tu prueba termina o tu cuenta se pausa, el archivo deja de aceptarse; tus propiedades publicadas no se borran.

---

## English summary

POST a CSV, JSON or simple XML file of the listings you represent to `/api/ci/mls/import` with `Authorization: Bearer cmls_...`. Add `?dry_run=1` to validate without saving. Required per row: `ref`, `type`, `city`. Prices in USD or MXN. Re-sending a `ref` updates it. Co-brokerage fee shares are private to members. Sales only in v1.