Tickets

ResumenPuntos de terminación

En HubSpot, los tickets representan solicitudes de ayuda de los clientes. A los tickets se les hace seguimiento a través de tu proceso de asistencia técnica en los estados de la pipeline hasta que se cierren. Los puntos de terminación de los tickets te permiten crear y administrar registros de ticket, así como sincronizar los datos de los registros de ticket entre HubSpot y otros sistemas. 

Obtén más información sobre las API de objetos, registros, propiedades y asociaciones en la guía Comprender el CRM. Para obtener más información general sobre objetos y registros de HubSpot, aprende a administrar la base de datos del CRM.

Crea tickets de asistencia técnica

Para crear nuevos tickets, haz una solicitud POST en /crm/v3/objects/tickets.

En tu solicitud, incluye los datos del ticket en el objeto propiedades. También puedes agregar el objeto asociaciones para asociar el nuevo ticket con registros existentes (por ejemplo, contactos, empresas) o actividades (por ejemplo, reuniones, notas).

Propiedades

Los detalles del ticket se almacenan en las propiedades de ticket. Hay propiedades de ticket de HubSpot predeterminadas, pero también puedes crear propiedades personalizadas.

Al crear un nuevo ticket, debes incluir las siguientes propiedades en tu solicitud: subject (el nombre del ticket), hs_pipeline_stage (el estado del ticket) y, si tienes varias pipelines, hs_pipeline. Si no se especifica una pipeline, se utilizará la pipeline predeterminada.

Para ver todas las propiedades disponibles, puedes recuperar una lista de las propiedades de ticket de tu cuenta haciendo una solicitud GET en /crm/v3/properties/tickets. Más información sobre la API de propiedades.

Nota: debes usar el ID interno de un estado de ticket o pipeline al crear un ticket a través de la API. El ID interno es un número, que también se devolverá cuando recuperes tickets a través de la API. Puedes encontrar el estado de un ticket o el ID interno de la pipeline en la configuración de tu pipeline de tickets.

Por ejemplo, para crear un nuevo ticket, tu solicitud puede ser similar a la siguiente:

///Example request body { "properties": { "hs_pipeline": "0", "hs_pipeline_stage": "1", "hs_ticket_priority": "HIGH", "subject": "troubleshoot report" } }

Asociaciones

Al crear un nuevo ticket, también puedes asociarlo con registros o actividades existentes. En el objeto asociaciones, incluye los siguientes campos:

Use this table to describe parameters / fields
ParameterDescription
toObjectId

El ID del registro o actividad con los que deseas asociar el ticket.

associationTypeId

Un identificador único para indicar el tipo de asociación entre el ticket y el otro objeto o actividad. Los tipos de asociación predeterminados se muestran aquí, o puedes recuperar el valor haciendo una solicitud GET a/crm/v4/associations/{fromObjectType}/{toObjectType}/labels. Más información sobre la API de asociaciones.

También puedes incluir el campo label para asignar una etiqueta de asociación definida que describa la asociación. Más información sobre cómo asociar registros a través de la API de asociaciones.

Por ejemplo, para asociar un nuevo ticket con un registro de contacto y de empresa existentes, tu solicitud se vería de la siguiente manera:

///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 } ] }] }

Recuperar tickets

Puedes recuperar tickets individualmente o en lotes.

  • Para recuperar un ticket individual, haz una solicitud GET en /crm/v3/objects/tickets/{ticketId}.
  • Para recuperar una lista de todos los tickets, haz una solicitud GET en /crm/v3/objects/tickets.

En estos puntos de terminación, puedes incluir los siguientes parámetros de consulta en la URL de la solicitud: 

Use this table to describe parameters / fields
ParameterDescription
propiedades

Una lista separada por comas de las propiedades que se devolverán en la respuesta. Si el un ticket solicitado no tiene un valor para una propiedad, no aparecerá en la respuesta.

propertiesWithHistory

Una lista separada por comas de las propiedades actuales e históricas que se devolverán en la respuesta. Si el un ticket solicitado no tiene un valor para una propiedad, no aparecerá en la respuesta.

asociaciones

