Opzio — API Reference

Autenticação

Auth

POST /api/auth/login Autenticar usuário

Body (JSON)

Campo	Tipo	Descrição
usuario	string	Login do usuário obrigatório
senha	string	Senha do usuário obrigatório

Exemplo de Request

POST /api/auth/login Content-Type: application/json { "usuario": "admin", "senha": "123456" }

Resposta 200

{ "ok": true, "usuario": { "id": "1", "nome": "Administrador", "perfil": "atendente" } }

Resposta 401

{ "erro": "Usuário ou senha incorretos" }

POST /api/auth/logout Encerrar sessão

Resposta 200

{ "ok": true }

Agenda

Agenda Técnica

Consulta a agenda de OS diretamente do ERP, agrupada por técnico. Fonte de verdade para o painel e o app do técnico.

GET /api/agenda Buscar agenda por data

Query Parameters

Parâmetro	Tipo	Descrição
data	string	Data única no formato YYYY-MM-DD opcional
inicio	string	Data inicial do período YYYY-MM-DD opcional
fim	string	Data final do período YYYY-MM-DD opcional

Exemplo de Request

GET /api/agenda?data=2026-07-21 GET /api/agenda?inicio=2026-07-21&fim=2026-07-25

Resposta 200

{ "tecnicos": [ { "tecnicoId": "234", "tecnicoNome": "Bruno", "diasOS": { "2026-07-21": [ { "osId": "12345", "clienteNome": "João Silva", "tipoOS": "Suporte Técnico", "status": "aguardando", "prioridade": "alta", "horaAgendada": "08:00", "dataAgendada": "2026-07-21", "lat": -23.8734, "lng": -46.7291, "clienteTelefone": "11999990000", "clienteEndereco": "Rua Exemplo, 123" } ] } } ], "total": 12, "fonte": "sgp" }

Ordens de Serviço

Atribuições de OS

Listagem e atribuição de ordens de serviço a técnicos.

GET /api/atribuicoes Listar OS atribuídas

Query Parameters

Parâmetro	Tipo	Descrição
tecnicoId	string	Filtrar por técnico opcional
apenasHoje	"1"	Retornar apenas OS do dia opcional
todos	"1"	Incluir todos os status opcional
comBaixas	"1"	Incluir OS concluídas opcional

Exemplo de Request

GET /api/atribuicoes?tecnicoId=234 GET /api/atribuicoes?apenasHoje=1

POST /api/atribuicoes Atribuir OS a técnico

Body (JSON)

Campo	Tipo	Descrição
osId	string	ID da OS no ERP obrigatório
tecnicoId	string	ID do técnico obrigatório
tecnicoNome	string	Nome do técnico obrigatório
clienteNome	string	Nome do cliente opcional
tipoOS	string	Tipo da OS opcional
dataAgendada	string	Data agendada YYYY-MM-DD opcional

Resposta 200

{ "ok": true, "osId": "12345" }

Ordens de Serviço

Atualizar OS no ERP

Atualiza campos de uma OS diretamente no ERP via API REST.

POST /api/sgp/os-update Atualizar campos de uma OS

Body (JSON)

Campo	Tipo	Descrição
osId	string	ID da OS obrigatório
os_prioridade	number	1=Alta · 2=Normal · 3=Baixa opcional
status	string	Novo status da OS opcional

Exemplo

{ "osId": "12345", "os_prioridade": 1 }

Resposta 200

{ "ok": true, "status": 200 }

Técnico

Finalizar OS

Encerra uma OS no ERP e registra o serviço realizado, com suporte a upload de fotos.

POST /api/tecnico/finalizar-os Encerrar OS com relato e fotos

Body (JSON)

Campo	Tipo	Descrição
osId	string	ID da OS obrigatório
relato	string	Descrição do serviço realizado obrigatório
fotos	string[]	Array de imagens em base64 opcional
tecnicoId	string	ID do técnico opcional

Resposta 200

{ "ok": true, "mensagem": "OS encerrada com sucesso" }

Alertas

Massiva de Rede

Detecção e gestão de falhas em massa. Quando detectada, notifica automaticamente os clientes afetados via WhatsApp.

GET /api/massiva-rede Listar alertas ativos

Executa a detecção automática e retorna todos os grupos de massiva ativos.

Resposta 200

{ "grupos": [ { "id": "CASA_GRANDE_1721512345", "chave": "CASA GRANDE|S1/P3", "pop": "CASA GRANDE", "oltNome": "OLT-PRINCIPAL", "osIds": ["111", "112", "113"], "clientes": ["João", "Maria", "Pedro"], "detectadoEm": "2026-07-21T14:30:00.000Z", "status": "novo", "osAtivas": 3 } ], "total": 1 }

POST /api/massiva-rede Ação sobre alerta

Body (JSON)

Campo	Tipo	Descrição
action	string	"confirmar" · "dispersar" · "atualizar" obrigatório
grupoId	string	ID do grupo de massiva obrigatório

