rev1-2026-05-07 Protheus 12.1.33

ContratoParceria

CRUD de Contrato de Parceria (tabela SC3) via rotina automática MATA125. Modelo 2 da TOTVS: o cabeçalho e os itens convivem na mesma tabela — cada linha do SC3 compartilha C3_NUM e diferencia-se por C3_ITEM. O número do contrato (C3_NUM) é gerado pelo Protheus no POST via GetSXENum + loop ConfirmSX8; no path use auto como placeholder.

Bloqueio TOTVS: tabela SC3 — verificar SX3 se C3_MSBLQL existe nesta base; bloqueio relevante esta em SA2 (fornecedor).

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

Convenções

Identificador externo. O contrato é identificado por C3_NUM (gerado pelo Protheus). No POST, o path param {numero} deve ser auto — qualquer string é aceita, mas o número efetivo só é conhecido após a inclusão e vem em data.numero. Em PUT/DELETE/GET, {numero} é o C3_NUM retornado anteriormente.

Modelo 2 (capa+itens na mesma tabela). Cada item é uma linha do SC3 com o mesmo C3_NUM e C3_ITEM distinto (sequencial, padding com StrZero no tamanho de C3_ITEM). O GET /_list deduplica por C3_NUM (1 linha por contrato); o GET /{numero} devolve { cabecalho, itens[] }.

Semântica delta no PUT. Cada elemento de itens[] se enquadra em um dos três casos: (a) alterar item existente — informar LINPOS com o C3_ITEM alvo + campos a alterar; (b) excluir item — LINPOS + AUTDELETA: "S"; (c) item novo — sem LINPOS, numerado pelo servidor como Max(C3_ITEM) + 1. Pelo menos 1 item é obrigatório no PUT.

Chave externa congelada no PUT. Alterar C3_FORNECE / C3_LOJA no cabeçalho via PUT não é suportado — esses campos são reaproveitados do registro posicionado para preservar consistência da rotina automática MATA125.

Formato de datas. C3_EMISSAO, C3_DATPRI e C3_DATPRF aceitam string AAAAMMDD no payload (ex: "20260507"). A conversão interna usa SToD(...). Ausência de C3_EMISSAO no POST cai no default dDataBase.

Paginação. /_list usa page/pageSize (default 50, máx 500). Filtros suportados: num (prefix de C3_NUM), fornece, loja, emissao (AAAAMMDD exato).

ContratoParceria

Operações sobre Contrato de Parceria (SC3)

POST /WsSC3/INCLUIR/{numero} Inclui Contrato de Parceria

Descrição

Cria um novo Contrato de Parceria via MATA125 em modo 3 (inclusão). O C3_NUM é gerado pelo Protheus (GetSXENum + loop ConfirmSX8) — o cliente envia apenas o cabeçalho e os itens. O path param {numero} deve ser auto (placeholder).

Fornecedor (C3_FORNECE + C3_LOJA) validado em SA2 antes de tocar MsExecAuto.
Cada item exige C3_PRODUTO existente em SB1 e C3_QUANT presente.
Cabeçalho aceita whitelist CAMPOS_CAB_ALLOW; itens, CAMPOS_ITEM_ALLOW.

Path parameter

numero string · path · obrigatório SC3.C3_NUM

Para POST, use auto — o número efetivo é gerado pelo servidor e devolvido em data.numero.

Request body

application/json PostBody · obrigatório

Objeto com cabecalho (obj) e itens (array, mínimo 1). Schema: PostBody.

Payload mínimo — fornecedor, loja, condição, moeda no cabeçalho e 1 item com produto/quantidade/preço/total.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "C3_FORNECE": "000001",
    "C3_LOJA": "01",
    "C3_COND": "001",
    "C3_MOEDA": "1"
  },
  "itens": [
    {
      "C3_PRODUTO": "01",
      "C3_QUANT": 2,
      "C3_PRECO": 135,
      "C3_TOTAL": 270
    }
  ]
}

