ProtheusSalesModule

O ProtheusSalesModule expõe serviços e controllers para criar orçamentos/pedidos, consultar clientes (base Protheus e prospects), calcular impostos, validar crédito e acompanhar o fluxo completo de aprovação. Ele depende do ProtheusModule (conexão/ERP) e reutiliza recursos do CoreModule (autenticação, PDF, socket, message broker).

Como Inicializar

Importe o módulo no AppModule junto aos módulos Core e Protheus.

import { Module } from "@nestjs/common"
import { CoreModule } from "@soulsys/api/core"
import { ProtheusModule } from "@soulsys/api/protheus-core"
import { ProtheusSalesModule } from "@soulsys/api/protheus-sales"

@Module({
  imports: [CoreModule, ProtheusModule, ProtheusSalesModule],
})
export class AppModule {}

As rotas expostas ficam sob /api/sys/protheus/sales.

Clientes e Prospects

Controller: CustomerController (/customers)

GET /:code/:unit?prospect=true|false: retorna cliente (SA1) ou prospect (SUS).
GET /:cgc: busca por CPF/CNPJ (SA1 + SUS).
POST /search: pesquisa por código/nome/CPF/CNPJ.
GET /:code/:unit/products/:productId: traz item da tabela de preço do cliente (ou produto base).
POST /:code/:unit/products/search: lista produtos pela tabela de preço do cliente.
POST /create-prospect: cria prospect via API Protheus e retorna o registro.

Exemplo de busca e produto vinculado à tabela de preço:

POST /api/sys/protheus/sales/customers/search
Content-Type: application/json
{ "keyword": "supermercado" }

GET /api/sys/protheus/sales/customers/000123/01/products/BALANCA001

Orçamentos e Pedidos

Controller: SaleController (/sales)

POST /: cria orçamento/pedido (fase quote ou order).
PATCH /:id: atualiza se canUpdate=true.
DELETE /:id: exclui se canDelete=true.
POST /:id/finish: finaliza manutenção.
POST /:id/assume e POST /:id/leave: assumir/deixar aprovação.
POST /:id/approve e POST /:id/reject: fluxo de aprovação.
POST /:id/undo: desfaz algumas fases (conforme regras).
POST /:id/cancel: cancela informando motivo/comentários.
POST /:id/confirm: envia para confirmação/processamento no Protheus.
GET /:id: detalha pedido (inclui itens, recebíveis, regras, aprovação, comentários, anexos, eventos).
POST /find: pesquisa com filtros (empresa, status, datas, cliente, fase, apenas envolvidos).
GET /:id/invoices: notas fiscais relacionadas.
GET /:id/pdf?revision=R1: gera PDF da proposta/pedido.
GET /:productId/stocks: consulta estoques via entry point.
GET /:saleId/credit: status de crédito do cliente considerando a venda.
GET /:saleId/collection-enabled: indica se cobrança/boletos está habilitado.

Exemplo de criação de orçamento:

POST /api/sys/protheus/sales/sales
Authorization: Bearer <token>
Content-Type: application/json
{
  "userEmail": "vendedor@soulsys.tech",
  "phase": "quote",
  "customerCode": "000123",
  "customerUnit": "01",
  "paymentCondId": "001",
  "items": [
    { "productId": "BALA001", "quantity": 10, "unitPrice": 25, "subTotal": 250 }
  ]
}

Listagem com filtros e paginação (herda de FilterDto):

POST /api/sys/protheus/sales/sales/find
Content-Type: application/json
{
  "page": 1,
  "limit": 20,
  "companyIds": ["<sys-company-id>"],
  "status": ["wtn_app", "on_app"],
  "customer": "mercado",
  "onlyInvolved": true
}

Comentários e Anexos

POST /:id/comments com { "msg": "Observação" }.
DELETE /:id/comments/:recno.
POST /:id/attachments com { "fileId": "<id-do-storage>" }.
DELETE /:id/attachments/:fileId.

Cálculo de Impostos

