Documentação Técnica — Vocalizador Conectores

1. Visão Geral

O Vocalizador Conectores é a ponte técnica entre canais externos de atendimento e o AtendenteAI. Ele recebe eventos das plataformas, normaliza os dados, registra logs técnicos e permite que o AtendenteAI responda pelo canal correto em nome da empresa autorizada.

Nesta versão, o módulo Meta contempla Instagram Direct e Facebook Messenger, ambos com recebimento via webhook e envio real pela Graph API da Meta.

O módulo de E-mail também está disponível, com conexão oficial para Gmail e Google Workspace por OAuth 2.0 e conexão universal para contas profissionais por IMAP/SMTP.

No fluxo de e-mail, o AtendenteAi atua como ferramenta de apoio: monitora mensagens autorizadas, identifica solicitações de clientes, consulta a base de conhecimento e elabora uma resposta sugerida. O envio não é automático e depende de revisão e aprovação humana.

2. Fluxo Operacional

3. Canais Meta Ativos

4. Cadastro Multiempresa

As empresas autorizadas no app Meta são registradas no arquivo:

/app/data/empresas_meta.json

Exemplo de estrutura:

{
  "rclojaoficial": {
    "nome": "RC LOJA",
    "ativo": true,
    "facebook": {
      "ativo": true,
      "page_id": "769644979842505",
      "token_env": "FACEBOOK_TOKEN_RCLOJAOFICIAL",
      "webhook_url": "https://conectores.vocalizador.com/webhooks/facebook"
    },
    "instagram": {
      "ativo": true,
      "instagram_account_id": "17841450707985248",
      "token_env": "INSTAGRAM_TOKEN_RCLOJAOFICIAL",
      "webhook_url": "https://conectores.vocalizador.com/webhooks/instagram"
    }
  }
}

5. Endpoints Internos para o AtendenteAI

Enviar resposta para Instagram

POST /instagram/send
Header: X-Conectores-Token: TOKEN_INTERNO

{
  "empresa_id": "rclojaoficial",
  "recipient_id": "ID_DO_CLIENTE_NO_INSTAGRAM",
  "mensagem": "Texto da resposta gerada pela IA"
}

Enviar resposta para Facebook Messenger

POST /facebook/send
Header: X-Conectores-Token: TOKEN_INTERNO

{
  "empresa_id": "rclojaoficial",
  "recipient_id": "ID_DO_CLIENTE_NO_MESSENGER",
  "mensagem": "Texto da resposta gerada pela IA"
}

O campo empresa_id define qual token será usado. O campo recipient_id é obtido no webhook recebido da Meta, normalmente pelo sender_id do cliente.

6. Endpoints de Monitoramento

7. Como Ativar uma Nova Empresa

1. Adicionar ou confirmar a empresa/página no app Meta.
2. Gerar o Page Access Token do Instagram e/ou Facebook Messenger.
3. Salvar o token como variável de ambiente no docker-compose.yml.
4. Cadastrar a empresa e os canais em data/empresas_meta.json.
5. Assinar a página nos campos corretos do webhook, como messages para Messenger.
6. Reiniciar o container.
7. Validar /meta/status, recebimento via webhook e envio real.

8. Segurança

• Os endpoints internos de envio usam X-Conectores-Token.
• Tokens reais da Meta não aparecem na documentação, no admin nem nos endpoints de status.
• O appsecret_proof é calculado automaticamente usando META_APP_SECRET.
• Logs registram eventos e IDs técnicos, mas não devem expor tokens.

9. Endpoints Oficiais do AtendenteAI

Para fechar o ciclo automático de atendimento, o Vocalizador Conectores deverá chamar endpoints oficiais no AtendenteAI. Esses endpoints serão responsáveis por receber a mensagem normalizada, processar IA, RAG, regras comerciais, histórico e devolver a ação esperada.

Endpoint principal — Mensagem recebida dos Conectores

POST https://atendenteai.com.br/api/v1/conectores/mensagem

Este endpoint universal será usado para mensagens recebidas via Instagram Direct, Facebook Messenger, Telegram e futuros canais integrados ao Vocalizador Conectores.

Payload enviado pelo Conector

