Como usar a API da Papo para criar e atualizar contatos em massa

Abrir em

Ver como Markdown

Abrir no ChatGPT Abrir no Claude

Vitor

Última atualização em Oct 18, 2026

Para criar e atualizar contatos em massa via programação, utilize a API REST da Papo. Com autenticação por chave secreta (Bearer token) e a chave pública da conta, você pode enviar requisições que inserem novos registros ou modificam dados existentes no CRM — ideal para sincronizar bases externas, migrar listas ou manter o cadastro sempre atualizado sem intervenção manual.

A API da Papo expõe endpoints de escrita que permitem criar um contato (com nome, e‑mail e/ou telefone) e atualizar um contato já existente. Combinados com a autenticação simples e o formato JSON, esses endpoints viabilizam operações em lote quando executados em sequência por scripts, ferramentas de automação (como n8n) ou integrações customizadas.

Resumo do processo de integração

Etapa	Ação	Detalhe importante
1. Obter as chaves	Gerar a chave secreta (sk_live_…) e copiar a chave pública (pk_live_…) no painel da Papo.	A chave secreta aparece uma única vez; guarde‑a em local seguro.
2. Autenticar as chamadas	Incluir o header `Authorization: Bearer sk_live_…` em todas as requisições de escrita.	A chave pública pode ser enviada no header `X-Papo-Public-Key` (opcional).
3. Preparar o payload	Montar um objeto JSON com os campos do contato (nome, e‑mail, telefone, etc.).	Campos obrigatórios e formato exato estão na documentação da API.
4. Enviar as requisições	Fazer POST para o endpoint de criação ou PUT/PATCH para atualização.	Cada requisição processa um contato; para muitos registros, automatize o envio em loop.
5. Verificar as respostas	A API retorna `success: true` e os dados do contato criado/atualizado.	Em caso de erro, o corpo traz o código e a mensagem para correção.

Como funciona a autenticação e os endpoints

Toda chamada que modifica dados (criação, atualização) exige a chave secreta da conta. Ela deve ser enviada como token Bearer no header Authorization ou, alternativamente, no header X-Papo-Secret-Key. A chave pública (fixa por conta) pode acompanhar a requisição no header X-Papo-Public-Key — seu uso é opcional, mas se enviada precisa corresponder à mesma conta da chave secreta.

A URL base da API é https://app.papo.global/api/v1. A partir dela, os endpoints de contatos aceitam os verbos HTTP adequados para criar um novo registro ou modificar um existente. Como a documentação completa detalha os paths, parâmetros e campos aceitos, recomendamos consultar a referência oficial da API antes de codificar.

Exemplo de autenticação (requisição de teste)

Para validar que suas chaves estão funcionando, você pode chamar o endpoint GET /api/v1/me, que retorna os dados da conta. O padrão de autenticação é o mesmo usado em todos os outros endpoints:

curl https://app.papo.global/api/v1/me \
  -H "Authorization: Bearer sk_live_…" \
  -H "X-Papo-Public-Key: pk_live_…"

A resposta bem‑sucedida inclui success: true e o objeto data com as informações da conta. A partir daí, basta substituir o endpoint e o método HTTP conforme a operação desejada com contatos.

Criando e atualizando contatos em massa

Embora a API processe um contato por requisição, a operação em massa é alcançada executando múltiplas chamadas em sequência. Um script em Python, Node.js ou uma automação no n8n pode:

Ler uma lista de contatos de um arquivo CSV, banco de dados ou ERP.
Para cada registro, montar o payload JSON com os campos necessários.
Enviar a requisição ao endpoint de criação (se o contato não existir) ou de atualização (usando o identificador do contato).
Coletar as respostas e tratar eventuais erros (e‑mail duplicado, campo inválido etc.).

Como a API é REST e utiliza JSON, qualquer linguagem com suporte a HTTP funciona. A Papo também fornece exemplos em JavaScript e Python na página de documentação, que podem ser adaptados para os endpoints de contato.

Gatilhos automáticos após a criação

Sempre que um novo contato é criado via API, os mesmos eventos internos do CRM são disparados. Se você tiver um Flow configurado com o gatilho “Contato criado”, a automação será executada automaticamente — por exemplo, enviando uma mensagem de boas‑vindas pelo WhatsApp ou notificando o time de vendas. Isso significa que a integração via API não apenas povoa a base, mas também ativa os fluxos de comunicação já existentes na conta.

Para quem essa integração é indicada

Empresas que migram de outro CRM ou planilha e precisam importar milhares de contatos de uma só vez, mantendo a base da Papo sincronizada.
Operações que captam leads em sistemas externos (landing pages, ERPs, e‑commerce) e desejam que eles entrem automaticamente no CRM da Papo, prontos para receber atendimento ou campanhas.
Times de TI que constroem integrações customizadas entre a Papo e ferramentas internas, utilizando a API como ponte para manter os dados de clientes sempre atualizados.
Revendedores white label que gerenciam múltiplas contas e querem automatizar a criação de contatos em escala para seus clientes.

Perguntas frequentes

Preciso de uma chave secreta para criar ou atualizar contatos?

Sim. Todas as operações de escrita (criação, atualização) exigem autenticação com a chave secreta da conta. A chave pública sozinha não autoriza modificações.

Posso enviar milhares de contatos de uma só vez?

A API processa um contato por requisição. Para volumes grandes, você deve automatizar o envio sequencial, respeitando os limites de taxa descritos na documentação oficial.

Os contatos criados via API disparam o Flow de “Contato criado”?

Sim. O evento de criação é o mesmo, independentemente da origem. Se houver um Flow ativo com esse gatilho, ele será executado para cada contato inserido via API.

Como sei se um contato já existe para evitar duplicidade?

Você pode utilizar os endpoints de busca (filtrando por e‑mail ou telefone) antes de criar. A documentação da API detalha os parâmetros de consulta disponíveis.

A API permite atualizar apenas alguns campos do contato?

Sim. No corpo da requisição de atualização, envie somente os campos que deseja modificar. Os demais permanecem inalterados.

Onde encontro a lista completa de endpoints e parâmetros?

A referência completa está disponível na página de documentação da API. Lá você encontra os paths, métodos, payloads e exemplos atualizados.