Protocolo de conexão com CRM

O BIKY.ai se conecta ao CRM ou DMS de cada marca ou distribuidor. Ele entrega cada lead que chega por qualquer canal, informa o andamento (em tempo real ou ao fechar a conversa, conforme o CRM) e recebe as alterações feitas pelo consultor. Tudo gira em torno do SalesCard, o registro do BIKY.ai que guarda o lead, sua etapa no Funnel e o id que o CRM atribui a ele. Este protocolo reúne o que aprendemos em mais de quinze integrações pela América Latina.

Como nos conectamos

Existem três caminhos, e um CRM pode combiná-los: seu CRM nos notifica por webhook, o BIKY.ai consulta a API dele e as atualizações de andamento saem por essa mesma API. Cada id que o CRM retorna fica salvo no SalesCard ou no contato, para que o próximo evento atualize o registro em vez de duplicá-lo.

Quem define a autenticação é o seu CRM: OAuth2 client_credentials com um connected app, OAuth2 autorizado por um usuário administrador, um token de curta duração, uma API key ou Basic Auth. Os webhooks de entrada usam uma URL exclusiva com um token por fluxo. Você também pode ativar a criptografia do corpo, e o Flows verifica a assinatura HMAC das plataformas que a enviam. Formulários web e fornecedores de leads também entram por esse caminho. Os formulários da Meta chegam como mais um canal.

Há três variantes. Algumas integrações rodam em uma plataforma de integração (iPaaS), com conectores OAuth2 autorizados por um dos usuários administradores do cliente. Quando o CRM não tem API, ou a API não cobre algum processo, um robô (RPA) opera o portal web dele com usuários designados pelo cliente. E, se o seu sistema não estiver neste documento, o BIKY.ai pode enviar cada alteração do SalesCard para o webhook que você nos indicar.

Também funciona no sentido inverso: seu CRM pode chamar a API do BIKY.ai com a chave da sua conta. Assim, ele pode criar ou buscar contatos (por telefone, e-mail ou id) e criar, consultar ou mover SalesCards entre as etapas de um Funnel. Há exemplos nas coleções do Postman da Keybe. Os campos, valores permitidos e exemplos dessa API estão na seção Campos e estrutura da API.

Integrações com CRM

Tudo trafega por HTTPS. Três coisas mudam de um CRM para outro: quem inicia a chamada, como ela se autentica e qual identificador evita duplicados. Estas são as integrações com mais tempo de operação.

Sale U

• Conexão e autenticação: entrada por webhook para uma URL exclusiva com token. Saída por API REST com API key, além de um secret e um timestamp no corpo.
• Quais dados trafegam: na entrada, o lead atribuído: nome, telefone, e-mail, concessionária, modelo e id do prospect. Na saída, cada atividade: status, agendamento, nota de acompanhamento, bloqueio ou liberação, temperatura e fechamento.
• Direção e frequência: tempo real. Conforme a concessionária, nos dois sentidos ou apenas do BIKY.ai para o Sale U. Cada concessionária precisa da autorização do fornecedor.
• Como evitamos duplicados: o contato é buscado pelo telefone e o SalesCard pelo id do prospect. Se o Sale U reenviar o mesmo lead, o existente é atualizado.

Salesforce

• Conexão e autenticação: API REST (objetos padrão ou o Apex do cliente), às vezes por trás da camada de integração dele. OAuth2 client_credentials com um connected app, OAuth2 de um usuário administrador ou Basic Auth.
• Quais dados trafegam: na saída, o lead com contato, modelo, origem, concessionária e consultor de vendas; depois, o status e o agendamento. Na entrada, a oportunidade ganha ou faturada.
• Direção e frequência: saída ao fechar a conversa, ao agendar e a cada mudança de status. Entrada por uma consulta SOQL periódica (por exemplo, a cada hora), filtrada pela data da última modificação.
• Como evitamos duplicados: o id do lead fica salvo no contato e os envios seguintes o atualizam. Se o CRM também deduplica do lado dele, a regra dele é respeitada.

Seekop / SICOP

• Conexão e autenticação: robô (RPA) no portal com o usuário de cada concessionária. Se a concessionária tiver acesso à API, API REST em formato ADF com API key.
• Quais dados trafegam: na entrada, os leads da fila de espera do CRM. Na saída, o acompanhamento na ficha do lead; via API, o prospect (contato, modelo, origem e comentário) com sua concessionária, e o agendamento.
• Direção e frequência: com o robô, nos dois sentidos: ele lê a fila a cada poucos minutos e registra o acompanhamento na ficha do lead. Via API, do BIKY.ai para o Seekop ao fechar a conversa e ao agendar.
• Como evitamos duplicados: o robô usa o id do lead no CRM e uma chave de idempotência por ação. Via API, o contato é marcado como enviado.