{
  "empresa_id": "rclojaoficial",
  "canal": "facebook",
  "evento": "mensagem_recebida",
  "conversation_id": "facebook:769644979842505:27688024324154357",
  "message_id": "mid.facebook.exemplo",
  "sender_id": "27688024324154357",
  "recipient_id": "769644979842505",
  "texto": "Olá, gostaria de saber mais sobre os perfumes.",
  "timestamp": "2026-07-08T13:06:58.884935+00:00",
  "raw": {
    "facebook_page_id": "769644979842505",
    "instagram_account_id": null
  }
}

Resposta esperada do AtendenteAI — responder automaticamente

{
  "status": "ok",
  "acao": "responder",
  "mensagem": "Olá! Claro, posso te ajudar. Você procura perfume feminino, masculino ou unissex?",
  "transferir_humano": false,
  "motivo": null,
  "tags": ["lead", "produto", "perfumaria"],
  "resumo_atendimento": "Cliente pediu informações sobre perfumes."
}

Resposta esperada do AtendenteAI — não responder automaticamente

{
  "status": "ok",
  "acao": "nao_responder",
  "mensagem": null,
  "transferir_humano": true,
  "motivo": "Cliente pediu atendimento humano.",
  "tags": ["humano", "prioridade"],
  "resumo_atendimento": "Cliente solicitou atendimento humano."
}

Headers de segurança

X-AtendenteAI-Token: TOKEN_INTERNO_FORTE

O token interno deve ser configurado por variável de ambiente no Conector e validado pelo AtendenteAI. Tokens da Meta nunca devem ser enviados para o AtendenteAI.

Variáveis recomendadas no Conector

ATENDENTEAI_WEBHOOK_URL=https://atendenteai.com.br/api/v1/conectores/mensagem
ATENDENTEAI_WEBHOOK_TOKEN=TOKEN_INTERNO_FORTE
ATENDENTEAI_AUTO_REPLY=false

10. Endpoints Oficiais por Módulo Futuro

Para manter padrão técnico e facilitar expansão, todos os próximos canais devem seguir a mesma estrutura de API:

Endpoints complementares recomendados

O placeholder {canal} deve ser substituído por meta, telegram, mercadolivre, shopee, tiktokshop ou outro canal oficial.

11. Módulo de E-mail — Gmail, Microsoft 365 e IMAP/SMTP

11.1. Objetivo do módulo

O módulo de E-mail permite que uma empresa conecte uma caixa empresarial ao AtendenteAi para monitorar mensagens novas, identificar contatos de clientes e elaborar respostas sugeridas com base nas regras, na identidade e na base de conhecimento configuradas pela empresa.

O serviço não foi criado para substituir o Gmail, o Outlook, o Webmail ou a caixa de origem. Seu objetivo é funcionar como uma camada temporária de triagem, inteligência e apoio ao atendimento.

11.2. Provedores disponíveis

11.3. Fluxo funcional OAuth — Gmail e Microsoft 365

A senha da conta Google ou Microsoft nunca é recebida pelo AtendenteAi ou pelo Vocalizador Conectores. A autorização ocorre diretamente na tela oficial do respectivo provedor.

11.4. Escopos Google utilizados

11.5. Triagem e geração da resposta sugerida

11.6. Regra de aprovação humana

No módulo de E-mail, nenhuma resposta sugerida é enviada automaticamente. A sugestão deve ser apresentada no AtendenteAi para revisão.

Os estados recomendados para o atendimento são:

recebida
classificada
sugestao_gerada
aguardando_revisao
aprovada
enviada

Estados alternativos:
rejeitada
descartada
expirada
erro_envio

O endpoint universal do AtendenteAi ainda deverá implementar a interface definitiva para receber a mensagem, apresentar a sugestão ao operador e devolver a aprovação ao Conector.

11.7. Contexto de conversa e encadeamento

A continuidade de uma conversa não deve depender apenas do texto visualmente citado em mensagens com assunto iniciado por “Re:”.

Os principais identificadores são:

• message_id: identifica uma mensagem específica;
• thread_id: identifica o conjunto de mensagens da conversa;
• conversation_id: identificador interno multiempresa do AtendenteAi;
• In-Reply-To: referencia a mensagem respondida;
• References: preserva o encadeamento entre mensagens.

Quando for necessário gerar uma nova sugestão, o sistema poderá consultar novamente a thread diretamente na conta de origem, desde que a autorização continue ativa.

11.8. Retenção e minimização de dados

O AtendenteAi não mantém uma cópia permanente da caixa de e-mail. Sempre que possível, são armazenados somente identificadores operacionais.