Una lista separada por comas de los objetos de los cuales recuperar los ID asociados. No se devolverán en la respuesta las asociaciones especificadas que no existan. Más información sobre la API de asociaciones.
  • Para recuperar un lote de tickets específicos por ID de registro o una propiedad de identificador único personalizado, haz una solicitud POST a crm/v3/objects/tickets/batch/read. El punto de terminación por lote no puede recuperar asociaciones. Obtener más información sobre cómo leer asociaciones por lotes con la API de asociaciones.

Para el punto de terminación de lectura por lotes, también puedes usar el parámetro opcional idProperty para recuperar tickets mediante una propiedad de identificador único personalizada. Por opción predeterminada, los valores de id en la solicitud se refieren al ID de registro (hs_object_id), por lo que no se requiere el parámetro idProperty al recuperar por ID de registro. Para utilizar una propiedad de valor único personalizada para recuperar tickets, debes incluir el parámetro idProperty.

Por ejemplo, para recuperar un lote de tickets, tu solicitud podría tener uno de los siguientes aspectos:

///Example request body with record ID { "properties": [ "subject", "hs_pipeline_stage", "hs_pipeline" ], "inputs": [ { "id": "4444888856" }, { "id": "666699988" } ] }
///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 con valores actuales e históricos para una propiedad, tu solicitud podría ser la siguiente:

///Example request body with record ID (current and historical values) { "propertiesWithHistory": [ "hs_pipeline_stage" ], "inputs": [ { "id": "4444888856" }, { "id": "666699988" } ] }

Actualizar tickets

Puedes actualizar tickets individualmente o por lotes. Para los tickets existentes, el ID de registro es un valor único predeterminado que puedes usar para actualizar el ticket a través de la API, pero también puedes identificar y actualizar tickets utilizando propiedades de identificador único personalizadas.

  • Para actualizar un ticket individual por su ID de registro, haz una solicitud PATCH en /crm/v3/objects/tickets/{ticketId}, e incluye los datos que deseas actualizar.
  • Para actualizar varios tickets, haz una solicitud POST a /crm/v3/objects/tickets/batch/update. En el cuerpo de la solicitud, incluye una matriz con los identificadores de los tickets y las propiedades que deseas actualizar.

Asociar tickets existentes con registros o actividades

Para asociar un ticket con otros registros del CRM o con una actividad, haz una solicitud PUT en  /crm/v3/objects/tickets/{ticketId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}. 

Para recuperar el  valor associationTypeId, consulta esta lista de valores predeterminados o haz una solicitud GET a/crm/v4/associations/{fromObjectType}/{toObjectType}/labels. 

Más información sobre la API de asociaciones.

Eliminar una asociación

Para eliminar una asociación entre un ticket y un registro o actividad, haz una solicitud DELETE en la siguiente URL: /crm/v3/objects/tickets/{ticketId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}.

Anclar una actividad en un registro de ticket

Nota: el anclaje de actividades a los registros de tickets a través de la API requiere la autenticación de OAuth a través de una aplicación pública. Las aplicaciones privadas no se pueden usar para anclar actividades a los registros de tickets.

Puedes anclar una actividad en un registro de ticket a través de la API incluyendo el campo hs_pinned_engagement_id en tu solicitud. En el campo, incluye el id de la actividad a anclar, que se puede recuperar a través de las API de interacciones. Puedes anclar una actividad por registro, y la actividad ya debe estar asociada con el ticket antes de anclarla.

Para establecer o actualizar la actividad anclada de un ticket, tu solicitud podría ser la siguiente:

///Example request body PATCH /crm/v3/objects/tickets/{ticketId} { "properties": { "hs_pinned_engagement_id": 123456789 } }

También puedes crear un ticket, asociarlo a una actividad existente y anclar la actividad en la misma solicitud. Por ejemplo:

///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 }] }] }

Eliminar tickets

Puedes eliminar tickets individualmente o por lotes, lo que agregará el ticket a la papelera de reciclaje en HubSpot. Más tarde puedes restaurar el ticket dentro de HubSpot.

Para eliminar un ticket individual por su ID, haz una solicitud DELETE en /crm/v3/objects/tickets/{ticketId}.

Obtén más información sobre la eliminación de tickets por lotes en la pestaña Puntos de terminación en la parte superior de este artículo.

¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.