Como criar usuários com a API Zendesk: Um guia completo

Gerenciar contas de usuário em escala é uma daquelas tarefas que começa simples e fica complicada rapidamente. Seja integrando clientes de uma nova aquisição, sincronizando usuários do seu banco de dados interno ou construindo um fluxo de registro de autoatendimento, você eventualmente precisará criar usuários Zendesk programaticamente.

A API de Usuários Zendesk oferece as ferramentas para fazer isso. É uma API RESTful que lida com tudo, desde a criação de usuários individuais até a importação em massa de milhares de uma só vez. Este guia orienta você pelas etapas práticas para colocá-la em funcionamento, com exemplos de código funcional que você pode adaptar à sua stack.

Se você está procurando automatizar mais do que apenas a criação de usuários, ferramentas como eesel AI podem lidar com todo o espectro da automação de suporte, desde o roteamento de tickets até respostas alimentadas por IA.

O que você vai precisar

Antes de começar a fazer chamadas de API, certifique-se de que você tem:

• Uma conta Zendesk com acesso de administrador apenas administradores podem criar tokens de API e gerenciar usuários via API
• Um token de API ou credenciais OAuth vamos abordar como gerar estes abaixo
• Familiaridade básica com APIs REST você deve saber o que é uma requisição POST
• Um ambiente de desenvolvimento cURL, Python ou Node.js funcionarão bem

Passo 1: configurar a autenticação da API

O Zendesk suporta dois métodos principais de autenticação para acesso à API: tokens de API e OAuth. Para a maioria das integrações servidor a servidor, os tokens de API são mais simples de implementar.

Gerando um token de API

1. Faça login na sua conta Zendesk como administrador
2. Navegue até o Admin Center (clique no ícone de engrenagem e, em seguida, "Ir para o Admin Center")
3. Vá para Apps e integrações → APIs → Zendesk API
4. Clique na aba Configurações e certifique-se de que o Acesso ao token está habilitado
5. Mude para a aba Tokens de API e clique em Adicionar token de API
6. Insira um nome descritivo como "Integração de Sincronização de Usuário"
7. Copie o token imediatamente o Zendesk só o exibe uma vez

Formatando seu cabeçalho de autenticação

O Zendesk usa autenticação Basic com seu token de API. O formato é:

• Nome de usuário: Seu endereço de e-mail do Zendesk com /token anexado (por exemplo, voce@empresa.com/token)
• Senha: O próprio token de API

Codifique as credenciais em Base64 e inclua-as no cabeçalho de Autorização:

curl https://seu-subdominio.zendesk.com/api/v2/users.json \
  -u voce@empresa.com/token:seu_token_api_aqui

Ou em Python:

import requests
from requests.auth import HTTPBasicAuth

subdomain = "seu-subdominio"
email = "voce@empresa.com"
token = "seu_token_api_aqui"

auth = HTTPBasicAuth(f"{email}/token", token)
headers = {"Content-Type": "application/json"}

url = f"https://{subdomain}.zendesk.com/api/v2/users.json"
response = requests.get(url, auth=auth, headers=headers)
print(response.json())

Melhores práticas de segurança

• Armazene tokens de API em variáveis de ambiente, nunca no seu código
• Rotacione os tokens periodicamente exclua os antigos e gere novos
• Use nomes de token descritivos para que você saiba para que cada um serve
• Exclua os tokens quando as integrações forem desativadas
• Considere criar um usuário de serviço dedicado com permissões limitadas em vez de usar o token de um administrador

Passo 2: criar um único usuário

A maneira mais simples de criar um usuário é através do endpoint POST /api/v2/users. No mínimo, você precisa fornecer um nome.

Parâmetros obrigatórios e opcionais

Entendendo as funções de usuário

O Zendesk tem três funções internas:

• end-user: Clientes que enviam tickets (padrão se nenhuma função for especificada)
• agent: Equipe de suporte que lida com tickets
• admin: Acesso administrativo completo

Para planos Enterprise, você também pode atribuir funções de agente personalizadas usando o parâmetro custom_role_id. Observe que as funções personalizadas devem ser criadas primeiro no Admin Center você não pode criá-las via API.

Exemplos de código

cURL:

curl https://seu-subdominio.zendesk.com/api/v2/users.json \
  -d '{"user": {"name": "Jane Smith", "email": "jane@example.com", "role": "end-user"}}' \
  -H "Content-Type: application/json" \
  -X POST \
  -u voce@empresa.com/token:seu_token_api

Python:

import requests
import json
from requests.auth import HTTPBasicAuth

subdomain = "seu-subdominio"
auth = HTTPBasicAuth("voce@empresa.com/token", "seu_token_api")
headers = {"Content-Type": "application/json"}

user_data = {
    "user": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "role": "end-user",
        "external_id": "user_12345"
    }
}

response = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/users.json",
    auth=auth,
    headers=headers,
    json=user_data
)

