Objetos personalizados

Visão geralObjetosEsquema de objeto
APPLICABLE PRODUCTS
  • Marketing Hub
    • Enterprise
  • Sales Hub
    • Enterprise
  • Service Hub
    • Enterprise
  • Content Hub
    • Enterprise
  • Operations Hub
    • Enterprise

Em cada conta do HubSpot, há os objetos padrão do CRM: contatos, empresas, negócios e tickets. Para representar e organizar seus dados de CRM com base nas necessidades da sua empresa, você também pode criar objetos personalizados. Você pode criar um objeto personalizado no HubSpot ou usar a API de objetos personalizados para definir objetos, propriedades e associações personalizadas a outros objetos do CRM. 

Abaixo, saiba como criar e gerenciar objetos personalizados por meio da API e veja um passo a passo sobre como criar um objeto personalizado de exemplo.

Para saber mais sobre como criar objetos personalizados, confira os seguintes posts de blog para desenvolvedores da HubSpot:

Observação: os objetos personalizados são específicos de cada conta e, dependendo da sua assinatura, há limites para o número de objetos personalizados que você pode criar. Saiba mais sobre seus limites em nosso Catálogo de produtos e serviços da HubSpot.

Métodos de autenticação

Você pode criar, ler e atualizar objetos personalizados usando um dos seguintes métodos de autenticação:

Observação: a partir de 30 de novembro de 2022, as chaves de API da HubSpot serão desativadas e não terão mais suporte. Continuar usando as chaves de API da HubSpot representará um risco de segurança para sua conta e dados. Durante esta fase, a HubSpot poderá desativar sua chave a qualquer momento.

Você deve autenticar usando um token de acesso de aplicativo privado ou OAuth. Saiba mais sobre essa alteração e como migrar uma integração de chave de API para usar um aplicativo privado.

Criar um objeto personalizado

Para criar um objeto personalizado, primeiramente, será necessário definir o esquema do objeto. O esquema inclui o nome do objeto, propriedades e associações a outros objetos do CRM. Você pode encontrar os detalhes completos da solicitação do esquema na guia Esquema do objeto na parte superior deste artigo. Você também pode visualizar uma solicitação de amostra no exemplo de passo a passo abaixo.

Para criar o esquema de objeto personalizado, faça uma solicitação POST para crm/v3/schemas. No corpo da solicitação, inclua definições para seu esquema de objeto, incluindo seu nome, propriedades e associações.

Ao nomear o objeto personalizado, saiba que:

  • Depois de criar um objeto, seu nome e rótulo não poderão ser alterados.
  • O nome pode conter somente letras, números e sublinhados.
  • O primeiro caractere do nome deve ser uma letra.
  • Os rótulos longos podem ser cortados em certas partes do produto.

Abaixo, leia sobre as definições necessárias para as propriedades e associações do objeto. 

Propriedades

As propriedades que você definir no corpo da solicitação serão usadas para armazenar informações em registros de objetos personalizados individuais.

Observação: você pode ter até 10 propriedades de valor exclusivo para cada objeto personalizado na sua conta da HubSpot.

Você usará suas propriedades definidas para preencher os seguintes campos baseados em propriedades:

  • requiredProperties: as propriedades que são necessárias ao criar um novo registro de objeto personalizado.
  • searchableProperties: as propriedades que são indexadas para pesquisa no HubSpot.
  • primaryDisplayProperty: a propriedade usada para nomear registros de objetos personalizados individuais.
  • secondaryDisplayProperties: as propriedades que aparecem em registros individuais sob primaryDisplayProperty.
    custom-object-secondary-display-properties0
    • A primeira propriedade listada em secondaryDisplayProperties também será adicionada como um quarto filtro na página de índice de objetos se for um dos seguintes tipos de propriedades:
      • string
      • number
      • enumeration
      • boolean
      • datetime
        custom-object-dashboard-filter0
    • Para remover uma propriedade de exibição da UI, você precisará, primeiramente, excluir a propriedade e depois recriá-la.

Por padrão, ao criar propriedades por meio da solicitação de esquema, a propriedade type é definida para string e fieldType é definido para text. Abaixo estão os valores que você pode usar para criar diferentes tipos de propriedades.

