{
  "openapi": "3.0.3",
  "info": {
    "title": "HorseInc Public Web Services API",
    "description": "Especificação pública de serviços e pontos de integração web da HorseInc (estúdio digital Marcelo Saltori). Permite que agentes autônomos de IA descubram capacidades, realizem diagnósticos digitais e iniciem contato comercial estruturado.",
    "version": "1.0.0",
    "contact": {
      "name": "Marcelo Saltori",
      "url": "https://marcelosaltori.com.br",
      "email": "contato@marcelosaltori.com.br"
    }
  },
  "servers": [
    {
      "url": "https://marcelosaltori.com.br/api/v1",
      "description": "API v1 Endpoint Base"
    },
    {
      "url": "https://marcelosaltori.com.br",
      "description": "Servidor de Produção Oficial"
    }
  ],
  "paths": {
    "/api/v1/status": {
      "get": {
        "summary": "Verificar status e capacidades públicas",
        "description": "Retorna o status operacional da infraestrutura da HorseInc e lista as capacidades de automação e desenvolvimento disponíveis.",
        "operationId": "getSystemStatusV1",
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "description": "Versão da API (padrão: v1)",
            "schema": { "type": "string", "default": "v1" }
          }
        ],
        "responses": {
          "200": {
            "description": "Status operacional e serviços disponíveis",
            "headers": {
              "RateLimit-Limit": {
                "schema": { "type": "integer" },
                "description": "Número máximo de requisições por minuto (Padrão IETF)"
              },
              "RateLimit-Remaining": {
                "schema": { "type": "integer" },
                "description": "Requisições restantes na janela atual (Padrão IETF)"
              },
              "RateLimit-Reset": {
                "schema": { "type": "integer" },
                "description": "Segundos restantes na janela de taxa (Padrão IETF)"
              },
              "X-RateLimit-Limit": {
                "schema": { "type": "integer" },
                "description": "Número máximo de requisições por minuto (legado)"
              },
              "X-RateLimit-Remaining": {
                "schema": { "type": "integer" },
                "description": "Requisições restantes na janela atual (legado)"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/status": {
      "get": {
        "summary": "Verificar status e capacidades públicas (alias legada)",
        "description": "Retorna o status operacional da infraestrutura da HorseInc e lista as capacidades de automação e desenvolvimento disponíveis.",
        "operationId": "getSystemStatus",
        "responses": {
          "200": {
            "description": "Status operacional e serviços disponíveis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/digital-analysis": {
      "post": {
        "summary": "Solicitar diagnóstico de presença digital",
        "description": "Recebe informações de um negócio ou clínica para análise automática de presença web, SEO local, conformidade com agentes de IA e tráfego.",
        "operationId": "requestDigitalAnalysisV1",
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "description": "Versão da API (padrão: v1)",
            "schema": { "type": "string", "default": "v1" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnalysisRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Diagnóstico aceito e agendado com sucesso",
            "headers": {
              "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Número máximo de requisições" },
              "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requisições restantes" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalysisResponse"
                }
              }
            }
          },
          "400": {
            "description": "Dados de solicitação inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/digital-analysis": {
      "post": {
        "summary": "Solicitar diagnóstico de presença digital (alias)",
        "description": "Recebe informações de um negócio ou clínica para análise automática de presença web, SEO local, conformidade com agentes de IA e tráfego.",
        "operationId": "requestDigitalAnalysis",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnalysisRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Diagnóstico aceito e agendado com sucesso",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalysisResponse"
                }
              }
            }
          },
          "400": {
            "description": "Dados de solicitação inválidos",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/contact": {
      "post": {
        "summary": "Enviar mensagem de contato comercial",
        "description": "Encaminha uma solicitação comercial ou proposta diretamente para a triagem da HorseInc via WhatsApp e Telegram.",
        "operationId": "sendContactMessageV1",
        "parameters": [
          {
            "name": "API-Version",
            "in": "header",
            "required": false,
            "description": "Versão da API (padrão: v1)",
            "schema": { "type": "string", "default": "v1" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mensagem recebida com sucesso",
            "headers": {
              "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Número máximo de requisições" },
              "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requisições restantes" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponse"
                }
              }
            }
          },
          "400": {
            "description": "Erro de validação dos campos",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "summary": "Enviar mensagem de contato comercial (alias)",
        "description": "Encaminha uma solicitação comercial ou proposta diretamente para a triagem da HorseInc via WhatsApp e Telegram.",
        "operationId": "sendContactMessage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mensagem recebida com sucesso",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponse"
                }
              }
            }
          },
          "400": {
            "description": "Erro de validação dos campos",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "StatusResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "online" },
          "studio": { "type": "string", "example": "HorseInc" },
          "operator": { "type": "string", "example": "Marcelo Saltori" },
          "capabilities": {
            "type": "array",
            "items": { "type": "string" },
            "example": [
              "Criação de Sites e Landing Pages de Alta Performance",
              "Automações WhatsApp e n8n",
              "Inteligência Artificial Aplicada e GEO",
              "Sistemas Web sob Medida (React 19, Supabase)"
            ]
          },
          "llms_url": { "type": "string", "example": "https://marcelosaltori.com.br/llms.txt" }
        },
        "required": ["status", "studio", "operator", "capabilities"]
      },
      "AnalysisRequest": {
        "type": "object",
        "properties": {
          "businessName": { "type": "string", "description": "Nome da empresa ou clínica", "example": "Clínica Harmonize" },
          "websiteUrl": { "type": "string", "format": "uri", "description": "URL atual do site (se houver)", "example": "https://clinicaharmonize.com.br" },
          "instagram": { "type": "string", "description": "Perfil no Instagram", "example": "@clinicaharmonize" },
          "segment": { "type": "string", "description": "Ramo de atuação", "example": "Estética Avançada" },
          "contactEmail": { "type": "string", "format": "email", "example": "contato@clinicaharmonize.com.br" },
          "contactPhone": { "type": "string", "example": "+5511999999999" }
        },
        "required": ["businessName", "contactEmail", "segment"]
      },
      "AnalysisResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "analysisId": { "type": "string", "example": "ana_98a7sd6f5g" },
          "message": { "type": "string", "example": "Diagnóstico digital iniciado. O relatório será entregue em até 24h." }
        },
        "required": ["success", "analysisId", "message"]
      },
      "ContactRequest": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "example": "João Silva" },
          "email": { "type": "string", "format": "email", "example": "joao@empresa.com" },
          "phone": { "type": "string", "example": "+5511988888888" },
          "message": { "type": "string", "example": "Gostaria de um orçamento para criação de site institucional e automação de agendamentos." }
        },
        "required": ["name", "email", "message"]
      },
      "ContactResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "message": { "type": "string", "example": "Mensagem recebida com sucesso. Marcelo Saltori entrará em contato em breve." }
        },
        "required": ["success", "message"]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "example": "Bad Request" },
          "message": { "type": "string", "example": "O campo contactEmail é obrigatório e deve ter formato válido." },
          "code": { "type": "integer", "example": 400 }
        },
        "required": ["error", "message", "code"]
      }
    },
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 com suporte a escopos para agentes autônomos de IA",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://marcelosaltori.com.br/api/v1/auth/token",
            "scopes": {
              "read:status": "Ler métricas e status operacional da infraestrutura",
              "write:leads": "Enviar solicitações de contato comercial e diagnósticos digitais"
            }
          }
        }
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Autenticação via chave de API em header HTTP"
      }
    }
  }
}