Como posso manipular formulários com jQuery?

Ao manipular valores de entrada de formulário usando .val() ou .prop(), você precisa acionar um evento de mudança usando change()  ou  trigger('change') para a alteração ser registrada corretamente.

Como os formulários do HubSpot são renderizados depois da criação do DOM, você precisa disparar a manipulação após o carregamento da janela ou modificar a incorporação para usar o 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(); } });

Como posso formatar a data/hora para APIs da HubSpot?

Os valores de hora são representados no formato ISO 8601 nas respostas, mas as APIs aceitarão um dos dois formatos para valores de data e hora:
  • Strings com formatação ISO 8601: dependendo do tipo de dados, elas terão um destes dois formatos:
    • Para valores que representam uma data específica, o formato de data completo será usado: YYYY-MM-DD (por exemplo, 2020-02-29)
    • Para valores que representam uma data e hora específica, a data completa mais as horas, os minutos, os segundos e uma fração decimal de um segundo formato será usada: YYYY-MM-DDThh:mm:ss.sTZD (por exemplo: 2020-02-29T03:30:17.000Z). Todos os horários serão representados em UTC, então os valores sempre usarão o designador de UTC "Z".
  • Data/hora em formato UNIX em milissegundos: valores de data/hora em milissegundos, que são representados em UTC. Por exemplo, o valor de data/hora 1427997766000 é traduzido como 2 de abril de 2015, 18:02:46 UTC ou 2 Abr 2015, 2:02:46 PM EDT (Horário de Verão do Leste).

Propriedades de data e data/hora no CRM do HubSpot

O HubSpot tem dois tipos de propriedades de objeto do CRM para armazenar a hora: date e datetime.

  • As propriedades date (incluindo as propriedades date picker criadas no HubSpot) armazenam a data,não a hora. As propriedades date exibem a data definida, independentemente da configuração de fuso horário da conta ou do usuário. Para valores de propriedade date, recomenda-se usar o formato de data completo ISO 8601. Se você usar o formato de data/hora UNIX, deverá usar uma data/hora em milissegundos de Era (ou seja, o valor deve ser definido como meia-noite UTC para a data). Por exemplo, para representar 1° de maio de 2015 em qualquer formato:
    • IOS 8601: 2015-05-01
    • EPOCH-millisecond timestamp: 1430438400000

Observação: se você usar uma data/hora UNIX para uma propriedade date e tentar definir um valor que não seja meia-noite UTC, receberá um erro.

  • As propriedades datetime armazenam a data e a hora. Qualquer formato de data/hora será aceito. No HubSpot, as propriedades datetime são exibidas com base no fuso horário do usuário que vê o registro; portanto, o valor será convertido para o fuso horário local do usuário. Como as propriedades date picker criadas no HubSpot são criadas como propriedades date, a única maneira de criar uma propriedade datetime é via API. Se a integração precisar armazenar horas específicas, você poderá criar propriedades datetime personalizadas usando os endpoints de propriedade.

O que preciso saber sobre mensagens de erro de API?

A menos que especificado de outra forma, a maioria dos endpoints do HubSpot retornará uma resposta 200 OK após o sucesso. Todos os endpoints que retornaram um código de status diferente especificarão a resposta retornada na sua documentação.

Além disso, o HubSpot tem várias respostas de erros comuns a várias APIs:

  • 401 Não autorizado - retornado quando a autenticação fornecida é inválida. Veja nossa Visão geral de autenticação para obter detalhes sobre as solicitações de API autenticadas.
  • 403 Proibido - retornado quando a autenticação fornecida não tem as permissões adequadas para acessar o URL específico. Como exemplo, um token de OAuth que só tem acesso de conteúdo receberá um 403 ao acessar a API Negócios (que exige acesso de contatos).
  • 429 Solicitações demais - retornando quando a conta ou o aplicativo está acima de seus limites de taxa de API. Encontre sugestões em trabalhar dentro desses limites aqui.
  • 502/504 Tempo limite - o HubSpot tem limites de processamento em vigor para impedir que um único cliente cause redução de desempenho, e essas respostas indicam que esses limites foram atingidos. Você normalmente verá essas respostas de tempo limite ao fazer um grande número de solicitações ao longo de um período prolongado. Se você receber uma dessas respostas, você deve pausar suas solicitações por alguns segundos e tentar novamente.