Conteúdos temporários podem ser eliminados antes de 30 dias quando o atendimento for concluído, rejeitado, descartado ou deixar de ser necessário.

11.9. Uso de inteligência artificial

O conteúdo estritamente necessário pode ser enviado ao mecanismo de inteligência artificial usado pelo AtendenteAi para classificar a solicitação e elaborar a resposta sugerida.

Mensagens empresariais não devem ser utilizadas para publicidade, criação de perfis publicitários ou treinamento de modelos gerais de inteligência artificial.

11.10. Segurança e Limited Use

• conexão pública por HTTPS;
• autorização Google por OAuth 2.0;
• senha Google nunca recebida;
• separação lógica por empresa e conta;
• sessões temporárias vinculadas à empresa e à conta autorizada;
• tokens nunca apresentados na interface pública;
• tokens e senhas de e-mail criptografados em repouso com Fernet;
• chave mestre fornecida por EMAIL_CREDENTIALS_KEY fora do código;
• arquivos sensíveis de credenciais, processados e sessões protegidos com permissão 600;
• modo estrito que rejeita credenciais persistidas sem criptografia;
• controle de mensagens processadas com data processed_at;
• eliminação automática dos registros processados após 30 dias;
• limpeza automática das sessões de onboarding expiradas ou inválidas;
• renovação e rotação de tokens com nova gravação criptografada;
• tokens não devem aparecer em logs técnicos;
• corpos completos não devem ser registrados deliberadamente em logs;
• acesso limitado às funcionalidades apresentadas ao usuário;
• retenção máxima de 30 dias para conteúdo temporário;
• nenhum armazenamento de anexos.

O uso e a transferência das informações recebidas das APIs Google devem obedecer à Google API Services User Data Policy, incluindo os requisitos de Limited Use.

Consulte a página pública: Segurança e Dados do Google.

11.11. Arquivo de configuração multiempresa

As contas de e-mail são associadas por empresa e conta em:

/app/data/empresas_email.json

Estrutura conceitual:

{
  "empresa_id": {
    "nome": "Nome da empresa",
    "contas": {
      "conta_id": {
        "ativo": true,
        "provedor": "gmail_google_workspace",
        "email": "conta@empresa.com.br",
        "oauth": {
          "access_token": "PROTEGIDO",
          "refresh_token": "PROTEGIDO",
          "expires_at": "DATA_ISO"
        },
        "gmail": {
          "messages_total": 0,
          "threads_total": 0,
          "history_id": "ID"
        }
      }
    }
  }
}

11.12. Endpoints públicos e técnicos do Gmail e Microsoft 365

11.13. Endpoints IMAP/SMTP

11.14. Sessões temporárias de onboarding

O AtendenteAi pode criar uma sessão temporária para abrir a configuração sem expor o token técnico ao cliente final.

POST /email/onboarding/session
Header: X-Conectores-Token: TOKEN_INTERNO

{
  "empresa_id": "rclojaoficial",
  "nome_empresa": "RCLOJA",
  "conta_id": "sac",
  "nome_conta": "SAC",
  "email_sugerido": "sac@empresa.com.br",
  "ttl_minutes": 60
}

A sessão é vinculada à empresa e à conta informadas e possui prazo de expiração. Ela não deve permitir acesso a outra organização.

11.15. Fluxo com o AtendenteAi principal

As mensagens selecionadas pelo Conector deverão ser encaminhadas para:

POST https://atendenteai.com.br/api/v1/conectores/mensagem

Exemplo conceitual para e-mail:

{
  "empresa_id": "rclojaoficial",
  "canal": "email",
  "evento": "mensagem_recebida",
  "conversation_id": "email:rclojaoficial:sac:THREAD_ID",
  "message_id": "GMAIL_MESSAGE_ID",
  "thread_id": "GMAIL_THREAD_ID",
  "sender_email": "cliente@exemplo.com",
  "subject": "Dúvida sobre um produto",
  "texto": "Conteúdo necessário para análise",
  "timestamp": "DATA_ISO"
}

11.16. Desconexão e exclusão

O fluxo de desconexão implementado:

1. identificar a empresa e a conta conectada;
2. revogar o token junto ao Google, quando aplicável;
3. remover access token e refresh token locais;
4. interromper novas consultas;
5. excluir conteúdos temporários relacionados;
6. registrar auditoria mínima sem conteúdo sensível.

