rev5-2026-05-14 Protheus 12.1.33

CadastroCliente

CRUD de cliente (tabela SA1) via MVC do CRMA980 — substituto moderno do antigo MATA030. Identificador externo é CNPJ (14 dígitos) ou CPF (11 dígitos); a chave técnica (A1_COD/A1_LOJA) é gerada pelo Protheus no POST via GetSXENum.

Vinculação com o ERP

Tabela mestre SA1 Cadastro de clientes

Rotina automática CRMA980 MVC · MsExecAuto

Wrapper AdvPL U_C980Exc src/lib/CRM/CRM980EXC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Cadastro

Cliente (estado de bloqueio)

tabela SA1 · campos A1_MSBLQL + A1_MSBLQD
A1_MSBLQL pertence("12") · "1"=Inativo (bloqueado), "2"=Ativo (default)

Integração · condicional

Localização Brasil

função CRMA980BRA · disparada via FwLoadBy*
ativa quando ambiente tem localização BR e payload inclui A1_INSCR + A1_EST

Sequência

Numeração SX8

GetSXENum("SA1","A1_COD") + Soma1 + ConfirmSX8
gerada pelo Protheus no POST · RollBackSX8 em erro

Convenções

Identificador externo. Todas as rotas /WsSA1/{cgc} aceitam apenas dígitos — 14 (CNPJ) ou 11 (CPF). Pontuação (., /, -) é rejeitada com 400. A chave interna A1_COD/A1_LOJA não é exposta como identificador externo; use /_byid?tipo=recno|msuid&valor=… quando precisar buscar por ela.

Bloqueio TOTVS (A1_MSBLQL / A1_MSBLQD). Em registro bloqueado, o PUT só aceita payload que toque exclusivamente os campos de bloqueio (caminho de desbloqueio). Qualquer outro campo no payload retorna 422 com motivo explícito. DELETE em cliente bloqueado também é rejeitado pelo MsExecAuto do CRMA980.

Polaridade do par MSBLQL/MSBLQD varia por tabela. Na SA1, A1_MSBLQL="1" é Inativo (bloqueado) e "2" é Ativo (liberado, default). Outras tabelas TOTVS podem inverter — consultar SX3 antes de replicar este padrão em outro endpoint.

Formato de datas. A1_MSBLQD no payload aceita string ISO YYYY-MM-DD ou string vazia (limpa a data); a conversão interna usa sToD(StrTran(…, "-", "")). No GET o campo é serializado por U_RestSerializa (Date-aware, rev3).

Paginação e delta-sync. /_list usa page/pageSize (default 50, máx 500). Para sincronização incremental, alterne para orderBy=recno e use since/cursor conforme o nextCursor retornado.

Cliente

CRUD por CNPJ/CPF

GET /WsSA1/{cgc} Consulta cliente por CGC

Descrição

Retorna o cliente pesquisado pelo CGC (CNPJ 14 dígitos ou CPF 11 dígitos). Aplica filtro de filial (xFilial("SA1")) e respeita o whitelist de CAMPOS_GET definido no .prw. O parâmetro opcional fields reduz o conjunto de campos retornados.

Path parameter

cgc string · path · obrigatório SA1.A1_CGC

CPF (11) ou CNPJ (14), apenas dígitos. Pattern: ^\d{11}$|^\d{14}$.

Query parameters

fields string · query · opcional

Lista de campos separados por vírgula. Validados contra CAMPOS_GET.

Cenarios

Exemplo da requisicao (cenario ativo)

Consulta direta — retorna whitelist completo de CAMPOS_GET.

RequestHTTP/1.1 · sem body

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

Consulta com fields — reduz payload de retorno via fields=.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSA1/99999999000199?fields=A1_COD,A1_NOME,A1_CGC,A1_MSBLQL
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Cliente encontrado. Envelope { success: true, data: Cliente }.

400

CGC fora do pattern. Tier: validation-error.

404

Cliente inexistente para o CGC informado. Tier: not-found.

500

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

POST /WsSA1/{cgc} Inclui novo cliente

Descrição

Inclui um cliente novo via CRMA980 em modo 3 (MODEL_OPERATION_INSERT). A chave técnica A1_COD/A1_LOJA é gerada pelo Protheus (GetSXENum + Soma1 + ConfirmSX8) — o cliente passa apenas o CGC. Em ambientes com localização Brasil, CRMA980BRA é disparado automaticamente quando o payload contém A1_INSCR + A1_EST.

