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}`

O corpo `exclusion-details`

Todos os três 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	Sim	Indica se o membro contribuiu com os custos e solicitou plano de extensão.
`exclusion-reason-details`	string	Condicional	Obrigatório quando `exclusion-reason` = `other`.
`documents`	array	Não	Documentos (`document-id` + `document-type`) previamente enviados.

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": true
  }
}

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`	`exclusion-reason` = `other` sem `exclusion-reason-details` (dependente).	`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.	`Benefit not found active in member`
`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.	`Exclusion not performed. 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"
}

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`

Exemplos

Erros comuns

`400` — documentos não aceitáveis

`424` — movimentações em andamento

​Escolhendo o endpoint

​O corpo exclusion-details

​Exemplos

​Erros comuns

​400 — documentos não aceitáveis

​424 — movimentações em andamento

Escolhendo o endpoint

O corpo `exclusion-details`

Exemplos

Erros comuns

`400` — documentos não aceitáveis

`424` — movimentações em andamento