Documentação da API

API TechBull Sistemas

Conecte seu ERP, e-commerce ou aplicativo próprio diretamente ao TechBull. Esta documentação cobre autenticação, vendas, clientes, produtos, títulos a receber e a pagar, agendamentos (interno e público) e entidades de apoio.

Começando

A API TechBull é uma API REST que retorna JSON. Todas as rotas estão sob o domínio do app principal e exigem autenticação por sessão (exceto onde indicado).

Introdução

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

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

Base URL e formato

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

Base URL

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).

Convenções

Campos em camelCase

Os campos documentados para entrada e saída usam camelCase. Espere nomes como cdEmpresa, nrPrevenda, idSituacao e prevendaItem.

Algumas integrações legadas podem trabalhar internamente com nomes de colunas em snake_case, mas os contratos e exemplos públicos desta documentação usam camelCase.

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.

Autenticação

A autenticação é baseada em token de sessão gerado no login (96 caracteres hexadecimais). O token tem validade de 30 dias.

Visão geral

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:

Rotas Mobile (/api/mobile/*)

Authorization: Bearer <token>

Demais rotas (vendas, clientes, etc.)

Cookie: session_id=<token>

Mesmo token, dois envios

O valor é exatamente o mesmo. Você pode armazenar o token uma única vez e enviá-lo como Authorization: Bearer ao chamar /api/mobile/* e como cookie session_id ao chamar as demais rotas (vendas, produtos, clientes, títulos, etc.).

Fazer login

POST/api/mobile/auth/login

Público

Autentica usuário com email e senha e retorna o token da sessão, o ID da sessão, a data de expiração e os dados básicos do usuário.

Body parameters

Parâmetro	Tipo	Obrig.	Descrição
`email`	string	Sim	Email do usuário cadastrado.
`senha`	string	Sim	Senha do usuário.
`timezone`	string	—	Fuso horário IANA. Padrão `America/Sao_Paulo`.

Exemplo de requisição

cURL

curl -X POST https://app.techbullsistemas.com.br/api/mobile/auth/login \

-H "Content-Type: application/json" \

-d '{

"email": "voce@empresa.com",

"senha": "sua-senha",

"timezone": "America/Sao_Paulo"

Resposta — 200 OK

response.json

{

"token": "a3f9c1e2b4d6...96-chars-hex...",

"sessionId": 42,

"expiresAt": "2026-05-19T12:00:00.000Z",

"user": {

"userId": 7,

"holdingId": 3,

"cdEmpresa": 1,

"nome": "Maria Silva",

"email": "voce@empresa.com",

"idAtivo": true

}

Guarde o token com segurança

O token tem validade de 30 dias. Trate-o como uma senha — não exponha em URLs nem em logs.

Obter usuário autenticado

GET/api/mobile/auth/me

Authorization: Bearer

Retorna informações do usuário associado ao token. Útil para validar se o token continua válido.

cURL

curl https://app.techbullsistemas.com.br/api/mobile/auth/me \

-H "Authorization: Bearer a3f9c1e2b4d6..."

Fazer logout

POST/api/mobile/auth/logout

Authorization: Bearer

Invalida o token de sessão atual no servidor.

cURL

curl -X POST https://app.techbullsistemas.com.br/api/mobile/auth/logout \

-H "Authorization: Bearer a3f9c1e2b4d6..."

Permissões

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.

Se uma chamada retornar 403 ForbiddenError com "Usuário não autorizado a realizar esta ação", peça ao admin da holding para conceder a feature correspondente ao seu usuário.

Listar catálogo de features

GET/api/feature

Cookie session_idfeature:consultar

Lista todas as features disponíveis no sistema. Útil para que o admin saiba quais permissões pode conceder.

cURL

curl https://app.techbullsistemas.com.br/api/feature \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Vendas e Pré-vendas

Toda venda começa como pré-venda (em aberto). Após efetivar, vira uma venda concretizada com nota fiscal, títulos gerados, movimentação de caixa e estoque. Pode ser cancelada ou estornada.

Conceito e ciclo de vida

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

AB

Aberta — pré-venda em rascunho, ainda editável.

EF

Efetivada — venda concretizada, com nota fiscal e títulos.

CA

Cancelada — pré-venda cancelada ou venda estornada.

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

Listar vendas

GET/api/venda

Cookie session_idvendas:consultar

Lista pré-vendas e vendas com filtros e paginação. Use idSituacao para filtrar por estado.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdEmpresa`	number	—	Filtra por empresa.
`idSituacao`	string	—	`AB`, `EF` ou `CA`.
`dtIni`	date (YYYY-MM-DD)	—	Data inicial.
`dtFim`	date (YYYY-MM-DD)	—	Data final.
`cdFuncionario`	number	—	Vendedor responsável.
`cdTipoVenda`	number	—	Tipo de venda.
`cdFormaPagamento`	number	—	Forma de pagamento.
`page`	number	—	Página (default 1).
`limit`	number	—	Itens por página (default 50).

cURL

curl "https://app.techbullsistemas.com.br/api/venda?cdEmpresa=1&idSituacao=EF&page=1&limit=10" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Resposta — 200 OK

response.json

{

"results": [

{

"nr_prevenda": 12345,

"cd_empresa": 1,

"cd_cliente": 100,

"id_situacao": "EF",

"vl_total": 150.50,

"dt_emissao": "2026-04-19T10:30:00.000Z",

"nr_nota": 9876,

"serie_nota": "1",

"prevenda_item": [ /* ... */ ],

"prevenda_titulo": [ /* ... */ ],

"prevenda_forma_pagamento": [ /* ... */ ]

}

"has_more_pages": true

}

Criar pré-venda

POST/api/venda

Cookie session_idvendas:cadastrar

Cria uma pré-venda em situação AB. Se enviar efetivar_venda: true, a venda já é efetivada na mesma chamada (requer também a feature vendas:efetivar).

Body parameters principais

Parâmetro	Tipo	Obrig.	Descrição
`cd_empresa`	number	Sim	Código da empresa.
`cd_cliente`	number	Sim	Código do cliente.
`cd_funcionario`	number	Sim	Vendedor.
`id_situacao`	string	Sim	Use `"AB"` para criar em aberto.
`vl_total`	number	Sim	Valor total da venda.
`vl_bruto`	number	Sim	Valor bruto antes de descontos.
`cd_forma_pagamento`	number	Sim	Forma de pagamento principal.
`cd_tipo_venda`	number	Sim	Tipo da venda.
`prevenda_item`	array	Sim	Itens da venda (produtos, quantidade, valores).
`prevenda_titulo`	array	Sim	Títulos a receber gerados.
`prevenda_forma_pagamento`	array	Sim	Detalhamento das formas de pagamento.
`efetivar_venda`	boolean	—	Se true, efetiva já na criação.

Exemplo de requisição

request body