Valores válidos para type
type Descrição Valores fieldType válidos
enumeration Uma sequência de caracteres que representa um conjunto de opções separadas por ponto e vírgula.  booleancheckbox, checkbox, radio, select
date Um valor com formatação ISO 8601 que representa um dia, mês e ano específicos. date
dateTime Um valor com formatação ISO 8601 que representa um dia, mês, ano e horário do dia específicos. O aplicativo HubSpot não exibirá o horário do dia. date
string Uma string de texto simples, com no máximo 65.536 caracteres. file, text, textarea
number Um valor numérico que contém dígitos numéricos e, na maioria das vezes, um número decimal. number
Valores válidos para fieldType 
fieldType Descrição
booleancheckbox Uma entrada que permite que os usuários selecionem Sim ou Não. Quando usada em um formulário, essa entrada aparece como uma única caixa de seleção.
checkbox Uma lista de caixas de seleção que permite que um usuário selecione várias opções em um conjunto de opções válidas para a propriedade.
date Um valor de data, que é exibido como um seletor de data.
file Permite que um arquivo seja carregado em um formulário. Armazenado e exibido como link de URL para o arquivo.
number Uma string de numerais ou números escritos em formato decimal ou em notação científica.
radio Uma entrada que permite que os usuários selecionem um conjunto de opções válidas para a propriedade. Quando usada em um formulário, essa entrada é exibida como um conjunto de botões de opção.
select Uma entrada suspensa que permite que os usuários selecionem um conjunto de opções válidas para a propriedade.
text Uma string de texto simples, que é exibida em uma entrada de texto com uma única linha.
textarea Uma string de texto simples, que é exibida como uma entrada de texto com várias linhas.

Associações

A HubSpot associará automaticamente um objeto personalizado com os e-mails, reuniões, notas, tarefas, chamadas e objetos de conversas. Você pode associar ainda mais seu objeto personalizado a outros objetos HubSpot padrão ou outros objetos personalizados.

Ao criar associações por meio da solicitação create schema, identifique objetos padrão usando o nome e objetos personalizados usando o valor objectTypeId. Por exemplo: 

// Example associatedObjects array "associatedObjects": [ "CONTACT", "COMPANY", "TICKET", "DEAL", "2-3453932" ]

Recuperar objetos personalizados existentes

Para recuperar todos os objetos personalizados, faça uma solicitação GET para/crm/v3/schemas.

Para recuperar um objeto personalizado específico, faça uma solicitação GET para um dos seguintes endpoints:

  • /crm/v3/schemas/{objectTypeId}
  • /crm/v3/schemas/p_{object_name}
  • /crm/v3/schemas/{fullyQualifiedName}. Você pode encontrar o

    fullyQualifiedName do objeto em seu esquema, que é derivado de p{portal_id}_{object_name}. Você pode encontrar o ID do portal da sua conta usando a API de informações da conta.

Por exemplo, para uma conta com um ID de 1234 e um objeto chamado lender, o URL de solicitação pode ser semelhante a qualquer um dos seguintes:

Obter registros de objetos personalizados

Você também pode obter os registros de um objeto personalizado.

  • Para recuperar um registro específico pelo seu valor de ID de registro, faça uma solicitação GET para crm/v3/objects/{objectType}/{recordId}.

Para este endpoint, você pode incluir os seguintes parâmetros de consulta no URL da solicitação: 

Use this table to describe parameters / fields
ParameterDescription
propriedades

Uma lista separada por vírgulas das propriedades a serem retornadas em resposta. Se o objeto personalizado solicitado não tiver um valor para uma propriedade, ele não será exibido na resposta.

propertiesWithHistory

Uma lista separada por vírgulas das propriedades atuais e do histórico a serem retornadas em resposta. Se o registro do objeto personalizado solicitado não tiver um valor para uma propriedade, ele não será exibido na resposta.

associações

Uma lista separada por vírgulas de objetos para recuperar IDs associados. Todas as associações especificadas que não existem não serão retornadas na resposta. Saiba mais sobre a API de associações.
  • Para recuperar vários registros, faça uma solicitação POST para crm/v3/objects/{objectType}/batch/read. O endpoint em lote não pode recuperar associações. Saiba como fazer associações de leitura em lote com a API de associações.

Na sua solicitação, você pode recuperar os registros pelo ID do registro (hs_object_id) ou por uma propriedade de identificador exclusivo personalizada. Por padrão, os valores de id na solicitação referem-se ao ID do registro; portanto, o parâmetro idProperty não é necessário ao recuperar pelo ID do registro. Para usar uma propriedade de valor exclusivo personalizada, você deve incluir o parâmetro idProperty.

