{
  "openapi": "3.1.0",
  "info": {
    "title": "Kônsul Digital AI Automation & LeadsHUB API",
    "version": "1.0.0",
    "description": "Public API specification for Kônsul Digital. Enables AI agents and developers to integrate with LeadsHUB conversational AI agents, ingest and qualify sales leads, book diagnostics, and query the AI tool directory.",
    "contact": {
      "name": "Kônsul Digital Support",
      "email": "somos@konsul.digital",
      "url": "https://konsul.digital/contact"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://konsul.digital/privacy"
    }
  },
  "servers": [
    {
      "url": "https://konsul.digital/api/v1",
      "description": "Production API Server"
    }
  ],
  "paths": {
    "/leads": {
      "post": {
        "operationId": "ingestLead",
        "summary": "Ingest and Qualify Commercial Lead",
        "description": "Submit a prospective buyer or patient lead to Kônsul LeadsHUB for AI qualification, automated triage, and CRM sync across WhatsApp and CRM channels.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LeadSubmissionRequest"
              },
              "examples": {
                "real_estate_lead": {
                  "summary": "Real Estate Buyer Lead",
                  "value": {
                    "full_name": "Carlos Mendoza",
                    "email": "carlos.mendoza@example.com",
                    "phone": "+50761234567",
                    "channel": "whatsapp",
                    "industry": "real_estate",
                    "country": "Panamá",
                    "budget_range": "$150,000 - $250,000",
                    "inquiry": "Interesado en apartamento de 2 recámaras en Costa del Este con financiamiento bancario."
                  }
                },
                "healthcare_lead": {
                  "summary": "Healthcare Patient Appointment Lead",
                  "value": {
                    "full_name": "Dra. Sofía Navarro",
                    "email": "sofia.navarro@example.com",
                    "phone": "+50769876543",
                    "channel": "whatsapp",
                    "industry": "healthcare",
                    "country": "Panamá",
                    "inquiry": "Consulta para triaje de dermatología con seguro privado ASSA."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lead received and processed successfully by Kônsul AI Engine",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeadSubmissionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid lead payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/consultations/book": {
      "post": {
        "operationId": "bookConsultation",
        "summary": "Book Free AI Automation Diagnostic Session",
        "description": "Schedules a 30-minute strategic AI consultation with a Kônsul Digital solutions architect for WhatsApp and CRM automation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsultationBookingRequest"
              },
              "example": {
                "company_name": "Inmobiliaria del Istmo",
                "contact_name": "María Ramos",
                "email": "mramos@inmobiliariaistmo.com",
                "phone": "+50762345678",
                "country": "Panamá",
                "target_processes": [
                  "WhatsApp lead qualification",
                  "Yappy payment integration",
                  "HubSpot CRM sync"
                ],
                "preferred_date": "2026-09-15T14:00:00Z"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Consultation scheduled successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsultationBookingResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid booking request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/tools": {
      "get": {
        "operationId": "searchTools",
        "summary": "Search AI & Automation Tools Directory",
        "description": "Query Kônsul curated directory of AI models, automation workflows (n8n, Make), and specialized tools for Real Estate and Healthcare.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Filter tools by sector or functional category",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "inmobiliario",
                "salud",
                "automatizacion",
                "llm",
                "voz",
                "crm"
              ]
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Search keyword for tool name or capabilities",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching AI tools and platforms",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolsListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/company/info": {
      "get": {
        "operationId": "getCompanyInfo",
        "summary": "Get Verified Company Trust & Anchor Profile",
        "description": "Returns verified business metadata for Kônsul Digital: legal identity, headquarters in Panama, branch offices in Spain and Portugal, key services, and contact points.",
        "responses": {
          "200": {
            "description": "Verified organization metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyInfoResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LeadSubmissionRequest": {
        "type": "object",
        "required": [
          "full_name",
          "email",
          "phone",
          "industry"
        ],
        "properties": {
          "full_name": {
            "type": "string",
            "description": "Full name of the lead",
            "example": "Carlos Mendoza"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Business or personal email address",
            "example": "carlos.mendoza@example.com"
          },
          "phone": {
            "type": "string",
            "description": "Phone number with international country code (e.g. +507 for Panama)",
            "example": "+50761234567"
          },
          "channel": {
            "type": "string",
            "enum": [
              "whatsapp",
              "instagram",
              "facebook",
              "web",
              "phone"
            ],
            "default": "whatsapp",
            "description": "Communication channel where lead originated"
          },
          "industry": {
            "type": "string",
            "enum": [
              "real_estate",
              "healthcare",
              "automotive",
              "retail",
              "finance_insurance",
              "other"
            ],
            "description": "Business sector for specialized AI prompt and workflow routing"
          },
          "country": {
            "type": "string",
            "description": "Country of origin",
            "example": "Panamá"
          },
          "budget_range": {
            "type": "string",
            "description": "Approximate purchasing or investment budget",
            "example": "$150,000 - $250,000"
          },
          "inquiry": {
            "type": "string",
            "description": "Detailed text of the customer inquiry or requirement"
          }
        }
      },
      "LeadSubmissionResponse": {
        "type": "object",
        "required": [
          "status",
          "lead_id",
          "qualification_score",
          "assigned_agent",
          "message"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "received",
              "qualified",
              "handed_off_to_human"
            ],
            "example": "qualified"
          },
          "lead_id": {
            "type": "string",
            "example": "lead_9821a4f0"
          },
          "qualification_score": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "example": 88
          },
          "assigned_agent": {
            "type": "string",
            "example": "Agente IA LeadsHUB - Inmobiliario"
          },
          "next_action": {
            "type": "string",
            "example": "Send interactive project brochure on WhatsApp and trigger Calendly booking"
          },
          "message": {
            "type": "string",
            "example": "Lead processed and queued for instant 3-second WhatsApp engagement."
          }
        }
      },
      "ConsultationBookingRequest": {
        "type": "object",
        "required": [
          "company_name",
          "contact_name",
          "email",
          "phone"
        ],
        "properties": {
          "company_name": {
            "type": "string",
            "example": "Grupo Inmobiliario Panamá"
          },
          "contact_name": {
            "type": "string",
            "example": "Gabriel Valverde"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "somos@konsul.digital"
          },
          "phone": {
            "type": "string",
            "example": "+50760000000"
          },
          "country": {
            "type": "string",
            "example": "Panamá"
          },
          "target_processes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "WhatsApp Automation",
              "CRM Integration"
            ]
          },
          "preferred_date": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-15T15:00:00Z"
          }
        }
      },
      "ConsultationBookingResponse": {
        "type": "object",
        "required": [
          "booking_id",
          "status",
          "meeting_url",
          "message"
        ],
        "properties": {
          "booking_id": {
            "type": "string",
            "example": "bk_773291"
          },
          "status": {
            "type": "string",
            "example": "confirmed"
          },
          "meeting_url": {
            "type": "string",
            "example": "https://calendly.com/wearekonsul/konsul-ecosistema-ia"
          },
          "message": {
            "type": "string",
            "example": "Consultation session booked. Confirmation sent to email."
          }
        }
      },
      "ToolsListResponse": {
        "type": "object",
        "required": [
          "total",
          "tools"
        ],
        "properties": {
          "total": {
            "type": "integer",
            "example": 14
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "example": "leadshub"
                },
                "name": {
                  "type": "string",
                  "example": "Kônsul LeadsHUB"
                },
                "category": {
                  "type": "string",
                  "example": "automatizacion"
                },
                "description": {
                  "type": "string",
                  "example": "Agentes de IA omnicanal para WhatsApp, Instagram y CRM."
                },
                "website": {
                  "type": "string",
                  "example": "https://konsul.digital/chatbot"
                },
                "is_third_party": {
                  "type": "boolean",
                  "example": false
                }
              }
            }
          }
        }
      },
      "CompanyInfoResponse": {
        "type": "object",
        "required": [
          "name",
          "legal_status",
          "headquarters",
          "offices",
          "primary_services",
          "contact"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Kônsul Digital"
          },
          "tagline": {
            "type": "string",
            "example": "Automatización con inteligencia artificial"
          },
          "website": {
            "type": "string",
            "example": "https://konsul.digital"
          },
          "headquarters": {
            "type": "object",
            "properties": {
              "country": {
                "type": "string",
                "example": "Panamá"
              },
              "city": {
                "type": "string",
                "example": "Ciudad de Panamá"
              },
              "address": {
                "type": "string",
                "example": "Bella Vista, Federico Boyd y Calle 51, Edificio Scotiaplaza, Piso 7, Oficina 21"
              }
            }
          },
          "offices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "country": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "address": {
                  "type": "string"
                }
              }
            }
          },
          "primary_services": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Agentes de IA para WhatsApp y CRM (LeadsHUB)",
              "Automatización de procesos y RPA",
              "Integración de pasarelas de pago (Yappy Comercial, PágueloFácil)",
              "Consultoría en IA para Sector Inmobiliario y Sector Salud"
            ]
          },
          "contact": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string",
                "example": "somos@konsul.digital"
              },
              "booking_url": {
                "type": "string",
                "example": "https://calendly.com/wearekonsul/konsul-ecosistema-ia"
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "resolution"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Standardized machine-readable error code",
                "example": "VALIDATION_ERROR"
              },
              "message": {
                "type": "string",
                "description": "Human and LLM understandable explanation of what went wrong",
                "example": "Missing required field: full_name."
              },
              "resolution": {
                "type": "string",
                "description": "Actionable guidance for the calling agent or developer to resolve the issue",
                "example": "Include full_name in the JSON request body and consult https://konsul.digital/openapi.json"
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "description": "API Key authentication for registered Kônsul LeadsHUB enterprise clients."
      }
    }
  }
}