Actions disponíveis

Action	Efeito
confirmar	Atribui todas as OS ao técnico responsável por massiva
dispersar	Libera as OS de volta para a fila de distribuição normal
atualizar	Re-executa a detecção e atualiza a lista

Técnico

Dados do Técnico

Informações de OS específica incluindo dados do cliente no ERP.

GET /api/tecnico/info-sgp/:osId Dados completos de uma OS

Path Parameter

Parâmetro	Tipo	Descrição
osId	string	ID da OS obrigatório

Exemplo

GET /api/tecnico/info-sgp/12345

Técnico

Localização do Técnico

POST /api/tecnico/localizacao Registrar posição do técnico

Body (JSON)

Campo	Tipo	Descrição
tecnicoId	string	ID do técnico obrigatório
lat	number	Latitude obrigatório
lng	number	Longitude obrigatório

Resposta 200

{ "ok": true }

Técnico

Controle de KM

GET /api/tecnico/km Consultar KM registrado

Query Parameters

Parâmetro	Tipo	Descrição
tecnicoId	string	Filtrar por técnico opcional
data	string	Data YYYY-MM-DD opcional

POST /api/tecnico/km Registrar KM do dia

Body (JSON)

Campo	Tipo	Descrição
tecnicoId	string	ID do técnico obrigatório
kmInicial	number	KM inicial do dia obrigatório
kmFinal	number	KM final do dia opcional
data	string	Data YYYY-MM-DD obrigatório

Gestão

Áreas de Cobertura

GET /api/areas Listar áreas cadastradas

Resposta 200

{ "areas": [ { "id": "area_1", "nome": "Jardim Casa Grande", "tecnicoId": "234", "cor": "#3B82F6", "poligono": [[-23.87, -46.72], ...] } ] }

POST /api/areas Salvar áreas de cobertura

Body (JSON)

Campo	Tipo	Descrição
areas	array	Array completo de áreas obrigatório

Gestão

Frota de Veículos

GET /api/veiculos Listar veículos cadastrados

Resposta 200

{ "veiculos": [ { "id": "v1", "placa": "ABC1D23", "modelo": "Fiat Strada", "tecnicoId": "234" } ] }

POST /api/veiculos Salvar veículos

Body (JSON)

Campo	Tipo	Descrição
veiculos	array	Array completo de veículos obrigatório

Sistema

Status do Sistema

GET /api/sistema/status Health check do sistema

Verifica se o sistema está operacional. Útil para monitoramento.

Resposta 200

{ "ok": true, "versao": "1.0", "timestamp": "2026-07-21T14:30:00.000Z" }

Alertas

Monitor PON — Detecção Proativa

Monitora ONUs online/offline por PON via API FTTX do ERP. Detecta quedas de rede automaticamente antes de qualquer chamado de cliente. Chamado pelo cron a cada 5 minutos.

POST /api/massiva-rede/monitor Executar varredura de PONs

Consulta todas as OLTs ativas, conta ONUs online/offline por PON e compara com snapshot anterior. Cria alerta de massiva automaticamente se detectar queda ≥ 4 ONUs e ≥ 35% de queda relativa. Também detecta OLTs inacessíveis (queda total).

Resposta 200 — sem alertas

{ "ok": true, "olts": 3, "alertas": 0, "detalhes": [], "duracaoMs": 1240 }

Resposta 200 — com alerta detectado

{ "ok": true, "olts": 3, "alertas": 1, "detalhes": ["OLT-PRINCIPAL S1/P3: 12→4 online (8 offline)"], "duracaoMs": 1890 }

Limiares de detecção:
• Queda absoluta ≥ 4 ONUs offline
• Queda relativa ≥ 35% do baseline
• Baseline mínimo: 3 ONUs online no snapshot anterior
• Cooldown: 30 min por PON (evita alertas repetidos)
• OLT inacessível → todas ONUs do snapshot contam como offline

GET /api/massiva-rede/monitor Consultar último snapshot de PONs

Retorna o snapshot mais recente de todas as PONs monitoradas, ordenado por quantidade de ONUs offline. Útil para debug e auditoria.

Resposta 200

{ "geradoEm": "2026-08-10T15:30:00.000Z", "totalPons": 24, "topOffline": [ { "chave": "100122:1:3", "online": 4, "offline": 8, "total": 12, "ts": "2026-08-10T15:30:00.000Z" } ] }

Chave do snapshot: "oltId:slot:pon" — ex: "100122:1:3"

Estoque

Estoque & Equipamentos

Controle de estoque de equipamentos (ONUs, cabos, splitters). Monitoramento de saldo e movimentações.

GET /api/estoque Listar itens em estoque

Query Parameters

Parâmetro	Tipo	Descrição
categoria	string	Filtrar por categoria opcional
tecnicoId	string	Estoque de um técnico específico opcional

Resposta 200

{ "itens": [ { "id": "1", "nome": "ONU GPON AN5506", "categoria": "onu", "quantidade": 12, "serial": "ZTEG12345678", "tecnicoId": "234" } ], "total": 1 }