Whitelist de campos: ver ClientePayload.
Complemento CRM (AI0) não é exposto nesta versão; o endpoint passa {}.

Path parameter

cgc string · path · obrigatório SA1.A1_CGC

CPF (11) ou CNPJ (14), apenas dígitos. Pattern: ^\d{11}$|^\d{14}$.

Request body

application/json ClientePayload · obrigatório

Payload plano com campos do whitelist CAMPOS_ALLOW. Schema completo em ClientePayload.

A1_NOME string · obrigatório SA1.A1_NOME

Razão social (PJ) ou nome completo (PF).

A1_NREDUZ string SA1.A1_NREDUZ

Nome reduzido (máx. 20).

A1_END string SA1.A1_END

Endereço (logradouro + número).

A1_BAIRRO string SA1.A1_BAIRRO

Bairro.

A1_MUN string SA1.A1_MUN

Município.

A1_EST string SA1.A1_EST

UF (2 chars).

A1_CEP string SA1.A1_CEP

CEP (8 dígitos, sem traço).

A1_DDD string SA1.A1_DDD

DDD (3 dígitos com zero à esquerda).

A1_TEL string SA1.A1_TEL

Telefone (apenas dígitos).

A1_EMAIL string SA1.A1_EMAIL

E-mail principal.

A1_TIPO string · obrigatório SA1.A1_TIPO

Tipo do cliente: F = Consumidor Final, R = Revenda, S = Solidário, X = Exportação.

A1_PFISICA string · obrigatório SA1.A1_PFISICA

Natureza: J = Jurídica (CGC 14), F = Física (CGC 11).

A1_INSCR string SA1.A1_INSCR

Inscrição Estadual ou ISENTO.

Payload mínimo (PJ) — apenas obrigatórios do CRMA980 para Pessoa Jurídica. Fixture: fixtures/create.json.

RequestHTTP/1.1 · application/json

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

{
  "A1_NOME": "TESTE_REST CLIENTE LTDA",
  "A1_NREDUZ": "TESTE_REST",
  "A1_END": "RUA TESTE 100",
  "A1_BAIRRO": "CENTRO",
  "A1_MUN": "SAO PAULO",
  "A1_EST": "SP",
  "A1_CEP": "01001000",
  "A1_DDD": "011",
  "A1_TEL": "999990000",
  "A1_EMAIL": "teste_rest@example.com",
  "A1_TIPO": "F",
  "A1_PFISICA": "J",
  "A1_INSCR": "ISENTO"
}

Pessoa Física (CPF) — payload realista com A1_PFISICA="F". Fixture: fixtures/create-pf.json.

RequestHTTP/1.1 · application/json

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

{
  "A1_NOME": "TESTE_REST CLIENTE PF",
  "A1_NREDUZ": "TESTE_PF",
  "A1_END": "RUA TESTE PF 100",
  "A1_BAIRRO": "CENTRO",
  "A1_MUN": "SAO PAULO",
  "A1_EST": "SP",
  "A1_CEP": "01001000",
  "A1_DDD": "011",
  "A1_TEL": "999990001",
  "A1_EMAIL": "teste_pf@example.com",
  "A1_TIPO": "F",
  "A1_PFISICA": "F",
  "A1_INSCR": "ISENTO"
}

Respostas

201

Cliente incluído. Envelope CrudResponse com data = chave técnica gerada (A1_COD/A1_LOJA).

400

CGC fora do pattern. Tier: validation-error.

409

Cliente já existe para o CGC. Tier: business-error.

422

Payload inválido — MsExecAuto do CRMA980 rejeitou (campos fora do whitelist, enums inválidos, IE incompatível com UF, etc). Tier: business-error.

500

Erro interno.

PUT /WsSA1/{cgc} Altera cliente existente

Descrição

Altera campos do cliente via CRMA980 em modo 4 (MODEL_OPERATION_UPDATE). Aceita qualquer subconjunto do whitelist CAMPOS_ALLOW.

Bloqueio TOTVS. Em registro bloqueado por A1_MSBLQL="1" ou dDataBase > A1_MSBLQD, o PUT retorna 422 a menos que o payload toque exclusivamente A1_MSBLQL/A1_MSBLQD (caminho de desbloqueio).

