Referência da API

API de cadastro TKS Vantagens

Uma API para empresas parceiras cadastrarem beneficiários no ecossistema TKS. Quando o cliente paga na plataforma do parceiro, o cadastro é enviado para cá, e o beneficiário já consegue ativar os produtos (telemedicina, clube de vantagens) com o CPF.

É uma API REST simples: você envia JSON por POST, autentica com um cabeçalho, e recebe JSON de volta. Sem SDK, sem OAuth.

Ambientes

Cada ambiente é um subdomínio próprio, com sua própria chave e seus próprios dados (homologação é totalmente isolada da produção).

⚠️ Os endpoints terminam com barra final. Ex.: /onboard/.

Autenticação

Toda requisição precisa do cabeçalho x-client-key. Essa chave identifica o parceiro, o sistema já sabe qual empresa é e vincula os cadastros automaticamente. Você não envia a empresa no corpo.

x-client-key: tks_hml_test_key_2026

• Uma chave por ambiente: a de homologação não funciona em produção.
• Nunca exponha a chave em frontend/navegador, ela é de servidor para servidor.
• Chave ausente → 401. Chave inválida → invalid_client_key.

Como testar

Use o ambiente de homologação com a chave de teste abaixo. Já existe uma empresa sandbox com contrato de Telemedicina + Clube de Vantagens pronta.

Os cadastros feitos em homologação não afetam clientes reais e não aparecem na plataforma de produção.

Cadastro: Pessoa Física

Cadastra uma pessoa. Pode ser individual (só o titular) ou família (titular + dependentes). Cada dependente tem CPF próprio e recebe os mesmos benefícios, vinculado ao titular.

Campos do profile

Exemplo: família (com dependente)

curl -X POST "https://api-hml.vantagens.online/onboard/" \
  -H "Content-Type: application/json" \
  -H "x-client-key: tks_hml_test_key_2026" \
  -d '{
    "profile": {
      "cpf": "223.344.556-28",
      "full_name": "Maria Souza",
      "birth_date": "1985-03-10",
      "email_customer": "maria@email.com"
    },
    "dependents": [
      { "cpf": "334.455.667-39", "full_name": "Pedro Souza", "birth_date": "2012-05-05", "email_customer": "pedro@email.com" }
    ]
  }'

Para individual, é só omitir dependents.

Seleção de produtos (opcional)

Por padrão a pessoa recebe todos os produtos do contrato. Se o contrato tiver mais de um produto e você quiser escolher quais produtos cada usuário recebe, envie products com os códigos. Dependentes herdam a seleção do titular.

Você só pode selecionar produtos que fazem parte do seu contrato. Depois do cadastro, dá para trocar a seleção pelo endpoint /assign.

curl -X POST "https://api-hml.vantagens.online/onboard/" \
  -H "Content-Type: application/json" \
  -H "x-client-key: tks_hml_test_key_2026" \
  -d '{
    "profile": { "cpf": "111.444.777-35", "full_name": "João Silva", "email_customer": "joao@email.com" },
    "products": ["CLUBE"]
  }'

Resposta

{
  "ok": true,
  "data": {
    "mode": "single",
    "profile_id": "uuid-do-titular",
    "cpf": "22334455628",
    "dependents_count": 1,
    "dependents": [ { "profile_id": "uuid", "is_dependent": true } ]
  }
}

Cadastro: Empresarial (em lote)

Uma empresa-cliente cadastra vários funcionários de uma vez, cada um com seus dependentes. Todos ficam etiquetados com o CNPJ da empresa-cliente (employer.ref), o que permite o relatório de "quais usuários vieram de qual empresa".

Estrutura

Exemplo

curl -X POST "https://api-hml.vantagens.online/onboard-corporate/" \
  -H "Content-Type: application/json" \
  -H "x-client-key: tks_hml_test_key_2026" \
  -d '{
    "employer": { "ref": "11.222.333/0001-81", "name": "Padaria do Zé" },
    "members": [
      {
        "profile": { "cpf": "445.566.778-40", "full_name": "Carlos Funcionário", "email_customer": "carlos@email.com" },
        "dependents": [ { "cpf": "556.677.889-50", "full_name": "Ana Funcionária", "email_customer": "ana@email.com" } ]
      },
      { "profile": { "cpf": "111.444.777-35", "full_name": "Bruno Sem Dependente", "email_customer": "bruno@email.com" } }
    ]
  }'

Resposta: relatório linha a linha

O lote tem falha parcial: se um CPF vier errado, os outros passam. Você recebe HTTP 200 com um resumo e o resultado de cada funcionário.

{
  "ok": true,
  "data": {
    "mode": "batch",
    "employer": { "ref": "11222333000181", "name": "Padaria do Zé" },
    "summary": { "members_total": 2, "members_ok": 2, "members_failed": 0 },
    "results": [
      { "index": 0, "status": "ok", "cpf": "44556677840", "profile_id": "uuid", "dependents_count": 1 },
      { "index": 1, "status": "ok", "cpf": "11144477735", "profile_id": "uuid", "dependents_count": 0 }
    ]
  }
}

Uma linha com erro fica assim: { "index": 3, "status": "error", "cpf": "…", "error": "invalid_cpf" }

Acima disso, envie em lotes menores (paginação).

