> ## Documentation Index
> Fetch the complete documentation index at: https://docs.piposaude.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Como fazer uma exclusão

> Excluir benefícios de um membro: primários, como dependente, ou um benefício específico.

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.

<Callout icon="megaphone" color="#3370D1">
  Toda chamada exige o header `Authorization: Bearer <access-token>` (ver [Autenticação](/docs/comecar/autenticacao)).
  Datas em ISO 8601 e campos em kebab-case (ver [Convenções](/docs/comecar/convencoes)).
</Callout>

## 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

<AccordionGroup>
  <Accordion title="Exclusão de benefícios primários">
    ```json theme={null}
    {
      "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" }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="Exclusão como dependente de um titular">
    ```json theme={null}
    {
      "exclusion-details": {
        "end-date": "2024-12-31",
        "exclusion-reason": "requested-by-beneficiary",
        "extension-plan": false
      }
    }
    ```
  </Accordion>

  <Accordion title="Exclusão de um benefício específico">
    ```json theme={null}
    {
      "exclusion-details": {
        "end-date": "2024-12-31",
        "exclusion-reason": "voluntary-dismissal",
        "extension-plan": true
      }
    }
    ```
  </Accordion>
</AccordionGroup>

Resposta de sucesso (`200`):

```json theme={null}
{ "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.

```json theme={null}
{
  "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**.

<CodeGroup>
  ```json Titular e dependente theme={null}
  {
    "enrollment-ids": ["789e0123-e89b-12d3-a456-426614174002"],
    "error": "Exclusion not performed. Member still has ongoing enrollments"
  }
  ```

  ```json Benefício específico theme={null}
  {
    "enrollment-id": "789e0123-e89b-12d3-a456-426614174002",
    "error": "Exclusion not performed. Benefit still has ongoing enrollment"
  }
  ```
</CodeGroup>

Detalhes de todos os códigos em [Erros](/docs/referencia/error-handling/erros).

<Info>
  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.**
</Info>