API TechBull Sistemas

Para integrar com o TechBull, o fluxo básico é:

1. Fazer login com email e senha para obter um token de sessão.
2. Enviar esse token em todas as próximas chamadas (via Cookie ou Authorization, conforme a rota).
3. Consumir os endpoints aos quais o seu usuário tem permissão (configurada pelo admin da holding).

Todas as rotas estão sob o domínio do app principal:

https://app.techbullsistemas.com.br

Os exemplos abaixo usam paths relativos como /api/venda — basta concatenar com a base URL.

• Conteúdo enviado e recebido: Content-Type: application/json.
• Datas em ISO-8601 (UTC), por exemplo 2026-04-19T12:00:00.000Z.
• Códigos HTTP padrão (200, 400, 401, 403, 404, 422, 500).

Códigos HTTP usados pela API:

• 200 / 201 — sucesso.
• 400 — erro de validação (campos faltando ou inválidos).
• 401 — não autenticado (sessão ausente ou expirada).
• 403 — autenticado mas sem permissão para a ação.
• 404 — recurso não encontrado.
• 409 — conflito (ex.: violação de chave estrangeira).
• 422 — entidade não processável.
• 500 — erro interno.

Após o login você recebe um token que precisa ser enviado nas próximas requisições. Existem duas formas conforme o tipo da rota:

Cada rota da API exige uma feature (string identificadora) que o usuário precisa ter habilitada. Por exemplo:

• vendas:consultar — listar vendas.
• vendas:efetivar — efetivar pré-venda em venda.
• clientes:cadastrar — criar novos clientes.
• titulosReceber:consultar — listar títulos a receber.
• caixa:recebimentoTitulo — dar baixa em títulos.

O administrador da holding (usuário 1) tem todas as features e é responsável por habilitar permissões para os demais usuários através do painel administrativo. Cada endpoint nesta documentação indica a permissão necessária no badge laranja.

A entidade principal é a prevenda. O campo id_situacao identifica o estado:

Fluxo típico: POST /api/venda (cria em AB) → POST /api/venda/efetivar (move para EF) → opcionalmente POST /api/venda/estornar (volta para CA).

Um cliente pode ter múltiplos representantes (vendedores) associados a ele. O vínculo é feito via tabela auxiliar cliente_vendedor (modelo Prisma ClienteVendedor), que substitui o antigo campo cliente.cd_vendedor (removido).

Tabela cliente_vendedor

Escopo de sincronização no app mobile

As rotas /api/mobile/sync/* que retornam dados relacionados a clientes (cliente, cidade, nota fiscal de saída e título a receber) passam a filtrar de acordo com o flag do usuário autenticado:

• idTodosClientesApp = true: o usuário enxerga todos os clientes da holding (sem filtro por representante).
• idTodosClientesApp = false (default): o usuário só enxerga clientes onde ele está na tabela cliente_vendedor como vendedor. Rotas que derivam de cliente (cidade, nota-fiscal-saida, titulo-receber) usam o mesmo escopo.

Cadastro offline (upload)

Ao receber um cliente cadastrado pelo app (POST /api/mobile/upload/cliente), o backend agora registra automaticamente um vínculo em cliente_vendedor entre o novo cliente e o usuário que fez o upload. Isso garante que o representante que cadastrou o cliente consiga vê-lo de volta, mesmo que seu idTodosClientesApp esteja em false.

Gerenciando vínculos pelo endpoint /api/users

Os campos idTodosClientesApp e clientesVendedor[] agora fazem parte do payload de POST / PUT em /api/users. OGET /api/users inclui clientesVendedor no retorno (com cdCliente, nmCliente e cpf) para facilitar a renderização da lista no ERP.

Existem duas formas de anexar uma imagem a um cliente/produto:

Todas as imagens ficam no bucket:

techbull-20bd5.appspot.com

Organizadas por holding e categoria, no caminho {holdingId}/images/{categoria}/{nome}.{ext}:

A API sempre retorna o par fotoToken + fotoNome (ou os equivalentes em fotoCliente/fotoProduto). Com esses valores você monta a URL pública de download com o seguinte template:

https://firebasestorage.googleapis.com/v0/b/techbull-20bd5.appspot.com/o/{holdingId}%2Fimages%2F{categoria}%2F{nome}.{ext}?alt=media&token={token}

Onde {token} é o valor de fotoToken sem a extensão (tudo antes do último ponto) e {ext} é a extensão (depois do último ponto).

Exemplo (TypeScript)

function getPhotoUrl(
  holdingId: number,
  categoria: 'cliente' | 'produto' | 'loja-online-produto',
  fotoNome: string,
  fotoToken: string,
) {
  const [token, ext = 'jpg'] = fotoToken.split('.');
  const caminho = `${holdingId}/images/${categoria}/${fotoNome}.${ext}`;
  return (
    'https://firebasestorage.googleapis.com/v0/b/' +
    'techbull-20bd5.appspot.com/o/' +
    encodeURIComponent(caminho) +
    `?alt=media&token=${token}`
  );
}

Todas as entidades abaixo aceitam os mesmos métodos:

• GET — lista/consulta com filtros (apenas autenticação).
• POST — criar (exige permissão de cadastrar).
• PUT — atualizar (exige permissão de editar).
• DELETE — excluir (exige permissão de excluir).

Para descobrir os campos exatos do body, consulte os validations.ts da entidade no projeto principal ou faça um GET e use o retorno como referência.

• /api/formaPagamento — aceita apenas GET e PUT (não há criar/excluir isoladamente; o PUT funciona como upsert/atualização em lote). Permissão: formaPagamento:editar.
• /api/cidade — público (não exige token).

Os bodies abaixo refletem o que a API valida no momento da criação (POST).

POST /api/marca

POST /api/grupoProduto

POST /api/unidade

Toda movimentação de estoque referencia uma operação previamente cadastrada (cdOperacaoEstoque) que define se ela soma (entrada) ou subtrai (saída) do saldo. Para popular o estoque inicial de um produto recém-criado, use uma operação de entrada (ex.: ajuste / inventário).

O campo request_id é útil para suporte: anote-o e informe ao time TechBull caso precise investigar uma falha específica.

Quando o body bate na validação Joi mas falha no Prisma (campo obrigatório esquecido, argumento desconhecido, tipo errado), a API responde com 422 e a mensagem inclui o detalhe acionável extraído da resposta do Prisma: