Como fazer uma inclusão

Uma inclusão registra um novo membro (titular e/ou dependentes) ou adiciona um benefício a um membro que já existe. As inclusões são assíncronas: a API responde com um request-id e o processamento continua em segundo plano — acompanhe o resultado pela consulta de requisição ou por webhooks.

Antes de começar, revise Convenções — valores em centavos, datas ISO 8601, campos em kebab-case. Toda chamada exige o header Authorization: Bearer <access-token> (ver Autenticação).

Escolhendo o endpoint

Cenário	Endpoint
Incluir novos membros / grupos familiares (em lote)	`POST /v1/enrollment/inclusion`
Incluir um benefício em um membro já existente	`POST /v1/enrollment/inclusion/{member-tax-id}`

Inclusão em lote

Monte o payload

Informe company-tax-id e a lista members. Cada membro traz seus dados de perfil e o mapa products (tipo de produto → entradas com start-option e name ou product-id).

Envie a requisição

POST /v1/enrollment/inclusion com o corpo JSON.

Guarde o request-id

A resposta 200 traz { "request-id": "..." }. Use-o para acompanhar o processamento.

Inclusão de titular

{
  "company-tax-id": "12345678000190",
  "members": [
    {
      "beneficiary-type": "primary",
      "name": "João Silva",
      "tax-id": "12345678900",
      "mothers-name": "Maria Silva",
      "date-of-birth": "1985-05-15",
      "gender": "male",
      "marital-status": "married",
      "admission-date": "2024-01-01",
      "work-contract-type": "brazil-labor-law",
      "job-title": "Desenvolvedor Senior",
      "employee-id": "EMP001",
      "salary": 800000,
      "email-corporate": "joao.silva@acme.com",
      "email-private": "joao.silva@email.com",
      "phone": "11987654321",
      "products": {
        "health-insurance": [
          { "name": "Plano Saúde Premium", "start-option": "on-inclusion-date" }
        ]
      }
    }
  ]
}

Inclusão de grupo familiar (membro com dependentes)

O titular e seus dependentes vão no mesmo array members. O dependente é vinculado pelo primary-tax-id. Documentos previamente enviados (ver envio de documentos) são referenciados pelo document-id.

{
  "company-tax-id": "12345678000190",
  "members": [
    {
      "beneficiary-type": "primary",
      "name": "Mariazinha da Silva",
      "tax-id": "12345678900",
      "mothers-name": "Mãe Maria Silva",
      "date-of-birth": "1985-05-15",
      "gender": "female",
      "marital-status": "married",
      "admission-date": "2024-01-01",
      "work-contract-type": "brazil-labor-law",
      "job-title": "Desenvolvedora Senior",
      "employee-id": "EMP001",
      "salary": 800000,
      "email-corporate": "maria.silva@acme.com",
      "email-private": "maria.silva@email.com",
      "phone": "11987654321",
      "documents": [
        { "document-id": "cd56c772-e8d9-4ce9-82c7-7bb155de40cc", "document-type": "identification-document-with-tax-id" },
        { "document-id": "957ef952-8515-4dd6-b356-c1434a8e9f33", "document-type": "enrollment-request" }
      ],
      "products": {
        "health-insurance": [
          { "product-id": "4de3d975-a4ed-47ab-aab9-d4a190fea06f", "start-option": "on-inclusion-date" }
        ],
        "dental-insurance": [
          { "product-id": "6b9616e3-f76b-414f-b5d5-75ebc90d5895", "start-option": "on-inclusion-date" }
        ]
      }
    },
    {
      "beneficiary-type": "dependent",
      "name": "Filho da Mariazinha",
      "tax-id": "41165181070",
      "primary-tax-id": "12345678900",
      "mothers-name": "Mariazinha da Silva",
      "date-of-birth": "2020-03-01",
      "gender": "male",
      "marital-status": "single",
      "dependent-relationship-type": "child",
      "dependent-relationship-start-date": "2020-03-01",
      "phone": "11911234456",
      "email-private": "filho.mariazinha@example.com",
      "weight": 7000,
      "height": 18000,
      "handicapped": "no",
      "documents": [
        { "document-id": "e079e1ad-bdff-49e9-85f7-fbd228ca15fd", "document-type": "document-proving-relationship" }
      ],
      "products": {
        "health-insurance": [
          { "product-id": "4de3d975-a4ed-47ab-aab9-d4a190fea06f", "start-option": "on-inclusion-date" }
        ]
      }
    }
  ]
}

Respostas de erro

403 Forbidden — sem permissão para acessar esta empresa

{ "error": "Not entitled to access this company" }

422 Unprocessable Entity — dados inválidos

A resposta devolve o lote com as offenses de cada membro. Ver Quando a movimentação não é aceita (422).

Inclusão de benefício em membro existente

Use POST /v1/enrollment/inclusion/{member-tax-id} com o CPF do membro no caminho. O corpo traz company-tax-id e member-benefits.

{
  "company-tax-id": "12345678000190",
  "member-benefits": {
    "beneficiary-type": "primary",
    "products": {
      "health-insurance": [
        { "name": "Plano Saúde Premium", "start-option": "on-inclusion-date" }
      ]
    }
  }
}

A resposta de sucesso (200) traz o request-id:

{ "request-id": "bbb22222-e89b-12d3-a456-426614174007" }

Respostas de erro

400 Bad Request — membro não é titular da empresa especificada

{ "error": "Member is not primary with the specified company" }

403 Forbidden — sem permissão

{ "error": "Not entitled to modify this member" }

422 Unprocessable Entity — dados inválidos

Além dos dados do membro, a resposta inclui as offenses que indicam quais validações falharam.

{
  "result": {
    "beneficiary-type": "primary",
    "company-tax-id": "12345678000190",
    "products": {
      "health-insurance": [
        { "name": "Plano Saúde Premium", "start-option": "on-inclusion-date" }
      ]
    },
    "offenses": ["product-health-insurance-0-already-exists"]
  }
}

Acompanhando o resultado

A inclusão retorna um request-id:

{ "request-id": "aaa11111-e89b-12d3-a456-426614174006" }

Consulte o status com GET /v1/request/{request-id}, que retorna o andamento por CPF e por produto.

Quando a movimentação não é aceita (422)

Se houver violações de validação, a resposta é 422 com o payload devolvido e uma lista de offenses por membro e/ou por documento:

{
  "result": [
    {
      "beneficiary-type": "primary",
      "name": "João Silva",
      "tax-id": "12345678900",
      "company-tax-id": "12345678000190",
      "offenses": ["invalid-tax-id", "missing-mothers-name"]
    }
  ]
}

Consulte a lista completa em Ofensas.

Testando em homologação

O parâmetro de query opcional auto-resolve-enrollments permite resolver a movimentação automaticamente: approve aprova, reject rejeita. Esta opção existe apenas no ambiente de Homologação, para testes.

POST /v1/enrollment/inclusion?auto-resolve-enrollments=approve

Começar

Guias

Referência

Escolhendo o endpoint

Inclusão em lote

Respostas de erro

Inclusão de benefício em membro existente

Respostas de erro

Acompanhando o resultado

Quando a movimentação não é aceita (422)

Testando em homologação

​Escolhendo o endpoint

​Inclusão em lote

​Respostas de erro

​Inclusão de benefício em membro existente

​Respostas de erro

​Acompanhando o resultado

​Quando a movimentação não é aceita (422)

​Testando em homologação

Escolhendo o endpoint

Inclusão em lote

Respostas de erro

Inclusão de benefício em membro existente

Respostas de erro

Acompanhando o resultado

Quando a movimentação não é aceita (422)

Testando em homologação