/IZII MDS — Orquestrador de Benefícios (REST)

delete

Excluir beneficiário (movimento E)

/v1/beneficiarios/{id}

**Exclusão** da vida na operadora de destino. Equivale ao movimento `E`. Os campos da exclusão vão no **corpo** (objeto `exclusao` do Orquestrador). **Regras verificadas em homologação SulAmérica (16/07/2026, protocolo real 2190832):** - `matriculaEmpresa` = o `beneficiario.matriculaProvedor` retornado na **inclusão** (guarde-o). - `dataExclusao` deve ser uma **data de corte permitida** pela operadora; data inválida retorna a crítica **M21001** listando as datas aceitas. - O example abaixo é um payload real executado com sucesso.

Path Parameters

idstringrequired

**CPF** do beneficiário (é o único identificador aplicado pelo backend nas rotas por id; verificado ao vivo).

ex: 36442421430

Headers

X-Cnpj-Provedorstringrequired

CNPJ da operadora de destino, atua como **chave de roteamento** (padrão Mediator). Ex.: SulAmérica `01685053000156`.

ex: 01685053000156

Request Body

application/jsonrequired

object

motivoExclusaostringrequired

dataExclusaostringdaterequired

matriculaEmpresastring

codigoRDPstring

tipoProdutostring

flagContributarioboolean

produtoobject

contratostring

subContratostring

codigostring

Ver schema bruto / exemplo JSON

{
  "motivoExclusao": "1",
  "dataExclusao": "2026-07-19",
  "matriculaEmpresa": "484228150",
  "codigoRDP": "01",
  "tipoProduto": "SAUDE",
  "flagContributario": false,
  "produto": {
    "contrato": "78043",
    "subContrato": "8UV4F",
    "codigo": "66181"
  }
}

Responses

200

Exclusão registrada / enviada à operadora.

object

Retorno padronizado de uma operação de escrita (`ResponseBaseSuccess`). Consolida o resultado, validações de negócio e dados de auditoria.

statusinteger

Código HTTP resultante do processamento na operadora.

protocolostring

Protocolo de rastreio gerado pela operadora.

statusMovimentacaostring

beneficiarioobject

Resumo do beneficiário afetado. Campos conforme respostas reais capturadas em 16/07/2026; cada operação popula um subconjunto.

codigostring

codigoMovimentacaostring

Igual ao `protocolo`.

tipoMovimentacaostring

INCLUSAO, EXCLUSAO, ...

cpfstring

carteirinhastring

Emitida quando a movimentação é liberada pela operadora.

matriculaFuncionariostring

matriculaFamiliastring

matriculaProvedorstring

Matrícula na operadora. GUARDE (exigida na exclusão como `matriculaEmpresa`).

sequencialstring

statusstring

nomestring

descricaostring

codigoBeneficiarioNoProvedorstring

validacoesarray

Validações/avisos retornados pela operadora.

items

object

nomeBeneficiariostring

matriculaFuncionariostring

sequencialinteger

codigostring

mensagemstring

criticasarray

Erros críticos de regra de negócio.

items

object

Crítica/erro de validação devolvido pela operadora.

codigostring

campostring

mensagemstring

requestURIstring

URI exata da operadora chamada (auditoria).

requestJsonobject

Payload exato enviado à operadora (auditoria/troubleshooting).

responseContentobject

Retorno cru (raw) devolvido pela API da operadora.

Ver schema bruto / exemplo JSON

{
  "status": 200,
  "protocolo": "2190832",
  "beneficiario": {
    "codigoMovimentacao": "2190832",
    "tipoMovimentacao": "EXCLUSAO"
  }
}

401

Token ausente, expirado ou inválido.

object

Estrutura padronizada de erro.

statusinteger

Código HTTP do erro.

codigostring

Código interno do erro.

mensagemstring

Descrição legível do erro.

criticasarray

items

object

Crítica/erro de validação devolvido pela operadora.