Listar benefícios

Retorna os benefícios (ativos e inativos) vinculados a um CPF, dentro do seu contrato.

curl "https://api-hml.vantagens.online/entitlements/?cpf=11144477735" \
  -H "x-client-key: tks_hml_test_key_2026"

Resposta

{
  "ok": true,
  "data": {
    "exists": true,
    "cpf": "11144477735",
    "items": [
      { "product_name": "Clube de Vantagens", "status": "active" },
      { "product_name": "Telemedicina", "status": "active" }
    ]
  }
}

Consultar situação

Retorna a situação de um CPF dentro do seu contrato, sem alterar nada. Traz o status do vínculo, o resumo de benefícios (ativos/inativos) e o papel da pessoa: se for titular, vem a lista dos dependentes com o status de cada; se for dependente, vem quem é o titular.

curl "https://api-hml.vantagens.online/status/?cpf=11144477735" \
  -H "x-client-key: tks_hml_test_key_2026"

Resposta: titular (mostra a família)

{
  "ok": true,
  "data": {
    "exists": true,
    "role": "titular",
    "membership": { "status": "active" },
    "entitlements_summary": { "active": 2, "inactive": 0 },
    "dependents": [
      { "cpf": "…", "full_name": "Maria", "status": "active" }
    ]
  }
}

Se o CPF for de um dependente, a resposta traz "role": "dependente" e um bloco holder com o CPF e o nome do titular.

Alterar produtos

Muda quais produtos um membro usa depois que ele já foi cadastrado. Você envia a lista completa de produtos que ele deve ter dali em diante. Não é adicionar ou remover um a um: o sistema compara com o que ele tem hoje e acerta a diferença, ligando os produtos que faltam e desligando os que ficaram de fora da lista.

Exemplo: se o membro tem Clube + Telemedicina e você envia ["CLUBE"], ele fica só com o Clube (a Telemedicina é desligada).

Aplicar no titular ajusta os dependentes dele junto; aplicar num dependente ajusta só ele.

curl -X POST "https://api-hml.vantagens.online/assign/" \
  -H "Content-Type: application/json" \
  -H "x-client-key: tks_hml_test_key_2026" \
  -d '{ "cpf": "11144477735", "products": ["CLUBE"] }'

Resposta

{
  "ok": true,
  "data": {
    "exists": true,
    "is_member": true,
    "cpf": "11144477735",
    "products_requested": ["CLUBE"],
    "applied": [
      { "cpf": "11144477735", "is_dependent": false,
        "created": 0, "reactivated": 0, "inactivated": 1,
        "products_active": ["CLUBE"] },
      { "cpf": "…", "is_dependent": true,
        "created": 0, "reactivated": 0, "inactivated": 1,
        "products_active": ["CLUBE"] }
    ]
  }
}

Não altera o status do vínculo (ativo/inativo). Só afeta membros da sua própria carteira.

Cancelar vínculo

Desativa o vínculo e os benefícios de um CPF (status → inactive). Não apaga nada, é reversível. Só afeta os benefícios vindos do seu contrato.

Família: cancelar um titular desativa também todos os dependentes dele; cancelar um dependente afeta só ele.

curl -X POST "https://api-hml.vantagens.online/cancel/" \
  -H "Content-Type: application/json" \
  -H "x-client-key: tks_hml_test_key_2026" \
  -d '{ "cpf": "11144477735" }'

Resposta

{
  "ok": true,
  "data": {
    "exists": true,
    "updated": {
      "membership_inactivated": 1,
      "entitlements_inactivated": 2,
      "dependents_inactivated": 2,
      "dependents_entitlements_inactivated": 4
    }
  }
}

Regras & validações

• CPF: aceito com ou sem máscara; é validado de verdade (dígito verificador). CPF inválido é recusado.
• CNPJ (employer.ref): aceito com ou sem máscara; armazenado só com dígitos e validado. Assim o mesmo cliente nunca "racha" em dois por formatação.
• Dependentes: cada um vira uma conta própria (CPF e e-mail próprios) vinculada ao titular.
• E-mail obrigatório: toda pessoa (titular e cada dependente) precisa de e-mail próprio; o sistema não gera. É necessário para ativar a Telemedicina.
• Únicos na família: num mesmo cadastro, CPF e e-mail não podem repetir (dependente ≠ titular ≠ outro dependente).
• Ativação em família: quando o titular ativa os benefícios no portal, os dependentes são ativados junto (não precisam ativar um a um).
• Família (cancel/status): cancelar um titular desativa junto os dependentes dele; consultar um titular mostra a família, e um dependente mostra o titular.
• Seleção de produtos: por padrão o membro recebe todos os produtos do contrato; envie products (por código) no cadastro para escolher um subconjunto, e use /assign para trocar depois. Dependentes herdam a seleção do titular. Reativar (/reactivate) preserva a seleção — não re-concede produtos que o membro não tinha.
• Falha parcial (lote): um registro com erro não derruba os outros; vem relatório por linha.
• Idempotente: reenviar o mesmo CPF não duplica; atualiza o que faltava.
• Rate limit: 60 requisições a cada 5 minutos por IP.

Códigos de erro

No lote, erros de um funcionário aparecem em results[].error (não como HTTP de erro).