Como gerar e usar chaves de API para integrar com outros sistemas

Q: ### Posso usar a chave pública no frontend do meu site?

Sim, a chave pública (pk_live_...) foi projetada para ser segura para uso em ambientes públicos, como o código JavaScript do seu site. Sua função é apenas identificar sua conta, não autenticar ações. A chave secreta, por outro lado, nunca deve ser exposta no código do lado do cliente.

Para integrar sua conta com sistemas externos como CRMs, ERPs ou plataformas de automação (n8n, Zapier), a Papo (https://papo.global/) oferece chaves de API (Application Programming Interface) que podem ser geradas e gerenciadas diretamente no seu painel. Essas chaves funcionam como credenciais seguras que autorizam outros softwares a acessar e executar ações na sua conta Papo de forma programática.

A API da Papo permite que você construa ecossistemas de trabalho conectados, automatizando tarefas que vão desde o envio de mensagens de WhatsApp até a extração de leads qualificados. Para garantir a segurança, a Papo utiliza um sistema de duas chaves: uma pública, para identificação, e uma secreta, para autenticação.

Tipo de Chave	Descrição	Nível de Segurança	Exemplo de Uso
Chave Pública (`pk_live_...`)	Um identificador único e fixo para a sua conta Papo.	Baixo. Pode ser exposta publicamente.	Identificar sua conta em um script no frontend do seu site.
Chave Secreta (`sk_live_...`)	Uma "senha" para a API. Autentica suas requisições e concede permissão para agir em nome da sua conta.	Alto. Deve ser mantida em sigilo absoluto.	Autenticar uma chamada de API a partir do seu servidor (backend) para enviar uma mensagem.

Como gerar e encontrar suas chaves de API

As chaves de API são gerenciadas em uma área específica da sua conta Papo. Siga os passos abaixo para acessá-las.

Acesse seu painel Papo e navegue até Configurações.
No menu de configurações, procure pela seção de Desenvolvedores ou API.
Nesta página, você encontrará sua Chave Pública (pk_live_...), que é fixa e pode ser copiada a qualquer momento.
Para a Chave Secreta, você precisará gerar uma nova. Clique no botão para criar uma nova chave.
Dê um nome descritivo para a chave, indicando onde ela será usada (ex: "Integração CRM", "Automação N8N"). Isso ajuda a identificar e revogar chaves específicas caso seja necessário.
Após a criação, a Chave Secreta (sk_live_...) será exibida uma única vez. Copie-a e guarde-a em um local seguro, como um gerenciador de senhas ou uma variável de ambiente no seu servidor. Por razões de segurança, a Papo não armazena o valor original da chave e não poderá exibi-la novamente.

Se você perder uma chave secreta ou suspeitar que ela vazou, revogue-a imediatamente no painel e crie uma nova.

Como usar as chaves para autenticar na API

Toda comunicação com a API da Papo que envolve ações ou acesso a dados privados deve ser autenticada. Isso é feito enviando a chave secreta em um cabeçalho HTTP.

A URL base para todas as chamadas de API é: https://app.papo.global/api/v1

Para se autenticar, inclua sua chave secreta no cabeçalho Authorization da sua requisição, precedida pela palavra Bearer.

Exemplo de requisição com curl para obter dados da sua conta:

curl https://app.papo.global/api/v1/me \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_SECRETA_AQUI"

Neste exemplo:

sk_live_SUA_CHAVE_SECRETA_AQUI deve ser substituída pela sua chave secreta real.
O endpoint /me retorna informações sobre a conta autenticada, servindo como um bom teste para verificar se a sua chave está funcionando.

A chave pública (pk_live_...) pode ser enviada opcionalmente no cabeçalho X-Papo-Public-Key como uma verificação adicional, mas a autenticação principal é sempre feita pela chave secreta.

O que você pode fazer com a API da Papo?

A API abre um leque de possibilidades para automatizar e integrar suas operações. Aqui estão alguns exemplos do que você pode fazer:

Enviar mensagens de WhatsApp: Crie scripts para enviar notificações, alertas ou mensagens transacionais através de um dos seus números conectados.
Buscar contatos do Extrator: Acesse a lista de leads que você extraiu com o Extrator de CNPJ para sincronizá-los com seu CRM principal.
Gerenciar instâncias: Liste e verifique o status das suas conexões de WhatsApp.
Utilizar a Inteligência Artificial: Envie textos para o motor de IA da Papo e receba respostas geradas com base nos seus prompts configurados.
Sincronizar dados: Mantenha seus sistemas internos (ERP, BI) atualizados com os dados gerados na Papo.

Perguntas Frequentes (FAQ)

### Onde encontro a documentação completa da API?

A documentação técnica detalhada, com todos os endpoints, parâmetros e exemplos de código em diferentes linguagens (JavaScript, Python), está disponível publicamente em papo.global/pt/docs.

### Minha chave secreta vazou. O que eu faço?

Se você suspeita que sua chave secreta foi comprometida, acesse imediatamente a área de desenvolvedores no seu painel Papo, encontre a chave vazada na lista e clique para revogá-la. Uma vez revogada, ela não poderá mais ser usada para autenticar requisições. Em seguida, gere uma nova chave para substituir a antiga em suas integrações.

### Quantas chaves secretas posso criar?

Você pode criar múltiplas chaves secretas. É uma boa prática de segurança gerar uma chave diferente para cada sistema ou ambiente que você integra (ex: uma para seu CRM, outra para seu sistema de automação, uma para o ambiente de testes, etc.). Isso permite revogar o acesso de um sistema específico sem afetar os outros.

### Posso usar a chave pública no frontend do meu site?

Sim, a chave pública (pk_live_...) foi projetada para ser segura para uso em ambientes públicos, como o código JavaScript do seu site. Sua função é apenas identificar sua conta, não autenticar ações. A chave secreta, por outro lado, nunca deve ser exposta no código do lado do cliente.

### Qual a diferença entre a API da Papo e um Webhook?

A principal diferença está em quem inicia a comunicação. Com a API, seu sistema inicia a ação: você "pede" (pull) dados da Papo ou "manda" (push) a Papo fazer algo, como enviar uma mensagem. Com um Webhook, a Papo inicia a ação: ela "empurra" (push) dados para o seu sistema automaticamente quando um evento específico acontece (ex: um contato chega a uma etapa de um Flow).

### Qual a diferença entre a API da Papo e a API Oficial do WhatsApp?

A API Oficial do WhatsApp é focada exclusivamente nas funcionalidades do canal WhatsApp. A API da Papo é uma camada de abstração mais ampla e poderosa: ela permite que você controle não apenas o WhatsApp, mas também outros módulos da plataforma, como o CRM, o Extrator de Leads e o motor de Inteligência Artificial, tudo com um único conjunto de chaves e de forma simplificada.