Como fazer uma exclusão

Uma exclusão encerra um ou mais benefícios de um membro. Assim como a inclusão, é assíncrona: a API responde com um request-id e o processamento segue em segundo plano.

Toda chamada exige o header Authorization: Bearer <access-token> (ver Autenticação). Datas em ISO 8601 e campos em kebab-case (ver Convenções).

Escolhendo o endpoint

Cenário	Endpoint
Excluir os benefícios primários de um membro	`POST /v1/enrollment/exclusion/{member-tax-id}`
Excluir benefícios em que o membro é dependente	`POST /v1/enrollment/exclusion/{member-tax-id}/dependent-of/{primary-member-tax-id}`
Excluir um benefício específico	`POST /v1/enrollment/exclusion/{member-tax-id}/benefit/{benefit-id}`
Excluir o benefício vinculado a um produto	`POST /v1/enrollment/exclusion/{member-tax-id}/product/{product-id}`

product-id identifica o benefício pelo produto contratado, e não pelo benefit-id. Se o membro tiver mais de um benefício ativo do mesmo produto dentro do escopo de empresas autorizado do chamador (ex.: o mesmo produto em duas empresas do mesmo grupo), a API não escolhe um deles: a exclusão é recusada com 409. Nesse caso, use o endpoint por benefit-id.

O corpo `exclusion-details`

Todos os quatro endpoints recebem o mesmo objeto exclusion-details:

Campo	Tipo	Obrigatório	Descrição
`end-date`	date	Sim	Data de fim do benefício (ISO 8601). Não pode estar no passado.
`exclusion-reason`	enum	Sim	`dismissal`, `voluntary-dismissal`, `just-cause-dismissal`, `requested-by-beneficiary` ou `other`.
`extension-plan`	boolean	Não	Solicita plano de extensão para todos os benefícios afetados. Ver regra de elegibilidade abaixo.
`extension-plan-rule`	array de objeto	Não	Solicita plano de extensão apenas para os produtos listados, cada um com a sua data de fim (`{ "product-id", "end-date" }`). Ver a seção Plano de extensão por produto abaixo.
`exclusion-reason-details`	string	Condicional	Obrigatório quando `exclusion-reason` = `other`.
`documents`	array	Não	Documentos (`document-id` + `document-type`) previamente enviados.

Plano de extensão só é concedido quando exclusion-reason é dismissal e o benefício é health-insurance ou dental-insurance. Para qualquer outra combinação de motivo/tipo de benefício, extension-plan e extension-plan-rule são ignorados silenciosamente — a exclusão segue normalmente, sem extensão.

Plano de extensão por produto

Com extension-plan-rule você escolhe quais produtos continuam ativos durante a extensão e até quando cada um. Cada benefício afetado pela exclusão recebe sua data de fim assim:

Situação do benefício	Extensão	Data de fim aplicada
Elegível e com o produto listado em `extension-plan-rule`	Sim	`end-date` do item da regra
Elegível, fora da regra, com `extension-plan: true`	Sim	`end-date` geral
Elegível, fora da regra, com `extension-plan` `false` ou ausente	Não	`end-date` geral
Não elegível (motivo diferente de `dismissal` ou tipo diferente de saúde/odonto)	Não	`end-date` geral, mesmo que o produto esteja na regra

Regras do campo:

Cada item exige product-id e end-date. O product-id é o mesmo devolvido nos benefícios do membro (Obter membro).
Um mesmo product-id não pode se repetir na lista. Se repetir, a requisição é recusada com 400 de coerção (ver Erros).
A validação de “data no passado” vale para o end-date geral. Informe no item da regra a data em que a extensão termina, normalmente posterior ao end-date geral.

Exemplo completo: demissão com extensão do plano de saúde

Cenário: um titular é demitido sem justa causa. Ele tem três benefícios primários ativos:

Produto	Tipo	`product-id`
Plano de saúde	`health-insurance`	`3fa85f64-5717-4562-b3fc-2c963f66afa6`
Plano odontológico	`dental-insurance`	`7c9e6679-7425-40de-944b-e07fc1f90ae7`
Seguro de vida	`life-insurance`	`9b2d3f1e-4c5a-4e8b-a1d2-6f7e8c9d0a1b`

O colaborador contribuía com o plano de saúde e optou por mantê-lo em extensão até 2025-12-31. O odontológico e o seguro de vida terminam junto com o desligamento.

curl -X POST "https://api.piposaude.com.br/v1/enrollment/exclusion/12345678909" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "exclusion-details": {
      "end-date": "2024-12-31",
      "exclusion-reason": "dismissal",
      "extension-plan": false,
      "extension-plan-rule": [
        { "product-id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "end-date": "2025-12-31" }
      ],
      "documents": [
        { "document-id": "e079e1ad-bdff-49e9-85f7-fbd228ca15fd", "document-type": "rescission" }
      ]
    }
  }'

Resultado, por benefício:

Produto	Extensão	Data de fim
Plano de saúde	Sim	`2025-12-31` (da regra)
Plano odontológico	Não	`2024-12-31` (geral)
Seguro de vida	Não (tipo não elegível)	`2024-12-31` (geral)

Para estender todos os benefícios elegíveis e ainda assim definir uma data própria para algum deles, envie extension-plan: true junto com a extension-plan-rule: os produtos listados usam a data da regra e os demais elegíveis usam o end-date geral.

Exemplos

Exclusão de benefícios primários

{
  "exclusion-details": {
    "end-date": "2024-12-31",
    "exclusion-reason": "dismissal",
    "extension-plan": false,
    "documents": [
      { "document-id": "e079e1ad-bdff-49e9-85f7-fbd228ca15fd", "document-type": "rescission" },
      { "document-id": "d9ff0205-76ca-4e6d-b8d5-ff9f85af3f99", "document-type": "birth-certificate-or-national-id" },
      { "document-id": "957ef952-8515-4dd6-b356-c1434a8e9f33", "document-type": "enrollment-request" }
    ]
  }
}