HubSpot

• Conexão e autenticação: conector do Flows com OAuth2 autorizado por um usuário do cliente; em alguns casos, webhook ou iPaaS.
• Quais dados trafegam: na saída, o contato e, conforme o caso, um negócio em um pipeline combinado. A sincronização de entrada dos negócios que chegam à etapa de ganho já foi projetada.
• Direção e frequência: saída ao fechar a conversa ou a cada compra. A entrada por polling periódico já foi projetada.
• Como evitamos duplicados: upsert do contato. Já foi projetado salvar o id dele no BIKY.ai e fazer a correspondência por esse id.

Microsoft Dynamics 365

• Conexão e autenticação: API OData que o cliente ou seu integrador publica por trás de um API gateway, com uma subscription key no cabeçalho.
• Quais dados trafegam: na saída, o lead com sua campanha; o agendamento é criado e atualizado.
• Direção e frequência: do BIKY.ai para o Dynamics, ao fechar a conversa e a cada evento de agendamento.
• Como evitamos duplicados: só são enviados leads novos, não edições. O id do agendamento fica salvo no contato e as alterações são aplicadas a ele.

CRM da montadora

• Conexão e autenticação: API REST JSON com token de curta duração; multipart com um PDF para o pedido. Sem webhooks: um serviço dedicado consulta a API periodicamente. O que a API não cobre é feito por um robô no portal.
• Quais dados trafegam: na entrada, os leads e suas mudanças de status, por concessionária. Na saída, a criação dos nossos próprios leads, o acompanhamento, o test drive e o pedido de pré-venda.
• Direção e frequência: entrada por polling a cada minuto, respeitando um intervalo mínimo entre consultas para a mesma concessionária; saída a cada evento do SalesCard.
• Como evitamos duplicados: o código do lead fica salvo no SalesCard; a criação de leads usa o id do SalesCard como chave de idempotência.

Outras integrações que já construímos

Algumas não têm mais contas ativas, mas podem ser implementadas novamente.

O Flows também inclui nós para os ERPs Siigo, Alegra e Defontana, e para um DMS de pós-venda (agendamento de serviços). As lojas virtuais (Shopify, VTEX e WooCommerce) sincronizam catálogo e contatos com o BIKY.ai e enviam notificações de carrinhos abandonados, pagamentos e alterações de pedidos. Os conectores delas, assim como os de pagamentos e transportadoras, estão na página de integrações.

Mapeamento de dados

O mapeamento é combinado campo a campo antes da construção, e cada lista fechada (origens, modelos, concessionárias, status) ganha sua própria tabela de equivalência.

Os status são mapeados com as etapas do Funnel. Em uma conta automotiva, o Funnel de vendas vem com estas nove. O nome exibido de cada etapa pode variar conforme a conta; a chave não muda, e é ela que a API usa.

Um lead que o CRM marca como inválido não move o SalesCard: apenas o status é armazenado, porque não se trata de uma venda perdida. As contas do setor automotivo também incluem um Funil de Pós-venda (qualificado, recebido, diagnóstico, aprovação, em serviço, entrega, pagamento, acompanhamento e não aprovado), que pode ser mapeado para o DMS de uma oficina quando necessário.

Sincronização e duplicados

Os dados de saída trafegam em tempo real ou quando a conversa é encerrada, dependendo do CRM. Os dados de entrada chegam por webhook, se o CRM oferecer esse recurso, ou, caso contrário, por consulta periódica (polling), com intervalos que vão de um minuto a uma hora. Nenhuma integração com CRM usa SFTP ou troca automática de arquivos.

O que dispara um envio ao CRM:

• A criação de um SalesCard: o lead é criado com contato, origem, modelo e concessionária.
• Um contato do consultor ou do BIKY (ligação, e-mail ou WhatsApp): um registro de acompanhamento.
• Uma mudança de etapa no Funil: o novo status.
• Um agendamento criado, remarcado ou cancelado: o agendamento ou o test drive.
• O encerramento de uma conversa: o lead com todos os seus dados e o seu status.

