Preguntas frecuentes

Obtén respuestas a preguntas frecuentes sobre las API de HubSpot. Para las preguntas de desarrollo del CMS, visita su documentación. Si no puedes encontrar lo que buscas, puedes preguntar en nuestro foro para desarrolladores

¿Cómo manipulo formularios usando jQuery?

Cuando manipulas los valores de entrada de formulario usando .val() o .prop(), debes activar un evento de cambio usando change()  o  trigger('change') para que el registro cambie correctamente.

Debido a que los formularios de HubSpot se visualizan después de las compilaciones de DOM, debes activar la manipulación después de que la ventana se carga o modificar la incrustación para usar el parámetro onFormReady.

Update fields when page finishes loading: $(window).load(function(){ $('input[value="checkbox_1"]').prop('checked', true).change(); $('input[name="firstname"]').val('Brian').change(); }); Modified embed code to update fields when form builds: hbspt.forms.create({ portalId: 'XXXXXX', formId: 'aa8b5b4a-62ac-461b-a387-XXXXXXXXXXX', onFormReady: function($form, ctx){ $('input[value="checkbox_1"]').prop('checked', true).change(); $('input[name="firstname"]').val('Brian').change(); } });

¿Cómo puedo darle formato a las marcas de tiempo para las API de HubSpot?

Las API de HubSpot aceptan dos formatos diferentes para los valores de fecha y hora.

El primer formato son las cadenas con formato ISO 8601. Según el tipo de datos, estos serán uno de dos formatos diferentes:

  • Para valores que representan una fecha específica, se usará el formato de fecha completa: AAAA-MM-DD (por ejemplo, 2020-02-29)
  • Para los valores que representan una información y un tiempo específicos, se usará un formato de datos completos más horas, minutos, segundos y una fracción decimal de un segundo: AAAA-MM-DDThh:mm:ss.sTZD (por ejemplo, 2020-02-29T03:30:17.000Z). Ten en cuenta que todas las horas serán representadas en UTC, por lo que los valores siempre el designador UTC «Z».

El segundo formato son las marcas de tiempo con formato UNIX en milisegundos. Los valores de marca de tiempo se tratarán como si estuvieran establecidos en la hora UTC. Por ejemplo, el valor de la marca de tiempo 1427997766000 se traduce al 2 de abril de 2015 a las 2:02:46 p. m. EDT (horario de verano del este) o al 2 de abril de 2015 a las 18:02:46 UTC.

Los valores de hora serán representados con el valor ISO 8601 en las respuestas, pero las API aceptarán cualquier el formato.

Propiedades de fecha y fecha y hora en el HubSpot CRM

HubSpot tiene dos tipos de propiedades de objetos de CRM para almacenar tiempo: fecha y fecha y hora.

Las propiedades de Fecha (incluidas las propiedades de selector de fechas creadas en HubSpot) solo pueden almacenar la fecha, no la hora. Al configurar valores de propiedad de fecha, recomendamos usar el formato de fecha completa ISO 8601.

Ejemplos:

  • 2015-05-01 se usaría para el 1 de mayo de 2015. Si bien es posible usar una marca de tiempo de milisegundos, los valores deben establecerse a la medianoche UTC para la fecha deseada. 
  • Se utilizará 1430438400000 para el 1 de mayo de 2015 (01 May 2015 00:00:00 UTC).

Si intentas establecer un valor que no sea medianoche UTC, recibirás un error. En HubSpot, las propiedades de fecha siempre muestran la fecha específica en que están configuradas, independientemente de la configuración de zona horaria de la cuenta o el usuario.

Las propiedades de fecha y hora pueden almacenar cualquier hora, por lo tanto, cualquier valor de fecha o de fecha y hora válidos que utilicen cualquiera de los formatos serán aceptados. En HubSpot, las propiedades de fecha y hora se muestran según la zona horaria del usuario que ve el registro, por lo que el valor se convertirá en la zona horaria local del usuario.

La única manera de crear una propiedad de fecha y hora es usando las API, ya que cualquier propiedad de selector de fechas creada en HubSpot se crea como una propiedad de fecha. Si tu integración debe almacenar horarios específicos, recomendamos crear propiedades de hora personalizadas usando los parámetros de propiedad para los objetos de CRM con los tu integración funcione.


¿Qué debo saber sobre los mensajes de error de API?

A menos que se especifique lo contrario, la mayoría de los puntos finales de HubSpot devolverá una respuesta satisfactoria 200 OK. Cualquier parámetro que regrese a un código de estado diferente especificará la respuesta devuelta en su documentación.

