{"openapi":"3.1.0","info":{"title":"Genio Hub API","version":"1.0.0","description":"API do Genio Hub para integrar o Instagram oficial (Meta) ao seu sistema. Cada chave acessa só a própria conta e só os endpoints das permissões dela.\n\n- **400** Requisição inválida: JSON inválido ou campo fora do formato. O corpo traz issues com o campo e o motivo.\n- **401** Não autenticado: Chave ausente ou inválida. Envie Authorization: Bearer gk_live_...\n- **403** Sem permissão: A chave não tem a permissão do endpoint, ou a conta do Instagram está desconectada.\n- **404** Endpoint inexistente: Confira o caminho na lista de endpoints.\n- **405** Método errado: Use o método indicado (GET ou POST).\n- **429** Limite atingido: Cota de publicação esgotada ou limite da Meta. Tente de novo mais tarde.\n- **4xx/5xx da Meta** Erro repassado da Meta: Quando a Meta recusa, devolvemos o mesmo status e o corpo original dela."},"servers":[{"url":"https://hub.genialise.com/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Conta"},{"name":"Direct"},{"name":"Comentários"},{"name":"Publicação"},{"name":"Estatísticas"}],"paths":{"/me":{"get":{"operationId":"me","tags":["Conta"],"summary":"Conta da chave","description":"Retorna a conta do Instagram ligada à chave, o modo de atendimento e as permissões da chave. Útil para testar a integração.\n\nNão exige permissão específica.","responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"instance_id":"4b0b6f0e-2c1f-4a51-9a0e-6c2a7d1e9f10","ig_user_id":"17841400000000000","username":"sualoja","account_type":"BUSINESS","mode":"hybrid","scopes":["messages:send","comments:reply","media:publish","media:read","insights:read"]}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/send":{"post":{"operationId":"send","tags":["Direct"],"summary":"Enviar Direct","description":"Envia uma mensagem de texto no Direct para quem falou com a conta nas últimas 24 horas. Aceita um botão de link opcional.\n\nPermissão da chave: `messages:send`.\n\nFora da janela de 24 horas a Meta recusa o envio com erro 400.","responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"recipient_id":"6812345678901234","message_id":"aWdfZAG1faWQ6MTc4NDE0MDA..."}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_id":{"type":"string","description":"ID da pessoa no Instagram (IGSID), recebido no webhook de mensagens."},"text":{"type":"string","description":"Texto da mensagem. Até 1.000 caracteres."},"button_title":{"type":"string","description":"Título do botão (até 20 caracteres). Exige button_url."},"button_url":{"type":"string","format":"uri","description":"Link aberto pelo botão."}},"required":["recipient_id","text"]},"example":{"recipient_id":"6812345678901234","text":"Olá! Segue o nosso catálogo.","button_title":"Ver catálogo","button_url":"https://sualoja.com/catalogo"}}}}}},"/private-reply":{"post":{"operationId":"privateReply","tags":["Comentários"],"summary":"Responder comentário no Direct","description":"Envia uma mensagem privada no Direct para quem comentou um post ou reel. Uma resposta privada por comentário, em até 7 dias.\n\nPermissão da chave: `comments:reply`.\n\nA Meta limita as respostas privadas por conta por hora. Picos acima do limite devolvem erro de limite: tente de novo mais tarde.","responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"recipient_id":"6812345678901234","message_id":"aWdfZAG1faWQ6MTc4NDE0MDA..."}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"comment_id":{"type":"string","description":"ID do comentário, recebido no webhook comments."},"text":{"type":"string","description":"Texto da mensagem. Até 1.000 caracteres."},"button_title":{"type":"string","description":"Título do botão (até 20 caracteres). Exige button_url."},"button_url":{"type":"string","format":"uri","description":"Link aberto pelo botão."}},"required":["comment_id","text"]},"example":{"comment_id":"17890000000000000","text":"Te mandei o link aqui! 💌","button_title":"Abrir link","button_url":"https://sualoja.com/oferta"}}}}}},"/comment-reply":{"post":{"operationId":"commentReply","tags":["Comentários"],"summary":"Responder comentário publicamente","description":"Publica uma resposta visível no próprio comentário.\n\nPermissão da chave: `comments:reply`.","responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"id":"17891111111111111"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"comment_id":{"type":"string","description":"ID do comentário."},"text":{"type":"string","description":"Texto da resposta. Até 2.200 caracteres."}},"required":["comment_id","text"]},"example":{"comment_id":"17890000000000000","text":"Enviamos no seu Direct! 💌"}}}}}},"/publish":{"post":{"operationId":"publish","tags":["Publicação"],"summary":"Publicar ou agendar","description":"Publica imagem, reel, story ou carrossel a partir de URLs públicas. Com scheduled_at no futuro, o post é agendado e a resposta é 202.\n\nPermissão da chave: `media:publish`.\n\nSem scheduled_at, a publicação é imediata e a resposta é { id, config_issue }.\n\nconfig_issue vem preenchido quando a Meta publica sem aplicar algo, por exemplo CAPTION_NOT_ATTACHED. Confira antes de considerar o post perfeito.\n\nAntes de publicar, a cota diária da conta é conferida. Sem cota, a resposta é 429.","responses":{"200":{"description":"Publicado na hora (sem scheduled_at)","content":{"application/json":{"example":{"id":"17900000000000000","config_issue":null}}}},"202":{"description":"Sucesso","content":{"application/json":{"example":{"scheduled_post_id":"9a7c2e10-55b1-4d8e-8f0e-1b2c3d4e5f60","status":"pending","scheduled_at":"2026-11-01T21:00:00.000Z"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["IMAGE","REELS","STORIES","CAROUSEL"],"description":"Tipo da publicação."},"url":{"type":"string","format":"uri","description":"Atalho para um único arquivo (IMAGE, REELS e STORIES)."},"items":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"kind":{"type":"string","enum":["image","video"]}},"required":["url"]},"description":"Arquivos do carrossel (2 a 10). kind = image | video; se omitido, .mp4 e .mov viram vídeo."},"caption":{"type":"string","description":"Legenda (até 2.200 caracteres). Ignorada em stories."},"scheduled_at":{"type":"string","format":"date-time","description":"Data e hora com fuso, por exemplo 2026-11-01T18:00:00-03:00."}},"required":["type"]},"example":{"type":"CAROUSEL","items":[{"url":"https://cdn.sualoja.com/1.jpg"},{"url":"https://cdn.sualoja.com/2.mp4"}],"caption":"Nova coleção ✨","scheduled_at":"2026-11-01T18:00:00-03:00"}}}}}},"/media":{"get":{"operationId":"media","tags":["Publicação"],"summary":"Listar publicações","description":"Lista as publicações mais recentes da conta, com legenda, tipo e link.\n\nPermissão da chave: `media:read`.","responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":[{"id":"17900000000000000","caption":"Nova coleção ✨","media_type":"CAROUSEL_ALBUM","media_product_type":"FEED","permalink":"https://www.instagram.com/p/XXXX/","timestamp":"2026-10-26T15:00:00+0000"}]}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/publishing-limit":{"get":{"operationId":"publishingLimit","tags":["Publicação"],"summary":"Cota de publicação","description":"Mostra quantas publicações a conta já usou nas últimas 24 horas e o total permitido pela Meta.\n\nPermissão da chave: `media:read`.","responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"data":[{"quota_usage":3,"config":{"quota_total":50,"quota_duration":86400}}]}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/insights":{"get":{"operationId":"insights","tags":["Estatísticas"],"summary":"Estatísticas","description":"Métricas da conta (alcance, visualizações, interações, seguidores), das últimas publicações e números da própria plataforma no período.\n\nPermissão da chave: `insights:read`.\n\nOs dados da Meta ficam em cache por 10 minutos por conta e período.","responses":{"200":{"description":"Sucesso","content":{"application/json":{"example":{"days":7,"since":"2026-10-19","until":"2026-10-26","account":{"followers":12840,"mediaCount":312,"metrics":{"reach":45210,"views":98110,"total_interactions":3120,"accounts_engaged":2210}},"media":[{"id":"17900000000000000","type":"REELS","caption":"Nova coleção ✨","permalink":"https://www.instagram.com/reel/XXXX/","thumbnail":null,"timestamp":"2026-10-25T18:00:00+0000","metrics":{"reach":8100,"likes":640,"comments":88,"saved":52,"shares":31}}],"platform":{"directReceived":420,"aiReplies":310,"commentDms":690,"queuePending":0},"cachedAt":"2026-10-26T15:30:00.000Z"}}}},"400":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erro","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"days","in":"query","required":false,"description":"Período em dias. Padrão: 7.","schema":{"type":"integer","enum":[7,30]}}]}}},"webhooks":{"instagramEvent":{"post":{"summary":"Evento do Instagram repassado ao seu sistema","description":"Nos modos API e Híbrido, cada evento (mensagens, comentários, postbacks, leituras) chega ao seu endpoint no formato original da Meta, com o campo extra `genial`. Cabeçalhos: `X-Genial-Event`, `X-Genial-Delivery` e `X-Genial-Signature: t=<unix>,v1=<hex>`, onde v1 = HMAC-SHA256(segredo do webhook, \"{t}.{corpo bruto}\"). Responda 2xx em até 10 s.","requestBody":{"content":{"application/json":{"example":{"object":"instagram","entry":[{"id":"17841400000000000","time":1761490000000,"messaging":[{"sender":{"id":"6812345678901234"},"recipient":{"id":"17841400000000000"},"timestamp":1761490000000,"message":{"mid":"aWdfZAG1faWQ6MTc4NDE0MDA...","text":"Oi! Qual o preço?"}}]}],"genial":{"instance_id":"4b0b6f0e-2c1f-4a51-9a0e-6c2a7d1e9f10","field":"messages","ig_user_id":"17841400000000000","username":"sualoja"}}}}},"responses":{"200":{"description":"Recebido"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"gk_live_..."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":"integer"},"issues":{"type":"array","items":{"type":"object"}}}}},"example":{"error":{"message":"This API key does not have the media:publish scope.","type":"GenialApiException","code":403}}}}}}