POST /api/estoque Registrar entrada ou saída

Body (JSON)

Campo	Tipo	Descrição
action	string	"entrada" · "saida" · "transferir" obrigatório
itemId	string	ID do item opcional — cria novo se omitido
nome	string	Nome do item opcional
quantidade	number	Quantidade a movimentar obrigatório
tecnicoId	string	Técnico origem/destino opcional
serial	string	Número de série opcional

Resposta 200

{ "ok": true, "itemId": "1", "saldoAtual": 10 }

GET /api/estoque/monitoramento Monitorar ONUs por serial

Cruza o estoque de ONUs com o status online/offline no ERP FTTX. Identifica ONUs instaladas que estão offline.

Resposta 200

{ "monitoramento": [ { "serial": "ZTEG12345678", "status": "offline", "ultimoOnline": "2026-08-10T22:00:00.000Z" } ] }

Rastreador GPS

Rastreamento de Veículos

Rastreamento GPS em tempo real de veículos da frota. Histórico de rotas, cercas eletrônicas e alertas de saída de área.

GET /api/rastreador/lista Posição atual de todos os veículos

Resposta 200

{ "veiculos": [ { "id": "v1", "placa": "ABC1D23", "tecnicoNome": "Bruno", "lat": -23.873, "lng": -46.729, "velocidade": 42, "atualizadoEm": "2026-08-11T10:30:00.000Z" } ] }

POST /api/rastreador Registrar posição do veículo

Body (JSON)

Campo	Tipo	Descrição
veiculoId	string	ID do veículo obrigatório
lat	number	Latitude obrigatório
lng	number	Longitude obrigatório
velocidade	number	Velocidade em km/h opcional
ignicao	boolean	Estado da ignição opcional

GET /api/rastreador/historico Histórico de rota de um veículo

Query Parameters

Parâmetro	Tipo	Descrição
veiculoId	string	ID do veículo obrigatório
data	string	Data YYYY-MM-DD opcional — padrão: hoje

GET /api/rastreador/cercas Listar cercas eletrônicas

Retorna os polígonos de cercas eletrônicas cadastrados. Quando um veículo sai de uma cerca, é gerado um alerta automático.

Resposta 200

{ "cercas": [ { "id": "c1", "nome": "Área de Operação SP", "poligono": [[-23.87, -46.72], ...], "ativa": true } ] }

GET /api/rastreador/alertas Alertas de cerca e velocidade

Lista alertas gerados: saída de cerca eletrônica, excesso de velocidade ou ignição fora de horário.

Query Parameters

Parâmetro	Tipo	Descrição
lido	"0"·"1"	Filtrar por lido/não lido opcional
veiculoId	string	Filtrar por veículo opcional

ONU / FTTX

Gestão de ONUs

Integração com o módulo FTTX do ERP para busca, autorização e gestão de ONUs na rede óptica.

POST /api/sgp/onu/buscar Buscar ONU por serial ou MAC

Body (JSON)

Campo	Tipo	Descrição
serial	string	Serial da ONU opcional
mac	string	MAC address da ONU opcional
oltId	number	ID da OLT para filtrar opcional

Resposta 200

{ "onu": { "id": "99", "serial": "ZTEG12345678", "olt": "OLT-PRINCIPAL", "slot": 1, "pon": 3, "online": true, "rx": "-21.5 dBm" } }

POST /api/sgp/onu/autorizar Autorizar ONU não provisionada

Body (JSON)

Campo	Tipo	Descrição
serial	string	Serial da ONU obrigatório
contratoId	string	ID do contrato no ERP obrigatório
templateId	number	ID do perfil de configuração obrigatório
vlan	number	VLAN do contrato (vem do info-sgp) obrigatório

Resposta 200

{ "ok": true, "onuId": "99", "mensagem": "ONU autorizada com sucesso" }

POST /api/sgp/onu/foto Enviar foto da ONU instalada

Body (JSON)

Campo	Tipo	Descrição
osId	string	ID da OS obrigatório
serial	string	Serial da ONU fotografada obrigatório
foto	string	Imagem em base64 obrigatório

GET /api/sgp/onu/templates Listar perfis de configuração GPON

Retorna os templates de provisão disponíveis no ERP (perfis de serviço GPON/EPON para autorização de ONUs).

Resposta 200

{ "templates": [ { "id": 1, "nome": "Residencial 100M", "tipo": "GPON" }, { "id": 2, "nome": "Empresarial 300M", "tipo": "GPON" } ] }

GET /api/tecnico/onu Dados da ONU do cliente (app técnico)

Retorna status detalhado da ONU do cliente de uma OS: sinal RX, VLAN, uptime, status online. Usado pelo app do técnico em campo.

Query Parameters

Parâmetro	Tipo	Descrição
osId	string	ID da OS obrigatório

Técnico — App

App do Técnico — Operações

