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 **HTTP 200** com o `MovimentacaoResultado`: guarde o `protocolo` (rastreio em `GET /v1/movimentacoes/{protocolo}`) e o `beneficiario.matriculaProvedor` (necessário para a exclusão). **Regras verificadas em homologação SulAmérica (16/07/2026):** - `dadosBancarios` é obrigatório na prática (ausente = erro 500 do Orquestrador). - `nomeAbreviado` deve ser **igual** a `nome` (senão crítica A1079). - `nome` **sem acentos** (senão crítica A1034). - CPF já cadastrado retorna crítica A041. - O example `titular` abaixo é um payload real executado com sucesso (protocolo 2190831).
Headers
X-Cnpj-Provedorstringrequired
CNPJ da operadora de destino, atua como **chave de roteamento** (padrão Mediator). Ex.: SulAmérica `01685053000156`.
ex: 01685053000156Request Body
application/jsonrequired
Dados de um beneficiário a incluir (titular ou dependente). **Obrigatórios na prática (SulAmérica homolog, verificado em 16/07/2026):** `nome` (sem acentos), `nomeAbreviado` (igual a `nome`), `cpf`, `matricula`, `matriculaFuncionario`, `dataNascimento`, `grauParentesco`, `estadoCivil`, `sexo`, `nomeMae`, `pis`, `cns`, `dataAdesao`, `dataAdmissao`, `dataEvento`, `dataVigencia`, `local`, `codigoSegurado`, `certificado`, `endereco`, `contato`, `dadosBancarios`, `produto` (com `subContrato`), `apolice`, `tipoProduto`. Use o example como base.
Sem acentos (crítica A1034).
Deve ser IGUAL a `nome` (crítica A1079).
Matrícula do beneficiário na empresa (obrigatória na prática).
0 = titular; demais valores = graus de parentesco.
PIS (campo aceito pelo backend; verificado ao vivo).
Constava no contrato legado; não validado. Prefira `pis`.
Cartão Nacional de Saúde.
Início de vigência (obrigatória na prática).
Código do local (obrigatório na prática; ex. 1).
OBRIGATÓRIO na prática (ausente = erro 500 do Orquestrador).
Dados do plano/produto contratado.
SAUDE, ODONTO ou VIDA.
Ver schema bruto / exemplo JSON
{
"nome": "Teste Marcos Fluxo",
"nomeAbreviado": "Teste Marcos Fluxo",
"cpf": "36442421430",
"matricula": "7700",
"matriculaFuncionario": "7700",
"dataNascimento": "1990-01-01",
"grauParentesco": "0",
"estadoCivil": "S",
"sexo": "M",
"nomeMae": "Mae Teste",
"pis": "12056412300",
"cns": "700000000000000",
"dataAdesao": "2026-04-19",
"dataAdmissao": "2026-01-15",
"dataEvento": "2026-04-19",
"dataVigencia": "2026-04-19",
"local": 1,
"codigoSegurado": "1",
"certificado": "1",
"endereco": {
"cep": "01310100",
"logradouro": "Av Paulista",
"numero": "1000",
"bairro": "Bela Vista",
"municipio": "Sao Paulo",
"uf": "SP"
},
"contato": {
"email": "teste@mds.com",
"dddCelular": "11",
"celular": "999999999"
},
"dadosBancarios": {
"banco": "001",
"agencia": "1234",
"digitoAgencia": "5",
"conta": "567890",
"digitoConta": "1",
"digito": "1",
"tipoConta": "1"
},
"produto": {
"contrato": "78043",
"subContrato": "8UV4F",
"codigo": "66181"
},
"apolice": {
"cia": "570",
"numero": "78043"
},
"tipoProduto": "SAUDE"
}Responses
Inclusão registrada / enviada à operadora (o processamento definitivo é assíncrono; acompanhe pelo `protocolo`).
Retorno padronizado de uma operação de escrita (`ResponseBaseSuccess`). Consolida o resultado, validações de negócio e dados de auditoria.
Código HTTP resultante do processamento na operadora.
Protocolo de rastreio gerado pela operadora.
Resumo do beneficiário afetado. Campos conforme respostas reais capturadas em 16/07/2026; cada operação popula um subconjunto.
Igual ao `protocolo`.
INCLUSAO, EXCLUSAO, ...
Emitida quando a movimentação é liberada pela operadora.
Matrícula na operadora. GUARDE (exigida na exclusão como `matriculaEmpresa`).
Validações/avisos retornados pela operadora.
items
Erros críticos de regra de negócio.
items
Crítica/erro de validação devolvido pela operadora.
URI exata da operadora chamada (auditoria).
Payload exato enviado à operadora (auditoria/troubleshooting).
Retorno cru (raw) devolvido pela API da operadora.
Ver schema bruto / exemplo JSON
{
"status": 200,
"protocolo": "2190831",
"statusMovimentacao": "1",
"beneficiario": {
"codigoMovimentacao": "2190831",
"tipoMovimentacao": "INCLUSAO",
"cpf": "36442421430",
"matriculaProvedor": "484229630",
"sequencial": "01",
"status": "1"
}
}Requisição malformada (campos obrigatórios ausentes/ inválidos).
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica/erro de validação devolvido pela operadora.
Token ausente, expirado ou inválido.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica/erro de validação devolvido pela operadora.
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`.
Retorno padronizado de uma operação de escrita (`ResponseBaseSuccess`). Consolida o resultado, validações de negócio e dados de auditoria.
Código HTTP resultante do processamento na operadora.
Protocolo de rastreio gerado pela operadora.
Resumo do beneficiário afetado. Campos conforme respostas reais capturadas em 16/07/2026; cada operação popula um subconjunto.
Igual ao `protocolo`.
INCLUSAO, EXCLUSAO, ...
Emitida quando a movimentação é liberada pela operadora.
Matrícula na operadora. GUARDE (exigida na exclusão como `matriculaEmpresa`).
Validações/avisos retornados pela operadora.
items
Erros críticos de regra de negócio.
items
Crítica/erro de validação devolvido pela operadora.
URI exata da operadora chamada (auditoria).
Payload exato enviado à operadora (auditoria/troubleshooting).
Retorno cru (raw) devolvido pela API da operadora.
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 **HTTP 200** com o `MovimentacaoResultado`: guarde o `protocolo` (rastreio em `GET /v1/movimentacoes/{protocolo}`) e o `beneficiario.matriculaProvedor` (necessário para a exclusão). **Regras verificadas em homologação SulAmérica (16/07/2026):** - `dadosBancarios` é obrigatório na prática (ausente = erro 500 do Orquestrador). - `nomeAbreviado` deve ser **igual** a `nome` (senão crítica A1079). - `nome` **sem acentos** (senão crítica A1034). - CPF já cadastrado retorna crítica A041. - O example `titular` abaixo é um payload real executado com sucesso (protocolo 2190831).
Headers
X-Cnpj-Provedorstringrequired
CNPJ da operadora de destino, atua como **chave de roteamento** (padrão Mediator). Ex.: SulAmérica `01685053000156`.
ex: 01685053000156Request Body
application/jsonrequired
Dados de um beneficiário a incluir (titular ou dependente). **Obrigatórios na prática (SulAmérica homolog, verificado em 16/07/2026):** `nome` (sem acentos), `nomeAbreviado` (igual a `nome`), `cpf`, `matricula`, `matriculaFuncionario`, `dataNascimento`, `grauParentesco`, `estadoCivil`, `sexo`, `nomeMae`, `pis`, `cns`, `dataAdesao`, `dataAdmissao`, `dataEvento`, `dataVigencia`, `local`, `codigoSegurado`, `certificado`, `endereco`, `contato`, `dadosBancarios`, `produto` (com `subContrato`), `apolice`, `tipoProduto`. Use o example como base.
Sem acentos (crítica A1034).
Deve ser IGUAL a `nome` (crítica A1079).
Matrícula do beneficiário na empresa (obrigatória na prática).
0 = titular; demais valores = graus de parentesco.
PIS (campo aceito pelo backend; verificado ao vivo).
Constava no contrato legado; não validado. Prefira `pis`.
Cartão Nacional de Saúde.
Início de vigência (obrigatória na prática).
Código do local (obrigatório na prática; ex. 1).
OBRIGATÓRIO na prática (ausente = erro 500 do Orquestrador).
Dados do plano/produto contratado.
SAUDE, ODONTO ou VIDA.
Ver schema bruto / exemplo JSON
{
"nome": "Teste Marcos Fluxo",
"nomeAbreviado": "Teste Marcos Fluxo",
"cpf": "36442421430",
"matricula": "7700",
"matriculaFuncionario": "7700",
"dataNascimento": "1990-01-01",
"grauParentesco": "0",
"estadoCivil": "S",
"sexo": "M",
"nomeMae": "Mae Teste",
"pis": "12056412300",
"cns": "700000000000000",
"dataAdesao": "2026-04-19",
"dataAdmissao": "2026-01-15",
"dataEvento": "2026-04-19",
"dataVigencia": "2026-04-19",
"local": 1,
"codigoSegurado": "1",
"certificado": "1",
"endereco": {
"cep": "01310100",
"logradouro": "Av Paulista",
"numero": "1000",
"bairro": "Bela Vista",
"municipio": "Sao Paulo",
"uf": "SP"
},
"contato": {
"email": "teste@mds.com",
"dddCelular": "11",
"celular": "999999999"
},
"dadosBancarios": {
"banco": "001",
"agencia": "1234",
"digitoAgencia": "5",
"conta": "567890",
"digitoConta": "1",
"digito": "1",
"tipoConta": "1"
},
"produto": {
"contrato": "78043",
"subContrato": "8UV4F",
"codigo": "66181"
},
"apolice": {
"cia": "570",
"numero": "78043"
},
"tipoProduto": "SAUDE"
}Responses
Inclusão registrada / enviada à operadora (o processamento definitivo é assíncrono; acompanhe pelo `protocolo`).
Retorno padronizado de uma operação de escrita (`ResponseBaseSuccess`). Consolida o resultado, validações de negócio e dados de auditoria.
Código HTTP resultante do processamento na operadora.
Protocolo de rastreio gerado pela operadora.
Resumo do beneficiário afetado. Campos conforme respostas reais capturadas em 16/07/2026; cada operação popula um subconjunto.
Igual ao `protocolo`.
INCLUSAO, EXCLUSAO, ...
Emitida quando a movimentação é liberada pela operadora.
Matrícula na operadora. GUARDE (exigida na exclusão como `matriculaEmpresa`).
Validações/avisos retornados pela operadora.
items
Erros críticos de regra de negócio.
items
Crítica/erro de validação devolvido pela operadora.
URI exata da operadora chamada (auditoria).
Payload exato enviado à operadora (auditoria/troubleshooting).
Retorno cru (raw) devolvido pela API da operadora.
Ver schema bruto / exemplo JSON
{
"status": 200,
"protocolo": "2190831",
"statusMovimentacao": "1",
"beneficiario": {
"codigoMovimentacao": "2190831",
"tipoMovimentacao": "INCLUSAO",
"cpf": "36442421430",
"matriculaProvedor": "484229630",
"sequencial": "01",
"status": "1"
}
}Requisição malformada (campos obrigatórios ausentes/ inválidos).
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica/erro de validação devolvido pela operadora.
Token ausente, expirado ou inválido.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica/erro de validação devolvido pela operadora.
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`.
Retorno padronizado de uma operação de escrita (`ResponseBaseSuccess`). Consolida o resultado, validações de negócio e dados de auditoria.
Código HTTP resultante do processamento na operadora.
Protocolo de rastreio gerado pela operadora.
Resumo do beneficiário afetado. Campos conforme respostas reais capturadas em 16/07/2026; cada operação popula um subconjunto.
Igual ao `protocolo`.
INCLUSAO, EXCLUSAO, ...
Emitida quando a movimentação é liberada pela operadora.
Matrícula na operadora. GUARDE (exigida na exclusão como `matriculaEmpresa`).
Validações/avisos retornados pela operadora.
items
Erros críticos de regra de negócio.
items
Crítica/erro de validação devolvido pela operadora.
URI exata da operadora chamada (auditoria).
Payload exato enviado à operadora (auditoria/troubleshooting).
Retorno cru (raw) devolvido pela API da operadora.