Os dados históricos são carregados uma única vez pela API do CRM, sem disparar mensagens nem fluxos, e com a data original de cada lead.

Regras contra duplicados:

1. Todo id que o CRM retorna é armazenado no BIKY.ai, e o evento seguinte atualiza esse registro em vez de criar um novo.
2. Os dados de entrada precisam ser idempotentes: o mesmo id de lead ou o mesmo evento repetido atualiza o SalesCard existente. Os CRMs fazem novas tentativas, e uma nova tentativa não pode abrir outro SalesCard.
3. Antes de criar um contato, ele é buscado pelo número de telefone normalizado. Se o CRM já faz a deduplicação por conta própria, a regra dele é respeitada e o id que ele retorna é armazenado.
4. Uma pessoa com um SalesCard aberto no Funil de Vendas não abre outro. Um interesse diferente abre, se o CRM o registrar como um lead separado.
5. O lead entra por um único caminho. Se um formulário alimenta o BIKY.ai e o CRM ao mesmo tempo, o mesmo lead é criado duas vezes.
6. Confirme com o cliente se o CRM dele cria um novo registro a cada envio. Enquanto não houver resposta, são enviados apenas registros novos, não edições.

Do que precisamos e quanto tempo leva

Construir costuma ser a parte rápida. Quem define o prazo são os insumos e as aprovações. Nos nossos projetos de 2025 e 2026, metade das concessionárias que entraram em um CRM já conectado ficou pronta em menos de duas semanas a partir da solicitação. Uma integração nova levou uma mediana de cinco semanas, sem contar a etapa comercial.

O que mais alonga um projeto: credenciais que não funcionam, um sandbox diferente do ambiente de produção, catálogos que chegam atrasados, o acordo de confidencialidade, a aprovação da marca ou do fornecedor do CRM e a linha de WhatsApp de cada concessionária. Veja a lista, por fase.

0. Antes de começar

• Acordo de confidencialidade e quaisquer documentos jurídicos que a sua empresa exija.
• Avaliação de segurança, se aplicável: temos certificação ISO/IEC 27001.
• Aprovação da marca ou do fornecedor do CRM para cada concessionária, se necessário.

1. Descoberta

• Documentação atualizada da API: objetos, campos obrigatórios, valores permitidos para cada lista (picklist), códigos de erro e limites de requisição.
• Se o CRM envia notificações por webhook ou se precisa ser consultado periodicamente.
• Quais objetos são sincronizados (lead, contato, oportunidade, agendamento) e quem é o dono de cada campo.
• Se o seu CRM cria um novo registro a cada envio ou atualiza o existente.
• Se o seu CRM também capta leads pelos próprios formulários e qual dos dois tem prioridade.
• Um responsável técnico do lado do cliente ou do integrador dele.

2. Mapeamento

• Catálogo de origens e status com seus códigos, indicando quais status são finais.
• Lista de modelos ou produtos com seus códigos e o valor padrão, caso o campo seja obrigatório.
• Concessionárias ou filiais com seus códigos no CRM.
• IDs dos consultores, se o CRM precisar saber quem está atendendo o lead.
• O tamanho máximo e o formato de cada campo, incluindo o número de telefone.
• As regras próprias do CRM: deduplicação, validações e atribuição automática.

3. Ambiente de testes

• Sandbox com credenciais válidas e a mesma versão, os mesmos dados de referência e as mesmas concessionárias do ambiente de produção.
• Credencial de integração, uma por ambiente, com permissões nos objetos em que vamos gravar: connected app (OAuth2 client_credentials) ou usuário técnico.
• Leads de teste combinados previamente: um teste em produção cria registros reais no seu CRM.

4. Go-live e monitoramento

• Credenciais de produção pelo canal seguro que combinarmos, nunca por e-mail, chat ou tickets.
• Aviso prévio antes de trocar ou desativar uma credencial.
• A linha de WhatsApp de cada concessionária, os IDs dos seus consultores e o cronograma de implantação por grupo de concessionárias.
• Um contato para incidentes.

Erros comuns e monitoramento

Quase todas as rejeições vêm dos dados, não da rede: um campo obrigatório vazio, um formato que o CRM não aceita ou uma regra específica do CRM. Esses casos não são reenviados automaticamente, porque falhariam da mesma forma. Em vez disso, corrigimos o dado ou a regra e reenviamos o evento.

Como monitoramos:

• Cada execução fica registrada no histórico, com os dados enviados nos nós do CRM.
• Nas integrações com serviço dedicado e no robô, um monitor faz verificações a cada 5 minutos. Ele classifica cada falha pela causa, exibe tudo em um painel e envia alertas por e-mail apenas para problemas críticos e recorrentes.
• Acompanhamos de perto cada concessionária nos primeiros dias depois de ativá-la. Depois disso, sempre que há uma reclamação, conciliamos os leads do CRM com os SalesCards e as conversas do BIKY.ai.

Lições aprendidas

Quase tudo o que falhou se resume a quatro regras: armazenar o id externo, validar o corpo de cada resposta, confirmar campos e catálogos antes de construir e testar cada concessionária com um lead de teste antes de ativá-la.

• Sale U. O mesmo lead chegava muitas vezes, e cada reenvio abria outro SalesCard.
  • O que mudamos: limpamos os SalesCards duplicados, e o fluxo de entrada agora busca o SalesCard pelo id do prospect antes de criar um novo.
  • O que faríamos diferente: vincular o SalesCard ao id do prospect.
• Sale U. O CRM passou a validar campos que antes aceitava, e fluxos antigos começaram a falhar sem nenhuma mudança do nosso lado.
  • O que mudamos: corrigimos os campos nos fluxos afetados.
  • O que faríamos diferente: enviar um alerta quando as rejeições de uma integração aumentam.
• Sale U. Concessionárias novas não tinham regra de atribuição, então os leads delas voltavam ao CRM sem atendimento.
  • O que mudamos: uma revisão da tabela de concessionárias sempre que uma nova conta é configurada.
  • O que faríamos diferente: testar cada concessionária com um lead de teste antes de ativá-la.
• Salesforce. Muitos leads foram rejeitados por causa de um campo obrigatório vazio: o modelo de interesse.
  • O que mudamos: solicitamos a documentação completa do CRM: campos obrigatórios, valores permitidos para cada lista (picklist) e catálogos.
  • O que faríamos diferente: combinar valores padrão antes da ativação.
• Salesforce. Uma regra do CRM bloqueava a reatribuição do responsável, e a rejeição não aparecia no BIKY.ai.
  • O que mudamos: encontramos a causa nos logs do conector.
  • O que faríamos diferente: registrar cada rejeição e perguntar sobre as regras de validação na fase de descoberta.
• Salesforce. A consulta de vendas ganhas filtrava pela data de criação, então quase nada chegava. Além disso, ela movia SalesCards do Funil de Pós-venda para a etapa de venda ganha ($step_won$) do Funil de Vendas.
  • O que mudamos: a consulta agora usa a data da última modificação da oportunidade e filtra pelo Funil de Vendas.
  • O que faríamos diferente: testar a consulta com seis meses de histórico antes da ativação.
• Salesforce. Os formulários da Meta alimentavam o BIKY.ai e o CRM ao mesmo tempo, então cada lead era criado duas vezes.
  • O que mudamos: agora os leads entram apenas pelo CRM.
  • O que faríamos diferente: definir um único caminho de entrada já na fase de descoberta.
• Seekop. Quando uma conta foi dividida em contas por concessionária, o roteamento pelo nome da concessionária deixou de bater e alguns leads nunca foram enviados.
  • O que mudamos: um único template compartilhado, com os dados de cada concessionária em variáveis de ambiente, e a integração anterior desligada na mesma etapa.
  • O que faríamos diferente: nunca rotear por nomes que o cliente pode alterar.
• HubSpot. A correspondência de negócios ganhos identificava apenas alguns casos: o id do HubSpot não ficava salvo no contato, e as buscas por e-mail geravam falsos positivos.
  • O que mudamos: projetamos a correspondência para usar apenas o id, com o número de telefone exato como alternativa.
  • O que faríamos diferente: salvar o id externo desde o primeiro envio.
• Zoho. O acesso expirava a cada hora porque o token não estava sendo renovado.
  • O que mudamos: passamos a usar um conector que renova o token sozinho.
  • O que faríamos diferente: usar sempre o refresh token ou um conector que cuide disso.
• Dynamics 365. A chave de assinatura era enviada na URL, mas o gateway exige que ela vá no header. Além disso, um campo do CRM era mais curto que o nosso id.
  • O que mudamos: a chave agora vai no header, e o cliente aumentou o tamanho do campo.
  • O que faríamos diferente: revisar headers e tamanhos de campo durante o mapeamento.