Exclusão como dependente de um titular

{
  "exclusion-details": {
    "end-date": "2024-12-31",
    "exclusion-reason": "requested-by-beneficiary",
    "extension-plan": false
  }
}

Exclusão de um benefício específico

{
  "exclusion-details": {
    "end-date": "2024-12-31",
    "exclusion-reason": "voluntary-dismissal",
    "extension-plan": false
  }
}

Exclusão de um benefício específico com plano de extensão específico

Demissão sem justa causa em que o benefício excluído (um plano de saúde) segue em extensão até 2025-12-31. O product-id da regra deve ser o produto do benefício informado em benefit-id; se não for, a regra não se aplica e o benefício termina no end-date geral.

{
  "exclusion-details": {
    "end-date": "2024-12-31",
    "exclusion-reason": "dismissal",
    "extension-plan": false,
    "extension-plan-rule": [
      { "product-id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "end-date": "2025-12-31" }
    ]
  }
}

Exclusão de benefício por produto

{
  "exclusion-details": {
    "end-date": "2024-12-31",
    "exclusion-reason": "dismissal",
    "extension-plan": false
  }
}

Resposta de sucesso (200):

{ "request-id": "ccc33333-e89b-12d3-a456-426614174008" }

Erros comuns

Status	Situação	Mensagem
`400`	`end-date` no passado (titular e benefício específico).	`End date cannot be in the past`
`400`	`end-date` no passado (produto).	`Exclusion not requested because end date cannot be in the past`
`400`	`exclusion-reason` = `other` sem `exclusion-reason-details` (dependente).	`Exclusion reason 'other' requires details`
`400`	`exclusion-reason` = `other` sem `exclusion-reason-details` (benefício específico e produto).	`Exclusion not requested because exclusion reason 'other' requires details`
`400`	Documentos não aceitáveis (titular).	`Exclusion not requested because provided documents are not acceptable`
`403`	Sem permissão (titular e benefício específico).	`Not entitled to modify this member`
`403`	Sem permissão (dependente).	`You are not authorized to exclude this member's benefits.`
`404`	Nenhum benefício primário ativo no membro.	`No active primary benefit found in member`
`404`	Nenhum benefício ativo como dependente do titular informado.	`No active benefits found in member as dependent of given primary-member`
`404`	Benefício não encontrado ativo no membro (benefício específico e produto).	`Benefit not found active in member`
`409`	Mais de um benefício ativo para o mesmo produto no escopo autorizado (produto).	`More than one active benefit found for product in authorized scope`
`424`	Membro ainda tem movimentações em andamento.	`Exclusion not performed. Member still has ongoing enrollments`
`424`	Benefício ainda tem movimentação em andamento (benefício específico).	`Exclusion not performed. Benefit still has ongoing enrollment`
`424`	Benefício ainda tem movimentação em andamento (produto).	`Exclusion not requested because benefit still has ongoing enrollment`

`400` — documentos não aceitáveis

Quando os documentos são rejeitados, a resposta devolve o exclusion-details enviado com offenses em dois níveis: no próprio exclusion-details e em cada documento problemático.

{
  "error": "Exclusion not requested because provided documents are not acceptable",
  "exclusion-details": {
    "end-date": "2024-12-31",
    "exclusion-reason": "dismissal",
    "extension-plan": false,
    "offenses": ["document-not-found", "document-invalid-format", "missing-document_exclusion-file"],
    "documents": [
      { "document-id": "e079e1ad-bdff-49e9-85f7-fbd228ca15fd", "document-type": "rescission" },
      { "document-id": "d9ff0205-76ca-4e6d-b8d5-ff9f85af3f99",
        "document-type": "birth-certificate-or-national-id",
        "offenses": ["document-invalid-format"] },
      { "document-id": "957ef952-8515-4dd6-b356-c1434a8e9f33",
        "document-type": "enrollment-request",
        "offenses": ["document-not-found"] }
    ]
  }
}

`424` — movimentações em andamento

O formato do 424 muda conforme o endpoint.

{
  "enrollment-ids": ["789e0123-e89b-12d3-a456-426614174002"],
  "error": "Exclusion not performed. Member still has ongoing enrollments"
}

{
  "enrollment-id": "789e0123-e89b-12d3-a456-426614174002",
  "error": "Exclusion not performed. Benefit still has ongoing enrollment"
}

{
  "enrollment-id": "789e0123-e89b-12d3-a456-426614174002",
  "error": "Exclusion not requested because benefit still has ongoing enrollment"
}

Detalhes de todos os códigos em Erros.

O parâmetro de query opcional auto-resolve-enrollments (approve ou reject) resolve a exclusão automaticamente. Esta opção existe apenas no ambiente de Homologação, para testes.

Começar

Guias

Referência

Escolhendo o endpoint

O corpo `exclusion-details`

Plano de extensão por produto

Exemplo completo: demissão com extensão do plano de saúde

Exemplos

Erros comuns

`400` — documentos não aceitáveis

`424` — movimentações em andamento

​Escolhendo o endpoint

​O corpo exclusion-details

​Plano de extensão por produto

​Exemplo completo: demissão com extensão do plano de saúde

​Exemplos

​Erros comuns

​400 — documentos não aceitáveis

​424 — movimentações em andamento

Escolhendo o endpoint

O corpo `exclusion-details`

Plano de extensão por produto

Exemplo completo: demissão com extensão do plano de saúde

Exemplos

Erros comuns

`400` — documentos não aceitáveis

`424` — movimentações em andamento