{ "info": { "name": "API do Pingo (v1)", "description": "Coleção da API pública do Pingo. 1) Crie uma chave em Configurações > API no Pingo. 2) Cole a chave na variável `api_key` desta coleção (aba Variables). 3) Rode GET /pipelines para ver os ids de funil e etapa. A chave é de servidor: não a coloque em páginas públicas. Documentação: https://www.pingotracker.com.br/docs/api", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_key}}", "type": "string" } ] }, "variable": [ { "key": "base_url", "value": "https://www.pingotracker.com.br/api/v1" }, { "key": "api_key", "value": "pgo_live_COLE_SUA_CHAVE_AQUI" }, { "key": "lead_id", "value": "" } ], "item": [ { "name": "Leads", "item": [ { "name": "Criar ou atualizar um lead", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{base_url}}/leads", "host": [ "{{base_url}}" ], "path": [ "leads" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"Maria Silva\",\n \"phone\": \"41999990000\",\n \"email\": \"maria@exemplo.com.br\",\n \"notes\": \"Quer horário à tarde\",\n \"tags\": [\n \"site\"\n ],\n \"external_id\": \"form-2026-0001\",\n \"consent\": true,\n \"attribution\": {\n \"utm_source\": \"google\",\n \"utm_medium\": \"cpc\",\n \"utm_campaign\": \"implante-curitiba\",\n \"gclid\": \"Cj0KCQjwExemploGclid123\",\n \"referrer\": \"https://www.google.com/\"\n },\n \"deal\": {\n \"value\": 1500.5\n }\n}", "options": { "raw": { "language": "json" } } }, "description": "Cria o lead e o coloca no funil. Se já existe cadastro com o mesmo telefone, atualiza em vez de duplicar.\n\nO telefone é o que identifica o lead. O Pingo reconhece o mesmo número com ou sem o 9º dígito e com ou sem o 55, então reenviar \"41 99999-0000\" e \"+55 41 9196-8668\" não cria dois cadastros.\n\nVocê NÃO envia a origem. Ela é calculada pelo Pingo a partir dos sinais de `attribution` (utm_source, utm_medium, fbclid, gclid...), com a mesma regra do resto do aplicativo. Sem nenhum sinal, o lead fica como `untracked` (Não rastreado). Sinal com formato inválido é ignorado e voltado num aviso (`warnings`), sem derrubar o lead.\n\nVale o primeiro contato: se o lead já tem uma origem registrada (qualquer uma diferente de `untracked` e `direct`, inclusive `social`, `organic` e `referral`), a chamada não muda nenhum dado de origem dele (utm, fbc, gclid...). Se a origem é `untracked` ou `direct`, o Pingo preenche a origem e só os campos de origem que ainda estão vazios, então a origem de um lead antigo pode mudar uma única vez.\n\nPara repetir o envio com segurança (formulário reenviado, webhook que chega duas vezes), mande um `external_id` único por envio. Com o mesmo `external_id`, o Pingo devolve `duplicate: true` e não grava nada de novo.\n\nO lead entra na etapa de entrada do funil padrão. Para outro funil ou etapa, informe `deal.pipeline_id` e `deal.stage_id` (veja GET /pipelines). Se o lead já tem negócio aberto nesse funil, ele NÃO é movido: para mover, use POST /leads/{id}/stage.\n\nEsta chamada só grava. Não envia mensagem ao lead e não dispara NA HORA nenhuma automação do funil. Atenção: se a etapa tem uma automação por tempo (por exemplo, follow-up para quem fica parado há alguns dias), ela passa a valer para o lead da API como vale para qualquer outro lead.\n\nA nota (`notes`) é acrescentada à ficha do lead, marcada com [API · nome da chave · data], sem apagar o que a equipe já escreveu. Tags novas são criadas na conta (até 5 por chamada).\n\nUma chave SEM `leads:read` (a de um formulário, por exemplo) recebe sempre a mesma resposta curta, `{ \"received\": true }` com status 202, seja o lead novo ou já existente: assim a chave de escrita não serve para descobrir quem já é cliente. Com `leads:read`, a resposta traz `id`, `created`, `duplicate`, `deal` e o cadastro (`lead`); `created: false` (status 200) quer dizer que o telefone já era conhecido no Pingo (cadastro ou conversa).\n\nPermissão necessária: leads:write." }, "response": [ { "name": "Exemplo (201)", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/leads" } }, "status": "OK", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": \"cm1lead0000000000000000a1\",\n \"created\": true,\n \"duplicate\": false,\n \"deal\": {\n \"id\": \"cm1negoc0000000000000000a1\",\n \"pipeline_id\": \"cm1funil000000000000000a1\",\n \"stage_id\": \"cm1etapa000000000000entr1\",\n \"status\": \"open\",\n \"value\": 1500.5,\n \"entered_stage_at\": \"2026-10-15T13:20:11.000Z\",\n \"created_at\": \"2026-10-15T13:20:11.000Z\"\n },\n \"lead\": {\n \"id\": \"cm1lead0000000000000000a1\",\n \"name\": \"Maria Silva\",\n \"phone\": \"5541999990000\",\n \"email\": \"maria@exemplo.com.br\",\n \"tags\": [\n \"site\",\n \"vip\"\n ],\n \"origin\": \"google_ads\",\n \"utm\": {\n \"source\": \"google\",\n \"medium\": \"cpc\",\n \"campaign\": \"implante-curitiba\"\n },\n \"deals\": [\n {\n \"id\": \"cm1negoc0000000000000000a1\",\n \"pipeline_id\": \"cm1funil000000000000000a1\",\n \"stage_id\": \"cm1etapa000000000000entr1\",\n \"status\": \"open\",\n \"value\": 1500.5,\n \"entered_stage_at\": \"2026-10-15T13:20:11.000Z\",\n \"created_at\": \"2026-10-15T13:20:11.000Z\"\n }\n ],\n \"created_at\": \"2026-10-15T13:20:11.000Z\",\n \"updated_at\": \"2026-10-15T13:20:11.000Z\"\n }\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "if (r.data && r.data.id) { pm.collectionVariables.set('lead_id', r.data.id); }" ] } } ] }, { "name": "Listar leads", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{base_url}}/leads?limit=50&updated_since=2026-10-15T00:00:00Z", "host": [ "{{base_url}}" ], "path": [ "leads" ], "query": [ { "key": "limit", "value": "50" }, { "key": "updated_since", "value": "2026-10-15T00:00:00Z" } ] }, "description": "Lista os leads da conta, de 100 em 100 no máximo, com filtros que não são dado pessoal.\n\nAs páginas são por `cursor`: devolva em `cursor` o `next_cursor` da resposta anterior até ele vir `null`.\n\nPara sincronizar de tempos em tempos, use `updated_since` com a hora da última sincronização menos 5 minutos de folga. A data de atualização do lead considera também a mudança de etapa dos negócios. Um lead pode aparecer mais de uma vez em sincronizações seguidas; trate pelo `id`.\n\nPara achar UM lead por telefone ou e-mail, use POST /leads/lookup (telefone e e-mail não devem ir na URL).\n\n`origin` e `utm` só aparecem se o plano da conta inclui a Origem automática.\n\nPermissão necessária: leads:read." }, "response": [ { "name": "Exemplo (200)", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/leads?limit=50&updated_since=2026-10-15T00:00:00Z" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"cm1lead0000000000000000a1\",\n \"name\": \"Maria Silva\",\n \"phone\": \"5541999990000\",\n \"email\": \"maria@exemplo.com.br\",\n \"tags\": [\n \"site\",\n \"vip\"\n ],\n \"origin\": \"google_ads\",\n \"utm\": {\n \"source\": \"google\",\n \"medium\": \"cpc\",\n \"campaign\": \"implante-curitiba\"\n },\n \"deals\": [\n {\n \"id\": \"cm1negoc0000000000000000a1\",\n \"pipeline_id\": \"cm1funil000000000000000a1\",\n \"stage_id\": \"cm1etapa000000000000entr1\",\n \"status\": \"open\",\n \"value\": 1500.5,\n \"entered_stage_at\": \"2026-10-15T13:20:11.000Z\",\n \"created_at\": \"2026-10-15T13:20:11.000Z\"\n }\n ],\n \"created_at\": \"2026-10-15T13:20:11.000Z\",\n \"updated_at\": \"2026-10-15T13:20:11.000Z\"\n }\n ],\n \"next_cursor\": null\n}" } ] }, { "name": "Achar um lead por telefone ou e-mail", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{base_url}}/leads/lookup", "host": [ "{{base_url}}" ], "path": [ "leads", "lookup" ] }, "body": { "mode": "raw", "raw": "{\n \"phone\": \"41999990000\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Devolve o lead que tem aquele telefone (ou e-mail). É POST de propósito: dado pessoal não deve ir na URL.\n\nInforme exatamente um entre `phone` e `email`.\n\nO telefone é comparado com e sem o 9º dígito e com e sem o 55. O e-mail não diferencia maiúscula. Número de outro país vai com o + na frente (ex.: +14155550123), mesmo que a resposta o traga só com dígitos: sem o +, 10 ou 11 dígitos só valem se forem brasileiros.\n\nSe houver mais de um cadastro com o mesmo contato, a resposta é 409 (`ambiguous_lead`): a API não adivinha qual é o certo.\n\nPermissão necessária: leads:read." }, "response": [ { "name": "Exemplo (200)", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/leads/lookup" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": \"cm1lead0000000000000000a1\",\n \"name\": \"Maria Silva\",\n \"phone\": \"5541999990000\",\n \"email\": \"maria@exemplo.com.br\",\n \"tags\": [\n \"site\",\n \"vip\"\n ],\n \"origin\": \"google_ads\",\n \"utm\": {\n \"source\": \"google\",\n \"medium\": \"cpc\",\n \"campaign\": \"implante-curitiba\"\n },\n \"deals\": [\n {\n \"id\": \"cm1negoc0000000000000000a1\",\n \"pipeline_id\": \"cm1funil000000000000000a1\",\n \"stage_id\": \"cm1etapa000000000000entr1\",\n \"status\": \"open\",\n \"value\": 1500.5,\n \"entered_stage_at\": \"2026-10-15T13:20:11.000Z\",\n \"created_at\": \"2026-10-15T13:20:11.000Z\"\n }\n ],\n \"created_at\": \"2026-10-15T13:20:11.000Z\",\n \"updated_at\": \"2026-10-15T13:20:11.000Z\"\n }\n}" } ], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "if (r.data && r.data.id) { pm.collectionVariables.set('lead_id', r.data.id); }" ] } } ] }, { "name": "Consultar um lead", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{base_url}}/leads/{{lead_id}}", "host": [ "{{base_url}}" ], "path": [ "leads", "{{lead_id}}" ] }, "description": "Devolve o lead pelo id, com tags, origem e negócios.\n\nUm id que não existe na sua conta e um id de outra conta dão exatamente a mesma resposta: 404.\n\nPermissão necessária: leads:read." }, "response": [ { "name": "Exemplo (200)", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/leads/{{lead_id}}" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": \"cm1lead0000000000000000a1\",\n \"name\": \"Maria Silva\",\n \"phone\": \"5541999990000\",\n \"email\": \"maria@exemplo.com.br\",\n \"tags\": [\n \"site\",\n \"vip\"\n ],\n \"origin\": \"google_ads\",\n \"utm\": {\n \"source\": \"google\",\n \"medium\": \"cpc\",\n \"campaign\": \"implante-curitiba\"\n },\n \"deals\": [\n {\n \"id\": \"cm1negoc0000000000000000a1\",\n \"pipeline_id\": \"cm1funil000000000000000a1\",\n \"stage_id\": \"cm1etapa000000000000entr1\",\n \"status\": \"open\",\n \"value\": 1500.5,\n \"entered_stage_at\": \"2026-10-15T13:20:11.000Z\",\n \"created_at\": \"2026-10-15T13:20:11.000Z\"\n }\n ],\n \"created_at\": \"2026-10-15T13:20:11.000Z\",\n \"updated_at\": \"2026-10-15T13:20:11.000Z\"\n }\n}" } ] }, { "name": "Atualizar um lead", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{base_url}}/leads/{{lead_id}}", "host": [ "{{base_url}}" ], "path": [ "leads", "{{lead_id}}" ] }, "body": { "mode": "raw", "raw": "{\n \"name\": \"Maria Silva\",\n \"add_tags\": [\n \"retorno\"\n ],\n \"remove_tags\": [\n \"site\"\n ],\n \"notes\": \"Ligar na quinta\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Muda nome, e-mail, tags e acrescenta uma nota. O telefone não muda por aqui.\n\nEnvie só o que quer mudar, ao menos um campo.\n\n`email: null` apaga o e-mail. `add_tags` cria as tags que não existem; `remove_tags` ignora as que não existem. O telefone não pode ser alterado (ele liga o cadastro à conversa do WhatsApp).\n\nA mudança vale só no Pingo: o cadastro do seu sistema de gestão (Feegow, Clinicorp, Conta Azul...) não é alterado, então os dois podem ficar diferentes.\n\nA nota é acrescentada à ficha, nunca substitui. Se a ficha não comporta mais texto (limite de 2.000 caracteres), a resposta é 409 `notes_full` e NADA é alterado.\n\nPermissão necessária: leads:write." }, "response": [ { "name": "Exemplo (200)", "originalRequest": { "method": "PATCH", "header": [], "url": { "raw": "{{base_url}}/leads/{{lead_id}}" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": \"cm1lead0000000000000000a1\",\n \"updated\": true,\n \"lead\": {\n \"id\": \"cm1lead0000000000000000a1\",\n \"name\": \"Maria Silva\",\n \"phone\": \"5541999990000\",\n \"email\": \"maria@exemplo.com.br\",\n \"tags\": [\n \"site\",\n \"vip\"\n ],\n \"origin\": \"google_ads\",\n \"utm\": {\n \"source\": \"google\",\n \"medium\": \"cpc\",\n \"campaign\": \"implante-curitiba\"\n },\n \"deals\": [\n {\n \"id\": \"cm1negoc0000000000000000a1\",\n \"pipeline_id\": \"cm1funil000000000000000a1\",\n \"stage_id\": \"cm1etapa000000000000entr1\",\n \"status\": \"open\",\n \"value\": 1500.5,\n \"entered_stage_at\": \"2026-10-15T13:20:11.000Z\",\n \"created_at\": \"2026-10-15T13:20:11.000Z\"\n }\n ],\n \"created_at\": \"2026-10-15T13:20:11.000Z\",\n \"updated_at\": \"2026-10-15T13:20:11.000Z\"\n }\n }\n}" } ] } ] }, { "name": "Funil", "item": [ { "name": "Mover o lead de etapa", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{base_url}}/leads/{{lead_id}}/stage", "host": [ "{{base_url}}" ], "path": [ "leads", "{{lead_id}}", "stage" ] }, "body": { "mode": "raw", "raw": "{\n \"stage_id\": \"cm1etapa00000000000000pre1\"\n}", "options": { "raw": { "language": "json" } } }, "description": "Move o negócio aberto do lead para outra etapa do mesmo funil.\n\nMover pela API NÃO dispara a automação da etapa: não manda mensagem ao lead e não envia conversão ao Meta. É o mesmo que mover em massa no Pingo sem marcar \"disparar a automação\". Automações por tempo da etapa nova (\"parado há N dias\") continuam valendo.\n\nA API não entra em etapa de ganho (fechar exige registrar o valor no Pingo) e não tira o negócio de uma etapa de ganho (não desfaz venda). Mover para uma etapa de perda e reabrir (sair da perda) funcionam.\n\nSe o lead tem mais de um negócio aberto no funil da etapa, informe `deal_id`. Mover para a etapa em que o negócio já está devolve `changed: false`.\n\nPermissão necessária: pipeline:write." }, "response": [ { "name": "Exemplo (200)", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/leads/{{lead_id}}/stage" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"changed\": true,\n \"deal\": {\n \"id\": \"cm1negoc0000000000000000a1\",\n \"pipeline_id\": \"cm1funil000000000000000a1\",\n \"stage_id\": \"cm1etapa00000000000000pre1\",\n \"status\": \"open\",\n \"value\": 1500.5,\n \"entered_stage_at\": \"2026-10-15T14:02:40.000Z\",\n \"created_at\": \"2026-10-15T13:20:11.000Z\"\n }\n }\n}" } ] }, { "name": "Listar funis e etapas", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{base_url}}/pipelines", "host": [ "{{base_url}}" ], "path": [ "pipelines" ] }, "description": "Os funis da conta com suas etapas: são os ids que POST /leads e POST /leads/{id}/stage pedem.\n\nO funil padrão vem primeiro. `is_entry` marca a etapa onde o lead novo nasce; `is_won` e `is_lost` marcam as etapas de ganho e de perda.\n\nPermissão necessária: pipeline:read." }, "response": [ { "name": "Exemplo (200)", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/pipelines" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"cm1funil000000000000000a1\",\n \"name\": \"Comercial\",\n \"is_default\": true,\n \"stages\": [\n {\n \"id\": \"cm1etapa000000000000entr1\",\n \"name\": \"Leads de Entrada\",\n \"order\": 0,\n \"is_entry\": true,\n \"is_won\": false,\n \"is_lost\": false\n },\n {\n \"id\": \"cm1etapa00000000000000pre1\",\n \"name\": \"Pré Vendas\",\n \"order\": 1,\n \"is_entry\": false,\n \"is_won\": false,\n \"is_lost\": false\n },\n {\n \"id\": \"cm1etapa000000000000fech1\",\n \"name\": \"Fechado\",\n \"order\": 5,\n \"is_entry\": false,\n \"is_won\": true,\n \"is_lost\": false\n },\n {\n \"id\": \"cm1etapa000000000000perd1\",\n \"name\": \"Perdido (sem contato)\",\n \"order\": 6,\n \"is_entry\": false,\n \"is_won\": false,\n \"is_lost\": true\n }\n ]\n }\n ]\n}" } ] } ] }, { "name": "Métricas", "item": [ { "name": "Métricas do período", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "{{base_url}}/metrics?from=2026-10-01&to=2026-10-15", "host": [ "{{base_url}}" ], "path": [ "metrics" ], "query": [ { "key": "from", "value": "2026-10-01" }, { "key": "to", "value": "2026-10-15" } ] }, "description": "Números agregados da conta (leads por dia e por origem, negócios por etapa). Nenhum dado de pessoa.\n\nO período vai de `from` a `to`, os dois inclusive, em dias de Brasília (padrão: os últimos 30 dias; no máximo 366 dias).\n\n`leads` conta as conversas criadas no período, de qualquer canal (WhatsApp, formulários, API). Dias sem lead não aparecem em `daily`. `scheduled` conta os leads do período que estão AGORA numa etapa de agendamento: quem já avançou para outra etapa deixa de contar. `closed` conta os que estão numa etapa de venda ou numa etapa com valor configurado (uma etapa \"Agendou R$ 450\" conta). Os dois são `null` se a conta não configurou a etapa. `attended` são as consultas com comparecimento na agenda do período.\n\n`pipeline.stages[].open_deals` é o retrato de HOJE (negócios abertos por etapa), não depende do período.\n\n`by_origin` só aparece se o plano da conta inclui a Origem automática. Receita não faz parte desta versão.\n\nEsta rota é mais pesada: limite de 20 chamadas por minuto por chave.\n\nPermissão necessária: metrics:read." }, "response": [ { "name": "Exemplo (200)", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/metrics?from=2026-10-01&to=2026-10-15" } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"period\": {\n \"from\": \"2026-10-01\",\n \"to\": \"2026-10-15\"\n },\n \"leads\": 128,\n \"scheduled\": 31,\n \"closed\": 9,\n \"attended\": 24,\n \"daily\": [\n {\n \"date\": \"2026-10-14\",\n \"leads\": 9\n },\n {\n \"date\": \"2026-10-15\",\n \"leads\": 12\n }\n ],\n \"by_origin\": [\n {\n \"origin\": \"google_ads\",\n \"leads\": 60\n },\n {\n \"origin\": \"meta_ads\",\n \"leads\": 48\n },\n {\n \"origin\": \"direct\",\n \"leads\": 20\n }\n ],\n \"pipeline\": {\n \"id\": \"cm1funil000000000000000a1\",\n \"name\": \"Comercial\",\n \"stages\": [\n {\n \"id\": \"cm1etapa000000000000entr1\",\n \"name\": \"Leads de Entrada\",\n \"open_deals\": 14\n },\n {\n \"id\": \"cm1etapa00000000000000pre1\",\n \"name\": \"Pré Vendas\",\n \"open_deals\": 22\n }\n ]\n }\n }\n}" } ] } ] } ] }