1. Introdução e Visão Geral

A Protheus REST API é uma solução desenvolvida em Node.js + Express + TypeScript que expõe qualquer tabela do ERP Protheus/TOTVS como um endpoint REST completo — sem necessidade de código adicional para cada entidade do banco de dados.

A API conecta-se diretamente ao banco de dados do Protheus (SQL Server ou MySQL), interpreta as requisições HTTP e gera as queries SQL correspondentes de forma automática, respeitando as convenções do Protheus como o soft-delete via coluna D_E_L_E_T_ e a chave primária R_E_C_N_O_.

Características principais

• Exposição automática de qualquer tabela Protheus via REST
• Suporte a MSSQL (SQL Server) e MySQL
• Operações CRUD individuais e em lote (bulk)
• Operações bulk atômicas com rollback automático em caso de falha
• Soft-delete nativo compatível com o padrão Protheus
• Múltiplos ambientes de banco de dados configuráveis
• Sistema completo de filtros, ordenação, paginação e relacionamentos
• Autenticação JWT via header HTTP
• Controle de acesso por endereço IP

2. Pré-requisitos e Instalação

2.1 Pré-requisitos

2.2 Instalação

# 1. Instale as dependências
npm install

# 2. Compile o TypeScript para a pasta server/
npm run build

# 3. Inicie o servidor
npm run serve

2.3 Scripts npm

2.4 Estrutura de diretórios

protheus-rest-api/
├── config/
│   ├── protheus-rest-api.config.jsonc        # Config de produção
│   └── protheus-rest-api.config-test.jsonc   # Config de teste
├── rdbconfig.json                            # Config da biblioteca rdb-server
├── src/                                      # Fonte TypeScript
│   ├── index.ts
│   └── libs/protheus-sql-server/
│       └── libs/rdb-server/
│           ├── controller.js
│           ├── db-manager.js
│           ├── query-generator.js
│           ├── query-support.js
│           ├── routes.js
│           └── db-connection/
├── server/                                   # Build compilado (npm run build)
└── docs/

3. Configuração Detalhada

3.1 protheus-rest-api.config.jsonc

Arquivo principal de configuração. O arquivo utilizado é definido pela chave appConfigFilePath do package.json.

{
  "service": {
    "name":        ".3001 - Node Protheus REST API",
    "description": "Protheus REST API",
    "script":      "server"
  },
  "port": 3001,
  "serverConfig": {
    "logDateWhenStarting":  true,
    "allowOnlyAddresses": ["::ffff:127.0.0.1", "::1"]
  },
  "completeLogger":  false,
  "bulkMaxRecords": 100,
  "environments": [
    {
      "name":      "protheus-prd",
      "plataform": "mssql",
      "config": {
        "user":              "seu_usuario",
        "password":          "sua_senha",
        "server":            "ip_ou_hostname",
        "database":          "PROTHEUS_PRD",
        "connectionTimeout": 999999999,
        "requestTimeout":    999999999,
        "options": { "enableArithAbort": true }
      },
      "default": true
    }
  ]
}

3.2 rdbconfig.json

Configuração interna da biblioteca rdb-server. Define o comportamento padrão para todas as tabelas.

{
  "rdbConfig": {
    "ENVIRONMENT_REQUEST_LOCATION": "headers",
    "envDefaults": {
      "idColumnName":             "R_E_C_N_O_",
      "deletedColumnName":        "D_E_L_E_T_",
      "deletedValue":             "'*'",
      "deleteAdd":               ["R_E_C_D_E_L_ = R_E_C_N_O_"],
      "columnsNotShow":          ["R_E_C_D_E_L_"],
      "updateAdd":               [],
      "insertAdd":               [],
      "idAutoIncrement":          false,
      "relationshipConditionById": false
    }
  }
}

3.3 Configurando múltiplos ambientes

{
  "name":      "protheus-prd",
  "plataform": "mssql",
  "config": {
    "user":     "usuario",
    "password": "senha",
    "server":   "192.168.1.10",
    "database": "PROTHEUS",
    "options": {
      "enableArithAbort": true
    }
  },
  "default": true
}

{
  "name":      "protheus-hml",
  "plataform": "mysql",
  "config": {
    "user":     "usuario",
    "password": "senha",
    "host":     "192.168.1.20",
    "database": "PROTHEUS_HML"
  },
  "default": false
}

4. Autenticação

Todas as requisições devem incluir um token JWT no header Authorization. O ambiente é selecionado pelo header environment.

Authorization: Bearer <seu-token-jwt>
Content-Type:  application/json
environment:   protheus-prd

5. Endpoints CRUD Padrão