Endpoints utilizados exclusivamente pelo app móvel do técnico em campo: ponto, pausa, rota, speed test, baixa e busca de contratos.

POST /api/tecnico/ponto Registrar ponto (entrada/saída)

Body (JSON)

Campo	Tipo	Descrição
tecnicoId	string	ID do técnico obrigatório
tipo	string	"entrada" · "saida" · "almoco_saida" · "almoco_retorno" obrigatório
lat	number	Latitude no momento do ponto opcional
lng	number	Longitude no momento do ponto opcional
foto	string	Selfie em base64 — processada no cliente com carimbo de data/hora BRT, endereço e coordenadas GPS via canvas + Nominatim opcional

A foto é carimbada pelo app do técnico antes do envio: data/hora em BRT, endereço reverso via OpenStreetMap (Nominatim) e coordenadas GPS. Imagens são comprimidas para max 1280px JPEG 0.82 (~15–160 KB). Fotos são armazenadas em /uploads/ponto/YYYY-MM-DD/ e removidas automaticamente após 90 dias via crontab.

Resposta 200

{ "ok": true, "registroId": "42", "hora": "08:01" }

POST /api/tecnico/pausa Registrar pausa ou retorno

Body (JSON)

Campo	Tipo	Descrição
tecnicoId	string	ID do técnico obrigatório
tipo	string	"iniciar" · "finalizar" obrigatório
motivo	string	Motivo da pausa opcional

POST /api/tecnico/solicitar-baixa Solicitar baixa de OS ao atendente

Técnico solicita confirmação de encerramento de OS. O atendente visualiza a solicitação no painel de baixas pendentes antes de confirmar no ERP.

Body (JSON)

Campo	Tipo	Descrição
osId	string	ID da OS obrigatório
tecnicoId	string	ID do técnico obrigatório
relato	string	Relato do serviço realizado obrigatório
fotos	string[]	Fotos em base64 opcional

Resposta 200

{ "ok": true, "baixaId": "15", "status": "pendente" }

POST /api/tecnico/speed-test Registrar resultado de speed test

Body (JSON)

Campo	Tipo	Descrição
osId	string	ID da OS obrigatório
download	number	Velocidade de download em Mbps obrigatório
upload	number	Velocidade de upload em Mbps obrigatório
ping	number	Latência em ms opcional

GET /api/tecnico/buscar-contrato Buscar contrato do cliente no ERP

Retorna dados do contrato vinculado a uma OS: plano, status de pagamento, endereço técnico. CPF/CNPJ nunca são exibidos.

Query Parameters

Parâmetro	Tipo	Descrição
osId	string	ID da OS obrigatório

GET /api/tecnico/rota Rota otimizada do dia para o técnico

Retorna as OS do dia ordenadas por proximidade geográfica (rota otimizada). Exibido no app do técnico como lista de paradas em sequência.

Query Parameters

Parâmetro	Tipo	Descrição
tecnicoId	string	ID do técnico obrigatório
data	string	Data YYYY-MM-DD opcional — padrão: hoje

POST /api/tecnico/km-foto Registrar KM com foto do odômetro

Body (JSON)

Campo	Tipo	Descrição
tecnicoId	string	ID do técnico obrigatório
tipo	string	"inicial" · "final" obrigatório
foto	string	Foto do odômetro em base64 obrigatório
km	number	KM lido no odômetro opcional — pode ser extraído da foto por IA

Reagendamento

Reagendamento de OS

Controle de solicitações de reagendamento feitas por técnicos e processamento automático pelo sync diário.

GET /api/reagendamento Listar solicitações de reagendamento

Retorna solicitações de reagendamento filtradas por status. Quando status=aprovado, cada registro inclui o objeto atribuicao com coordenadas e endereço da OS — usado pelo mapa do admin e pelo app do técnico para exibir reagendadas aprovadas.

Query Parameters

Parâmetro	Tipo	Descrição
status	string	"pendente" · "aprovado" · "rejeitado" · "todos" opcional — padrão: pendente
tecnicoId	string	Filtrar por técnico opcional

Resposta 200

{ "solicitacoes": [ { "id": "1", "osId": "12345", "tecnicoId": "234", "tecnicoNome": "Bruno", "motivo": "Cliente ausente", "novaData": "2026-08-15", "status": "aprovado", "criadoEm": "2026-08-11T10:00:00.000Z", "atribuicao": { "lat": -23.8734, "lng": -46.7291, "clienteEndereco": "Rua Exemplo, 123", "clienteBairro": "Jardim Casa Grande", "tipoOS": "Suporte Técnico", "horaAgendada": "14:00", "tecnicoNome": "Bruno" } } ] }

O campo atribuicao só está presente quando status=aprovado e há uma OS vinculada no banco local.

POST /api/reagendamento Criar ou aprovar solicitação

Body (JSON)

Campo	Tipo	Descrição
action	string	"criar" · "aprovar" · "rejeitar" obrigatório
osId	string	ID da OS obrigatório
tecnicoId	string	ID do técnico opcional
motivo	string	Motivo do reagendamento opcional
novaData	string	Nova data YYYY-MM-DD opcional

