Pular para o conteúdo principal

Documentação dos Serviços - Force Mobile - 2026

Visão Geral​

Esta seção contém a documentação dos serviços implementados para gerenciar as operações na aplicação Force Mobile. Estes serviços são responsáveis pela integração com a API REST para buscar e manipular dados remotos.

Nota: Alguns serviços já implementam padrão offline-first com integração ao banco de dados local (SQLite).

Serviços Disponíveis​

Client Service​

Gerencia operações relacionadas aos clientes, incluindo busca, cadastro, atualização e sincronização com banco de dados local (offline-first).

  • Endpoints: GET /cliente, POST /cliente, PUT /cliente/{id}, GET /cliente/search/clientes, GET /cliente/cnpj/{cnpj}, GET /cliente/cep/{cep}
  • Principais recursos: Busca paginada, busca com filtros, cadastro, atualização, sincronização local, cache offline, consulta de CNPJ e CEP

Layout Service​

Gerencia operações relacionadas aos layouts de formulários, permitindo buscar configurações de layout por entidade.

  • Endpoint: GET /layout
  • Principais recursos: Busca de layouts por entidade (Cliente, Produto, Cabeçalho, Contato), configuração dinâmica de formulários

Field Layout Service​

Gerencia operações relacionadas aos campos individuais de layouts, fornecendo configurações detalhadas para renderização dinâmica de formulários.

  • Endpoint: GET /campoLayout
  • Principais recursos: Busca de campos por layout, configurações de visibilidade/obrigatoriedade/editabilidade, opções de campos

Contact Service​

Gerencia operações relacionadas aos contatos de clientes, incluindo cadastro e atualização.

  • Endpoints: POST /cliente/contato/{clientId}, PUT /cliente/contato/{contactId}
  • Principais recursos: Cadastro de contatos vinculados a clientes, atualização de contatos, validação de CPF/CNPJ

Client Attachment Service​

Gerencia anexos de clientes: listar anexos de um cliente, enviar novos anexos (upload) e excluir anexos existentes.

  • Endpoints: GET /cliente/anexo/cliente/{clientId}, POST /cliente/anexo/{clientId}, DELETE /cliente/anexo/{attachmentId}
  • Localização: services/client-attachment/client-attachment.service.ts
  • Principais recursos: Busca paginada de anexos por cliente, upload via FormData, remoção de anexos, validação de tamanho e tipos MIME aceitos

Activity Note Service​

Gerencia apontamentos de atividade (check-ins/visitas) realizados pelos usuários, permitindo registrar, listar, atualizar, finalizar (checkout) e excluir atividades.

  • Endpoints: GET /checkin/porUsuario/{userId}, GET /checkin/{id}, POST /checkin, PUT /checkin/{id}, DELETE /checkin/{id}, PATCH /checkin/checkout/{id}
  • Principais recursos: Registro de check-in/check-out, listagem paginada por usuário, suporte a payloads com FormData (anexos), validação via schema (zod), finalização de atividade (checkout) e histórico de visitas

Activity Type Service​

Busca os tipos de atividade (check-in) disponíveis na API remota, usado para popular selects, filtros e validações que dependem da lista de tipos.

  • Endpoint: GET /tipoAtividadeCheckin
  • Localização: services/activity-type/activity-type.service.ts
  • Principais recursos: Busca paginada de tipos de atividade, suporte a sincronização incremental, uso em selects e filtros

Reasons Not Selling Service​

Fornece acesso aos motivos de não-venda cadastrados na API, usado para popular selects, filtros e validações quando um vendedor registra uma visita sem venda.

  • Endpoints: GET /motivosNaoVenda
  • Principais recursos: Busca paginada de motivos, suporte a sincronização incremental, filtro por data de atualização, integração em telas de apontamento de atividade

Publication Service​