• Vários. Alguns CRMs exigem dados que o BIKY.ai nem sempre tem, como um telefone com um número exato de dígitos, o sobrenome ou o produto. Uma regra desse tipo acabou bloqueando todos os leads de um cliente.
  • O que mudamos: perguntamos por essas regras na fase de descoberta.
  • O que faríamos diferente: medir com dados reais quantos leads cumprem cada regra antes de ativá-la.
• CRM da montadora. Marcar uma venda como fechada congela o lead no CRM para sempre.
  • O que mudamos: o BIKY.ai nunca envia esse status. Ele apenas o lê.
  • O que faríamos diferente: perguntar na fase de descoberta quais status são irreversíveis.
• CRM da montadora. Uma mudança nas credenciais do CRM interrompeu a entrada de leads.
  • O que mudamos: um alerta quando as consultas falham repetidamente ao longo do tempo.
  • O que faríamos diferente: combinar aviso prévio de cada mudança e o envio das novas credenciais por um canal seguro.
• CRM da montadora. O sandbox não tinha os dados do distribuidor do projeto e aceitava valores que a produção rejeita.
  • O que mudamos: validamos cada campo no sandbox e confirmamos em produção.
  • O que faríamos diferente: solicitar desde o início um sandbox idêntico à produção.
• Vários. Telefones com código de país duplicado, um 1 a mais ou sem código de país criavam contatos inválidos e SalesCards duplicados.
  • O que mudamos: normalização de telefones nos fluxos de entrada, com regras por origem.
  • O que faríamos diferente: combinar o formato do telefone durante o mapeamento, objeto por objeto.

Campos e estrutura da API

Campos, valores permitidos e regras da API do BIKY.ai para contatos e SalesCards.

Acesso

Toda chamada leva a chave da conta no header Authorization: Bearer <key>. A Keybe emite uma chave por conta e a entrega junto com as URLs base dos serviços de Contacts e Funnels.

• {app}: o id da conta no BIKY.ai, um por marca ou concessionária. Ele vai em todos os caminhos, exceto no de validação de telefone.
• {typeEntity}: people, business ou office. Para leads, use people.
• Um recurso único volta como um objeto simples. Uma lista volta como {data, paginator}. O paginator inclui totalDocs, limit, page, totalPages, pagingCounter, hasPrevPage, hasNextPage, prevPage e nextPage.
• Os erros voltam como {statusCode, timestamp, path, message, error}. Em um erro de validação, message é a lista de campos que falharam, por exemplo ["responsible should not be empty"].

Contato e SalesCard

O contato é a pessoa. O SalesCard é cada oportunidade de venda dessa pessoa dentro de um Funnel. Normalmente, um CRM mapeia o seu lead para os dois.

Endpoints

Campos do contato

Campos do SalesCard

Exemplos

Os valores entre < > são fornecidos por cada conta: ids de Funil, etapa, consultor e produto.

1. Criar ou atualizar o contato. POST /{app}/contacts/upsert-or-fallback. A resposta é {status, contact}; contact.uuid é o id usado no SalesCard. Com fallback, o motivo vem em reason, e você não deve criar o SalesCard até corrigir os dados.

{
  "typeEntity": "people",
  "name": "Mariana",
  "surname": "Torres",
  "phone": [{ "value": "525500001234", "countryCode": "52", "country": "MX", "isPrimary": true }],
  "email": [{ "value": "[email protected]", "isPrimary": true }],
  "registerChannel": [{ "channel": "api", "data": "MiCRM" }],
  "source": { "utmSource": "micrm", "utmCampaign": "lanzamiento-octubre" },
  "externalIds": [{ "systemName": "MiCRM_LeadId", "value": "L-000123" }]
}

2. Criar o SalesCard na primeira etapa. POST /{app}/funnel/{funnel}/steps/{step}/cards. A resposta retorna o SalesCard com seu _id.

{
  "name": "Mariana Torres",
  "persons": ["<contact uuid>"],
  "responsible": { "uuid": "<advisor uuid>", "name": "<advisor name>" },
  "description": "Lead received from MiCRM.",
  "productsData": [{ "id": "<product id>", "sku": "<sku>", "name": "<model>", "price": 450000 }],
  "utm": { "source": "micrm", "campaign": "lanzamiento-octubre", "sourceCardId": "OPP-000456" }
}

3. Mudança de etapa. PATCH /{app}/simple/cards/{id}. Move o SalesCard para Interessado (SQL) sem alterar mais nada.

{ "stepName": "$step_sql$" }

Regras da API