POST /api/sgp/reagendar Reagendar OS no ERP

Atualiza a data agendada de uma OS diretamente no ERP via API REST.

Body (JSON)

Campo	Tipo	Descrição
osId	string	ID da OS no ERP obrigatório
novaData	string	Nova data YYYY-MM-DD obrigatório
tecnicoId	string	ID do técnico responsável opcional

Resposta 200

{ "ok": true, "osId": "12345", "novaData": "2026-08-15" }

POST /api/sgp/reagendar-hoje Mover OS atrasadas para hoje

Chamado automaticamente pelo sync diário (passo 3b). Move todas as OS abertas de dias anteriores para a data atual no ERP.

Resposta 200

{ "ok": true, "processadas": 4, "erros": 0 }

POST /api/sgp/auto-atribuir Atribuir OS automaticamente por área

Cruza coordenadas da OS com polígonos de áreas cadastradas e atribui ao técnico responsável por aquela área.

Body (JSON)

Campo	Tipo	Descrição
osIds	string[]	Lista de IDs de OS para processar opcional — processa todas se omitido

Resposta 200

{ "ok": true, "atribuidas": 6, "semArea": 2 }

Inteligência Artificial

IA — Distribuição de OS

Motor de distribuição inteligente de ordens de serviço. Usa coordenadas, áreas, carga de trabalho e histórico para sugerir ou aplicar atribuições otimizadas.

POST /api/ia/distribuir Distribuir OS automaticamente

Analisa as OS abertas do dia, cruza com áreas e carga dos técnicos, e aplica a distribuição otimizada. Registra no histórico.

Body (JSON)

Campo	Tipo	Descrição
data	string	Data YYYY-MM-DD para distribuir opcional — padrão: hoje
forcar	boolean	Redistribuir mesmo OS já atribuídas opcional
apenasPreview	boolean	Só sugerir, não aplicar opcional

Resposta 200

{ "ok": true, "distribuidas": 12, "semCobertura": 1, "detalhes": [ { "osId": "111", "tecnico": "Bruno", "area": "Jardim Casa Grande" } ] }

POST /api/ia/distribuir-web Distribuição via interface web (streaming)

Versão da distribuição com resposta em streaming para atualização em tempo real no painel. Aceita os mesmos parâmetros que /api/ia/distribuir.

POST /api/ia/script-auto Executar script de IA automático

Chamado pelo cron após o sync. Executa a distribuição automática completa sem intervenção humana. Registra log no histórico.

Resposta 200

{ "ok": true, "distribuidas": 8, "fonte": "cron" }

POST /api/ia/script-sgp Sincronizar e distribuir via SGP

Busca OS diretamente do SGP, executa distribuição e salva atribuições. Equivalente ao script-auto mas forçando re-fetch do ERP.

GET /api/ia/historico Histórico de distribuições

Query Parameters

Parâmetro	Tipo	Descrição
data	string	Filtrar por data YYYY-MM-DD opcional
limite	number	Máximo de registros opcional — padrão 30

Resposta 200

{ "historico": [ { "id": "1", "data": "2026-08-11", "distribuidas": 12, "fonte": "manual", "executadoEm": "2026-08-11T08:01:00.000Z" } ] }

GET /api/ia/stats Estatísticas da IA

Retorna métricas de desempenho: total distribuído, taxa de cobertura de áreas, média de OS por técnico.

GET /api/inteligencia Painel de inteligência operacional

Agrega dados de OS, atribuições e pontos para gerar insights operacionais: técnicos sobrecarregados, áreas com mais OS, taxa de resolução no prazo.

Resposta 200

{ "resumo": { "totalOS": 45, "finalizadas": 38, "taxaResolucao": "84%", "tecnicoMaisOS": "Bruno" }, "porTecnico": [...] }

Ponto & RH

Ponto Eletrônico & RH

Gestão de jornada, correções de ponto, escala de trabalho, benefícios e lançamentos de RH.

GET /api/relatorio/ponto Relatório de ponto por período

Query Parameters

Parâmetro	Tipo	Descrição
tecnicoId	string	Filtrar por técnico opcional
inicio	string	Data inicial YYYY-MM-DD obrigatório
fim	string	Data final YYYY-MM-DD obrigatório

Resposta 200

{ "relatorio": [ { "tecnicoNome": "Bruno", "data": "2026-08-11", "entrada": "08:01", "saida": "17:42", "totalHoras": "09:41", "extras": "01:41" } ] }

POST /api/admin/correcao-ponto Solicitar ou aprovar correção de ponto

Body (JSON)

Campo	Tipo	Descrição
action	string	"solicitar" · "aprovar" · "rejeitar" obrigatório
registroId	string	ID do registro de ponto obrigatório
novoHorario	string	Horário corrigido HH:MM opcional
motivo	string	Justificativa opcional

GET /api/admin/escala Consultar escalas de trabalho