A rota de desconexão remove imediatamente as credenciais locais e tenta revogar o token junto ao Google. A liberação definitiva para clientes externos continua condicionada à homologação e às exigências do Google.

11.17. Controles técnicos de segurança

• Concluído: criptografia Fernet dos tokens OAuth em repouso;
• Concluído: criptografia de senhas IMAP/SMTP persistidas;
• Concluído: chave mestre fora do código e dos arquivos públicos;
• Concluído: modo estrito contra credenciais em texto simples;
• Concluído: renovação e rotação com gravação criptografada;
• Concluído: revogação Google e remoção local na desconexão;
• Concluído: arquivos sensíveis com permissão 600;
• Concluído: retenção automática de registros processados por 30 dias;
• Concluído: registros novos com identificador e processed_at;
• Concluído: compatibilidade com registros legados durante a migração;
• Concluído: limpeza automática de sessões de onboarding expiradas;
• Concluído: teste real Microsoft com bloqueio de reprocessamento duplicado;
• Pendente: revisão contínua dos logs e do acesso administrativo;
• Pendente: procedimento documentado de resposta a incidentes;
• Pendente: homologação externa exigida pelo Google.

11.18. Checklist para verificação Google

1. validar domínio e identidade oficial do aplicativo;
2. configurar a tela de consentimento com nome e logotipo definitivos;
3. publicar página inicial do produto;
4. publicar Política de Privacidade;
5. publicar Termos de Serviço;
6. publicar página de Exclusão de Dados;
7. publicar Segurança e Dados do Google;
8. justificar individualmente os escopos solicitados;
9. gravar vídeo demonstrando o fluxo OAuth completo;
10. mostrar no vídeo onde os dados Gmail são utilizados;
11. demonstrar que a resposta exige aprovação humana;
12. demonstrar desconexão e revogação;
13. fornecer conta ou ambiente de demonstração, quando solicitado;
14. concluir os controles técnicos pendentes;
15. preparar-se para eventual avaliação de segurança aplicável a escopos restritos.

11.19. Páginas públicas relacionadas

• Política de Privacidade
• Termos de Serviço
• Exclusão de Dados
• Segurança e Dados do Google
• Conexão de E-mail

12. Módulo Mercado Livre

12.1. Objetivo

O módulo permite que cada empresa conecte sua própria conta do Mercado Livre ao AtendenteAi. A conexão é isolada por empresa_id, impedindo que uma organização consulte, altere ou desconecte a conta de outra empresa.

12.2. Página protegida da empresa

A página principal do módulo está disponível em:

GET https://conectores.vocalizador.com/mercadolivre

Essa página não deve ser aberta diretamente sem uma sessão válida. Quando não existe o cookie seguro da empresa, o servidor responde com HTTP 401 e apresenta o frontend no estado não autenticado.

O cookie utilizado pelo navegador é:

mercadolivre_session

12.3. Criação do acesso pelo AtendenteAi

O AtendenteAi autenticado deve solicitar um link temporário pelo endpoint interno:

POST /mercadolivre/internal/session
X-Conectores-Token: TOKEN_INTERNO
Content-Type: application/json

{
  "empresa_id": "rclojaoficial"
}

Resposta esperada:

{
  "launch_url": "https://conectores.vocalizador.com/mercadolivre/access/TICKET_TEMPORARIO",
  "expires_in": 60
}

O prazo real é informado em expires_in. O ticket é temporário, de uso único e vinculado exclusivamente à empresa informada.

12.4. Consumo do ticket

O navegador abre o endereço recebido em launch_url:

GET /mercadolivre/access/{ticket}

Após validar e consumir o ticket, o Conector cria ou renova a sessão da empresa, grava o cookie mercadolivre_session e redireciona o navegador para /mercadolivre.

Tickets inválidos, já utilizados ou expirados retornam HTTP 401 com a mensagem sanitizada acesso inválido ou expirado.

12.5. Segurança do frontend

• sessão vinculada ao empresa_id;
• ticket temporário e de uso único;
• autenticação interna por X-Conectores-Token;
• cookie específico para o caminho /mercadolivre;
• proteção CSRF nas operações sensíveis;
• cabeçalhos para impedir cache de respostas sensíveis;
• erros externos sem exposição de tokens ou credenciais.

12.6. OAuth do Mercado Livre