Payload realista — inclui emissão, datas de previsão/prazo no item, observação e contato. Demonstra dois itens distintos.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "C3_FORNECE": "000001",
    "C3_LOJA": "01",
    "C3_COND": "001",
    "C3_MOEDA": "1",
    "C3_EMISSAO": "20260507",
    "C3_OBS": "Contrato anual rev1",
    "C3_CONTATO": "FULANO COMPRAS"
  },
  "itens": [
    {
      "C3_PRODUTO": "01",
      "C3_QUANT": 2,
      "C3_PRECO": 135,
      "C3_TOTAL": 270,
      "C3_DATPRI": "20260507",
      "C3_DATPRF": "20260607"
    },
    {
      "C3_PRODUTO": "02",
      "C3_QUANT": 5,
      "C3_PRECO": 42,
      "C3_TOTAL": 210
    }
  ]
}

Respostas

201

Contrato incluído. Envelope RespCriado com data.numero contendo o C3_NUM gerado.

400

Body JSON ausente/inválido, bloco cabecalho ou itens ausente. Tier: validation-error.

422

Validação de negócio falhou — fornecedor inexistente em SA2, produto fora do SB1, condição inválida, ou rejeição do MsExecAuto do MATA125. Tier: business-error.

500

Erro interno (falha em GetSXENum, exceção no MATA125, etc).

PUT /WsSC3/ALTERAR/{numero} Altera contrato (delta de itens)

Descrição

Altera campos do cabeçalho e/ou itens do contrato via MATA125 em modo 4. A semântica é delta: o array itens declara as operações a aplicar, não o estado final desejado.

LINPOS = "C3_ITEM" existente → posiciona para alteração ou exclusão.
AUTDELETA = "S" exclui; "N" mantém (default).
Item sem LINPOS → cria nova linha (numerada após o último C3_ITEM existente).
Pelo menos 1 item é obrigatório (o array não pode estar vazio).
C3_FORNECE/C3_LOJA no cabeçalho são ignorados — reaproveitados do registro posicionado.

Path parameter

numero string · path · obrigatório SC3.C3_NUM

C3_NUM do contrato a alterar.

Request body

application/json PutBody · obrigatório

Cabeçalho opcional, lista de itens com semântica delta. Schema: PutBody.

Delta completo — altera item 0001, exclui item 0002 e cria item novo numa única operação. Caso mais representativo da semântica delta do PUT.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "C3_COND": "002"
  },
  "itens": [
    {
      "LINPOS": "0001",
      "AUTDELETA": "N",
      "C3_QUANT": 5
    },
    {
      "LINPOS": "0002",
      "AUTDELETA": "S"
    },
    {
      "C3_PRODUTO": "07",
      "C3_QUANT": 1,
      "C3_PRECO": 50,
      "C3_TOTAL": 50
    }
  ]
}

Apenas alterar cabeçalho — itens existentes informados com AUTDELETA: "N" para preservá-los. Lembre que o array de itens não pode estar vazio.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "C3_OBS": "Observacao atualizada",
    "C3_CONTATO": "NOVO CONTATO"
  },
  "itens": [
    { "LINPOS": "0001", "AUTDELETA": "N" }
  ]
}

Excluir item — remove a linha 0002 sem alterar mais nada. LINPOS + AUTDELETA: "S" bastam.

RequestHTTP/1.1 · application/json

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

{
  "itens": [
    { "LINPOS": "0002", "AUTDELETA": "S" }
  ]
}

Adicionar item novo — sem LINPOS, a linha é numerada como Max(C3_ITEM existente) + 1 (StrZero no tamanho de C3_ITEM). C3_PRODUTO é validado em SB1 antes do MsExecAuto.

RequestHTTP/1.1 · application/json

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

{
  "itens": [
    {
      "C3_PRODUTO": "07",
      "C3_QUANT": 1,
      "C3_PRECO": 50,
      "C3_TOTAL": 50
    }
  ]
}

Respostas

200

Contrato alterado. Envelope RespOk com data.numero.

400

Path param inválido, body JSON ausente, ou itens vazio. Tier: validation-error.

404

C3_NUM informado não localizado. Tier: not-found.

422

Item novo com C3_PRODUTO ausente/inexistente em SB1, ou rejeição do MsExecAuto do MATA125 (campos fora do whitelist, datas inválidas, etc). Tier: business-error.

500

Erro interno.

DEL /WsSC3/EXCLUIR/{numero} Exclui contrato (cabeçalho + todos os itens)

Descrição