POST /calculate-item-taxes: calcula impostos conforme cliente e produto.

POST /api/sys/protheus/sales/sales/calculate-item-taxes
{
  "customerCode": "000123",
  "customerUnit": "01",
  "prospect": false,
  "productId": "BALA001",
  "quantity": 5,
  "unitPrice": 20.5
}

PDF da Venda

GET /:id/pdf?revision=R1: retorna PDF inline. Ajuste layout com env PROTHEUS_SALES_PDF_LOGO_TOP/HEIGHT.

GET /api/sys/protheus/sales/sales/000045/pdf
Accept: application/pdf

Eventos em Tempo Real

A cada atualização/exclusão, o serviço emite eventos no SocketService:

sys_sales_proc_{sysCompanyId}_{saleId}_{event}
sys_sales_sale_{sysCompanyId}_{saleId}_{event}

event pode ser updated ou deleted. Use no frontend para atualizar grids ou dashboards em tempo real.

Crédito

Serviço: CreditService.

GET /sales/:saleId/credit: monta painel de crédito combinando limite, aging (SE1), faturamento anual (SD2) e pedidos liberados (SC9). Se a venda estiver cancelada/faturada, o cálculo ignora o pedido.

Estoques

GET /sales/:productId/stocks: delega para entry point sys_protheus_sales.sales.get_item_stocks. Implemente esse entry point para retornar locais e quantidades disponíveis.

Pontos de Entrada

Registre callbacks usando @EntryPoint para customizar regras sem alterar o core:

sys_protheus_sales.sales.get_business_rules — retorna lista de regras de negócio aplicadas à venda.
sys_protheus_sales.sales.get_approval_roles — define papéis aprovadores exigidos.
sys_protheus_sales.sales.has_approver_role — verifica se o usuário atual é aprovador.
sys_protheus_sales.sales.can_assume_approval — decide se o usuário pode assumir a aprovação.
sys_protheus_sales.sales.get_item_stocks — devolve estoques do produto.

Exemplo:

import { Injectable } from "@nestjs/common"
import { EntryPoint } from "@soulsys/api/core"
import { Sale, User } from "@soulsys/api/protheus-sales"

@Injectable()
export class SalesHooks {
  @EntryPoint("sys_protheus_sales.sales.get_approval_roles")
  async approvalRoles(sale: Sale, user: User) {
    if (sale.totalValue > 50000) return ["dir_fin", "dir_com"]
    if (sale.totalValue > 10000) return ["sup_com"]
    return []
  }
}

Confirmação Assíncrona

Quando PROTHEUS_SALES_ASYNC_CONF_ENABLED=true, a confirmação do pedido pode ser processada via fila sys_protheus_sales_conf (RabbitMQ/MessageBroker). A API responde imediatamente e o processamento posterior reemite eventos socket ao concluir.

Variáveis de Ambiente

Além das variáveis do ProtheusModule (banco/usuário API), configure as específicas de vendas:

Variável	Descrição
PROTHEUS_SALES_ENABLED	Habilita o módulo de vendas.
PROTHEUS_SALES_PDF_LOGO_TOP	Posição superior (px) do logo no PDF.
PROTHEUS_SALES_PDF_LOGO_HEIGHT	Altura (px) do logo no PDF.
PROTHEUS_SALES_ASYNC_CONF_ENABLED	Ativa confirmação assíncrona via fila `sys_protheus_sales_conf`.
PROTHEUS_SALES_ASYNC_CONF_RETRY_MINUTES	Tempo de retry (minutos) para DLQ quando a confirmação assíncrona falha.
PROTHEUS_SALES_SHOWCASE_MODE	Simula latência e reduz TTL da fila para ambientes de demonstração.
PROTHEUS_COLLECTION_ENABLED	Habilita verificação de cobrança/boletos (`/collection-enabled`).

Dica: mantenha PROTHEUS_SALES_ASYNC_CONF_ENABLED=false em desenvolvimento para simplificar o ciclo de testes, e ative em produção com fila configurada.