{"openapi": "3.0.3", "info": {"title": "Grooven Platform Events Webhook", "description": "Webhook para receber eventos de plataformas externas (e-commerce, ERP, CRM) e enviar templates WhatsApp automaticamente. As mensagens são logadas no histórico de conversas para continuidade.", "version": "1.0.0", "contact": {"name": "Grooven", "url": "https://grooven.ai", "email": "dev@grooven.ai"}}, "servers": [{"url": "https://events.grooven.ai", "description": "Production"}, {"url": "https://qo4l8uus46.execute-api.us-east-2.amazonaws.com", "description": "Production (Alternative)"}], "security": [{"ApiKeyAuth": []}], "paths": {"/": {"post": {"summary": "Enviar evento de plataforma", "description": "Recebe um evento de plataforma externa e envia um template WhatsApp para o cliente. A mensagem é automaticamente logada no histórico de conversas.", "operationId": "sendPlatformEvent", "tags": ["Events"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PlatformEvent"}, "examples": {"purchase_completed": {"summary": "Compra finalizada", "value": {"event_type": "purchase_completed", "customer": {"name": "João Silva", "phone": "5511999999999"}, "template": {"name": "compra_confirmada", "language": "pt_BR", "components": [{"type": "body", "parameters": [{"type": "text", "text": "João"}, {"type": "text", "text": "#12345"}, {"type": "text", "text": "R$ 299,90"}]}]}, "metadata": {"order_id": "12345", "total": 299.9, "source": "nuvemshop"}}}, "cart_abandoned": {"summary": "Carrinho abandonado", "value": {"event_type": "cart_abandoned", "customer": {"name": "Maria Santos", "phone": "5521988887777"}, "template": {"name": "carrinho_abandonado", "language": "pt_BR"}, "metadata": {"cart_id": "abc123", "cart_value": 450.0, "source": "shopify"}}}, "appointment_reminder_named_params": {"summary": "Lembrete com variáveis nomeadas (named params)", "description": "Use este formato quando o template aprovado na Meta usa variáveis nomeadas (ex.: `{{nome_paciente}}`). Sem o campo `parameter_name` a Meta retorna erro `(#100) Parameter name is missing or empty`. O nome em cada `parameter_name` deve bater exatamente com o nome declarado no body do template.", "value": {"event_type": "appointment_reminder", "customer": {"name": "Marcio Galhango de Menezes", "phone": "5511984012234"}, "template": {"name": "lembrete_no_dia", "language": "pt_BR", "components": [{"type": "body", "parameters": [{"type": "text", "parameter_name": "nome_paciente", "text": "Marcio Galhango de Menezes"}, {"type": "text", "parameter_name": "hoje_ou_amanha", "text": "hoje"}, {"type": "text", "parameter_name": "horario_da_consulta", "text": "13:15"}, {"type": "text", "parameter_name": "pronome_medico", "text": "Dr."}, {"type": "text", "parameter_name": "nome_medico", "text": "Profissional Teste"}]}]}, "metadata": {"atendimento_id": "48"}}}, "hubspot_flat": {"summary": "Formato flat (HubSpot)", "description": "Formato simplificado para integrações que não suportam JSON aninhado", "value": {"event_type": "meeting_scheduled", "customer_name": "João Silva", "customer_phone": "5511999999999", "template_name": "reuniao_agendada", "template_language": "pt_BR"}}}}}}, "responses": {"200": {"description": "Evento processado com sucesso", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SuccessResponse"}}}}, "400": {"description": "Erro de validação ou processamento", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "401": {"description": "API key inválida ou ausente", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "429": {"description": "Rate limit excedido", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}}}, "get": {"summary": "Documentação OpenAPI", "description": "Retorna a especificação OpenAPI desta API", "operationId": "getOpenApiSpec", "tags": ["Documentation"], "security": [], "responses": {"200": {"description": "OpenAPI specification", "content": {"application/json": {"schema": {"type": "object"}}}}}}}}, "components": {"securitySchemes": {"ApiKeyAuth": {"type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key da organização. Gere em Configurações > Integrações > API Keys"}}, "schemas": {"PlatformEvent": {"type": "object", "required": ["event_type", "customer", "template"], "properties": {"event_type": {"type": "string", "description": "Tipo do evento", "enum": ["purchase_completed", "payment_approved", "payment_failed", "payment_pending", "order_shipped", "order_delivered", "cart_abandoned", "review_request", "appointment_reminder", "appointment_confirmed", "appointment_cancelled", "invoice_sent", "payment_due", "custom"]}, "customer": {"$ref": "#/components/schemas/Customer"}, "template": {"$ref": "#/components/schemas/Template"}, "contact_id": {"type": "string", "format": "uuid", "description": "ID do contato no CRM Grooven (opcional, para tracking)"}, "metadata": {"type": "object", "description": "Dados extras para logging e contexto", "additionalProperties": true}}}, "Customer": {"type": "object", "required": ["phone"], "properties": {"name": {"type": "string", "description": "Nome do cliente", "example": "João Silva"}, "phone": {"type": "string", "description": "Telefone WhatsApp com DDI (apenas números)", "example": "5511999999999", "pattern": "^[0-9]{10,15}$"}}}, "Template": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string", "description": "Nome do template Meta aprovado", "example": "compra_confirmada"}, "language": {"type": "string", "description": "Código do idioma", "default": "pt_BR", "example": "pt_BR"}, "body": {"type": "string", "description": "Texto do body para logging (opcional)"}, "components": {"type": "array", "description": "Parâmetros do template", "items": {"$ref": "#/components/schemas/TemplateComponent"}}}}, "TemplateComponent": {"type": "object", "required": ["type"], "properties": {"type": {"type": "string", "enum": ["header", "body", "button"], "description": "Tipo do componente"}, "parameters": {"type": "array", "description": "Lista de parâmetros do componente. A ORDEM deve corresponder à ordem das variáveis no body do template aprovado. Para templates com variáveis nomeadas (ex.: `{{nome_paciente}}`), cada parâmetro DEVE ter `parameter_name` preenchido.", "items": {"$ref": "#/components/schemas/TemplateParameter"}}, "sub_type": {"type": "string", "enum": ["quick_reply", "url"], "description": "Sub-tipo para botões"}, "index": {"type": "integer", "description": "Índice do botão (0, 1, 2)"}}}, "TemplateParameter": {"type": "object", "required": ["type"], "description": "Parâmetro de variável do template. **IMPORTANTE — named vs positional**: Templates Meta aprovados a partir de 2024 podem usar variáveis nomeadas (ex.: `{{nome_paciente}}`) em vez de posicionais (`{{1}}`, `{{2}}`). Se o template usa variáveis nomeadas, **é obrigatório incluir o campo `parameter_name`** em cada parâmetro — sem isso a Meta retorna `(#100) Parameter name is missing or empty`. Veja o exemplo `appointment_reminder` no endpoint POST `/` ou consulte https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages#named-parameters.", "properties": {"type": {"type": "string", "enum": ["text", "currency", "date_time", "image", "document", "video"], "description": "Tipo do parâmetro"}, "parameter_name": {"type": "string", "description": "Nome da variável no template (obrigatório quando o template usa named parameters como `{{nome_paciente}}`). Deve bater EXATAMENTE com o nome declarado no body do template aprovado na Meta. Omita este campo apenas se o template usa parâmetros posicionais (`{{1}}`, `{{2}}`, …).", "example": "nome_paciente"}, "text": {"type": "string", "description": "Valor de texto"}, "currency": {"type": "object", "properties": {"fallback_value": {"type": "string"}, "code": {"type": "string"}, "amount_1000": {"type": "integer"}}}, "date_time": {"type": "object", "properties": {"fallback_value": {"type": "string"}}}, "image": {"type": "object", "properties": {"link": {"type": "string", "format": "uri"}}}}}, "SuccessResponse": {"type": "object", "properties": {"success": {"type": "boolean", "example": true}, "data": {"type": "object", "properties": {"conversation_id": {"type": "string", "format": "uuid"}, "message_sent": {"type": "boolean"}, "template": {"type": "string"}, "event_type": {"type": "string"}}}}}, "ErrorResponse": {"type": "object", "properties": {"success": {"type": "boolean", "example": false}, "error": {"type": "string", "description": "Mensagem de erro"}}}}}, "tags": [{"name": "Events", "description": "Endpoints para envio de eventos de plataforma"}, {"name": "Documentation", "description": "Documentação da API"}]}