Cada tabela Protheus é acessível pelo nome como parâmetro de rota. O :id corresponde ao valor de R_E_C_N_O_.

5.1 GET — Listar registros

GET /SBM?BM_FILIAL=01&$limit=20
Authorization: Bearer <token>
environment:   protheus-prd

[
  { "R_E_C_N_O_": 105, "BM_FILIAL": "01", "BM_GRUPO": "A001", "BM_DESC": "Grupo A" },
  { "R_E_C_N_O_": 106, "BM_FILIAL": "01", "BM_GRUPO": "A002", "BM_DESC": "Grupo B" }
]

5.2 GET — Buscar por ID

{ "R_E_C_N_O_": 105, "BM_FILIAL": "01", "BM_GRUPO": "A001", "BM_DESC": "Grupo A" }

5.3 POST — Inserir registro único

POST /SBM
{ "BM_FILIAL": "01", "BM_GRUPO": "A003", "BM_DESC": "Grupo C" }

{ "R_E_C_N_O_": 107, "BM_FILIAL": "01", "BM_GRUPO": "A003", "BM_DESC": "Grupo C" }

5.4 PUT — Atualizar registro único

PUT /SBM/105
{ "BM_DESC": "Nova Descrição" }

5.5 DELETE — Soft-delete

6. Bulk Operations

Operações em lote permitem inserir, atualizar ou deletar múltiplos registros em uma única requisição. Todas são atômicas: se qualquer registro falhar, toda a transação é revertida (rollback) e nenhuma alteração é persistida.

6.1 POST — Inserção em lote (bulk insert)

POST /SBM
[
  { "BM_FILIAL": "01", "BM_GRUPO": "A001", "BM_DESC": "Grupo 1" },
  { "BM_FILIAL": "01", "BM_GRUPO": "A002", "BM_DESC": "Grupo 2" }
]

{ "inserted": 2 }

6.2 PUT — Atualização em lote (bulk update)

PUT /SBM
[
  { "R_E_C_N_O_": 105, "BM_DESC": "Atualizado 1" },
  { "R_E_C_N_O_": 106, "BM_DESC": "Atualizado 2" }
]

{ "updated": 2 }

6.3 DELETE — Soft-delete em lote

DELETE /SBM
[105, 106, 107]

{ "deleted": 3 }

6.4 Contratos de Erro — Bulk Operations

7. Filtros e Query Parameters

Os endpoints GET /:tableName aceitam um conjunto rico de parâmetros de query string para filtrar, projetar, ordenar, paginar e relacionar dados. Parâmetros prefixados com $ são diretivas de controle; os demais são interpretados como filtros de coluna.

7.1 Filtros de coluna — igualdade exata

Qualquer parâmetro sem prefixo $ e sem sufixo de operador é interpretado como filtro de igualdade na coluna correspondente. As comparações de texto são case-insensitive e acentos são normalizados automaticamente.

# Filtro simples
GET /SBM?BM_FILIAL=01

# Múltiplos filtros (AND implícito)
GET /SBM?BM_FILIAL=01&BM_GRUPO=A001

7.2 Operadores de comparação

Para filtros além da igualdade exata, sufixe o nome da coluna com o operador: COLUNA$operador=valor

Valores especiais nos filtros

7.3 $map — Projeção de colunas

Seleciona apenas as colunas especificadas no resultado. Sem $map, retorna todas as colunas. R_E_C_N_O_ é sempre incluído automaticamente.

GET /SBM?$map=BM_GRUPO grupo,BM_DESC descricao
# Retorna: [{ "R_E_C_N_O_": 105, "grupo": "A001", "descricao": "Grupo A" }]

7.4 $sort — Ordenação

Define a ordem dos resultados. Sem $sort, a API ordena por R_E_C_N_O_.

7.5 $page / $limit — Paginação por página

Paginação clássica. $page começa em 1. O valor padrão de $limit é 10. O header de resposta x-total-length retorna o total de registros sem paginação.

# Página 1, 20 registros por página
GET /SBM?$page=1&$limit=20

# Página 3, 50 por página, com filtro e ordenação
GET /SBM?BM_FILIAL=01&$page=3&$limit=50&$sort=BM_GRUPO

7.6 $start / $end — Paginação por intervalo de linhas

Alternativa à paginação por página. Define o intervalo exato de linhas (numeradas após aplicar filtros e ordenação). A linha 1 é o primeiro resultado.

# Linhas 1 a 50
GET /SBM?$start=1&$end=50

# A partir da linha 51 (sem limite final)
GET /SBM?$start=51

7.7 q — Busca full-text

