rev2-2026-05-01 Protheus 12.1.33

LancamentoContabil

CRUD de lançamento contábil (tabela CT2) via MsExecAuto da rotina padrão CTBA102. Substitui a User Function de desktop Gaiz_CargaCT2.prw (interativa, lia de view SQL Server). O identificador externo é a chave composta natural da CT2 — filial-data(YYYYMMDD)-lote-sublote-doc; em POST sem doc, o servidor gera por SOMA1 sobre o último documento da combinação filial/data/lote/sublote.

Bloqueio TOTVS: tabela CT2 — movimento contabil; sem MSBLQL nativo; bloqueio relevante esta em CT1 (conta) e CTH (classe).

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

Convenções

Chave composta. O identificador externo é a chave de negócio <filial>-<YYYYMMDD>-<lote>-<sublote>-<doc>, separada por hífens. Exemplo: 01-20991231-999-999-999999. O pattern aceito é ^[^-]+-\d{8}-[^-]+-[^-]+-[^-]+$. A data dentro da chave é sempre no formato YYYYMMDD (8 dígitos, sem separadores).

Documento gerado pelo servidor. Em POST /INCLUIR (sem {key} no path), o servidor gera o doc automaticamente via SOMA1 sobre o último CT2_DOC da combinação filial/data/lote/sublote. Em POST /INCLUIR/{key} o cliente força o documento — duplicata retorna 409.

Cabeçalho lógico, persistência por linha. A CT2 é uma tabela de linhas; o "lançamento" é um documento (CT2_DOC) cujas linhas compartilham a chave composta. O payload aceita um cabeçalho (filial, data, lote, sublote, padrao) + array itens[] com no mínimo 1 item — o CTBA102 persiste linha a linha.

Tipo de débito/crédito (dc). "1"=Débito (exige debito), "2"=Crédito (exige credito), "3"=Partida dobrada (exige debito + credito). Valores fora desse enum retornam 422.

Pré-requisitos ambientais. O CTBA102 é sensível à parametrização contábil. Para qualquer POST/PUT funcionar é preciso ter CT1 com as contas usadas, CTH com a combinação filial/lote/sublote, CTO com a moeda (moedlc, default "01") e o calendário contábil aberto na data. Sem isso, o MsExecAuto retorna 422 com a mensagem do NomeAutoLog.

Paginação e delta-sync no /_list. Default orderBy=chave com paginação por page/pageSize (default 50, máx 500). Para sincronização incremental, use orderBy=recno com paginação keyset via cursor (recno do último item da página anterior) — a resposta inclui nextCursor.

LancamentoContabil

CRUD por chave composta

POST /WsLancamentoContabil/INCLUIR Inclui lançamento; servidor gera doc

Descrição

Inclui um lançamento contábil via CTBA102 em modo 3. O servidor calcula o próximo CT2_DOC por SOMA1 sobre o último documento da combinação filial/data/lote/sublote — o cliente não envia doc. A resposta 201 traz a chave composta gerada em data.

Request body

application/json LancamentoPayload · obrigatório

Cabeçalho + array itens[] com no mínimo 1 linha. Schema completo em LancamentoPayload.

Lançamento de duas linhas (partida dobrada). Fixture: fixtures/post-valid.json.

RequestHTTP/1.1 · application/json

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

{
  "filial": "01",
  "data": "20991231",
  "lote": "999",
  "sublote": "999",
  "padrao": "",
  "itens": [
    {
      "moedlc": "01",
      "dc": "3",
      "debito": "1102001",
      "credito": "2101001",
      "valor": 100.00,
      "origem": "TESTE_REST CT2",
      "conver": "15555",
      "hist": "Teste smoke REST linha 1"
    },
    {
      "moedlc": "01",
      "dc": "3",
      "debito": "1102002",
      "credito": "2101002",
      "valor": 50.00,
      "origem": "TESTE_REST CT2",
      "conver": "15555",
      "hist": "Teste smoke REST linha 2"
    }
  ]
}

Respostas

201

Lançamento incluído. Envelope CrudResponse com data = chave composta gerada (filial-data-lote-sublote-doc).

400

Payload sem campos obrigatórios (filial, data, lote, sublote) ou data fora do pattern ^\d{8}$. Tier: validation-error.