{

"cd_empresa": 1,

"cd_cliente": 100,

"cd_funcionario": 5,

"id_situacao": "AB",

"pr_desconto": 0,

"vl_desconto_total": 0,

"pr_acrescimo": 0,

"vl_acrescimo_total": 0,

"vl_acrescimo_total_item": 0,

"vl_bruto": 150.50,

"vl_total": 150.50,

"cd_forma_pagamento": 1,

"id_utiliza_credito_devolucao": "N",

"cd_tipo_venda": 1,

"prevenda_item": [

{

"cd_produto": 200,

"qt_produto": 1,

"vl_unitario": 150.50,

"vl_custo": 80,

"vl_desconto": 0,

"vl_acrescimo": 0,

"pr_comissao": 0,

"cd_funcionario": 5,

"qt_entrega_separacao": 0,

"qt_entrega_conferido": 0,

"id_produto_promocao": "N",

"qt_devolvido": 0,

"vl_promocao": 0

}

"prevenda_titulo": [

{

"dt_vencto": "2026-05-19T00:00:00.000Z",

"vl_titulo": 150.50,

"nr_forma": 1

}

"prevenda_forma_pagamento": [

{

"id_forma_pagamento": 1,

"nr_parcela": 1,

"vl_parcela": 150.50,

"vl_total": 150.50,

"vl_forma_original": 150.50

}

"prevenda_funcionario_auxiliar": []

}

Resposta — 200 OK

response.json

{

"prevenda_efetivada": {

"nr_prevenda": 12346,

"cd_empresa": 1,

"id_situacao": "AB",

"vl_total": 150.50

"nfe": null

}

Atualizar pré-venda

PUT/api/venda

Cookie session_idvendas:editar

Atualiza uma pré-venda existente. Substitui itens, títulos e formas quando enviados. Requer nr_prevenda.

O body é o mesmo do POST, com nr_prevenda obrigatório. Pode incluir efetivar_venda: true para atualizar e efetivar na mesma chamada.

Cancelar pré-venda

DELETE/api/venda

Cookie session_idvendas:excluir

Cancela uma pré-venda em aberto. Não funciona em vendas já efetivadas (use /api/venda/estornar).

request body

{

"cd_empresa": 1,

"nr_prevenda": 12345,

"motivo_cancela": "Cliente desistiu"

}

Efetivar venda

POST/api/venda/efetivar

Cookie session_idvendas:efetivar

Efetiva uma pré-venda em aberto: gera a nota fiscal de saída, títulos a receber, movimenta caixa, estoque e crédito do cliente. A pré-venda passa para EF e recebe nr_nota e serie_nota.

cURL

curl -X POST https://app.techbullsistemas.com.br/api/venda/efetivar \

-H "Content-Type: application/json" \

-H "Cookie: session_id=a3f9c1e2b4d6..." \

-d '{ "cd_empresa": 1, "nr_prevenda": 12345 }'

Resposta — 200 OK

response.json

{

"prevenda_efetivada": {

"nr_prevenda": 12345,

"id_situacao": "EF",

"nr_nota": 9876,

"serie_nota": "1",

"dt_efetivacao": "2026-04-19T14:32:11.000Z"

"nfe": {

"success": true,

"data": { /* dados do retorno da NFC-e/NF-e */ }

}

Pré-requisito: o caixa da empresa deve estar aberto. Caso contrário a API retorna "Caixa não encontrado".

Estornar venda

POST/api/venda/estornar

Cookie session_idvendas:estornar

Estorna uma venda já efetivada (EF): cancela a nota fiscal, reverte estoque, títulos, caixa e crédito. A pré-venda passa para CA e nr_nota/serie_nota são limpos.

request body

{

"cd_empresa": 1,

"nr_prevenda": 12345

}

Editar venda efetivada

PUT/api/venda/update-efetivada

Cookie session_idvendas:editar

Ajusta dados não-financeiros de uma venda já efetivada (tipo de venda, observação, vendedor, vendedores auxiliares), espelhando na nota fiscal quando existir.

request body

{

"cd_empresa": 1,

"nr_prevenda": 12345,

"cd_tipo_venda": 2,

"obs": "Cliente preferencial",

"cd_funcionario": 5,

"prevenda_funcionario_auxiliar": [

{ "cd_funcionario": 8, "pr_comissao": 1.5 }

]

}

Atualizar formas de pagamento

POST/api/venda/updateFormaPagamento

Cookie session_idvendas:editar

Atualiza as formas de pagamento, títulos e totais de uma venda (ex.: cliente decide parcelar diferente).

request body

{

"cd_empresa": 1,

"nr_prevenda": 12345,

"vl_acrescimo_total": 0,

"vl_total": 200.00,

"prevenda_forma_pagamento": [

{

"id_forma_pagamento": 1,

"nr_parcela": 1,

"vl_parcela": 200.00,

"vl_total": 200.00,

"vl_forma_original": 200.00

}

"prevenda_titulo": [

{

"dt_vencto": "2026-05-19T00:00:00.000Z",

"vl_titulo": 200.00,

"nr_forma": 1

}

]

}

Relatórios

Consultas consolidadas para integração, com filtros e totais já calculados pelo TechBull.

Relatório de notas fiscais

GET/api/notaFiscalRelatorio

Cookie session_idrelatorio:notaFiscal

Lista NF-e, NFC-e e recibos D1 emitidos no período. O retorno contém os dados resumidos de cada nota e os totais consolidados da consulta.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdEmpresa`	number	Sim	Código da empresa.
`dtIni`	date (YYYY-MM-DD)	Sim	Data inicial do período de emissão.
`dtFim`	date (YYYY-MM-DD)	Sim	Data final do período de emissão.
`nrNota`	number	—	Filtra pelo número da nota.
`nmCliente`	string	—	Busca parcial pelo nome do cliente.
`idSerie`	string	—	Tipo da nota: `D1`, `NFC` ou `NFE`.
`situacao`	string	—	`PR` para autorizada, `PE` para pendente ou `CA` para cancelada.

cURL

curl "https://app.techbullsistemas.com.br/api/notaFiscalRelatorio?cdEmpresa=1&dtIni=2026-08-01&dtFim=2026-08-31&idSerie=NFE&situacao=PR" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Valores considerados

O valor do relatório considera somente itens de produto. Notas compostas apenas por serviços não aparecem na listagem.

Resposta — 200 OK

response.json

{

"results": [

{

"nr_nota": 9876,

"serie": "1",

"dt_emissao": "2026-08-12T14:30:00.000Z",

"nm_cliente": "Cliente Exemplo",

"nr_prevenda": 12345,

"vl_total_produtos": 150.50,

"id_situacao": "PR",

"ds_situacao": "Autorizada",

"ds_tipo_nota": "NF-e",

"nr_chave_acesso": "35260812345678000190550010000098761234567890"

}

"totais": {

"total_quantidade": 1,

"total_valor": 150.50,

"total_d1": 0,

"total_autorizada": 1

}

Notas fiscais com produtos

GET/api/notaFiscalRelatorio/detalhado

Cookie session_idrelatorio:notaFiscal

Lista as notas fiscais e inclui todos os itens de cada nota no array produtos. O retorno é um array JSON direto, paginado pelos parâmetros page e limit.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdEmpresa`	number	—	Código da empresa. Quando omitido, consulta todas as empresas permitidas da holding.
`nrNota`	number	—	Número exato da nota.
`serie`	string	—	Série exata da nota. Não pode ser combinada com idSerie.
`dtIni`	date (YYYY-MM-DD)	—	Data inicial de emissão. Deve ser enviada junto com dtFim.
`dtFim`	date (YYYY-MM-DD)	—	Data final de emissão, inclusive. Deve ser enviada junto com dtIni.
`cdCliente`	number	—	Código exato do cliente.
`nmCliente`	string	—	Busca parcial pelo nome do cliente.
`cpf`	string	—	Busca parcial por CPF ou CNPJ do cliente.
`cdProduto`	number	—	Código exato do produto presente na nota.
`nmProduto`	string	—	Busca parcial pela descrição do produto.
`cdReferencia`	string	—	Busca parcial pela referência do produto.
`cdGrupo`	number	—	Código do grupo de produto.
`cdMarca`	number	—	Código da marca do produto.
`cdFornecedor`	number	—	Código do fornecedor do produto.
`idTipoProduto`	string	—	`P` para produto ou `S` para serviço.
`cdFuncionario`	number	—	Código do vendedor/funcionário da nota.
`cdNatureza`	number	—	Código da natureza de operação.
`cdTipoVenda`	number	—	Código do tipo de venda.
`idFormaPagamento`	number	—	Código da forma de pagamento da nota.
`idSerie`	string	—	Tipo da nota: `D1`, `NFC` ou `NFE`. Não pode ser combinado com `serie`.
`situacao`	string	—	`PR` para autorizada, `PE` para pendente ou `CA` para cancelada.
`nrChaveAcesso`	string	—	Busca parcial pela chave de acesso da nota.
`page`	number	—	Página da consulta. Padrão: 1.
`limit`	number	—	Quantidade de notas por página. Padrão: 100; máximo: 500.
`order`	string	—	Ordenação pela data de emissão: desc (padrão) ou asc.

cURL

curl "https://app.techbullsistemas.com.br/api/notaFiscalRelatorio/detalhado?cdEmpresa=1&dtIni=2026-08-01&dtFim=2026-08-31&cdProduto=200&page=1&limit=100" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

O filtro de produto seleciona a nota

Se uma nota possuir o produto filtrado, ela será incluída e o array produtos trará todos os itens dessa nota — não apenas o produto usado no filtro.

Paginação do array

A resposta não possui envelope: ela é um json[]. Solicite as páginas seguintes até receber um array vazio.

Resposta — 200 OK

response.json

[

{

"nrNota": 9876,

"cdEmpresa": 1,

"serie": "1",

"dsTipoNota": "NF-e",

"dtDigitacao": "2026-08-12T14:29:45.000Z",

"dtEmissao": "2026-08-12T14:30:00.000Z",

"dtSaida": "2026-08-12T14:30:00.000Z",

"cdCliente": 150,

"nmCliente": "Cliente Exemplo",

"cpf": "12345678000190",

"cdFuncionario": 5,

"nmFuncionario": "Vendedor Exemplo",

"cdNatureza": 1,

"dsNatureza": "Venda de mercadoria",

"cdTipoVenda": 2,

"dsTipoVenda": "Venda normal",

"idFormaPagamento": 1,

"nrPrevenda": 12345,

"idSituacao": "PR",

"dsSituacao": "Autorizada",

"nrChaveAcesso": "35260812345678000190550010000098761234567890",

"obs": null,

"vlTotalProdutos": 230.40,

"vlDescontoTotal": 10.00,

"vlFrete": 0,

"vlIcms": 41.47,

"vlIpi": 0,

"vlServico": 0,

"vlIss": 0,

"vlTotalNota": 220.40,

"produtos": [

{

"cdProduto": 200,

"cdReferencia": "CAM-PT-M",

"dsProduto": "Camiseta preta M",

"idTipoProduto": "P",

"cdGrupo": 10,

"dsGrupo": "Camisetas",

"cdMarca": 3,

"dsMarca": "Marca Exemplo",

"cdFornecedor": 8,

"nmFornecedor": "Fornecedor Exemplo",

"cdUnidade": 1,

"dsUnidade": "UN",

"cdAgrupador": 4,

"cdProdutoBarraEan": "7891234567890",

"idSituacao": "PR",

"qtProduto": 3,

"qtDevolvido": 0,

"qtLiquida": 3,

"vlUnitario": 79.90,

"vlDesconto": 9.30,

"vlDescontoPromocao": 0,

"vlAcrescimo": 0,

"vlAcrescimoFinanceiro": 0,

"vlOutrasDespesas": 0,

"vlFrete": 0,

"vlTotalItem": 230.40,

"cdSituacaoTributaria": "000",

"prIcms": 18,

"vlIcms": 41.47,

"prIpi": 0,

"vlIpi": 0,

"prPis": 1.65,

"prCofins": 7.6

}

]

}

]

Relatório de produtos vendidos

GET/api/produtosVendidos

Cookie session_idrelatorio:produtosVendidos

Consolida produtos ou serviços vendidos no período, com quantidade, custo, valor de venda, preço médio e margem. É possível consultar várias empresas e agrupar o resultado por produto, grupo, marca ou fornecedor.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdEmpresas`	number[]	Sim	Códigos das empresas separados por vírgula, por exemplo 1,2.
`dtIni`	date (YYYY-MM-DD)	Sim	Data inicial do período de emissão.
`dtFim`	date (YYYY-MM-DD)	Sim	Data final do período de emissão.
`idTipoProduto`	string	—	`TODOS` (padrão), `P` para produtos ou `S` para serviços.
`idAgrupamento`	string	—	`PRODUTO` (padrão), `GRUPO`, `MARCA` ou `FORNECEDOR`.
`cdGrupos`	number[]	—	Códigos dos grupos separados por vírgula.
`cdMarca`	number	—	Filtra por uma marca.
`cdFornecedor`	number	—	Filtra por um fornecedor.
`busca`	string	—	Busca por descrição ou referência do produto.

cURL

curl "https://app.techbullsistemas.com.br/api/produtosVendidos?cdEmpresas=1,2&dtIni=2026-08-01&dtFim=2026-08-31&idTipoProduto=P&idAgrupamento=PRODUTO&busca=camiseta" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Regras do relatório

São consideradas notas de saída normais, com natureza de faturamento. Notas avulsas são excluídas e as devoluções são descontadas da quantidade e dos valores.

Permissão para valores e agrupamentos

A rota exige relatorio:produtosVendidos. Para exibir custo, valor de venda e margem, além de agrupar por grupo, marca ou fornecedor, o usuário também precisa de relatorios:vendas.

Resposta — 200 OK

response.json

{

"exibeValoresVenda": true,

"items": [

{

"groupKey": 200,

"dsLabel": "Camiseta preta · M",

"cdReferencia": "CAM-PT-M",

"dsGrupo": "Camisetas",

"dsMarca": "Marca Exemplo",

"dsFornecedor": "Fornecedor Exemplo",

"cdProduto": 200,

"qtVendida": 12,

"vlCustoTotal": 300.00,

"vlVendaTotal": 958.80,

"vlPrecoMedio": 79.90,

"prMargem": 68.71

}

"totais": {

"qtVendida": 12,

"vlCustoTotal": 300.00,

"vlVendaTotal": 958.80,

"prMargem": 68.71

"idAgrupamento": "PRODUTO"

}

Clientes

CRUD de clientes da holding, com filtros avançados (aniversário, crédito, datas de cadastro, ordenação) e suporte a formulários dinâmicos.

Listar clientes

GET/api/cliente

Cookie session_id

Apenas autenticação é exigida (sem permissão específica).

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`id`	string	—	IDs separados por vírgula.
`name`	string	—	Busca por nome.
`cpf`	string	—	CPF/CNPJ.
`fone`	string	—	Telefone.
`cdCidade`	number	—	Código da cidade.
`periodoAniversarioIni`	date	—	Início do período de aniversário.
`periodoAniversarioFim`	date	—	Fim do período de aniversário.
`vlCreditoClienteMin`	number	—	Crédito mínimo.
`vlCreditoClienteMax`	number	—	Crédito máximo.
`orderBy[field]`	string	—	Campo de ordenação.
`orderBy[direction]`	asc \| desc	—	Direção da ordenação.
`page`	number	—	Página.
`limit`	number	—	Itens por página.

cURL

curl "https://app.techbullsistemas.com.br/api/cliente?name=Maria&page=1&limit=20" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Referências comerciais no retorno

Cada cliente pode retornar cdTelevendas, cdClienteGrupo e cdTabelaPrecoCondicao. Os três campos são opcionais e podem ser null.

O vendedor responsável é uma relação separada e deve ser consultado em GET /api/clienteVendedor. Já cdTelevendas identifica especificamente o televendas configurado no ERP de origem.

Criar cliente

POST/api/cliente

Cookie session_idclientes:cadastrar

Cria um novo cliente. Aceita endereço, dependentes (clienteDependente) e anexos (clienteAnexo) opcionais.

Campos obrigatórios

Parâmetro	Tipo	Obrig.	Descrição
`cdEmpresa`	number	Sim	Empresa de origem do cadastro.
`nmCliente`	string	Sim	Nome ou razão social.
`tpPessoa`	"F" \| "J"	Sim	Pessoa Física ou Jurídica.
`cdCategoria`	number	Sim	Categoria do cliente.
`cdSituacaoCliente`	number	Sim	Situação cadastral.
`idTipoCliente`	string	Sim	Tipo de cliente.
`vlLimiteCredito`	number	Sim	Limite total de crédito.
`vlLimiteDisponivel`	number	Sim	Limite disponível atual.
`vlCreditoDevolucao`	number	Sim	Crédito por devoluções.
`cpf`	string	—	CPF (PF) ou CNPJ (PJ), apenas dígitos. Valida o dígito verificador.
`fone`	string	—	Telefone fixo (até 15 caracteres).
`celular`	string	—	Telefone celular (até 15 caracteres).
`email`	string	—	E-mail (até 60 caracteres).
`idSexo`	"M" \| "F"	—	Sexo. Use `"M"` ou `"F"` (e não `sexo`).
`dtNascimento`	string (ISO-8601)	—	Data de nascimento como string ISO-8601, ex.: `"1990-04-19T00:00:00.000Z"`.
`cdTelevendas`	number \| null	—	Código do televendas vinculado ao cliente.
`cdClienteGrupo`	number \| null	—	Código do grupo comercial. Consulte /api/clienteGrupo.
`cdTabelaPrecoCondicao`	number \| null	—	Código do vínculo entre tabela e condição de preço. Consulte /api/tabelaPrecoCondicao.
`endereco / bairro / cdCidade / cep`	string / number	—	Dados de endereço (todos opcionais).
`clienteDependente`	array	—	Dependentes do cliente (opcional).
`clienteAnexo`	array	—	Anexos (opcional).

Convenções importantes

Use idSexo, não sexo.
dtNascimento precisa ser string ISO-8601 — não envie um objeto Date serializado pelo JavaScript sem antes chamar .toISOString().
idTipoCliente é uma string (ex.: "F" para físico, "J" para jurídico ou um código próprio de até 3 caracteres).

request body

{

"cdEmpresa": 1,

"nmCliente": "João Souza",

"tpPessoa": "F",

"cpf": "12345678900",

"fone": "11999999999",

"celular": "11988888888",

"email": "joao@email.com",

"idSexo": "M",

"dtNascimento": "1990-04-19T00:00:00.000Z",

"cdTelevendas": 7,

"cdClienteGrupo": 3,

"cdTabelaPrecoCondicao": 12,

"cdCategoria": 1,

"cdSituacaoCliente": 1,

"idTipoCliente": "F",

"vlLimiteCredito": 5000,

"vlLimiteDisponivel": 1000,

"vlCreditoDevolucao": 0,

"clienteDependente": [],

"clienteAnexo": []

}

Atualizar cliente

PUT/api/cliente

Cookie session_idclientes:editar

Mesmo schema do POST, exigindo cdCliente.

request body (resumido)

{

"cdCliente": 100,

"cdEmpresa": 1,

"nmCliente": "João Souza Atualizado",

"tpPessoa": "F",

"cdCategoria": 1,

"cdSituacaoCliente": 1,

"idTipoCliente": "001",

"cdTelevendas": 7,

"cdClienteGrupo": 3,

"cdTabelaPrecoCondicao": 12,

"vlLimiteCredito": 7000,

"vlLimiteDisponivel": 2000,

"vlCreditoDevolucao": 0

}

Excluir cliente

DELETE/api/cliente

Cookie session_idclientes:excluir

request body

{ "cdCliente": 100 }

Salvar respostas de formulário

POST/api/cliente/formulario

Cookie session_idclientes:formulario

Persiste respostas de um formulário dinâmico vinculado ao cliente. Envie um array de respostas.

request body

[

{ "cdCliente": 10, "cdFormulario": 2, "cdPergunta": 5, "dsResposta": "Sim" },

{ "cdCliente": 10, "cdFormulario": 2, "cdPergunta": 6, "dsResposta": "" }

]

Vendedores / acesso no app de força de venda

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).

Mudança de schema

Cliente.cdVendedor foi removido. Qualquer integração que estivesse lendo/escrevendo esse campo precisa passar a usar a relação ClienteVendedor.
A coluna cd_vendedor em cliente deixou de existir no banco; os vínculos existentes foram migrados para cliente_vendedor via script SQL.
No model User foi adicionado o flag idTodosClientesApp (mapeado para id_todos_clientes_app), default false.

Tabela `cliente_vendedor`

Parâmetro	Tipo	Obrig.	Descrição
`cdHolding`	number	Sim	Holding (parte da PK composta).
`cdCliente`	number	Sim	Cliente vinculado (parte da PK composta).
`cdVendedor`	number	Sim	`userId` do representante vinculado (parte da PK composta).

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.

PUT /api/users (trecho)

{

"userIdAlterar": 7,

"cdEmpresa": 1,

"nome": "Maria Silva",

"email": "maria@empresa.com",

"idTodosClientesApp": false,

"clientesVendedor": [

{ "cdCliente": 100 },

{ "cdCliente": 215 }

]

}

Comportamento do update

Quando clientesVendedor é enviado no payload, o backend substitui a lista inteira: apaga todos os vínculos atuais do usuário e recria apenas os enviados. Para manter a lista intacta, omita o campo.

Produtos

CRUD de produtos com filtros por marca, fornecedor, grupo, código de barras e busca agregada. Inclui endpoint de atualização em lote.

Listar produtos

GET/api/produto

Cookie session_id

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`id`	string	—	IDs separados por vírgula.
`name`	string	—	Busca por nome do produto.
`cdProdutoBarra`	string	—	Código de barras.
`cdMarca`	number	—	Código da marca.
`cdGrupo`	number	—	Código do grupo.
`cdAgrupador`	number	—	Código do agrupador de preço. Consulte /api/produtoAgrupador.
`cdFornecedor`	number	—	Código do fornecedor.
`cdReferencia`	string	—	Referência interna.
`somenteProdutosComSaldo`	boolean	—	Apenas com saldo em estoque.
`idTipoProduto`	string	—	Tipo do produto.
`dsAgregado`	string	—	Busca agregada por nome, marca, grupo, referência, etc.
`page`	number	—	Página (default 1).
`limit`	number	—	Itens por página.

cURL

curl "https://app.techbullsistemas.com.br/api/produto?cdMarca=3&cdAgrupador=2&dsAgregado=camiseta&page=1&limit=50" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Agrupador de preço no retorno

O campo cdAgrupador identifica o agrupador de preço associado ao produto e pode ser null. Consulte o cadastro correspondente em GET /api/produtoAgrupador.

Características e seus valores são consultados separadamente em GET /api/caracteristicaProduto e GET /api/produtoCaracteristicaProduto.

Criar produto

POST/api/produto

Cookie session_idprodutos:cadastrar

Cria um novo produto com código de barras, tabelas de preço e dados fiscais. Escopo: holding — não envie cdEmpresa no body (o saldo de estoque é criado automaticamente em todas as empresas da holding).

Defaults aplicados pela API

A API preenche automaticamente os campos fiscais e flags padrão quando você não os envia, então o payload mínimo abaixo já é suficiente. Você pode sobrescrever qualquer um deles passando o valor explicitamente.

Defaults aplicados: idSituacao: "A", idTipoProduto: "P", idSaldoNegativo: "N", idDecimal: "N", idLiberaQtd: "N", idEnviaLojaVirtual: "N", idComplemento: "N", cdFornecedor: 1, cdCor: 1, cdTamanho: 1, cdGrade: 1, nrItem: 1, cdSituacaoTributaria: "000", cdSituacaoPis/Cofins/Ipi: "01", prIcms / prComissao / prMargemSubstituicao: 0, fatorVenda: 1, qtMinimo / qtMaximo / pesoBruto / pesoLiquido / cubagem: 0. Se cdUnidadeEmbalagem não for enviado, recebe o mesmo valor de cdUnidade.

Os itens de tabelaPrecoItem também recebem defaults: os demais campos numéricos obrigatórios (prIpi, prFrete, prAcrescimoFinanceiro, prMargemExtra, prDesconto, prSubstituicao, vlPromocao, vlPromocaoAprazo, vlUltCompra, prJuros, vlParcela, vlCustoMedio, vlCustoReposicao, vlNegociacao, prSubstituicaoSolidaria, vlOutrasDespesas, vlParcelaPromocao, prJurosPromocao) são preenchidos com 0 quando omitidos.

Body parameters mínimos

Parâmetro	Tipo	Obrig.	Descrição
`dsProduto`	string	Sim	Descrição do produto (até 200 caracteres).
`cdMarca`	number	Sim	Código da marca (use /api/marca para listar).
`cdGrupo`	number	Sim	Código do grupo (use /api/grupoProduto para listar).
`cdAgrupador`	number \| null	—	Agrupador de preço (use /api/produtoAgrupador para listar).
`cdUnidade`	number	Sim	Código da unidade (use /api/unidade para listar).
`produtoBarra`	array	—	Lista de códigos de barras. Cada item: `{ cdBarra: string }`.
`tabelaPrecoItem`	array	—	Tabela de preços (custo e venda ficam aqui dentro, não no nível do produto). Item mínimo: `{ cdTabelaPreco, vlCompra, vlCusto, vlVenda, prMargemLucro }`.

Onde ficam custo e venda?

vlCusto, vlCompra, vlVenda e prMargemLucro são campos de tabelaPrecoItem, e não do produto em si. Enviar vlCusto no nível do produto é silenciosamente ignorado pela API (compatibilidade), mas o correto é colocá-los dentro do array.

Exemplo — payload mínimo

request body

{

"dsProduto": "Camiseta Preta P",

"cdMarca": 3,

"cdGrupo": 1,

"cdAgrupador": 2,

"cdUnidade": 1,

"produtoBarra": [

{ "cdBarra": "7891234567890" }

"tabelaPrecoItem": [

{

"cdTabelaPreco": 1,

"vlCompra": 25.00,

"vlCusto": 25.00,

"vlVenda": 79.90,

"prMargemLucro": 60

}

]

}

Exemplo — sobrescrevendo defaults fiscais

request body

{

"dsProduto": "Camiseta Preta P",

"cdMarca": 3,

"cdGrupo": 1,

"cdAgrupador": 2,

"cdUnidade": 1,

"cdFornecedor": 7,

"prIcms": 18,

"cdSituacaoTributaria": "102",

"cdClassificacaoFiscal": "61091000",

"cdCest": "2810400",

"produtoBarra": [{ "cdBarra": "7891234567890" }],

"tabelaPrecoItem": [

{

"cdTabelaPreco": 1,

"vlCompra": 25.00,

"vlCusto": 25.00,

"vlVenda": 79.90,

"prMargemLucro": 60

}

]

}

Resposta — 200 OK

response.json

{

"cdProduto": 242,

"dsProduto": "Camiseta preta p",

"cd_holding": 3

}

Atualizar produto

PUT/api/produto

Cookie session_idprodutos:editar

request body (resumido)

{

"cdProduto": 100,

"dsProduto": "Camiseta Preta P (atualizada)",

"cdAgrupador": 2,

"tabelaPrecoItem": [

{ "cdTabelaPreco": 1, "vlVenda": 89.90, "prMargemLucro": 65 }

]

}

Excluir produto

DELETE/api/produto

Cookie session_idprodutos:excluir

request body

{ "cdProduto": 100 }

Atualizar produtos em lote

PUT/api/produto/bulk-update

Cookie session_idprodutos:editar

Atualiza vários produtos em uma única chamada. Cada item retorna individualmente o resultado da operação.

request body

{

"items": [

{

"cdProduto": 10,

"dsProduto": "Nome novo",

"cdAgrupador": 2,

"tabelaPrecoItem": [

{ "cdTabelaPreco": 1, "vlVenda": 99.90, "prMargemLucro": 30 }

]

{ "cdProduto": 11, "vlCusto": 18.50 }

]

}

Resposta — 200 OK

response.json

{

"results": [

{ "cdProduto": 10, "success": true },

{ "cdProduto": 11, "success": false, "message": "Custo inválido" }

]

}

Cotações e Cadastros

Consultas de integração para cotações, logística, fornecedores e referências comerciais de clientes e produtos. Todas exigem sessão autenticada e são sempre isoladas pela holding do usuário. Os nomes das tabelas de origem estão indicados em cada endpoint.

Listar cotações de venda

GET/api/cotacaoVenda

Cookie session_idvendas:consultar

Consulta a tabela cotacao_venda. O parâmetro id é um atalho para nrCotacao.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`nrCotacao`	number	—	Número da cotação.
`cdEmpresa`	number	—	Código da empresa.
`idSituacao`	string	—	Situação da cotação.
`dtIni`	date (YYYY-MM-DD)	—	Emissão a partir desta data.
`dtFim`	date (YYYY-MM-DD)	—	Emissão até esta data.
`id`	string	—	Código(s) principal(is), separados por vírgula.
`name`	string	—	Busca parcial no campo de nome/descrição da entidade.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 50, máximo 500).

cURL

curl "https://app.techbullsistemas.com.br/api/cotacaoVenda?cdEmpresa=1&idSituacao=AB&page=1&limit=50" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: nrCotacao, cdEmpresa, cdCliente, nmCliente, idSituacao, dtEmissao, vlCotacao. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Listar itens das cotações de venda

GET/api/cotacaoVendaItem

Cookie session_idvendas:consultar

Consulta a tabela cotacao_venda_item. Informe nrCotacao e cdEmpresa para recuperar os itens de uma cotação específica.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`nrCotacao`	number	—	Número da cotação.
`nrItem`	number	—	Número do item dentro da cotação.
`cdEmpresa`	number	—	Código da empresa.
`id`	string	—	Código(s) principal(is), separados por vírgula.
`name`	string	—	Busca parcial no campo de nome/descrição da entidade.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 50, máximo 500).

cURL

curl "https://app.techbullsistemas.com.br/api/cotacaoVendaItem?nrCotacao=120&cdEmpresa=1&limit=100" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: nrCotacao, nrItem, cdEmpresa, cdProduto, dsProduto, qtCotada, vlUnitario. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Listar transportadoras

GET/api/transportadora

Cookie session_idfrete:consultar

Consulta a tabela transportadora por código ou nome.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`id`	string	—	Código(s) principal(is), separados por vírgula.
`name`	string	—	Busca parcial no campo de nome/descrição da entidade.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 50, máximo 500).

cURL

curl "https://app.techbullsistemas.com.br/api/transportadora?name=Logistica&page=1&limit=50" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: cdTransportadora, razaoSocial, nmTransportadora, cnpj, fone, email. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Listar veículos

GET/api/veiculo

Cookie session_idfrete:consultar

Consulta a tabela veiculo por código, descrição, placa ou situação.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`placa`	string	—	Busca parcial pela placa.
`idAtivo`	string	—	Indicador de situação cadastrado no veículo.
`id`	string	—	Código(s) principal(is), separados por vírgula.
`name`	string	—	Busca parcial no campo de nome/descrição da entidade.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 50, máximo 500).

cURL

curl "https://app.techbullsistemas.com.br/api/veiculo?placa=ABC1D23&idAtivo=S" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: cdVeiculo, dsVeiculo, placa, qtPesoCapacidade, idAtivo. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Listar motoristas

GET/api/motorista

Cookie session_idfrete:consultar

Consulta a tabela motorista por código, nome, CPF ou situação.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`cpf`	string	—	Busca parcial pelo CPF.
`idAtivo`	string	—	Indicador de situação cadastrado no motorista.
`id`	string	—	Código(s) principal(is), separados por vírgula.
`name`	string	—	Busca parcial no campo de nome/descrição da entidade.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 50, máximo 500).

cURL

curl "https://app.techbullsistemas.com.br/api/motorista?name=Joao&idAtivo=S" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: cdMotorista, nmMotorista, cpf, idComissao, idAtivo. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Listar fornecedores

GET/api/fornecedor

Cookie session_id

Consulta a tabela fornecedor. Este endpoint já fazia parte da API e exige apenas autenticação.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`id`	string	—	Código(s) principal(is), separados por vírgula.
`name`	string	—	Busca parcial no campo de nome/descrição da entidade.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 10; use -1 para listar todos).

cURL

curl "https://app.techbullsistemas.com.br/api/fornecedor?name=Textil&page=1&limit=50" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: cdFornecedor, razaoSocial, nmFornecedor, cnpj, fone, email, cdGrupoFornecedor. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Listar grupos de fornecedor

GET/api/fornecedorGrupo

Cookie session_idfornecedores:consultar

Consulta a tabela fornecedor_grupo por código ou descrição.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`id`	string	—	Código(s) principal(is), separados por vírgula.
`name`	string	—	Busca parcial no campo de nome/descrição da entidade.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 50, máximo 500).

cURL

curl "https://app.techbullsistemas.com.br/api/fornecedorGrupo?name=Industria&page=1&limit=50" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: cdGrupoFornecedor, dsGrupoFornecedor, dtManutencao. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Listar grupos de produto

GET/api/grupoProduto

Cookie session_id

Consulta a tabela grupo_produto. Este endpoint já fazia parte da API e exige apenas autenticação.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`idAtivo`	boolean	—	Filtra grupos ativos ou inativos.
`id`	string	—	Código(s) principal(is), separados por vírgula.
`name`	string	—	Busca parcial no campo de nome/descrição da entidade.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 10; use -1 para listar todos).

cURL

curl "https://app.techbullsistemas.com.br/api/grupoProduto?name=Vestuario&idAtivo=true&limit=50" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: cdGrupo, dsGrupo, idTipo, prComissao, idAtivo. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Listar vendedores responsáveis dos clientes

GET/api/clienteVendedor

Cookie session_id

Consulta a tabela cliente_vendedor. Cada registro vincula um cliente ao seu vendedor responsável; um cliente pode possuir mais de um vínculo. Este cadastro é diferente do campo cdTelevendas retornado pelo cliente.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdCliente`	number	—	Código do cliente.
`cdVendedor`	number	—	Código do vendedor responsável.
`id`	string	—	Código(s) principal(is), separados por vírgula.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 50, máximo 500).

cURL

curl "https://app.techbullsistemas.com.br/api/clienteVendedor?cdCliente=100&limit=50" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: cdCliente, cdVendedor. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Listar grupos de cliente

GET/api/clienteGrupo

Cookie session_id

Consulta a tabela cliente_grupo, referenciada pelo campo cdClienteGrupo de cada cliente.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`id`	string	—	Código(s) principal(is), separados por vírgula.
`name`	string	—	Busca parcial no campo de nome/descrição da entidade.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 50, máximo 500).

cURL

curl "https://app.techbullsistemas.com.br/api/clienteGrupo?name=Atacado&page=1&limit=50" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: cdGrupo, dsGrupo, prDesconto1, prDesconto2, idLimitePorGrupo, dtManutencao. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Listar condições das tabelas de preço

GET/api/tabelaPrecoCondicao

Cookie session_id

Consulta os vínculos entre tabela de preço e condição de preço. O código do vínculo é retornado no cliente como cdTabelaPrecoCondicao.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdTabelaPreco`	number	—	Código da tabela de preço.
`cdCondicaoPreco`	number	—	Código da condição de preço.
`id`	string	—	Código(s) principal(is), separados por vírgula.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 50, máximo 500).

cURL

curl "https://app.techbullsistemas.com.br/api/tabelaPrecoCondicao?cdTabelaPreco=1&limit=50" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: cdTabelaPrecoCondicao, cdTabelaPreco, cdCondicaoPreco, nrOrdem. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Listar agrupadores de preço dos produtos

GET/api/produtoAgrupador

Cookie session_id

Consulta a tabela produto_agrupador, referenciada pelo campo cdAgrupador do produto.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`id`	string	—	Código(s) principal(is), separados por vírgula.
`name`	string	—	Busca parcial no campo de nome/descrição da entidade.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 50, máximo 500).

cURL

curl "https://app.techbullsistemas.com.br/api/produtoAgrupador?name=Camisetas&page=1&limit=50" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: cdAgrupador, dsAgrupador, idAtualizaCusto, idAtualizaVenda, idControlaGrade, cdSite. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Listar características de produto

GET/api/caracteristicaProduto

Cookie session_id

Consulta o catálogo de características disponíveis para os produtos, como gramatura, composição, coleção ou qualquer outro atributo definido no ERP de origem.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`id`	string	—	Código(s) principal(is), separados por vírgula.
`name`	string	—	Busca parcial no campo de nome/descrição da entidade.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 50, máximo 500).

cURL

curl "https://app.techbullsistemas.com.br/api/caracteristicaProduto?name=Gramatura&page=1&limit=50" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: cdCaracteristicaProduto, dsCaracteristicaProduto, ativo, tipoCampo, cdSite, dtUltAlteracao. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Listar valores das características dos produtos

GET/api/produtoCaracteristicaProduto

Cookie session_id

Consulta os valores associados a cada produto e característica. Conforme o tipo da característica, o valor estará em valorDecimal, valorInteiro ou valorString.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdProduto`	number	—	Código do produto.
`cdCaracteristicaProduto`	number	—	Código da característica.
`id`	string	—	Código(s) principal(is), separados por vírgula.
`page`	number	—	Página da consulta (padrão 1).
`limit`	number	—	Registros por página (padrão 50, máximo 500).

cURL

curl "https://app.techbullsistemas.com.br/api/produtoCaracteristicaProduto?cdProduto=200&limit=100" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Campos de destaque no retorno: cdProduto, cdCaracteristicaProduto, valorDecimal, valorInteiro, valorString. A resposta usa o formato paginado padrão com results e hasMorePages; o identificador interno da holding não é exposto.

Fotos (Firebase Storage)

As imagens de clientes, produtos e fotos extras da loja online são armazenadas no Firebase Cloud Storage. A API TechBull oferece endpoints dedicados para upload, troca e remoção dessas imagens sem que você precise integrar o SDK do Firebase no seu cliente.

Visão geral

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

Recomendado — via API

Envie o arquivo em base64 direto para POST /api/cliente/foto ou POST /api/produto/foto. A API sobe para o Firebase e já atualiza o registro no banco.

Avançado — upload direto

Seu app já usa o SDK do Firebase? Faça o upload direto ao bucket e informe apenas fotoCliente / nomeFotoCliente (ou os equivalentes de produto) na API.

Campos persistidos

Cliente: fotoCliente (token + extensão, ex. "a1b2c3.jpg") e nomeFotoCliente (nome do arquivo sem extensão).
Produto: fotoProduto e nomeFotoProduto no mesmo formato.
Fotos extras (loja online): tabela dedicada com fotoToken, fotoNome e ordem.

Tamanho e formatos

O limite por arquivo é de 5 MB. Formatos suportados: image/jpeg, image/png, image/webp e image/gif. O corpo da requisição (JSON com base64) pode ter até 10 MB.

Estrutura no storage

Todas as imagens ficam no bucket:

bucket

techbull-20bd5.appspot.com

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

Categoria	Usada por	Exemplo de caminho
cliente	Foto principal do cliente	3/images/cliente/100.jpg
produto	Foto principal do produto	3/images/produto/55.jpg
loja-online-produto	Fotos extras exibidas na loja online	3/images/loja-online-produto/abc123.jpg

Enviar foto do cliente

POST/api/cliente/foto

Cookie session_idclientes:editar

Substitui a foto principal do cliente. Se fileBase64 for enviado, a API faz o upload para o Firebase Storage e grava fotoCliente / nomeFotoCliente no banco. Se você já subiu a imagem por conta própria, envie apenas fotoCliente + nomeFotoCliente.

Body parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdCliente`	number	Sim	Código do cliente.
`fileBase64`	string	—	Arquivo em `base64`, com ou sem prefixo `data:image/...;base64,`. Obrigatório se `fotoCliente` não for enviado.
`contentType`	string	—	Ex.: `image/jpeg`. Inferido automaticamente quando o base64 já vem como `data URL`.
`filename`	string	—	Opcional. Usado para descobrir a extensão.
`fotoCliente`	string	—	Alternativa ao `fileBase64`: token retornado pelo Firebase, no formato `token.ext`.
`nomeFotoCliente`	string	—	Obrigatório quando `fotoCliente` é enviado. Nome do arquivo sem extensão.

Exemplo — upload via API

cURL

# 1) gere o base64 a partir do arquivo local

BASE64=$(base64 -w 0 cliente.jpg)

curl -X POST https://app.techbullsistemas.com.br/api/cliente/foto \

-H "Content-Type: application/json" \

-H "Cookie: session_id=a3f9c1e2b4d6..." \

-d "{

\"cdCliente\": 100,

\"contentType\": \"image/jpeg\",

\"filename\": \"cliente.jpg\",

\"fileBase64\": \"$BASE64\"

Exemplo — já subiu para o Firebase

request body

{

"cdCliente": 100,

"fotoCliente": "a3f9c1e2b4d6e7.jpg",

"nomeFotoCliente": "100"

}

Resposta — 200 OK

response.json

{

"ok": true,

"fotoCliente": "a3f9c1e2b4d6e7.jpg",

"nomeFotoCliente": "100"

}

Remover foto do cliente

DELETE/api/cliente/foto

Cookie session_idclientes:editar

Zera os campos fotoCliente e nomeFotoCliente do cliente. O arquivo no Firebase continua no bucket, mas deixa de ser referenciado.

request body

{ "cdCliente": 100 }

Enviar foto do produto

POST/api/produto/foto

Cookie session_idprodutos:editar

Mesma dinâmica do endpoint de cliente: envie fileBase64 para que a API faça o upload no Firebase, ou apenas fotoProduto + nomeFotoProduto se você já subiu o arquivo.

Body parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdProduto`	number	Sim	Código do produto.
`fileBase64`	string	—	Arquivo em base64 (obrigatório se não enviar fotoProduto).
`contentType`	string	—	Ex.: image/jpeg.
`filename`	string	—	Usado para inferir a extensão.
`fotoProduto`	string	—	Token retornado pelo Firebase (token.ext).
`nomeFotoProduto`	string	—	Obrigatório quando fotoProduto é enviado.

cURL

BASE64=$(base64 -w 0 produto.jpg)

curl -X POST https://app.techbullsistemas.com.br/api/produto/foto \

-H "Content-Type: application/json" \

-H "Cookie: session_id=a3f9c1e2b4d6..." \

-d "{

\"cdProduto\": 55,

\"contentType\": \"image/jpeg\",

\"filename\": \"produto.jpg\",

\"fileBase64\": \"$BASE64\"

Resposta — 200 OK

response.json

{

"ok": true,

"fotoProduto": "a3f9c1e2b4d6e7.jpg",

"nomeFotoProduto": "55"

}

Remover foto do produto

DELETE/api/produto/foto

Cookie session_idprodutos:editar

Limpa fotoProduto e nomeFotoProduto do produto.

request body

{ "cdProduto": 55 }

Listar fotos extras de um produto

GET/api/loja-online/produto-fotos

Cookie session_id

Retorna a galeria de imagens do produto usada pela loja online. A foto principal exibida no card do produto segue sendo fotoProduto da entidade produto.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdProduto`	number	Sim	Código do produto.

cURL

curl "https://app.techbullsistemas.com.br/api/loja-online/produto-fotos?cdProduto=55" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Resposta — 200 OK

response.json

{

"results": [

{

"id": 12,

"cdProduto": 55,

"fotoNome": "abc123",

"fotoToken": "d4e5f6.jpg",

"ordem": 0

}

]

}

Adicionar foto extra

POST/api/loja-online/produto-fotos

Cookie session_id

Cadastra uma nova foto na galeria. O arquivo precisa estar no Firebase Storage na categoria loja-online-produto. Envie apenas o par fotoNome + fotoToken.

Body parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdProduto`	number	Sim	Código do produto.
`fotoNome`	string	Sim	Nome do arquivo (sem extensão).
`fotoToken`	string	Sim	Token retornado pelo Firebase, no formato token.ext.
`ordem`	number	—	Posição na galeria (o próximo valor livre é usado se omitido).

request body

{

"cdProduto": 55,

"fotoNome": "abc123",

"fotoToken": "d4e5f6.jpg",

"ordem": 0

}

Reordenar fotos extras

PUT/api/loja-online/produto-fotos

Cookie session_id

Atualiza a ordem de exibição das fotos. Envie os IDs na nova sequência desejada.

request body

{

"cdProduto": 55,

"ids": [12, 15, 14, 13]

}

Excluir foto extra

DELETE/api/loja-online/produto-fotos

Cookie session_id

Remove uma foto da galeria a partir do seu ID.

request body

{ "id": 12 }

Definir foto principal

PUT/api/loja-online/produto-foto-principal

Cookie session_id

Promove uma das fotos extras a foto principal do produto (fotoProduto). Use extraId para promover uma foto existente da galeria (ela é copiada para a categoria produto e removida da galeria), ou envie fotoProduto + nomeFotoProduto caso já tenha subido uma imagem nova por conta própria.

Body parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdProduto`	number	Sim	Código do produto.
`extraId`	number	—	ID da foto extra a ser promovida (mutuamente exclusivo com `fotoProduto`).
`fotoProduto`	string	—	Token da nova foto principal (token.ext).
`nomeFotoProduto`	string	—	Nome do arquivo correspondente à foto principal.

promover foto extra

{

"cdProduto": 55,

"extraId": 12

}

definir diretamente

{

"cdProduto": 55,

"fotoProduto": "a3f9c1e2b4d6e7.jpg",

"nomeFotoProduto": "55"

}

Montar URL de download

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:

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)

getPhotoUrl.ts

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}`
  );
}

Cache-friendly

As URLs geradas são estáveis enquanto o token não for regenerado. Sinta-se livre para fazer cache no seu CDN ou na camada de aplicação.

Títulos a Receber e a Pagar

Endpoints para CRUD de títulos financeiros e baixa (recebimento/pagamento) com formas de pagamento.

Listar títulos a receber

GET/api/tituloReceber

Cookie session_idtitulosReceber:consultar

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`tpPeriodo`	"E" \| "V" \| "P"	Sim	Tipo de período: `E` emissão, `V` vencimento, `P` pagamento.
`cdEmpresa`	number	—	Empresa.
`cdPessoa`	number	—	Cliente.
`serie`	string	—	Série do título.
`idSituacao`	string	—	`AB`, `PG`, `CA`.
`dtIni`	date	—	Data inicial.
`dtFim`	date	—	Data final.
`vlIni`	number	—	Valor mínimo.
`vlFim`	number	—	Valor máximo.
`page`	number	—	Página.
`limit`	number	—	Itens por página.

cURL

curl "https://app.techbullsistemas.com.br/api/tituloReceber?tpPeriodo=V&dtIni=2026-01-01&dtFim=2026-12-31" \

-H "Cookie: session_id=a3f9c1e2b4d6..."

Criar/Atualizar/Excluir título a receber

POST/api/tituloReceber

Cookie session_idtitulosReceber:cadastrar

Métodos suportados: POST criar, PUT atualizar (com nrTitulo), DELETE remover (envia cdUnidade no body). Respectivamente exigem titulosReceber:editar e titulosReceber:excluir.

Receber títulos (baixa)

POST/api/recebimento

Cookie session_idcaixa:recebimentoTitulo

Realiza a baixa de um ou mais títulos a receber, registrando as formas de pagamento, troco e crédito de cliente quando aplicável.

Body parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdEmpresa`	number	Sim	Empresa do recebimento.
`titulos`	array	Sim	Lista de títulos a baixar (mínimo 1).
`formasPagamento`	array	Sim	Formas de pagamento usadas (mínimo 1).
`vlTotal`	number	Sim	Valor total recebido.
`vlDesconto`	number	—	Desconto aplicado.
`vlAcrescimo`	number	—	Acréscimo aplicado.
`cdCliente`	number	—	Cliente (para registrar crédito do troco).

request body

{

"cdEmpresa": 1,

"cdCliente": 100,

"titulos": [

{

"cdEmpresa": 1,

"nrTitulo": 500,

"nrParcela": 1,

"serie": "A",

"vlPago": 150.50,

"dtPagto": "2026-04-19T12:00:00.000Z"

}

"formasPagamento": [

{ "cdFormaPagamento": 1, "vlBruto": 150.50, "vlTotal": 150.50 }

"vlTotal": 150.50,

"vlDesconto": 0,

"vlAcrescimo": 0

}

Resposta — 200 OK

response.json

{

"nrRecebimento": 9001,

"qtTitulos": 1,

"vlTotal": 150.50

}

Listar títulos a pagar

GET/api/tituloPagar

Cookie session_idtitulosPagar:consultar

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`tpPeriodo`	"E" \| "V" \| "P"	Sim	Tipo de período (emissão/vencimento/pagamento).
`cdEmpresa`	number	—	Empresa.
`cdFornecedor`	number	—	Fornecedor.
`cdConta`	number	—	Conta bancária/caixa.
`cdTipoDespesa`	number	—	Tipo de despesa.
`idSituacao`	string	—	AB, PG, CA.
`dtIni`	date	—	Data inicial.
`dtFim`	date	—	Data final.
`page`	number	—	Página.
`limit`	number	—	Itens por página.

Criar/Atualizar/Excluir título a pagar

POST/api/tituloPagar

Cookie session_idtitulosPagar:cadastrar

Aceita POST PUT DELETE. Para excluir, envie nrTitulo no body. Permissões titulosPagar:editar e titulosPagar:excluir.

Pagar título

POST/api/tituloPagar/pagar

Cookie session_idtitulosPagar:pagar

Marca um título em aberto como pago e movimenta a conta correspondente.

Lembre-se de incluir serie no body — ela faz parte da chave composta do título junto com cdEmpresa, nrTitulo e nrParcela.

request body

{

"cdEmpresa": 1,

"nrTitulo": 800,

"nrParcela": 1,

"serie": "A",

"cdFornecedor": 50,

"vlPago": 230.00,

"dtPagto": "2026-04-19T15:00:00.000Z",

"cdConta": 1

}

Cancelar título a pagar

POST/api/tituloPagar/cancelar

Cookie session_idtitulosPagar:cancelar

Cancela um título em aberto. Não funciona em títulos já pagos (use estornar primeiro).

request body

{

"cdEmpresa": 1,

"nrTitulo": 800,

"nrParcela": 1,

"serie": "A",

"cdFornecedor": 50

}

Estornar pagamento

POST/api/tituloPagar/estornar

Cookie session_idtitulosPagar:estornar

Reverte um título já pago, devolvendo-o para a situação aberta e estornando a movimentação na conta.

request body

{

"cdEmpresa": 1,

"nrTitulo": 800,

"nrParcela": 1,

"serie": "A",

"cdFornecedor": 50

}

Entidades de Apoio

Catálogos auxiliares que alimentam o cadastro de produtos, clientes e vendas. A maioria segue o mesmo padrão CRUD.

CRUD padrão

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.

Lista de endpoints

Endpoint	Permissões base	Descrição
/api/grupoProduto	grupos:*	Grupos / categorias de produto.
/api/marca	marcas:*	Marcas dos produtos.
/api/cor	cor:*	Cores disponíveis.
/api/tamanho	tamanhos:*	Tamanhos / grade.
/api/fornecedor	fornecedores:*	Fornecedores dos produtos.
/api/categoria	categoria:*	Categorias de cliente.
/api/tabelaPreco	tabelaPreco:*	Tabelas de preço.
/api/unidade	unidades:*	Unidades de medida.
/api/cidade	— (público)	Cidades do IBGE. Não exige autenticação.

Exceções do padrão

/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).

Campos obrigatórios das principais entidades

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

`POST /api/marca`

request body

{

"dsMarca": "Urban Wear",

"observacao": "Marca própria da loja"

}

`POST /api/grupoProduto`

Parâmetro	Tipo	Obrig.	Descrição
`dsGrupo`	string	Sim	Nome do grupo (até 60 caracteres).
`idTipo`	"P" \| "S"	Sim	Tipo do grupo: `P` = produto, `S` = serviço.
`prComissao`	number	Sim	Percentual padrão de comissão para esse grupo.

request body

{

"dsGrupo": "Vestuário",

"idTipo": "P",

"prComissao": 0

}

`POST /api/unidade`

Parâmetro	Tipo	Obrig.	Descrição
`dsUnidade`	string	Sim	Sigla da unidade (ex.: UN, KG, MT).
`dsUnidadeFator`	string	Sim	Sigla da unidade de fator (geralmente igual a dsUnidade).
`fator`	number	Sim	Fator de conversão (1 quando não há conversão).

request body

{

"dsUnidade": "UN",

"dsUnidadeFator": "UN",

"fator": 1

}

Estoque

Movimentações de entrada e saída de estoque. A criação aceita um array para movimentar vários produtos numa mesma chamada.

Conceito

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).

Pré-requisito para vendas

A efetivação de vendas (POST /api/venda/efetivar) consome estoque. Se o produto não tiver saldo suficiente e a configuração idSaldoNegativo dele for "N", a efetivação falha. Sempre dê entrada de estoque antes de vender.

Listar movimentações de estoque

GET/api/movimentoEstoque

Cookie session_idestoque:consultar

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdEmpresa`	number	—	Empresa.
`dtIni`	date (YYYY-MM-DD)	—	Data inicial.
`dtFim`	date (YYYY-MM-DD)	—	Data final.
`page`	number	—	Página (default 1).
`limit`	number	—	Itens por página.

Lançar movimentação(ões)

POST/api/movimentoEstoque

Cookie session_idestoque:cadastrar

O body é um array de movimentações — cada item afeta um produto. Indicado tanto para entradas (ajustes, compras) quanto para saídas (perdas, transferências).

Body (cada item do array)

Parâmetro	Tipo	Obrig.	Descrição
`cdEmpresa`	number	Sim	Empresa.
`cdProduto`	number	Sim	Produto a movimentar.
`cdOperacaoEstoque`	number	Sim	Operação cadastrada (define se é entrada ou saída).
`qtd`	number	Sim	Quantidade movimentada (sempre positiva — o sinal vem da operação).
`nrDocumento`	number	—	Número do documento de origem (NF, ajuste, etc.).
`serie`	string	—	Série do documento.
`cdPessoa`	number	—	Cliente ou fornecedor envolvido.
`tpPessoa`	"C" \| "F"	—	Tipo da pessoa: C = cliente, F = fornecedor.
`obs`	string	—	Observação livre.

Campos ignorados silenciosamente

vlCusto, vlVenda e vlCompra não existem no model MovimentoEstoque — eles vivem em tabelaPrecoItem/notas fiscais. Para manter compatibilidade, a API descarta esses campos sem erro caso sejam enviados, mas eles não terão efeito no movimento.

request body

[

{

"cdEmpresa": 1,

"cdProduto": 200,

"cdOperacaoEstoque": 1,

"qtd": 50,

"obs": "Estoque inicial"

{

"cdEmpresa": 1,

"cdProduto": 201,

"cdOperacaoEstoque": 1,

"qtd": 30

}

]

Agendamentos

Cadastro de horários para serviços vinculados a clientes, funcionários e produtos/serviços. Útil para nichos como salão de beleza, oficinas, clínicas e consultorias.

Listar agendamentos

GET/api/agendamento

Cookie session_idagendamentos:consultar

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdEmpresa`	number	—	Empresa.
`cdAgendamento`	number	—	ID específico.
`dtAgendamentoIni`	date	—	Início do período.
`dtAgendamentoFim`	date	—	Fim do período.
`cdCliente`	number	—	Cliente.
`cdFuncionario`	number	—	Funcionário responsável.
`cdProduto`	number	—	Produto/serviço agendado.
`idSituacao`	number	—	Situação do agendamento.

Criar agendamento

POST/api/agendamento

Cookie session_idagendamentos:cadastrar

Cria um agendamento. Os serviços/produtos vinculados vão dentro do array servicos; não envie objetos completos de cliente ou funcionário no body — apenas os códigos.

Body parameters

Parâmetro	Tipo	Obrig.	Descrição
`cdEmpresa`	number	Sim	Empresa.
`cdCliente`	number	Sim	Cliente do agendamento.
`dtAgendamentoIni`	date (ISO-8601)	Sim	Data/hora de início.
`dtAgendamentoFim`	date (ISO-8601)	—	Data/hora de término.
`cdFuncionario`	number	—	Funcionário responsável.
`idSituacao`	string	—	Situação inicial (ex.: AB para aberto / agendado).
`observacao`	string	—	Observação livre (use observacao, não obs).
`color`	string	—	Cor para exibição na agenda (hex).
`servicos`	array	—	Serviço/produto do agendamento. Cada item: `{ cdProduto: number }`. Apenas o primeiro item é persistido (o model atual suporta um serviço por agendamento).

O nome correto do campo de observação é observacao (não obs). Enviar obs faz o servidor responder com 422 Erro de validação do banco de dados: Unknown argument `obs`.

Sobre o array `servicos`

Historicamente a validação aceita uma lista de serviços, mas o model interno AgendamentoServicos é 1-1 com o agendamento. Por compatibilidade, a API aceita o array mas persiste apenas o primeiro item. O campo cdServico é aceito e ignorado silenciosamente (não existe no model).

request body

{

"cdEmpresa": 1,

"cdCliente": 100,

"cdFuncionario": 5,

"dtAgendamentoIni": "2026-04-25T14:00:00.000Z",

"dtAgendamentoFim": "2026-04-25T15:00:00.000Z",

"idSituacao": "AB",

"observacao": "Cliente alérgico a corante",

"color": "#f97316",

"servicos": [

{ "cdProduto": 200 }

]

}

Atualizar agendamento

PUT/api/agendamento

Cookie session_idagendamentos:editar

Mesmo schema do POST, com cdAgendamento obrigatório.

Excluir agendamento

DELETE/api/agendamento

Cookie session_idagendamentos:excluir

request body

{ "cdEmpresa": 1, "cdAgendamento": 42 }

Agendamento Público

Endpoints para o cliente final reservar horário pelo link público do salão — sem autenticação. Diferente de /api/agendamento (uso interno autenticado). O {slug} é o identificador configurado no painel (Agenda → Configurar link público).

Visão geral

Fluxo recomendado

GET .../info — dados da empresa, serviços e tipo de grade
GET .../disponibilidade — horários ou vagas livres
POST .../reservar — confirma a reserva com nome e CPF

Dois modos de grade

O campo tipoGradePublica define o comportamento:

HORARIO — o cliente escolhe um slot de horário (slotStartISO).
VAGAS — o cliente escolhe dia + serviço (diaYYYYMMDD + servicoPublicoId).

Não confundir rotas

/api/agendamento-public/{slug}/... — reserva pelo cliente (público)
/api/agendamento-publico — configuração interna no painel (requer login)
/api/agendamento — agenda interna (requer login e cdCliente / cdFuncionario)

Página web do cliente: /agendamento-publico/{slug} (ou subdomínio customizado, se configurado). O servicoPublicoId usado na reserva é o campo id retornado em servicos[].

Info da página pública

GET/api/agendamento-public/{slug}/info

Público

Retorna dados de exibição e a lista de serviços públicos ativos. Use para montar a tela de agendamento ou mapear servicoPublicoId pelo nome do serviço.

Path parameters

Parâmetro	Tipo	Obrig.	Descrição
`slug`	string	Sim	Identificador do link (case-insensitive). Ex.: salao-bella.

Resposta — 200 OK

response.json

{

"slug": "salao-bella",

"nome_empresa": "Salão Bella",

"logo_url": "https://...",

"nr_minutos_slot": 30,

"id_requer_confirmacao": false,

"tipo_grade_publica": "VAGAS",

"nr_vagas_por_dia": 10,

"dias_semana_bloqueados": [0],

"servicos": [

{

"id": 3,

"nm_servico": "Corte",

"ds_servico": "Corte masculino",

"nr_minutos": 30

}

]

}

Consultar disponibilidade

GET/api/agendamento-public/{slug}/disponibilidade

Público

Lista serviços e, conforme o tipo de grade, retorna slots de horário (slotsPorDia) ou vagas por dia/serviço (vagasPorDia).

Path parameters

Parâmetro	Tipo	Obrig.	Descrição
`slug`	string	Sim	Identificador do link público.

Query parameters

Parâmetro	Tipo	Obrig.	Descrição
`desde`	string (YYYY-MM-DD)	—	Primeiro dia da janela consultada. Padrão: hoje (fuso America/Sao_Paulo).
`dias`	number	—	Quantidade de dias (1–31). Padrão: 7.

Resposta — modo VAGAS (trecho)

response.json

{

"tz": "America/Sao_Paulo",

"tipo_grade_publica": "VAGAS",

"servicos": [

{ "id": 3, "nm_servico": "Corte", "ds_servico": null, "nr_minutos": 30 }

"vagas_por_dia": {

"2026-05-22": {

"fechado": false,

"servicos": [

{

"id": 3,

"nm_servico": "Corte",

"disponivel": true,

"vagas_total": 10,

"vagas_ocupadas": 2,

"vagas_livres": 8

}

]

}

Resposta — modo HORARIO (trecho)

response.json

{

"tz": "America/Sao_Paulo",

"tipo_grade_publica": "HORARIO",

"servicos": [],

"slots_por_dia": {

"2026-05-22": [

{

"inicio_iso": "2026-05-22T15:00:00.000Z",

"fim_iso": "2026-05-22T15:30:00.000Z"

}

]

}

Reservar horário

POST/api/agendamento-public/{slug}/reservar

Público

Cria o agendamento. O backend resolve ou cadastra o cliente pelo CPF — não é necessário enviar cdCliente. Envie apenas um dos modos: horário fixo ou dia + serviço.

Path parameters

Parâmetro	Tipo	Obrig.	Descrição
`slug`	string	Sim	Identificador do link público.

Body parameters (comuns)

Parâmetro	Tipo	Obrig.	Descrição
`nmCliente`	string	Sim	Nome do cliente (3–120 caracteres).
`cpf`	string	Sim	CPF com 11 dígitos (com ou sem máscara). Validado no servidor.

Body — modo HORARIO

Parâmetro	Tipo	Obrig.	Descrição
`slotStartISO`	string (ISO-8601)	Sim	Início do slot escolhido (valor de inicioISO em disponibilidade).

Body — modo VAGAS

Parâmetro	Tipo	Obrig.	Descrição
`diaYYYYMMDD`	string	Sim	Dia da reserva no formato YYYY-MM-DD.
`servicoPublicoId`	number	Sim	ID do serviço (campo id em servicos[] de info ou disponibilidade).

Não envie slotStartISO junto com diaYYYYMMDD / servicoPublicoId. A API retorna 400 se ambos os modos forem informados ou se nenhum for informado.

Exemplo — modo VAGAS

request body

{

"nmCliente": "Maria Silva",

"cpf": "12345678901",

"diaYYYYMMDD": "2026-05-22",

"servicoPublicoId": 3

}

Exemplo — modo HORARIO

request body

{

"nmCliente": "Maria Silva",

"cpf": "12345678901",

"slotStartISO": "2026-05-22T15:00:00.000Z"

}

Resposta — 200 OK

response.json

{

"ok": true,

"cd_agendamento": 128,

"id_requer_confirmacao": false,

"whatsapp_url": "https://wa.me/5511999999999?text=..."

}

Rate limit

Rotas públicas possuem limite de requisições por IP. Respostas 429 indicam excesso de tentativas — aguarde antes de tentar novamente.

Erros

Todos os erros seguem um formato JSON consistente, com campos em snake_case.

Formato padrão

exemplo de erro

{

"name": "ValidationError",

"message": "O campo \"cdEmpresa\" é obrigatório.",

"action": "Ajuste os dados enviados e tente novamente.",

"status_code": 400,

"error_id": "f3a4...",

"request_id": "9b2c...",

"error_location_code": "MODEL:VALIDATOR:FINAL_SCHEMA",

"key": "cdEmpresa",

"type": "any.required"

}

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

Erros de validação do banco (422)

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:

exemplo (422)

{

"message": "Erro de validação do banco de dados: Argument `prIcms` is missing.",

"action": "Verifique se o campo informado está correto e se todos os campos obrigatórios foram enviados.",

"request_id": "9b2c..."

}

exemplo — argumento desconhecido

{

"message": "Erro de validação do banco de dados: Unknown argument `obs`.",

"action": "Verifique se o campo informado está correto e se todos os campos obrigatórios foram enviados.",

"request_id": "f3a4..."

}

Se o detalhe vier em inglês (porque é gerado pelo Prisma), os padrões mais comuns são:

Argument `xxx` is missing. → faltou enviar o campo xxx.
Unknown argument `xxx`. → você enviou um campo que não existe nessa entidade.
Invalid value for argument `xxx` → o tipo/valor de xxx está errado (ex.: passar string onde espera number).

Códigos de status

Status	Quando acontece
`400`	ValidationError — body/query inválido (campo obrigatório, tipo errado, regra de negócio).
`401`	UnauthorizedError — sessão ausente, expirada ou credenciais incorretas no login.
`403`	ForbiddenError — autenticado, mas sem a feature/permissão necessária.
`404`	NotFoundError — recurso não encontrado.
`409`	Conflito — geralmente violação de chave estrangeira (Prisma P2003).
`422`	UnprocessableEntityError — dados não processáveis.
`500`	InternalServerError — erro inesperado no servidor (anote o request_id).

Dúvidas ou sugestões? Entre em contato pelo formulário do site.

API TechBull Sistemas

Começando

Introdução

Base URL e formato

Convenções

Autenticação

Visão geral

Fazer login

Body parameters

Exemplo de requisição

Resposta — 200 OK

Obter usuário autenticado

Fazer logout

Permissões

Listar catálogo de features

Vendas e Pré-vendas

Conceito e ciclo de vida

Listar vendas

Query parameters

Resposta — 200 OK

Criar pré-venda

Body parameters principais

Exemplo de requisição

Resposta — 200 OK

Atualizar pré-venda

Cancelar pré-venda

Efetivar venda

Resposta — 200 OK

Estornar venda

Editar venda efetivada

Atualizar formas de pagamento

Relatórios

Relatório de notas fiscais

Query parameters

Resposta — 200 OK

Notas fiscais com produtos

Query parameters

Resposta — 200 OK

Relatório de produtos vendidos

Query parameters

Resposta — 200 OK

Clientes

Listar clientes

Query parameters

Criar cliente

Campos obrigatórios

Atualizar cliente

Excluir cliente

Salvar respostas de formulário

Vendedores / acesso no app de força de venda

Tabela cliente_vendedor

Escopo de sincronização no app mobile

Cadastro offline (upload)

Gerenciando vínculos pelo endpoint /api/users

Produtos

Listar produtos

Query parameters

Criar produto

Body parameters mínimos

Exemplo — payload mínimo

Exemplo — sobrescrevendo defaults fiscais

Resposta — 200 OK

Atualizar produto

Excluir produto

Atualizar produtos em lote

Resposta — 200 OK

Cotações e Cadastros

Listar cotações de venda

Query parameters

Listar itens das cotações de venda

Query parameters

Listar transportadoras

Query parameters

Listar veículos

Query parameters

Listar motoristas

Query parameters

Listar fornecedores

Query parameters

Listar grupos de fornecedor

Tabela `cliente_vendedor`

Gerenciando vínculos pelo endpoint `/api/users`

`POST /api/marca`

`POST /api/grupoProduto`

`POST /api/unidade`