zendesk-custom-objects-create-type

{
  "title": "Como criar um tipo de objeto personalizado no Zendesk: Um guia completo",
  "slug": "zendesk-custom-objects-create-type",
  "locale": "pt",
  "date": "2026-02-27",
  "updated": "2026-02-27",
  "template": "default",
  "excerpt": "Um guia passo a passo para criar tipos de objetos personalizados no Zendesk, abrangendo os métodos de API e Admin Center com exemplos práticos.",
  "categories": [
    "Zendesk",
    "Guides"
  ],
  "tags": [
    "Zendesk",
    "Custom Objects",
    "API",
    "Admin Center",
    "Tutorial"
  ],
  "readTime": 11,
  "author": 16,
  "reviewer": 14,
  "seo": {
    "title": "Como criar um tipo de objeto personalizado no Zendesk: Um guia completo",
    "description": "Um guia passo a passo para criar tipos de objetos personalizados no Zendesk, abrangendo os métodos de API e Admin Center com exemplos práticos.",
    "image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-52c48c7c-a1bf-48cb-bcc2-360921f95f3b"
  },
  "coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-52c48c7c-a1bf-48cb-bcc2-360921f95f3b",
  "coverImageAlt": "Imagem do banner para Como criar um tipo de objeto personalizado no Zendesk: Um guia completo",
  "coverImageWidth": 1920,
  "coverImageHeight": 1080,
  "faqs": {
    "heading": "Perguntas Frequentes",
    "type": "blog",
    "answerType": "html",
    "faqs": [
      {
        "question": "Posso alterar uma chave de objeto personalizado depois de criá-la?",
        "answer": "Não, a chave do objeto é permanente depois de criada. Se você precisar de uma chave diferente, terá que excluir o objeto e criar um novo. Isso também exclui todos os registros existentes, então planeje sua nomenclatura cuidadosamente antecipadamente."
      },
      {
        "question": "Como crio um tipo de objeto personalizado do Zendesk se eu não for um administrador?",
        "answer": "Você não pode. Apenas os administradores têm permissão para criar e modificar tipos de objetos personalizados. Se você precisar de objetos personalizados para sua equipe, solicite que um administrador os crie para você ou peça acesso de administrador."
      },
      {
        "question": "Qual é a diferença entre a nova API de objetos personalizados e a API Sunshine legada?",
        "answer": "A nova API usa endpoints como /api/v2/custom_objects e é a abordagem recomendada atualmente. A API Sunshine legada usa /api/sunshine/objects/types e tem uma estrutura de dados diferente baseada em JSON Schema. Se você estiver começando do zero, use a nova API."
      },
      {
        "question": "Posso usar objetos personalizados em gatilhos e automações do Zendesk?",
        "answer": "Sim, mas com limitações. Você pode usar campos de relacionamento de pesquisa em gatilhos de ticket para verificar se um ticket tem um registro de objeto personalizado relacionado. Você também pode usar espaços reservados para incluir dados de objetos personalizados em ações de gatilho e notificações por e-mail."
      },
      {
        "question": "Como importo dados existentes para objetos personalizados?",
        "answer": "Use o Importador de Dados no Admin Center. Prepare um arquivo CSV com colunas correspondentes às suas chaves de campo, inclua uma coluna external_id para correspondência e carregue através de Admin Center > Objetos e regras > Importador de dados."
      },
      {
        "question": "O que acontece se eu excluir um tipo de objeto personalizado?",
        "answer": "Excluir um tipo de objeto remove permanentemente todos os registros desse tipo. Esta ação não pode ser desfeita. Certifique-se de exportar todos os dados que você precisa manter antes de excluir."
      }
    ],
    "supportLink": null
  }
}
---