Retorna escalas cadastradas (6x1, 5x2, 12x36, etc.) com horários de entrada, saída e configuração de folga.

POST /api/admin/escala Criar ou editar escala

Body (JSON)

Campo	Tipo	Descrição
nome	string	Ex: "6x1 Semanal" obrigatório
tipo	string	"semanal" · "mensal" · "personalizado" obrigatório
horarioEntrada	string	Horário padrão de entrada HH:MM obrigatório
horarioSaida	string	Horário padrão de saída HH:MM obrigatório

POST /api/admin/escala-funcionario Atribuir escala a um funcionário

Body (JSON)

Campo	Tipo	Descrição
tecnicoId	string	ID do técnico/funcionário obrigatório
escalaId	string	ID da escala obrigatório
dataInicio	string	Data de início YYYY-MM-DD obrigatório

GET /api/admin/beneficios Listar benefícios configurados

Retorna os benefícios ativos (VT, VR, plano de saúde, etc.) com valor e forma de desconto.

POST /api/admin/lancamento-rh Registrar lançamento avulso

Registra adicionais, descontos, bônus, verbas rescisórias ou ausências (Atestado, Férias, Folga, Falta) para um funcionário. Quando o tipo é uma ausência e o período cobre o dia atual, o sistema redistribui automaticamente as OS abertas do técnico para outros técnicos disponíveis.

Body (JSON)

Campo	Tipo	Descrição
tecnicoId	string	ID do funcionário obrigatório
tipo	string	"adicional" · "desconto" · "bonus" · "Atestado" · "Férias" · "Folga" · "Falta" obrigatório
descricao	string	Descrição do lançamento obrigatório
valor	number	Valor em R$ (não obrigatório para ausências)
dataInicio	string	Data inicial YYYY-MM-DD (obrigatório para ausências)
dataFim	string	Data final YYYY-MM-DD (obrigatório para ausências)
competencia	string	Mês/ano YYYY-MM obrigatório

Resposta 200 — com redistribuição automática

{ "ok": true, "redistribuicao": { "redistribuidas": 4, "emAndamento": 1 } }

⚠️ OS com status em_deslocamento ou em_atendimento não são redistribuídas automaticamente — devem ser tratadas manualmente.

Cargos & Colaboradores

Cargos e Perfis de Colaborador

Gestão de cargos com controle de acesso por módulo. Cada cargo define quais módulos o colaborador pode acessar.

GET /api/admin/cargos Listar cargos cadastrados

Resposta 200

{ "cargos": [ { "id": "1", "nome": "Supervisor Técnico", "departamento": "Operações", "modulos": ["dashboard", "os", "agenda", "mapa"], "salarioBase": 3500 } ] }

POST /api/admin/cargos Criar ou editar cargo

Body (JSON)

Campo	Tipo	Descrição
id	string	ID do cargo (edição) opcional — omitir para criar
nome	string	Nome do cargo obrigatório
departamento	string	Departamento opcional
modulos	string[]	Lista de módulos permitidos opcional
salarioBase	number	Salário base R$ opcional

Módulos disponíveis: dashboard · os · agenda · reagendamentos · mapa · areas · areas_editar · ia · massiva · estoque · ponto · folha · relatorio · veiculos · rota

GET /api/admin/colaborador-perfil Listar colaboradores e perfis

Retorna todos os usuários com perfil colaborador, seu cargo e os módulos que têm acesso (herdados do cargo).

Query Parameters

Parâmetro	Tipo	Descrição
cargoId	string	Filtrar por cargo opcional

POST /api/admin/colaborador-perfil Atribuir cargo a colaborador

Body (JSON)

Campo	Tipo	Descrição
usuarioId	string	ID do usuário obrigatório
cargoId	string	ID do cargo obrigatório

Folha de Pagamento

Apuração mensal da folha de pagamento. Calcula horas trabalhadas, extras, banco de horas, benefícios e lançamentos avulsos.

GET /api/folha Consultar folha de um período

Query Parameters

Parâmetro	Tipo	Descrição
competencia	string	Mês/ano no formato YYYY-MM obrigatório
tecnicoId	string	Filtrar por funcionário opcional

Resposta 200

{ "competencia": "2026-08", "funcionarios": [ { "tecnicoNome": "Bruno", "salarioBase": 2800, "horasExtras": 12.5, "valorExtras": 218.75, "beneficios": 350, "descontos": 50, "totalLiquido": 3318.75, "status": "aberta" } ] }

POST /api/folha Fechar ou reabrir folha

Body (JSON)

Campo	Tipo	Descrição
action	string	"fechar" · "reabrir" · "calcular" obrigatório
competencia	string	YYYY-MM obrigatório

Tabelas Tributárias

INSS · IRRF · VT · VA

Tabelas legais usadas no cálculo da folha de pagamento. Os valores padrão seguem a legislação vigente e podem ser atualizados pelo administrador quando houver mudança na lei — sem necessidade de alteração no código.

