No HubSpot, os tickets representam as solicitações de ajuda feitas por clientes. Os tickets são rastreados durante o processo de suporte nos status de pipeline até que sejam fechados. Os pontos de extremidade de tickets permitem controlar a criação e o gerenciamento de registros de tickets, bem como sincronizar os dados de tickets entre o HubSpot e outros sistemas.
Saiba mais sobre objetos, registros, propriedades e APIs de associações no guia Noções básicas do CRM. Para obter informações mais gerais sobre objetos e registros no HubSpot, saiba como gerenciar seu banco de dados do CRM.
Para criar novos tickets, faça uma solicitação POST
para /crm/v3/objects/tickets
.
Na solicitação, inclua os dados do ticket em um objeto de propriedades. Você também pode adicionar um objeto de associações para associar seu novo ticket a registros (por exemplo, contatos, empresas) ou atividades (por exemplo, reuniões, observações) existentes.
Os detalhes do ticket são armazenados nas propriedades do ticket. Existem propriedades de ticket padrão do HubSpot, mas você também pode criar propriedades personalizadas.
Ao criar um novo ticket, você deve incluir as seguintes propriedades na solicitação: subject
(o nome do ticket), hs_pipeline_stage
(o status do ticket) e, caso tenha vários pipelines, hs_pipeline
. Se um pipeline não for especificado, o pipeline padrão será usado.
Para exibir todas as propriedades disponíveis, você pode recuperar uma lista das propriedades do ticket da sua conta, fazendo uma solicitação GET
para /crm/v3/properties/tickets
. Saiba mais sobre a API de propriedades.
Observação: você deve usar o ID interno de um status de ticket ou pipeline ao criar um ticket por meio da API. O ID interno é um número, que também será retornado quando você recuperar tickets por meio da API. Você pode encontrar o status de um ticket ou a ID interna do pipeline nas configurações do pipeline de tickets.
Por exemplo, para criar um novo ticket, a solicitação pode ser semelhante à seguinte:
///Example request body
{
"properties": {
"hs_pipeline": "0",
"hs_pipeline_stage": "1",
"hs_ticket_priority": "HIGH",
"subject": "troubleshoot report"
}
}
Ao criar um novo ticket, você também pode associá-lo a registros ou atividades existentes, incluindo um objeto de associações. Por exemplo, para associar um novo ticket a um contato e uma empresa existentes, a solicitação seria parecida com a seguinte:
xxxxxxxxxx
///Example request body
{
"properties": {
"hs_pipeline": "0",
"hs_pipeline_stage": "1",
"hs_ticket_priority": "HIGH",
"subject": "troubleshoot report"
},
"associations": [
{
"to": {
"id": 201
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 16
}
]
},
{
"to": {
"id": 301
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 26
}
]
}
]
}
No objeto de associações, você deve incluir o seguinte:
Descrição | Parâmetro |
---|---|
to | O registro ou a atividade que você deseja associar ao ticket especificado por seu valor de id exclusivo. |
types | O tipo de associação entre o ticket e o registro/atividade. Inclua associationCategory e associationTypeId . Os IDs de tipo de associação padrão são listados aqui, ou você pode recuperar o valor de tipos de associação personalizados (ou seja, rótulos) por meio da API de associações. |
Você pode recuperar tickets individualmente ou em lotes.
- Para recuperar um ticket individual, faça uma solicitação
GET
para/crm/v3/objects/tickets/{ticketId}
. - Para solicitar uma lista de todos os tickets, faça uma solicitação
GET
para/crm/v3/objects/tickets
.
Para ambos os pontos de extremidade, você pode incluir os seguintes parâmetros de consulta no URL da solicitação:
Descrição | Parâmetro |
---|---|
properties | Uma lista separada por vírgulas das propriedades a serem retornadas em resposta. Se o ticket 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 ticket solicitado não tiver um valor para uma propriedade, ele não será exibido na resposta. |
associations | 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 um lote de tickets específicos por ID de registro ou uma propriedade de identificador exclusivo personalizada, faça uma solicitação
POST
paracrm/v3/objects/tickets/batch/read
. O ponto de extremidade em lote não pode recuperar associações. Saiba como fazer associações de leitura em lote com a API de associações.
Para o ponto de extremidade de leitura em lote, você também pode usar o parâmetro idProperty
opcional para recuperar tickets por uma propriedade de identificador exclusivo personalizada. Por padrão, os valores de id
na solicitação referem-se ao ID do registro (hs_object_id
); portanto, o parâmetro idProperty
não é necessário ao recuperar pelo ID do registro. Para usar uma propriedade de valor exclusivo personalizada para recuperar tickets, você deve incluir o parâmetro idProperty
.
Por exemplo, para recuperar um lote de tickets, sua solicitação pode ser parecida com o seguinte:
xxxxxxxxxx
///Example request body with record ID
{
"properties": ["subject", "hs_pipeline_stage", "hs_pipeline"],
"inputs": [
{
"id": "4444888856"
},
{
"id": "666699988"
}
]
}
xxxxxxxxxx
///Example request body with a unique value property
{
"properties": ["subject", "hs_pipeline_stage", "hs_pipeline"],
"idProperty": "uniquepropertyexample",
"inputs": [
{
"id": "abc"
},
{
"id": "def"
}
]
}
Para recuperar tickets com valores atuais e do histórico de uma propriedade, sua solicitação pode ser parecida com o seguinte:
xxxxxxxxxx
///Example request body with record ID (current and historical values)
{
"propertiesWithHistory": ["hs_pipeline_stage"],
"inputs": [
{
"id": "4444888856"
},
{
"id": "666699988"
}
]
}
Você pode atualizar tickets individualmente ou em massa. Para tickets existentes, o ID do registro é um valor exclusivo padrão que você pode usar para atualizar o ticket via API, mas você também pode identificar e atualizar tickets usando propriedades de identificador exclusivo personalizadas.
- Para atualizar um ticket individual por seu ID de registro, faça uma solicitação
PATCH
para/crm/v3/objects/tickets/{ticketId}
e inclua os dados que você deseja atualizar. - Para atualizar vários tickets, faça uma solicitação
POST
para/crm/v3/objects/tickets/batch/update
. No corpo da solicitação, inclua uma matriz com os identificadores dos tickets e as propriedades que deseja atualizar.
Para associar um ticket a outros registros do CRM ou a uma atividade, faça uma solicitação PUT
para /crm/v3/objects/tickets/{ticketId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
Para recuperar o valor associationTypeId
, consulte esta lista de valores padrão ou envie uma solicitação GET
para /crm/v4/associations/{fromObjectType}/{toObjectType}/labels
.
Saiba mais sobre a API de associações.
Para remover uma associação entre um ticket e um registro ou uma atividade, faça uma solicitação DELETE
para o seguinte URL: /crm/v3/objects/tickets/{ticketId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
Você pode fixar uma atividade em um registro de ticket por meio da API, incluindo o campo hs_pinned_engagement_id
na sua solicitação. No campo, inclua o id
da atividade a ser fixada, que pode ser recuperado por meio das APIs de engajamentos. Você pode fixar uma atividade por registro. No entanto, a atividade já deve estar associada ao registro de ticket antes da fixação.
Para definir ou atualizar a atividade fixada de um ticket, sua solicitação pode ser parecida com o seguinte:
xxxxxxxxxx
///Example request body PATCH /crm/v3/objects/tickets/{ticketId}
{
"properties": {
"hs_pinned_engagement_id": 123456789
}
}
Você também pode criar um registro de ticket, associá-lo a uma atividade existente e fixar a atividade na mesma solicitação. Por exemplo:
xxxxxxxxxx
///Example request body POST /crm/v3/objects/tickets
{
"properties": {
"hs_pipeline": "0",
"hs_pipeline_stage": "1",
"hs_ticket_priority": "HIGH",
"subject": "troubleshoot report",
"hs_pinned_engagement_id": 123456789
},
"associations": [
{
"to": {
"id": 123456789
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 227
}
]
}
]
}
Você pode excluir tickets individualmente ou em massa, o que adicionará o ticket à lixeira no HubSpot. Posteriormente, você pode restaurar o ticket no HubSpot.
Para excluir um ticket individual pelo seu ID, faça uma solicitação DELETE
para /crm/v3/objects/tickets/{ticketId}
.
Saiba mais sobre a exclusão em massa de tickets na guia* Pontos de extremidade* na parte superior deste artigo.