Además, HubSpot tiene varias respuestas de error comunes a múltiples API:

  • 401 Unauthorized: regresa cuando la autentificación proporcionada no es válida. Consulta nuestro Resumen de autentificación para obtener información sobre las solicitudes de autentificación de API.
  • 403 Forbidden: regresa cuando la autentificación proporcionada no tiene los permisos adecuados para acceder a la URL específica. Como ejemplo, un token de OAuth que solo tiene acceso de contenido recibirá 403 cuando accede a la API de Negocios (que requiere acceso a contactos).
  • 429 Too many requests: regresa cuando tu cuenta o aplicación supera los límites de la tasa de API. Encuentra sugerencias para trabajar dentro de esos límites aquí.
  • 502/504 timeouts: HubSpot tiene límites de procesamiento establecidos para evitar que un solo cliente provoque un rendimiento degradado, y estas respuestas indican que se alcanzaron esos límites. Normalmente solo verás estas respuestas de tiempo de espera al realizar una gran cantidad de solicitudes durante un período de tiempo sostenido. Si obtienes una de estas respuestas, deberías pausar tus solicitudes por unos segundos y luego volver a intentarlo.

Además de estos errores generales, las respuestas de error de HubSpot están diseñadas para ser legibles por personas. La mayoría de los puntos finales no devuelven códigos de error, pero devuelven una respuesta con formato JSON con detalles sobre el error. Puedes encontrar más información sobre los errores específicos de puntos finales en las páginas de documentación correspondientes al punto final.

Nota: Los campos de la respuesta del ejemplo a continuación deben ser tratados como opcionales en cualquier error interpretado. Los campos específicos incluidos pueden variar entre diferentes API, por lo tanto, cualquier análisis de errores debería permitir que falten campos específicos en la respuesta.

{"status":"error","message":"This will be a human readable message with details about the error.","errors":[{"message":"This will be a message with additional details about the error","in":"name"}],"category":"VALIDATION_ERROR","correlationId":"a43683b0-5717-4ceb-80b4-104d02915d8c"}

¿Las API de HubSpot admiten solicitudes de HubSpot/AJAX?

En la mayoría de los casos, las API de HubSpot no admiten las solicitudes cruzadas (CORS) AJAX. Hacer la solicitud del lado del cliente usando JavaScript expondría cualquier autenticación que estés usando para la solicitud. Para usar JavaScript/AJAX, deberías hacer la solicitud (excepto cualquier autentificación) a un servidor externo que luego pueda agregar la autentificación necesaria y hacer solicitudes en el lado del servidor de API de HubSpot.

Las excepciones a esta regla son:


¿Cómo valida HubSpot las direcciones de correo electrónico?

HubSpot valida las direcciones de correo electrónico utilizadas para cualquier proceso que crearía o actualizaría un registro de contacto. Esto incluye usar los puntos finales de contactos para crear o actualizar un contacto así como envíos de formularios o eventos.

Estos procesos no comprueban la validez de la dirección de correo electrónico en sí (como un formulario incrustado), sino su formato. Además de ser válida según RFC 2822, ponemos las siguientes restricciones en la dirección de correo electrónico:

  • No permitimos que las partes locales se estén entre comillas (Por ejemplo, "Correo de prueba"@hubspot.com no es válido)
  • La parte del dominio debe terminar en un TLD válido, como se detalla en https://data.iana.org/TLD/tlds-alpha-by-domain.txt (Ten en cuenta que esto se debe a que se trata de un correo electrónico de tipo TLS, por lo que "usuario@email.삼성" es una dirección de correo electrónico válida).
  • Cuando usas la API de formularios v3, se puede ignorar la validación agregando el parámetro skipValidation a la solicitud del cuerpo de la solicitud y configurándola en true.

¿Cómo configuro varios valores para las propiedades de la casilla de comprobación?

Al configurar varios valores para una propiedad de casilla comprobación, los valores deben estar separados con un punto y coma (;).
Ejemplo: 'value1;value2;value5'

Al actualizar un registro a través de los puntos finales de objetos CRM, el valor de la propiedad debería ser una sola cadena con todos los valores separados por punto y coma

{
  "properties":
    {
      "example_property": "value1;value3;value4"
    }
}

Para los puntos finales de Formularios, asegúrate de que los punto y coma también estén codificados:

...&example_property=value1%3Bvalue2%3Bvalue4


¿Hay límites para los registros de contactos?