Gerencia publicações e comentários dentro da solução, permitindo listar publicações ativas, consultar detalhes, gerenciar comentários e alternar likes por usuário.

  • Endpoints: GET /publicacoes/ativas, GET /publicacoes/:publicationId, GET /publicacoes/:publicationId/comentarios, POST /publicacoes/:publicationId/:userId, PUT /publicacoes/:publicationId/:commentId, DELETE /publicacoes/:publicationId/:commentId, PATCH /publicacoes/:publicationId/:userId
  • Principais recursos: Busca de publicações ativas (paginada), detalhes de publicação, listagem/registro/edição/remoção de comentários, alternância de curtida por usuário, paginação de comentários

Profile Image Service​

Gerencia a imagem de perfil dos usuários: baixar (blob), enviar via FormData e remover a imagem vinculada ao usuário.

  • Endpoints: GET /usuario/:userId/imagemPerfil, POST /usuario/:userId/imagemPerfil, DELETE /usuario/:userId/imagemPerfil
  • Principais recursos: Download como Blob, upload com FormData, remoção, integração com perfil do usuário

Version Service​

Busca versões e changelogs da solução, com paginação e filtros por solução/data.

  • Endpoint: GET /versoes
  • Principais recursos: Lista paginada de versões, filtro por solucaoId e dataHora, exibição de registro de alterações (changelog)

AI Service​

Fornece funcionalidades de IA para extração de produtos de documentos e sugestão de pedidos baseada em parâmetros de negociação.

  • Endpoints: POST /documents/extrair-produtos, GET /pedido-sugerido
  • Principais recursos: Extração de produtos via upload (PDF/imagem) com metadados, sugestão de pedido baseada em parâmetros comerciais, integração com helpers buildFormData e buildQueryParams, suporte a testes via mocks

Open Title Service​

Gerencia operações relacionadas aos títulos em aberto, permitindo buscar títulos pendentes de forma geral ou filtrados por cliente.

  • Endpoints: GET /titulosAberto, GET /titulosAberto/cliente/{clientId}
  • Principais recursos: Busca paginada de títulos em aberto, consulta por cliente específico, filtros por data, informações de valor, parcelas e status

Aliquot Service​

Gerencia operações relacionadas às alíquotas fiscais, permitindo buscar configurações de tributação.

  • Endpoint: GET /aliquota
  • Principais recursos: Busca paginada de alíquotas, configurações de ICMS, margem de lucro, base ST reduzida, informações fiscais detalhadas

Payment Method Service​

Gerencia operações relacionadas às formas de pagamento, permitindo buscar métodos de pagamento disponíveis para vendas.

  • Endpoint: GET /formaPagamento
  • Principais recursos: Busca de formas de pagamento, condições de pagamento, juros, prazos e restrições, filtros por consumidor

Product Group Service​

Gerencia operações relacionadas aos grupos de produtos, permitindo buscar hierarquias de categorização de produtos.

  • Endpoint: GET /grupoProdutos
  • Principais recursos: Busca de grupos de produtos, estrutura hierárquica de categorias, grupos pai e filhos, filtros analíticos e sintéticos

Operations Group Service​

Fornece acesso aos grupos de operações configurados na API (ex: entrada, saída, transferência, ajuste). Permite listar grupos e tipos de operação associados com paginação.

  • Endpoint: GET /gruposOperacao
  • Principais recursos: Busca paginada de grupos de operação, tipos de operação por grupo, opções para popular selects e filtros de operações

Company Service​

Gerencia operações relacionadas às empresas, permitindo buscar informações sobre as empresas/filiais da organização.

  • Endpoint: GET /empresa
  • Principais recursos: Busca de empresas, informações de filiais, controle por unidade de negócio

Price Service​

Gerencia operações relacionadas aos preços de produtos, permitindo buscar tabelas de preços e consultar valores conforme diferentes políticas comerciais.

  • Endpoint: GET /precoProduto
  • Principais recursos: Busca de preços por tabela, consulta de valores por produto, preços flexíveis e fixos, múltiplas políticas de precificação

Product Service​

Gerencia operações relacionadas aos produtos, permitindo buscar catálogo completo com filtros avançados.

  • Endpoints: GET /produtos, GET /produtos/{ids}
  • Principais recursos: Busca de produtos com paginação, busca por IDs específicos, filtros por cliente/tabela de preços/marcas/fabricantes/fornecedores/grupos, informações detalhadas, especificações técnicas, dimensões e classificações fiscais

Payment Slip Service​

Gerencia operações relacionadas ao boleto de cobrança, permitindo buscar e salvar o PDF do boleto localmente.

  • Endpoint: GET /api/v1/document/boleto
  • Principais recursos: Busca do boleto PDF, conversão em base64, salvamento do arquivo local, integração com serviço de armazenamento

Stock Service​

Gerencia operações relacionadas ao estoque de produtos, permitindo consultar disponibilidade por empresa, local, lote e controle de validade.

  • Endpoint: GET /estoque
  • Principais recursos: Busca de estoque, consulta por empresa/filial, filtros por local de armazenagem, controle de lotes e validade, cálculo de saldo disponível

Order Header Service​

Gerencia operações relacionadas aos pedidos de venda, permitindo buscar histórico, inicializar pedidos, atualizar e deletar.

  • Endpoints: GET /cabecalhoPedido, GET /cabecalhoPedido/{id}, POST /cabecalhoPedido/cabecalhoBasico/{clientId}, PUT /cabecalhoPedido/{orderHeaderId}, DELETE /cabecalhoPedido/{orderHeaderId}
  • Principais recursos: Busca de pedidos com paginação, filtros por período (data início/fim), filtros por líder/usuário/cliente, inicialização de pedido básico, consulta de detalhes completos, atualização e deleção de pedidos, informações de cabeçalho e itens do pedido

User Service​

Gerencia operações relacionadas aos usuários do sistema, permitindo buscar lista completa de usuários e consultar subordinados de um líder específico.

  • Endpoints: GET /usuario/usuarios, GET /usuario/listarSubordinados/{leaderId}
  • Principais recursos: Busca de usuários com paginação, consulta de subordinados por líder, informações de perfil e hierarquia, acesso a organizações vinculadas, clientes atribuídos e colaboradores

Client Profile Service​

Gerencia operações relacionadas aos perfis de clientes, permitindo buscar perfis e produtos associados.

  • Endpoint: GET /perfil
  • Principais recursos: Busca de perfis de clientes com paginação, consulta de produtos associados ao perfil, informações básicas de produtos

Organization Configuration Service​

Gerencia configurações e funcionalidades das organizações, permitindo controlar acessos, definir parâmetros e personalizar comportamentos do sistema.

  • Endpoints: GET /configuracaoOrganizacao, GET /configuracaoOrganizacao/funcionalidades/context
  • Principais recursos: Busca de configurações da organização, consulta de contextos de funcionalidades por organização/grupo/usuário, controle de acessos, valores padrões, gerenciamento de permissões

Access Log Service​

Gerencia o registro de acessos ao sistema, coletando informações do dispositivo e enviando logs de entrada do usuário.

  • Endpoint: POST /logAcesso
  • Principais recursos: Registro de acessos, coleta automática de dados do dispositivo, informações de bateria/memória/armazenamento, rastreamento de versões, monitoramento de compatibilidade

Usage Log Service​

Gerencia o registro de uso de funcionalidades do sistema, permitindo rastrear interações dos usuários e tempos de execução.

  • Endpoint: POST /logUso
  • Principais recursos: Registro de uso de funcionalidades, rastreamento de tempo de execução, monitoramento de status HTTP, registro de mensagens e tipos de uso, análise de performance

Item Service​

Gerencia operações relacionadas aos itens de pedidos, permitindo cadastro, atualização completa e atualização parcial.

  • Endpoints: POST /item, PUT /item/{itemId}, PATCH /item/{itemId}
  • Principais recursos: Cadastro de novos itens em pedidos, atualização completa de itens, atualização parcial de campos específicos, gerenciamento de produtos/preços/quantidades, controle de descontos e impostos

Sync Queue Service​