Exclui o contrato inteiro (cabeçalho + todos os itens) via MATA125 em modo 5. O endpoint monta um aCabec mínimo com C3_FILIAL + C3_NUM + C3_FORNECE/C3_LOJA lidos do registro posicionado.

Path parameter

numero string · path · obrigatório SC3.C3_NUM

C3_NUM do contrato a excluir.

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Contrato excluído. Envelope RespOk.

400

Path param ausente ou maior que o tamanho de C3_NUM. Tier: validation-error.

404

Contrato inexistente. Tier: not-found.

422

Rejeição do MsExecAuto — contrato pode ter dependências em outras tabelas (pedidos vinculados, integridade referencial). Tier: business-error.

500

Erro interno.

GET /WsSC3/{numero} Consulta contrato por número

Descrição

Retorna o contrato pesquisado por C3_NUM, montando { cabecalho, itens[] }. O cabeçalho vem do primeiro registro encontrado e o array de itens enumera todas as linhas com o mesmo C3_NUM e C3_FILIAL coincidente. Whitelist CAMPOS_CAB_GET e CAMPOS_ITEM_GET controlam os campos retornados.

Path parameter

numero string · path · obrigatório SC3.C3_NUM

C3_NUM do contrato. Para listagem, use /_list.

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Contrato encontrado. Envelope RespByNum com data: { cabecalho, itens[] }.

400

Número ausente ou maior que o tamanho de C3_NUM. Tier: validation-error.

404

Contrato inexistente ou sem itens. Tier: not-found.

Listagem

Listagem paginada (1 linha por contrato)

GET /WsSC3/_list Lista contratos com filtros e paginação

Descrição

Lista contratos com filtros opcionais por num (prefix de C3_NUM), fornece (C3_FORNECE exato), loja (C3_LOJA exato), emissao (C3_EMISSAO em formato AAAAMMDD).

O retorno é deduplicado por C3_NUM — cada contrato aparece em uma única linha mesmo que tenha múltiplos itens em SC3.

Query parameters

num string · query · opcional SC3.C3_NUM

Prefix de C3_NUM (usa DbSeek(...,.T.)).

fornece string · query · opcional SC3.C3_FORNECE

Filtro exato por C3_FORNECE.

loja string · query · opcional SC3.C3_LOJA

Filtro exato por C3_LOJA.

emissao string · query · opcional SC3.C3_EMISSAO

Filtro exato em AAAAMMDD (ex: 20260507).

page integer · query · opcional

Página (default 1, mínimo 1).

pageSize integer · query · opcional

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

Chamada de exemplo

Request · sem filtroHTTP/1.1 · sem body

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

Request · filtro por fornecedor + emissãoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSC3/_list?fornece=000001&loja=01&emissao=20260507
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de contratos. Envelope RespList com data[], page, pageSize, count.

500

Erro interno.

Schemas

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

Cabecalho

object

Bloco de cabeçalho do contrato. Whitelist de campos aceitos (CAMPOS_CAB_ALLOW): apenas os listados abaixo entram em aCabec do MsExecAuto.

C3_FORNECEstring · obrigatório no POSTSC3.C3_FORNECE

Código do fornecedor (SA2.A2_COD). Validado em SA2 via DbSeek.

C3_LOJAstring · obrigatório no POSTSC3.C3_LOJA

Loja do fornecedor (SA2.A2_LOJA), tipicamente "01".

C3_CONDstring · opcionalSC3.C3_COND

Código da condição de pagamento (SE4.E4_CODIGO).

C3_MOEDAstring · opcionalSC3.C3_MOEDA

Código da moeda. "1" = Real (default usual).

C3_EMISSAOstring · opcionalSC3.C3_EMISSAO

Data de emissão em AAAAMMDD (ex: "20260507"). Default dDataBase quando omitido no POST.

C3_OBSstring · opcionalSC3.C3_OBS

Observação livre do contrato.

C3_CONTATOstring · opcionalSC3.C3_CONTATO

Contato responsável pelo contrato.

Item

object

Item do contrato (linha do SC3 com o mesmo C3_NUM). Whitelist CAMPOS_ITEM_ALLOW aceita no payload de POST/PUT.

C3_PRODUTOstring · obrigatório (item novo)SC3.C3_PRODUTO