Por exemplo, para recuperar um lote de registros de objetos personalizados, sua solicitação pode ser parecida com o seguinte:

///Example request body for record ID { "properties": [ "petname" ], "inputs": [ { "id": "12345" }, { "id": "67891" } ] }
///Example request body for unique value property { "properties": [ "petname" ], "idProperty": "uniquepropertyexample", "inputs": [ { "id": "abc" }, { "id": "def" } ] }
Para recuperar registos de objetos personalizados com valores atuais e do histórico de uma propriedade, sua solicitação pode ser parecida com o seguinte:
///Example request body for record ID (current and historical values) { "propertiesWithHistory": [ "pet_owner" ], "inputs": [ { "id": "12345" }, { "id": "67891" } ] }

Atualizar os objetos personalizados existentes

Para atualizar o esquema de um objeto, faça uma solicitação PATCH para https://api.hubapi.com/crm/v3/schemas/{objectTypeId}.

Quando seu objeto personalizado for definido:

  • O nome e os rótulos do objeto (singular e plural) não podem ser alterados.
  • As propriedades requiredProperties, searchableProperties, primaryDisplayProperty esecondaryDisplayProperties podem ser alteradas atualizando o esquema do objeto. Para definir uma nova propriedade como uma propriedade obrigatória, pesquisável ou de exibição, você precisa criá-la antes de atualizar o esquema.
  • Você pode criar e editar propriedades de objetos personalizados no HubSpot ou por meio da API de propriedades. 

Atualizar associações

Para adicionar outras associações de objetos ao seu objeto personalizado, faça uma solicitação POST para/crm/v3/schemas/{objectTypeId}/associations.

Você só pode associar seu objeto personalizado com objetos HubSpot padrão (por exemplo, contato, empresa, negócio ou ticket) ou outros objetos personalizados. No campo toObjectTypeId, identifique objetos personalizados pelo valor objectTypeId e objetos padrão pelo seu nome. Por exemplo:

// Example association request body { "fromObjectTypeId": "2-3444025", "toObjectTypeId": "ticket", "name": "cat_to_ticket" }

Excluir um objeto personalizado

Você somente pode excluir um objeto personalizado depois que todas as instâncias de objeto desse tipo forem excluídas. Para excluir um objeto personalizado, faça uma solicitação DELETE para /crm/v3/schemas/{objectType}.

Se você precisar criar um novo objeto personalizado com o mesmo nome que o objeto excluído, você deve excluir o esquema fazendo uma solicitação DELETE para /crm/v3/schemas/{objectType}?archived=true. Você só pode excluir um tipo de objeto personalizado depois que todas as instâncias de objeto desse tipo, associações e propriedades de objeto personalizado forem excluídas.

Exemplo de objeto personalizado

Apresentamos a seguir um passo a passo para criar um exemplo de objeto personalizado. Para obter detalhes completos das solicitações mostradas, consulte a guia Definição do objeto na parte superior do artigo.

Este passo a passo abrange:

  1. criação de um esquema de objeto personalizado.
  2. criação de um registro de objeto personalizado.
  3. associação de um registro de objeto personalizado a um contato do HubSpot.
  4. criação de uma nova definição de associação entre o objeto personalizado e o ticket da HubSpot.
  5. criação de uma nova definição de propriedade.
  6. atualização do esquema do objeto (ou seja, secondaryDisplayProperties) com a nova propriedade.

Meta: uma concessionária de automóveis chamada CarSpot deseja armazenar seu inventário na HubSpot usando um objeto personalizado. Para controlar a propriedade e compras de veículos, eles associarão carros a registros do contato. Além disso, eles também controlarão a manutenção do veículo usando tickets da HubSpot e propriedades personalizadas.

Criar esquema de objetos

O CarSpot precisa criar um esquema de objeto que possa representar os seguintes atributos como propriedades: 

  1. Condição (nova ou usada): enumeração
  2. Data de chegada na concessionária: data
  3. Ano: número
  4. Marca: cadeia de caracteres
  5. Modelo: cadeia de caracteres
  6. VIN: cadeia de caracteres (valor único)
  7. Cor: cadeia de caracteres
  8. Quilometragem: cadeia de caracteres
  9. Preço: número
  10. Observações: cadeia de caracteres