Além desses erros gerais, as respostas de erro do HubSpot são projetadas para compreensíveis aos usuários. A maioria dos endpoints não retorna códigos de erro, mas uma resposta de JSON formatada com detalhes sobre o erro. Mais detalhes para erros específicos de endpoint podem ser encontrados nas páginas de documentação para o final.

Observação: os campos no exemplo de resposta abaixo devem ser tratados como opcionais em qualquer análise de erro. Os campos específicos incluídos podem variar entre APIs diferentes, portanto qualquer análise de erro deve possibilitar que os campos específicos estejam ausentes da resposta.

{"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"}

As APIs da HubSpot é compatível com solicitações CORS/ AJAX?

Geralmente, as APIs da HubSpot não permitem solicitações AJAX (CORS) entre origens. Fazer a solicitação do lado do cliente usando JavaScript poderia expor qualquer autenticação que você esteja usando para a solicitação. Para usar JavaScript/AJAX, você precisará fazer a solicitação (excluindo qualquer autenticação) para um servidor externo que possa adicionar a autenticação necessária e fazer solicitações ao lado do servidor de APIs da HubSpot.

As exceções para esta regra são:

Como o HubSpot valida endereços de e-mail?

O HubSpot valida endereços de e-mail usados para qualquer processo que criaria ou atualizaria um registro de contato. Isso inclui usar os endpoints de contato para criar ou atualizar um contato, além de envios de formulário ou eventos.

Esses processos não verificam o endereço de e-mail quanto à validade (como um formulário incorporado faria), mas quanto ao formato. Além de ser válida de acordo com o RFC 2822, a HubSpot impõe as seguintes restrições aos endereços de e-mail:

  • Partes locais do endereço não podem incluir aspas. (por exemplo, "Test Email"@hubspot.com não é válido)
  • A parte do domínio precisa terminar em um TLD válido, como listado em https://data.iana.org/TLD/tlds-alpha-by-domain.txt (observe que isso é depois de lidar com TLDs unicode, então "user@email.삼성" é um endereço de e-mail válido).

Como posso definir vários valores para propriedades de caixa de seleção?

Ao definir vários valores para uma propriedade de caixa de seleção, os valores devem ser separados por ponto e vírgula (;).
Exemplo: 'value1;value2;value5'

Ao atualizar um registro pode meio dos endpoints do objeto do CRM, o valor da propriedade deve ser uma única cadeia de caracteres com todos os valores separados por ponto e vírgula:

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

Para os endpoints de formulários, verifique se os pontos e vírgulas também são codificados em URL:

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

Há limites em registros do contato?

O HubSpot tem alguns limites em vigor em relação aos registros de contatos mesclados e envios de formulário para registros de contato:

  1. Há um limite de 250 identidades vinculadas por contato.
    • Se, ao tentar mesclar dois contatos, o contato resultante tiver mais de 250 identidades, você receberá um erro.
  2. Os contatos são limitados a 1.000 envios de formulário. Envios que fariam o contato ultrapassar esse limite serão ignorados completamente:
    • Os dados do formulário não atualizarão o registro do contato.
    • O envio em si não será exibido para o registro do contato, seja nos dados de envios de formulário dos endpoints dos contatos ou na linha do tempo do contato.
    • O envio não será avaliado quanto a associação ou fluxos de trabalho da lista.
    • O envio não aparecerá na lista de envios para visualizar o formulário no HubSpot.

