API Senior Sistemas: endpoints, limitações e casos práticos
Por Alexandre Pereira · · 3 min de leitura
A API Senior Sistemas oferece acesso programático aos principais módulos do ERP, mas conhecer seus endpoints e limitações técnicas evita frustrações em projetos de integração. Uma metalúrgica capixaba com 120 funcionários economizou 15 horas semanais automatizando a extração de holerites via API, mas só depois de entender as nuances do throttling e paginação.
A documentação oficial mapeia três grupos principais de endpoints: gestão de pessoas (folha, ponto, benefícios), ERP corporativo (vendas, compras, estoque) e financeiro (contas a pagar, receber, fluxo de caixa). Cada grupo tem particularidades de autenticação e estrutura de resposta.
Quais endpoints mais usamos na prática?
Os endpoints de folha de pagamento (/payroll) e gestão de pessoas (/hr) lideram em volume de uso. Uma distribuidora em Vitória processa 200 holerites mensais via GET /payroll/payslips, reduzindo de 4 horas para 8 minutos o envio por WhatsApp Business API usando n8n.
Para vendas, os endpoints /sales/orders (criação) e /sales/customers (sincronização de cadastro) são essenciais. O POST /sales/orders aceita estrutura JSON completa com itens, mas rejeita pedidos sem validação de estoque quando o parâmetro check_inventory=true.
O módulo financeiro via /financial permite extrair relatórios de DRE e fluxo de caixa, mas com limite de 90 dias por consulta. Períodos maiores exigem múltiplas requisições com paginação manual.
Por que a autenticação OAuth2 complica?
A API Senior usa OAuth2 com refresh tokens que expiram em 24 horas, forçando renovação constante. Diferente do TOTVS Protheus que aceita token fixo, o Senior invalida credenciais antigas automaticamente. Uma rede varejista com 5 lojas perdeu 2 dias de sincronização por não implementar renovação automática.
O throttling limita 100 requisições por minuto por cliente, mas esse limite se aplica globalmente, não por endpoint. Extrair 500 holerites simultâneos estoura facilmente, retornando HTTP 429. A solução é implementar fila com delay de 600ms entre chamadas.
Headers obrigatórios incluem Content-Type: application/json, Authorization: Bearer {token} e X-Senior-Domain para ambientes multi-tenant. Esquecer o domínio retorna 403 mesmo com token válido.
Quando usar cache local?
Cadastros de clientes, fornecedores e produtos mudam pouco, justificando cache de 6 horas. Uma indústria alimentícia em Serra reduziu 70% das chamadas API cachando o endpoint /erp/customers em banco local Supabase.
Dados transacionais como vendas, estoque e movimentação financeira precisam de sincronização quase real-time. O webhook /events/notifications avisa mudanças, mas só funciona para alguns módulos. Para outros, polling a cada 5 minutos via GET com parâmetro modified_since resolve.
Relatórios pesados como balancete e DRE devem ser processados assincronamente. O endpoint POST /reports/generate retorna job_id para consulta posterior via GET /reports/status/{job_id}, evitando timeout.
Erros comuns incluem não paginar resultados grandes (limite 50 por página), usar campos deprecated sem migração e não tratar HTTP 502/503 que o Senior retorna em manutenções programadas. Cache inteligente e retry exponencial são obrigatórios para produção robusta.