rev1-2026-05-07 Protheus 12.1.33

CadastroAtivo

CRUD de bens do Ativo Imobilizado sobre a rotina automática ATFA010. Modelo 2 (cabeçalho SN1 + grade SN3): cada item representa um tipo de saldo/depreciação do bem (contábil, fiscal, societário, …). O identificador externo é a chave composta N1_CBASE + N1_ITEM (concatenada sem separador, tamanhos via TamSX3).

Bloqueio TOTVS: tabela SN1 — cadastro de ativos, nesta base sem MSBLQL/MSBLQD; verificar SX3 antes de implementar.

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

Convenções

Chave composta como identificador externo. O path param {chave} em /WsSN1/ALTERAR/<chave>, /WsSN1/EXCLUIR/<chave> e /WsSN1/<chave> é a concatenação sem separador de N1_CBASE + N1_ITEM. Os tamanhos são lidos em runtime de TamSX3 — não há comprimento fixo. No POST, o segmento equivalente é placeholder (auto) e a chave real vem dentro do cabecalho do payload.

Payload aninhado (Modelo 2). Diferente dos endpoints de tabela única (SA1, SB1), o corpo é estruturado em { cabecalho, itens[] }. O array itens tem mínimo 1 elemento e cada item representa uma linha de SN3 (tipo de saldo).

PUT exige N3_TIPO em todo item. O ATFA010 em modo 4 usa N3_TIPO como LINPOS para localizar a linha do grid. Item sem N3_TIPO é rejeitado com 422 antes do MsExecAuto — caso contrário a rotina substituiria todo o grid SN3 do bem. Itens não listados no payload não são tocados.

DELETE remove cabeçalho + todos os itens. O EXCLUIR aciona nOper=5 com AUTDELETA em cada linha SN3 conhecida. Não há exclusão parcial por item — para remover um tipo específico, use PUT com N3_TIPO + AUTDELETA no modo grid (futuro; não suportado em rev1).

Formato de datas. Campos N1_AQUISIC e N3_DINDEPR aceitam string YYYYMMDD no payload — convertidos via SToD(). Qualquer outro formato produz data inválida e é rejeitado pela rotina.

Paginação. /_list usa page/pageSize (default 50, máx 500). A listagem retorna apenas a capa (campos de SN1); para obter os itens, faça GET /WsSN1/<chave>.

Fixtures sentinel. Os smoke tests usam N1_CBASE com prefixo _TS para que registros residuais sejam triviais de identificar e descartar.

Ativo

CRUD de bens (cabeçalho SN1 + itens SN3) via ATFA010

POST /WsSN1/INCLUIR/{chave} Inclui novo ativo (cabeçalho + itens)

Descrição

Cria um novo bem (cabeçalho SN1) com 1 ou mais itens SN3 (tipos de saldo) via ATFA010 em nOper=3. A chave (N1_CBASE + N1_ITEM) vem no cabecalho do body; o segmento da URL é placeholder (auto).

Whitelist de campos do cabeçalho: ver Cabecalho.
Whitelist de campos de item: ver Item.
N3_CCONTAB precisa existir em CT1 antes do POST.

Path parameter

chave string · path · obrigatório placeholder

Placeholder fixo (auto). A chave real (N1_CBASE + N1_ITEM) vem no cabecalho do payload.

Request body

application/json AtivoPayload · obrigatório

Estrutura { cabecalho, itens[] }. Schema completo em AtivoPayload.

Bem com saldo contábil único — payload mínimo para inclusão. Fixture: fixtures/create.json.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "N1_CBASE": "_TS001",
    "N1_ITEM": "01",
    "N1_AQUISIC": "20260507",
    "N1_DESCRIC": "NOTEBOOK DELL VOSTRO",
    "N1_QUANTD": 1,
    "N1_CHAPA": "987"
  },
  "itens": [
    {
      "N3_TIPO": "01",
      "N3_HISTOR": "Saldo contabil",
      "N3_TPSALDO": "1",
      "N3_TPDEPR": "1",
      "N3_CCONTAB": "11101001",
      "N3_VORIG1": 10000,
      "N3_PERDEPR": 20,
      "N3_DINDEPR": "20260507"
    }
  ]
}

Múltiplos tipos de saldo — bem com lançamentos contábil e fiscal simultâneos (cada item = uma linha SN3 distinta por N3_TIPO). Fixture: fixtures/create-multi.json.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "N1_CBASE": "_TS002",
    "N1_ITEM": "01",
    "N1_AQUISIC": "20260507",
    "N1_DESCRIC": "MAQUINA INDUSTRIAL XPTO",
    "N1_QUANTD": 1,
    "N1_CHAPA": "4421"
  },
  "itens": [
    {
      "N3_TIPO": "01",
      "N3_HISTOR": "Saldo contabil",
      "N3_TPSALDO": "1",
      "N3_TPDEPR": "1",
      "N3_CCONTAB": "11201001",
      "N3_VORIG1": 50000,
      "N3_PERDEPR": 10,
      "N3_DINDEPR": "20260507"
    },
    {
      "N3_TIPO": "02",
      "N3_HISTOR": "Saldo fiscal",
      "N3_TPSALDO": "1",
      "N3_TPDEPR": "1",
      "N3_CCONTAB": "11201001",
      "N3_VORIG1": 50000,
      "N3_PERDEPR": 10,
      "N3_DINDEPR": "20260507"
    }
  ]
}

