Autenticação

Toda requisição v3 carrega duas coisas: quem você é (um token de API) e em qual workspace você está atuando (um header, ou o workspace padrão do seu token).

Seu token de API

Envie o token no header apikey, na íntegra, incluindo o prefixo sk_live_.

curl https://api.pingonotify.com/v3/connections \
  -H "apikey: sk_live_a1b2c3d4e5f6..."

Criando um token

Crie tokens pelo painel, ou pela própria API:

curl -X POST https://api.pingonotify.com/v3/api-tokens \
  -H "apikey: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Servidor de produção" }'

{
  "id": "0195f3a0-...",
  "name": "Servidor de produção",
  "token": "sk_live_xF3k9...",
  "prefix": "sk_live",
  "tokenLast4": "9f2a"
}

Se você perder um token, rotacione-o (PATCH /v3/api-tokens/{id} com refreshToken: true) — o segredo antigo para de funcionar no instante em que o novo é emitido. Excluir um token (DELETE /v3/api-tokens/{id}) o revoga imediatamente.

Apenas um Owner ou Admin pode criar, rotacionar ou excluir tokens.

O que um token pode fazer

Um token não tem escopos próprios. Ele herda as permissões do usuário que o criou, no workspace ao qual pertence. Um token criado por um Owner pode fazer tudo que um Owner pode — inclusive mexer na cobrança e excluir o workspace.

Trate um token como a credencial de uma pessoa, não de uma integração. Crie-o sob uma conta cujo papel corresponda ao que a integração realmente precisa.

Escolhendo o workspace

Seu token pertence a um workspace, e é contra ele que a requisição roda quando você não diz nada.

Para atuar em um workspace diferente do qual você participa, envie o id dele no header X-Account-Id:

curl https://api.pingonotify.com/v3/helpdesk/conversations \
  -H "apikey: sk_live_..." \
  -H "X-Account-Id: 0195f3a0-1234-7890-abcd-ef0123456789"

Liste os workspaces disponíveis para você com GET /v3/accounts. Apontar o X-Account-Id para um workspace do qual você não é membro retorna 403.

Papéis e permissões

Todo membro de um workspace tem um ou mais papéis, e o papel decide o que a API permite. Uma ação negada retorna 403 Insufficient account permissions.

Duas regras valem conhecer antes de desenhar uma integração em cima de um papel:

• Você nunca pode conceder um papel igual ou acima do seu. Um Manager pode convidar um Agent, mas não outro Manager.
• Um Agent só enxerga as caixas de entrada das quais é membro. Uma conversa em uma caixa da qual ele não participa não é proibida para ele — ela simplesmente não existe do ponto de vista da API, e retorna 404. Isso é proposital: um 403 confirmaria que a conversa existe.

Exigências de plano

Alguns endpoints precisam de mais do que um papel.

O helpdesk é um recurso PRO para escrita. Qualquer membro de qualquer plano pode ler o helpdesk, mas criar, responder, atribuir ou configurar exige o plano PRO. Sem ele, esses endpoints retornam:

{
  "message": "HELPDESK_PLAN_REQUIRED",
  "hint": "O helpdesk está disponível no plano PRO."
}

Conexões oficiais do WhatsApp e campanhas oficiais exigem um plano pago, e tanto conexões quanto mensagens são medidas contra os limites do seu plano. Quando um limite é atingido você recebe um 403 com um código como USER_PLAN_EXCEEDED_CONNECTIONS ou USER_PLAN_EXCEEDED_MESSAGES. Consulte sua folga a qualquer momento com GET /v3/summary.

Tokens OAuth 2.1

Existe uma segunda credencial: um access token OAuth 2.1, enviado em Authorization: Bearer. É o que um assistente de IA ou uma aplicação de terceiro usa em vez de um token de API, emitido pelo servidor de autorização do próprio Pingo depois que uma pessoa aprova numa tela de consentimento.

Ele difere do apikey em três pontos que importam. Ele tem escopo — e escopo só estreita o que o dono dele pode fazer, nunca amplia. Ele é preso a um workspace, escolhido no consentimento, então X-Account-Id não o aponta para outro. E ele expira: uma hora, com refresh token quando o cliente se registrou para isso.

Para registrar um cliente, rodar o fluxo e ler todos os erros que ele pode devolver, veja OAuth 2.1. A primeira coisa construída sobre ele é o Servidor MCP.

Endpoints sem apikey

Um punhado de rotas não leva apikey. Cada uma documenta a sua própria credencial: