Perguntas frequentes

Veja as respostas a perguntas frequentes sobre APIs da HubSpot. Para perguntas de desenvolvimento do CMS, acesse a documentação. Se não conseguir encontrar o que procura, você pode perguntar no nosso fórum do desenvolvedor

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?

As APIs da HubSpot aceitam dois formatos diferentes para valores de data e hora.

O primeiro formato é cadeias de caracteres formatada em 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: AAAA-MM-DD (por exemplo, 2020-02-29)
  • Para valores que representam uma data e hora específica, a data completa mais horas, minutos, segundos e uma fração decimal de um segundo formato será usada: AAAA-mm-DubT:b:ss.sTZD (por exemplo, 2020-02-29T-03:30:17,000Z). Observe que todos os horários serão representados em UTC, então os valores sempre usarão o designador de UTC "Z".

O segundo formato é data/hora formatado em UNIC em milissegundos. Os valores de data/hora serão tratados como se estivessem definidos em horário UTC. Por exemplo, o valor da data/hora 1427997766000 é traduzido como 2 de abril de 2015, 14:02:46 EDT (Horário de Verão do Leste) ou 02 Abr 2015 18:02:46 UTC.

Os valores de tempo serão representados com o valor ISO 8601 nas respostas, mas as APIs aceitarão ambos os formatos.

Propriedades de data e data/hora no CRM do HubSpot

O HubSpot tem dois tipos de propriedades de objeto de CRM para data de armazenamento: data e hora.

As propriedades de data (incluindo propriedades de seletor de data criadas na HubSpot) podem armazenar apenas a data. Ao definir valores de propriedade de data, recomendamos usar o formato de data completa ISO 8601.

Exemplos:

  • 2015-05-01 seria usado para 1º de maio de 2015. Embora seja possível usar uma data/hora em milissegundos, os valores precisam ser definidos como meia-noite UTC da data desejada. 
  • 1430438400.000 seria usado para 1º de maio de 2015 (01 de maio de 2015 0:00:00 UTC).

Se você tentar definir um valor que não seja meia-noite UTC, você receberá um erro. No HubSpot, as propriedades de data sempre exibem a data específica a qual elas estão definidas, seja qual for a configuração do fuso horário da conta ou usuário.

As propriedades de data/hora podem armazenar qualquer horário, portanto, qualquer data ou hora válida que use um formato será aceita. No HubSpot, as propriedades de data/hora são exibidas com base no fuso horário do usuário que vê o registro, portanto o valor será convertido no fuso horário local do usuário.

A única maneira de criar uma propriedade de data e hora é usar as APIs, pois a propriedade de seletor de data criada no HubSpot é criada como uma propriedade de data. Se sua integração precisar armazenar horários específicos, recomendamos criar propriedades de data/hora personalizadas usando os endpoints da propriedade para os objetos de CRM com os quais sua integração trabalhe.


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, disponibilizamos as seguintes restrições nos endereços de e-mail:

  • Não permitimos que as partes locais sejam consultadas (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).
  • Ao usar a API v3 Forms, a validação pode ser ignorada adicionando-se o parâmetro skipValidation ao corpo da solicitação e configurando-o como true.

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?

Rastreamento jurídico de processamento 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 do 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.