Respostas

201

Ativo incluído. Envelope RespostaCriacao com data.cbase + data.item.

400

Payload mal formado ou falta cabecalho/itens. Tier: validation-error.

422

Regra de negócio do ATFA010 rejeitou o payload (campo obrigatório ausente, N3_CCONTAB inexistente em CT1, enum inválido). Tier: business-error.

500

Erro interno (stack em console_rest.log).

PUT /WsSN1/ALTERAR/{chave} Altera ativo existente (capa e/ou itens)

Descrição

Altera campos do cabeçalho SN1 e/ou itens SN3 específicos via ATFA010 em nOper=4. Cada item do array itens deve trazer N3_TIPO — usado como LINPOS para identificar a linha no grid.

Itens não listados no payload não são tocados. Para excluir uma linha SN3 específica, é necessário evoluir o wrapper (suporte a AUTDELETA em modo grid; backlog).

Path parameter

chave string · path · obrigatório SN1.N1_CBASE + SN1.N1_ITEM

N1_CBASE + N1_ITEM concatenados (sem separador). Tamanhos via TamSX3.

Request body

application/json AtivoPayload · obrigatório

Subconjunto dos whitelists. Cada item exige N3_TIPO.

Alteração de cabeçalho — só atualiza descrição/chapa, mas ainda assim os itens precisam ser informados (com N3_TIPO para LINPOS).

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "N1_DESCRIC": "NOTEBOOK DELL VOSTRO 5430",
    "N1_CHAPA": "987-A"
  },
  "itens": [
    { "N3_TIPO": "01" }
  ]
}

Alteração de item — ajusta histórico e taxa de depreciação só do tipo 01. Outras linhas (tipos 02, 03…) permanecem como estão.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {},
  "itens": [
    {
      "N3_TIPO": "01",
      "N3_HISTOR": "Saldo contabil revisado",
      "N3_PERDEPR": 25
    }
  ]
}

Respostas

200

Ativo alterado. Envelope RespostaCriacao.

400

Payload mal formado. Tier: validation-error.

404

Bem inexistente para a chave informada. Tier: not-found.

422

Item sem N3_TIPO, regra de negócio do ATFA010, ou referência inválida (ex: N3_CCONTAB inexistente). Tier: business-error.

500

Erro interno.

DEL /WsSN1/EXCLUIR/{chave} Exclui ativo (capa + todos os itens)

Descrição

Exclui o bem inteiro via ATFA010 em nOper=5. O wrapper monta AUTDELETA em todas as linhas SN3 conhecidas antes de invocar o MsExecAuto. Não há exclusão parcial.

Path parameter

chave string · path · obrigatório SN1.N1_CBASE + SN1.N1_ITEM

N1_CBASE + N1_ITEM concatenados.

Chamada de exemplo

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsSN1/EXCLUIR/_TSDOC000101
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Ativo excluído. Envelope RespostaSimples (success + message).

400

Chave em formato inválido. Tier: validation-error.

404

Bem inexistente. Tier: not-found.

422

Bem com saldos/movimentos que impedem exclusão (regra do ATFA010). Tier: business-error.

500

Erro interno.

GET /WsSN1/{chave} Consulta bem por chave (cabeçalho + itens)

Descrição

Retorna o bem completo: cabeçalho de SN1 + todos os itens de SN3 ligados à mesma chave (N1_CBASE + N1_ITEM). Aplica filtro de filial (xFilial("SN1")) e respeita os whitelists CAMPOS_CAB_GET e CAMPOS_ITEM_GET.

Path parameter

chave string · path · obrigatório SN1.N1_CBASE + SN1.N1_ITEM

N1_CBASE + N1_ITEM concatenados.

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Bem encontrado. Envelope RespostaConsulta com data.cabecalho + data.itens[].

400

Chave em formato inválido. Tier: validation-error.

404

Bem inexistente. Tier: not-found.

500

Erro interno.

Listagem

Consulta paginada da capa SN1

GET /WsSN1/_list Lista paginada de bens (capa SN1)

Descrição

Lista a capa dos bens cadastrados, com filtros parciais opcionais e paginação page/pageSize. Retorna apenas campos do cabeçalho SN1 — para obter os itens (grade SN3) faça GET /WsSN1/<chave>.

Query parameters

cbase string · query · opcional SN1.N1_CBASE

Prefixo de N1_CBASE (match por LIKE 'cbase%').

descric string · query · opcional SN1.N1_DESCRIC

Texto contido em N1_DESCRIC (case-insensitive).

chapa string · query · opcional SN1.N1_CHAPA

Valor exato de N1_CHAPA.

page integer · query · opcional

Número da página (default 1, mínimo 1).

pageSize integer · query · opcional