422

Payload rejeitado pelo MsExecAuto do CTBA102 — conta não cadastrada (CT1), sublote ausente (CTH), moeda inválida (CTO), calendário fechado, dc fora de 1|2|3. Tier: business-error.

500

Erro interno.

POST /WsLancamentoContabil/INCLUIR/{key} Inclui com doc forçado pelo cliente

Descrição

Mesmo comportamento do POST sem chave, mas o cliente fixa o doc via path param. Útil para migração / carga com numeração externa preservada. Documento já existente para a chave retorna 409.

Path parameter

key string · path · obrigatório CT2.CT2_FILIAL+DATA+LOTE+SBLOTE+DOC

Chave composta <filial>-<YYYYMMDD>-<lote>-<sublote>-<doc>. Pattern: ^[^-]+-\d{8}-[^-]+-[^-]+-[^-]+$.

Request body

application/json LancamentoPayload · obrigatório

Mesmo schema do POST sem chave. Cabeçalho do body deve bater com o cabeçalho da chave do path (filial/data/lote/sublote).

Carga com numeração externa — doc fixo via path.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsLancamentoContabil/INCLUIR/01-20991231-999-999-999998
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "filial": "01",
  "data": "20991231",
  "lote": "999",
  "sublote": "999",
  "itens": [
    {
      "dc": "3",
      "debito": "1102001",
      "credito": "2101001",
      "valor": 100.00,
      "hist": "Carga numeracao externa"
    }
  ]
}

Respostas

201

Lançamento incluído. Envelope CrudResponse.

400

Chave fora do pattern ou payload sem obrigatórios. Tier: validation-error.

409

Documento já existe para a chave informada. Tier: business-error.

422

Rejeitado pelo MsExecAuto do CTBA102. Tier: business-error.

500

Erro interno.

GET /WsLancamentoContabil/{key} Consulta cabeçalho + linhas de um documento contábil

Descrição

Retorna o documento contábil completo — cabeçalho lógico (filial, data, lote, sublote, doc, contagem de linhas) e array linhas[] com os campos CT2_* de CAMPOS_GET de cada linha. Aplica filtro de filial via xFilial("CT2").

Path parameter

key string · path · obrigatório CT2.CT2_FILIAL+DATA+LOTE+SBLOTE+DOC

Chave composta <filial>-<YYYYMMDD>-<lote>-<sublote>-<doc>.

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsLancamentoContabil/01-20991231-999-999-999999
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lançamento encontrado. Envelope { success: true, data: LancamentoConsulta }.

400

Chave fora do pattern.

404

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

500

Erro interno.

PUT /WsLancamentoContabil/ALTERAR/{key} Altera lançamento existente (CTBA102 modo 4)

Descrição

Altera as linhas do lançamento via CTBA102 em modo 4. O cabeçalho lógico (chave composta) não muda — para mudar a chave, exclua e reinsira. As linhas vêm novamente no payload; o MsExecAuto substitui o conjunto.

Path parameter

key string · path · obrigatório CT2.CT2_FILIAL+DATA+LOTE+SBLOTE+DOC

Chave composta <filial>-<YYYYMMDD>-<lote>-<sublote>-<doc>.

Request body

application/json LancamentoPayload · obrigatório

Cabeçalho + array completo de linhas. O cabeçalho do body deve bater com a chave do path.

Altera valores e históricos. Fixture: fixtures/put-update.json.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsLancamentoContabil/ALTERAR/01-20991231-999-999-999999
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "filial": "01",
  "data": "20991231",
  "lote": "999",
  "sublote": "999",
  "padrao": "",
  "itens": [
    {
      "moedlc": "01",
      "dc": "3",
      "debito": "1102001",
      "credito": "2101001",
      "valor": 200.00,
      "origem": "TESTE_REST CT2 ALTERADO",
      "conver": "15555",
      "hist": "Teste smoke REST ALTERADO linha 1"
    },
    {
      "moedlc": "01",
      "dc": "3",
      "debito": "1102002",
      "credito": "2101002",
      "valor": 75.00,
      "origem": "TESTE_REST CT2 ALTERADO",
      "conver": "15555",
      "hist": "Teste smoke REST ALTERADO linha 2"
    }
  ]
}

