Para criar e atualizar negócios no Kanban 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 criam cards, movem oportunidades entre etapas e marcam resultados, integrando o funil de vendas a sistemas externos sem intervenção manual.
A API da Papo expõe operações de escrita para o Kanban, permitindo trabalhar com funis, etapas e cards do CRM. Isso viabiliza sincronizar um ERP, uma landing page ou uma ferramenta de pagamento com o funil de vendas, mantendo as oportunidades sempre atualizadas.
Resumo da integração com o Kanban
| 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. Conhecer funis e etapas | Listar os funis do Kanban e suas etapas para obter os identificadores necessários. | A resposta da API traz os identificadores usados nas próximas chamadas. |
| 4. Criar ou mover cards | Enviar a operação para criar um card em uma etapa, mover um card de um contato para outra etapa ou marcar resultado. | Cada operação processa uma ação; para muitos registros, automatize o envio em loop. |
| 5. Validar a resposta | A API retorna success: true e os dados do card ou da listagem. |
Em caso de erro, o corpo da resposta traz código e mensagem para correção. |
O que a API permite fazer no Kanban
Com os endpoints do Kanban, você pode programaticamente:
- Listar os funis disponíveis e suas etapas, com nome e posição.
- Listar os cards do CRM.
- Listar todos os cards ganhos, para relatórios de vendas fechadas.
- Criar um card em uma etapa, opcionalmente vinculado a um contato existente.
- Mover o card de um contato para outra etapa do funil.
- Marcar cards como ganhos ou como perdas.
- Criar um funil Kanban com etapas padrão ou personalizadas.
Essas operações permitem que o funil reflita automaticamente o que acontece fora da Papo, como uma compra confirmada, uma reunião agendada ou um cadastro vindo do site.
Como funciona a autenticação e as chamadas
Toda chamada que modifica dados 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 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 Kanban aceitam os verbos HTTP adequados para criar, mover, atualizar e listar. Como a documentação completa detalha os paths, parâmetros e campos aceitos, recomendamos consultar a referência oficial da API antes de codificar.
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 nos 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.
Fluxo típico de integração com sistemas externos
Um script em Python, Node.js ou uma automação em ferramentas como n8n pode executar o ciclo completo do funil:
- Listar os funis e etapas para obter os identificadores de cada coluna.
- Criar um card na etapa inicial, vinculando a um contato se necessário.
- Mover o card para uma nova etapa quando um evento externo ocorrer — por exemplo, pagamento confirmado ou reunião marcada.
- Marcar o card como ganho ou perda quando a oportunidade for concluída.
- Listar os cards ganhos para alimentar relatórios, dashboards ou sistemas de BI.
Como a API é REST e utiliza JSON, qualquer linguagem com suporte a HTTP funciona. Os detalhes de payload e campos de cada operação estão na documentação oficial.
Para quem essa integração é indicada
- Empresas que captam oportunidades em sistemas externos, como landing pages, ERPs ou e‑commerce, e desejam que elas entrem automaticamente no funil da Papo.
- Operações que precisam mover cards conforme eventos de pagamento, como gateways ou plataformas de cobrança, sem abrir o CRM manualmente.
- Times de BI e dados que querem puxar cards ganhos e valores para dashboards em tempo real.
- Equipes de TI que constroem integrações customizadas entre a Papo e ferramentas internas, usando a API como ponte entre o funil de vendas e o restante da operação.
Perguntas frequentes
Preciso usar a chave pública em todas as chamadas?
Não. A chave pública é opcional, mas, se enviada no header X-Papo-Public-Key, precisa corresponder à mesma conta da chave secreta.
Como sei quais etapas existem no meu funil?
Liste os funis do Kanban pela API. A resposta retorna as etapas de cada funil com seus identificadores, usados para criar ou mover cards.
Posso criar um card já vinculado a um contato?
Sim. A criação de card permite vincular opcionalmente a um contato existente, mantendo o histórico e os dados do cliente associados à oportunidade.
A API permite atualizar o valor de um card?
A API expõe operações de escrita para cards do Kanban. Os campos exatos que podem ser atualizados, incluindo valores, estão detalhados na documentação oficial da API.
É possível marcar um card como ganho ou perda pela API?
Sim. A API permite marcar cards como ganhos e como perdas, além de listar todos os cards ganhos para relatórios e dashboards.
Preciso programar ou posso usar ferramentas de automação?
Você pode usar qualquer linguagem com suporte a HTTP ou ferramentas de automação como n8n, executando as chamadas em sequência conforme o fluxo desejado.
Leia também
- Como usar a API da Papo para criar e atualizar contatos em massa
- Como receber eventos em tempo real da Papo via Webhook (outbound)
O primeiro usuário é gratuito e não exige cartão de crédito.