codigostring

campostring

mensagemstring

404

Recurso não encontrado.

object

Estrutura padronizada de erro.

statusinteger

Código HTTP do erro.

codigostring

Código interno do erro.

mensagemstring

Descrição legível do erro.

criticasarray

items

object

Crítica/erro de validação devolvido pela operadora.

codigostring

campostring

mensagemstring

422

Rejeição por regra de negócio da operadora; detalhes em `criticas`.

object

Retorno padronizado de uma operação de escrita (`ResponseBaseSuccess`). Consolida o resultado, validações de negócio e dados de auditoria.

statusinteger

Código HTTP resultante do processamento na operadora.

protocolostring

Protocolo de rastreio gerado pela operadora.

statusMovimentacaostring

beneficiarioobject

Resumo do beneficiário afetado. Campos conforme respostas reais capturadas em 16/07/2026; cada operação popula um subconjunto.

codigostring

codigoMovimentacaostring

Igual ao `protocolo`.

tipoMovimentacaostring

INCLUSAO, EXCLUSAO, ...

cpfstring

carteirinhastring

Emitida quando a movimentação é liberada pela operadora.

matriculaFuncionariostring

matriculaFamiliastring

matriculaProvedorstring

Matrícula na operadora. GUARDE (exigida na exclusão como `matriculaEmpresa`).

sequencialstring

statusstring

nomestring

descricaostring

codigoBeneficiarioNoProvedorstring

validacoesarray

Validações/avisos retornados pela operadora.

items

object

nomeBeneficiariostring

matriculaFuncionariostring

sequencialinteger

codigostring

mensagemstring

criticasarray

Erros críticos de regra de negócio.

items

object

Crítica/erro de validação devolvido pela operadora.

codigostring

campostring

mensagemstring

requestURIstring

URI exata da operadora chamada (auditoria).

requestJsonobject

Payload exato enviado à operadora (auditoria/troubleshooting).

responseContentobject

Retorno cru (raw) devolvido pela API da operadora.

Ver schema bruto / exemplo JSON

{
  "status": 400,
  "criticas": [
    {
      "codigo": "M21001",
      "mensagem": "Data Exclusão Inválida. Datas de exclusões permitidas: [2026-07-19]"
    }
  ]
}

delete

Excluir beneficiário (movimento E)

/v1/beneficiarios/{id}

Path Parameters

idstringrequired

**CPF** do beneficiário (é o único identificador aplicado pelo backend nas rotas por id; verificado ao vivo).

ex: 36442421430

Headers

X-Cnpj-Provedorstringrequired

CNPJ da operadora de destino, atua como **chave de roteamento** (padrão Mediator). Ex.: SulAmérica `01685053000156`.

ex: 01685053000156

Request Body

application/jsonrequired

object

motivoExclusaostringrequired

dataExclusaostringdaterequired

matriculaEmpresastring

codigoRDPstring

tipoProdutostring

flagContributarioboolean

produtoobject

contratostring

subContratostring

codigostring

Ver schema bruto / exemplo JSON

{
  "motivoExclusao": "1",
  "dataExclusao": "2026-07-19",
  "matriculaEmpresa": "484228150",
  "codigoRDP": "01",
  "tipoProduto": "SAUDE",
  "flagContributario": false,
  "produto": {
    "contrato": "78043",
    "subContrato": "8UV4F",
    "codigo": "66181"
  }
}

Responses

200

Exclusão registrada / enviada à operadora.

object

Retorno padronizado de uma operação de escrita (`ResponseBaseSuccess`). Consolida o resultado, validações de negócio e dados de auditoria.

statusinteger

Código HTTP resultante do processamento na operadora.

protocolostring

Protocolo de rastreio gerado pela operadora.

statusMovimentacaostring

beneficiarioobject

Resumo do beneficiário afetado. Campos conforme respostas reais capturadas em 16/07/2026; cada operação popula um subconjunto.