Respostas

200

Lançamento alterado. Envelope CrudResponse.

400

Chave fora do pattern ou payload sem obrigatórios. Tier: validation-error.

404

Documento inexistente. Tier: not-found.

422

Rejeitado pelo MsExecAuto do CTBA102 (conta, sublote, moeda, calendário, dc). Tier: business-error.

500

Erro interno.

DEL /WsLancamentoContabil/EXCLUIR/{key} Exclui lançamento (CTBA102 modo 5)

Descrição

Exclui todas as linhas do lançamento via CTBA102 em modo 5. Lançamento já contabilizado / conciliado pode ser rejeitado pelo MsExecAuto com 422.

Path parameter

key string · path · obrigatório CT2.CT2_FILIAL+DATA+LOTE+SBLOTE+DOC

Chave composta <filial>-<YYYYMMDD>-<lote>-<sublote>-<doc>.

Chamada de exemplo

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsLancamentoContabil/EXCLUIR/01-20991231-999-999-999999
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lançamento excluído. Envelope CrudResponse.

400

Chave fora do pattern.

404

Documento inexistente. Tier: not-found.

422

Lançamento já contabilizado/conciliado, ou dependência interna do CTBA102. Tier: business-error.

500

Erro interno.

GET /WsLancamentoContabil/_byid Consulta por id técnico (recno|msuid)

Descrição

Resolve o lançamento por id técnico em vez da chave de negócio. tipo=recno faz DbGoTo com defesa multi-filial via xFilial; tipo=msuid resolve via campo CT2_MSUID (scan full, sem índice nativo) e retorna 501 quando o campo não existe no dicionário.

Query parameters

tipo string · query · obrigatório

Indica qual id técnico está sendo usado.

recnomsuid

valor string · query · obrigatório

Inteiro positivo quando tipo=recno; literal quando tipo=msuid.

Chamada de exemplo

Request · por recnoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsLancamentoContabil/_byid?tipo=recno&valor=1234
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Request · por msuidHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsLancamentoContabil/_byid?tipo=msuid&valor=9f7a3e2c4b8d1a0e
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lançamento encontrado. Envelope { success: true, data: LancamentoConsulta }.

400

tipo/valor ausentes ou tipo fora do enum.

404

Lançamento não localizado. Tier: not-found.

501

Busca por msuid requer campo CT2_MSUID não presente no dicionário deste ambiente.

500

Erro interno.

Listagem

Listagem paginada por filtros

GET /WsLancamentoContabil/_list Lista DOCs distintos com filtros e paginação

Descrição

Lista documentos contábeis distintos (uma entrada por filial+data+lote+sublote+doc) filtrados por filial, data, lote, sublote. Cada item inclui recno sempre, e msuid/msuidt quando o dicionário tem os campos.

orderBy=chave (default) — paginação offset por page/pageSize.
orderBy=recno — paginação keyset via cursor com nextCursor retornado.
since=<recno> — válido em orderBy=chave; cacheia "último recno visto".

Query parameters

filial string · query · opcional CT2.CT2_FILIAL

Filial (default xFilial("CT2")).

data string · query · opcional CT2.CT2_DATA

Data em YYYYMMDD.

lote string · query · opcional CT2.CT2_LOTE

Lote contábil.

sublote string · query · opcional CT2.CT2_SBLOTE

Sub-lote contábil.

page integer · query · opcional

Página (default 1); aplicável apenas em orderBy=chave.

pageSize integer · query · opcional

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

orderBy string · query · opcional

Modo de ordenação. Default chave.

chaverecno

since integer · query · opcional

Filtra RecNo() >= since. Aplicável em orderBy=chave.

cursor integer · query · opcional

Keyset cursor: emite registros com RecNo > cursor. Aplicável em orderBy=recno; cliente envia o nextCursor da página anterior.

Chamada de exemplo

Request · paginação por chaveHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsLancamentoContabil/_list?data=20991231&lote=999&page=1&pageSize=50
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Request · delta-sync por recnoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsLancamentoContabil/_list?orderBy=recno&cursor=0&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de documentos. Envelope com data[] (ListItem), orderBy, pageSize, count, e page (em orderBy=chave) ou nextCursor (em orderBy=recno).

400