A1_MSBLQL: "1" = Inativo, "2" = Ativo (default).
A1_MSBLQD: string ISO YYYY-MM-DD ou vazia (limpa).

Path parameter

cgc string · path · obrigatório SA1.A1_CGC

CPF (11) ou CNPJ (14), apenas dígitos.

Request body

application/json ClientePayload · obrigatório

Subconjunto do whitelist. Em cliente bloqueado, ver convenções.

A1_NOME string SA1.A1_NOME

Razão social.

A1_NREDUZ string SA1.A1_NREDUZ

Nome reduzido.

A1_END string SA1.A1_END

Endereço.

A1_BAIRRO string SA1.A1_BAIRRO

Bairro.

A1_EMAIL string SA1.A1_EMAIL

E-mail principal.

A1_MSBLQL string SA1.A1_MSBLQL · combobox

Flag de bloqueio: "1" = Inativo, "2" = Ativo. Em registro bloqueado, só este campo (e/ou A1_MSBLQD) é aceito no payload.

A1_MSBLQD string SA1.A1_MSBLQD · Date

Data de vigência do bloqueio (ISO YYYY-MM-DD) ou string vazia para limpar.

Alteração comum — atualiza dados cadastrais sem mexer no bloqueio. Fixture: fixtures/update.json.

RequestHTTP/1.1 · application/json

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

{
  "A1_NOME": "TESTE_REST CLIENTE LTDA ALTERADO",
  "A1_NREDUZ": "TESTE_ALT",
  "A1_END": "RUA TESTE 200",
  "A1_BAIRRO": "VILA TESTE",
  "A1_EMAIL": "teste_rest_alt@example.com"
}

Liberar registro bloqueado — caminho de desbloqueio. Em cliente bloqueado, esse é um dos dois únicos payloads aceitos. Qualquer campo fora do par A1_MSBLQL/A1_MSBLQD provoca 422.

RequestHTTP/1.1 · application/json

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

{
  "A1_MSBLQL": "2"
}

Bloqueio manual com vigência futura — define A1_MSBLQL="1" (Inativo) e A1_MSBLQD no futuro. O MsExecAuto interpreta a data como vigência.

RequestHTTP/1.1 · application/json

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

{
  "A1_MSBLQL": "1",
  "A1_MSBLQD": "2026-12-31"
}

Limpa data de bloqueio — passa A1_MSBLQD="" para zerar a data. Combinável com mudança de A1_MSBLQL no mesmo payload.

RequestHTTP/1.1 · application/json

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

{
  "A1_MSBLQL": "2",
  "A1_MSBLQD": ""
}

Respostas

200

Cliente alterado. Envelope CrudResponse.

400

CGC fora do pattern. Tier: validation-error.

404

Cliente inexistente. Tier: not-found.

422

Validação de payload (whitelist, enum) ou registro bloqueado com payload tocando campos fora do par A1_MSBLQL/A1_MSBLQD. Tier: business-error.

500

Erro interno.

DEL /WsSA1/{cgc} Exclui cliente

Descrição

Exclui o cliente via CRMA980 em modo 5 (MODEL_OPERATION_DELETE). O MsExecAuto do CRMA980 rejeita exclusão de registros bloqueados.

Path parameter

cgc string · path · obrigatório SA1.A1_CGC

CPF (11) ou CNPJ (14), apenas dígitos.

Cenario

Exemplo da requisicao (cenario ativo)

Exclusao direta — chama CRMA980 op=5. Falha 422 em cliente bloqueado ou com dependencias.

RequestHTTP/1.1 · sem body

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

Respostas

200

Cliente excluído. Envelope CrudResponse.

400

CGC fora do pattern. Tier: validation-error.

404

Cliente inexistente. Tier: not-found.

422

Cliente bloqueado ou tem dependências (títulos abertos, contatos vinculados). Tier: business-error.

500

Erro interno.

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

Descrição

Busca o cliente por id técnico — útil para integrações que persistem a chave interna (recno) ou o identificador universal (msuid) e querem reconfirmar o registro sem reconstruir o CGC.

Query parameters

tipo string · query · obrigatório

Indica qual id técnico está sendo usado.

recnomsuid

valor string · query · obrigatório

