Catálogo da API REST

Versão: v1
Última atualização: 23/07/2026
Prefixo: /api/v1

Este catálogo descreve os endpoints implementados no backend NestJS. Os contratos devem ser atualizados junto com o código sempre que houver mudança.

Endereços

Convenções

• Conteúdo JSON usa Content-Type: application/json.
• Upload manual usa multipart/form-data.
• Datas de entrada usam preferencialmente YYYY-MM-DD.
• Data e hora usam ISO 8601.
• Valores monetários são números decimais.
• Endpoints protegidos recebem Authorization: Bearer <accessToken>.
• Listagens respeitam empresa, lojas e vendedor do usuário autenticado.

Perfis abreviados

Quando a tabela informa autenticado, o serviço aplica o escopo do papel recebido no token.

Respostas e erros

Ao receber 401, o frontend encerra a sessão local e redireciona para o login.

Saúde e autenticação

Exemplo de login:

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "usuario@empresa.com",
  "password": "senha-fornecida-em-canal-seguro"
}

A resposta contém accessToken, refreshToken e os dados do usuário. Tokens e credenciais não devem ser gravados em logs de aplicação.

Resposta do health check:

{
  "status": "ok",
  "service": "gv-api",
  "version": "0.1.0"
}

Dados iniciais

/app-data abastece seletores e experiências do frontend. Não substitui os endpoints transacionais.

Lojas

Campos principais: code, name, format (Loja, Quiosque ou Outlet), operation, city, state, brandId, regionId, supervisorId, cnpj, protheusCode, operatingDays, openTime e closeTime.

operatingDays usa os números de dia da semana do JavaScript: domingo 0, segunda 1 até sábado 6.

Usuários do backoffice

Campos principais: nome, e-mail, senha, papel, foto, loja, vigência profissional, férias e situação. A troca de cargo usa atualização ou conversão e deve preservar a identidade, o histórico e a auditoria da pessoa.

Upload de fotos

O corpo usa multipart/form-data, com o arquivo no campo file. São aceitos JPG, PNG e WebP com até 2 MB. A API valida e recodifica a imagem como WebP 512x512, remove os metadados do arquivo original e responde com photoUrl, path, filename e mimeType. O cadastro de usuário ou vendedor persiste somente a URL; o arquivo fica no diretório definido por UPLOAD_DIR.

Vendedores, lotação e ausências

Uma lotação recebe storeId, type, startsAt, endsAt e notes. A transferência recebe a nova loja, a data de início e a observação. Uma ausência recebe início, fim, motivo e observação. As mutações de ausência retornam affectedGoalCycles com as metas que cruzam o período alterado para o frontend solicitar o recálculo.

No cadastro de vendedor, pdvCode é obrigatório. Para vendas Protheus, o vínculo usa document/CPF como chave principal e storeId + pdvCode como alternativa.

Metas

Criação do ciclo:

{
  "storeId": "uuid-da-loja",
  "name": "Meta 07/2026",
  "startsAt": "2026-07-01",
  "endsAt": "2026-07-31"
}

A edição estrutural da distribuição usa allocations. Esse formato permite incluir ou remover linhas quando férias, ausências ou lotações alteram os dias disponíveis:

{
  "allocations": [
    {
      "sellerId": "uuid-do-vendedor",
      "date": "2026-08-21",
      "amount1": 5000,
      "amount2": 5750,
      "amount3": 6500
    }
  ]
}

A API valida escopo, vendedor, período, loja, disponibilidade e duplicidade de vendedor/data. Em seguida recria as metas diárias e consolida os totais de cada vendedor e da loja em uma transação auditada.

O recálculo por disponibilidade soma primeiro a distribuição já existente para preservar a meta de cada data. Depois reparte cada dia somente entre os vendedores do ciclo que estejam disponíveis conforme férias, ausências, vigência e lotação.

A importação diária recebe todos os dias do mês para cada loja. amount2 e amount3 são opcionais; quando ausentes, a API calcula 115% e 130% da meta principal. Com dryRun=true, todas as validações e o rateio são simulados sem gravação.

{
  "dryRun": false,
  "rows": [
    {
      "storeId": "uuid-da-loja",
      "date": "2026-08-01",
      "amount1": 22000
    },
    {
      "storeId": "uuid-da-loja",
      "date": "2026-08-02",
      "amount1": 0
    }
  ]
}

