{"swagger":"2.0","info":{"title":"Facilito API","description":"Documentación oficial de los endpoints externos de Facilito.\n\n### 🔒 Autenticación\nPara consumir cualquiera de los endpoints, es obligatorio incluir tu API Key en la cabecera (header) de cada petición:\n* **Header Name:** `x-api-key`\n* **Header Value:** `Tu API Key provista de forma privada` (ej: `solicita-tu-key-a-facilito`)\n\nSi la cabecera está ausente o es incorrecta, el servidor responderá con un estado `401 Unauthorized`.","version":"1.0.0"},"definitions":{},"paths":{"/facilito-casa/cotizar":{"post":{"description":"Calcula el valor de la prima del seguro de arrendamiento de SURA de manera dinámica.","parameters":[{"name":"body","in":"body","schema":{"type":"object","required":["f_destinacion_arriendo","iva_canon","plan_de_arrendamiento","duracion_con","f_valor_canon"],"properties":{"f_destinacion_arriendo":{"type":"string","enum":["VIVIENDA","COMERCIAL"]},"iva_canon":{"type":"string","enum":["SI","NO"]},"plan_de_arrendamiento":{"type":"string","enum":["PLAN BASICO","PLAN CLASICO","PLAN GLOBAL"]},"duracion_con":{"type":"number","minimum":1,"maximum":12},"f_valor_canon":{"type":"number"},"valor_administracion":{"type":"number","default":0},"asistencia_domiciliaria":{"type":"string","enum":["SI","NO"],"default":"NO"},"danios_faltantes":{"type":"string","enum":["SI","NO"],"default":"NO"},"danios_monto":{"type":"number","default":0}}}}],"responses":{"200":{"description":"Default Response","schema":{"type":"object","properties":{"success":{"type":"boolean"},"valor_canon":{"type":"number"},"valor_administracion":{"type":"number"},"duracion_meses":{"type":"number"},"plan":{"type":"string"},"desglose":{"type":"object","properties":{"prima_arrendamiento":{"type":"number"},"prima_iva_canon":{"type":"number"},"prima_administracion":{"type":"number"},"asistencia":{"type":"number"},"cobertura_danos":{"type":"number"}}},"total_prima":{"type":"number"},"total_iva":{"type":"number"},"total_pagar":{"type":"number"}}}}}}},"/facilito-casa/solicitud/create":{"post":{"description":"Crea una nueva solicitud (Oportunidad y Contactos) en Facilito de manera externa.","parameters":[{"name":"body","in":"body","schema":{"type":"object","required":["f_valor_canon","propietario","arrendatario"],"properties":{"mode":{"type":"string","enum":["test","live"],"default":"test","description":"Modo de ejecución (test no crea workflows de firmas)"},"source":{"type":"string","description":"Origen o Aliado comercial"},"codasesor":{"type":"string","description":"Código del Asesor"},"nombreasesor":{"type":"string","description":"Nombre del Asesor"},"f_destinacion_arriendo":{"type":"string","enum":["VIVIENDA","COMERCIAL"],"default":"VIVIENDA"},"f_valor_canon":{"type":"number","description":"Valor del canon mensual de arrendamiento sin puntos ni comas"},"valor_administracion":{"type":"number","description":"Valor mensual de la administración"},"duracion_con":{"type":"number","default":12,"description":"Duración del contrato en meses"},"plan_de_arrendamiento":{"type":"string","enum":["PLAN CLASICO","PLAN GLOBAL","PLAN BASICO"],"default":"PLAN CLASICO"},"asistencia_domiciliaria":{"type":"string","enum":["SI","NO"],"default":"NO"},"danios_faltantes":{"type":"string","enum":["SI","NO"],"default":"NO"},"danios_monto":{"type":"number","description":"Monto de cobertura por daños y faltantes"},"direccion_inmueble":{"type":"string","description":"Dirección del inmueble a arrendar"},"ciudad_inmueble":{"type":"string","description":"Ciudad del inmueble a arrendar"},"propietario":{"type":"object","required":["first_name","last_name","email","phone"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string","description":"Número celular con indicativo (Ej: +573001234567)"},"tipo_documento":{"type":"string","enum":["CEDULA","NIT","PASAPORTE","CEDULA_EXTRANJERIA"],"default":"CEDULA"},"numero_documento":{"type":"string"}}},"arrendatario":{"type":"object","required":["first_name","last_name","email","phone"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"tipo_documento":{"type":"string","enum":["CEDULA","NIT","PASAPORTE","CEDULA_EXTRANJERIA"],"default":"CEDULA"},"numero_documento":{"type":"string"},"cedula_base64":{"type":"string","description":"Archivo de cédula codificado en Base64. (Alternativa de carga directa, requiere cedula_filename)"},"cedula_filename":{"type":"string","description":"Nombre del archivo de cédula con su extensión, ej: cedula_inquilino.pdf. (Requerido si se envía cedula_base64 para que el servidor identifique la extensión del archivo)"},"cedula_url":{"type":"string","description":"URL pública de descarga del archivo de cédula. El servidor la descargará automáticamente de esta dirección. (Alternativa a usar cedula_base64)"}}},"codeudor":{"type":"object","properties":{"has_codeudor":{"type":"string","enum":["Si","No"],"default":"No"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"tipo_documento":{"type":"string","enum":["CEDULA","NIT","PASAPORTE","CEDULA_EXTRANJERIA"],"default":"CEDULA"},"numero_documento":{"type":"string"}}}},"example":{"mode":"test","source":"TuBroki","codasesor":"36943","nombreasesor":"Figuro Colombia Ltda","f_destinacion_arriendo":"VIVIENDA","f_valor_canon":1800000,"valor_administracion":250000,"duracion_con":12,"plan_de_arrendamiento":"PLAN CLASICO","asistencia_domiciliaria":"SI","danios_faltantes":"SI","danios_monto":5000000,"direccion_inmueble":"Calle 45 # 12a - 30, Apto 402","ciudad_inmueble":"Medellín","propietario":{"first_name":"Juan","last_name":"Pérez","email":"juan.propietario@ficticio.com","phone":"+573001234567","tipo_documento":"CEDULA","numero_documento":"12345678"},"arrendatario":{"first_name":"Pedro","last_name":"Gómez","email":"pedro.inquilino@gmail.com","phone":"+573104567890","tipo_documento":"CEDULA","numero_documento":"10203040","cedula_base64":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=","cedula_filename":"cedula_arrendatario.png"},"codeudor":{"has_codeudor":"Si","first_name":"María","last_name":"Rodríguez","email":"maria.codeudor@hotmail.com","phone":"+573209876543","tipo_documento":"CEDULA","numero_documento":"50607080"}}}},{"type":"string","description":"API Key de autorización de Facilito","required":true,"in":"header","name":"x-api-key"}],"responses":{"200":{"description":"Default Response","schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"solicitudId":{"type":"string"},"opportunityId":{"type":"string"},"contactIdTomador":{"type":"string"}},"example":{"success":true,"message":"Solicitud de cotización creada exitosamente en Facilito.","solicitudId":"731-8682","opportunityId":"opp_123456ghl","contactIdTomador":"con_789012ghl"}}}}}},"/facilito-casa/solicitud/trazabilidad/{numSolicitud}":{"get":{"description":"Retorna la trazabilidad detallada del estado de una solicitud basándose en el pipeline de Facilito.","parameters":[{"type":"string","description":"Número de radicado de solicitud (Ej: 731-8682)","required":true,"in":"path","name":"numSolicitud"}],"responses":{"200":{"description":"Default Response","schema":{"type":"object","properties":{"success":{"type":"boolean"},"solicitudId":{"type":"string"},"opportunityId":{"type":"string"},"opportunityName":{"type":"string"},"currentStage":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"timeline":{"type":"array","items":{"type":"object","properties":{"step":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["completed","active","pending","rejected","warning"]}}}},"observaciones":{"type":"string"}},"example":{"success":true,"solicitudId":"731-8682","opportunityId":"opp_123456ghl","opportunityName":"Juan Pérez - Solicitud de Arrendamiento","currentStage":{"id":"6813f234-c271-4a77-a676-2e3e5c83163f","name":"EVALUACION"},"timeline":[{"step":1,"name":"Cotización","description":"Formulario diligenciado y copia de documento de identidad recibidos.","status":"completed"},{"step":2,"name":"Evaluación","description":"Estamos evaluando. Este paso tarda aproximadamente 3 horas laborales.","status":"active"},{"step":3,"name":"Aprobada contrato","description":"Estamos pendientes que el propietario diligencie la orden de contrato. Si ya lo hizo, estamos haciendo el contrato.","status":"pending"},{"step":4,"name":"Firmas","description":"Se envió el contrato a propietario, inquilino y codeudores si aplica. Si está en esta etapa, alguien falta por firmar.","status":"pending"},{"step":5,"name":"Proceso de expedición","description":"Ya todos firmaron, estamos en proceso de expedición. Para acelerar este paso, responde el correo que enviamos de confirmación.","status":"pending"},{"step":6,"name":"Póliza expedida","description":"Tu póliza ha sido expedida.","status":"pending"}]}}}}}},"/contacts/upsert":{"post":{"summary":"Upsert de Contacto (Crear o Actualizar)","description":"Sincroniza un contacto/cliente desde el sistema de operación o punto de venta (POS) del aliado comercial hacia GoHighLevel.\n\n### 🔄 Mecanismo de Upsert (Deduplicación Automática):\n* **Si el cliente NO existe:** Se crea un nuevo contacto en la subcuenta con su información y se le asigna la sucursal.\n* **Si el cliente YA existe (por Email o Teléfono):** Se actualizan sus datos y se reasigna la `sucursal_asignada` a la nueva tienda sin crear registros duplicados.\n\n### 🏪 Valores válidos para sucursal_asignada:\n* `Doral`\n* `Coral Gables`\n\n### 🔒 Autenticación Requerida:\nEs obligatorio incluir tanto `x-location-id` como `x-api-key` en las cabeceras HTTP.","tags":["Integración de Contactos (CRM)"],"parameters":[{"name":"body","in":"body","schema":{"type":"object","required":["firstName"],"properties":{"firstName":{"type":"string","description":"Nombre del contacto","example":"Alex"},"lastName":{"type":"string","description":"Apellido del contacto","example":"Gómez"},"email":{"type":"string","format":"email","description":"Correo electrónico del cliente","example":"alex.gomez@gmail.com"},"phone":{"type":"string","description":"Teléfono con o sin indicativo internacional (normalizado a E.164 automáticamente)","example":"+13055550199"},"sucursal_asignada":{"type":"string","enum":["Doral","Coral Gables"],"description":"Tienda o sucursal donde se realizó la compra o registro","example":"Doral"},"tags":{"type":"array","items":{"type":"string"},"description":"Etiquetas para segmentación y automatizaciones en el CRM","example":["pos-sneacare","cliente-mostrador"]},"source":{"type":"string","description":"Origen de la transacción o sistema emisor","example":"POS SneaCare"}}}},{"type":"string","description":"Identificador único de la subcuenta en GoHighLevel (ej: k6eshf7NoYpyHCCp6PA4)","example":"k6eshf7NoYpyHCCp6PA4","required":true,"in":"header","name":"x-location-id"},{"type":"string","description":"API Key o Private Token de la subcuenta (ej: pit-24b219c4-08e6-4e2d-9786-4d43e7f6b899)","example":"pit-24b219c4-08e6-4e2d-9786-4d43e7f6b899","required":true,"in":"header","name":"x-api-key"}],"responses":{"200":{"description":"Contacto procesado exitosamente (creado o actualizado)","schema":{"description":"Contacto procesado exitosamente (creado o actualizado)","type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Contacto creado exitosamente en GHL"},"action":{"type":"string","enum":["created","updated"],"example":"created"},"contact":{"type":"object","properties":{"id":{"type":"string","description":"ID único del contacto en GoHighLevel","example":"9omOrA3oAotlPItaDypc"},"firstName":{"type":"string","example":"Alex"},"lastName":{"type":"string","example":"Gómez"},"email":{"type":"string","example":"alex.gomez@gmail.com"},"phone":{"type":"string","example":"+13055550199"},"locationId":{"type":"string","example":"k6eshf7NoYpyHCCp6PA4"},"isNew":{"type":"boolean","example":true},"action":{"type":"string","example":"created"},"customFields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"value":{"type":"string"}}}}}}}}},"400":{"description":"Error de validación (faltan identificadores o JSON inválido)","schema":{"description":"Error de validación (faltan identificadores o JSON inválido)","type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Se requiere al menos un identificador único para el contacto: email o phone."}}}},"401":{"description":"Error de autenticación (API Key ausente o inválida)","schema":{"description":"Error de autenticación (API Key ausente o inválida)","type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Acceso Denegado: Se requiere una API Key válida (header x-api-key) correspondiente a esta subcuenta."}}}}}}},"/contacts/search":{"get":{"summary":"Buscar Contacto (Multi-Criterio)","description":"Consulta y recupera la información de un contacto en la subcuenta buscando por teléfono, correo electrónico, documento o nombre.","tags":["Integración de Contactos (CRM)"],"parameters":[{"type":"string","description":"Término de búsqueda universal (teléfono, email, documento o nombre)","example":"+13055550199","required":false,"in":"query","name":"query"},{"type":"string","description":"Búsqueda específica por número de teléfono","example":"3055550199","required":false,"in":"query","name":"phone"},{"type":"string","description":"Búsqueda específica por correo electrónico","example":"alex.gomez@gmail.com","required":false,"in":"query","name":"email"},{"type":"string","description":"ID de la subcuenta en GoHighLevel","example":"k6eshf7NoYpyHCCp6PA4","required":true,"in":"header","name":"x-location-id"},{"type":"string","description":"API Key de la subcuenta","example":"pit-24b219c4-08e6-4e2d-9786-4d43e7f6b899","required":true,"in":"header","name":"x-api-key"}],"responses":{"200":{"description":"Contacto encontrado con éxito","schema":{"description":"Contacto encontrado con éxito","type":"object","properties":{"success":{"type":"boolean","example":true},"matchCriteria":{"type":"string","example":"phone"},"contact":{"type":"object","properties":{"id":{"type":"string","example":"9omOrA3oAotlPItaDypc"},"firstName":{"type":"string","example":"Alex"},"lastName":{"type":"string","example":"Gómez"},"email":{"type":"string","example":"alex.gomez@gmail.com"},"phone":{"type":"string","example":"+13055550199"},"tags":{"type":"array","items":{"type":"string"}},"customFields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"value":{"type":"string"}}}}}}}}},"401":{"description":"Error de autenticación","schema":{"description":"Error de autenticación","type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Acceso Denegado: Se requiere una API Key válida (header x-api-key) correspondiente a esta subcuenta."}}}},"404":{"description":"No se encontró ningún contacto","schema":{"description":"No se encontró ningún contacto","type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"No se encontró ningún contacto que coincida con \"+13055550199\" en esta subcuenta."}}}}}}}},"schemes":["https","http"],"consumes":["application/json","multipart/form-data"],"produces":["application/json"],"securityDefinitions":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header"}}}