Se você estiver acima desses limites devido ao teste, recomendamos excluir os contatos de teste e criar um novo registro de teste. Usar o mesmo endereço de e-mail no novo contato não restaura o contato excluído e todos os envios de formulário com o e-mail serão associados ao novo registro.

Como posso enviar e-mails transacionais?

O HubSpot permite dois métodos de envio de e-mails transacionais: a API SMTP e a API de envio único.

Usar a API SMTP

A API SMTP não envia e-mails diretamente. Ela é usada apenas para obter credenciais de login para o servidor SMTP da HubSpot. Depois de obter um token e senha usando a SMTP API, você precisará usar essas credenciais para fazer login no servidor SMTP da HubSpot e enviar o e-mail pelo SMTP. Os detalhes do login (o nome e a porta) do servidor SMTP podem ser encontrados na página de documentação. O e-mail e links serão embalados para permitir rastreamento de e-mail do HubSpot, mas, você precisará criar a integridade do conteúdo do e-mail.

Usando a API de envio único

A API de envio único usa e-mails de modelo criados na ferramenta de e-mail do HubSpot, com uma API POST formatada de JSON para enviar e-mails. Primeiro, você precisará criar um e-mail no HubSpot e selecionar “Salvar para API de envio único” ao escolher o destinatário.  Depois que o e-mail for criado, você pode usar a API para enviar o e-mail a um contato, definir os detalhes do destinatário (incluindo qualquer contato ou propriedades personalizadas definida no e-mail) no corpo da solicitação da API.  Mais detalhes para o formato dessa solicitação JSON podem ser encontrados na página de documentação.

Como posso assinar atualizações de API?

Atualizações para as ferramentas de APIs e de desenvolvedor do HubSpot são feitas por meio do nosso log de alterações do desenvolvedor.

Você pode usar o formulário à esquerda para assinar as atualizações. Selecione Instantâneo como frequência para obter notificações assim que forem anunciadas. Caso contrário, selecione uma das outras frequências para obter um resumo das atualizações na frequência escolhida.

Como posso lidar com a privacidade e conformidade legal ao trabalhar com a plataforma HubSpot?

Rastrear a base jurídica para processar dados no HubSpot

De acordo com o GDPR, as empresas precisam de um motivo lícito para usar e processar os dados de contato e devem manter registros de consentimento e evidências de outros propósitos lícitos do processamento.

A propriedade de contato Base jurídica do processamento de dados do contato permite coletar, acompanhar e armazenar as bases lícitas de processamento através do contrato, interesse legítimo e/ou consentimento dos seus contatos do HubSpot.

Ao acessar dados de contato pelos endpoints dos contatos, essa propriedade usa o nome hs_legal_basis. Como qualquer outra propriedade do contato, qualquer contato com essa propriedade definida seria acessível pela API. A propriedade também pode ser definida ou atualizada para registros de contatos pela API.

No entanto, as opções de propriedade não podem ser alteradas através da API. Elas só podem ser atualizados de dentro da HubSpot, mas é possível extrair as opções personalizadas que possam ter sido definidas para a propriedade pelos endpoints de propriedade. Como as contas individuais da HubSpot podem não usar as configurações padrão, recomendamos usar esses pontos para obter as opções de propriedade.

Para obter mais detalhes sobre essa propriedade e como ela pode ser usado no HubSpot, consulte este
artigo da base de conhecimento.

Lidando com exclusões de contatos em conformidade com a privacidade

Usuários do HubSpot podem excluir permanentemente um registro de contato para cumprir as leis de privacidade. Consulte este artigo da Central de Conhecimento para mais informações.

Você pode se inscrever no tipo de assinatura contact.privacyDeletion para receber notificações de Webhook quando um usuário realizar a exclusão de um contato em conformidade com a privacidade. Consulte Visão geral de webhooks para mais informações sobre webhooks e como tratar essas notificações.

Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..