Whitelabel — Progem API

Quando usar / quando não usar

Use para o site/app do associado (tenant whitelabel): catálogo público, adesão, área do titular, carnê CelCash.
Não use para mobile operacional de cobrador/vendedor (JWT authFlow=mobile) — ver Cobrador / Vendedor.
Não use /api/v1/app/admin/** aqui — admin de usuários fica em Plataforma.
ViaCEP e Nalapide/Memorial são terceiros do front — fora deste contrato de API Progem.
Auth (login/refresh/senha) → Whitelabel · Acesso.

Pré-requisito: Central (Progem web)

A API não substitui o cadastro no Central

O whitelabel lê branding, planos, unidades, parceiros e vendedor padrão já cadastrados no Central / ApiClient do tenant. Sem setup, listagens vazias ou 204/404 quebram a jornada.

ApiClient + X-Progem-ID (empresa/tenant) corretos no BFF.
Planos ativos, unidades, locais/parceiros, cupons e vendedor(es) com e-mail.
Integração CelCash habilitada no tenant quando o fluxo de carnê for usado.

Auth e headers (ponteiro)

Token do associado: Acesso WL (/api/v1/app/auth/* + X-Progem-ID). Esta página de domínio assume Bearer já emitido.

Público / catálogo / adesão: BFF injeta client-token + X-Progem-ID (sem Bearer do associado).
Área logada / perfil: Bearer + X-Progem-ID — ver também Acesso WL · Usuário logado.
Não use JWT mobile operacional — esse fluxo é Acesso Mobile (cobrador/vendedor/CRM/agenda).

Mapa de endpoints (fonte: app real)

Domínio	Método / path	Auth
Branding	`GET /api/v1/public/branding`	Tenant / público
Unidades	`GET /api/v1/unidades/me`, `GET /api/v1/unidades/all`	Tenant
Planos	`GET /api/v1/planos`, `GET /api/v1/planos/{id}`	Tenant
Produtos	`GET /api/v1/produtos`, `GET /api/v1/produtos/{id}`	Tenant
Parceiros	`GET /api/v1/locais/parceiros`, `…/{id}`	Tenant
Cupom	`GET /api/v1/cupons/{codigo}`	Tenant
Adesão	`GET /pessoas/cpf/{cpf}`, `POST /pessoas`, `GET /dependentes/pessoa/{id}`, `POST /dependentes`, `POST /contratos`, `GET /vendedores/email/{email}`	Tenant
BFF alias	`GET /api/v1/vendedores/padrao` → resolve para `vendedores/email/{email}` (só BFF)	Tenant
Área associado	`GET /contratos/cpf/{cpf}`, `…/{id}/dependentes`, `…/pagamentos`, `…/pagamentos/mes`, `…/debitos`	Tenant (+ Bearer na área)
CelCash	`POST /api/v1/celcash/contratos/{id}/carne/manual` (+ proxy BFF `/api/celcash/clientes/contratos/{id}`)	Tenant
Perfil	`GET`/`PUT /api/v1/app/me`, avatar, `POST /app/me/devices`	Bearer + tenant

Jornada alinhada ao app

1. Boot do tenant GET /public/branding + GET /unidades/me (CSS vars, logo, unidade).

2. Catálogo Planos (?status=ATIVO), detalhe do plano, produtos, locais/parceiros, cupom.

3. Adesão Lookup CPF → criar pessoa/dependentes → vendedor → POST /contratos → CelCash cliente/carnê.

4. Área do usuário Login (Acesso) → contrato por CPF → pagamentos/débitos/dependentes → perfil/avatar/devices.

Branding e unidades

GET /api/v1/public/branding

Boot do tema (cores, logo, ETag). O app envia If-None-Match quando há cache local.

GET {{url_base}}/api/v1/public/branding
X-Progem-ID: {{tenant_id}}

GET /api/v1/unidades/me

Unidade “principal” do tenant no whitelabel (estado + CSS). contato.whatsapp / contato.telefone são o atendimento da empresa.

Módulos do tenant (configurados no AWIS Console, sempre presentes): habilitaMemorial, habilitaBeneficios, habilitaPlanos (vitrine de planos + adesão online) e habilitaProdutos. false oculta a tela no whitelabel; os endpoints de catálogo continuam respondendo (a área do associado usa /planos/{id}).

GET {{url_base}}/api/v1/unidades/me
X-Progem-ID: {{tenant_id}}

GET /api/v1/unidades/all

Lista de filiais (página Filiais). O BFF também pode expor /api/progem/unidades como alias.

GET {{url_base}}/api/v1/unidades/all
X-Progem-ID: {{tenant_id}}

Catálogo

GET /api/v1/planos

Grade pública. App tipicamente filtra status=ATIVO.

GET {{url_base}}/api/v1/planos?status=ATIVO
X-Progem-ID: {{tenant_id}}

GET /api/v1/planos/{id}

Detalhe do plano (adesão, área do usuário, serviços digitais).

GET {{url_base}}/api/v1/planos/42
X-Progem-ID: {{tenant_id}}

GET /api/v1/produtos · GET /api/v1/produtos/{id}

GET {{url_base}}/api/v1/produtos
GET {{url_base}}/api/v1/produtos/15
X-Progem-ID: {{tenant_id}}

GET /api/v1/locais/parceiros · …/{id}

Clube de benefícios. Query comum: size (preview ou listagem).

GET {{url_base}}/api/v1/locais/parceiros?size=12
GET {{url_base}}/api/v1/locais/parceiros/88
X-Progem-ID: {{tenant_id}}

GET /api/v1/cupons/{codigo}

Validação de cupom na etapa de carnê/adesão.

GET {{url_base}}/api/v1/cupons/PROMO10
X-Progem-ID: {{tenant_id}}

Adesão (pessoa → dependente → contrato)

Fluxo do wizard Cadastro.jsx. Paths oficiais abaixo; tentativas legadas do cliente estão em Erros e fallbacks.

GET /api/v1/pessoas/cpf/{cpf}

GET {{url_base}}/api/v1/pessoas/cpf/123.456.789-01
X-Progem-ID: {{tenant_id}}

POST /api/v1/pessoas

POST {{url_base}}/api/v1/pessoas
X-Progem-ID: {{tenant_id}}
Content-Type: application/json

{
  "nome": "Maria Silva",
  "cpf": "123.456.789-01",
  "rg": null,
  "dataNascimento": "1990-05-12",
  "sexo": "MULHER",
  "estadoCivil": null,
  "contatos": { "email": "maria@exemplo.com", "celular": "11999998888", "telefone": null },
  "endereco": {
    "cep": "01310100",
    "cidade": "São Paulo",
    "uf": "SP",
    "bairro": "Bela Vista",
    "logradouro": "Av. Paulista",
    "numero": "1000",
    "complemento": null
  }
}

GET /api/v1/dependentes/pessoa/{pessoaId}

GET {{url_base}}/api/v1/dependentes/pessoa/55
X-Progem-ID: {{tenant_id}}

POST /api/v1/dependentes

POST {{url_base}}/api/v1/dependentes
X-Progem-ID: {{tenant_id}}
Content-Type: application/json

{
  "cpf": "98765432100",
  "nome": "João Silva",
  "parentesco": "FILHO",
  "sexo": "HOMEM",
  "dataNascimento": "2015-01-20",
  "titularId": 55
}

GET /api/v1/vendedores/email/{email}

Contrato oficial na API. O BFF ainda expõe GET /api/v1/vendedores/padrao como alias que resolve para este path (não existe controller dedicado na API).

GET {{url_base}}/api/v1/vendedores/email/vendedor%40empresa.com
X-Progem-ID: {{tenant_id}}

POST /api/v1/contratos

POST {{url_base}}/api/v1/contratos
X-Progem-ID: {{tenant_id}}
Content-Type: application/json

{
  "titularId": 55,
  "planoId": 42,
  "vendedorId": 717,
  "dataContrato": "2026-09-19",
  "diaD": 10,
  "valorAdesao": 0,
  "valorMensalidade": 79.90,
  "dataEfetivacao": "2026-10-01",
  "cupomDesconto": null
}

Contrato do associado (área logada)

GET /api/v1/contratos/cpf/{cpf}

Entrada da área do usuário, carteirinha e pós-login. unidade.whatsapp / unidade.telefone são o atendimento da unidade dona do contrato; contatos são do titular (nunca usar como canal da empresa).

GET {{url_base}}/api/v1/contratos/cpf/12345678901
X-Progem-ID: {{tenant_id}}
Authorization: Bearer {{access_token}}

GET /api/v1/contratos/{id}/dependentes

GET {{url_base}}/api/v1/contratos/900/dependentes
X-Progem-ID: {{tenant_id}}
Authorization: Bearer {{access_token}}

Com token de usuário do app, se o CPF logado for de um dependente com parentesco COLABORADOR, a resposta traz somente o próprio cadastro (não lista os demais beneficiários).

Pagamentos e CelCash

GET /api/v1/contratos/{id}/pagamentos

GET {{url_base}}/api/v1/contratos/900/pagamentos
X-Progem-ID: {{tenant_id}}
Authorization: Bearer {{access_token}}

GET /api/v1/contratos/{id}/pagamentos/mes

GET {{url_base}}/api/v1/contratos/900/pagamentos/mes
X-Progem-ID: {{tenant_id}}
Authorization: Bearer {{access_token}}

GET /api/v1/contratos/{id}/debitos

GET {{url_base}}/api/v1/contratos/900/debitos
X-Progem-ID: {{tenant_id}}
Authorization: Bearer {{access_token}}

POST /api/v1/celcash/contratos/{id}/carne/manual

Emissão de carnê. O BFF também faz proxy de POST /api/celcash/clientes/contratos/{contratoId} (criar cliente/contrato CelCash).

POST {{url_base}}/api/v1/celcash/contratos/900/carne/manual
X-Progem-ID: {{tenant_id}}
Content-Type: application/json

{
  "cobrancas": [
    { "numeroParcela": 1, "valor": 79.90, "dataVencimento": "2026-10-10" },
    { "numeroParcela": 2, "valor": 79.90, "dataVencimento": "2026-11-10" }
  ]
}

Perfil já autenticado

Exige Bearer do associado (ver Acesso) + X-Progem-ID.

GET /api/v1/app/me

GET {{url_base}}/api/v1/app/me
Authorization: Bearer {{access_token}}
X-Progem-ID: {{tenant_id}}

{
  "id": 1001,
  "nome": "Maria Silva",
  "email": "maria@exemplo.com",
  "cpf": "12345678901",
  "celular": "11999998888",
  "dataNascimento": "1990-05-12",
  "emailVerificado": true,
  "celularVerificado": false,
  "progemLink": { }
}

PUT /api/v1/app/me

Contrato oficial: PUT (204 sem corpo). O cliente tem helper que tenta PATCH — não conte PATCH /app/me como contrato da API.

PUT {{url_base}}/api/v1/app/me
Authorization: Bearer {{access_token}}
X-Progem-ID: {{tenant_id}}
Content-Type: application/json

{ "nome": "Maria S. Silva", "celular": "11988887777" }

Avatar — GET / PUT / DELETE /api/v1/app/me/avatar

PUT {{url_base}}/api/v1/app/me/avatar
Authorization: Bearer {{access_token}}
X-Progem-ID: {{tenant_id}}
Content-Type: multipart/form-data
file: <imagem>

GET  {{url_base}}/api/v1/app/me/avatar   → blob imagem
DELETE {{url_base}}/api/v1/app/me/avatar

POST /api/v1/app/me/devices

Registro FCM (push). Resposta típica 204.

POST {{url_base}}/api/v1/app/me/devices
Authorization: Bearer {{access_token}}
X-Progem-ID: {{tenant_id}}
Content-Type: application/json

{
  "usuarioAppId": 1001,
  "fcmToken": "…",
  "plataforma": "WEB",
  "appTipo": "WHITELABEL"
}

Erros e fallbacks do cliente

Tentativas legadas — não são contrato oficial

O front ainda tenta estes paths em fallbacks de lookup. Não documente nem implemente integrações novas contra eles — use os paths oficiais desta página.

GET /api/v1/pessoas/by-cpf/{cpf}
GET /api/v1/pessoas?cpf=…
GET /api/v1/contratos/consulta/cpf/{cpf}
GET /api/v1/app/contratos/me
PATCH /api/v1/app/me (oficial é PUT)

Respostas típicas: 400 tenant/body · 401/403 auth · 404 recurso · 204 em alguns updates sem corpo.

Checklist de integração

Tenant (X-Progem-ID) e branding/unidades carregam no boot.
Planos ativos e vendedor resolvido antes de POST /contratos.
Área logada usa Bearer de Acesso, não JWT mobile.
Não depender de fallbacks by-cpf / app/contratos/me.
Admin /app/admin fora deste guia → Plataforma.
CelCash: carnê manual + (via BFF) clientes/contratos quando o tenant tiver integração.

Whitelabel (domínio)