> ## Documentation Index > Fetch the complete documentation index at: https://br.developers.hubspot.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # API do CRM | Tickets > **[Run in Postman](https://app.getpostman.com/run-collection/26126890-98d91102-ed47-41b0-8304-23f04f12ed0f)** > **Requisitos de escopo** # Tickets 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](https://knowledge.hubspot.com/pt/object-settings/set-up-and-customize-pipelines) 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](https://br.developers.hubspot.com/docs/guides/crm/understanding-the-crm). Para obter informações mais gerais sobre objetos e registros no HubSpot,[ saiba como gerenciar seu banco de dados do CRM](https://knowledge.hubspot.com/pt/get-started/manage-your-crm-database). ## Criar tickets 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. ### Propriedades Os detalhes do ticket são armazenados nas propriedades do ticket. Existem [propriedades de ticket padrão do HubSpot](https://knowledge.hubspot.com/pt/properties/hubspots-default-ticket-properties), mas você também pode [criar propriedades personalizadas](https://knowledge.hubspot.com/pt/properties/create-and-edit-properties). 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](https://br.developers.hubspot.com/docs/api-reference/crm-properties-v3/guide.md). > [!WARNING] > > **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.](https://knowledge.hubspot.com/pt/object-settings/set-up-and-customize-pipelines) Por exemplo, para criar um novo ticket, a solicitação pode ser semelhante à seguinte: **JSON** ```json theme={null} ///Example request body { "properties": { "hs_pipeline": "0", "hs_pipeline_stage": "1", "hs_ticket_priority": "HIGH", "subject": "troubleshoot report" } } ``` ### Associações Ao criar um novo ticket, você também pode associá-lo a [registros](https://knowledge.hubspot.com/pt/records/associate-records) ou [atividades](https://knowledge.hubspot.com/pt/records/associate-activities-with-records) 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: **JSON** ```json theme={null} ///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](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md#association-type-id-values), ou você pode recuperar o valor de tipos de associação personalizados (ou seja, rótulos) por meio da [API de associações](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md#retrieve-association-types). | ## Recuperar tickets 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.](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md) | * Para recuperar um lote de tickets específicos por ID de registro ou uma [propriedade de identificador exclusivo personalizada](https://br.developers.hubspot.com/docs/api-reference/crm-properties-v3/guide.md#create-unique-identifier-properties), faça uma solicitação `POST` para `crm/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](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md). 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](https://br.developers.hubspot.com/docs/api-reference/crm-properties-v3/guide.md#create-unique-identifier-properties). 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: ```json theme={null} ///Example request body with record ID { "properties": ["subject", "hs_pipeline_stage", "hs_pipeline"], "inputs": [ { "id": "4444888856" }, { "id": "666699988" } ] } ``` ```json theme={null} ///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: ```json theme={null} ///Example request body with record ID (current and historical values) { "propertiesWithHistory": ["hs_pipeline_stage"], "inputs": [ { "id": "4444888856" }, { "id": "666699988" } ] } ``` ## Atualizar tickets 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.](https://br.developers.hubspot.com/docs/api-reference/crm-properties-v3/guide.md#create-unique-identifier-properties) * 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. ### Associar tickets existentes a registros ou atividades 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}`. > [!NOTE] > > Para recuperar o valor `associationTypeId`, consulte [esta lista](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md#association-type-id-values) 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.](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md) ### Remover uma associação 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}`. ## Fixar uma atividade em um registro de ticket 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](https://br.developers.hubspot.com/docs/api-reference/overview.md). 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: ```json theme={null} ///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: ```json theme={null} ///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 } ] } ] } ``` ## Excluir tickets Você pode excluir tickets individualmente ou em massa, o que adicionará o ticket à lixeira no HubSpot. Posteriormente, você pode[ restaurar o ticket no HubSpot](https://knowledge.hubspot.com/pt/records/restore-deleted-records). Para excluir um ticket individual pelo seu ID, faça uma solicitação `DELETE` para `/crm/v3/objects/tickets/{ticketId}`. Saiba mais sobre exclusão de tickets na \[documentação de referência.