EntrarTeste grátis

API · Atualizado em 12/10/2026

API do Pipe: visão geral e primeira chamada

Entenda o que a API do Pipe faz, escolha entre API, MCP e Builder e faça sua primeira chamada com uma chave de API em poucos minutos.

Neste artigo
  1. Quando usar
  2. Qual caminho usar
  3. Pré-requisitos
  4. Passo a passo: sua primeira chamada
  5. Resultado esperado
  6. O que a API cobre
  7. Problemas comuns
  8. Boas práticas
  9. Próximos passos
  10. Perguntas frequentes

A API do Pipe deixa um sistema seu conversar com o atendimento: enviar mensagens, abrir tickets, consultar contatos, puxar relatórios e receber eventos por webhook. Ela segue o padrão REST, usa JSON e é autenticada por uma chave de API que você cria na Gestão.

Quando usar

  • Quando um sistema seu (CRM, ERP, n8n, script) precisa enviar mensagens, abrir tickets ou ler dados do atendimento.
  • Quando você quer puxar histórico e relatórios para um painel ou BI.
  • Quando precisa reagir a eventos do Pipe, como ticket criado ou mensagem entregue.

Qual caminho usar

CaminhoPara quemQuando escolher
API por chaveQuem programaIntegração estável entre sistemas, com formato previsível e controle por escopo. Este guia
MCPQuem prefere conversar com um agente de IAConfigurar e consultar o atendimento em português, sem escrever código. Veja a visão geral do MCP
BuilderQuem monta o atendimentoFluxos de conversa, menus e regras dentro do Pipe, sem integração externa. Veja como criar um fluxo

Os três podem conviver. O Builder cuida da conversa automática, a API liga o Pipe ao resto da sua operação e o MCP ajuda a configurar.

Pré-requisitos

  • Uma conta no Pipe com pelo menos um fluxo e um canal conectado.
  • Uma chave de API. O passo a passo está em Autenticação e chaves de API.
  • Um programa para fazer chamadas HTTP, como curl, Postman ou a biblioteca HTTP da sua linguagem.

Passo a passo: sua primeira chamada

  1. Crie uma chave na Gestão e copie o valor. Ele começa com pipe_.
  2. Guarde a chave em uma variável de ambiente, em vez de colar no comando:
export PIPE_CHAVE="pipe_exemplo_000000000000000000000000"
  1. Liste as filas do seu fluxo. É uma leitura, então não altera nada:
curl -s https://http.pipebr.app/v1/queues \
  -H "Authorization: Bearer $PIPE_CHAVE"
  1. Confira a resposta. Ela traz a lista em data e o controle de paginação em page_info:
{
  "data": [
    {
      "id": "b3a1c9de-0000-4000-8000-000000000001",
      "nome": "Vendas",
      "cor": null,
      "ordem": 1,
      "ativa": true,
      "capacidade_padrao": 5,
      "flowId": "b3a1c9de-0000-4000-8000-0000000000f1",
      "aguardando": 2,
      "inAttendance": 3
    }
  ],
  "page_info": { "has_next_page": false, "end_cursor": null }
}
  1. Faça uma escrita simples. Este exemplo cria (ou encontra) um contato:
curl -s -X POST https://http.pipebr.app/v1/contacts \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name": "Maria Exemplo", "phoneE164": "+5511955550101"}'

A resposta traz o contato e created: true quando ele foi criado agora, ou created: false quando já existia.

Resultado esperado

Você recebe JSON com status 200 (leituras) ou 201 (criações). Se vier 401, a chave está ausente, errada, revogada ou expirada. Se vier 403, a chave não tem o escopo da rota. Os detalhes estão em Erros, respostas e paginação.

O que a API cobre

AssuntoArtigo
Chaves e formatos de autenticaçãoAutenticação e chaves de API
Permissões de cada chaveEscopos e permissões
Formato de erro e paginaçãoErros, respostas e paginação
Limite de chamadas e repetição seguraLimites de uso e idempotência
Mudanças na APIVersões e notas de versão
Enviar texto, mídia, modelos e reaçõesEnviar mensagens
Contatos e etiquetas de contatoContatos
Variáveis do bot e sessões presas no botContexto do contato e sessões do bot
Tickets, transferência e filas onlineConversas e tickets
Mensagens ativas e campanhasMensagens ativas e campanhas
Mensagens agendadasAgendamentos
Relatórios e monitoramentoRelatórios
Eventos por webhookWebhooks e eventos
Etiquetas, respostas rápidas, regras e modelosConsultar cadastros
Formato de comandos estilo BlipCompatibilidade com a Blip
O que a API ainda não fazLimitações da API

Problemas comuns

  • 401 logo na primeira chamada: confira se o cabeçalho é Authorization: Bearer pipe_... e se a chave não foi revogada. A chave aparece completa só uma vez, na criação.
  • 404 em um recurso que existe: uma chave de fluxo só enxerga o próprio fluxo. Recursos de outro fluxo respondem 404, de propósito.
  • 429 em testes em loop: cada chave tem limite de chamadas por segundo e por minuto. Veja Limites de uso.

Boas práticas

  • Guarde a chave em variável de ambiente ou em um cofre de segredos, nunca no código nem em repositório.
  • Use uma chave por integração, com o menor conjunto de escopos possível.
  • Trate respostas de erro pelo campo error.code, que é estável, e não pelo texto da mensagem.

Próximos passos

Perguntas frequentes

Qual é o endereço da API?

Para integrações com chave de API, use https://http.pipebr.app. As rotas começam com /v1, como /v1/queues. O mesmo conjunto também responde em https://api.pipebr.app enquanto esse endereço atender integradores.

Preciso de cadastro para usar a API?

Você precisa de uma chave de API criada na Gestão, em Configurações e Chaves de acesso do fluxo. Não existe login nem cookie na API por chave.

A API tem formato JSON?

Sim. Corpo e respostas são JSON em UTF-8. Erros seguem sempre o mesmo formato, com code e message.

Posso testar sem afetar clientes reais?

Comece pelas rotas de leitura, como GET /v1/queues. Elas não alteram nada. Para enviar mensagens, use um contato seu e um canal de teste.