O lote é transacional: conflito de loja/mês, data ausente, duplicidade, valor inválido ou dia positivo sem vendedor impede a gravação de todos os ciclos. A meta de cada dia é dividida em centavos entre os vendedores disponíveis, com diferença máxima de um centavo entre as parcelas.

A distribuição recebe uma lista de metas diárias:

{
  "dailyGoals": [
    {
      "id": "uuid-meta-diaria",
      "amount1": 1200,
      "amount2": 1320,
      "amount3": 1440
    }
  ]
}

Campanhas, motivos e feriados

O feriado informa nome, data, tipo (HOLIDAY ou OPTIONAL_DAY), abrangência, estado, cidade, lojas, e se deve ser excluído dos dias da meta.

Tablet e atendimentos

Eventos implementados para atendimento:

• ATTENDANCE_STARTED;
• ATTENDANCE_FINISHED;
• STORE_DAY_ENDED, registrado no encerramento do dia.

Exemplo de evento:

{
  "clientEventId": "uuid-gerado-no-tablet",
  "deviceId": "uuid-dispositivo",
  "storeId": "uuid-loja",
  "eventType": "ATTENDANCE_FINISHED",
  "createdAtLocal": "2026-07-23T18:30:00-03:00",
  "payload": {
    "attendanceId": "uuid-atendimento",
    "result": "NOT_CONVERTED",
    "lossReasonId": "uuid-motivo"
  }
}

O backend usa clientEventId para impedir duplicidade na sincronização offline.

Vendas

Cada venda importada informa loja, vendedor opcional, identificador externo, data, valor e quantidade de peças.

Validação diária

Validação de um dia:

{
  "storeId": "uuid-loja",
  "date": "2026-07-22",
  "notes": "Conferido com o fechamento da loja",
  "autoUpdateBlocked": true,
  "rows": [
    {
      "validationId": "uuid-validacao",
      "adjustedSalesAmount": 12540.9,
      "adjustedPiecesQuantity": 32,
      "adjustedSalesQuantity": 18
    }
  ]
}

Sem mudança de valor, o status é validado. Havendo alteração, fica validado com edição manual. O usuário, a data e a justificativa são auditados.

Validação de NF

Filtros da lista: storeId, status, dateFrom, dateTo, issueType e search. Tipos atuais: vendedor ausente, valor, quantidade, vendedor, data ou loja alterados. O resumo aceita storeId, operation, dateFrom e dateTo. O reprocessamento de vendedores respeita o mesmo escopo de loja/operação e usa CPF ou a combinação loja + código PDV, sem criar ou alterar cadastros de funcionários.

{
  "sellerId": "uuid-vendedor-ou-null",
  "soldAt": "2026-07-22",
  "amount": 899.9,
  "piecesQty": 2,
  "includedInMetrics": true,
  "notes": "Conferido com a loja"
}

includedInMetrics=false mantém a NF no histórico, mas a retira dos dashboards, metas e agregações comerciais.

Relatórios e feedbacks

O analítico aceita storeId, sellerId, dateFrom, dateTo, status, origin, search e take.

No consolidado do Dashboard, salesAmount, salesQuantity e piecesQuantity consideram somente vendas com vendedor vinculado. O campo unidentifiedSalesAmount retorna separadamente o valor pendente das NFs sem vendedor.

Integrações e configurações

O upload usa o campo multipart file, aceita até 10 MB e os formatos .xlsx, .xls e .csv.

A sincronização Protheus trata o cadastro de vendedores como somente leitura: não cria nem atualiza pessoas. O resultado informa sellerMatches e sellerNotFound; movimentos sem correspondência geram MISSING_SELLER no Validador NF.

Parâmetros disponíveis:

• timezone, currency e dateFormat;
• sellerPinDigits e tabletIdleMinutes;
• validationTolerance e goalRounding;
• dataSource, com protheus ou manual;
• dailySyncTime e protheusReviewDays;
• protheusClosingDay e protheusClosingTime.

Filtros de auditoria: limit, personId, entityId e actorUserId.

Teste rápido

curl https://api.technos.projeto.dbai.com.br/api/v1/health

Para uma chamada protegida:

curl \
  -H "Authorization: Bearer $GV_ACCESS_TOKEN" \
  "https://api.technos.projeto.dbai.com.br/api/v1/stores"

Limitações documentais atuais

O projeto ainda não publica uma especificação OpenAPI/Swagger gerada automaticamente. Este catálogo e os controllers NestJS são a referência vigente. Adicionar geração OpenAPI é recomendado antes da abertura da API a terceiros.