Autenticação

Autentique suas requisições com uma chave de API ou com o login do usuário API (access_token).

Acelere sua integração!

Baixe a coleção do Postman com todos os endpoints da API Atys, organizados por módulo — é só preencher a sua chave de API.

Baixar coleção Postman 308 requisições · JSON · Collection v2.1
Importante: todas as requisições à API Atys são autenticadas pelo header Authorization: Bearer …. Você escolhe o que vai nele: uma chave de API ou um access_token obtido com login.

Como funciona

Toda integração usa um usuário API, criado em Configurações → Usuários API. A partir dele há duas formas de autenticar — as duas continuam válidas e podem ser usadas ao mesmo tempo:

Chave de API Recomendado
  1. O administrador gera a chave na plataforma e marca o que ela pode fazer.
  2. Seu sistema envia a chave no header Authorization. Não há login.
  • Não expira (a menos que você defina uma data)
  • Só acessa o que foi marcado
  • Revogável sem afetar outras integrações
Ver como fazer →
Login com usuário API Forma original
  1. Seu sistema faz login com o e-mail e a senha do usuário API e recebe um access_token.
  2. Envia o token no header Authorization e repete o login quando ele expira.
  • Expira em 45 dias (16 horas sem "lembrar")
  • Um novo login derruba o token anterior
  • Acessa tudo o que o usuário API pode
Ver como fazer →
Chave de APILogin com usuário API
Como obterGerada uma vez na plataformaPOST /api/oauth/token com e-mail e senha
ValidadeNão expira, salvo data definida45 dias (16 horas sem "lembrar")
Novo loginNão afeta a chaveDerruba o token anterior do mesmo dispositivo
PermissõesSó as marcadas na chaveTudo o que o usuário API pode
RevogarBotão Revogar, só aquela chaveTrocando a senha do usuário API
EndpointsOs da API v1 e os já documentadosTodos

Já integra com login? Nada muda: o POST /api/oauth/token continua funcionando. Para integrações novas, prefira a chave.

Chave de API (recomendado)

A chave de API é a forma recomendada de autenticar integrações. Ela é gerada pelo administrador da empresa e não depende de e-mail e senha: não expira (a menos que você defina uma data), não é derrubada por um novo login e pode ser revogada a qualquer momento sem afetar outras integrações.

Como gerar

  1. Na plataforma Atys, acesse Configurações → Usuários de API e crie um usuário API, se ainda não tiver.
  2. Na linha do usuário, clique no ícone de chave e em Gerar chave.
  3. Dê um nome (ex.: ERP), marque as permissões e, se quiser, uma data de expiração.
  4. Copie a chave exibida. Ela aparece uma única vez; se perder, revogue e gere outra.

Como usar

Envie a chave no header Authorization, exatamente como um access_token. Não há passo de login.

Exemplo de requisição com chave de API

cURL
curl https://api.atys.pro/api/v1/crm/pipelines \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"

Permissões

A chave só acessa os endpoints das permissões marcadas na criação:

PermissãoEndpoints
Enviar mensagens e consultar conversasEnvio pelo WhatsApp Oficial (api-send-message com ofc_whatsapp), edição e revogação de mensagens, conversas (contact-channels), canais (company-channels) e templates
Consultar CRMCRM (API v1): todas as consultas — funil, catálogos, negócios, notas, tarefas, histórico, agendamentos, documentos e relatórios
Criar, editar e mover negócios do CRMCRM (API v1): criar, editar, mover, ganhar/perder, arquivar, transferir, clonar e importar negócios; notas, tarefas, agendamentos, documentos e anexos
Consultar WhatsApp OficialWhatsApp Oficial (API v1): WABAs, números, qualidade, modo de operação, consumo, templates, grupos e ligações
Gerenciar WhatsApp OficialWhatsApp Oficial (API v1): cadastrar números, teto de gastos, criar e editar templates, grupos, participantes e ligações
Excluir no WhatsApp OficialWhatsApp Oficial (API v1): excluir templates, grupos, números e WABAs
Consultar ticketsTickets (API v1): tickets, catálogos, atendentes, contatos, etiquetas, interações e anexos
Criar, editar e responder ticketsTickets (API v1): abrir e editar tickets, status, prioridade, responsável, vínculos, fixar; responder, notas internas, anexos e acesso do contato
Consultar conversas e mensagensOmnichat (API v1): conversas, contador de não lidas, histórico, templates e respostas rápidas
Atender conversas e enviar mensagensOmnichat (API v1): atribuir, transferir, fixar, arquivar, encerrar e reabrir; enviar, editar, apagar, reagir e encaminhar mensagens
Consultar contatosContatos (API v1): contatos, canais, campos, etiquetas, catálogos e status de importação e exportação
Gerenciar contatosContatos (API v1): cadastrar e editar contatos e canais, campos, etiquetas, ações em lote, importação e exportação
Excluir contatosContatos (API v1): excluir contatos e canais, inclusive em lote
Consultar agendaAgenda (API v1): eventos, participantes, lembretes, anexos, horários, disponibilidade e conflitos
Gerenciar agendaAgenda (API v1): criar, editar e excluir eventos; participantes, lembretes, anexos, horário de atendimento, reservas e links de agendamento
Configurar o CRMCRM (API v1): pipelines, etapas, tarefas padrão, campos, etiquetas, motivos de perda e gatilhos
Excluir negócios do CRMCRM (API v1): excluir negócios
Gerenciar webhooksWebhooks: assinaturas, eventos disponíveis, teste, entregas e rotação de segredo

