rev2-2026-05-05 Protheus 12.1.33

Natureza

CRUD de naturezas financeiras (tabela SED) via REST. As mutações delegam para a rotina padrão FINA010 via MsExecAuto, encapsulada pelo wrapper U_FN010Exec (src/lib/FIN/FN010EXC.prw). A leitura usa BeginSql direto na SED. A chave externa é ED_CODIGO (até 10 caracteres), informada pelo cliente — não há sequência automática SX8 neste endpoint.

Base URL https://erpapi.jetme.com.br/api/99/01 Empresa 99 · Filial 01

Convenções

Identificador externo. O código da natureza (ED_CODIGO) é a chave externa e é fornecido pelo cliente — não há sequenciador SX8 envolvido. Aceita até 10 caracteres alfanuméricos. Tudo é normalizado para uppercase antes do seek/persistência.

Filtro de filial. Toda operação aplica xFilial("SED"). A query param filial existe por compatibilidade com a URL padrão da REST do Protheus (/api/99/01 já fixa empresa/filial); ela não troca o contexto — o filtro vem do tenant da URL.

Domínios canônicos. Tipo aceita 1 (A Pagar), 2 (A Receber) ou 3 (Ambos, default). Cond aceita R (Receita, default) ou D (Despesa). Os Calc* e Ded* são flags S/N (default N para os Calc, 2 para os Ded).

POST com path obrigatório. Por característica do build 240223P (Static Functions no mesmo PRW quebram ::GetContent()), o WsSED declara WSSYNTAX "/WsSED/INCLUIR/{codigo}" para o POST — o código aparece duas vezes (no path e no body). O endpoint confia no body como fonte canônica; o path é só ginástica de roteamento.

PUT é parcial. Apenas os campos presentes no body são alterados. Omitidos mantêm o valor atual. O wrapper U_FN010Exec recebe um aArray com somente os pares a alterar e o registro SED previamente posicionado.

Bloqueio TOTVS. A tabela SED não tem os campos ED_MSBLQL/ED_MSBLQD neste dicionário — o padrão de bloqueio adotado em CadastroCliente (par *_MSBLQL/*_MSBLQD com PUT restrito) não se aplica aqui. Exclusão é feita via DELETE (Op=5) e respeita as travas internas do FINA010 (existem títulos vinculados, etc).

Natureza

CRUD por ED_CODIGO

GET /WsSED/ Lista naturezas da filial

Descrição

Retorna todas as naturezas da filial corrente. Não há paginação — a SED tipicamente tem volume baixo (dezenas a poucas centenas de registros). A consulta é feita via BeginSql direto na tabela, com ORDER BY ED_CODIGO.

Cada item devolve os campos canônicos do envelope Natureza: código, descrição, tipo, condição, e as flags de cálculo de impostos/deduções.

Query parameters

filial string · query · opcional

Filial Protheus (default "01"). Compatibilidade; o filtro efetivo vem da URL /api/99/01.

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSED/
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lista de naturezas. Envelope { success: true, data: { total, naturezas: Natureza[] } }.

500

Erro interno (falha na query). Tier: business-error.

GET /WsSED/{codigo} Consulta natureza por código

Descrição

Retorna uma única natureza pelo código (ED_CODIGO). Mesma forma de leitura do /WsSED/ (BeginSql), apenas acrescentando AND ED_CODIGO = %exp:cCodigo%.

Path parameter

codigo string · path · obrigatório SED.ED_CODIGO

Código da natureza, até 10 caracteres alfanuméricos. Normalizado para uppercase.

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSED/TST
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Natureza encontrada. Envelope { success: true, data: Natureza }.

404

Natureza inexistente para o código informado. Tier: not-found.

500

Erro interno (DbSeek, serialização). Tier: business-error.

POST /WsSED/INCLUIR/{codigo} Cria nova natureza

Descrição

Inclui uma natureza nova via FINA010 em modo 3 (inclusão). O aArray de pares {campo, valor} é montado a partir do body e enviado ao MsExecAuto pelo wrapper U_FN010Exec.

Campos aceitos: ver NaturezaRequest.
Obrigatórios: Filial, Codigo, Descricao.
O segmento INCLUIR no path é exigido pelo roteador (WSSYNTAX); evita conflito com o GET por código.

Path parameter

codigo string · path · obrigatório SED.ED_CODIGO

Mesmo código informado no body (Codigo). Aparece duplicado por exigência do build 240223P do roteador WSRESTFUL.

Request body

application/json NaturezaRequest · obrigatório

Payload plano com os campos da natureza. Schema completo em NaturezaRequest.

Payload mínimo — apenas os obrigatórios mais Tipo e Cond explícitos. Fixture: fixtures/create.json.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsSED/INCLUIR/TST
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "Filial": "01",
  "Codigo": "TST",
  "Descricao": "NATUREZA TESTE",
  "Tipo": "3",
  "Cond": "R"
}

Com impostos e deduções — natureza realista para receita de serviço com cálculo de IRRF e ISS, deduções padrão de PIS/COFINS.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsSED/INCLUIR/SRV001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "Filial": "01",
  "Codigo": "SRV001",
  "Descricao": "RECEITA DE SERVICOS",
  "Tipo": "2",
  "Cond": "R",
  "CalcIRF": "S",
  "CalcISS": "S",
  "CalcCOF": "S",
  "CalcPIS": "S",
  "DedPIS": "2",
  "DedCOF": "2"
}

Respostas

201

Natureza criada. Envelope CrudResponse com data.codigo = código persistido.

400

Body inválido (JSON malformado) ou campo obrigatório ausente (Filial, Codigo, Descricao). Tier: validation-error.

422

FINA010 rejeitou a inclusão (código duplicado, valor fora do domínio em Tipo/Cond, etc). Tier: business-error.

500

Erro interno.

PUT /WsSED/{codigo} Altera natureza existente

Descrição

Altera campos da natureza via FINA010 em modo 4 (alteração). O endpoint posiciona o registro SED com DbSeek antes do MsExecAuto — requisito do MVC para Op=4. Apenas os campos presentes no body entram no aArray; omitidos mantêm o valor atual.

Restrições. A chave ED_CODIGO não pode ser alterada por PUT — o seek é feito pelo código do path. Para "renomear" um código, exclua e crie de novo.

Path parameter

codigo string · path · obrigatório SED.ED_CODIGO

Código da natureza existente.

Query parameters

filial string · query · opcional

Compatibilidade. Default "01".

Request body

application/json NaturezaPutRequest · obrigatório

Subconjunto dos campos. Envie apenas o que deseja alterar.

Alteração comum — atualiza descrição e troca o tipo para "A Pagar".

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsSED/TST
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "Descricao": "NATUREZA TST REVISADA",
  "Tipo": "1"
}

Receita → Despesa — caso extremo válido: inverte o sentido da natureza (Cond de R para D) e ativa o cálculo de IRRF. Útil quando uma natureza foi cadastrada com sentido errado.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsSED/TST
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "Cond": "D",
  "CalcIRF": "S"
}

Respostas

200

Natureza alterada. Envelope CrudResponse.

400

Código ausente no path ou body inválido. Tier: validation-error.

404

Natureza inexistente. Tier: not-found.

422

FINA010 rejeitou a alteração (valor fora do domínio em algum enum). Tier: business-error.

500

Erro interno.

DEL /WsSED/{codigo} Exclui natureza

Descrição

Exclui a natureza via FINA010 em modo 5. O MsExecAuto recusa a exclusão quando a natureza está vinculada a títulos / lançamentos — nessa situação o endpoint devolve 422 com a mensagem do NomeAutoLog.

Path parameter

codigo string · path · obrigatório SED.ED_CODIGO

Código da natureza existente.

Query parameters

filial string · query · opcional

Compatibilidade. Default "01".

Chamada de exemplo

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsSED/TST
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Natureza excluída. Envelope CrudResponse.

404

Natureza inexistente. Tier: not-found.

422

Natureza com dependências (títulos vinculados, lançamentos no SE1/SE2/etc). Tier: business-error.

500

Erro interno.

Schemas

Definições canônicas — campos com origem SX3 rastreável

Natureza

object

Representação retornada nos GETs (lista e individual). Chaves em camelCase — diferente do payload de POST/PUT que usa PascalCase nas chaves canônicas.

codigostring · obrigatórioSED.ED_CODIGO

Código da natureza (até 10 caracteres).

descricaostring · obrigatórioSED.ED_DESCRIC

Descrição (até 40 caracteres).

tipostring · opcionalSED.ED_TIPO

Tipo da natureza.

123

condstring · opcionalSED.ED_COND

Condição: R=Receita, D=Despesa.

RD

calcIRFstring · opcionalSED.ED_CALCIRF

Calcula IRRF.

SN

calcISSstring · opcionalSED.ED_CALCISS

Calcula ISS.

SN

calcINSstring · opcionalSED.ED_CALCINS

Calcula INSS.

SN

calcCSLstring · opcionalSED.ED_CALCCSL

Calcula CSLL.

SN

calcCOFstring · opcionalSED.ED_CALCCOF

Calcula COFINS.

SN

calcPISstring · opcionalSED.ED_CALCPIS

Calcula PIS.

SN

dedPISstring · opcionalSED.ED_DEDPIS

Tipo de dedução PIS (default "2").

dedCOFstring · opcionalSED.ED_DEDCOF

Tipo de dedução COFINS (default "2").

NaturezaRequest

object

Payload do POST. Chaves em PascalCase mapeiam diretamente para o nome lógico do campo (sem o prefixo ED_). Obrigatórios: Filial, Codigo, Descricao. Demais com defaults seguros do FINA010.

Filialstring · obrigatórioSED.ED_FILIAL

Filial (2 caracteres). Tipicamente "01".

Codigostring · obrigatórioSED.ED_CODIGO

Código da natureza (até 10 caracteres). Mesmo valor do path.

Descricaostring · obrigatórioSED.ED_DESCRIC

Descrição (até 40 caracteres).

Tipostring · opcionalSED.ED_TIPO

Default "3" (Ambos).

123

Condstring · opcionalSED.ED_COND

Default "R" (Receita).

RD

CalcIRFstring · opcionalSED.ED_CALCIRF

Default "N".

SN

CalcISSstring · opcionalSED.ED_CALCISS

Default "N".

SN

CalcINSstring · opcionalSED.ED_CALCINS

Default "N".

SN

CalcCSLstring · opcionalSED.ED_CALCCSL

Default "N".

SN

CalcCOFstring · opcionalSED.ED_CALCCOF

Default "N".

SN

CalcPISstring · opcionalSED.ED_CALCPIS

Default "N".

SN

DedPISstring · opcionalSED.ED_DEDPIS

Tipo dedução PIS (default "2").

DedCOFstring · opcionalSED.ED_DEDCOF

Tipo dedução COFINS (default "2").

NaturezaPutRequest

object · subset

Payload do PUT — todos os campos opcionais. Omitir mantém o valor atual. Não aceita Filial nem Codigo (a chave é do path; alterá-la não é suportado pelo MVC).

Descricaostring · opcionalSED.ED_DESCRIC

Nova descrição.

Tipostring · opcionalSED.ED_TIPO

Novo tipo.

123

Condstring · opcionalSED.ED_COND

Nova condição.

RD

CalcIRFstring · opcionalSED.ED_CALCIRF

Flag IRRF.

SN

CalcISSstring · opcionalSED.ED_CALCISS

Flag ISS.

SN

CalcINSstring · opcionalSED.ED_CALCINS

Flag INSS.

SN

CalcCSLstring · opcionalSED.ED_CALCCSL

Flag CSLL.

SN

CalcCOFstring · opcionalSED.ED_CALCCOF

Flag COFINS.

SN

CalcPISstring · opcionalSED.ED_CALCPIS

Flag PIS.

SN

DedPISstring · opcionalSED.ED_DEDPIS

Tipo dedução PIS.

DedCOFstring · opcionalSED.ED_DEDCOF

Tipo dedução COFINS.

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. No POST, data.codigo ecoa o código persistido; PUT/DELETE devolvem data vazio.

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso (ex: "Natureza criada com sucesso.").

datastring | object · opcional

No POST, objeto { codigo } com o ED_CODIGO persistido. Em PUT/DELETE, string vazia.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode trazer detalhe técnico do MsExecAuto (mensagem NomeAutoLog) quando aplicável.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

Mensagem editorial do erro (apresentável ao usuário final).

datastring · opcional

Token interno / detalhe técnico (ex: log do MsExecAuto).