GET /api/admin/tabelas-tributarias Consultar tabelas vigentes (INSS e IRRF)

Retorna as faixas de INSS e IRRF. Se não houver customização, retorna os valores padrão da legislação atual. Indica data e responsável da última atualização.

Resposta 200

{ "tabelas": { "inss": { "valor": [ { "ate": 1412.00, "aliq": 7.5 }, { "ate": 2666.68, "aliq": 9.0 }, { "ate": 4000.03, "aliq": 12.0 }, { "ate": 7786.02, "aliq": 14.0 } ], "atualizadoEm": null, "atualizadoPor": null }, "irrf_faixas": { "valor": [ { "acimaDe": 0, "aliq": 0, "deducao": 0 }, { "acimaDe": 2428.80, "aliq": 7.5, "deducao": 182.16 }, { "acimaDe": 2826.65, "aliq": 15.0, "deducao": 394.16 }, { "acimaDe": 3751.05, "aliq": 22.5, "deducao": 675.49 }, { "acimaDe": 4664.68, "aliq": 27.5, "deducao": 908.73 } ], "atualizadoEm": null, "atualizadoPor": null } } }

POST /api/admin/tabelas-tributarias Atualizar tabela (quando mudar a lei)

Sobrescreve uma tabela específica com os novos valores. A alteração é registrada com data e nome do responsável.

Body (JSON)

Campo	Tipo	Descrição
chave	string	"inss" · "irrf_faixas" · "irrf_desconto" obrigatório
valor	array	Novas faixas conforme estrutura da tabela obrigatório
atualizadoPor	string	Nome do responsável pela atualização opcional

GET /api/admin/config-beneficio Consultar valores de VT e VA

Retorna os valores diários de Vale Transporte e Vale Alimentação configurados. Se não houver customização, retorna os valores padrão. Cada empresa configura os seus próprios valores.

Resposta 200

{ "config": { "vtValorDia": 22, "vaValorDia": 35, "vtDescontaAtestado": false, "vaDescontaAtestado": false } }

POST /api/admin/config-beneficio Atualizar valores de VT e VA

Body (JSON)

Campo	Tipo	Descrição
vtValorDia	number	Valor diário do Vale Transporte em R$
vaValorDia	number	Valor diário do Vale Alimentação em R$
vtDescontaAtestado	boolean	Descontar VT em dias de atestado
vaDescontaAtestado	boolean	Descontar VA em dias de atestado

GET /api/admin/escala Listar escalas de trabalho

Retorna todas as escalas cadastradas. Cada escala define os dias e horários de trabalho. Pode ser atribuída individualmente a cada colaborador.

Resposta 200