Qualquer outro endpoint responde 403 para a chave, mesmo que o usuário API tenha acesso a ele pela plataforma.

Login: obter o access_token

Método anterior, que continua funcionando: login com o e-mail e a senha do usuário API. Para integrações novas, prefira a chave de API.

Para obter o token de autenticação, faça uma requisição POST para https://api.atys.pro/api/oauth/token com suas credenciais.

POST https://api.atys.pro/api/oauth/token Autenticar e obter access_token

Parâmetros do body (JSON)

ParâmetroTipoObrigatórioDescriçãoValor
emailstringSimE-mail do usuário APIjoao@exemplo.com
passwordstringSimSenha do usuário APIsenha123
grant_typestringSimTipo de grantpassword
device_namestringNãoweb (padrão) ou mobile; outro valor responde 422. Um novo login derruba só o token anterior com o mesmo device_name. Ver renovação.web
rememberbooleanNãoValidade do token: true (default) = 45 dias; false = 16 horas.true

Exemplos de código

JavaScript (Fetch API)
const response = await fetch('https://api.atys.pro/api/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    email: 'seu-email@exemplo.com',
    password: 'sua-senha-segura',
    grant_type: 'password'
  })
});

const data = await response.json();
console.log(data.access_token);

Resposta de sucesso (200 OK)

JSON Response
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "user_data": {
    "id": 123,
    "name": "João Silva",
    "email": "joao@exemplo.com",
    "company_id": 45,
    // ... demais campos do usuário
  }
}

Usando o access_token

Após obter o token, inclua-o no header Authorization de todas as requisições subsequentes:

Header Authorization
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

Exemplo de requisição autenticada

JavaScript (Fetch API)
const response = await fetch('https://api.atys.pro/api/contacts', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer SEU_ACCESS_TOKEN',
    'Accept': 'application/json'
  }
});

const data = await response.json();

Renovação do token

O access_token obtido com e-mail e senha vale por 45 dias (16 horas se o login for feito com "remember": false). Não existe um endpoint separado de renovação: renovar é fazer login de novo com POST /api/oauth/token. A plataforma invalida o token antes do prazo — e a próxima chamada recebe 401 — quando:

  • outro login é feito com o mesmo usuário e o mesmo device_name (o padrão é web);
  • as permissões ou o cargo do usuário API são alterados, ou o acesso dele a canais muda;
  • o usuário é bloqueado ou excluído;
  • a senha é redefinida pelo fluxo de recuperação ("esqueci minha senha");
  • o usuário tem horário de acesso configurado e a chamada acontece fora dele;
  • a empresa é bloqueada ou suspensa (com restrição de cobrança a resposta é 402, sem invalidar o token).

Como renovar automaticamente

  1. Guarde o token (cache, banco ou arquivo) e reaproveite-o em todas as chamadas — não faça login a cada requisição.
  2. Ao receber 401, faça login de novo, guarde o token novo e repita a chamada uma única vez. Se o segundo 401 vier, pare e avise: as credenciais estão erradas ou o usuário foi bloqueado.
  3. Uma integração por usuário API. Cada usuário tem no máximo um token por device_name (web ou mobile), então duas integrações que fazem login com o mesmo usuário se derrubam. Crie um usuário API para cada uma — ou, melhor, use uma chave de API por integração, que não depende de login.
  4. Opcional: renove antes de vencer — por exemplo, refaça o login a cada 40 dias. A resposta do login não informa a data de expiração; conte a partir do momento do login.

Exemplo: renovar o token ao receber 401