Realiza busca em todas as colunas da tabela simultaneamente. Case-insensitive. Em MSSQL usa collation específico para suporte a acentos. Colunas numéricas são convertidas para texto antes da comparação.

# Busca "embalagem" em todos os campos
GET /SBM?q=embalagem

# Combinado com filtro de coluna
GET /SBM?BM_FILIAL=01&q=materia

7.8 $query — Expressão SQL literal

Permite passar uma expressão SQL WHERE arbitrária. Útil para condições complexas não cobertas pelos operadores padrão. A expressão é envolta em parênteses e adicionada ao WHERE via AND.

GET /SBM?$query=BM_GRUPO LIKE 'A%' AND BM_DESC NOT IN ('Inativo', 'Obsoleto')

7.9 $embed — Relacionamentos embarcados (1:N)

Embarca registros de uma tabela filha em cada registro do resultado principal. Relação pai → N filhos. O resultado da tabela filha aparece como array no registro pai, sob a chave com o nome da tabela filha.

GET /SC5?$embed=SC6&$on=SC6.C6_NUM = SC5.C5_NUM

# Resultado:
[
  {
    "R_E_C_N_O_": 10,
    "C5_NUM": "000001",
    "SC6": [
      { "C6_ITEM": "01", "C6_PRODUTO": "PROD001" },
      { "C6_ITEM": "02", "C6_PRODUTO": "PROD002" }
    ]
  }
]

7.10 $expand — Expansão de referência (N:1)

Expande uma referência de chave estrangeira trazendo o registro pai completo. Relação filho → 1 pai. O registro pai aparece como objeto no registro filho.

GET /SC6?$expand=SB1&$on=SB1.B1_COD = SC6.C6_PRODUTO

# Resultado:
[
  {
    "R_E_C_N_O_": 50,
    "C6_PRODUTO": "PROD001",
    "SB1": { "B1_DESC": "Produto 001", "B1_UM": "UN" }
  }
]

7.11 $on — Condição de JOIN

Define a condição SQL de relacionamento usada por $embed e $expand. Obrigatório quando relationshipConditionById é false (padrão). Aceita expressões SQL padrão: tabela.coluna = tabela.coluna.

Resumo de todos os parâmetros de query

8. Soft Delete — Comportamento Protheus

O Protheus utiliza "deleção lógica" (soft-delete) baseada em colunas de controle. Esta API implementa esse comportamento nativamente e de forma transparente.

SQL gerado pelo DELETE

UPDATE SBM
SET    D_E_L_E_T_   = '*',
       R_E_C_D_E_L_ = R_E_C_N_O_
WHERE  R_E_C_N_O_   = 105
AND    D_E_L_E_T_   != '*'

Colunas de controle

Todos os GET adicionam automaticamente WHERE D_E_L_E_T_ != '*'. Registros deletados nunca aparecem nos resultados sem intervenção direta no banco.

9. Códigos de Retorno HTTP

10. Exemplos Práticos — Tabela SBM

A tabela SBM (Grupos de Materiais) é usada como referência. Substitua por qualquer tabela Protheus disponível.

Listar com filtro, ordenação e paginação

GET /SBM?BM_FILIAL=01&$page=1&$limit=10&$sort=BM_GRUPO
Authorization: Bearer <token>
environment:   protheus-prd

Projeção de colunas com alias

GET /SBM?BM_FILIAL=01&$map=BM_GRUPO grupo,BM_DESC descricao&$sort=BM_GRUPO

Busca full-text + intervalo de R_E_C_N_O_

GET /SBM?q=embalagem&R_E_C_N_O_$gte=100&R_E_C_N_O_$lte=500

Filtro com lista ($in) e exclusão ($nlike)

GET /SBM?BM_GRUPO$in=MA01|PA01|EM01&BM_DESC$nlike=obsoleto

Inserção em lote

POST /SBM
[
  { "BM_FILIAL": "01", "BM_GRUPO": "MA01", "BM_DESC": "Matéria Prima"  },
  { "BM_FILIAL": "01", "BM_GRUPO": "PA01", "BM_DESC": "Produto Acabado" },
  { "BM_FILIAL": "01", "BM_GRUPO": "EM01", "BM_DESC": "Embalagem"       }
]

Atualização em lote

PUT /SBM
[
  { "R_E_C_N_O_": 200, "BM_DESC": "Matéria Prima Nacional"     },
  { "R_E_C_N_O_": 201, "BM_DESC": "Produto Acabado Exportação" }
]

Deleção em lote

DELETE /SBM
[200, 201, 202]

11. Troubleshooting

Erros de conexão

Outros erros comuns

Ativar log completo de queries

// Temporariamente: ativa o log das queries SQL completas no console
"completeLogger": true