¿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?

Los valores de hora se representan en formato ISO 8601 en las respuestas, pero las API aceptarán cualquiera de dos formatos para los valores de fecha y hora:
  • 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 fecha y hora específicos, se usará un formato de fecha completo 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). Todas las horas se representan en UTC, por lo que los valores siempre usarán el designador UTC «Z».
  • Marcas de tiempo con formato Unix en milisegundos: valores de marca de tiempo en milisegundos, que se representan en tiempo UTC. Por ejemplo, el valor de la marca de tiempo 1427997766000 se traduce al al 02 de abril de 2015 a las 18:02:46 UTC o al 2 de abril de 2015 a las 2:02:46 p. m. EDT (horario de verano del este).

Propiedades de fecha y fecha y hora en el HubSpot CRM

HubSpot tiene dos tipos de propiedades de objetos de CRM para almacenar tiempo: date y datetime.

  • Las propiedades de fecha (incluidas las propiedades del date picker creadas en HubSpot) almacenan la fecha, no la hora. Las propiedades de date muestran la fecha en la que están configuradas, independientemente de la configuración de zona horaria de la cuenta o el usuario. Para los valores de propiedad date, se recomienda utilizar el formato de fecha completa ISO 8601. Si utilizas el formato de marca de tiempo Unix, debes utilizar una marca de tiempo de milisegundos EPOCH (es decir, el valor debe establecerse en medianoche UTC para la fecha). Por ejemplo, para representar el 1 de mayo de 2015 en cualquiera de los dos formatos:
    • IOS 8601: 2015-05-01
    • Marca de tiempo de milisegundos EPOCH: 1430438400000

Nota: si utilizas una marca de tiempo Unix para una propiedad date e intentas establecer un valor que no sea medianoche UTC, recibirás un error.

  • Las propiedades datetime almacenan tanto la fecha como la hora. Se aceptará cualquiera de estos formatos de marca de tiempo. En HubSpot, las propiedades de datetime 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. Debido a que las propiedades date picker creadas en HubSpot se crean como propiedades de date, la única forma de crear una propiedad datetime es a través de la API. Si tu integración necesita almacenar horas específicas, puedes crear propiedades datetime personalizadas utilizando los puntos de conexión de la propiedad.

¿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 al analizar. 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, HubSpot pone las siguientes restricciones en la dirección de correo electrónico:

  • Las partes locales de la dirección no pueden incluir 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).

¿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 la base legal del 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 jurídica para el tratamiento de 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.

¿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.