O cliente inicia o processo já autenticado no AtendenteAi e identificado por um empresa_id. O AtendenteAi solicita ao Conector um ticket temporário de uso único e abre no navegador o launch_url do domínio conectores.vocalizador.com. O Conector consome o ticket e preserva internamente sua associação com o empresa_id, sem confiar em uma identificação de empresa fornecida depois pelo navegador.

O cliente é direcionado à página oficial do Mercado Livre e autoriza o aplicativo. O Mercado Livre retorna ao callback do Conector com code e state. No servidor, o Conector valida o estado, troca o código por access_token e refresh_token diretamente com o Mercado Livre e consulta a identidade oficial da conta vendedora. A associação persistida passa a ser empresa_id do AtendenteAi ↔ account_id do Mercado Livre, com estado connected.

Nenhum token é enviado ao navegador ou ao AtendenteAi, nem incluído em URL, log ou payload de resposta. Essa arquitetura isola as empresas, aplica o menor privilégio e reduz a superfície de exposição. Ela também favorece auditorias e validações do aplicativo e impede que uma conta seja usada para responder por outra empresa.

12.6.1. Persistência, validade e renovação dos tokens

O access_token observado possui validade aproximada de seis horas, mas o sistema não depende de um valor fixo: o expires_at oficial retornado pelo Mercado Livre é sempre a fonte de verdade. O access_token, refresh_token, token_type e expires_at são armazenados criptografados em /app/data/mercadolivre_credentials.json. O arquivo mantém os metadados não secretos separados de um bloco encrypted_credentials; a chave de criptografia fica fora do arquivo e fora do Git.

O refresh_token mantém a conexão sem exigir novo login a cada seis horas. Uma verificação periódica é executada a cada 300 segundos, com margem preventiva de 15 minutos. Antes de operações críticas, como consultar, preparar ou publicar uma resposta, a validade também é verificada. Na preparação e na publicação, se restar menos de um minuto, o token é renovado antes da chamada.

Depois da renovação, o novo conjunto de credenciais é criptografado e substitui atomicamente o registro anterior. Se a renovação falhar, nenhuma resposta é publicada. Uma nova autorização manual só é necessária em caso de revogação, refresh_token inválido ou ausente, credencial removida ou falha definitiva de renovação.

12.6.2. Separação de responsabilidades entre as duas VPS

12.6.3. Fluxo completo de ping-pong

A. Conexão

AtendenteAi autenticado
→ POST /mercadolivre/internal/session
→ launch_url temporário
→ página do Conector
→ autorização oficial do Mercado Livre
→ callback no Conector
→ troca de code por tokens
→ associação empresa_id ↔ account_id
→ status connected

B. Pergunta

Comprador faz pergunta
→ Mercado Livre envia notificação ao webhook do Conector
→ Conector valida e deduplica a notificação
→ Conector consulta a pergunta completa na API oficial
→ confirma seller_id, question_id e status UNANSWERED
→ normaliza o evento
→ envia ao endpoint universal do AtendenteAi

C. Resposta

AtendenteAi consulta a base de conhecimento da empresa
→ gera ou apresenta resposta para revisão
→ devolve empresa_id, conta_id, question_id e text ao Conector
→ Conector prepara e valida
→ estado pending, blocked ou manual_review
→ publicação explícita
→ nova consulta remota
→ confirmação de seller e UNANSWERED
→ envio pela API do Mercado Livre
→ estado published

A validação e a deduplicação protegem contra webhook falso, atrasado ou repetido. A revalidação remota imediatamente antes do envio previne resposta por conta errada e resposta duplicada. A separação entre a geração pela IA e a autorização/publicação externa permite revisão humana e produz uma trilha de auditoria sanitizada.

12.7. Rotas principais implantadas

12.8. Barreira de segurança e revisão humana

O processamento de notificações apenas prepara e armazena respostas. Não existe publicação automática: a revisão humana e a aprovação explícita pelo endpoint interno são o modo padrão.

Antes do armazenamento e novamente imediatamente antes do envio, uma barreira determinística classifica a resposta como approved, blocked ou manual_review. A barreira bloqueia dados de contato, direcionamento para canais externos, documentos pessoais e pagamentos externos. Uma resposta alterada de forma relevante nunca é publicada silenciosamente e deve voltar para revisão humana.

Os endpoints internos, protegidos por X-Conectores-Token, são:

GET /marketplaces/mercadolivre/internal/pending-answers?empresa_id={empresa_id}
POST /marketplaces/mercadolivre/internal/pending-answers/prepare
PUT /marketplaces/mercadolivre/internal/pending-answers/review
POST /marketplaces/mercadolivre/internal/pending-answers/publish

prepare aceita exclusivamente empresa_id, conta_id, question_id e text. Tokens não são aceitos no payload e essa operação nunca publica. Se já existir um registro para a mesma identidade, a API retorna HTTP 409 already_exists e não o sobrescreve.

O endpoint de revisão permite confirmar ou substituir exclusivamente o texto de uma resposta em manual_review ou blocked. A identidade formada por empresa_id, conta_id e question_id não pode ser alterada. O texto revisado passa novamente pela barreira determinística e somente uma decisão approved devolve a resposta ao estado pending. A revisão não publica a resposta.

prepared → manual_review → texto revisado → validação → pending → aprovação/publicação

A publicação recebe somente empresa_id, conta_id e question_id. Tokens nunca são aceitos do cliente. O Conector recupera internamente as credenciais criptografadas, renova o token quando necessário, consulta novamente a pergunta, confirma vendedor e estado UNANSWERED, revalida o texto e impede envios duplicados. A publicação exige um registro válido em estado publicável. Depois do envio, o registro passa a published; uma nova tentativa não deve produzir outro envio.

Cada decisão gera auditoria estruturada e sanitizada com empresa, plataforma, conta, pergunta, decisão, regras acionadas, indicador de envio, motivo e timestamp, sem tokens, cookies ou credenciais.

12.9. Evidência do primeiro teste real

Em 14/07/2026, a empresa rclojaoficial, associada à conta vendedora Mercado Livre 28961129, concluiu uma homologação funcional com uma pergunta real identificada pela API no estado UNANSWERED. Para preservar dados pessoais, não são registrados aqui o texto da pergunta, o texto da resposta ou a identidade do comprador.

A resposta foi preparada pela rota interna. A validação retornou decision=approved, publication_status=pending, requires_human_review=false e rule_ids vazio. A publicação explícita retornou published=true e status=published, e a resposta apareceu corretamente no anúncio real. Uma tentativa posterior de preparar novamente o mesmo question_id retornou HTTP 409 Conflict, confirmando o bloqueio de sobrescrita e duplicidade.

12.10. Integração pendente com o AtendenteAi

A parte já disponível no Conector está preparada para receber o empresa_id do AtendenteAi e devolver o launch_url. No AtendenteAi principal ainda será necessário:

1. identificar o empresa_id autenticado;
2. chamar POST /mercadolivre/internal/session;
3. abrir o launch_url retornado;
4. controlar a contratação e a cobrança do módulo adicional;
5. publicar o endpoint universal para receber eventos normalizados;
6. devolver respostas aprovadas para o Conector.

A cobrança e a habilitação comercial do módulo pertencem ao AtendenteAi. O Conector cuida da integração técnica com o Mercado Livre, das credenciais, da sessão e do transporte seguro dos eventos.

13. Mercado Pago — links de cobrança

Disponível O módulo Mercado Pago permite que cada empresa conecte sua própria conta recebedora e gere links do Checkout Pro dentro do atendimento. O dinheiro é processado e depositado pelo Mercado Pago diretamente na conta autorizada; o AtendenteAi não recebe nem retém os valores.

13.1. Recursos disponíveis

• conexão e desconexão segura da conta por OAuth;
• limites, parcelamento e política comercial de acréscimo;
• links gerados pelo painel, por atendentes ou por agentes autorizados;
• identificação de cliente, pedido, conversa, canal e autor;
• status, valor pago, deduções e valor líquido conciliado;
• acesso às movimentações e orientações oficiais do Mercado Pago.

13.2. Atendente humano e agente de IA

No Chat, o atendente seleciona a conversa, revisa cliente, referência, descrição e valor, confirma os dados e gera o link. Ele pode copiar o link ou inseri-lo na mensagem, mas o sistema não o envia automaticamente.

Para a IA, gerar_link_mercado_pago é uma ferramenta nativa e não depende da base de conhecimento da empresa. Ela só aparece com módulo ativo, agente atribuído, conta conectada e autorização para cobranças por agentes. A confirmação explícita do cliente é obrigatória.

13.3. Confirmação e segurança