Tamanho da página (default 50, máx 500).

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSN1/_list?cbase=_TS&page=1&pageSize=50
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Request · busca por descriçãoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSN1/_list?descric=notebook&pageSize=20
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lista paginada. Envelope RespostaListagem com page, pageSize, count e data[].

400

page/pageSize fora dos limites.

500

Erro interno.

Schemas

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

AtivoPayload

object

Estrutura raiz dos payloads POST e PUT. Combina cabeçalho (linha única de SN1) com array de itens (linhas de SN3).

cabecalhoCabecalho · obrigatório

Campos da capa do bem. Ver Cabecalho.

itensItem[] · obrigatório

Array de tipos de saldo / depreciação. Mínimo 1 elemento. Ver Item.

Cabecalho

object

Linha do cabeçalho do bem (SN1). N1_CBASE e N1_ITEM são obrigatórios no POST (compõem a chave); no PUT são derivados do path e não precisam ser repetidos no corpo.

N1_CBASEstring · obrigatório em POSTSN1.N1_CBASE

Código base do bem. Tamanho via TamSX3 (varia entre clientes; 4 a 6 chars).

N1_ITEMstring · obrigatório em POSTSN1.N1_ITEM

Sub-item do bem (default "01" quando há um único item por base).

N1_AQUISICstring (date) · opcionalSN1.N1_AQUISIC

Data de aquisição. Formato YYYYMMDD — convertida por SToD().

N1_DESCRICstring · opcionalSN1.N1_DESCRIC

Descrição do bem.

N1_QUANTDnumber · opcionalSN1.N1_QUANTD

Quantidade. Default 1.

N1_CHAPAstring · opcionalSN1.N1_CHAPA

Plaqueta de patrimônio (identificador físico do bem).

Item

object

Linha do grid SN3. Cada item representa um tipo de saldo/depreciação (contábil, fiscal, societário, etc.). N3_TIPO é o discriminador da linha — sempre obrigatório (LINPOS em PUT).

N3_TIPOstring · obrigatórioSN3.N3_TIPO

Tipo de saldo (LINPOS do grid em PUT). Valores comuns: 01=contábil, 02=fiscal, 05=societário.

N3_HISTORstring · opcionalSN3.N3_HISTOR

Histórico contábil livre.

N3_TPSALDOstring · opcionalSN3.N3_TPSALDO

Tipo de saldo do bem.

N3_TPDEPRstring · opcionalSN3.N3_TPDEPR

Tipo de depreciação aplicado.

N3_CCONTABstring · opcionalSN3.N3_CCONTAB

Conta contábil. Deve existir em CT1 antes do MsExecAuto; caso contrário 422.

N3_VORIG1number · opcionalSN3.N3_VORIG1

Valor original (moeda 1).

N3_VORIG2number · opcionalSN3.N3_VORIG2

Valor original (moeda 2).

N3_VORIG3number · opcionalSN3.N3_VORIG3

Valor original (moeda 3).

N3_VMXDEPRnumber · opcionalSN3.N3_VMXDEPR

Valor máximo de depreciação.

N3_VLSALV1number · opcionalSN3.N3_VLSALV1

Valor de salvamento (moeda 1).

N3_PERDEPRnumber · opcionalSN3.N3_PERDEPR

Taxa anual de depreciação em %.

N3_PRODMESnumber · opcionalSN3.N3_PRODMES

Produção do mês (depreciação por unidades produzidas).

N3_PRODANOnumber · opcionalSN3.N3_PRODANO

Produção do ano.

N3_DINDEPRstring (date) · opcionalSN3.N3_DINDEPR

Data de início da depreciação. Formato YYYYMMDD.

RespostaCriacao

object · envelope

Envelope das respostas 201 (POST) e 200 (PUT). data traz a chave do bem (útil quando o cliente quer reusar imediatamente em GET/PUT/DELETE).

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial.

data.cbasestring · opcional

N1_CBASE do bem afetado.

data.itemstring · opcional

N1_ITEM do bem afetado.

RespostaConsulta

object · envelope

Envelope do GET /WsSN1/{chave}. Retorna o bem completo (cabeçalho + array de itens SN3).

successboolean · const: true

Sempre true.

messagestring · opcional

Mensagem editorial (geralmente vazia em consulta).

data.cabecalhoCabecalho · obrigatório

Linha de SN1. Ver Cabecalho.

data.itensItem[] · obrigatório

Lista de tipos de saldo do bem. Ver Item.

RespostaListagem

object · envelope

Envelope do GET /WsSN1/_list. Devolve só campos de cabeçalho — não inclui o grid SN3.

successboolean · const: true

Sempre true.

pageinteger · obrigatório

Página atual.

pageSizeinteger · obrigatório

Tamanho da página efetivamente aplicado.

countinteger · obrigatório

Quantidade de itens no array data (não é o total geral).

dataCabecalhoListagem[] · obrigatório

Lista de capas: N1_CBASE, N1_ITEM, N1_DESCRIC, N1_CHAPA, N1_AQUISIC.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode trazer token interno da causa (ex: log do NomeAutoLog) para tratamento programático.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

Mensagem editorial do erro.

datastring · opcional

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