Eles também adicionarão uma descrição para fornecer contexto sobre como usar o objeto e definirão uma associação entre seu objeto personalizado e o objeto de contatos padrão para que possam conectar carros a possíveis compradores. 

Com o modelo de dados finalizado, eles criarão o esquema de objetos fazendo uma solicitação POST para /crm/v3/schemas com o seguinte corpo de solicitação:todos

// Example POST request to https://api.hubspot.com/crm/v3/schemas { "name": "cars", "description": "Cars keeps track of cars currently or previously held in our inventory.", "labels": { "singular": "Car", "plural": "Cars" }, "primaryDisplayProperty": "model", "secondaryDisplayProperties": [ "make" ], "searchableProperties": [ "year", "make", "vin", "model" ], "requiredProperties": [ "year", "make", "vin", "model" ], "properties": [ { "name": "condition", "label": "Condition", "type": "enumeration", "fieldType": "select", "options": [ { "label": "New", "value": "new" }, { "label": "Used", "value": "used" } ] }, { "name": "date_received", "label": "Date received", "type": "date", "fieldType": "date" }, { "name": "year", "label": "Year", "type": "number", "fieldType": "number" }, { "name": "make", "label": "Make", "type": "string", "fieldType": "text" }, { "name": "model", "label": "Model", "type": "string", "fieldType": "text" }, { "name": "vin", "label": "VIN", "type": "string", "hasUniqueValue": true, "fieldType": "text" }, { "name": "color", "label": "Color", "type": "string", "fieldType": "text" }, { "name": "mileage", "label": "Mileage", "type": "number", "fieldType": "number" }, { "name": "price", "label": "Price", "type": "number", "fieldType": "number" }, { "name": "notes", "label": "Notes", "type": "string", "fieldType": "text" } ], "associatedObjects": [ "CONTACT" ] }

Depois de criar o esquema do objeto, o CarSpot registra o campo {objectTypeId} do novo objeto, pois ele será usado para buscar e atualizar o objeto posteriormente. Eles também podem usar o valor {fullyQualifiedName}, se preferirem.

Criação de um registro de objeto personalizado

Com o objeto personalizado criado, agora, a CarSpot pode criar registros no objeto para cada carro em seu inventário.

Eles criarão seu primeiro carro fazendo uma solicitação POST para /crm/v3/objects/2-3465404 com o seguinte corpo de solicitação:

// Example POST request to https://api.hubspot.com/crm/v3/objects/2-3465404 { "properties": { "condition": "used", "date_received": "1582416000000", "year": "2014", "make": "Nissan", "model": "Frontier", "vin": "4Y1SL65848Z411439", "color": "White", "mileage": "80000", "price": "12000", "notes": "Excellent condition. No accidents." } }

A resposta para esta chamada de API seria semelhante a:Copiar todos

// Example response body { "id": "181308", "properties": { "color": "White", "condition": "used", "make": "Nissan", "mileage": "80000", "model": "Frontier", "vin": "4Y1SL65848Z411439", "notes": "Excellent condition. No accidents.", "price": "12000", "year": "2014", "date_received": "1582416000000" }, "createdAt": "2020-02-23T01:44:11.035Z", "updatedAt": "2020-02-23T01:44:11.035Z", "archived": false }

Com o registro criado, eles podem usar o valor id para associar posteriormente o carro a um contato existente.

Se quisessem recuperar mais tarde este registro junto com propriedades específicas, eles poderiam fazer uma solicitação GET para https://api.hubapi.com/crm/v3/objects/2-3465404/181308?portalId=1234567&properties=year&properties=make&properties=model

Associar um registro de objeto personalizado a outro contato

Você pode usar o ID do novo registro de carro (181308) e o ID de outro registro para associar um registro de objeto personalizado a um registro de outro objeto.

Para criar uma associação, faça uma solicitaçãoPUT para /crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType}. Se a relação do objeto já estiver definida, para determinar o valor associationType, faça uma solicitação GET para crm/v3/schemas/{objectType}.

Por exemplo, com o ID de contato 51 e o tipo de associação 75, o CarSpot pode associar o registro do carro a um contato. Usando os IDs acima, a URL da solicitação será construída da seguinte maneira:

https://api.hubspot.com/crm/v3/objects/2-3465404/181308/associations/contacts/51/75

Definir uma nova associação