Criar ou abrir um link não significa que houve pagamento. O status approved só é aceito depois do webhook assinado e da reconciliação autenticada com a API. Tokens OAuth permanecem criptografados no servidor e nunca são enviados ao navegador.

13.4. Endpoints internos

POST   /payments/mercadopago/internal/admin-session
GET    /payments/mercadopago/internal/connections/{empresa_id}
GET    /payments/mercadopago/internal/capabilities/{empresa_id}
PUT    /payments/mercadopago/internal/settings
POST   /payments/mercadopago/internal/charges
GET    /payments/mercadopago/internal/charges/{empresa_id}/{charge_id}
DELETE /payments/mercadopago/internal/connections/{empresa_id}

Todas as rotas internas exigem X-Conectores-Token. Criações também exigem X-Idempotency-Key. Nenhuma rota aceita ou devolve o access token da conta conectada.

13.5. Limites da integração

Meios de pagamento, análise antifraude, tarifas, prazos e antecipações são definidos pelo Mercado Pago e podem variar conforme a conta do recebedor. A política de acréscimo do AtendenteAi é uma decisão comercial da empresa, não uma previsão da tarifa efetiva do provedor.

14. Asaas — cobranças identificadas

Disponível A integração Asaas já autenticou uma conta de testes, criou cliente e cobrança no Sandbox e processou o evento real de teste PAYMENT_RECEIVED, conciliando R$ 5,00 como RECEIVED e R$ 4,01 líquidos. O código multiempresa está publicado. Cada empresa pode conectar sua própria conta em Sandbox ou Produção, mantendo o Sandbox central para homologações controladas.

14.1. Fluxo homologado

• chave da conta protegida e criptografada por empresa;
• API Key e token de webhook exclusivos e cifrados por empresa;
• webhook criado automaticamente com URL opaca por conexão;
• cliente localizado ou criado pela referência interna;
• cobrança a partir de R$ 5,00 com cliente, pedido, conversa e autor;
• pagamento na invoiceUrl hospedada pelo Asaas;
• webhook autenticado, deduplicado e reconciliado por nova consulta à API;
• distinção entre PENDING, CONFIRMED, RECEIVED, OVERDUE e REFUNDED.

14.2. Como cada empresa preparará a conexão

1. entrar na própria conta Asaas pela interface web com um usuário administrador;
2. abrir Menu do usuário → Integrações → Chaves de API;
3. gerar uma chave identificada, por exemplo, como “AtendenteAi Produção”;
4. copiar a chave completa no momento da geração, pois ela é exibida integralmente uma única vez;
5. colar a chave somente no campo protegido em Administração → Recursos → Asaas → Conectar conta;
6. aguardar a validação e o estado Conta conectada.

Produção usa chave iniciada por $aact_prod_; Sandbox usa $aact_hmlg_. A chave nunca deve ser enviada por WhatsApp, chat, e-mail, chamado, base de conhecimento ou mensagem a atendentes. Em caso de exposição, a empresa deve desativá-la no Asaas e gerar outra. O AtendenteAi não solicita senha da conta, código de verificação, dados bancários ou token de ação crítica para essa conexão. Consulte a documentação oficial do Asaas.

14.3. Endpoints

GET    /payments/asaas/status
POST   /payments/asaas/internal/connections/bootstrap
POST   /payments/asaas/internal/connections
GET    /payments/asaas/internal/connections/{empresa_id}
DELETE /payments/asaas/internal/connections/{empresa_id}
POST   /payments/asaas/internal/charges
GET    /payments/asaas/internal/charges/{empresa_id}/{charge_id}
POST   /payments/asaas/internal/admin-session
POST   /payments/asaas/webhook
POST   /payments/asaas/webhook/{connection_id}

14.4. Limites atuais

Cobranças por agentes, transferências, saques, Pix de saída, subcontas, assinaturas e armazenamento de cartões permanecem desativados. Abrir o link não confirma recebimento; somente a conciliação autenticada altera o estado financeiro.

15. Próximos Módulos

O Mercado Livre já teve consulta, preparação e publicação real validadas. A próxima etapa é conectar o fluxo automático ao endpoint universal do AtendenteAi e validar o recebimento por webhook. Depois será iniciado o módulo Shopee, seguido pelo TikTok Shop. A homologação Google permanece como atividade paralela.

Endpoints oficiais entre Conectores e AtendenteAI