Código do produto (SB1.B1_COD). Validado em SB1 via DbSeek.

C3_QUANTnumber · obrigatório (item novo)SC3.C3_QUANT

Quantidade contratada.

C3_PRECOnumber · opcionalSC3.C3_PRECO

Preço unitário.

C3_TOTALnumber · opcionalSC3.C3_TOTAL

Valor total (C3_QUANT × C3_PRECO, calculado pelo cliente).

C3_DATPRIstring · opcionalSC3.C3_DATPRI

Data de previsão (AAAAMMDD).

C3_DATPRFstring · opcionalSC3.C3_DATPRF

Data prevista de fim (AAAAMMDD).

C3_LOCALstring · opcionalSC3.C3_LOCAL

Local de estoque associado ao item.

C3_OBSstring · opcionalSC3.C3_OBS

Observação no nível do item.

C3_ITEMstring · serializado no GETSC3.C3_ITEM

Número sequencial do item (StrZero no tamanho de C3_ITEM). Gerado pelo servidor; não é aceito no payload (use LINPOS).

ItemDelta

object · extends Item

Item enriquecido para PUT — herda todos os campos de Item e adiciona dois campos de controle (LINPOS e AUTDELETA) que orquestram o delta.

LINPOSstring · opcional

C3_ITEM de um item existente. Presente → o item é posicionado para alteração/exclusão. Ausente → o item é tratado como linha nova.

AUTDELETAstring · opcional · default "N"

"S" exclui o item posicionado por LINPOS; "N" mantém. Em item novo, é forçado para "N" internamente.

SN

PostBody

object · envelope de inclusão

Payload do POST. cabecalho exige C3_FORNECE + C3_LOJA e itens precisa ter pelo menos um elemento.

cabecalhoCabecalho · obrigatório

Cabeçalho do contrato. C3_FORNECE e C3_LOJA são exigidos; demais campos seguem Cabecalho.

itensarray<Item> · obrigatório · minItems 1

Lista de itens. Cada elemento segue Item; C3_PRODUTO e C3_QUANT são obrigatórios.

PutBody

object · envelope delta

Payload do PUT. cabecalho é opcional; itens obrigatório com pelo menos 1 elemento (cada um é um ItemDelta).

cabecalhoCabecalho · opcional

Campos de cabeçalho a alterar. C3_FORNECE/C3_LOJA enviados aqui são descartados (chave externa congelada).

itensarray<ItemDelta> · obrigatório · minItems 1

Lista de operações delta. Cada elemento altera, exclui ou cria um item.

RespByNum

object · envelope

Resposta do GET /WsSC3/{numero}. data encapsula cabecalho + itens[] reconstruídos a partir das linhas do SC3.

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial (vazia em sucesso).

data.cabecalhoCabecalho · obrigatório

Cabeçalho do contrato — campos definidos por CAMPOS_CAB_GET.

data.itensarray<Item> · obrigatório

Lista de itens — campos definidos por CAMPOS_ITEM_GET.

RespList

object · envelope paginado

Resposta paginada do /_list. Cada elemento de data representa um contrato (deduplicado por C3_NUM).

successboolean

Sempre true.

messagestring

Mensagem editorial (vazia em sucesso).

pageinteger

Página atual.

pageSizeinteger

Tamanho da página efetivo (já capado em 500).

countinteger

Número de elementos retornados na página.

data[].C3_NUMstringSC3.C3_NUM

Número do contrato.

data[].C3_FORNECEstringSC3.C3_FORNECE

Código do fornecedor.

data[].C3_LOJAstringSC3.C3_LOJA

Loja do fornecedor.

data[].C3_EMISSAOstringSC3.C3_EMISSAO

Data de emissão (AAAAMMDD).

RespOk · RespCriado

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. Em POST (RespCriado) data.numero traz o C3_NUM gerado; em PUT, data.numero ecoa o C3_NUM alterado; em DELETE, data fica vazio.

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso.

data.numerostring · opcionalSC3.C3_NUM

C3_NUM envolvido na operação (gerado no POST, ecoado no PUT, ausente no DELETE).

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode conter detalhe técnico da rejeição (mensagem do NomeAutoLog do MsExecAuto, etc).

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.