Este tópico trata do recebimento de informações enviadas pelo HubSpot para o Tolky.

O objetivo desta documentação é orientar você, cliente, a configurar fluxos de trabalho (workflows) ou webhooks no seu HubSpot para que, sempre que um ticket ou deal (negócio) for criado ou atualizado, os dados sejam enviados automaticamente para as rotas internas do Tolky, seguindo o modelo combinado.

Ou seja, a integração parte do seu HubSpot, que envia os dados para o Tolky.

A API do back-end Tolky expõe rotas internas para integração com HubSpot, permitindo o recebimento de dados de tickets, deals (negócios) e objetos personalizados. Essas rotas cuidam da autenticação, enriquecimento dos dados e encaminhamento para processamento, retornando o resultado final ao cliente.

Importante:

  • Quando você envia um deal do HubSpot, ele é tratado como um lead na plataforma Tolky.
  • Quando você envia um ticket, ele é tratado como ticket.
  • Quando você envia um object (objeto personalizado), ele pode ser convertido em lead ou ticket dentro do Tolky, conforme o mapeamento previamente combinado no projeto.

​
⚠️ Payload Estruturado e Acordado

Atenção: O objeto JSON enviado para estas rotas deve ser exatamente o objeto previamente mapeado e acordado com o cliente. Não altere, remova ou adicione campos arbitrariamente. O formato do payload foi definido em conjunto com o cliente e o HubSpot, garantindo que todos os campos necessários para o correto mapeamento e salvamento no banco estejam presentes e com os nomes corretos.

​
Rotas Disponíveis

  • POST /api/integrations/hubspot/internal/tickets
    • Para receber e processar tickets (chamados) enviados a partir de fluxos configurados no HubSpot do cliente.
  • POST /api/integrations/hubspot/internal/deals
    • Para receber e processar deals (negócios) enviados a partir de fluxos configurados no HubSpot do cliente.
  • POST /api/integrations/hubspot/internal/objects
    • Para receber e processar objetos personalizados enviados a partir de fluxos configurados no HubSpot do cliente. O objeto será convertido em lead ou ticket dentro do Tolky, conforme o acordo do projeto.

​
Como Funciona

  1. No seu HubSpot, configure um fluxo de trabalho (workflow) ou webhook para enviar os dados do ticket ou deal para a rota do Tolky (veja exemplos abaixo).
  2. O JSON enviado deve seguir exatamente o modelo acordado com o Tolky.
  3. Não é necessário enviar hostId ou hostSlug – a API preenche automaticamente após autenticação.
  4. A API do Tolky processa e retorna o resultado do processamento, ou um erro detalhado.

​
Exemplo de Request

​
Ticket

POST /api/integrations/hubspot/internal/tickets
Content-Type: application/json

{
  "email": "maria.souza@empresa.com",
  "content": "Solicitação de suporte para acesso ao sistema",
  "subject": "Maria Souza - Problema de acesso",
  "lastname": "Souza",
  "firstname": "Maria",
  "createdate": 1745358901234,
  "external_id": 9988776655,
  "mobilephone": "+5521998765432",
  "campus_unifenas": "Alfenas",
  "hs_pipeline_stage": 2041958559
}

​
Deal

POST /api/integrations/hubspot/internal/deals
Content-Type: application/json

{
  "cep": "12345-678",
  "cpf": "987.654.321-00",
  "rua": "Rua das Flores",
  "sexo": "Feminino",
  "email": "maria.souza@empresa.com",
  "bairro": "Centro",
  "cidade": "Rio de Janeiro",
  "estado": "Rio de Janeiro",
  "unidade": "Unidade Central",
  "dealname": "Maria Souza - Novo Deal",
  "lastname": "Souza",
  "dealstage": 58130978,
  "firstname": "Maria",
  "complemento": "Apto 101",
  "external_id": 8877665544,
  "mobilephone": "+5521998765432",
  "nome_da_m_e": "Fernanda",
  "date_of_birth": "1988-03-22",
  "tipo_ingresso": "Presencial",
  "local_da_prova": "Sala 12",
  "numero_endereco": "100",
  "generalinstructions": "Atender com prioridade",
  "modalidade_de_ensino": "Integral"
}

​
Objeto Personalizado (Object)

POST /api/integrations/hubspot/internal/objects
Content-Type: application/json

{
  "customField1": "valor1",
  "customField2": "valor2",
  "email": "athos@tolky.to",
  "nome_do_objeto": "Exemplo",
  "external_id": 123456789,
  "campo_extra": "valor não mapeado"
}
  • Os campos customField1, customField2, email, nome_do_objeto, external_id são exemplos de campos mapeados.
  • O campo campo_extra não será enviado para o HubSpot, mas será salvo no InterData.

Observação: O objeto recebido na rota /objects será convertido em lead ou ticket dentro do Tolky, conforme o mapeamento previamente combinado no projeto.

​
Sobre Campos Extras no Payload

Atenção: O objeto enviado deve seguir o modelo previamente acordado com o cliente. Campos que não foram combinados (ou seja, que não fazem parte do mapeamento oficial) não serão enviados para o HubSpot.

  • O que acontece com campos extras?
    • Não são preenchidos no HubSpot: O sistema só envia para o HubSpot os campos que fazem parte do mapeamento oficial.
    • São salvos no InterData: Todos os campos extras enviados no payload, que não possuem uma coluna específica nas tabelas principais do banco Tolky, serão armazenados na tabela de dados gerais chamada InterData.
      • Isso garante que nenhuma informação enviada seja perdida, mesmo que não exista um campo específico para ela no banco.
  • No caso de objetos personalizados (objects):
    • O Tolky irá converter o objeto recebido em lead ou ticket de acordo com o mapeamento previamente combinado no projeto.

