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

Mesmo domínio, separados por caminho. Cada ambiente tem sua própria chave e seus próprios dados (homologação é 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" }
    ]
  }'

Para individual, é só omitir dependents.

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" },
        "dependents": [ { "cpf": "556.677.889-50", "full_name": "Ana Funcionária" } ]
      },
      { "profile": { "cpf": "111.444.777-35", "full_name": "Bruno Sem Dependente" } }
    ]
  }'

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 vinculados ao CPF.

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

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 próprio) vinculada ao titular.
• 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).