Parâmetro fora do domínio (orderBy inválido, pageSize > 500, data mal formada).

500

Erro interno.

Schemas

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

ItemLancamento

object

Linha individual de um lançamento contábil. Vai dentro do array itens[] de LancamentoPayload.

moedlcstring · opcional · default "01"CT2.CT2_MOEDLC

Moeda do lançamento. Default "01" (moeda padrão da empresa).

dcstring · obrigatórioCT2.CT2_DC

"1"=Débito, "2"=Crédito, "3"=Partida dobrada.

123

debitostring · condicionalCT2.CT2_DEBITO

Conta de débito (CT1). Obrigatória quando dc ∈ {1, 3}.

creditostring · condicionalCT2.CT2_CREDIT

Conta de crédito (CT1). Obrigatória quando dc ∈ {2, 3}.

valornumber · obrigatórioCT2.CT2_VALOR

Valor do lançamento. > 0 (exclusiveMinimum).

origemstring · opcionalCT2.CT2_ORIGEM

Origem do lançamento (texto livre; útil para rastreabilidade de carga).

hpstring · opcionalCT2.CT2_HP

Histórico padrão (código de histórico parametrizado).

converstring · opcional · default "15555"CT2.CT2_CONVER

Indicador de conversão de moeda.

histstring · opcionalCT2.CT2_HIST

Histórico livre da linha.

LancamentoPayload

object

Payload completo aceito em POST e PUT — cabeçalho lógico + array de linhas (mínimo 1 item).

filialstring · obrigatórioCT2.CT2_FILIAL

Filial do lançamento.

datastring · obrigatórioCT2.CT2_DATA

Data contábil em YYYYMMDD. Pattern: ^\d{8}$.

lotestring · obrigatórioCT2.CT2_LOTE

Lote contábil.

sublotestring · obrigatórioCT2.CT2_SBLOTE

Sub-lote (cadastrado em CTH).

padraostring · opcional

Lançamento padrão (CPADRAO). Vazio = lançamento livre.

itensarray<ItemLancamento> · obrigatório

Linhas do lançamento — mínimo 1 (minItems: 1). Schema em ItemLancamento.

LancamentoConsulta

object

Resposta dos GETs por chave de negócio e por id técnico — cabeçalho lógico do documento + array de linhas com campos CT2_* filtrados por CAMPOS_GET no .prw.

filialstringCT2.CT2_FILIAL

Filial do documento.

datastringCT2.CT2_DATA

Data contábil (YYYYMMDD).

lotestringCT2.CT2_LOTE

Lote.

sublotestringCT2.CT2_SBLOTE

Sub-lote.

docstringCT2.CT2_DOC

Documento.

countinteger

Quantidade de linhas retornadas.

linhasarray<object>

Linhas CT2_* (campos do CAMPOS_GET) + recno/msuid/msuidt quando disponíveis.

recnointeger · opcional

RecNo da primeira linha (id técnico ancorado ao documento).

msuidstring · opcionalCT2.CT2_MSUID

Identificador universal — só aparece quando o dicionário tem o campo.

msuidtstring · opcionalCT2.CT2_MSUIDT

Timestamp técnico — só aparece quando o dicionário tem o campo.

ListItem

object

Item enxuto do /_list — uma entrada por documento distinto (chave composta), sem o array de linhas.

filialstringCT2.CT2_FILIAL

Filial.

datastringCT2.CT2_DATA

Data contábil (YYYYMMDD).

lotestringCT2.CT2_LOTE

Lote.

sublotestringCT2.CT2_SBLOTE

Sub-lote.

docstringCT2.CT2_DOC

Documento.

recnointeger

RecNo da primeira linha do documento. Sempre presente.

msuidstring · opcionalCT2.CT2_MSUID

Só quando o dicionário tem o campo.

msuidtstring · opcionalCT2.CT2_MSUIDT

Só quando o dicionário tem o campo.

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. data traz a chave composta gerada (POST) ou string vazia (PUT/DELETE).

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso.

datastring | object · opcional

Em POST, a chave composta gerada (ex: "01-20991231-999-999-999999"). Em PUT/DELETE pode ser string vazia.

Erro

object · envelope

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

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

Mensagem editorial do erro.

datastring · opcional

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