if response.status_code == 201:
    user = response.json()["user"]
    print(f"Usuário criado {user['id']}: {user['name']}")
else:
    print(f"Erro: {response.status_code} - {response.text}")

JavaScript (Node.js com axios):

const axios = require('axios');

const subdomain = 'seu-subdominio';
const email = 'voce@empresa.com';
const token = 'seu_token_api';

const userData = {
  user: {
    name: 'Jane Smith',
    email: 'jane@example.com',
    role: 'end-user',
    external_id: 'user_12345'
  }
};

axios.post(
  `https://${subdomain}.zendesk.com/api/v2/users.json`,
  userData,
  {
    auth: {
      username: `${email}/token`,
      password: token
    },
    headers: {
      'Content-Type': 'application/json'
    }
  }
)
.then(response => {
  const user = response.data.user;
  console.log(`Usuário criado ${user.id}: ${user.name}`);
})
.catch(error => {
  console.error('Erro:', error.response?.data || error.message);
});

Interpretando a resposta

Uma criação bem-sucedida retorna HTTP 201 Created com o objeto do usuário:

{
  "user": {
    "id": 9873843,
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "end-user",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "active": true,
    "verified": false
  }
}

Passo 3: criar ou atualizar usuários (upsert)

O que acontece se você tentar criar um usuário que já existe? O endpoint de criação padrão retorna um erro 422. Para cenários de sincronização em que você está importando usuários regularmente de um sistema externo, use o endpoint create_or_update em vez disso.

Quando usar create_or_update

Use POST /api/v2/users/create_or_update quando:

• Você está sincronizando usuários de um banco de dados externo
• Você quer operações idempotentes (a mesma solicitação produz o mesmo resultado)
• Você não quer verificar se um usuário existe antes de criar

Como a correspondência funciona

O Zendesk corresponde usuários por:

1. ID externo se fornecido, isso tem precedência
2. Endereço de e-mail se nenhuma correspondência de ID externo for encontrada

Códigos de resposta

Exemplo prático: sincronizando de um sistema externo

import requests
from requests.auth import HTTPBasicAuth

auth = HTTPBasicAuth("voce@empresa.com/token", "seu_token_api")
headers = {"Content-Type": "application/json"}

external_users = [
    {"name": "Jane Smith", "email": "jane@example.com", "external_id": "usr_001"},
    {"name": "John Doe", "email": "john@example.com", "external_id": "usr_002"}
]

for external_user in external_users:
    user_data = {"user": external_user}

    response = requests.post(
        "https://seu-subdominio.zendesk.com/api/v2/users/create_or_update.json",
        auth=auth,
        headers=headers,
        json=user_data
    )

    if response.status_code == 201:
        print(f"Criado: {external_user['email']}")
    elif response.status_code == 200:
        print(f"Atualizado: {external_user['email']}")
    else:
        print(f"Falhou: {external_user['email']} - {response.text}")

Passo 4: criar vários usuários em massa

Se você precisa criar centenas ou milhares de usuários, chamadas de API individuais são ineficientes. O Zendesk fornece um endpoint em massa que aceita até 100 usuários por solicitação.

Endpoint e limitações

• Endpoint: POST /api/v2/users/create_many
• Limite: 100 usuários por solicitação
• Habilitação: As importações em massa devem ser habilitadas pelo suporte do Zendesk (entre em contato com eles se você receber erros 403)

Entendendo as respostas job_status

Ao contrário da criação de usuário único, as operações em massa são assíncronas. A API retorna imediatamente com um objeto job_status, e a criação real acontece em segundo plano:

{
  "job_status": {
    "id": "82de0b044094f0c67893ac9fe64f1a99",
    "status": "queued",
    "total": 50,
    "progress": 0,
    "url": "https://seu-subdominio.zendesk.com/api/v2/job_statuses/82de0b044094f0c67893ac9fe64f1a99"
  }
}

Consulte o URL do status do trabalho para acompanhar o progresso:

def check_job_status(job_url):
    response = requests.get(job_url, auth=auth)
    job = response.json()["job_status"]

    print(f"Status: {job['status']}, Progresso: {job['progress']}/{job['total']}")

    if job["status"] == "completed":
        for result in job.get("results", []):
            print(f"  {result['action']}: Usuário {result['id']} - {result['status']}")

    return job["status"]

import time
while check_job_status(job_url) != "completed":
    time.sleep(5)

Quando a criação em massa faz sentido

Exemplo de criação em massa

users_to_create = [
    {"name": "Usuário Um", "email": "usuario1@example.com", "role": "end-user"},
    {"name": "Usuário Dois", "email": "usuario2@example.com", "role": "end-user"},
    # ... até 100 usuários
]

response = requests.post(
    "https://seu-subdominio.zendesk.com/api/v2/users/create_many.json",
    auth=auth,
    headers=headers,
    json={"users": users_to_create}
)

if response.status_code == 200:
    job = response.json()["job_status"]
    print(f"Trabalho enfileirado: {job['id']}")
