API WhatsApp WTOCRM para exportação: QR code e pareamento

Um comprador de outro país pede uma cotação pelo WhatsApp. Sua equipe responde pelo celular, enquanto os dados do cliente ficam em outro sistema. Quando chega a hora de confirmar uma amostra, esclarecer uma especificação ou retomar o contato, você precisa localizar a conversa novamente. A API WhatsApp do WTOCRM (WTO WA API) permite vincular uma conta por QR code ou código de pareamento e, após a conexão, enviar e receber mensagens pela API. Você pode integrar esse canal ao seu CRM, ERP ou SaaS de comércio exterior para conectar as conversas às tarefas da equipe. Para quem exporta, a API oferece um canal de comunicação dentro do software de gestão. Para quem desenvolve, as requisições REST e os eventos de webhook permitem usar o backend existente. Comece conectando sua primeira instância do WhatsApp e valide o fluxo completo.

Pontos principais

A WTO WA API oferece acesso ao WhatsApp via protocolo, com login por QR code ou código de pareamento vinculado ao número de telefone.

A pessoa responsável pela conta escaneia o QR code ou digita o código de pareamento no WhatsApp do celular.

Receber um código não confirma a conexão. Aguarde instance.state igual a open antes de enviar.

As requisições REST iniciam operações; os webhooks levam respostas e eventos de conexão ao seu aplicativo.

Ilustração conceitual de um celular conectado a uma janela de conversas de exportação, com silhuetas de porto e contêineres — Ilustração conceitual de integração de mensagens no comércio exterior, não uma captura do produto.

Por que conectar o WhatsApp ao software de exportação?

Associe a conversa aos dados comerciais quando uma mensagem precisar gerar uma próxima ação. O comprador confirma um modelo e sua equipe atualiza a cotação. O cliente informa o endereço e você confere os dados de envio da amostra. Se você desenvolve software para exportadores, comece com uma tarefa concreta: enviar uma mensagem sobre a cotação a partir do cadastro do cliente e associar a resposta ao contato certo. Assim você testa tanto o canal de mensagens quanto a identificação do cliente. A WTO WA API fornece as operações de mensagens. Seu aplicativo implementa a identificação de contatos, aprovação de cotações, consulta de pedidos e atribuição de tarefas. Para avaliar os estados de conexão e o tratamento de eventos, consulte a visão geral da API para desenvolvedores.

O que a API WhatsApp via protocolo do WTOCRM oferece?

A WTO WA API conecta o WhatsApp por uma sessão de dispositivo vinculado e disponibiliza operações de conexão e mensagens por HTTP. Você pode manter sua linguagem e suas ferramentas atuais para criar a interface e as regras de negócio.

Recurso	Como você pode usar
Login por QR code	Exibir a imagem na página de conexão para a pessoa responsável pela conta escanear
Login por código de pareamento	Informar o número do WhatsApp, obter o código e pedir que a pessoa o digite no celular
Endpoints de texto e mídia	Iniciar conversas na tela comercial e incluir imagens ou documentos conforme o suporte dos endpoints
Consulta de conexão	Verificar a conta antes do envio e mostrar o estado atual
Webhooks	Encaminhar eventos de mensagens e conexão ao backend para acionar regras definidas por você

Este guia trata do acesso via protocolo de dispositivo vinculado fornecido pelo WTOCRM, que não é a integração oficial da WhatsApp Business Platform ou Cloud API da Meta. A pessoa responsável pela conta precisa concluir a vinculação; a conexão e o uso continuam sujeitos à rede, ao estado da conta e às regras da plataforma. O WTOCRM publica este guia para explicar o uso da sua API WhatsApp. As referências de conexão, mensagens e webhooks vinculadas no texto definem os parâmetros atuais. Consulte o diretório da WTO WA API para ver as operações disponíveis. Valide as mensagens de texto antes de acrescentar mídia e outros recursos.

Vincule a conta por QR code ou código de pareamento

Prepare uma instância de dispositivo vinculado conforme a documentação de criação de instância e abra o guia de conexão. Tenha o nome da instância, uma chave com permissão de acesso e o celular da conta. Mantenha a chave no backend e substitua os valores de exemplo antes de testar. As duas opções usam o mesmo endpoint. Omita number para obter um QR code; inclua number para solicitar o pareamento por telefone.

QR code: exiba a imagem e confirme no celular

Faça a requisição no backend, substituindo export-demo pelo nome da sua instância:

curl --request GET \
  --url 'https://waapi.wtocrm.com/instance/connect/export-demo' \
  --header 'apikey: YOUR_API_KEY'

Exiba o valor retornado em base64 como imagem QR ou transforme code em um QR code. O campo base64 já inclui o prefixo de URL de dados PNG; code contém os dados brutos do QR code. No WhatsApp do celular, a pessoa responsável pela conta abre Dispositivos conectados, escolhe Conectar um dispositivo e escaneia a imagem. Exiba o QR code de login apenas à pessoa autorizada.

Código de pareamento: informe o número e digite o código no celular

Para usar um código, inclua o número do WhatsApp na requisição de conexão:

curl --request GET \
  --url 'https://waapi.wtocrm.com/instance/connect/export-demo?number=5511999999999' \
  --header 'apikey: YOUR_API_KEY'

O número acima ilustra o formato. Troque pelo seu próprio número do WhatsApp, com código do país: de 8 a 15 dígitos, sem zero inicial, +, espaços ou pontuação. Leia pairingCode na resposta. No celular desse número, abra Dispositivos conectados, inicie a conexão de um dispositivo, escolha Conectar com número de telefone e digite o código retornado. Os nomes dos menus podem variar conforme a versão do aplicativo. pairingCode é o código que você digita no celular; code contém os dados do QR code. Não confunda os campos. Requisições repetidas de pareamento podem gerar um novo código, então evite renová-lo enquanto alguém o digita. Se o campo ainda não estiver disponível, siga o guia de conexão e aguarde antes de tentar novamente.

