Política de "uso justo" das ferramentas de carregamento em massa de dados (KB040)

Este documento descreve a política de “fair use” das ferramentas de carga massiva de dados como a API e as cargas de dados em bloco conhecidas como KB020, e inclui indicações relativas aos limites da API.

API

A API do Smartosh está desenhada para facilitar a integração e sincronização de dados entre a plataforma Smart OSH e sistemas externos dos clientes. O seu propósito é permitir:

Intercâmbio bidirecional de informação entre sistemas corporativos
Atualização automatizada de dados a partir de fontes externas (ERP, HRIS, sistemas de gestão, etc.)
Consultas pontuais para integração com ferramentas de reporting ou BI
Sincronização de dados com outros sistemas da organização
Automatização de fluxos de trabalho que complementem o uso da plataforma

Uso não previsto

A API não está desenhada nem é oferecida para:

Criar interfaces de utilizador alternativas que substituam significativamente o uso da plataforma web do Smart OSH
Desenvolver aplicações completas que repliquem a funcionalidade principal do Smart OSH
Substituir o acesso normal de utilizadores à plataforma por acesso exclusivo via API
Extrair continuamente toda a base de dados para operar fora do Smart OSH

Princípios Gerais

A API do Smart OSH está disponível para todos os nossos clientes sem um limite estabelecido de consultas ou atualizações, sob o princípio de uso “fair use” dos recursos da plataforma.

Autenticação e gestão de sessões

A autenticação na API do SmartOSH realiza-se mediante HTTP Basic Authentication. Na primeira chamada, o cliente deve autenticar-se utilizando as credenciais de utilizador API. O cliente HTTP guardará o token resultante do HTTP Authentication Challenge e as chamadas subsequentes ficarão autenticadas automaticamente.

As credenciais de acesso (utilizador e palavra-passe) podem ser criadas pelo administrador do SmartOSH a partir da consola de administração da plataforma.

Gestão de sessões

Quando se usar Basic Authentication é necessário que o cliente da API mantenha a sessão entre chamadas. Existem dois métodos equivalentes:

Cookies de sessão: O cliente HTTP mantém automaticamente os cookies recebidos na primeira chamada.
Header x-session: O cliente captura o valor do header x-session recebido na primeira resposta e reenvia-o em todas as chamadas subsequentes.

Se a sessão não for mantida corretamente:

As chamadas serão extremamente lentas
Pode comprometer-se o desempenho da subscrição do cliente
Será atingido o limite de sessões simultâneas

Limite de sessões

A API tem um limite de 50 identificadores de sessão distintos por utilizador por hora. Quando este limite é ultrapassado, o serviço rejeita os pedidos com a mensagem:

“You are using too many sessions. Please make sure that you are reusing your sessions using cookies. For more information please check the reference guide KB008.”

Causas comuns de excesso de sessões:

O mesmo utilizador API está a ser partilhado por vários utilizadores ou sistemas reais
Os identificadores de sessão não estão a ser conservados adequadamente entre chamadas
Não estão a ser reutilizados os cookies de sessão

Recomendações:

Manter a sessão ativa corretamente mediante cookies ou cabeçalhos x-session
Se múltiplos sistemas precisam de acesso simultâneo, distribuir os pedidos entre diferentes utilizadores API
Verificar que o cliente HTTP está configurado para preservar cookies entre chamadas

Uso esperado

Atualizações de dados

A API está desenhada para receber apenas dados que sofreram alterações reais. Os clientes devem:

Enviar atualizações apenas quando a informação tiver efetivamente mudado
Implementar lógica de deteção de alterações antes de realizar chamadas à API
NÃO enviar atualizações reiterativas da mesma informação sem modificações

Limites técnicos de velocidade (Rate Limiting)

Embora não exista um limite rígido de volume total, o Smart OSH implementa controlos de velocidade para garantir a estabilidade do serviço:

Limite máximo: 3.600 pedidos por hora (equivalente a 60 pedidos por minuto)
Chamadas concorrentes: 1. As chamadas em paralelo receberão um status code 429
Mecanismo de proteção: Quando o sistema detecta um ritmo superior a estes valores, ativa automaticamente um mecanismo de throttling que limitará temporariamente os pedidos

Códigos de resposta e gestão de erros

Códigos HTTP relevantes

Código	Significado	Ação requerida
`200 OK`	Pedido bem-sucedido	Continuar normalmente
`400 Bad Request`	Habitualmente “You are using too many sessions”	Ver gestão de sessões
`401 Unauthorized`	Credenciais inválidas ou sessão expirada	Verificar credenciais e reautenticar
`429 Too Many Requests`	Limite de velocidade ultrapassado	Implementar backoff e reintentar
`503 Service Unavailable`	Serviço temporariamente indisponível	Reintentar com estratégia exponencial
`504 / 524 Gateway Timeout`	Timeout por bloqueio de recursos	Reintentar após um intervalo

Manutenção programada

O Smart OSH realiza manutenções periódicas que podem resultar em código 503 Service Unavailable. As janelas de manutenção são notificadas com antecedência. Os clientes devem implementar estratégias de reintento perante códigos 503 para gerir estes períodos sem perda de dados.

Bloqueios por operações concorrentes

A plataforma pode reter ou bloquear temporariamente o acesso a certos dados quando:

