Documentação da API Oficial

Abrir documentação interativa (Swagger) 📥 Baixar coleção do Postman

Autenticação – Fluxo OAuth2

Use este fluxo para integrações server-to-server. O cliente envia suas credenciais via Basic Auth e recebe um access_token para acessar os endpoints protegidos.

Sandbox

POST https://sandbox-api.progem.com.br/oauth2/token

Produção

POST https://api.progem.com.br/oauth2/token

Passo a passo

  1. Crie/obtenha seu clientId e clientSecret (cadastro do cliente).
  2. Monte o header Authorization: Basic com base64(clientId:clientSecret).
    Ex.: echo -n "saobento:secret1234567890" | base64 → c2FvYmVudG86c2VjcmV0MTIzNDU2Nzg5MA==
  3. Envie a requisição para /oauth2/token com:
    • Header X-Progem-ID = ID da empresa (tenant)
    • Body x-www-form-urlencoded com grant_type=client_credentials e os escopos desejados
  4. Use o token retornado em Authorization: Bearer <access_token> + mantenha o X-Progem-ID nas chamadas. 
POST /oauth2/token
Headers:
Authorization: Basic <base64(clientId:clientSecret)>
Content-Type: application/x-www-form-urlencoded
X-Progem-ID: <empresaId (tenant)>
Body:
{
  "grant_type": "client_credentials",
  "scope": "read:unidades read:planos read:parceiros write:pessoas read:pessoas read:contratos write:contratos write:dependentes read:dependentes read:duplicatas read:planos read:parceiros"
}

Notas: separe escopos por espaço (no cURL, espaços viram %20). O token refletirá apenas escopos permitidos para o cliente. 

curl -X POST "https://sandbox-api.progem.com.br/oauth2/token" \
  -H "Authorization: Basic <base64(clientId:clientSecret)>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Progem-ID: 128" \
  --data "grant_type=client_credentials&scope=read:unidades%20read:planos%20read:parceiros%20write:pessoas%20read:pessoas%20read:contratos%20write:contratos%20write:dependentes%20read:dependentes%20read:duplicatas"

Dica: base64 de saobento:secret1234567890 → c2FvYmVudG86c2VjcmV0MTIzNDU2Nzg5MA== 

HTTP/1.1 200 OK
{
  "access_token": "eyJhbGciOiJIUzI1NiJ9....PSPYDDtgE3s6B7C8L0e5zp6TsHY93CKdUrQHJlkOfxw",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "write:pessoas read:pessoas read:contratos write:contratos write:dependentes read:dependentes read:duplicatas read:planos read:parceiros",
  "empresaId": 128
}

Uso: inclua Authorization: Bearer <access_token> e X-Progem-ID nas próximas requisições.