Gerencia operações relacionadas à fila de sincronização de dados, permitindo iniciar sincronizações e consultar histórico básico e avançado.

  • Endpoints: POST /historicoSincronizacao/sincronizacaoTotal, GET /historicoSincronizacao/historico, GET /historicoSincronizacao/historico/filtrar
  • Principais recursos: Iniciar sincronização total de dados, consultar histórico básico por dispositivo/usuário, consultar histórico avançado por entidade com filtros (status, solicitante, dispositivo), monitorar status e tempo de processamento, rastrear registros incluídos e alterados

Promotion Service​

Gerencia operações relacionadas às promoções, permitindo buscar promoções disponíveis com paginação e filtros avançados.

  • Endpoint: GET /promocoes
  • Principais recursos: Busca de promoções com paginação, filtro por data de atualização, descontos por cliente/produto/grupo, descontos por quantidade, promoções por tabela de preços, controle de período de vigência

Pricing Table Service​

Gerencia operações relacionadas às tabelas de preço, permitindo buscar tabelas disponíveis com paginação e por IDs específicos.

  • Endpoints: GET /tabelaPreco, GET /tabelaPreco/{ids}
  • Principais recursos: Busca de tabelas de preço com paginação, busca por IDs específicos, filtro por data de atualização, informações de organização e identificação externa

Measurement Unit Service​

Gerencia operações relacionadas às unidades de medida, permitindo buscar unidades disponíveis para produtos.

  • Endpoint: GET /unidadeMedida
  • Principais recursos: Busca paginada de unidades de medida, sincronização offline, popular dropdowns/selects com opções de unidades disponíveis

PDF Service​

Gerencia operações relacionadas à criação e gerenciamento de PDFs, incluindo geração local de PDFs de pedidos, download de documentos online e acesso a relatórios formatados.

  • Endpoints: POST /api/v1/document/pdf, GET /relatorioFormatado, GET /relatorioFormatado/{id}
  • Principais recursos: Geração de PDFs de pedidos em Base64, download de documentos online, busca de relatórios formatados com paginação, integração com sistema de arquivos local

Alternative Unit Service​

Gerencia operações relacionadas às unidades alternativas de medida para produtos, permitindo buscar unidades alternativas com filtros por produto.

  • Endpoint: GET /unidadeAlternativa
  • Principais recursos: Busca paginada de unidades alternativas, filtro por produto, conversão de quantidades entre unidades, sincronização offline

City Service​

Gerencia operações relacionadas às cidades, permitindo buscar dados geográficos e fiscais para formulários e cadastros.

  • Endpoint: GET /cidades
  • Principais recursos: Busca paginada de cidades, filtros por município/UF/estado/nome, sincronização offline, apoio a cadastros e formulários

Carrier Service​

Gerencia operações relacionadas às transportadoras, permitindo buscar transportadoras com filtros por cliente, localidade e condições comerciais.

  • Endpoint: GET /transportadora
  • Principais recursos: Busca paginada de transportadoras, filtros por cidade/UF/cliente/valor mínimo, sincronização offline, apoio a formulários de venda e logística

Componentes Compartilhados​

buildQueryParams Helper​

Função utilitária que converte um objeto de parâmetros em URLSearchParams, tratando adequadamente arrays e valores nulos/undefined.

Localização: helpers/buildQueryParams.ts

type QueryValue =
  | string
  | number
  | boolean
  | undefined
  | null
  | (string | number | boolean)[];

function buildQueryParams<T extends Record<string, QueryValue>>(
  params: T,
): URLSearchParams;

Comportamento:

  • Remove parâmetros undefined ou null
  • Converte arrays em múltiplos parâmetros com mesmo nome
  • Converte todos os valores para string

PageResponse Interface​

Interface compartilhada para respostas paginadas da API.

Localização: services/client/client.service.ts

interface PageResponse<T> {
  content: T[]; // Array de itens da página atual
  page?: number; // Número da página atual
  size?: number; // Tamanho da página
  totalPages?: number; // Total de páginas
  totalElements?: number; // Total de elementos
  // ... outros campos de paginação
}

API Service​

Instâncias configuradas do Axios para comunicação com a API.