cURL (shell)
#!/usr/bin/env bash
# Guarda o token num arquivo; se a chamada voltar 401, faz login de novo e repete UMA vez.
TOKEN_FILE=/tmp/atys_token

login() {
  curl -s -X POST https://api.atys.pro/api/oauth/token \
    -H "Content-Type: application/json" -H "Accept: application/json" \
    -d "{\"email\":\"$ATYS_EMAIL\",\"password\":\"$ATYS_PASSWORD\",\"grant_type\":\"password\",\"device_name\":\"web\"}" \
    | sed -E 's/.*"access_token":"([^"]+)".*/\1/' > "$TOKEN_FILE"
}

atys() { # uso: atys GET /api/v1/crm/pipelines
  [ -s "$TOKEN_FILE" ] || login
  status=$(curl -s -o /tmp/atys_body -w "%{http_code}" -X "$1" "https://api.atys.pro$2" \
    -H "Authorization: Bearer $(cat "$TOKEN_FILE")" -H "Accept: application/json")
  if [ "$status" = "401" ]; then
    login
    curl -s -X "$1" "https://api.atys.pro$2" \
      -H "Authorization: Bearer $(cat "$TOKEN_FILE")" -H "Accept: application/json"
  else
    cat /tmp/atys_body
  fi
}

atys GET /api/v1/crm/pipelines
Com chave de API isso não é necessário. A chave não expira (a não ser que você defina uma data) e não é derrubada por logins — não há token para renovar.

Melhores práticas de segurança

Recomendado
  • Use HTTPS em todas as requisições.
  • Armazene tokens de forma segura (variáveis de ambiente).
  • Nunca exponha tokens em URLs ou logs.
  • Implemente rotação automática de tokens.
  • Use senhas fortes para usuários API.
  • Monitore uso anormal da API.
Evite
  • Nunca commite tokens no Git.
  • Não armazene tokens em cookies sem criptografia.
  • Não compartilhe tokens entre diferentes ambientes.
  • Evite hardcoding de credenciais.
  • Não use tokens em requisições HTTP (sem S).
  • Não ignore erros de autenticação.

Erros comuns de autenticação

401 Unauthorized — token inválido ou expirado

Causa: o token ou a chave de API está inválido, expirado, revogado ou não foi enviado.

Solução: com e-mail e senha, faça login novamente; com chave de API, gere uma nova chave.

{
  "success": false,
  "message": "Unauthenticated.",
  "error_code": "TOKEN_EXPIRED"
}
403 Chave de API sem permissão para o endpoint

Causa: a chave é válida, mas o endpoint não pertence às permissões dela.

Solução: gere uma chave com a permissão necessária em Configurações → Usuários de API.

{
  "message": "Esta chave de API não tem permissão para esta rota.",
  "scopes": ["crm:read"]
}
422 Campos do login ausentes ou inválidos

Causa: falta email, password ou grant_type, ou um valor não é aceito (por exemplo device_name diferente de web e mobile). errors diz qual campo.

Solução: corrija o corpo da requisição conforme a tabela de parâmetros.

{
  "message": "The password field is required.",
  "errors": {
    "password": ["The password field is required."]
  }
}
509 Login recusado (texto simples, não JSON)

Causa: o login com e-mail e senha responde 509 com uma mensagem em texto simples quando:

  • o e-mail ou a senha estão errados — E-mail ou senha inválidos. (a mesma mensagem para os dois casos);
  • o usuário está fora do horário de acesso configurado para ele — Seu acesso ao sistema está restrito neste horário…;
  • o usuário ou a empresa estão bloqueados, ou a empresa está suspensa por atraso de pagamento.

Solução: leia o corpo como texto, não como JSON. Confira as credenciais e, no caso do horário, libere o horário do usuário API em Configurações → Usuários API. Não repita o login em laço: as tentativas contam para o limite (429). A chave de API não depende do horário de acesso; usuário inativo ou empresa bloqueada, porém, também bloqueiam a chave.

HTTP/1.1 509
Content-Type: text/html; charset=utf-8

E-mail ou senha inválidos.
429 Too Many Requests

Causa: muitas tentativas de login em pouco tempo — até 10 por minuto por IP e 5 por minuto por e-mail.

Solução: espere os segundos do cabeçalho Retry-After antes de tentar de novo.

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "message": "Too Many Attempts."
}

Recebemos seu contato!

Um especialista da Atys vai falar com você em breve para agendar a demonstração.

Agendar demonstração

Em 20 minutos um especialista mostra a Atys na sua realidade.

BR +55