Agora, a CarSpot quer começar o rastreamento dos serviços pós-venda de seus carros. Para fazer isso, eles usarão os tickets da HubSpot para registrar qualquer manutenção realizada.

Para permitir associações entre carros e tickets, eles criarão uma nova associação fazendo uma solicitação POST para /crm/v3/schemas/2-3465404/associations com o seguinte corpo de solicitação:

// Example POST request to https://api.hubspot.com/crm/v3/schemas/2-3465494/associations { "fromObjectTypeId": "2-3465404", "toObjectTypeId": "ticket", "name": "car_to_ticket" }

A resposta para esta chamada de API seria semelhante a:Copiar todos

// Example response { "id": "121", "createdAt": "2020-02-23T01:52:12.893826Z", "updatedAt": "2020-02-23T01:52:12.893826Z", "fromObjectTypeId": "2-3465404", "toObjectTypeId": "0-5", "name": "car_to_ticket" }

Ao criar uma nova associação entre dois objetos personalizados, especifique os objetos personalizados por objectTypeId no campo toObjectTypeId. Para objetos padrão, você pode identificá-los pelo nome ou usar os seguintes valores: 

  • Contato: 0-1
  • Empresa: 0-2
  • Negócio: 0-3
  • Ticket: 0-5

Definir uma nova propriedade

À medida que continuam a controlar a manutenção, a CarSpot vê uma oportunidade para agrupar serviços de manutenção em pacotes. Para controlar esses pacotes de manutenção em registros de carros individuais, eles criarão uma nova propriedade de enumeração que contém os pacotes disponíveis.

Para definir uma nova propriedade, eles farão uma solicitação POST para/crm/v3/properties/2-3465404 com o seguinte corpo de solicitação:

// Example POST request to https://api.hubspot.com/crm/v3/properties/2-3465404 { "groupName": "car_information", "name": "maintenance_package", "label": "Maintenance Package", "type": "enumeration", "fieldType": "select", "options": [ { "label": "Basic", "value": "basic" }, { "label": "Oil change only", "value": "oil_change_only" }, { "label": "Scheduled", "value": "scheduled" } ] }

A resposta para esta chamada de API seria semelhante a:Copiar todos

// Example response { "updatedAt": "2020-02-23T02:08:20.055Z", "createdAt": "2020-02-23T02:08:20.055Z", "name": "maintenance_package", "label": "Maintenance Package", "type": "enumeration", "fieldType": "select", "groupName": "car_information", "options": [ { "label": "Basic", "value": "basic", "displayOrder": -1, "hidden": false }, { "label": "Oil change only", "value": "oil_change_only", "displayOrder": -1, "hidden": false }, { "label": "Scheduled", "value": "scheduled", "displayOrder": -1, "hidden": false } ], "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }

Agora que a propriedade foi criada, eles querem exibi-la na barra lateral de cada registro de carro para que as informações fiquem facilmente disponíveis para seus representantes de vendas e técnicos. Para fazer isso, eles adicionarão a propriedade a secondaryDisplayProperties fazendo uma solicitação PATCH para/crm/v3/schemas/2-3465404 com o seguinte corpo de solicitação: 

// Example PATCH request to https://api.hubspot.com/crm/v3/schemas/2-3465404 { "secondaryDisplayProperties": [ "maintenance_package" ] }

A resposta para esta chamada de API seria semelhante a:Copiar todos

// Example response { "id": "3465404", "createdAt": "2020-02-23T01:24:54.537Z", "updatedAt": "2020-02-23T02:12:24.175874Z", "labels": { "singular": "Car", "plural": "Cars" }, "requiredProperties": [ "year", "model", "vin", "make" ], "searchableProperties": [ "year", "model", "vin", "make" ], "primaryDisplayProperty": "model", "secondaryDisplayProperties": [ "maintenance_package" ], "portalId": 1234567, "name": "car" }

Agora, quando um técnico abre um registro do contato com um carro associado, a propriedade será exibida no cartão de objeto personalizado na barra lateral:

Screen Shot 2020-03-06 at 11.08.41 AM

Como a CarSpot continua a usar a HubSpot, eles provavelmente encontrarão maneiras de refinar e expandir esse objeto personalizado e muito mais usando a API da HubSpot. Eles podem até mesmo optar por criar páginas dinâmicas usando seus dados de objetos personalizados.

Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..