Valor do id (inteiro quando tipo=recno, string quando tipo=msuid).

Cenarios

Exemplo da requisicao (cenario ativo)

Por RecNo — caminho recomendado.

RequestHTTP/1.1 · sem body

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

Por MSUID — utiliza A1_MSUID (presente nesta base).

RequestHTTP/1.1 · sem body

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

Respostas

200

Cliente encontrado. Envelope { success: true, data: Cliente }.

400

Parâmetros tipo/valor ausentes ou tipo fora do enum.

404

Cliente não localizado. Tier: not-found.

501

Busca por msuid requer índice/coluna não disponível no ambiente.

500

Erro interno.

Listagem

Listagem paginada e typeahead

GET /WsSA1/_list Lista clientes com filtros e paginação

Descrição

Lista clientes com filtros por cod, nome (prefix normalizado, sem acento) ou cgc (prefix). Suporta dois modos de ordenação:

orderBy=chave (default) — paginação por page/pageSize.
orderBy=recno — delta-sync, usa since/cursor com nextCursor retornado.

Query parameters

cod string · query · opcional SA1.A1_COD

A1_COD exato (índice 1).

nome string · query · opcional SA1.A1_NOME

Prefix normalizado (sem acento, uppercase).

cgc string · query · opcional SA1.A1_CGC

CGC prefix (índice 3).

fields string · query · opcional

Lista de campos validados contra CAMPOS_GET.

page integer · query · opcional

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

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

Início do delta-sync (válido com orderBy=recno).

cursor integer · query · opcional

Cursor retornado em nextCursor de página anterior.

Cenarios

Exemplo da requisicao (cenario ativo)

Paginacao por chave — modo default com filtro por prefixo de nome.

RequestHTTP/1.1 · sem body

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

Delta-sync por RecNo — cliente itera via nextCursor.

RequestHTTP/1.1 · sem body

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

Respostas

200

Página de clientes. Envelope com data (array de Cliente), page, pageSize, count, opcionalmente nextCursor.

400

Parâmetro fora do domínio (ex: orderBy inválido, pageSize > 500).

500

Erro interno.

GET /WsSA1/_search Typeahead por nome ou CGC

Descrição

Busca rápida (typeahead) para autocomplete de UI. Retorna uma lista enxuta (cod, loja, cgc, nome, recno, msuid, msuidt) — não devolve o schema completo de Cliente.

Query parameters

q string · query · obrigatório

Termo de busca. Mínimo 2 caracteres.

match string · query · opcional

Modo de match. Default prefix.

prefixcontains

limit integer · query · opcional

Quantidade máxima (default 10, máx 25).

Cenarios

Exemplo da requisicao (cenario ativo)

Match por prefixo — modo default; mais rapido (usa indice de A1_NOME).

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSA1/_search?q=teste&match=prefix&limit=10
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Match contendo termo — busca por substring; full-scan da tabela, mais caro.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSA1/_search?q=cliente&match=contains&limit=25
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lista enxuta de sugestões. Envelope: success, count, data[] com cod/loja/cgc/nome/recno/msuid/msuidt.

400

q ausente ou < 2 caracteres, match fora do enum.

500

Erro interno.

Schemas

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

Cliente

object

Representação retornada nos GETs (/{cgc}, /_list, /_byid). Inclui chave técnica (A1_COD/A1_LOJA), dados cadastrais e flags de bloqueio. Campos efetivamente retornados dependem de CAMPOS_GET e do filtro fields.

A1_CODstring · opcionalSA1.A1_COD

Chave técnica do cliente (sequência gerada por GetSXENum).

A1_LOJAstring · opcionalSA1.A1_LOJA

Loja do cliente (default "01").

A1_NOMEstring · opcionalSA1.A1_NOME

Razão social ou nome completo.

A1_NREDUZstring · opcionalSA1.A1_NREDUZ

Nome reduzido / fantasia.

A1_ENDstring · opcionalSA1.A1_END

Endereço (logradouro + número).

A1_BAIRROstring · opcionalSA1.A1_BAIRRO

Bairro.

A1_ESTstring · opcionalSA1.A1_EST

UF (sigla, 2 letras).

A1_CEPstring · opcionalSA1.A1_CEP

CEP (8 dígitos, sem hífen).

A1_TIPOstring · opcionalSA1.A1_TIPO