A arquitetura dos conectores foi organizada para manter o AtendenteAI como o cérebro da operação e o Conector Vocalizador como a ponte técnica entre os canais externos e a inteligência artificial.

1. Entrada de mensagens no AtendenteAI

Toda mensagem recebida por Instagram, Facebook, Telegram e futuros canais deve ser normalizada pelo conector e enviada para um endpoint universal no AtendenteAI.

POST https://atendenteai.com.br/api/v1/conectores/mensagem

Headers recomendados:

Content-Type: application/json
X-AtendenteAI-Token: TOKEN_SEGURO_DO_ATENDENTEAI

Payload padrão:

{
  "empresa_id": "rclojaoficial",
  "canal": "telegram",
  "evento": "mensagem_recebida",
  "conversation_id": "telegram:8532544760:7308874092",
  "message_id": "123",
  "sender_id": "7308874092",
  "recipient_id": "7308874092",
  "texto": "Olá, quero saber mais informações",
  "timestamp": "2026-07-08T18:54:29Z",
  "raw": {}
}

Esse formato permite que o AtendenteAI trate todos os canais de forma padronizada, sem precisar conhecer os detalhes técnicos de cada API externa.

2. Resposta do AtendenteAI para o Conector

Após processar a mensagem, consultar a base de conhecimento e gerar a resposta, o AtendenteAI deve devolver a mensagem para o Conector Vocalizador por um endpoint universal.

POST https://conectores.vocalizador.com/internal/reply

Headers recomendados:

Content-Type: application/json
X-Conectores-Token: TOKEN_SEGURO_DOS_CONECTORES

Payload padrão:

{
  "empresa_id": "rclojaoficial",
  "canal": "telegram",
  "conversation_id": "telegram:8532544760:7308874092",
  "recipient_id": "7308874092",
  "message_text": "Olá! Posso te ajudar com mais informações. O que você procura hoje?"
}

O conector identifica o canal e a empresa, localiza o token correto da empresa cadastrada e envia a resposta pelo canal original.

3. Endpoints técnicos por canal

Além do endpoint universal de resposta, o conector mantém endpoints técnicos por canal para testes, diagnóstico e fallback operacional.

POST https://conectores.vocalizador.com/telegram/send
POST https://conectores.vocalizador.com/instagram/send
POST https://conectores.vocalizador.com/facebook/send

4. Regra profissional de identidade da empresa

Cada empresa deve utilizar suas próprias credenciais e, no caso do Telegram, seu próprio bot. Assim, o cliente final conversa com a empresa procurada, e não com um bot genérico do AtendenteAI.

Cliente → @CasaDasBateriasBot
Conector → AtendenteAI
AtendenteAI → Conector
@CasaDasBateriasBot → Cliente

O AtendenteAI atua como motor de inteligência e atendimento. A identidade pública continua sendo a da empresa contratante.

5. Padrão de conversation_id

O conversation_id deve identificar canal, origem da empresa e cliente final.

telegram:<bot_id_da_empresa>:<chat_id_do_cliente>
instagram:<instagram_account_id>:<sender_id_do_cliente>
facebook:<page_id_da_empresa>:<sender_id_do_cliente>

Esse padrão permite histórico separado por empresa, canal e cliente.

Status do dispatch universal de respostas

O endpoint POST /internal/reply é o caminho oficial para o AtendenteAI devolver respostas ao Conector Vocalizador. A partir dele, o conector identifica o canal, a empresa e o destinatário, usando as credenciais cadastradas da própria empresa.

Status atual por canal

Exemplo de resposta Telegram pelo /internal/reply

POST https://conectores.vocalizador.com/internal/reply

{
  "empresa_id": "rclojaoficial",
  "canal": "telegram",
  "conversation_id": "telegram:8532544760:7308874092",
  "message_text": "Olá! Essa é uma resposta gerada pelo AtendenteAI."
}

No Telegram, o conector consegue extrair o chat_id pelo conversation_id. Também é possível enviar recipient_id ou chat_id diretamente no payload.

Regra de identidade

A resposta sempre deve sair pelo canal da empresa contratante. No Telegram, isso significa usar o bot/token cadastrado daquela empresa, evitando que o cliente final receba resposta de um bot genérico.

Cliente → @BotDaEmpresa
Conector → AtendenteAI
AtendenteAI → Conector
@BotDaEmpresa → Cliente