Estão a ser executadas operações massivas (importações, processos batch, etc.)
Outros utilizadores estão a realizar operações individuais sobre os mesmos recursos
Existem processos de cálculo intensivos em curso

Durante estes bloqueios a API pode experimentar tempos de resposta mais prolongados ou devolver códigos 503 / 504 / 524. O cliente deve implementar reintentos com intervalos crescentes.

Estratégias de reintento recomendadas

Backoff exponencial com jitter:

Reintento 1: esperar 1–2 segundos
Reintento 2: esperar 2–4 segundos
Reintento 3: esperar 30–60 segundos
Reintento 4: esperar 180–300 segundos

Códigos que requerem reintento: 429, 503, 504, 524, erros de rede/timeout.

Códigos que NÃO devem ser reintentados automaticamente: 400, 401, 403, 404, 422.

Melhores práticas

Consultas em bloco com paginação — Utilizar endpoints de consulta massiva para grandes volumes. Tamanho de página recomendado: 100–500 registos.
Estratégias de backoff — Implementar retrocesso exponencial perante erros ou respostas 429 / >500. Adicionar jitter aleatório para evitar sincronização de reintentos.
Deteção de alterações local — Manter um registo do estado dos dados no sistema cliente. Considerar o uso de timestamps, checksums ou hashes para detetar alterações.
Consolidação de atualizações — Agrupar múltiplas alterações numa só requisição quando a API o permitir. Utilizar operações batch quando disponíveis.
Timeouts apropriados — Ligação: 10–30 segundos. Leitura: 60–100 segundos para operações complexas.

Headers informativos

A API pode incluir os seguintes headers para monitorizar o uso:

x-throttled — Indica se as consultas estão limitadas pelo servidor
x-requestsUserMinCount — Contador de consultas realizadas nos últimos 60 segundos

Horários recomendados

Para operações massivas, evite na medida do possível os horários de pico:

Evitar: 9:00–18:00 (CET)
Preferir: 20:00–7:00 (CET) para cargas massivas
Coordenar com suporte para operações extraordinárias

Cargas massivas mediante Excel (KB020)

Propósito

As ferramentas de carga massiva mediante ficheiros Excel (KB020) estão desenhadas para:

Migrações iniciais de dados ao implementar o SmartOSH
Atualizações massivas pontuais quando existem alterações significativas nos dados
Cargas incrementais de novos registos ou modificações de registos existentes
Correções massivas de dados perante incidências identificadas

Princípio de uso incremental

As cargas mediante KB020 devem seguir um modelo incremental, não de substituição total:

Carregar apenas os registos que mudaram desde a última carga
Incluir só as colunas com valores modificados quando possível
NÃO recarregar massivamente toda a base de dados de forma periódica
NÃO subir ficheiros com dados idênticos aos já existentes na plataforma
NÃO usar KB020 como método habitual de atualização de dados que mudam frequentemente

Impacto das cargas massivas

Tal como com a API, cada carga de dados mediante KB020 desencadeia validações, recálculos automáticos, notificações por email, ativação de fluxos de trabalho e bloqueios temporários de recursos.

As cargas repetitivas de dados sem alterações geram custos computacionais desnecessários, saturam os utilizadores com notificações supérfluas e podem afetar o desempenho geral do ambiente do cliente.

Uso não apropriado de KB020

As ferramentas de carga massiva não devem ser utilizadas para:

Substituir as funcionalidades de atualização de dados disponíveis na interface web
Realizar recargas sistemáticas e periódicas da totalidade dos dados sem modificações efetivas
Atualizar registos cujos valores não sofreram alterações
Constituir o método principal de gestão e manutenção de dados em substituição do uso normal da plataforma

Boas práticas para cargas em lote

Preparação do ficheiro Excel:

Identifique quais registos mudaram realmente desde a última carga
Exporte do SmartOSH o estado atual se precisar de comparar
Inclua apenas os registos modificados ou novos com as suas colunas identificadoras (ID, Key, código único, etc.)

Frequência recomendada:

Migrações iniciais: uma única vez ao implementar
Atualizações normais: só quando houver alterações significativas que o justifiquem
Frequência máxima recomendada: uma carga diária
Para atualizações frequentes, urgentes ou unitárias: utilize a API em vez de KB020

Sinais de uso inadequado:

Cargas diárias ou várias vezes por semana dos mesmos dados
Ficheiros com milhares de registos mas poucas alterações reais
Cargas automáticas programadas sem validação prévia de alterações que gerem muitos erros

Intervenção em casos de uso abusivo

O Smartosh reserva-se o direito de contactar clientes cujo padrão de uso:

Ultrapasse sistematicamente os limites de velocidade estabelecidos
Gere cargas desnecessárias mediante atualizações repetitivas sem alterações
Comprometa o desempenho geral da plataforma
Não implemente estratégias de reintento adequadas

Nestes casos, trabalharemos com o cliente para otimizar a sua integração e garantir um uso sustentável do serviço. O SmartOSH reserva-se o direito de limitar ou restringir o uso da API.

Disponibilidade e SLA

Disponibilidade objetivo: 99,5% (exclui manutenções programadas e bloqueios de dados funcionais do próprio ambiente do cliente)
Suporte técnico: Disponível em horário laboral