Como criar organizações usando a API do Zendesk: Um guia completo

Organizações são um dos recursos mais poderosos do Zendesk para gerenciar relacionamentos com clientes em escala. Elas permitem agrupar usuários, rotear tickets automaticamente e controlar a visibilidade das conversas de suporte. Embora você possa criar organizações manualmente através da interface do Zendesk, o verdadeiro poder vem da automação desse processo através da API do Zendesk.

Se você estiver migrando de outra plataforma, sincronizando com seu CRM ou construindo um fluxo de inscrição self-service, saber como criar organizações via API de Organizações do Zendesk é essencial para qualquer implementação séria. Este guia orienta você através de tudo o que você precisa saber, desde a autenticação até o tratamento de casos extremos. Se você está procurando automatizar o gerenciamento de organizações além das chamadas básicas da API, a eesel AI pode lidar com todo o fluxo de trabalho para você.

O que você precisa para começar

Antes de mergulhar no código, certifique-se de que você tem esses pré-requisitos em vigor:

• Uma conta do Zendesk com acesso de administrador. Apenas administradores e agentes com funções personalizadas podem criar organizações via API.
• Um token de API. Você precisará gerar isso a partir do seu Admin Center do Zendesk em Apps e integrações > APIs > Zendesk API.
• Seu subdomínio do Zendesk. Esta é a primeira parte do seu URL do Zendesk (por exemplo, suaempresa em suaempresa.zendesk.com).
• Uma ferramenta para fazer requisições HTTP. Mostraremos exemplos usando cURL, Python e JavaScript, então escolha o que funciona para sua stack.

A API do Zendesk usa autenticação básica com uma combinação de endereço de e-mail e token de API. Isso é mais seguro do que usar sua senha e permite que você controle o acesso granularmente.

Passo 1: Gere seu token de API do Zendesk

Seu token de API é a chave que permite que seu código se autentique com o Zendesk. Veja como criar um:

1. Faça login na sua conta do Zendesk como administrador
2. Clique no ícone Admin Center na barra lateral
3. Navegue até Apps e integrações > APIs > Zendesk API
4. Clique na aba Settings
5. Habilite Token Access se ainda não estiver ativado
6. Clique no ícone de mais (+) para adicionar um novo token
7. Dê a ele um nome descritivo como "API de Gerenciamento de Organização"
8. Copie o token imediatamente (o Zendesk só o mostra uma vez)

Armazene este token com segurança. Trate-o como uma senha. Qualquer pessoa com seu token pode acessar seus dados do Zendesk através da API.

Dica profissional: Crie tokens separados para diferentes integrações em vez de reutilizar um em todos os lugares. Isso torna mais fácil revogar o acesso, se necessário, sem quebrar outros sistemas.

Passo 2: Entenda o endpoint de organizações

A API de Organizações segue as convenções REST. Para criar uma organização, você fará uma requisição POST para:

https://{subdomínio}.zendesk.com/api/v2/organizations

O corpo da requisição é um objeto JSON contendo as propriedades da organização. Veja como é uma requisição de criação mínima:

{
  "organization": {
    "name": "Acme Corporation"
  }
}

O único campo obrigatório é name (nome), e ele deve ser exclusivo em toda a sua conta do Zendesk. Você não pode incluir caracteres de pipe (|) no nome, ou a requisição falhará.

Além do básico, você pode definir várias propriedades úteis:

A autenticação usa HTTP Basic Auth. Combine seu endereço de e-mail com /token: e seu token de API, então codifique o resultado em base64. O cabeçalho se parece com isto:

Authorization: Basic {credenciais_codificadas_em_base64}

Passo 3: Crie sua primeira organização

Vamos colocar isso em prática com exemplos de código funcional. Cada exemplo cria uma organização com campos comuns que você realmente usaria.

Usando cURL

SUBDOMAIN="suaempresa"
EMAIL="admin@suaempresa.com"
TOKEN="seu_token_api_aqui"

curl -X POST "https://${SUBDOMAIN}.zendesk.com/api/v2/organizations" \
  -H "Content-Type: application/json" \
  -u "${EMAIL}/token:${TOKEN}" \
  -d '{
    "organization": {
      "name": "Acme Corporation",
      "domain_names": ["acme.com", "acmecorp.com"],
      "external_id": "CRM-12345",
      "tags": ["enterprise", "priority"],
      "details": "Cliente Enterprise desde 2020"
    }
  }'

Usando Python

import requests
import base64

subdomain = "suaempresa"
email = "admin@suaempresa.com"
token = "seu_token_api_aqui"

credentials = base64.b64encode(
    f"{email}/token:{token}".encode()
).decode()

organization = {
    "organization": {
        "name": "Acme Corporation",
        "domain_names": ["acme.com", "acmecorp.com"],
        "external_id": "CRM-12345",
        "tags": ["enterprise", "priority"],
        "details": "Cliente Enterprise desde 2020"
    }
}

response = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/organizations",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Basic {credentials}"
    },
    json=organization
)

if response.status_code == 201:
    created_org = response.json()["organization"]
    print(f"ID da organização criada: {created_org['id']}")
    print(f"Nome: {created_org['name']}")
else:
    print(f"Erro: {response.status_code}")
    print(response.json())

Usando JavaScript/Node.js

const axios = require('axios');

// Configuration
const config = {
  subdomain: 'suaempresa',
  email: 'admin@suaempresa.com',
  token: 'seu_token_api_aqui'
};

// Organization data
const organization = {
  organization: {
    name: 'Acme Corporation',
    domain_names: ['acme.com', 'acmecorp.com'],
    external_id: 'CRM-12345',
    tags: ['enterprise', 'priority'],
    details: 'Cliente Enterprise desde 2020'
  }
};

// Make the request
axios.post(
  `https://${config.subdomain}.zendesk.com/api/v2/organizations`,
  organization,
  {
    headers: {
      'Content-Type': 'application/json'
    },
    auth: {
      username: `${config.email}/token`,
      password: config.token
    }
  }
)
.then(response => {
  const org = response.data.organization;
  console.log(`ID da organização criada: ${org.id}`);
  console.log(`Nome: ${org.name}`);
})
.catch(error => {
  console.error('Erro:', error.response?.data || error.message);
});

Uma criação bem-sucedida retorna HTTP 201 com o objeto de organização completo, incluindo o campo id gerado automaticamente que você precisará para futuras atualizações.

Passo 4: Trabalhe com campos de organização personalizados

A maioria das implementações do Zendesk usa campos personalizados para armazenar dados adicionais da organização, como níveis de conta, regiões ou IDs de CRM. Veja como trabalhar com eles via API.

Primeiro, você precisa saber quais campos personalizados existem. Você pode encontrá-los no seu Admin Center do Zendesk em Objetos e regras > Organizações > Campos, ou recuperá-los via API:

curl "https://{subdomínio}.zendesk.com/api/v2/organization_fields" \
  -u "{email}/token:{token}"

Cada campo personalizado tem uma chave exclusiva (como nível_da_conta ou região). Quando você estiver criando ou atualizando uma organização, inclua-os no objeto organization_fields:

{
  "organization": {
    "name": "Acme Corporation",
    "organization_fields": {
      "account_tier": "enterprise",
      "region": "north_america",
      "crm_id": "CRM-12345",
      "contract_value": 50000
    }
  }
}

O formato do valor depende do tipo de campo:

• Campos de texto: Valores de string
• Campos de dropdown: O valor da tag de opção (não o nome de exibição)
• Campos numéricos: Números (não strings)
• Campos de data: Formato ISO 8601 (2024-01-15)
• Campos de checkbox: Booleano (true ou false)

Caso de uso comum: Sincronizando dados da organização do seu CRM. Configure um webhook ou job agendado que envia atualizações para o Zendesk sempre que os detalhes da conta mudarem em seu sistema primário. Isso mantém os agentes de suporte trabalhando com informações atuais.

Passo 5: Lide com erros e casos extremos

O código de produção precisa lidar com as coisas dando errado. Aqui estão os erros mais comuns que você encontrará:

401 Não Autorizado

Isso significa que suas credenciais são inválidas. Verifique se:

• Seu token de API está correto e não foi revogado
• Seu endereço de e-mail corresponde à conta que possui o token
• Você está usando o formato correto: email/token:token (observe a parte /token:)

422 Entidade Não Processável

A requisição foi entendida, mas não pôde ser processada. Causas comuns:

• Nome duplicado: Os nomes das organizações devem ser exclusivos. Verifique as organizações existentes primeiro.
• Caracteres inválidos: Os nomes não podem conter caracteres de pipe (|).
• Campos obrigatórios ausentes: O campo name é obrigatório.
• Valores de campos personalizados inválidos: Certifique-se de que os valores de dropdown correspondam exatamente às opções definidas.

429 Muitas Requisições

Você atingiu o limite de taxa do Zendesk. A API de Organizações permite 700 requisições por minuto. Se você precisar criar organizações em massa, adicione atrasos entre as requisições:

import time

for org_data in organizations:
    response = requests.post(url, json=org_data, auth=auth)
    if response.status_code == 429:
        # Espere e tente novamente
        time.sleep(1)
        response = requests.post(url, json=org_data, auth=auth)
    # Processar resposta...
    time.sleep(0.1)  # Seja gentil com a API

Melhor prática: Ao construir integrações, sempre verifique os códigos de status de resposta e implemente backoff exponencial para erros 429. Registre as requisições com falha para que você possa tentar novamente mais tarde.

Automatizando o gerenciamento de organizações com eesel AI

Gerenciar organizações manualmente não escala. À medida que sua base de clientes cresce, manter as organizações do Zendesk sincronizadas com seu CRM, sistema de faturamento e outras ferramentas se torna um fardo operacional significativo.

É aqui que podemos ajudar. Na eesel AI, construímos um colega de equipe de IA que se integra diretamente com o Zendesk e pode automatizar fluxos de trabalho baseados em organização.

Veja como nossos clientes usam a eesel AI com organizações:

• Atribuição automática de organização: Quando um ticket chega, nossa IA pode procurar o solicitante em seu CRM, criar ou atualizar sua organização no Zendesk e rotear o ticket para a equipe certa com base nas propriedades da organização.
• Escalonamento inteligente: Podemos ler campos personalizados da organização (como nível de conta ou nível de SLA) e escalar tickets de clientes enterprise automaticamente.
• Respostas com reconhecimento da organização: Nossa IA rascunha respostas que referenciam detalhes específicos da organização, como termos de contrato, gerentes de conta dedicados ou problemas anteriores.

Ao contrário da construção de integrações de API personalizadas, a eesel AI aprende com seus dados e fluxos de trabalho existentes. Você descreve o que deseja em português claro (como "Se o nível da organização for enterprise, coloque o gerente de conta em cópia"), e nossa IA lida com as chamadas de API, tratamento de erros e lógica.

Você pode começar com nosso AI Copilot elaborando respostas para revisão do agente e, em seguida, subir para automação total à medida que você constrói confiança. A maioria das equipes vê o retorno em dois meses.

Comece a construir com a API de organizações do Zendesk

Agora você tem tudo o que precisa para criar e gerenciar organizações programaticamente no Zendesk. Vamos recapitular os principais passos:

1. Gere um token de API do seu Admin Center do Zendesk
2. Estruture sua requisição POST para /api/v2/organizations com os dados da organização
3. Lide com a resposta JSON para obter o ID da organização criada
4. Use campos personalizados para armazenar dados específicos da organização
5. Implemente o tratamento de erros adequado para o código de produção

A API de Organizações é apenas o começo. Você também pode atualizar organizações, mesclar duplicatas, gerenciar associações de organização e configurar regras de negócios baseadas em organização.

Para casos de uso avançados, como importações em massa ou sincronização bidirecional com outros sistemas, considere se uma solução alimentada por IA pode economizar tempo para sua equipe. Experimente a eesel AI gratuitamente por 7 dias e veja como a automação pode transformar suas operações de suporte.