Tipo do cliente.

FRSLX

A1_PFISICAstring · opcionalSA1.A1_PFISICA

Pessoa Física (F) ou Jurídica (J).

FJ

A1_DDDstring · opcionalSA1.A1_DDD

DDD do telefone principal.

A1_TELstring · opcionalSA1.A1_TEL

Telefone principal.

A1_EMAILstring · opcionalSA1.A1_EMAIL

E-mail principal.

A1_CGCstring · opcionalSA1.A1_CGC

CNPJ (14) ou CPF (11), apenas dígitos.

A1_INSCRstring · opcionalSA1.A1_INSCR

Inscrição Estadual; aceita "ISENTO".

A1_MSBLQLstring · opcionalSA1.A1_MSBLQL

Flag de bloqueio TOTVS-padrão. SX3 pertence("12"), default "2". "1"=Inativo (bloqueado), "2"=Ativo (liberado).

12

recnointeger · opcional

Id técnico do registro (RecNo do AdvPL).

msuidstring · opcional

Identificador universal MS_UID.

msuidtstring · opcional

Timestamp técnico associado ao msuid.

ClientePayload

object

Payload plano aceito em POST e PUT. Whitelist definida em CAMPOS_ALLOW no .prw. Em PUT sobre cliente bloqueado, o payload deve conter apenas A1_MSBLQL e/ou A1_MSBLQD — qualquer outro campo provoca 422.

A1_NOMEstring · opcionalSA1.A1_NOME

Razão social ou nome completo.

A1_NREDUZstring · opcionalSA1.A1_NREDUZ

Nome reduzido / fantasia.

A1_ENDstring · opcionalSA1.A1_END

Endereço.

A1_BAIRROstring · opcionalSA1.A1_BAIRRO

Bairro.

A1_MUNstring · opcionalSA1.A1_MUN

Município.

A1_ESTstring · opcionalSA1.A1_EST

UF (2 letras).

A1_COD_MUNstring · opcionalSA1.A1_COD_MUN

Código IBGE do município.

A1_CEPstring · opcionalSA1.A1_CEP

CEP (8 dígitos).

A1_PAISstring · opcionalSA1.A1_PAIS

Código de país (default "105" = Brasil).

A1_DDDstring · opcionalSA1.A1_DDD

DDD.

A1_TELstring · opcionalSA1.A1_TEL

Telefone.

A1_FAXstring · opcionalSA1.A1_FAX

Fax.

A1_EMAILstring (email) · opcionalSA1.A1_EMAIL

E-mail principal.

A1_PFISICAstring · opcionalSA1.A1_PFISICA

Pessoa Física / Jurídica.

FJ

A1_TIPOstring · opcionalSA1.A1_TIPO

F=Cons.Final, R=Revendedor, S=Solidário, L=Produtor Rural, X=Exportação.

FRSLX

A1_INSCRstring · opcionalSA1.A1_INSCR

Inscrição Estadual; aceita "ISENTO". CRMA980BRA pode rejeitar IE inválida combinada com UF.

A1_CONTATOstring · opcionalSA1.A1_CONTATO

Nome do contato principal.

A1_MSBLQLstring · opcionalSA1.A1_MSBLQL

Flag de bloqueio TOTVS-padrão (SX3 pertence("12"), default "2"): "1"=Inativo, "2"=Ativo. MsExecAuto do CRMA980 rejeita valores fora do domínio.

12

A1_MSBLQDstring · opcionalSA1.A1_MSBLQD

Bloqueio com vigência. Aceita string ISO YYYY-MM-DD ou vazia (limpa a data). Bloqueio fica ativo enquanto dDataBase > A1_MSBLQD.

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. data traz a chave técnica 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, contém a chave técnica gerada (A1_COD/A1_LOJA). Em PUT/DELETE pode ser string vazia ou objeto auxiliar.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode conter o token interno da causa (ex: mensagem do NomeAutoLog) para tratamento programático, 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).

Cenarios

Combinacoes documentadas (1 por example do openapi.yaml)

consulta-direta

GET /WsSA1/{cgc}

Consulta direta por CGC (CNPJ 14 ou CPF 11, apenas digitos). Retorna whitelist completo de CAMPOS_GET.

consulta-com-fields

GET /WsSA1/{cgc}?fields=...

