Conexões de entrada

A conexão de entrada é um endereço do Papeador para o seu sistema avisar que algo aconteceu: um pagamento, uma matrícula, um cancelamento. O Papeador acha ou cria o contato e aplica as regras da conexão: mudar o estágio, pôr ou tirar etiquetas, registrar uma compra, criar uma nota.

Criar

1. No Papeador, abra Integrações → Conexões de entrada → Nova conexão (só o dono e os admins).
2. Escolha o projeto em que os contatos entram e, se quiser, gere um segredo para o aviso vir assinado (recomendado).
3. Copie o endereço (https://app.papeador.com.br/webhooks/entrada/…) e cadastre no seu sistema como destino de webhook.

O formato do aviso

O aviso chega por POST, em JSON, de um destes jeitos.

Formato padrão do Papeador. Só evento e o e-mail, telefone ou id_externo do contato são obrigatórios; id evita processar o mesmo aviso duas vezes.

{
  "id": "evt-123",
  "evento": "aluno.matriculado",
  "contato": { "nome": "Ana", "email": "ana@exemplo.com", "telefone": "+5551999990000", "id_externo": "123" },
  "tags": ["matriculado"],
  "estagio": "cliente",
  "compra": { "id": "pg-9", "valor": 197.0, "descricao": "Curso X", "status": "paga", "valido_ate": "2026-12-31" },
  "nota": "Texto que vira nota no contato",
  "dados": { "turma": "noite" }
}

Formato do seu sistema (de-para). Mande como o seu sistema já manda. Na tela da conexão, diga de onde vem cada campo (evento, id, nome, e-mail, telefone, id do usuário) pelo caminho no JSON, como cliente.email ou itens.0.id. O último aviso recebido aparece na tela como exemplo para montar o de-para.

Regras

Cada regra diz o que fazer num evento (ou em todos):

• filtro: só aplica quando o aviso tem um valor. caminho=valor olha só aquele campo (ex.: dados.situacao=cancelada); sem o =, vale o valor em qualquer campo;
• estágio: muda o estágio do contato no projeto da conexão;
• etiquetas: põe e tira;
• compra: registra ou estorna, com id, valor e “válido até” vindos do aviso;
• nota: cria uma nota, em que {{caminho}} vira o valor do aviso.

O id do usuário no seu sistema

Mande contato.id_externo sempre que tiver. O Papeador liga a ficha a esse id (no projeto da conexão) e, dali em diante, acha a ficha por ele, mesmo que a pessoa troque o e-mail no seu sistema. É o mesmo id do sub do chat do usuário logado: pagamento e conversa caem na mesma ficha.

• Ordem da busca: id já ligado, depois e-mail ou telefone, depois ficha nova.
• Aviso só com id_externo vale quando o id já está ligado (senão fica no histórico, sem contato).
• Se o id está ligado a uma ficha e o e-mail do aviso é de outra, vale o id, e a ficha ganha uma nota para a equipe decidir se junta as duas.

Respostas

Código	Quando
200	processado, repetido (mesmo id) ou sem contato
400	fora do formato
401	assinatura inválida
403	conexão desligada
404	endereço errado

Com segredo, o aviso precisa vir assinado, no cabeçalho configurado na conexão (padrão X-Papeador-Assinatura). Veja como assinar: é o mesmo formato dos avisos que o Papeador manda.

A tela da conexão mostra o histórico dos avisos recebidos e o que cada um fez na ficha.