Objetos padrão do Zendesk, como tickets, usuários e organizações, cobrem a maioria das necessidades de suporte. Mas o que acontece quando sua empresa tem dados exclusivos que não se encaixam nessas caixas predefinidas? Os [objetos personalizados do Zendesk](https://developer.zendesk.com/documentation/custom-data/v2/getting-started-with-custom-objects/) oferecem a flexibilidade de modelar seus dados exatamente como você precisa.

Objetos personalizados permitem que você estenda o modelo de dados do Zendesk para armazenar informações específicas do seu negócio. Esteja você rastreando licenças de software, garantias de produtos ou detalhes de assinatura, os objetos personalizados oferecem a flexibilidade de modelar seus dados exatamente como você precisa.

Neste guia, você aprenderá como criar um tipo de objeto personalizado no Zendesk usando dois métodos: a API REST para configurações automatizadas e o Admin Center para uma abordagem de apontar e clicar. Também veremos como ferramentas como o [eesel AI](https://www.eesel.ai/integrations/zendesk) podem trabalhar em conjunto com seus dados personalizados para automatizar os fluxos de trabalho de suporte.

## Criando um tipo de objeto personalizado via API

O método da API oferece controle preciso e permite automatizar a criação de objetos em várias instâncias do Zendesk. Veja como criar um tipo de objeto personalizado do Zendesk programaticamente.

### Passo 1: Habilite objetos personalizados em sua conta

Antes de usar a API, um administrador precisa ativar o recurso:

1. Navegue até **Admin Center** > **Objetos e regras** > **Objetos personalizados**
2. Clique em **Começar** para habilitar o recurso
3. Se você usou objetos personalizados legados anteriormente, verá um banner para experimentar a nova experiência

### Passo 2: Crie o objeto personalizado

Uma vez habilitado, use o [endpoint de criação de objeto personalizado](https://developer.zendesk.com/api-reference/custom-data/custom-objects/custom_objects/#create-custom-object) para definir seu objeto:

**Endpoint:** `POST /api/v2/custom_objects`

**Parâmetros obrigatórios:**
- `key`: Um identificador exclusivo para seu objeto (não pode ser alterado posteriormente)
- `title`: O nome de exibição singular (por exemplo, "Licença de Software")
- `title_pluralized`: O nome de exibição plural (por exemplo, "Licenças de Software")

Aqui está um exemplo cURL completo:

```bash
curl --request POST https://{subdomain}.zendesk.com/api/v2/custom_objects \
  --header "Content-Type: application/json" \
  -u {email_address}/token:{api_token} \
  --data-raw '{
    "custom_object": {
      "key": "software_license",
      "title": "Software License",
      "title_pluralized": "Software Licenses"
    }
  }'

Resposta esperada (201 Created):

{
  "custom_object": {
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/software_license.json",
    "key": "software_license",
    "created_by_user_id": "15590417147927",
    "updated_by_user_id": "15590417147927",
    "created_at": "2023-09-12T16:28:17Z",
    "updated_at": "2023-09-12T16:28:17Z",
    "title": "Software License",
    "raw_title": "Software License",
    "title_pluralized": "Software Licenses",
    "raw_title_pluralized": "Software Licenses",
    "description": "",
    "raw_description": ""
  }
}

A key que você escolher é permanente, então escolha algo descritivo que seja consistente com suas convenções de nomenclatura.

Passo 3: Adicione campos personalizados para definir o esquema

Um objeto sem campos é apenas um contêiner vazio. Use o endpoint de criação de campo de objeto personalizado para adicionar propriedades:

Endpoint: POST /api/v2/custom_objects/{custom_object_key}/fields

Tipos de campo disponíveis:

• text: Texto de linha única ou múltipla
• dropdown: Opções predefinidas com tags
• checkbox: Booleano verdadeiro/falso
• lookup: Relacionamentos com tickets, usuários, organizações ou outros objetos personalizados
• date: Valores de data
• number: Valores inteiros
• decimal: Números decimais
• regexp: Texto correspondente a um padrão de expressão regular

Exemplo: Adicionando um campo suspenso para o status da licença

curl --request POST \
  https://{subdomain}.zendesk.com/api/v2/custom_objects/software_license/fields \
  --header "Content-Type: application/json" \
  -u {email_address}/token:{api_token} \
  --data-raw '{
    "custom_object_field": {
      "key": "status",
      "title": "License Status",
      "type": "dropdown",
      "custom_field_options": [
        {"name": "Active", "raw_name": "Active", "value": "active"},
        {"name": "Expired", "raw_name": "Expired", "value": "expired"},
        {"name": "Pending", "raw_name": "Pending", "value": "pending"}
      ]
    }
  }'

Exemplo: Adicionando um relacionamento de pesquisa para vincular licenças a usuários

curl --request POST \
  https://{subdomain}.zendesk.com/api/v2/custom_objects/software_license/fields \
  --header "Content-Type: application/json" \
  -u {email_address}/token:{api_token} \
  --data-raw '{
    "custom_object_field": {
      "key": "assigned_user",
      "title": "Assigned User",
      "type": "lookup",
      "relationship_target_type": "zen:user"
    }
  }'

Os agentes veem os campos na ordem em que você os cria. Se você precisar reordená-los mais tarde, use o endpoint de reordenação de campos de objeto personalizado.

---

Criando um tipo de objeto personalizado no Admin Center

Se você prefere uma interface visual, o Admin Center oferece uma maneira direta de criar objetos personalizados sem escrever nenhum código.

Passo 1: Acesse a página de objetos personalizados

1. No Admin Center, clique em Objetos e regras na barra lateral
2. Selecione Objetos personalizados > Objetos
3. Clique em Criar objeto

Passo 2: Configure as propriedades do objeto

Preencha as informações básicas do objeto:

• Chave do objeto: Um identificador exclusivo (por exemplo, software_license). Isso não pode ser alterado posteriormente.
• Nome singular: Como o objeto aparece na interface (por exemplo, "Licença de Software")
• Nome plural: A forma plural mostrada nas listas (por exemplo, "Licenças de Software")
• Descrição: Contexto opcional para outros administradores
• Visibilidade: Escolha se os agentes podem visualizar este tipo de objeto na página de registros de Objetos personalizados

Clique em Salvar para criar o objeto.

Passo 3: Defina campos personalizados

Após salvar, você verá uma aba Campos:

1. Clique em Adicionar campo
2. Selecione um tipo de campo no menu suspenso (texto, número, data, suspenso, caixa de seleção, pesquisa)
3. Insira uma chave de campo e um título de exibição
4. Configure opções específicas do tipo (por exemplo, valores suspensos, alvo de pesquisa)
5. Defina se o campo é obrigatório
6. Clique em Salvar

Repita este processo para cada campo que você precisa. O campo padrão name está incluído por padrão, então você não precisa criá-lo separadamente.

---

Entendendo campos e relacionamentos de objetos personalizados

Os campos definem quais dados seus objetos personalizados podem conter. Escolher os tipos de campo certos torna seus dados mais úteis e fáceis de trabalhar.

Campos padrão vs personalizados

Cada objeto personalizado inclui automaticamente um campo name padrão. Isso serve como o identificador principal para os registros. Você pode personalizar seu título (por exemplo, alterar "Nome" para "Chave de Licença"), mas não pode removê-lo.

Os campos personalizados são onde você define sua estrutura de dados específica. Você pode adicionar até 100 campos personalizados por objeto, dando-lhe muita flexibilidade para modelos de dados complexos.

Tipos de campo explicados

• Campos de texto: Armazenam texto de forma livre. Use linha única para entradas curtas (como números de série) e multi-linha para descrições mais longas.
• Campos suspensos: Restringem a entrada a opções predefinidas. Útil para campos de status, categorias ou qualquer dado com um conjunto fixo de valores.
• Campos de caixa de seleção: Valores simples verdadeiro/falso. Bom para sinalizadores como "requer aprovação" ou "está ativo".
• Campos de data: Armazenam datas do calendário. Útil para datas de validade, datas de compra ou datas de renovação.
• Campos de número/decimal: Armazenam valores numéricos. Use para quantidades, valores ou quaisquer valores calculados.
• Campos de relacionamento de pesquisa: O tipo de campo mais poderoso. Eles criam conexões entre seu objeto personalizado e outros objetos do Zendesk.

Relacionamentos de pesquisa

Os campos de pesquisa permitem que você vincule registros de objetos personalizados a:

• Tickets: Associe uma licença, produto ou ativo a um ticket de suporte específico
• Usuários: Conecte registros aos clientes que os possuem
• Organizações: Vincule dados a contas de empresas
• Outros objetos personalizados: Construa relacionamentos complexos (por exemplo, licenças vinculadas a produtos)

Quando você adiciona um campo de pesquisa a um formulário de ticket, os agentes podem pesquisar e selecionar registros de objetos personalizados relacionados diretamente enquanto trabalham nos tickets. Isso traz seus dados personalizados para o fluxo de trabalho de suporte.

Limites de plano para ter em mente

Limite	Suite Team/Growth	Enterprise/Professional+
Objetos personalizados por conta	3-5	30-50
Campos por objeto	100	100
Relacionamentos de pesquisa por objeto	5	10

Esses limites são limites rígidos, então planeje a estrutura do seu objeto de acordo. Se você estiver atingindo os limites com frequência, pode ser necessário consolidar objetos ou atualizar seu plano.

---

Criando e gerenciando registros de objetos

Depois de definir seu tipo de objeto e campos, você pode começar a criar registros reais.

Criando registros via API

Use o endpoint de criação de registro de objeto personalizado:

Endpoint: POST /api/v2/custom_objects/{custom_object_key}/records

curl --request POST \
  https://{subdomain}.zendesk.com/api/v2/custom_objects/software_license/records \
  --header "Content-Type: application/json" \
  -u {email_address}/token:{api_token} \
  --data-raw '{
    "custom_object_record": {
      "name": "LICENSE-2024-001",
      "custom_fields": {
        "status": "active",
        "assigned_user": "123456789"
      }
    }
  }'

Criando registros no Admin Center

1. Vá para Admin Center > Objetos e regras > Objetos personalizados > Registros
2. Selecione seu tipo de objeto no menu suspenso
3. Clique em Adicionar registro
4. Preencha os valores dos campos
5. Clique em Salvar

Importação em massa com CSV

Para grandes conjuntos de dados, use o Importador de Dados no Admin Center:

1. Prepare um CSV com colunas correspondentes às suas chaves de campo
2. Inclua uma coluna external_id para corresponder aos registros existentes
3. Carregue via Admin Center > Objetos e regras > Importador de dados
4. Mapeie as colunas CSV para os campos do objeto
5. Revise e confirme a importação

O Importador de Dados pode criar novos registros e atualizar os existentes com base no campo external_id.

Usando espaços reservados em macros e gatilhos

Os dados de objetos personalizados se tornam poderosos quando você os usa em seus fluxos de trabalho de suporte. O Zendesk suporta espaços reservados que permitem referenciar valores de objetos personalizados em macros, gatilhos e automações.

Para um campo de pesquisa com ID 123456789 em um ticket:

• {{ticket.ticket_field_123456789.name}} retorna o nome do registro vinculado
• {{ticket.ticket_field_123456789.custom_fields.status}} retorna o valor do campo de status
• {{ticket.ticket_field_123456789.custom_fields.status.title}} retorna o valor de exibição para campos suspensos

Isso permite que você crie macros dinâmicas que extraem dados relevantes do cliente automaticamente.

---

Limites de plano e considerações importantes

Antes de construir sua estrutura de objeto personalizado, entenda as restrições:

Plano	Limite de Objeto Personalizado
Suite Team	3
Suite Growth	5
Support Enterprise / Suite Professional	30
Suite Enterprise / Suite Enterprise Plus	50

Limitações principais:

• Limite de campo: 100 campos personalizados por objeto (campos padrão não contam)
• Limites de pesquisa: 5 campos de pesquisa por objeto no Team/Growth, 10 em planos superiores
• Chaves imutáveis: A chave do objeto não pode ser alterada após a criação. Se você cometer um erro, precisará excluir e recriar o objeto (perdendo todos os registros existentes).
• Somente administrador: Apenas administradores podem criar e modificar tipos de objeto. Os agentes podem criar e editar registros se receberem permissão.
• Limites de taxa de API: As operações em massa estão sujeitas à limitação de taxa de API padrão do Zendesk.

Melhores práticas:

• Use convenções de nomenclatura consistentes para chaves (minúsculas com sublinhados funciona bem)
• Documente seu esquema de objeto para outros membros da equipe
• Teste com um pequeno conjunto de dados antes da importação em massa
• Planeje seus relacionamentos de pesquisa cuidadosamente, eles não podem ser facilmente alterados posteriormente

---

Estendendo seu helpdesk com IA

Objetos personalizados oferecem uma maneira poderosa de estruturar seus dados. Mas os dados sozinhos não resolvem problemas de suporte, você precisa torná-los acionáveis. A IA pode preencher essa lacuna.

eesel AI funciona como um colega de equipe de IA dentro de sua instância do Zendesk. Ele aprende com seus artigos da central de ajuda, tickets anteriores e, sim, até mesmo seus dados de objetos personalizados. Em vez de apenas armazenar informações sobre licenças de software ou garantias de produtos, o eesel pode usar esses dados para resolver tickets automaticamente.

Veja como funciona: conecte o eesel à sua conta do Zendesk e ele começará imediatamente a aprender o contexto do seu negócio. Quando um cliente envia um e-mail sobre um problema de licença, o eesel pode procurar seus registros de objetos personalizados, verificar o status e responder com as informações corretas. Nenhum agente é necessário para pesquisas de rotina.

A diferença da automação padrão é que o eesel entende o contexto. Ele não apenas corresponde palavras-chave, ele lê o ticket, entende o que o cliente precisa e toma as medidas apropriadas com base em seus dados personalizados. Você define regras de escalonamento em português claro ("Se a licença estiver expirada, ofereça opções de renovação") e o eesel as segue.

Para equipes que já usam objetos personalizados para rastrear dados complexos de clientes, adicionar uma camada de IA pode transformar esses dados em resoluções automatizadas. Vale a pena explorar se você está procurando escalar sem aumentar proporcionalmente sua equipe.

---

Comece a construir objetos personalizados no Zendesk hoje

Agora você tem dois métodos sólidos para criar tipos de objetos personalizados no Zendesk: a API para controle programático e o Admin Center para configuração visual. Ambas as abordagens permitem que você estenda o Zendesk além de seu modelo de dados padrão para capturar as informações exclusivas que sua empresa precisa.

A chave é começar simples. Escolha um caso de uso (como rastrear licenças de software ou registros de produtos), crie um objeto básico com alguns campos e teste-o com sua equipe. Depois de ver como os objetos personalizados se encaixam em seu fluxo de trabalho, você pode expandir para modelos de dados mais complexos.

Lembre-se de que o planejamento é importante. As chaves de objeto são permanentes, os relacionamentos de campo são difíceis de alterar e os limites do plano são restrições reais. Esboce seu modelo de dados antes de construir.

Para referência detalhada da API e exemplos adicionais, confira a documentação oficial de objetos personalizados do Zendesk. E se você está procurando fazer mais com seus dados personalizados, explore como o eesel AI pode transformar esses dados em resoluções de suporte automatizadas.

---