{ "escalas": [ { "id": "1", "nome": "Segunda a Sexta 08h–17h", "diasConfig": { "seg": { "ativo": true, "entrada": "08:00", "saida": "17:00" }, "ter": { "ativo": true, "entrada": "08:00", "saida": "17:00" }, "sab": { "ativo": false" } } } ] }

POST /api/admin/escala Criar ou editar escala

Body (JSON)

Campo	Tipo	Descrição
id	string	ID da escala — omitir para criar nova opcional
nome	string	Nome da escala obrigatório
diasConfig	object	Configuração por dia da semana (seg/ter/qua/qui/sex/sab/dom) com entrada, saída e se está ativo obrigatório

POST /api/admin/escala-funcionario Atribuir escala a um colaborador

Body (JSON)

Campo	Tipo	Descrição
userId	string	ID do colaborador obrigatório
escalaId	string	ID da escala obrigatório

Relatórios

Relatórios e Emails

Geração e envio de relatórios por email. Relatório de KM diário, ponto eletrônico e resumos operacionais.

GET /api/relatorio-email Listar relatórios de email configurados

Resposta 200

{ "relatorios": [ { "id": "1", "tipo": "km_diario", "destinatarios": ["gestor@empresa.com"], "horario": "18:00", "ativo": true } ] }

POST /api/relatorio-email Criar ou editar relatório automático

Body (JSON)

Campo	Tipo	Descrição
tipo	string	"km_diario" · "ponto_mensal" · "resumo_os" obrigatório
destinatarios	string[]	Lista de emails obrigatório
horario	string	Horário de envio HH:MM opcional
ativo	boolean	Ativar/desativar envio opcional

POST /api/relatorio-email/enviar Enviar relatório manualmente agora

Body (JSON)

Campo	Tipo	Descrição
relatorioId	string	ID do relatório obrigatório
data	string	Data de referência YYYY-MM-DD opcional — padrão: hoje

Resposta 200

{ "ok": true, "enviados": 2, "destinatarios": ["gestor@empresa.com"] }

Administração

Gestão de Usuários e Provedores

CRUD de usuários do painel e configuração de integrações com ERPs (SGP, IXC, MKAuth).

GET /api/admin/usuarios Listar usuários do sistema

Resposta 200

{ "usuarios": [ { "id": "1", "nome": "Bruno Silva", "usuario": "bruno", "perfil": "tecnico", "ativo": true, "cor": "#3B82F6", "sgpId": "234" } ] }

POST /api/admin/usuarios Criar ou editar usuário

Body (JSON)

Campo	Tipo	Descrição
id	string	ID do usuário (edição) opcional — omitir para criar
nome	string	Nome completo obrigatório
usuario	string	Login (único) obrigatório
senha	string	Senha obrigatório na criação
perfil	string	"admin" · "atendente" · "tecnico" · "colaborador" obrigatório
cor	string	Cor no mapa (hex) opcional
sgpId	string	ID do técnico no ERP opcional
ativo	boolean	Ativar/desativar acesso opcional

GET /api/admin/provedores Listar integrações com ERP

Retorna as configurações de integração com os ERPs de internet (SGP, IXC, MKAuth). Inclui URL, status da conexão e últimas sincronizações.

Resposta 200

{ "provedores": [ { "id": "1", "tipo": "sgp", "url": "https://empresa.sgp.net.br", "status": "conectado", "ultimoSync": "2026-08-11T10:00:00.000Z" } ] }

POST /api/admin/provedores Configurar integração ERP

Body (JSON)

Campo	Tipo	Descrição
tipo	string	"sgp" · "ixc" · "mkauth" obrigatório
url	string	URL base do ERP obrigatório
token	string	Token de API obrigatório
usuario	string	Usuário da API opcional
senha	string	Senha da API opcional

Atendente

Painel do Atendente

Endpoints exclusivos do painel de atendimento: aprovação de baixas solicitadas pelos técnicos e gestão de remoções de OS.

GET /api/atendente/baixas-pendentes Listar baixas aguardando aprovação

Retorna todas as OS onde o técnico solicitou baixa via app mas ainda aguardam confirmação do atendente para encerrar no ERP.

Resposta 200

{ "baixas": [ { "id": "15", "osId": "12345", "tecnicoNome": "Bruno", "clienteNome": "João Silva", "relato": "ONU trocada e sinal normalizado", "fotos": 2, "solicitadoEm": "2026-08-11T10:30:00.000Z" } ], "total": 1 }

POST /api/atendente/baixas-pendentes Aprovar ou rejeitar baixa

Body (JSON)

Campo	Tipo	Descrição
action	string	"aprovar" · "rejeitar" obrigatório
baixaId	string	ID da solicitação de baixa obrigatório
motivo	string	Motivo da rejeição opcional

Resposta 200 (aprovar)

{ "ok": true, "osEncerrada": true, "osId": "12345" }

POST /api/remocao Remover OS da distribuição local

Remove uma OS da fila de distribuição local do Opzio (não altera o ERP). Usado quando uma OS foi cancelada ou tratada fora do sistema.

Body (JSON)

Campo	Tipo	Descrição
osId	string	ID da OS obrigatório
motivo	string	Motivo da remoção opcional

Onboarding

Implantação de Novo Cliente

Cada cliente Opzio é uma instância completamente isolada — banco de dados próprio, processo PM2 próprio e subdomínio próprio. Nenhum dado é compartilhado entre clientes.

📦 Arquitetura por cliente

Código

/root/clientes/vivanet/

Cópia do template servix-demo
sem dados fictícios

Banco

prisma/vivanet.db

SQLite exclusivo
schema limpo (sem seed)

Processo

PM2: vivanet

Porta exclusiva (range 3100–3899)
calculada por hash do nome

Acesso

vivanet.servix.cgrltec.com.br

Nginx → porta do cliente
login: admin / senha definida

🚀 Script de implantação

Rode no VPS como root. O script cria tudo automaticamente em 6 passos.

./novo-cliente.sh NOME_CLIENTE SUBDOMINIO SENHA_ADMIN # Exemplo real: ./novo-cliente.sh vivanet vivanet minhasenha123

O que o script faz automaticamente:

Copia /root/servix-demo/ → /root/clientes/CLIENTE/ (sem banco, sem dados demo)
Gera .env exclusivo com DATABASE_URL, NEXTAUTH_SECRET e NEXTAUTH_URL
Cria data/ com JSONs vazios (massivas, áreas, estoque…)
Roda npm install + prisma migrate deploy → banco limpo
Cria usuário admin com a senha informada
Build + PM2 na porta exclusiva + registra em /root/clientes/registro.txt

⚠️ Passo manual após o script: configurar Nginx para rotear
SUBDOMINIO.servix.cgrltec.com.br → 127.0.0.1:PORTA

📋 O que o cliente configura após receber acesso

1. Entra no painel como admin com a senha entregue
2. Cadastra técnicos (nome, login, cor no mapa)
3. Configura integração com ERP (SGP / IXC / MKAuth) — URL + credenciais
4. Sistema começa a puxar OS automaticamente via sync a cada 2 min
5. Ajusta áreas de cobertura no mapa para distribuição automática por IA

Opzio API Reference v1.2 · São Paulo, Brasil Agosto 2026