> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wtocrm.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Integre WhatsApp ao seu CRM, ERP ou SaaS de exportação com a API WTOCRM. Vincule por QR code ou pareamento, envie mensagens e receba respostas por webhook.

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](https://docs.wtocrm.com/pt-BR/waapi/connect-instance.md) 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](https://assets.wtocrm.com/blog/2026/whatsapp-api-for-export-business/cover-fc11b84da5.webp)

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](https://docs.wtocrm.com/pt-BR/blog/whatsapp-api-for-developers.md).

## 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](https://wtocrm.com) 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](https://docs.wtocrm.com/pt-BR/waapi/index.md) 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](https://docs.wtocrm.com/pt-BR/waapi/create-instance.md) e abra o [guia de conexão](https://docs.wtocrm.com/pt-BR/waapi/connect-instance.md). 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:

```bash theme={null}
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:

```bash theme={null}
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](https://docs.wtocrm.com/pt-BR/waapi/get-connection-state.md):

```bash theme={null}
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](https://docs.wtocrm.com/pt-BR/waapi/send-text-message.md). Substitua o número pelo seu número de teste:

```bash theme={null}
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](https://docs.wtocrm.com/pt-BR/waapi/set-webhook.md) 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](https://docs.wtocrm.com/pt-BR/waapi/send-media-message.md).

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

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

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](https://docs.wtocrm.com/pt-BR/waapi/connect-instance.md) 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](https://docs.wtocrm.com/pt-BR/waapi/connect-instance.md) para integrar as conversas ao seu software de exportação.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.