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

Incluir beneficiário (movimento I)

/v1/beneficiarios

**Inclusão** de uma vida (titular ou dependente) na operadora de destino. Equivale ao movimento `I` do contrato legado. Retorna **201 Created** com o `MovimentacaoResultado`, contendo o `protocolo` de rastreio e eventuais `criticas` de validação da operadora. O header `Location` aponta para o recurso criado quando a operadora devolve um identificador de imediato.

Headers

X-Cnpj-Provedorstringrequired

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

Request Body

application/jsonrequired

object

Dados de um beneficiário a incluir (titular ou dependente).

nomestringrequired
nomeAbreviadostring
cpfstringrequired
dataNascimentostringdaterequired
grauParentescostringrequired

0 = titular; demais valores = graus de parentesco.

estadoCivilstring
sexostring
nomeMaestring
rgstring
orgaoEmissorstring
dataExpedicaoRgstring
pisPasepstring
matriculaFuncionariostring
matriculaIziistring
dataAdesaostringdate
dataAdmissaostringdate
dataEventostringdate
enderecoobject
cepstring
logradourostring
numerostring
complementostring
bairrostring
municipiostring
codMunicipiostring
ufstring
contatoobject
emailstring
dddCelularstring
celularstring
dddTelefone1string
telefone1string
dadosBancariosobject
bancostring
agenciastring
digitoAgenciastring
contastring
digitoContastring
tipoContastring
produtoobject

Dados do plano/produto contratado.

contratostring
carteirinhastring
subContratostring
codigostring
codigoRDPstring
dataAlteracaoPlanostring
dataInicioContratostring
motivoAlteracaostring
apoliceobject
ciastring
numerostring
subfaturastring
tipoProdutostring

SAUDE, ODONTO ou VIDA.

Ver schema bruto / exemplo JSON
{
  "nome": "João dos Santos e Silva",
  "cpf": "35999999960",
  "dataNascimento": "1990-05-21",
  "grauParentesco": "0",
  "estadoCivil": "S",
  "sexo": "M",
  "dataAdesao": "2026-04-19",
  "dataAdmissao": "2026-01-15",
  "endereco": {
    "cep": "01310100",
    "logradouro": "Av. Paulista",
    "numero": "1000",
    "bairro": "Bela Vista",
    "municipio": "São Paulo",
    "uf": "SP"
  },
  "contato": {
    "email": "joao@empresa.com",
    "dddCelular": "11",
    "celular": "999999999"
  },
  "produto": {
    "contrato": "1234",
    "codigo": "PLAN-001"
  },
  "apolice": {
    "cia": "570",
    "numero": "123456789"
  },
  "tipoProduto": "SAUDE"
}

Responses

201

Inclusã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.

nomestring
cpfstring
numeroCarteirinhastring
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.

400

Requisição malformada (campos obrigatórios ausentes/ inválidos).

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

A operadora rejeitou a movimentação por uma regra de negócio (ex. "CPF inválido", "Beneficiário inativo", "Fora da vigência"). Os detalhes vêm em `criticas` / `validacoes`.

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.

nomestring
cpfstring
numeroCarteirinhastring
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.