{
  "openapi": "3.1.0",
  "info": {
    "title": "Estudio Jurídico Souilhe - Public & Agent API",
    "version": "1.0.0",
    "description": "API pública y especificación para agentes de Inteligencia Artificial de Estudio Jurídico Souilhe. Especialistas en indemnizaciones por accidentes de tránsito y laborales (ART) en Resistencia (Chaco), Misiones y todo el NEA argentino.",
    "contact": {
      "name": "Estudio Jurídico Souilhe",
      "url": "https://estudiosouilhe.com",
      "email": "consultas@estudiosouilhe.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://estudiosouilhe.com"
    }
  },
  "servers": [
    {
      "url": "https://estudiosouilhe.com",
      "description": "Servidor Web Principal"
    },
    {
      "url": "https://v3.estudiosouilhe.com",
      "description": "Servidor CRM / Backend API"
    }
  ],
  "tags": [
    {
      "name": "Contact",
      "description": "Recepción y registro de consultas y casos de accidentes viales y laborales"
    },
    {
      "name": "Routing",
      "description": "Redirección inteligente con atribución de canal"
    },
    {
      "name": "Tracking",
      "description": "Telemetría y analítica de interacción"
    },
    {
      "name": "Discovery",
      "description": "Recursos legibles por máquinas, LLMs y agentes de IA"
    }
  ],
  "paths": {
    "/api/public/contacto": {
      "post": {
        "tags": ["Contact"],
        "summary": "Registrar consulta legal o siniestro vial / laboral",
        "description": "Permite a usuarios o agentes de IA enviar una solicitud de asesoramiento legal. El estudio atiende bajo modalidad de pacto de cuota litis (sin costos por adelantado).",
        "operationId": "registrarContacto",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsultaContactoRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Consulta registrada exitosamente",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Solicitud inválida o campos faltantes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Error interno del servidor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/contacto/whatsapp": {
      "post": {
        "tags": ["Tracking"],
        "summary": "Registrar evento de clic hacia WhatsApp",
        "description": "Registra analítica anónima cuando un usuario inicia contacto por WhatsApp.",
        "operationId": "registrarClickWhatsapp",
        "responses": {
          "201": {
            "description": "Evento registrado exitosamente",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "500": {
            "description": "Error interno",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/contacto/telefono": {
      "post": {
        "tags": ["Tracking"],
        "summary": "Registrar evento de clic hacia llamada telefónica",
        "description": "Registra analítica cuando un usuario inicia una llamada telefónica.",
        "operationId": "registrarClickTelefono",
        "responses": {
          "201": {
            "description": "Evento registrado exitosamente",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "500": {
            "description": "Error interno",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/go/wa/{canal}": {
      "get": {
        "tags": ["Routing"],
        "summary": "Redirección a WhatsApp con atribución de canal",
        "description": "Redirige al chat de WhatsApp oficial del estudio (+54 9 3625 200253) con mensaje contextual según el canal de origen.",
        "operationId": "redirectWhatsappCanal",
        "parameters": [
          {
            "name": "canal",
            "in": "path",
            "required": true,
            "description": "Canal de origen (ej. google, instagram, facebook, web)",
            "schema": {
              "type": "string",
              "enum": ["google", "instagram", "facebook", "general"]
            }
          },
          {
            "name": "text",
            "in": "query",
            "required": false,
            "description": "Mensaje personalizado opcional para prefijar en WhatsApp",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirección hacia wa.me"
          }
        }
      }
    },
    "/go/whatsapp": {
      "get": {
        "tags": ["Routing"],
        "summary": "Redirección directa a WhatsApp",
        "description": "Enlace directo hacia el WhatsApp oficial de atención del estudio.",
        "operationId": "redirectWhatsappDirecto",
        "responses": {
          "302": {
            "description": "Redirección hacia wa.me"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Información resumida para Modelos de Lenguaje (LLMs)",
        "description": "Documento en Markdown con resumen de servicios, sedes, preguntas frecuentes y recursos para agentes.",
        "operationId": "getLlmsTxt",
        "responses": {
          "200": {
            "description": "Contenido Markdown de contexto",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Especificación OpenAPI en formato JSON",
        "description": "Descarga de la especificación OpenAPI 3.1.0 de la plataforma.",
        "operationId": "getOpenApiJson",
        "responses": {
          "200": {
            "description": "Documento OpenAPI JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/openapi.yaml": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Especificación OpenAPI en formato YAML",
        "description": "Descarga de la especificación OpenAPI en formato YAML.",
        "operationId": "getOpenApiYaml",
        "responses": {
          "200": {
            "description": "Documento OpenAPI YAML",
            "content": {
              "text/yaml": {
                "schema": {
                  "type": "string"
                }
              },
              "application/x-yaml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Mapa del sitio XML",
        "description": "Sitemap XML conforme al protocolo sitemaps.org con las URLs públicas del sitio.",
        "operationId": "getSitemapXml",
        "responses": {
          "200": {
            "description": "Documento XML Sitemap",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/developers": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Portal de desarrolladores y agentes de IA",
        "description": "Página con documentación técnica sobre las APIs y recursos para agentes.",
        "operationId": "getDevelopersPortal",
        "responses": {
          "200": {
            "description": "Portal técnico (HTML o Markdown según negociación de contenido)",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ConsultaContactoRequest": {
        "type": "object",
        "required": ["nombre", "telefono", "email", "mensaje"],
        "properties": {
          "nombre": {
            "type": "string",
            "description": "Nombre y apellido del consultante",
            "example": "Juan Pérez"
          },
          "telefono": {
            "type": "string",
            "description": "Número de teléfono o WhatsApp de contacto",
            "example": "3624123456"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Correo electrónico de contacto",
            "example": "juan.perez@example.com"
          },
          "mensaje": {
            "type": "string",
            "description": "Detalle del accidente de tránsito o laboral sufrido y dudas legales",
            "example": "Sufrí un choque en moto en Resistencia y la aseguradora del tercero no me quiere pagar los gastos médicos."
          },
          "segundo_nombre": {
            "type": "string",
            "description": "Campo honeypot de seguridad para bots de spam. Debe dejarse vacío por usuarios y agentes legítimos.",
            "example": ""
          }
        }
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "message": {
            "type": "string",
            "example": "Inquiry registered successfully."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "error"
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "example": "BAD_REQUEST"
              },
              "message": {
                "type": "string",
                "example": "All fields (name, phone, email, message) are required."
              },
              "hint": {
                "type": "string",
                "example": "Refer to https://estudiosouilhe.com/openapi.json for schema requirements."
              }
            }
          }
        }
      }
    }
  }
}