​
Exemplo prático

Se você enviar:

{
  "email": "maria.souza@empresa.com",
  "subject": "Teste Alterado",
  "campo_personalizado": "novo valor personalizado"
}
  • O campo campo_personalizado não será enviado para o HubSpot.
  • Ele será salvo no InterData do lado Tolky, ficando disponível para consultas ou integrações futuras.

​
Exemplo de Resposta

​
Sucesso

{
  "entityData": { "id": "999", "status": "created" },
  "contactData": { "id": "888", "email": "maria.souza@empresa.com" },
  "interData": [{ "campo_personalizado": "novo valor personalizado" }]
}

​
Erro de Autenticação

{
  "code": 403,
  "message": "Invalid credentials"
}

​
Erro de Validação ou Processamento

{
  "code": 400,
  "message": "Required parameters are missing"
}

ou

{
  "code": 500,
  "message": "Internal server error occurred"
}

​
Observações Importantes

  • Payload: O objeto enviado deve ser exatamente o que foi acordado com o cliente. Isso garante o correto mapeamento e persistência dos dados.
  • Autenticação: As rotas internas exigem autenticação (token/bearer). Certifique-se de enviar o header Authorization: Bearer <token>.
  • Não envie hostId ou hostSlug: Estes são preenchidos automaticamente pelo sistema após autenticação.
  • Erros detalhados: Em caso de erro, a resposta conterá o código HTTP, mensagem e detalhes para troubleshooting.

​
👨‍💻 Para Desenvolvedores: Integrando HubSpot ao Tolky

​
Objetivo

Esta seção explica como configurar o seu HubSpot para enviar dados de deals, tickets ou objetos personalizados automaticamente para o Tolky, utilizando as rotas internas da API Tolky.

​
1. Configurando o HubSpot para Envio de Dados

Você deve utilizar webhooks do HubSpot, workflows ou integrações customizadas via scripts no seu ambiente HubSpot. O objetivo é garantir que, sempre que um deal, ticket ou objeto personalizado for criado/atualizado no seu HubSpot, os dados sejam enviados para a API Tolky.

​
Exemplo de Fluxo com Webhook

  1. No seu HubSpot, crie um webhook (via workflow ou app customizado) que será disparado quando um ticket, deal ou objeto personalizado for criado/atualizado.
  2. Configure o webhook para fazer uma requisição POST para a rota correspondente da API Tolky:
    • Tickets: /api/integrations/hubspot/internal/tickets
    • Deals: /api/integrations/hubspot/internal/deals
    • Objects: /api/integrations/hubspot/internal/objects
  3. O payload do webhook deve ser exatamente igual ao modelo acordado (veja exemplos acima).
  4. Inclua o header de autenticação:
    Authorization: Bearer <token>

​
Exemplo de Código (Node.js)

const axios = require("axios");

async function enviarDealParaTolky(dealData) {
  try {
    const response = await axios.post(
      "https://<seu-endpoint-tolky>/api/integrations/hubspot/internal/deals",
      dealData,
      {
        headers: {
          "Content-Type": "application/json",
          Authorization: "Bearer <seu_token_aqui>",
        },
      }
    );
    console.log("Resposta Tolky:", response.data);
  } catch (error) {
    console.error(
      "Erro ao enviar para Tolky:",
      error.response?.data || error.message
    );
  }
}

O mesmo padrão pode ser usado para tickets ou objetos personalizados, alterando apenas a URL e o payload. No caso de objetos personalizados, lembre-se que eles serão convertidos em lead ou ticket conforme o mapeamento previamente combinado.

​
Exemplo de Configuração de Webhook no HubSpot

  • URL:
    https://<seu-endpoint-tolky>/api/integrations/hubspot/internal/deals (para deals) https://<seu-endpoint-tolky>/api/integrations/hubspot/internal/objects (para objetos personalizados)
  • Método:
    POST
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <token>
  • Body:
    Preencha com o JSON do deal, ticket ou objeto personalizado conforme o modelo acordado.

​
4. Testando a Integração

  • Utilize ferramentas como Postman ou Insomnia para testar o envio manualmente antes de automatizar.
  • Verifique as respostas da API Tolky para garantir que os dados foram processados corretamente.

​
5. Observações

  • Autenticação obrigatória: Sempre envie o header Authorization: Bearer <token>.
  • Não envie hostId ou hostSlug: O sistema preenche automaticamente.
  • Erros: Em caso de erro, a resposta conterá detalhes para troubleshooting.

​
Resumo do Processo

  1. HubSpot dispara webhook/workflow com os dados do deal, ticket ou objeto personalizado.
  2. API Tolky recebe, autentica, processa e retorna o resultado.
  3. Dados são salvos conforme o mapeamento (incluindo conversão de objeto personalizado em lead ou ticket), extras vão para o InterData.

Se precisar de exemplos de payload ou dúvidas sobre o mapeamento, consulte a seção de exemplos acima ou entre em contato com o time Tolky.

Integrar minichat com meu siteEndpoint Tolky Reasoning