advpl-webservice

Files (2)

• SKILL.md
• reference.md

SKILL.md (first lines)

# advpl-webservice — REST e SOAP no Protheus

ADVPL/TLPP suporta duas formas de Web Service:

- **REST** — preferida hoje. Sintaxe declarativa com `WSRESTFUL` + annotations `@Get`/`@Post`/`@Put`/`@Delete`. Em TLPP, mais limpo ainda com `Class ... Inherit FWRest`.
- **SOAP** — legado, mas vivo. `WSSERVICE` + `WSDATA` + `WSMETHOD` + `WSSTRUCT`.

O AppServer Protheus expõe ambos via porta HTTP configurada em `appserver.ini` (`[HTTPSERVER]`, `[HTTPV11]` para REST).

## Quando usar

- Criar API REST/SOAP no Protheus.
- Edit em fontes com `WSRESTFUL`, `WSSERVICE`, `WSMETHOD`, `WSDATA`, `WSSTRUCT`, `@Get`, `@Post`.
- Integração de Protheus com aplicação externa (mobile, e-commerce, ERP terceiro).
- Revisão de segurança em endpoint exposto (SEC-001, SEC-002).

## REST com WSRESTFUL (TLPP moderno)

```advpl
#include "tlpp-core.th"
#include "tlpp-rest.th"

@Get(endpoint="/v1/cliente/:codigo", description="Busca cliente por código")
User Function GetCliente()
    Local oResp  := JsonObject():New()
    Local cCod   := oRest:GetUrlParam("codigo")
    Local cError := ""

    If Empty(cCod)
        oRest:SetStatusCode(400)
        oResp["error"] := "Codigo obrigatorio"
        oRest:SetResponse(oResp:ToJson())
        Return .F.
    EndIf

    DbSelectArea("SA1")
    SA1->(DbSetOrder(1))
    If SA1->(DbSeek(xFilial("SA1") + cCod))
        oResp["codigo"] := SA1->A1_COD
        oResp["nome"]   := AllTrim(SA1->A1_NOME)
        oResp["cnpj"]   := SA1->A1_CGC
        oRest:SetStatusCode(200)
    Else
        oRest:SetStatusCode(404)
        oResp["error"] := "Cliente nao encontrado"
    EndIf

    oRest:SetResponse(oResp:ToJson())
Return .T.
```

## REST com WSRESTFUL (estilo classic)

```advpl
WSRESTFUL XYZCli DESCRIPTION "API de Clientes"

    WSMETHOD GET   DESCRIPTION "Lista clientes"   WSSYNTAX "/api/cli"
    WSMETHOD GET   DESCRIPTION "Busca por codigo" WSSYNTAX "/api/cli/{codigo}"
    WSMETHOD POST  DESCRIPTION "Cria cliente"     WSSYNTAX "/api/cli"

END WSRESTFUL

WSMETHOD GET WSSERVICE XYZCli
    Local cBody := ""
    // ... lógica
    ::SetContentType("application/json")
    ::SetResponse(cBody)
Return .T.

WSMETHOD POST WSSERVICE XYZCli
    Local cInput := ::GetContent()  // ATENÇÃO SEC-002
    // ... lógica com validação
Return .T.
```

## SOAP com WSSERVICE

```advpl
WSSERVICE XYZSrv DESCRIPTION "Servico XYZ"
    WSDATA cCodCliente AS STRING
    WSDATA oCliente    AS XYZCliRet

    WSMETHOD BuscaCliente DESCRIPTION "Busca cliente por codigo"
END WSSERVICE

WSSTRUCT XYZCliRet
    WSDATA cCodigo AS STRING
    WSDATA cNome   AS STRING
    WSDATA nLimite AS NUMERIC
END WSSTRUCT

WSMETHOD BuscaCliente WSRECEIVE cCodCliente WSSEND oCliente WSSERVICE XYZSrv
    ::oCliente := WSClassNew("XYZCliRet")
    // ... popula
Return .T.
```

## Regra crítica — NUNCA `RpcSetEnv` em REST (SEC-001 família)

`RpcSetEnv` é usado para abrir ambiente Protheus (empresa, filial, usuário) em **JOB/RPC**. **Em REST, o framework já entrega o ambiente** via autenticação HTTP (`token`, `basic auth`) configurada no `appserver.ini`.

```advpl
// ERRADO — risco crítico (SEC-001 família)
@Post(endpoint="/v1/pedido")
User Function CriaPedido()
    RpcSetEnv("01", "0101", "admin", "totvs")  // BLOQUEAR
    // ...
Return .T.

// CORRETO — ambiente já vem da requisição autenticada
@Post(endpoint="/v1/pedido")
User Function CriaPedido()
    Local cEmp := cEmpAnt  // já preenchido pelo framework
    Local cFil := cFilAnt  // já preenchido pelo framework
    // ... lógica
Return .T.
```

Razão: `RpcSetEnv` hardcoded vaza credenciais e bypassa o login do usuário REST. Auditoria perde rastreio.

From replybr/plugadvpl, MIT.

More from replybr/plugadvpl