Escopo Descrição Endpoints (exemplos)
read:unidades Ler dados da empresa e unidades GET /api/v1/unidades/me, GET /api/v1/unidades/all
read:planos Listar/consultar planos GET /api/v1/planos, GET /api/v1/planos/{id}
read:parceiros Listar locais parceiros GET /api/v1/locais
read:pessoas / write:pessoas Consultar/criar titulares GET /api/v1/pessoas/**, POST /api/v1/pessoas
read:dependentes / write:dependentes Consultar/criar dependentes GET /api/v1/dependentes/**, POST /api/v1/dependentes
read:contratos / write:contratos Consultar/criar contratos GET /api/v1/contratos/**, POST /api/v1/contratos
read:duplicatas Consultar parcelas/pagamentos GET /api/v1/contratos/{id}/pagamentos, /debitos, /pagamentos/mes

Observação: a autorização é verificada por endpoint; peça somente os escopos necessários.

Códigos de Resposta:
200 OK                  – Token gerado com sucesso
400 Bad Request         – Parâmetros inválidos (ex.: grant_type ausente ou Content-Type incorreto)
401 Unauthorized        – clientId/clientSecret inválidos (Authorization: Basic)
403 Forbidden           – Escopo solicitado não autorizado para o cliente
429 Too Many Requests   – Limite de requisições atingido
500 Internal Server Error – Erro no servidor

Erros comuns & soluções

  • 401: revise o Authorization: Basic (par clientId:clientSecret e base64).
  • 400: confira grant_type=client_credentials e Content-Type: application/x-www-form-urlencoded.
  • 400: ausente X-Progem-ID (tenant) nos headers.
  • 403: escopo não habilitado para o cliente; ajuste os escopos solicitados.

Buscar Contratos por CPF

Endpoint que retorna informações dos contratos vinculados ao CPF informado.

GET /api/v1/contratos/cpf/316.220.873-48
Headers:
Authorization: Bearer <seuAccessToken>
Resposta:
[
    {
        "id": 114598,
        "numeroContrato": 9008,
        "nome": "Carolina Stefany Malu Ferreira",
        "nomeTitular": "Carolina Stefany Malu Ferreira",
        "rg": "691225555",
        "estadoCivil": "SOLTEIRO",
        "dataNascimento": "1983-10-11",
        "titularId": 103492,
        "titular": true,
        "contratoAtivo": true,
        "atrasado": false,
        "parcelasEmAtraso": 0,
        "planoId": 658,
        "nomePlano": "PLANO SUPER LUXO C/ CREMAÇÃO",
        "dataEfetivacao": "2022-06-09",
        "diaD": 5,
        "contatos": {
            "celular": "(84) 98496-9300",
            "telefone": null,
            "email": "carolina_ferreira@marcofaria.com"
        },
        "endereco": {
            "cep": "59630-400",
            "cidade": "Mossoró",
            "uf": "RN",
            "bairro": "Rincão",
            "logradouro": "Rua Edson Edilson de Melo",
            "numero": "799",
            "complemento": ""
        },
        "unidade": {
            "id": 128,
            "nomeFantasia": "FUNERÁRIA SÃO BENTO",
            "cnpj": "31.286.698/0001-87",
            "cidade": "Curitiba",
            "uf": "PR",
            "bairro": "Centro",
            "nomeLogo": "https://app.pro....e22-4f01-9f7e-f9443ddab567_arquivo.png"
        }
    }
]
Códigos de Resposta Esperados:
200 OK - Requisição bem-sucedida
400 Bad Request - CPF inválido ou parâmetros faltando
401 Unauthorized - Falha na autenticação (API Key ou Tenant inválido)
403 Forbidden - Permissão negada
500 Internal Server Error - Erro no servidor

Dependentes do Contrato

Retorna os dependentes vinculados ao contrato com dados como nome, CPF, parentesco e carência.

GET /api/v1/contratos/{id}/dependentes
Headers:
Authorization: Bearer <seuAccessToken>
Resposta:
[
  {
    "id": 1645501,
    "nome": "Bruna Silvana Pires",
    "cpf": null,
    "celular": "(71) 99799-8694",
    "dataNascimento": "1973-02-25",
    "parentesco": "IRMAO",
    "dataCadastro": "2025-07-04",
    "titularId": 286911,
    "unidadeCarencia": "DIAS",
    "periodoCarencia": 90,
    "inicioCarencia": "2025-07-04"
  },
  {
    "id": 1645503,
    "nome": "Mariana Hadassa Araújo",
    "cpf": null,
    "celular": "(84) 99175-6201",
    "dataNascimento": "1971-05-24",
    "parentesco": "CONJUGE",
    "dataCadastro": "2025-07-04",
    "titularId": 286911,
    "unidadeCarencia": "DIAS",
    "periodoCarencia": 90,
    "inicioCarencia": "2025-07-04"
  },
  {
    "id": 1645502,
    "nome": "Stefany Luana Daniela Novaes",
    "cpf": null,
    "celular": "(63) 99909-0826",
    "dataNascimento": "2000-01-06",
    "parentesco": "FILHO",
    "dataCadastro": "2025-07-04",
    "titularId": 286911,
    "unidadeCarencia": "DIAS",
    "periodoCarencia": 90,
    "inicioCarencia": "2025-07-04"
  },
  {
    "id": 1645500,
    "nome": "Yuri Juan Aragão",
    "cpf": "261.485.584-75",
    "celular": "(46) 99112-0012",
    "dataNascimento": "1980-01-01",
    "parentesco": "TITULAR",
    "dataCadastro": "2025-07-04",
    "titularId": 286911,
    "unidadeCarencia": "DIAS",
    "periodoCarencia": 90,
    "inicioCarencia": "2025-07-04"
  }
]
Códigos de Resposta Esperados:
200 OK - Requisição bem-sucedida
400 Bad Request - ID inválido ou parâmetro ausente
401 Unauthorized - Falha na autenticação (API Key ou Tenant inválido)
403 Forbidden - Permissão negada
404 Not Found - Contrato não encontrado
500 Internal Server Error - Erro no servidor

Cadastrar Contrato

Cria um novo contrato para o titular informado com base no plano selecionado.

POST /api/v1/contratos
Headers:
Content-Type: application/json
Authorization: Bearer <seuAccessToken>
Body:
{
  "titularId": 293669,
  "planoId": 1695,
  "vendedorId": 2719,
  "dataContrato": "2025-07-29",
  "diaD": 11,
  "dataEfetivacao": "2025-11-01",
  "valorAdesao": 100.90,
  "valorMensalidade": 79.90,
  "cupomDesconto": "BEMVINDO10"
}
HTTP/1.1 201 Created
{
  "id": 306883,
  "numeroContrato": 15157,
  "status": "ORCAMENTO",
  "pessoaId": 286911,
  "planoId": 1014,
  "vendedorId": 717,
  "dataContrato": "2025-07-10",
  "dataEfetivacao": "2025-11-01",
  "valorAdesao": 100.90,
  "valorMensalidade": 79.90,
  "cupomDesconto": "BEMVINDO10",
  "diaD": 11
}
Códigos de Resposta Esperados:
201 Created  – Contrato criado com sucesso  
400 Bad Request  – Dados inválidos  
401 Unauthorized  – API Key ou Tenant inválido  
403 Forbidden  – Permissão negada  
500 Internal Server Error  – Erro interno no servidor

Pagamentos

Retorna os pagamentos do contrato com informações de vencimento, valor, status, boleto e pix.

GET /api/v1/contratos/{id}/pagamentos
Headers:
Authorization: Bearer <seuAccessToken>
Resposta:
[
    {
        "id": 8941395,
        "numeroDuplicata": "01",
        "status": "PAGA",
        "valorParcela": 30.00,
        "valorRecebido": 30.00,
        "dataVencimento": "2025-07-04",
        "dataRecebimento": "2025-07-04",
        "linkPagamento": null,
        "urlBoleto": "https://data.sandbox.cel.cash/sandboxawis/boleto/20250793HEDT5Y95D4AC58YZZ6R2RQR04174820",
        "pixQrcode": "00020101021226880014BR.GOV.BCB.PIX2566api-h.rendimento.com.br/q/v2/cobv/190a0bf11bb444148476d682388316dc5204000053039865802BR5913AWIS SOFTWARE6011Pato Branco61088550459262070503***63041600",
        "pixImage": "https://data.sandbox.cel.cash/sandboxawis/pix/R6WJK6JWN3SXNTHZ5JJY0000016735"
    },
    {
        "id": 8941396,
        "numeroDuplicata": "02",
        "status": "ABERTA",
        "valorParcela": 30.00,
        "valorRecebido": 0.00,
        "dataVencimento": "2025-08-04",
        "dataRecebimento": null,
        "linkPagamento": "https://panel.sandbox.cel.cash/c/5609/aa4d6604/b",
        "urlBoleto": "https://data.sandbox.cel.cash/sandboxawis/boleto/202507Q552FEZD9MGWM3TWUEPAY3QAP04175031",
        "pixQrcode": "00020101021226880014BR.GOV.BCB.PIX2566api-h.rendimento.com.br/q/v2/cobv/1249fd1bfbf14249bdea899fe1d491dd5204000053039865802BR5913AWIS SOFTWARE6011Pato Branco61088550459262070503***6304B09E",
        "pixImage": "https://data.sandbox.cel.cash/sandboxawis/pix/QP97632RJZD46QS7QSHP0000016736"
    },
    {
        "id": 8941397,
        "numeroDuplicata": "03",
        "status": "ABERTA",
        "valorParcela": 30.00,
        "valorRecebido": 0.00,
        "dataVencimento": "2025-09-04",
        "dataRecebimento": null,
        "linkPagamento": "https://panel.sandbox.cel.cash/c/5609/aa4d6604/b",
        "urlBoleto": "https://data.sandbox.cel.cash/sandboxawis/boleto/202507HT9GDKZCUCHHHJ4P1BN88648604175034",
        "pixQrcode": "00020101021226880014BR.GOV.BCB.PIX2566api-h.rendimento.com.br/q/v2/cobv/ac959eb781e9437085691839d4e4328c5204000053039865802BR5913AWIS SOFTWARE6011Pato Branco61088550459262070503***630452B5",
        "pixImage": "https://data.sandbox.cel.cash/sandboxawis/pix/ZA9UCYACAYSSR6D8MHG10000016737"
    },
    {
        "id": 8941398,
        "numeroDuplicata": "04",
        "status": "ABERTA",
        "valorParcela": 30.00,
        "valorRecebido": 0.00,
        "dataVencimento": "2025-10-04",
        "dataRecebimento": null,
        "linkPagamento": "https://panel.sandbox.cel.cash/c/5609/aa4d6604/b",
        "urlBoleto": "https://data.sandbox.cel.cash/sandboxawis/boleto/2025072616AVGK51YRYAH8AKFXN5SGW04175036",
        "pixQrcode": "00020101021226880014BR.GOV.BCB.PIX2566api-h.rendimento.com.br/q/v2/cobv/b1a74b672c0b4b5b8eae1c6aa86f02f65204000053039865802BR5913AWIS SOFTWARE6011Pato Branco61088550459262070503***6304E089",
        "pixImage": "https://data.sandbox.cel.cash/sandboxawis/pix/JJCXS15MFK23DRSEBG120000016738"
    },
    {
        "id": 8941399,
        "numeroDuplicata": "05",
        "status": "ABERTA",
        "valorParcela": 30.00,
        "valorRecebido": 0.00,
        "dataVencimento": "2025-11-04",
        "dataRecebimento": null,
        "linkPagamento": "https://panel.sandbox.cel.cash/c/5609/aa4d6604/b",
        "urlBoleto": "https://data.sandbox.cel.cash/sandboxawis/boleto/202507AF9WG41Z4G9AFSK5UGDC9ERH404175038",
        "pixQrcode": "00020101021226880014BR.GOV.BCB.PIX2566api-h.rendimento.com.br/q/v2/cobv/12d5bdc66c434d42908ab7a675aad5465204000053039865802BR5913AWIS SOFTWARE6011Pato Branco61088550459262070503***6304573F",
        "pixImage": "https://data.sandbox.cel.cash/sandboxawis/pix/Y85E9XV38UZU6PRV4XER0000016739"
    },
    {
        "id": 8941400,
        "numeroDuplicata": "06",
        "status": "ABERTA",
        "valorParcela": 30.00,
        "valorRecebido": 0.00,
        "dataVencimento": "2025-12-04",
        "dataRecebimento": null,
        "linkPagamento": "https://panel.sandbox.cel.cash/c/5609/aa4d6604/b",
        "urlBoleto": "https://data.sandbox.cel.cash/sandboxawis/boleto/202507U29K6T9JRCNTYQQ92F1CRBHRJ04175040",
        "pixQrcode": "00020101021226880014BR.GOV.BCB.PIX2566api-h.rendimento.com.br/q/v2/cobv/a915ee70b53c45ad868b7de7f371e0865204000053039865802BR5913AWIS SOFTWARE6011Pato Branco61088550459262070503***63043A25",
        "pixImage": "https://data.sandbox.cel.cash/sandboxawis/pix/6GZMGPHPTDNRARDXQ3XU0000016740"
    }
]
Códigos de Resposta Esperados:
200 OK - Requisição bem-sucedida
400 Bad Request - Contrato inválido ou ausente
401 Unauthorized - Falha na autenticação (API Key ou Tenant inválido)
403 Forbidden - Permissão negada
404 Not Found - Contrato não encontrado
500 Internal Server Error - Erro interno no servidor

Listar Débitos do Contrato

Retorna todas as parcelas em aberto de um contrato.

GET /api/v1/contratos/{id}/debitos
Headers:
Authorization: Bearer <seuAccessToken>

HTTP/1.1 200 OK
[
    {
        "id": 9022684,
        "numero": "01",
        "status": "ABERTA",
        "valorParcela": 25.00,
        "valorRecebido": 0.00,
        "dataVencimento": "2025-07-09",
        "dataRecebimento": null,
        "linkPagamento": null,
        "urlBoleto": "https://data.sandbox.cel.cash/sandboxawis/boleto/202507EB5HYAYDWSQVFGC52JG6MURWM09171452",
        "pixQrcode": "00020101021226880014BR.GOV.BCB.PIX2566api-h.rendimento.com.br/q/v2/cobv/6dee21d63efd4615aed83f6c34b928d15204000053039865802BR5913AWIS SOFTWARE6011Pato Branco61088550459262070503***6304A40C",
        "pixImage": "https://data.sandbox.cel.cash/sandboxawis/pix/6B6G8FNR8R53B1Y3YCSB0000016765"
    }
]
Códigos de Resposta:
200 OK    – Débitos retornados com sucesso  
401 Unauthorized – Token JWT inválido ou ausente  
403 Forbidden    – Escopo insuficiente  
500 Internal Server Error – Erro interno no servidor

Pagamento do Mês do Atual

Retorna todas as parcelas pagas no mês corrente de um contrato.

GET /api/v1/contratos/{id}/pagamentos/mes
Headers:
Authorization: Bearer <seuAccessToken>

HTTP/1.1 200 OK
[
    {
        "id": 9022684,
        "numero": "01",
        "status": "ABERTA",
        "valorParcela": 25.00,
        "valorRecebido": 0.00,
        "dataVencimento": "2025-07-09",
        "dataRecebimento": null,
        "linkPagamento": null,
        "urlBoleto": "https://data.sandbox.cel.cash/sandboxawis/boleto/202507EB5HYAYDWSQVFGC52JG6MURWM09171452",
        "pixQrcode": "00020101021226880014BR.GOV.BCB.PIX2566api-h.rendimento.com.br/q/v2/cobv/6dee21d63efd4615aed83f6c34b928d15204000053039865802BR5913AWIS SOFTWARE6011Pato Branco61088550459262070503***6304A40C",
        "pixImage": "https://data.sandbox.cel.cash/sandboxawis/pix/6B6G8FNR8R53B1Y3YCSB0000016765"
    }
]
Códigos de Resposta:
200 OK    – Pagamentos retornados com sucesso  
401 Unauthorized – Token JWT inválido ou ausente  
403 Forbidden    – Escopo insuficiente  
500 Internal Server Error – Erro interno no servidor

Cadastrar Titular

Cria uma nova pessoa como titular.

POST /api/v1/pessoas
Headers:
Content-Type: application/json
Authorization: Bearer <seuAccessToken>
Body:
{
  "nome": "João da Silva",
  "cpf": "543.462.629-02",
  "rg": "MG-12.345.678",
  "dataNascimento": "1980-05-20",
  "sexo": "HOMEM",
  "profissao": "Professor",
  "estadoCivil": "CASADO",
  "contatos": {
    "email": "joao.silva@email.com",
    "celular": "(34) 99999-0000",
    "telefone": "(34) 3222-0000"
  },
  "endereco": {
    "cep": "38700-000",
    "cidade": "Patos de Minas",
    "uf": "MG",
    "bairro": "Centro",
    "logradouro": "Rua dos Andradas",
    "numero": "123",
    "complemento": "Apto 201"
  }

}

HTTP/1.1 201 Created
{
  "id": 286921,
  "nome": "João da Silva",
  "cpf": "543.462.629-02",
  "rg": "MG-12.345.678",
  "dataNascimento": "1980-05-20T00:00:00",
  "sexo": "HOMEM",
  "profissao": "Professor",
  "estadoCivil": "CASADO",
  "tipo": "FISICA",
  "status": "VIVA",
  "statusRegistro": "CADASTRO",
  "contatos": {
    "celular": "(34) 99999-0000",
    "telefone": "(34) 3222-0000",
    "email": "joao.silva@email.com"
  },
  "endereco": {
    "cep": "38700-000",
    "cidade": "Patos de Minas",
    "uf": "MG",
    "bairro": "Centro",
    "logradouro": "Rua dos Andradas",
    "numero": "123",
    "complemento": "Apto 201"
  }
}
Códigos de Resposta Esperados:
201 Created  – Titular cadastrado com sucesso  
400 Bad Request  – Dados inválidos  
401 Unauthorized  – API Key ou Tenant inválido  
403 Forbidden  – Permissão negada  
500 Internal Server Error  – Erro interno no servidor

Buscar Titular por ID

Busca uma pessoa titular pelo ID informado.

GET /api/v1/pessoas/{id}
Headers:
Authorization: Bearer <seuAccessToken>
HTTP/1.1 200 OK
{
    "id": 286911,
    "nome": "Yuri Juan Aragão",
    "cpf": "261.485.584-75",
    "rg": null,
    "dataNascimento": "1980-01-01T00:00:00",
    "sexo": "HOMEM",
    "profissao": null,
    "estadoCivil": "NAO_INFORMADO",
    "contatos": {
        "celular": "(46) 99112-0012",
        "telefone": null,
        "email": "an**e@awis.com.br"
    },
    "endereco": {
        "cep": "59133-375",
        "cidade": "Natal",
        "uf": "RN",
        "bairro": "Pajuçara",
        "logradouro": "Rua Maria Lúcia",
        "numero": "123",
        "complemento": ""
    }
}
Códigos de Resposta Esperados:
200 OK – Titular encontrado com sucesso  
400 Bad Request – ID inválido  
401 Unauthorized – API Key ou Tenant inválido  
403 Forbidden – Permissão negada  
404 Not Found – Titular não encontrado  
500 Internal Server Error – Erro interno no servidor

Buscar Titular por CPF

Busca uma pessoa titular pelo CPF informado.

GET /api/v1/pessoas/cpf/{cpf}
Headers:
Authorization: Bearer <seuAccessToken>
HTTP/1.1 200 OK
{
    "id": 286911,
    "nome": "Yuri Juan Aragão",
    "cpf": "261.485.584-75",
    "rg": null,
    "dataNascimento": "1980-01-01T00:00:00",
    "sexo": "HOMEM",
    "profissao": null,
    "estadoCivil": "NAO_INFORMADO",
    "contatos": {
        "celular": "(46) 99112-0012",
        "telefone": null,
        "email": "an**e@awis.com.br"
    },
    "endereco": {
        "cep": "59133-375",
        "cidade": "Natal",
        "uf": "RN",
        "bairro": "Pajuçara",
        "logradouro": "Rua Maria Lúcia",
        "numero": "123",
        "complemento": ""
    }
}
Códigos de Resposta Esperados:
200 OK – Titular encontrado com sucesso  
400 Bad Request – CPF inválido  
401 Unauthorized – API Key ou Tenant inválido  
403 Forbidden – Permissão negada  
404 Not Found – Titular não encontrado  
500 Internal Server Error – Erro interno no servidor

Cadastrar Dependente

Cria um novo dependente vinculado a uma pessoa.

POST /api/v1/dependentes
Headers:
Content-Type: application/json
Authorization: Bearer <seuAccessToken>
Body:
{
  "cpf": "824.952.440-33",
  "nome": "João Pedro",
  "email": "joao@email.com",
  "fone": "(34) 3232-1000",
  "celular": "(34) 99999-8888",
  "parentesco": "FILHO",
  "sexo": "HOMEM",
  "dataNascimento": "2001-05-20",
  "titularId": 286911,
  "apelido": "Joãozinho",
  "estadoCivil": "SOLTEIRO"
}
HTTP/1.1 201 Created
{
  "id": 1645522,
  "nome": "João Pedro",
  "cpf": "824.952.440-33",
  "email": "joao@email.com",
  "dataNascimento": "2001-05-20",
  "sexo": "HOMEM",
  "titularId": 286911,
  "estadoCivil": "SOLTEIRO",
  "apelido": "Joãozinho",
  "parentesco": "FILHO"
}
Códigos de Resposta:
201 Created  – Dependente cadastrado com sucesso
400 Bad Request  – Dados inválidos
401 Unauthorized  – API Key ou Tenant ausente/inválido
500 Internal Server Error  – Erro interno

Buscar Dependente por ID

Retorna os dados do dependente com base no ID informado.

GET /api/v1/dependentes/{id}
Headers:
Authorization: Bearer <seuAccessToken>
HTTP/1.1 200 OK
{
  "id": 1645500,
  "nome": "Yuri Juan Aragão",
  "cpf": "261.485.584-75",
  "email": "an**e@awis.com.br",
  "dataNascimento": "1980-01-01",
  "sexo": "HOMEM",
  "titularId": 286911,
  "estadoCivil": "NAO_INFORMADO",
  "apelido": null,
  "parentesco": "TITULAR"
}
Códigos de Resposta:
200 OK – Dependente encontrado
404 Not Found – Dependente não encontrado

Buscar Dependente por CPF

Retorna uma lista de dependentes com base no CPF informado.

GET /api/v1/dependentes/cpf/{cpf}
Headers:
Authorization: Bearer <seuAccessToken>
HTTP/1.1 200 OK
[
  {
    "id": 1645500,
    "nome": "Yuri Juan Aragão",
    "cpf": "261.485.584-75",
    "email": "an**e@awis.com.br",
    "dataNascimento": "1980-01-01",
    "sexo": "HOMEM",
    "titularId": 286911,
    "estadoCivil": "NAO_INFORMADO",
    "apelido": null,
    "parentesco": "TITULAR"
  }
]
Códigos de Resposta:
200 OK – Lista retornada
401 Unauthorized – API Key ou Tenant inválido

Listar Dependentes por Titular ID

Retorna todos os dependentes que compartilham o mesmo `titular_id`.

GET /api/v1/dependentes/pessoa/{pessoaId}
Headers:
Authorization: Bearer <seuAccessToken>
Resposta:
[
    {
        "id": 1645500,
        "nome": "Yuri Juan Aragão",
        "cpf": "261.485.584-75",
        "email": "an**e@awis.com.br",
        "dataNascimento": "1980-01-01",
        "sexo": "HOMEM",
        "titularId": 286911,
        "estadoCivil": "NAO_INFORMADO",
        "apelido": null,
        "parentesco": "TITULAR"
    },
    {
        "id": 1645501,
        "nome": "Bruna Silvana Pires",
        "cpf": null,
        "email": null,
        "dataNascimento": "1973-02-25",
        "sexo": "MULHER",
        "titularId": 286911,
        "estadoCivil": "NAO_INFORMADO",
        "apelido": null,
        "parentesco": "IRMAO"
    },
    {
        "id": 1645502,
        "nome": "Stefany Luana Daniela Novaes",
        "cpf": null,
        "email": null,
        "dataNascimento": "2000-01-06",
        "sexo": "MULHER",
        "titularId": 286911,
        "estadoCivil": "NAO_INFORMADO",
        "apelido": null,
        "parentesco": "FILHO"
    },
    {
        "id": 1645503,
        "nome": "Mariana Hadassa Araújo",
        "cpf": null,
        "email": null,
        "dataNascimento": "1971-05-24",
        "sexo": "MULHER",
        "titularId": 286911,
        "estadoCivil": "NAO_INFORMADO",
        "apelido": null,
        "parentesco": "CONJUGE"
    }
]
Códigos de Resposta:
200 OK - Lista de dependentes retornada

Dados da Empresa Logada

Retorna as informações da empresa autenticada.

GET /api/v1/unidades/me
Headers:
Authorization: Bearer <seuAccessToken>
{
    "id": 128,
    "nomeFantasia": "FUNERÁRIA SÃO BENTO",
    "razaoSocial": "FUNERÁRIA SÃO BENTO LTDA",
    "cnpj": "31.286.698/0001-87",
    "contato": {
        "telefone": "(96) 3668-6574",
        "email": "contato@funerariasaobento.com.br"
    },
    "endereco": {
        "cep": "80010-000",
        "cidade": "Curitiba",
        "uf": "PR",
        "bairro": "Centro",
        "logradouro": "Rua José Loureiro",
        "numero": "386",
        "complemento": "",
        "latitude": "-25.43221",
        "longitude": "-49.26854"
    },
    "corPrincipal": "#258a00",
    "corSecundaria": "#025f1e",
    "urlLogo": "http://local....../arquivo?nome=81b60a29-7e22-4f01-9f7e-f9443ddab567_arquivo.png"
}
Códigos de Resposta Esperados:
200 OK    – Dados da unidade retornados com sucesso
401 Unauthorized – Token inválido ou ausente
403 Forbidden    – Permissão negada
500 Internal Server Error – Erro interno no servidor

Listar Unidades

Retorna os dados detalhados das unidades vinculadas à empresa autenticada.

GET /api/v1/unidades/all
Headers:
Authorization: Bearer <seuAccessToken>
Resposta: 200 OK
[
  {
    "id": 128,
    "nomeFantasia": "FUNERÁRIA SÃO BENTO",
    "razaoSocial": "FUNERÁRIA SÃO BENTO LTDA",
    "cnpj": "31.286.698/0001-87",
    "contato": {
      "telefone": "(96) 3668-6574",
      "email": "contato@funerariasaobento.com.br"
    },
    "endereco": {
      "cep": "80010-000",
      "cidade": "Curitiba",
      "uf": "PR",
      "bairro": "Centro",
      "logradouro": "Rua José Loureiro",
      "numero": "386",
      "complemento": "",
      "latitude": "-25.43221",
      "longitude": "-49.26854"
    },
    "corPrincipal": "#258a00",
    "corSecundaria": "#025f1e",
    "urlLogo": "https://app.progem.com.br/progem/api/downloads/empresa/128/arquivo?nome=logo.png"
  }
]
Códigos de Resposta:
200 OK    – Lista de unidades detalhadas retornada com sucesso  
401 Unauthorized – Token inválido ou ausente  
403 Forbidden    – Escopo insuficiente  
500 Internal Server Error – Erro interno

Buscar Vendedor por Email

Retorna os dados do vendedor (usuário comissionado) pelo e-mail informado.

GET /api/v1/vendedores/email/{email}
Headers:
Authorization: Bearer <seuAccessToken>
HTTP/1.1 200 OK
{
  "id": 717,
  "nome": "Fulano de Tal",
  "email": "fulano@exemplo.com"
}
Códigos de Resposta Esperados:
200 OK    – Vendedor encontrado com sucesso  
404 Not Found – Vendedor não encontrado  
401 Unauthorized – Token ausente ou inválido  
403 Forbidden    – Permissão negada  
500 Internal Server Error – Erro interno

Listar Planos da Empresa

Retorna todos os planos da empresa, incluindo precificação, faixas etárias e regras de isenção. 

GET /api/v1/planos
Headers:
Authorization: Bearer <seuAccessToken>
HTTP/1.1 200 OK
[
  {
    "id": 2691,
    "nome": "Plano Familiar Ouro",
    "foto": "https://app.pro...vo?nome=34652b80-f571-4b2d-a9b0-ef326ee0d0d0_download_3.jpeg",
    "valorUnitario": 120.00,
    "valorAdesao": 50.00,
    "numeroDependentes": 5,
    "valorIncremental": 10.00,
    "valorCondicional": 0.00,
    "numeroParcelas": 12,
    "idadeMinimaTitular": 18,
    "idadeMaximaTitular": 75,
    "idadeMinimaDependente": 0,
    "idadeMaximaDependente": 75,
    "unidadeCarencia": "DIAS",
    "tipoCarencia": "LIMITADA",
    "inadimplenciaCarencia": 2,
    "periodoCarencia": 90,
    "compartilharPlano": true,
    "parentescos": ["CONJUGE", "FILHO", "PAI", "MAE"],
    "faixasEtarias": [
	  { "idadeMinima": 0, "idadeMaxima": 17, "valor": 10.00 },
	  { "idadeMinima": 18, "idadeMaxima": 59, "valor": 20.00 },
	  { "idadeMinima": 60, "idadeMaxima": 120, "valor": 30.00 }
    ],
    "faixasEtariasTitular": [
	  { "idadeMinima": 18, "idadeMaxima": 59, "valor": 25.00 },
	  { "idadeMinima": 60, "idadeMaxima": 120, "valor": 35.00 }
    ],
    "produtos": [
      { "nome": "VEU BORDADO" },
	  { "nome": "FLORES PARA ORNAMENTAÇÃO NA URNA" },
	  { "nome": "LIVRO DE PRESENÇA" },
	  { "nome": "VESTIMENTA" },
	  { "nome": "SALÃO VELÓRIO DAS EMPRESAS DO GRUPO" },
	  { "nome": "VELAS" },
	  { "nome": "COROA DE FLORES NATURAL DESIDATADA COM FAIXA PARA HOMENAGEM" }
    ],
    "servicos": [
	  { "descricao": "ORIENTAÇÃO SOBRE REGISTRO DE ÓBITO JUNTO AO CARTÓRIO" },
	  { "descricao": "CONSERVAÇÃO/EMBALSAMAMENTO" },
	  { "descricao": "CARRO FUNERÁRIO PARA TRASLADO" }
    ],
    "isencoes": [
	  { "idadeMinima": 0, "idadeMaxima": 5, "parentesco": "Filho" },
	  { "idadeMinima": 60, "idadeMaxima": 80, "parentesco": "Pai" }
    ],
    "links": [
      {
        "link": "https://plataforma.tv",
        "descricao": "Plataforma de IPTV",
        "observacoes": "A melhor e maior plataforma de entretenimento gratuito",
        "logo": "https://app.pro...vo?nome=logo.png",
        "capa": "https://app.pro...vo?nome=capa.png",
        "visivel": true
      }
    ],
  }
]
Códigos de Resposta Esperados:
200 OK - Consulta realizada com sucesso
401 Unauthorized - API Key ausente ou inválida
500 Internal Server Error - Erro interno

Buscar Plano por ID

Retorna os dados completos de um plano com base no ID informado. 

GET /api/v1/planos/{id}
Headers:
Authorization: Bearer <seuAccessToken>
HTTP/1.1 200 OK
{
  "id": 2691,
  "nome": "Plano Familiar Ouro",
  "foto": "https://app.pro...vo?nome=34652b80-f571-4b2d-a9b0-ef326ee0d0d0_download_3.jpeg",
  "valorUnitario": 120.00,
  "valorAdesao": 50.00,
  "numeroDependentes": 5,
  "valorIncremental": 10.00,
  "valorCondicional": 0.00,
  "numeroParcelas": 12,
  "idadeMinimaTitular": 18,
  "idadeMaximaTitular": 75,
  "idadeMinimaDependente": 0,
  "idadeMaximaDependente": 75,
  "unidadeCarencia": "DIAS",
  "tipoCarencia": "LIMITADA",
  "inadimplenciaCarencia": 2,
  "periodoCarencia": 90,
  "compartilharPlano": true,
  "parentescos": ["CONJUGE", "FILHO", "PAI", "MAE"],
  "faixasEtarias": [
	{ "idadeMinima": 0, "idadeMaxima": 17, "valor": 10.00 },
	{ "idadeMinima": 18, "idadeMaxima": 59, "valor": 20.00 },
	{ "idadeMinima": 60, "idadeMaxima": 120, "valor": 30.00 }
  ],
  "faixasEtariasTitular": [
	{ "idadeMinima": 18, "idadeMaxima": 59, "valor": 25.00 },
	{ "idadeMinima": 60, "idadeMaxima": 120, "valor": 35.00 }
  ],
  "produtos": [
	{ "nome": "VEU BORDADO" },
	{ "nome": "FLORES PARA ORNAMENTAÇÃO NA URNA" },
	{ "nome": "LIVRO DE PRESENÇA" },
	{ "nome": "VESTIMENTA" },
	{ "nome": "SALÃO VELÓRIO DAS EMPRESAS DO GRUPO" },
	{ "nome": "VELAS" },
	{ "nome": "COROA DE FLORES NATURAL DESIDATADA COM FAIXA PARA HOMENAGEM" }
  ],
  "servicos": [
	{ "descricao": "ORIENTAÇÃO SOBRE REGISTRO DE ÓBITO JUNTO AO CARTÓRIO" },
	{ "descricao": "CONSERVAÇÃO/EMBALSAMAMENTO" },
	{ "descricao": "CARRO FUNERÁRIO PARA TRASLADO" }
  ],
  "isencoes": [
	{ "idadeMinima": 0, "idadeMaxima": 5, "parentesco": "Filho" },
	{ "idadeMinima": 60, "idadeMaxima": 80, "parentesco": "Pai" }
  ],
  "links": [
    {
      "link": "https://plataforma.tv",
      "descricao": "Plataforma de IPTV",
      "observacoes": "A melhor e maior plataforma de entretenimento gratuito",
      "logo": "https://app.pro...vo?nome=logo.png",
      "capa": "https://app.pro...vo?nome=capa.png",
      "visivel": true
    }
  ],
}
Códigos de Resposta Esperados:
200 OK – Plano encontrado
401 Unauthorized – API Key ausente ou inválida
404 Not Found – Plano não encontrado
500 Internal Server Error – Erro interno

Listar Locais Parceiros

Retorna todos os locais marcados como parceiros para a empresa (tenant) corrente.

GET /api/v1/locais/parceiros
Headers:
Authorization: Bearer <seuAccessToken>
Resposta: 200 OK
[
    {
        "id": 3921,
        "nome": "B & B Serviços Médicos",
        "imagem": "https://app.pr....c_download%20%283%29.png",
        "beneficios": [
            {
                "id": 3,
                "descricao": "Desconto em consultas odontológicas",
                "media": "https://app.pr....c_download%20%283%29.png",
                "dataPublicacao": "2025-10-10",
                "publicado": true,
                "tipo": "PORCENTAGEM",
                "valor": 0.00,
                "porcentagem": 20.00
            },
            {
                "id": 4,
                "descricao": "Desconto em exames laboratoriais",
                "media": null,
                "dataPublicacao": mull,
                "publicado": false,				
                "tipo": "PORCENTAGEM",
                "valor": 0.00,
                "porcentagem": 20.00
            },
            {
                "id": 5,
                "descricao": "Descontos em consultas medicas",
                "media": null,
                "dataPublicacao": mull,
                "publicado": false,				
                "tipo": "PORCENTAGEM",
                "valor": 0.00,
                "porcentagem": 20.00
            }
        ],
        "contatos": {
            "celular": "",
            "telefone": "(11) 3000-999",
            "email": "https://www.bebcentromedicoo.com.br/"
        },
        "endereco": {
            "cep": "05615-040",
            "cidade": "São Paulo",
            "uf": "SP",
            "bairro": "Vila Progredior",
            "logradouro": "Rua Carlos Lima Morel",
            "numero": "423",
            "complemento": null,
            "latitude": "-23.58528",
            "longitude": "-46.71699"
        }
    }
]
Códigos de Resposta:
200 OK    – Lista de parceiros retornada com sucesso  
401 Unauthorized – Token JWT inválido ou ausente  
403 Forbidden    – Escopo insuficiente  
500 Internal Server Error – Erro interno no servidor

Meu Perfil – GET /api/v1/app/me

Retorna os dados do usuário autenticado.

GET /api/v1/app/me
Headers:
Authorization: Bearer <accessToken>
X-Progem-ID: <empresaId (tenant)>
HTTP/1.1 200 OK
{
  "id": 12345,
  "nome": "Maria da Silva",
  "email": "maria@exemplo.com",
  "cpf": "12345678909",
  "celular": "(46) 99888-0000",
  "fotoUrl": "https://cdn.exemplo.com/avatars/maria.png",
  "status": "ATIVO",
  "criadoEm": "2025-07-01T14:12:33Z"
}
200 OK            – Perfil retornado
401 Unauthorized  – Access token ausente/ inválido
403 Forbidden     – Sem permissão

Atualizar Perfil – PATCH /api/v1/app/me

Atualiza campos básicos do usuário autenticado.

PATCH /api/v1/app/me
Headers:
Content-Type: application/json
Authorization: Bearer <accessToken>
X-Progem-ID: <empresaId>

Body (exemplo):
{
  "nome": "Maria O. da Silva",
  "celular": "(46) 99888-0000",
  "fotoUrl": "https://cdn.exemplo.com/avatars/maria.png"
}
HTTP/1.1 200 OK
{
  "id": 12345,
  "nome": "Maria O. da Silva",
  "email": "maria@exemplo.com",
  "cpf": "12345678909",
  "celular": "(46) 99888-0000",
  "fotoUrl": "https://cdn.exemplo.com/avatars/maria.png",
  "status": "ATIVO"
}
200 OK             – Atualizado com sucesso
400 Bad Request    – Campos inválidos
401 Unauthorized   – Token inválido/ausente
403 Forbidden      – Sem permissão

Registrar Usuário – POST /api/v1/app/auth/register

Cria um novo usuário do app.

POST /api/v1/app/auth/register
Headers:
Content-Type: application/json
Authorization: Bearer <accessToken>
X-Progem-ID: <empresaId>
X-Device-ID: <uuid-do-aparelho>

Body:
{
  "nome": "Maria Oliveira",
  "email": "maria@exemplo.com",
  "senha": "SenhaForte!2025",
  "cpf": "123.456.789-09",
  "celular": "(46) 99123-4567",
  "dataNascimento": "1990-05-10",
  "aceiteTermos": true,
  "aceitePrivacidade": true
}
HTTP/1.1 201 Created
{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "userId": 12345,
  "nome": "Maria Oliveira",
  "email": "maria@exemplo.com",
  "cpf": "12345678909"
}
201 Created        – Usuário criado
400 Bad Request    – Dados inválidos
409 Conflict       – E-mail/CPF já em uso
500 Internal Error – Erro no servidor

Esqueci a Senha – POST /api/v1/app/password/forgot

Inicia o fluxo de recuperação de senha enviando um código de verificação por e-mail ou SMS.

POST /api/v1/app/password/forgot
Headers:
Content-Type: application/json
X-Progem-ID: <empresaId>
User-Agent: <app ou navegador>

Body:
{
  "identifier": "cliente@exemplo.com",
  "channel": "EMAIL"
}

Observação: O campo identifier pode ser e-mail, CPF ou celular. O campo channel é opcional e define o canal (EMAIL ou SMS).

HTTP/1.1 200 OK

A resposta é cega: o status 200 OK é retornado mesmo que o usuário não exista, por motivos de segurança.

200 OK             – Fluxo iniciado com sucesso
400 Bad Request    – Dados inválidos
429 Too Many Req.  – Limite de tentativas atingido
500 Internal Error – Erro interno no servidor

Resetar Senha – POST /api/v1/app/password/reset

Conclui o fluxo de recuperação de senha, usando o código enviado por e-mail/SMS e definindo uma nova senha.

POST /api/v1/app/password/reset
Headers:
Content-Type: application/json
X-Progem-ID: <empresaId>

Body:
{
  "identifier": "cliente@exemplo.com",
  "codigo": "482913",
  "novaSenha": "NovaSenhaForte!2025"
}

Nota: O identifier deve ser o mesmo informado no passo /forgot.

HTTP/1.1 200 OK
{
  "message": "Senha redefinida com sucesso."
}
200 OK             – Senha redefinida
400 Bad Request    – Código inválido ou expirado
404 Not Found      – Usuário não encontrado
500 Internal Error – Erro interno no servidor

Alterar Senha – POST /api/v1/app/password/change

Permite ao usuário autenticado alterar sua senha atual para uma nova senha.

POST /api/v1/app/password/change
Headers:
Content-Type: application/json
Authorization: Bearer <accessToken>
X-Progem-ID: <empresaId>

Body:
{
  "email": "cliente@exemplo.com",
  "senhaAtual": "MinhaSenha@2024",
  "novaSenha": "NovaSenhaForte!2025"
}

Requisitos: O usuário deve estar autenticado e o e-mail deve corresponder ao usuário do token.

HTTP/1.1 200 OK
{
  "message": "Senha alterada com sucesso."
}
200 OK             – Senha alterada com sucesso
400 Bad Request    – Dados inválidos
401 Unauthorized   – Token ausente ou inválido
403 Forbidden      – Senha atual incorreta
404 Not Found      – Usuário não encontrado
500 Internal Error – Erro interno do servidor

Autenticação (App) – Login unificado por email ou cpf

Use este endpoint quando o usuário final fizer login no aplicativo.

Endpoint

POST /api/v1/app/auth/login

Headers obrigatórios

  • X-Progem-ID: <empresaId> (tenant)
  • X-Device-ID: <uuid-do-aparelho>
  • Content-Type: application/json
  • Authorization: Bearer <accessToken>

Body (JSON)

{
  "identificador": "maria@exemplo.com",   // ou "123.456.789-09"
  "senha": "SenhaForte!2025"
}

Resposta – 200 OK

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "userId": 987,
  "nome": "Maria da Silva",
  "email": "maria@exemplo.com",
  "cpf": "12345678909"
}
Exemplos cURL 
curl -X POST https://sandbox-api.progem.com.br/api/v1/app/auth/login \
 -H "X-Progem-ID: 407" \
 -H "X-Device-ID: 550e8400-e29b-41d4-a716-446655440000" \
 -H "Content-Type: application/json" \
 -d '{ "identificador":"123.456.789-09", "senha":"SuaSenha" }'
curl -X POST https://api.progem.com.br/api/v1/app/auth/login \
 -H "X-Progem-ID: 407" \
 -H "X-Device-ID: 550e8400-e29b-41d4-a716-446655440000" \
 -H "Content-Type: application/json" \
 -d '{ "identificador":"maria@exemplo.com", "senha":"SuaSenha" }'

Erros comuns

  • 400 Bad Request: ausência de X-Device-ID ou body inválido.
  • 401 Unauthorized: credenciais inválidas.
  • 422 Unprocessable Entity: CPF inválido (menos de 11 dígitos após normalização).
  • 429 Too Many Requests: limite de tentativas excedido (se habilitado).

Refresh Token – POST /api/v1/app/auth/refresh

Gera um novo par accessToken + refreshToken a partir de um refreshToken válido. 

POST /api/v1/app/auth/refresh
Headers:
Content-Type: application/json
Authorization: Bearer <accessToken>
X-Progem-ID: <empresaId>
X-Device-ID: <uuid-do-aparelho>

Body:
{
  "refreshToken": "eyJhbGciOi..."
}
HTTP/1.1 200 OK
{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi..."
}
200 OK              – Token renovado
400 Bad Request     – Falta X-Device-ID ou body inválido
401 Unauthorized    – refreshToken inválido/expirado
403 Forbidden       – refreshToken de outro tenant
500 Internal Error  – Erro no servidor
  • O back-end valida: assinatura, expiração, tenant (X-Progem-ID), existência na base (hash) e revogação.
  • Por política, um usuário possui um refresh ativo por device. Ao renovar, os antigos do mesmo device são revogados.

Logout – POST /api/v1/app/auth/logout

Revoga os refresh tokens do usuário para o deviceId informado.

POST /api/v1/app/auth/logout
Headers:
Authorization: Bearer <accessToken>
X-Progem-ID: <empresaId>
X-Device-ID: <uuid-do-aparelho>

Body:
{
  "deviceId": "12312345678"
}

HTTP/1.1 204 No Content
204 No Content      – Logout efetuado
400 Bad Request     – Falta X-Device-ID
401 Unauthorized    – Token inválido/ausente