Pular para o conteúdo

API v1 · Guia

Autenticação e escopos

Como criar o token pessoal, quais escopos escolher e o que o gerente e o vendedor enxergam pela API.

Crie um token pessoal em Configurações e envie em todo pedido no cabeçalho Authorization: Bearer <token>. O token carrega a empresa, o seu papel e os escopos que você escolheu (crm:read, crm:write, inbox:read, inbox:send). A sessão do navegador não vale na v1: sem o cabeçalho a resposta é 401.

O token enxerga o mesmo que você enxerga no Rumo CRM: o gerente vê a empresa inteira, o vendedor vê só o que é dele. Um registro de outra empresa ou fora do seu papel responde 404, como se não existisse.

Criar o token

  1. No Rumo CRM, abra Configurações → API e integrações.
  2. Dê um nome que diga onde o token vai rodar (por exemplo, “ERP” ou “Painel de BI”).
  3. Marque só os escopos de que essa integração precisa e escolha a validade.
  4. Copie o token na hora: ele aparece uma vez só. Guarde numa variável de ambiente ou num cofre de segredos, nunca no código de um site ou aplicativo, onde qualquer pessoa pode ler.
  5. Para cortar o acesso, revogue o token na mesma tela. Vale no pedido seguinte.
Terminal
curl "https://rumocrm.com/api/v1/contacts?limit=1" \
  -H "Authorization: Bearer $RUMO_TOKEN"

Escopos por operação

Um painel que só lê precisa de um escopo de leitura. Se o token vazar, o estrago fica limitado ao que ele pode fazer.

crm:readCRM: ler · Ver contatos, empresas, negócios, funis e atividades.

  • GET/contacts
  • GET/contacts/{id}
  • GET/companies
  • GET/companies/{id}
  • GET/pipelines
  • GET/pipelines/{id}
  • GET/pipelines/{id}/stages
  • GET/deals
  • GET/deals/{id}
  • GET/deals/{id}/products

crm:writeCRM: escrever · Criar e editar contatos, empresas, negócios, tarefas e notas.

  • POST/contacts
  • PATCH/contacts/{id}
  • POST/companies
  • PATCH/companies/{id}
  • DELETE/companies/{id}
  • POST/deals
  • PATCH/deals/{id}
  • DELETE/deals/{id}
  • POST/deals/{id}/move
  • POST/deals/{id}/win
  • POST/deals/{id}/lose
  • PUT/deals/{id}/products

inbox:readInbox: ler · Ler conversas e mensagens do WhatsApp e do Instagram.

  • GET/channels
  • GET/conversations
  • GET/conversations/{id}
  • GET/conversations/{id}/messages
  • GET/conversations/{id}/messages/{messageId}

inbox:sendInbox: enviar · Enviar mensagens aos clientes em seu nome. Use com cuidado.

  • POST/conversations/{id}/messages

Gerente e vendedor

O token não tem papel próprio: ele usa o papel de quem o criou, conferido a cada pedido. Para uma integração que precisa da empresa inteira (ERP, BI, planilha de comissão), crie o token com um usuário gerente. Um token de vendedor serve para automações da carteira dele e enxerga o mesmo que ele enxerga no Rumo CRM. A regra exata de cada recurso está na descrição da operação, na referência.

401, 403 ou 404

SituaçãoRespostaO que fazer
Pedido sem o cabeçalho, ou token inexistente, vencido ou revogado401 missing_api_token ou invalid_api_tokenConfira o token. Se foi revogado ou venceu, crie outro.
A pessoa dona do token saiu da empresa ou foi desativada401 invalid_api_tokenO token morre junto com o acesso dela. Crie um token com outro usuário.
O token não tem o escopo que a operação exige403 insufficient_api_token_scopeCrie um token com o escopo (o escopo não muda depois de criado).
O papel de quem criou o token não permite a ação403 permission_deniedUse um token de gerente. Cada operação da referência diz o papel exigido.
O registro é de outra empresa, está fora do papel do token ou não existe404 resource_not_foundPara o vendedor, o registro não é dele. A API não diz qual dos três casos é.

Por que 404 e não 403? Um 403 confirmaria que o registro existe. Respondendo 404, um token não descobre, testando ids, o que existe em outra empresa ou na carteira de um colega. O 403 fica para o que o token já sabe que existe: a operação em si.

PróximoPaginação e updatedSince