Reduz payload de retorno via fields=; util em mobile / typeahead avancado.

payload-pj-minimo

POST /WsSA1/{cgc}

Pessoa Juridica minima: CNPJ 14d no path, A1_PFISICA="J", A1_TIPO="F" (Cons.Final), endereco basico e A1_INSCR="ISENTO". A1_COD/A1_LOJA sao gerados pelo Protheus (GetSXENum). Tier happy-path-minimal.

payload-pf

POST /WsSA1/{cgc}

Pessoa Fisica: CPF 11d no path, A1_PFISICA="F". Validacao de DV do CPF e feita pelo X3_VALID customizado da base (quirk: usa A1_TIPO em vez de A1_PFISICA — ver Pendencias). Tier happy-path-realistic.

alterar-endereco

PUT /WsSA1/{cgc}

Atualiza dados cadastrais comuns (endereco, email, telefone) em cliente liberado. Em cliente bloqueado retorna 422.

liberar-bloqueio

PUT /WsSA1/{cgc}

Caminho de desbloqueio: em cliente bloqueado, payload so com A1_MSBLQL="2" e/ou A1_MSBLQD="" e aceito. Helper U_C980Blq.

bloquear-com-data

PUT /WsSA1/{cgc}

Bloqueio manual com vigencia: A1_MSBLQL="1" + A1_MSBLQD ISO futura.

limpar-data

PUT /WsSA1/{cgc}

Passa A1_MSBLQD="" para zerar a vigencia. Combinavel com mudanca de A1_MSBLQL.

delete-direto

DELETE /WsSA1/{cgc}

Exclusao via CRMA980 op=5. MsExecAuto rejeita registros bloqueados ou com dependencias (titulos abertos, contatos).

byid-recno

GET /WsSA1/_byid?tipo=recno&valor=...

Lookup por recno da SA1 — caminho recomendado.

byid-msuid

GET /WsSA1/_byid?tipo=msuid&valor=...

Lookup por A1_MSUID (presente nesta base — validado 2026-05-08).

listagem-paginada

GET /WsSA1/_list?nome=...&page=...

Paginacao classica com filtros (cod, nome prefix normalizado, cgc prefix). Default 50, max 500.

delta-sync

GET /WsSA1/_list?orderBy=recno&since=...

Sincronizacao incremental por recno; cliente itera via nextCursor.

search-prefix

GET /WsSA1/_search?q=...&match=prefix

Typeahead por prefixo (default) — usa indice de A1_NOME. Limit max 25.

search-contains

GET /WsSA1/_search?q=...&match=contains

Match por substring — full-scan; mais caro mas util quando o usuario nao sabe o inicio do nome.

Pendências conhecidas (rev4)

SX3 quirk em A1_CGC nesta base. O X3_VALID customizado da empresa usa A1_TIPO em vez do esperado A1_PFISICA para decidir se valida CPF ou CNPJ. Resultado: CNPJ 14d com A1_TIPO="F" pode falhar CPFINVALID. Workaround: usar CPF 11d ou ajustar A1_TIPO conforme o tipo de documento. Memo: feedback_sa2_cgc_x3_customizado.

CPF 00874109159 proibido em fixtures. Instrucao 2026-05-11. Use CGCs sentinel (99999999000191) ou CPFs ja listados como aceitos.

PUT em cliente bloqueado: caminho restrito. Quando A1_MSBLQL="1" ou dDataBase > A1_MSBLQD, PUT so aceita payload tocando exclusivamente A1_MSBLQL/A1_MSBLQD — qualquer outro campo retorna 422 com motivo. Helper canonico: U_C980Blq("SA1").

Polaridade MSBLQL varia entre tabelas. Na SA1 confirmou-se "1"=Inativo / "2"=Ativo (default SX3). Outras tabelas TOTVS podem inverter — sempre consultar SX3 antes de replicar este padrao.

Localizacao Brasil condicional. CRMA980BRA e disparado quando o payload tem A1_INSCR + A1_EST; pode rejeitar IE incompativel com UF. Em ambiente sem localizacao BR, o fluxo silenciosamente nao roda.

AI0 (CRM) nao exposto. Complemento CRM nao e enviavel via REST nesta versao — o endpoint passa {} para FwLoadBy* de AI0. Adicionar quando houver demanda.