rev2-2026-04-29 Protheus 12.1.33

ChavePix

Gestão de chaves PIX (tabela F72) vinculadas a um fornecedor (SA2). Sub-cadastro identificado externamente pelo CGC do fornecedor + tipo da chave (F72_TPCHV: 01=CPF/CNPJ, 02=Email, 03=Telefone, 04=EVP). O endpoint persiste via FINA885 (wrapper U_F885MVC); F72_NOME e F72_COD são derivados do fornecedor e ficam read-only.

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

Vinculação com o ERP

Tabela F72 Chaves PIX (sub-cadastro de SA2)

Tabela pai SA2 Fornecedor (busca por A2_CGC, índice 3)

Rotina automática FINA885 MVC · MsExecAuto

Wrapper AdvPL U_F885MVC src/lib/FIN/F885MVC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Helpers REST U_RestErro + U_RestResolveFields, U_RestMontaRegistro (src/lib/_shared/RestUtils.prw)

Dependências de ambiente

Cadastro pai

Fornecedor (SA2)

o fornecedor deve existir antes de cadastrar a chave · busca por A2_CGC (índice 3); a chave técnica F72_COD/F72_NOME é preenchida pelo wrapper a partir de A2_COD/A2_NOME — não aceita override pela API

Unicidade

Tipo + Fornecedor

cada combinação F72_COD + F72_LOJA + F72_TPCHV é única · POST de tipo já existente colide; use PUT para alterar a chave do mesmo tipo

Smoke test

Sentinel 99999999000199

test-chave-pix.sh depende do fornecedor sentinel criado por test-cadastro-fornecedor.sh · rode os dois em sequência (ou via src/scripts/test-all.sh)

Convenções

Identificador do fornecedor. Todas as rotas /WSF72/{cgc} aceitam apenas dígitos — 14 (CNPJ) ou 11 (CPF). Pontuação (., /, -) é rejeitada com 400. O CGC é resolvido para A2_COD/A2_LOJA internamente; o consumidor nunca precisa enviar a chave técnica do fornecedor.

Tipo da chave (F72_TPCHV). Domínio fechado: 01=CPF/CNPJ, 02=Email, 03=Telefone, 04=EVP. O par (fornecedor, tipo) é único — para ter duas chaves do mesmo tipo no mesmo fornecedor, use tipos distintos. Para trocar o valor de uma chave já cadastrada, use PUT informando o mesmo F72_TPCHV no payload.

Campos derivados (read-only). F72_NOME e F72_COD são preenchidos pelo wrapper U_F885MVC a partir de A2_NOME/A2_COD do fornecedor. Aparecem no GET (para o consumidor evitar um GET adicional ao WsFornecedor), mas qualquer valor enviado no payload é ignorado — abriria divergência entre F72 e SA2.