else:
    print(f"Erro: {response.status_code} - {response.text}")

Erros comuns e solução de problemas

Mesmo com o código certo, as coisas podem dar errado. Veja como lidar com os problemas mais comuns:

401 Não autorizado

Suas credenciais de autenticação são inválidas. Verifique:

• O endereço de e-mail está correto?
• Você anexou /token ao nome de usuário?
• O token de API ainda está ativo (não foi excluído)?
• Você está usando o subdomínio correto?

403 Proibido

Você não tem permissão para esta ação. Causas comuns:

• O token de API pertence a um agente, não a um administrador
• As importações em massa não estão habilitadas na sua conta (entre em contato com o suporte do Zendesk)
• Você está tentando criar um usuário administrador sem permissões suficientes

422 Entidade Não Processável

Os dados da solicitação são inválidos. Verifique:

• O campo name está presente? (é obrigatório)
• O formato do e-mail é válido?
• A função é uma de: end-user, agent, admin?
• O organization_id existe?

429 Muitas Solicitações

Você atingiu o limite de taxa do Zendesk. A API retorna um cabeçalho Retry-After indicando quantos segundos esperar. Implemente backoff exponencial no seu código:

import time

def api_call_with_retry(url, auth, headers, json_data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, auth=auth, headers=headers, json=json_data)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Taxa limitada. Esperando {retry_after} segundos...")
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Número máximo de tentativas excedido")

Erros de e-mail duplicado

Se você receber um erro 422 mencionando "O e-mail já foi usado", então:

• Use o endpoint create_or_update em vez disso
• Verifique se o usuário existe primeiro com GET /api/v2/users/search?query=email@example.com

Melhores práticas para automação de gerenciamento de usuários

Depois de trabalhar com a API de Usuários Zendesk, aqui estão padrões que funcionam consistentemente bem:

Use external_id para idempotência

Sempre inclua um external_id que mapeie para o seu ID de usuário interno. Isso torna as operações idempotentes e simplifica a sincronização:

user_data = {
    "user": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "external_id": f"banco_de_dados_interno_{internal_user_id}"
    }
}

Defina o status verificado para ignorar a verificação de e-mail

Se você estiver criando usuários de uma fonte confiável (como seu próprio banco de dados), defina verified: true para impedir que o Zendesk envie e-mails de verificação:

user_data = {
    "user": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "verified": True  # Ignorar e-mail de verificação
    }
}

Lide com funções personalizadas corretamente

Funções personalizadas são um recurso Enterprise. Para atribuí-las:

1. Crie a função personalizada primeiro no Admin Center
2. Obtenha o custom_role_id do URL ou API da função
3. Defina tanto role: "agent" quanto custom_role_id: 12345

Implemente o tratamento de erros adequado

Não presuma que as chamadas de API sejam bem-sucedidas. Envolva as chamadas em blocos try/except e lide com casos de erro específicos:

try:
    response = requests.post(url, auth=auth, headers=headers, json=data)
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    if response.status_code == 422:
        errors = response.json().get("details", {})
        print(f"Erro de validação: {errors}")
    else:
        raise

Armazene as credenciais com segurança

Nunca codifique tokens de API. Use variáveis de ambiente:

import os

ZENDESK_SUBDOMAIN = os.environ.get("ZENDESK_SUBDOMAIN")
ZENDESK_EMAIL = os.environ.get("ZENDESK_EMAIL")
ZENDESK_TOKEN = os.environ.get("ZENDESK_TOKEN")

Considere necessidades de automação mais amplas

Se você está automatizando a criação de usuários, provavelmente está gerenciando uma operação de suporte crescente. Embora a API Zendesk lide com o gerenciamento de usuários, você também pode precisar automatizar o tratamento, roteamento e respostas de tickets. eesel AI integra-se ao Zendesk para lidar com esses fluxos de trabalho automaticamente, desde classificar e marcar tickets até redigir respostas alimentadas por IA.

Comece a automatizar seus fluxos de trabalho Zendesk

Você agora tem a base para criar usuários Zendesk programaticamente. Seja construindo uma integração de sincronização de usuário, automatizando a integração ou gerenciando uma grande base de clientes, a API de Usuários oferece o controle que você precisa.

Os padrões neste guia autenticação, criação única, upserts e operações em massa cobrem a maioria dos cenários do mundo real. Comece com o endpoint de usuário único para validar sua configuração e, em seguida, passe para operações em massa à medida que sua escala aumenta.

Se você está procurando automatizar além da criação de usuários, considere como a IA pode otimizar todo o seu fluxo de trabalho de suporte. eesel AI integra-se ao Zendesk para lidar com a triagem de tickets, redação de respostas e roteamento inteligente reduzindo o trabalho manual e melhorando os tempos de resposta. Você pode explorar nosso agente de IA para atendimento ao cliente para ver como a automação pode se estender por toda a sua stack de suporte.