Comece a conversar: confirme a conexão, envie e receba

Após a confirmação no celular, verifique a conexão antes de enviar. O teste completo exige que seu aplicativo envie a mensagem, que o destinatário de teste a receba e que a resposta chegue ao backend.

Confirme o estado da conexão

Consulte o endpoint de estado da conexão:

curl --request GET \
  --url 'https://waapi.wtocrm.com/instance/connectionState/export-demo' \
  --header 'apikey: YOUR_API_KEY'

Aguarde instance.state igual a open. O valor connecting indica conexão em andamento; close indica desconexão. Um QR code, código de pareamento ou retorno HTTP bem-sucedido não substitui essa verificação.

Envie a primeira mensagem de teste

Envie uma mensagem identificada como teste para um destinatário seu. A estrutura abaixo segue a documentação de envio de texto. Substitua o número pelo seu número de teste:

curl --request POST \
  --url 'https://waapi.wtocrm.com/message/sendText/export-demo' \
  --header 'apikey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"number":"5511999999999","textMessage":{"text":"WTOCRM integration test: please reply to confirm receipt."}}'

Confira o resultado da API e o recebimento no celular de destino. A resposta da API e a entrega final são etapas diferentes. Se a requisição expirar, verifique se a operação foi concluída antes de repetir, para evitar mensagens duplicadas.

Receba respostas por webhook

Use a documentação de configuração de webhook para definir sua URL HTTPS e os eventos necessários. Configure os retornos de mensagens com os eventos aceitos pela sua instância. O guia de conexão também documenta CONNECTION_UPDATE para mudanças de conexão. Peça uma resposta ao destinatário de teste. Verifique se o evento chega ao backend e corresponde à instância e ao contato corretos. Elimine duplicações pelo identificador da mensagem e diferencie mensagens recebidas das suas próprias mensagens enviadas para evitar acompanhamentos repetidos ou ciclos de resposta automática.

Implemente um fluxo de exportação no software existente

Comece pela conversa que leva da consulta à cotação. Sua equipe envia uma mensagem no cadastro do cliente, a resposta chega pelo webhook, o aplicativo a associa ao contato e a pessoa responsável decide a próxima ação.

Tarefa de exportação	Canal da API	Lógica implementada no seu sistema
Resposta à consulta	Envio de texto e eventos de mensagens	Identificar o contato e registrar a origem e a pessoa responsável
Conversa sobre cotação	Envio de texto ou documentos pelo endpoint de mídia	Selecionar a versão correta e aprovar preço e prazo
Acompanhamento de amostras	Atualizações de andamento e confirmações	Associar a solicitação de amostra e conferir o envio
Expedição e pós-venda	Notificações e respostas	Consultar o pedido e criar tarefas de atendimento

Esses são exemplos de integrações que você pode construir. Vincular a conta não sincroniza automaticamente cotações, pedidos ou tarefas: seu aplicativo precisa conectar os dados comerciais. Para imagens e documentos, consulte o endpoint de mensagens de mídia. Use o canal para conversas comerciais que seus clientes concordaram em receber. Valide um fluxo completo com uma instância de teste antes de ampliar números, equipes e regras de automação.

Perguntas de desenvolvimento

Depois de conectar a conta, seu software pode usar os endpoints de envio e os webhooks para criar uma experiência de chat. Seu aplicativo implementa a interface, a lista de mensagens, a associação de contatos e o controle de acesso. Se você precisa de um espaço de trabalho pronto, conheça separadamente os recursos de conversas do WTOCRM.

Onde devo digitar o código de pareamento?

No fluxo de vinculação de dispositivos do WhatsApp, no celular da conta. A API retorna pairingCode, que seu aplicativo exibe à pessoa responsável. Após a confirmação no celular, consulte o estado da conexão.

Por que não consigo enviar depois de receber um QR code?

A imagem é uma credencial de login. A pessoa responsável ainda precisa escaneá-la e concluir a vinculação. Se a geração do código ou a conexão estiver pendente, verifique o estado e aguarde open. Consulte o guia de conexão para solucionar problemas.

Posso integrar com Python, Java, PHP ou Node.js?

Você pode usar o cliente HTTP de cada linguagem para fazer requisições REST e seu próprio backend para receber webhooks. Este guia não depende de um SDK específico. Siga a autenticação, a estrutura de requisição e o tratamento de resposta documentados. Conecte sua primeira instância do WhatsApp. Escolha QR code ou código de pareamento, confirme open, envie uma mensagem de teste e receba a resposta. Abra o guia de conexão da API WhatsApp do WTOCRM para integrar as conversas ao seu software de exportação.

​Por que conectar o WhatsApp ao software de exportação?

​O que a API WhatsApp via protocolo do WTOCRM oferece?

​Vincule a conta por QR code ou código de pareamento

​QR code: exiba a imagem e confirme no celular

​Código de pareamento: informe o número e digite o código no celular

​Comece a conversar: confirme a conexão, envie e receba

​Confirme o estado da conexão

​Envie a primeira mensagem de teste

​Receba respostas por webhook

​Implemente um fluxo de exportação no software existente

​Perguntas de desenvolvimento

​A equipe pode conversar pelo nosso software após o login por QR code?

​Onde devo digitar o código de pareamento?

​Por que não consigo enviar depois de receber um QR code?

​Posso integrar com Python, Java, PHP ou Node.js?