Importación masiva

La importación sirve para meter una cartera en Skautik y mantenerla ahí. Un anuncio suelto es un POST a properties; cuatrocientos, refrescados cada noche, son esto.

Una transferencia

curl -sS -X POST "https://api.skautik.com/v1/api/imports?format=csv&mode=incremental" \
  -H "Authorization: Bearer $SKAUTIK_API_KEY" \
  -H "Idempotency-Key: 6f1c2a7e-4d90-4a1b-9f33-0c2f5b8e77aa" \
  -F "file=@listings.csv"

La respuesta es una pasada que puedes consultar:

{
  "data": {
    "id": "imp_3d9b7e2145",
    "format": "csv",
    "mode": "incremental",
    "status": "queued",
    "dry_run": false
  }
}

GET /v1/api/imports/{import_id} informa del progreso y, al terminar, de los recuentos:

{
  "counts": { "read": 412, "created": 37, "updated": 361, "withdrawn": 9 }
}

GET /v1/api/imports/{import_id}/records es el detalle fila por fila, incluido cada rechazo con su motivo. Es el primer sitio donde mirar cuando los recuentos no son los que esperabas.

Los dos modos

incremental actualiza lo que contiene el archivo y deja todo lo demás en paz. Es el modo por defecto, y la elección correcta para un feed parcial: un archivo con los cambios de esta semana, o los anuncios de una sola oficina.

full_sync trata el archivo como la verdad completa para esa fuente. Todo lo que esta fuente publicó antes y que falte en el archivo se retira.

El modo por defecto es incremental por un motivo: un modo que quita cosas no debería ser algo que te toque por omisión. Una subida truncada en modo de sincronización completa retira una cartera entera.

Haz siempre una pasada en seco con un mapeo nuevo

curl -sS -X POST "https://api.skautik.com/v1/api/imports?format=csv&mode=full_sync&dry_run=true" \
  -H "Authorization: Bearer $SKAUTIK_API_KEY" \
  -F "file=@listings.csv"

Una pasada en seco analiza todo, valida todo e informa exactamente de los recuentos y de los resultados por ficha que produciría una pasada real, sin escribir nada. En una sincronización completa te dirá cuántos inmuebles se retirarían, que es la cifra que conviene mirar antes de enterarte por las malas.

La identidad, y por qué importa external_id

Todos los formatos de importación tienen un campo que identifica una ficha en tu sistema, y Skautik indexa por él. Envía el mismo external_id dos veces y la segunda pasada actualiza la primera ficha; envía uno nuevo cada vez y publicarás el mismo inmueble una y otra vez.

Ese campo es toda la historia de la reconciliación. Se devuelve en cada inmueble, así que nunca necesitas una tabla que mapee nuestros identificadores a los tuyos.

Si tu exportación no tiene un identificador estable por ficha, arréglalo antes de importar. Cualquier otra cosa, incluido casar por dirección, acabará fusionando dos pisos de un mismo edificio o partiendo un piso en dos fichas.

Fuentes permanentes

Una subida puntual está bien para una migración. Para un feed, crea una fuente una vez y deja que corra:

curl -sS -X POST "https://api.skautik.com/v1/api/import-sources" \
  -H "Authorization: Bearer $SKAUTIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly listing sync",
    "format": "csv",
    "delivery": { "type": "fetch", "url": "https://partner.example.com/exports/latest.csv" },
    "schedule": "15 3 * * *",
    "deletion_policy": "withdraw",
    "mapping": { "Objektnummer": "external_id", "Kaufpreis": "price" }
  }'

• delivery.type es fetch cuando recogemos de una URL de forma programada, o una entrega cuando nos la envías tú.
• schedule es cron, en UTC. Cada noche a una hora tranquila gana a cada hora: un feed consultado más a menudo de lo que cambia es solo carga.
• mapping traduce los nombres de tus columnas a los nuestros, para que no tengas que renombrar nada por tu lado.
• deletion_policy decide qué significa una ficha ausente para esta fuente.

last_delivery_at y next_expected_at en la fuente son lo que hay que vigilar con alertas. Un feed que se para en silencio es el fallo que merece la pena cazar, y se parece exactamente a un feed sin cambios salvo que vigiles esos dos campos.

Fichas que pertenecen a una fuente

Un inmueble que llegó por una importación pertenece a esa importación. Su source lo dice, y los endpoints de escritura se niegan a cambiarlo con 409 managed_by_import.

Es deliberado. Si el feed y la API pudieran editar la misma ficha, la siguiente pasada del feed desharía la edición en silencio, y nadie sabría qué sistema manda. Cámbialo en el sistema que alimenta la importación.

Formatos

Formatos de importación cubre cada uno de los que Skautik lee, cómo identifica una ficha y cómo funciona la retirada dentro de él. En la mayoría de los casos ya produces uno de ellos para un portal inmobiliario, y puedes enviarlo tal cual.

Si tu sistema exporta algo que no está en la lista, envía una muestra en lugar de escribir un conversor. Los formatos de intercambio inmobiliario son un conjunto pequeño y conocido.

Una lista de comprobación para una primera importación

• Haz una pasada en seco, y lee los resultados por ficha en lugar de solo los recuentos.
• Confirma que external_id es estable y único en tu fuente.
• Empieza en incremental; pasa a full_sync solo cuando el archivo sea genuinamente completo.
• Envía una Idempotency-Key, para que una expiración no se convierta en una segunda importación.
• Vigila next_expected_at en cuanto sea una fuente permanente.