Status ativa/inativa (F72_ACTIVE). Aceita "0" (inativa) ou "1" (ativa). O endpoint não implementa bloqueio TOTVS-padrão (*_MSBLQL/*_MSBLQD) porque a tabela F72 não expõe esses campos nesta base.

Seleção de campos (?fields=). O GET aceita lista CSV validada contra CAMPOS_GET = "F72_TPCHV|F72_CHVPIX|F72_ACTIVE|F72_NOME|F72_COD". Campos fora do whitelist retornam 400.

Chaves PIX

CRUD por CGC do fornecedor

GET /WSF72/{cgc} Lista chaves PIX do fornecedor

Descrição

Retorna o array de chaves PIX cadastradas para o fornecedor identificado pelo CGC. Resolve A2_CGC → A2_COD/A2_LOJA no SA2 (índice 3, xFilial("SA2")) e percorre F72 filtrando por F72_COD + F72_LOJA. O parâmetro opcional fields reduz o conjunto retornado.

Path parameter

cgc string · path · obrigatório SA2.A2_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.

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Request · com fieldsHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WSF72/99999999000199?fields=F72_TPCHV,F72_CHVPIX
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Array de chaves. Envelope { success: true, data: ChavePix[] } — array pode ser vazio quando o fornecedor não tem chaves cadastradas.

400

CGC fora do pattern, ou fields com campo fora do whitelist. Tier: validation-error.

404

Fornecedor não encontrado para o CGC informado. Tier: not-found.

500

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

POST /WSF72/{cgc} Inclui nova chave PIX

Descrição

Inclui uma nova chave PIX para o fornecedor via FINA885 em modo 3 (MODEL_OPERATION_INSERT). O wrapper U_F885MVC resolve o fornecedor pelo CGC e preenche F72_COD/F72_LOJA/F72_NOME automaticamente. Tentar inserir duas chaves com o mesmo F72_TPCHV no mesmo fornecedor colide com a unicidade da tabela.

Whitelist de campos: ver ChavePixPayload.
Campos derivados (F72_COD, F72_NOME) não podem ser enviados — são ignorados pelo wrapper.

Path parameter

cgc string · path · obrigatório SA2.A2_CGC

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

Request body

application/json ChavePixPayload · obrigatório

Payload plano com whitelist CAMPOS_ALLOW = "F72_TPCHV|F72_CHVPIX|F72_ACTIVE". Schema completo em ChavePixPayload.

Chave por e-mail (tipo 02) — payload mínimo do smoke test. Origem: test-chave-pix.sh passo 2.

RequestHTTP/1.1 · application/json

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

{
  "F72_TPCHV": "02",
  "F72_CHVPIX": "teste-pix@exemplo.com",
  "F72_ACTIVE": "1"
}

Chave por telefone (tipo 03) — DDI + DDD + número, apenas dígitos.

RequestHTTP/1.1 · application/json

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

{
  "F72_TPCHV": "03",
  "F72_CHVPIX": "+5511999990000",
  "F72_ACTIVE": "1"
}

EVP cadastrada inativa — chave aleatória (tipo 04) com F72_ACTIVE="0", útil para deixar pré-cadastrada e ativar depois via PUT.

RequestHTTP/1.1 · application/json

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

{
  "F72_TPCHV": "04",
  "F72_CHVPIX": "4f9b8b6e-1c2a-4a8e-9f3d-1234567890ab",
  "F72_ACTIVE": "0"
}

Respostas

201

Chave incluída. Envelope CrudResponse.

400

CGC fora do pattern ou JSON inválido. Tier: validation-error.

404

Fornecedor não encontrado para o CGC informado. Tier: not-found.

422

Payload inválido — F72_TPCHV fora do domínio {01,02,03,04}, chave duplicada para o tipo, ou MsExecAuto do FINA885 rejeitou o registro. Tier: business-error.

500

Erro interno.

PUT /WSF72/{cgc} Altera chave PIX existente

Descrição

Altera a chave PIX identificada por F72_TPCHV no payload. Persiste via FINA885 em modo 4 (MODEL_OPERATION_UPDATE). O F72_TPCHV é identificador dentro do fornecedor — para alterar o tipo de uma chave existente, faça DELETE do tipo antigo seguido de POST do novo.

Path parameter

cgc string · path · obrigatório SA2.A2_CGC

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

Request body

application/json ChavePixPayload · obrigatório

F72_TPCHV é obrigatório (identifica a linha alvo); os demais campos do whitelist são opcionais.

Trocar o valor da chave — mantém o tipo (02=Email) e atualiza F72_CHVPIX. Origem: test-chave-pix.sh passo 4.

RequestHTTP/1.1 · application/json

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

{
  "F72_TPCHV": "02",
  "F72_CHVPIX": "teste-pix-alt@exemplo.com",
  "F72_ACTIVE": "1"
}

Desativar chave — preserva o valor e marca F72_ACTIVE="0". Útil para suspender uso sem perder o histórico.

RequestHTTP/1.1 · application/json

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

{
  "F72_TPCHV": "02",
  "F72_ACTIVE": "0"
}

Respostas

200

Chave alterada. Envelope CrudResponse.

400

CGC fora do pattern ou JSON inválido. Tier: validation-error.

404

Fornecedor não encontrado, ou chave PIX do tipo informado inexistente para o fornecedor. Tier: not-found.

422

Payload inválido — MsExecAuto do FINA885 rejeitou. Tier: business-error.

500

Erro interno.

DEL /WSF72/{cgc}/{tpchv} Remove chave PIX

Descrição

Remove a chave PIX do fornecedor identificada pelo tipo (tpchv) via FINA885 em modo 5 (MODEL_OPERATION_DELETE). Exclusão definitiva — para "desligar" sem perder o histórico, use PUT com F72_ACTIVE="0".

Path parameters

cgc string · path · obrigatório SA2.A2_CGC

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

tpchv string · path · obrigatório F72.F72_TPCHV

Tipo da chave a remover.

01020304

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Chave removida. Envelope CrudResponse.

400

CGC fora do pattern ou tpchv fora do domínio {01,02,03,04}. Tier: validation-error.

404

Fornecedor ou chave do tipo informado não encontrada. Tier: not-found.

500

Erro interno.

Schemas

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

ChavePix

object

Representação de uma chave PIX retornada pelo GET /WSF72/{cgc}. Campos efetivamente retornados dependem de CAMPOS_GET = "F72_TPCHV|F72_CHVPIX|F72_ACTIVE|F72_NOME|F72_COD" e do filtro fields.

F72_TPCHVstring · obrigatórioF72.F72_TPCHV

Tipo da chave PIX.

01020304

F72_CHVPIXstring · obrigatórioF72.F72_CHVPIX

Valor da chave (formato depende de F72_TPCHV): CPF/CNPJ apenas dígitos, e-mail RFC 5322, telefone com DDI, ou UUID v4 para EVP.

F72_ACTIVEstring · opcionalF72.F72_ACTIVE

Status da chave: "1"=ativa, "0"=inativa.

01

F72_NOMEstring · read-onlyF72.F72_NOME

Razão social / nome do fornecedor (derivado de A2_NOME pelo wrapper). Não aceita override pelo payload.

F72_CODstring · read-onlyF72.F72_COD

Código técnico do fornecedor (derivado de A2_COD). Não aceita override pelo payload.

ChavePixPayload

object

Payload aceito em POST e PUT. Whitelist em CAMPOS_ALLOW = "F72_TPCHV|F72_CHVPIX|F72_ACTIVE". Campos fora do whitelist (incluindo F72_COD e F72_NOME) são silenciosamente ignorados pelo wrapper.

F72_TPCHVstring · obrigatórioF72.F72_TPCHV

Tipo da chave PIX. Em PUT, identifica a linha a alterar dentro do fornecedor.

01020304

F72_CHVPIXstring · obrigatório em POSTF72.F72_CHVPIX

Valor da chave; o formato deve casar com F72_TPCHV.

F72_ACTIVEstring · opcionalF72.F72_ACTIVE

Status. Default "1" (ativa) quando omitido em POST.

01

CrudResponse

object · envelope

Envelope padrão das respostas de POST, PUT e DELETE. F72 não gera sequência SX8 — o identificador externo (CGC + TPCHV) já basta para localizar o registro criado.

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso.

datastring · opcional

String vazia ou objeto auxiliar. Não traz chave técnica gerada (F72 não usa GetSXENum).

Erro

object · envelope

Envelope padrão de erros 4xx/5xx, produzido por U_RestErro. data pode conter detalhe técnico (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).