Autenticación
Cree una llave en Panel, API con los permisos que necesita y envíela en cada solicitud:
curl https://vivuk.co/api/v1/avisos \
-H "Authorization: Bearer SU_LLAVE" \
-H "Accept: application/json"
Base: https://vivuk.co/api/v1. Respuestas en JSON, fechas en ISO 8601 con hora de Colombia, montos en pesos sin decimales. Límite: 120 solicitudes por minuto por llave.
Permisos
avisos:leer y avisos:escribircontactos:leer y contactos:escribircontratos:leer
Endpoints
Cuenta
| Método y ruta | Permiso | Qué hace |
|---|
| GET /cuenta | cualquiera | Datos de la cuenta, plan y uso (avisos activos, contratos, usuarios). |
Avisos
| Método y ruta | Permiso | Qué hace |
|---|
| GET /avisos | avisos:leer | Lista los avisos de la cuenta. Filtros: estado, operacion, tipo, actualizado_desde. 50 por página. |
| POST /avisos | avisos:escribir | Crea un aviso. Queda en revisión hasta que lo aprobemos. |
| GET /avisos/{codigo} | avisos:leer | Un aviso con sus fotos. |
| PATCH /avisos/{codigo} | avisos:escribir | Actualiza un aviso. El precio y la administración se aplican de una vez; los demás cambios vuelven a revisión. |
| POST /avisos/{codigo}/estado | avisos:escribir | Pausa, reactiva o cierra un aviso: estado = publicado, pausado o cerrado (con cierre = arrendado, vendido o retirado). |
| POST /avisos/{codigo}/fotos | avisos:escribir | Sube una foto (multipart). Envíe las variantes foto_480, foto_960, foto_1600 y foto_og, o un solo archivo foto en JPEG o WebP de hasta 1600 px. |
| DELETE /avisos/{codigo}/fotos/{id} | avisos:escribir | Borra una foto. |
Contactos
| Método y ruta | Permiso | Qué hace |
|---|
| GET /contactos | contactos:leer | Interesados en sus avisos, con canal, aviso y asesor. Filtros: desde, aviso. |
| PATCH /contactos/{id} | contactos:escribir | Cambia el estado (nuevo, contactado, visita, cerrado, descartado) o las notas. |
Contratos
| Método y ruta | Permiso | Qué hace |
|---|
| GET /contratos | contratos:leer | Contratos de la cuenta con su estado. |
| GET /contratos/{codigo} | contratos:leer | Un contrato con sus cobros mensuales. |
Edificios
| Método y ruta | Permiso | Qué hace |
|---|
| GET /edificios | avisos:leer | Edificios, conjuntos y proyectos de la cuenta. |
| POST /edificios | avisos:escribir | Crea un edificio para agrupar unidades. |
Referencias
| Método y ruta | Permiso | Qué hace |
|---|
| GET /municipios?q= | cualquiera | Busca municipios por nombre. Use el código DANE en los avisos. |
| GET /tipos | cualquiera | Tipos de inmueble, características y garantías válidas. |
Crear un aviso
POST https://vivuk.co/api/v1/avisos
{
"operacion": "arriendo",
"tipo": "apartamento",
"titulo": "Apartamento con balcón cerca al parque",
"descripcion": "Tercer piso, iluminado, cocina abierta, zona de ropas.",
"municipio": "68001",
"barrio": "Cabecera del Llano",
"precio": 1850000,
"administracion": 240000,
"area": 72,
"habitaciones": 3,
"banos": 2,
"parqueaderos": 1,
"estrato": 4,
"mascotas": true,
"caracteristicas": [
"Balcón",
"Ascensor"
],
"requisitos": {
"garantia": "poliza",
"ingresos_veces": 3
}
}
Campos obligatorios: operacion, tipo, titulo, municipio (código DANE de 5 dígitos), precio y área (o área del lote en lotes y fincas). Las fotos se suben después; se necesitan al menos 3 para pasar la revisión.
Errores
| Código | Significado |
|---|
| 401 | Falta la llave o no es válida. |
| 403 | La llave no tiene el permiso o el plan no incluye la API. |
| 404 | No existe o no es de su cuenta. |
| 422 | Datos inválidos. La respuesta trae errores por campo. |
| 429 | Pasó el límite de solicitudes. Espere los segundos de Retry-After. |
Webhooks
Registre una URL en el panel y escoja los eventos: contacto.nuevo, aviso.publicado, aviso.cerrado, cobro.reportado, cobro.pagado, contrato.firmado, promesa.firmada .
POST https://su-sistema.co/vivuk
Vivuk-Firma: t=1760040245,v1=5f2b…
{
"id": "evt_01HZX3",
"evento": "contacto.nuevo",
"creado_en": "2026-10-09T15:04:05-05:00",
"datos": {
"contacto": {
"id": 812,
"canal": "whatsapp",
"nombre": "Laura",
"telefono": "3001234567"
},
"aviso": {
"codigo": "VIV-2026-004512"
}
}
}
Para comprobar que viene de Vivuk, calcule HMAC-SHA256(secreto, t + "." + cuerpo) en hexadecimal y compárelo con v1; rechace firmas con más de 5 minutos. Responda con un código 2xx en menos de 10 segundos. Si falla, reintentamos 3 veces: al minuto, a los 10 minutos y a la hora.
Feeds y multipublicación
Desde el panel puede activar un feed privado de sus avisos publicados en JSON, en XML y en el formato del catálogo de inmuebles de Meta. La URL lleva una llave propia que puede cambiar cuando quiera. Para Mercado Libre, conecte su cuenta y publique desde cada aviso.