codigostring

codigoMovimentacaostring

Igual ao `protocolo`.

tipoMovimentacaostring

INCLUSAO, EXCLUSAO, ...

cpfstring

carteirinhastring

Emitida quando a movimentação é liberada pela operadora.

matriculaFuncionariostring

matriculaFamiliastring

matriculaProvedorstring

Matrícula na operadora. GUARDE (exigida na exclusão como `matriculaEmpresa`).

sequencialstring

statusstring

nomestring

descricaostring

codigoBeneficiarioNoProvedorstring

validacoesarray

Validações/avisos retornados pela operadora.

items

object

nomeBeneficiariostring

matriculaFuncionariostring

sequencialinteger

codigostring

mensagemstring

criticasarray

Erros críticos de regra de negócio.

items

object

Crítica/erro de validação devolvido pela operadora.

codigostring

campostring

mensagemstring

requestURIstring

URI exata da operadora chamada (auditoria).

requestJsonobject

Payload exato enviado à operadora (auditoria/troubleshooting).

responseContentobject

Retorno cru (raw) devolvido pela API da operadora.

Ver schema bruto / exemplo JSON

{
  "status": 200,
  "protocolo": "2190832",
  "beneficiario": {
    "codigoMovimentacao": "2190832",
    "tipoMovimentacao": "EXCLUSAO"
  }
}

401

Token ausente, expirado ou inválido.

object

Estrutura padronizada de erro.

statusinteger

Código HTTP do erro.

codigostring

Código interno do erro.

mensagemstring

Descrição legível do erro.

criticasarray

items

object

Crítica/erro de validação devolvido pela operadora.

codigostring

campostring

mensagemstring

404

Recurso não encontrado.

object

Estrutura padronizada de erro.

statusinteger

Código HTTP do erro.

codigostring

Código interno do erro.

mensagemstring

Descrição legível do erro.

criticasarray

items

object

Crítica/erro de validação devolvido pela operadora.

codigostring

campostring

mensagemstring

422

Rejeição por regra de negócio da operadora; detalhes em `criticas`.

object

Retorno padronizado de uma operação de escrita (`ResponseBaseSuccess`). Consolida o resultado, validações de negócio e dados de auditoria.

statusinteger

Código HTTP resultante do processamento na operadora.

protocolostring

Protocolo de rastreio gerado pela operadora.

statusMovimentacaostring

beneficiarioobject

Resumo do beneficiário afetado. Campos conforme respostas reais capturadas em 16/07/2026; cada operação popula um subconjunto.

codigostring

codigoMovimentacaostring

Igual ao `protocolo`.

tipoMovimentacaostring

INCLUSAO, EXCLUSAO, ...

cpfstring

carteirinhastring

Emitida quando a movimentação é liberada pela operadora.

matriculaFuncionariostring

matriculaFamiliastring

matriculaProvedorstring

Matrícula na operadora. GUARDE (exigida na exclusão como `matriculaEmpresa`).

sequencialstring

statusstring

nomestring

descricaostring

codigoBeneficiarioNoProvedorstring

validacoesarray

Validações/avisos retornados pela operadora.

items

object

nomeBeneficiariostring

matriculaFuncionariostring

sequencialinteger

codigostring

mensagemstring

criticasarray

Erros críticos de regra de negócio.

items

object

Crítica/erro de validação devolvido pela operadora.

codigostring

campostring

mensagemstring

requestURIstring

URI exata da operadora chamada (auditoria).

requestJsonobject

Payload exato enviado à operadora (auditoria/troubleshooting).

responseContentobject

Retorno cru (raw) devolvido pela API da operadora.

Ver schema bruto / exemplo JSON

{
  "status": 400,
  "criticas": [
    {
      "codigo": "M21001",
      "mensagem": "Data Exclusão Inválida. Datas de exclusões permitidas: [2026-07-19]"
    }
  ]
}