Localização: services/api.service.ts

  • api: Cliente HTTP com autenticação (token de acesso)
  • apiWithoutAccessToken: Cliente HTTP sem autenticação (usado pelos serviços atuais)

Helpers de Validação​

Helpers para validação de documentos brasileiros e formatação.

Localização: helpers/

cpfValidate.ts​

  • isValidCpf(cpf: string): boolean - Valida CPF
  • cpfMask(cpf: string): string - Aplica máscara de CPF

cnpjValidate.ts​

  • isValidCnpj(cnpj: string): boolean - Valida CNPJ
  • cnpjMask(cnpj: string): string - Aplica máscara de CNPJ

formatCpfCnpj.ts​

  • formatCpfCnpj(value: string): string - Formata CPF ou CNPJ automaticamente

zod.ts​

  • Helpers customizados para validação com Zod
  • nullableString, nullableStringWithRegex, nullableEmail, etc.

filterLayoutByEntity Helper​

Função utilitária que filtra layouts por entidade.

Localização: helpers/fiterLayoutByEntity.ts

function filterLayoutByEntity(layout: Layout[], entity: string): Layout[];

Repositories​

ClientRepository​

Repositório para acesso ao banco de dados local.

Localização: repositories/client/client.repository.ts

Principais métodos:

  • saveBatch(clients): Salva clientes em lote
  • findById(id): Busca cliente por ID
  • findMany(params): Busca clientes com filtros
  • clearAll(): Limpa todos os clientes
  • getAvailableLocations(): Obtém localizações únicas

Testes​

Todos os serviços possuem testes unitários implementados:

  • services/client/client.service.test.ts
  • services/layout/layout.service.test.ts
  • services/field-layout/field-layout.service.test.ts
  • services/contact/contact.service.test.ts

Executar Testes​

# Todos os testes
npm test

# Teste específico
npx jest services/client/client.service.test.ts

# Modo watch
npx jest services/contact/contact.service.test.ts --watch

# Com coverage
npm test -- --coverage

Mocks​

Dados mock estão disponíveis para desenvolvimento e testes:

  • __mocks__/client.mock.ts - Dados de clientes e cadastros
  • __mocks__/layout.mock.ts - Layouts de exemplo para diferentes entidades
  • __mocks__/field-layout.mock.ts - Campos de layout com diversas configurações
  • __mocks__/contact.mock.ts - Dados de contatos

Padrões e Arquitetura​

Instâncias dos Serviços​

Cada serviço possui um arquivo de instância que exporta uma instância singleton:

  • services/client/client.service.instance.ts
  • services/layout/layout.instance.ts
  • services/field-layout/field-layout.instance.ts
  • services/contact/contact.service.instance.ts

Exemplo de uso:

import { clientService } from "@/services/client/client.service.instance";

const clients = await clientService.fetchRemote({ page: 0, size: 20 });

Offline-First (Client Service)​

O ClientService implementa padrão offline-first:

  1. Sincronização: Dados são baixados da API e salvos localmente
  2. Cache Local: App trabalha com dados do banco local (SQLite)
  3. Busca Híbrida: Busca remota quando necessário + filtros locais
  4. Performance: Reduz latência e permite operação offline

Formulários Dinâmicos (Layout & Field Layout)​

Os serviços de Layout e Field Layout permitem renderização dinâmica de formulários:

  1. Buscar Layout: Obter configuração do layout para uma entidade
  2. Processar Campos: Iterar sobre os campos do layout
  3. Renderizar UI: Criar inputs baseados nas configurações
  4. Validar: Aplicar regras de validação (obrigatório, editável, etc.)
  5. Submeter: Enviar dados para o serviço correspondente (Client, Contact, etc.)

Validações com Zod​

Todos os schemas de cadastro/atualização usam Zod para validação:

  • Validação em tempo de execução
  • Type-safe (TypeScript)
  • Mensagens de erro customizadas
  • Regras complexas (refinements)

Exemplo:

import { clientRegisterBaseSchema } from "@/types/client/client-register.type";

const validated = clientRegisterBaseSchema.parse(formData);
// Se passar, dados estão válidos e tipados