HubSpot tiene algunos límites con respecto a los registros de contactos combinados y los envíos de formularios para registros de contactos:

  1. Hay un límite de 250 identidades enlazadas por contacto.
    • Si intentas combinar dos contactos y el contacto resultante tendría más de 250 identidades, recibirás un error.
  2. Los contactos se limitan a 1000 envíos de formularios. Los envíos que llevarían a un contacto por encima de este límite se descartarán por completo:
    • Los datos del formulario no actualizarán el registro de contacto.
    • El envío en sí no aparecerá para el registro de contacto, ya sea en los datos de form-submissions de los puntos finales de contactos o en la cronología del contacto.
    • El envío no se evaluará para la membresía de listas o workflows.
    • El envío no aparecerá en la lista de envíos para ver el formulario en HubSpot.

Si excedes cualquiera de estos límites debido a pruebas, recomendamos eliminar los contactos de prueba y crear un nuevo registro de prueba. Usar la misma dirección de correo electrónico en el nuevo contacto no restaurará el contacto eliminado y los envíos de formularios con el correo electrónico se asociarán al nuevo registro.


¿Cómo envío correos electrónicos transaccionales?

HubSpot admite dos métodos de envío de correos electrónicos transaccionales, API SMTP y API de envío individual.

Usar la API SMTP

La API SMTP no envía correos electrónicos directamente, pero solo se utiliza para obtener credenciales de inicio de sesión para el servidor SMTP de HubSpot. Después de obtener un token y contraseña usando la API SMTP, deberás usar esas credenciales para iniciar sesión en el servidor SMTP de HubSpot y enviar el correo electrónico a SMTP. Los detalles de inicio de sesión (nombre del host y puerto) para el servidor SMTP se pueden encontrar en la página de documentación. El correo electrónico y los enlaces estarán envueltos en el seguimiento de correos electrónicos de HubSpot, pero deberás crear la totalidad del contenido del correo electrónico.

Usar la API de envío individual

La API de envío individual usa correos electrónicos de plantillas creados en la herramienta de correo electrónico de HubSpot, junto con un POST con formato JSON para enviar correos electrónicos. Primero, deberás crear un correo electrónico en HubSpot y seleccionar «Guardar para API de envío individual» al elegir el destinatario.  Después de crear el correo electrónico, puedes usar la API para enviar el correo electrónico a un contacto, establecer los detalles del destinatario (incluyendo cualquier contacto o propiedades personalizadas establecidas en el correo electrónico) en el cuerpo de la solicitud de API.  Puedes encontrar más detalles para el formato de esa solicitud JSON en la página de documentación.


¿Cómo puedo suscribirme a las actualizaciones de API?

Las actualizaciones de las API y las herramientas de desarrollador de HubSpot se realizan a través de nuestro Changelog de desarrollador.

Puedes usar el formulario en la izquierda para suscribirte a las actualizaciones. Selecciona Instantánea para obtener notificaciones tan pronto como se anuncien. De lo contrario, selecciona una de las otras frecuencias para obtener un resumen de las actualizaciones en tu frecuencia seleccionada.


¿Cómo puedo abordar la privacidad y el cumplimiento legal cuando trabajo con la plataforma de HubSpot?

Seguimiento de bases legales de procesamiento en HubSpot

Según el RGPD, las empresas necesitan una razón legal para usar y procesar los datos de los contactos y deben mantener registros del consentimiento y presentar pruebas de otros propósitos legales del procesamiento.

La propiedad de contacto Base legal para procesar datos del contacto te permite recopilar, hacer seguimiento y almacenar bases legales de procesamiento mediante contrato, interés legítimo y/o consentimiento para tus contactos de HubSpot.

Cuando accedes a datos de contacto a través de los  puntos finales de contactos, esta propiedad usa el nombre hs_legal_basis. Al igual que con cualquier otra propiedad de contacto, cualquier contacto con esta propiedad establecida sería accesible a través de la API. La propiedad también puede establecerse o actualizarse para los registros de contactos a través de la API.

Sin embargo, las opciones de propiedad no se pueden modificar a través de la API. Solo se pueden actualizar desde HubSpot, pero es posible extraer opciones personalizadas que hayan sido configuradas para la propiedad a través de los puntos finales de las propiedades del contacto. Dado que las cuentas de HubSpot individuales pueden no usar la configuración predeterminada, es recomendable usar estos puntos finales para obtener las opciones de propiedad.

Para obtener más detalles sobre esta propiedad y cómo se puede usar en HubSpot, consulta este
artículo de la base de conocimientos.

Manejo de las eliminaciones de contactos conforme con la privacidad

Los usuarios de HubSpot pueden eliminar permanentemente un registro de contacto para cumplir con las leyes de privacidad. Consulta este artículo de la base de conocimientos para obtener más información.

Puedes suscribirte al tipo de suscripción de contact.privacyDeletion para recibir notificaciones de webhook cuando un usuario realiza una eliminación de contactos conforme con la privacidad. Consulta el resumen de webhooks para obtener más detalles sobre webhooks y manejo de estas notificaciones.