Práticas recomendadas

Use estes padrões para manter as integrações de parceiros previsíveis, observáveis e seguras para as instalações.

Identifique as instalações de forma consistente

Escolha o método de vinculação configurado para sua conta de parceiro e use-o de forma consistente:

Direct Link - use o facility_id do Performance Hub retornado pelo endpoint de instalações.
Linking Identifier - use seu próprio identificador de local, como um ID de filial, código de local ou número de loja.

Não envie os dois identificadores na mesma solicitação. O Performance Hub resolve as solicitações usando o método de vinculação configurado para sua conta de parceiro.

Consulte Métodos de vinculação de parceiros para obter orientações de configuração.

Faça gravações em lote com cuidado

A Partner API aceita corpos de solicitação JSON e foi projetada para fluxos de sincronização em lote, onde documentado. Mantenha os lotes limitados e passíveis de nova tentativa.

Orientações padrão:

Use até 1000 itens por solicitação em lote para um desempenho ideal.
Mantenha os payloads abaixo de 10MB.
Respeite o limite de 5 solicitações por segundo por endpoint.

Os limites de taxa são ajustáveis e podem ser configurados caso a caso pelo seu gerente de conta de parceiro do Performance Hub. Se você espera importações de alto volume, tráfego de lançamento ou preenchimentos retroativos de relatórios, combine o volume necessário antes da janela de mudança.

Se você precisar sincronizar um grande conjunto de dados, divida-o em blocos determinísticos e registre o ID de cada bloco do seu lado. Isso facilita a análise de novas tentativas com falha.

Tente novamente com segurança

Use recuo exponencial para falhas transitórias, como 429, 500, 502, 503 e 504.

Evite loops de repetição rápidos. Um bom ponto de partida é:

Tentar novamente após 1 segundo.
Tentar novamente após 2 segundos.
Tentar novamente após 4 segundos.
Parar e emitir um alerta se a operação ainda falhar.

Para falhas de validação, como 400 ou 422, corrija a solicitação antes de tentar novamente.

Use idempotência onde houver suporte

O endpoint de destravamento do Door/Gate Controller aceita um idempotency_key opcional. Reutilizar a mesma chave para o mesmo parceiro, instalação e porta retorna o resultado existente, quando houver um.

Use uma chave estável para a ação que está sendo realizada, por exemplo, um ID de check-in ou um ID de evento de acesso do seu sistema.

Não presuma que todos os endpoints de gravação oferecem suporte a idempotência, a menos que isso esteja documentado para o endpoint.

Mantenha os dados de origem limpos

Envie valores estáveis e normalizados sempre que possível:

Use IDs consistentes de membros, planos, instalações e check-ins do seu sistema de origem.
Use carimbos de data/hora ISO 8601 para datas e horários.
Envie números de telefone em formato internacional, quando disponíveis.
Envie moedas usando os campos documentados para cada endpoint.
Evite sobrecarregar campos de texto livre com dados que pertencem a campos estruturados.

Projete para sincronizações incrementais e completas

A maioria das integrações de parceiros precisa das duas:

Sincronizações incrementais para as mudanças do dia a dia.
Sincronizações completas de reconciliação para corrigir eventos perdidos, importações históricas ou divergências de dados.

Sua integração deve ser capaz de reenviar o estado atual de um membro, plano de associação ou snapshot de relatório sem depender do sucesso de uma solicitação anterior.

Publique Access Time Windows com segurança

Trate o valor access_time_windows de cada membro como um snapshot completo, com revisão independente:

Coordene um único fluxo monotonicamente crescente de access_time_windows_revision entre os workers incrementais e de reconciliação.
Repita uma entrega incerta ou transitória com a mesma revisão e o mesmo payload normalizado.
Omita access_time_windows quando não estiver atualizando esse valor.
Envie [] somente depois que uma consulta bem-sucedida à fonte oficial comprovar que não resta nenhuma janela. Nunca transforme um tempo limite, um resultado parcial ou uma falha de análise na origem em revogação.
Mantenha external_id e scope_key estáveis e certifique cada mapeamento de escopo antes da produção.
Monitore a idade dos dados de origem em relação à política de atualização acordada para essa integração.

Consulte o guia oficial para produtores de Access Time Windows para ver snapshots completos, fusos horários, horário de verão, cancelamento e vetores de teste.

Trate o controle de acesso como crítico para a segurança

Para destravamentos do Door/Gate Controller:

Seu sistema deve decidir se a pessoa tem permissão para entrar antes de chamar o Performance Hub.
O Performance Hub retorna 200 somente depois que o controlador local confirma que o relé foi fisicamente destravado.
A maioria das confirmações é concluída em 3-5 segundos.
Um tempo limite é uma falha explícita de destravamento, não um sucesso em segundo plano.
Tente novamente somente de acordo com as suas próprias regras de acesso e segurança.

Sempre registre o event_id e o command_id retornados pelo endpoint de destravamento.

Monitore sua integração

Use os logs de solicitações do Partner Console durante o desenvolvimento e o lançamento. Em produção, mantenha também seus próprios logs com:

Data e hora da solicitação.
Endpoint.
ID do registro de origem.
Identificador da instalação.
Código de status HTTP.
Corpo da resposta ou mensagem de erro do Performance Hub.

Esses campos tornam o suporte e a reconciliação muito mais rápidos quando um cliente pergunta o que aconteceu.