Alterar beneficiário (movimento A)
/v1/beneficiarios/{cpf}Alteração de dados cadastrais (movimento A).
Envie o cadastro completo, não apenas os campos alterados. Apesar do verbo PATCH, a operadora trata a movimentação como substituição: payload sem endereco, contato, dadosBancarios, produto e apolice não é processado. Monte o corpo a partir dos dados atuais da vida e altere o que precisa.
A alteração se desdobra em mais de uma operação na operadora, então a resposta pode repetir o mesmo código de crítica, um por bloco alterado.
Valide o fluxo em homologação antes de usar em produção.
Path Parameters
cpfstringrequired
CPF do beneficiário (é o único valor aceito nas rotas por id).
Em consulta ele é o filtro de busca. Em escrita (PATCH/DELETE) ele NÃO identifica a vida na SulAmérica: quem identifica é a matriculaOperadora do corpo. Aqui ele apenas preenche o campo cpf da operação quando o corpo não o traz; se o corpo trouxer, o corpo prevalece.
Não aceita protocolo nem matrícula. Para consultar pelo protocolo da movimentação use GET /v1/movimentacoes/{protocolo}.
ex: 36442421430Headers
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
Cadastro da vida para a alteração. Envie o cadastro completo, não só os campos modificados (ver a descrição da operação). login/senha (opcionais): credencial do Portal Empresa do estipulante; nunca ecoados.
CPF do beneficiário, tratado como dado cadastral, não como chave de busca: quem identifica a vida na SulAmérica é a matriculaOperadora.
Para alterar o CPF, envie aqui o valor novo: o corpo prevalece sobre o {id} da rota. Omitido, assume o {id} da rota.
Local de rateio (somente SulAmérica).
Matrícula do beneficiário na operadora, obrigatória na alteração (sem ela a resposta é a crítica A02003). É o mesmo valor exigido na exclusão como matriculaEmpresa: a matriculaProvedor da inclusão, que nas consultas aparece em matriculaFamilia.
Sem acentos (crítica A1046, com sugestão em A1080).
M ou F.
S, C, V, D ou O.
0=Titular, 1=Cônjuge, ...
Dados do plano/produto contratado.
Ver schema bruto / exemplo JSON
{
"matriculaOperadora": "484229630",
"dataEvento": "2026-06-10",
"nome": "TESTE BENEFICIARIO UM",
"nomeAbreviado": "TESTE BENEFICIARIO UM",
"dataNascimento": "1990-01-01",
"sexo": "M",
"estadoCivil": "S",
"grauParentesco": "0",
"nomeMae": "Mae Teste",
"endereco": {
"cep": "04567000",
"logradouro": "Rua Nova",
"numero": "55",
"bairro": "Bela Vista",
"municipio": "Sao Paulo",
"uf": "SP"
},
"contato": {
"email": "joao.novo@empresa.com",
"dddCelular": "11",
"celular": "988887777"
},
"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
Alteração processada.
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. Estes campos são repassados como a operadora os envia: quais vêm preenchidos, e com que valor, é decisão dela e pode variar por operadora e por operação.
Igual ao protocolo.
INCLUSAO, EXCLUSAO, ...
Emitida quando a movimentação é liberada pela operadora.
Matrícula da família na operadora. Comportamento observado na SulAmérica (homologação): nas respostas de consulta é aqui que vem o valor exigido na exclusão como matriculaEmpresa.
Matrícula na operadora, exigida na exclusão como matriculaEmpresa. GUARDE o valor devolvido na inclusão. Comportamento observado na SulAmérica (homologação): nas consultas este campo volta nulo e o mesmo valor aparece em matriculaFamilia.
Um item por vida enviada, na inclusão (o único movimento que aceita várias vidas). Cada entrada traz o codigoMovimentacao (protocolo) daquela vida.
Vem vazia em consulta, alteração e exclusão, que movimentam uma vida só.
protocolo e beneficiario no topo seguem apontando para a primeira vida, por compatibilidade. Em lote, use esta lista.
Vem vazia em consulta.
items
Validações retornadas pela operadora (wrappers). A mensagem do wrapper marca a severidade das críticas internas: "Critica Bloqueante" (rejeição) ou "Critica Não Bloqueante" (aviso; a movimentação segue o fluxo).
items
items
Erros críticos de regra de negócio.
items
Crítica de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
URI exata da operadora chamada (auditoria).
Eco do payload enviado à operadora (auditoria/troubleshooting), com credenciais sempre mascaradas (***); login/senha nunca são ecoados.
Retorno cru (raw) devolvido pela API da operadora.
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 de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
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 de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
Corpo da requisição acima do limite aceito pela fachada: 1 MB nas rotas de dados, 12 MB em POST /v1/faturas/interpretacoes, que recebe o PDF em base64.
Não há limite de ITENS no lote: o teto é de bytes, e existe para que um corpo gigante não derrube o processo. Lote grande que estoure o limite deve ser dividido em requisições; cada uma é independente na operadora.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
Não foi possível concluir a operação junto à operadora.
Em consulta, sem repetir no corpo a falha pode ser transitória e nova tentativa é segura.
Em escrita (POST, PATCH, DELETE) o corpo traz repetir: false, e o desfecho é indeterminado: a operadora pode ter processado e só a resposta ter se perdido. Não reenvie. Se o corpo trouxer protocolo, consulte-o em GET /v1/movimentacoes/{protocolo}; se não, confira o beneficiário pelo CPF antes de tentar de novo.
Erro gerado pela própria API, antes ou depois de falar com a operadora. Formato distinto do Erro, que é usado quando o desfecho vem da operadora.
Motivo resumido.
Detalhe técnico, quando existe.
Quando false, não reenvie. Em consulta significa que repetir devolve o mesmo resultado; em escrita significa que o desfecho é indeterminado, porque a operadora pode ter processado e só a resposta ter se perdido. Ausente quando a falha pode ser transitória, o que só ocorre em consulta.
Protocolo da movimentação, quando a operadora devolveu um antes de falhar. **Em escrita com 502, consulte este protocolo em GET /v1/movimentacoes/{protocolo} em vez de reenviar.**
Caminho chamado na operadora, sem host. Para diagnóstico.
Resposta da operadora, para diagnóstico. Formato variável.
Outro status de transporte, repassado do provedor como veio (ex. 403, 404, 409, 429). A fachada não os traduz: mascará-los de 400 esconderia do consumidor a diferença entre pedido inválido e limite de uso, por exemplo.
Não são desfecho de negócio. Rejeição da operadora chega em HTTP 200 com criticas; ausência de registro também é 200. Um status aqui indica problema de integração, não de cadastro, e vale acionar o suporte.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
Alterar beneficiário (movimento A)
/v1/beneficiarios/{cpf}Alteração de dados cadastrais (movimento A).
Envie o cadastro completo, não apenas os campos alterados. Apesar do verbo PATCH, a operadora trata a movimentação como substituição: payload sem endereco, contato, dadosBancarios, produto e apolice não é processado. Monte o corpo a partir dos dados atuais da vida e altere o que precisa.
A alteração se desdobra em mais de uma operação na operadora, então a resposta pode repetir o mesmo código de crítica, um por bloco alterado.
Valide o fluxo em homologação antes de usar em produção.
Path Parameters
cpfstringrequired
CPF do beneficiário (é o único valor aceito nas rotas por id).
Em consulta ele é o filtro de busca. Em escrita (PATCH/DELETE) ele NÃO identifica a vida na SulAmérica: quem identifica é a matriculaOperadora do corpo. Aqui ele apenas preenche o campo cpf da operação quando o corpo não o traz; se o corpo trouxer, o corpo prevalece.
Não aceita protocolo nem matrícula. Para consultar pelo protocolo da movimentação use GET /v1/movimentacoes/{protocolo}.
ex: 36442421430Headers
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
Cadastro da vida para a alteração. Envie o cadastro completo, não só os campos modificados (ver a descrição da operação). login/senha (opcionais): credencial do Portal Empresa do estipulante; nunca ecoados.
CPF do beneficiário, tratado como dado cadastral, não como chave de busca: quem identifica a vida na SulAmérica é a matriculaOperadora.
Para alterar o CPF, envie aqui o valor novo: o corpo prevalece sobre o {id} da rota. Omitido, assume o {id} da rota.
Local de rateio (somente SulAmérica).
Matrícula do beneficiário na operadora, obrigatória na alteração (sem ela a resposta é a crítica A02003). É o mesmo valor exigido na exclusão como matriculaEmpresa: a matriculaProvedor da inclusão, que nas consultas aparece em matriculaFamilia.
Sem acentos (crítica A1046, com sugestão em A1080).
M ou F.
S, C, V, D ou O.
0=Titular, 1=Cônjuge, ...
Dados do plano/produto contratado.
Ver schema bruto / exemplo JSON
{
"matriculaOperadora": "484229630",
"dataEvento": "2026-06-10",
"nome": "TESTE BENEFICIARIO UM",
"nomeAbreviado": "TESTE BENEFICIARIO UM",
"dataNascimento": "1990-01-01",
"sexo": "M",
"estadoCivil": "S",
"grauParentesco": "0",
"nomeMae": "Mae Teste",
"endereco": {
"cep": "04567000",
"logradouro": "Rua Nova",
"numero": "55",
"bairro": "Bela Vista",
"municipio": "Sao Paulo",
"uf": "SP"
},
"contato": {
"email": "joao.novo@empresa.com",
"dddCelular": "11",
"celular": "988887777"
},
"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
Alteração processada.
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. Estes campos são repassados como a operadora os envia: quais vêm preenchidos, e com que valor, é decisão dela e pode variar por operadora e por operação.
Igual ao protocolo.
INCLUSAO, EXCLUSAO, ...
Emitida quando a movimentação é liberada pela operadora.
Matrícula da família na operadora. Comportamento observado na SulAmérica (homologação): nas respostas de consulta é aqui que vem o valor exigido na exclusão como matriculaEmpresa.
Matrícula na operadora, exigida na exclusão como matriculaEmpresa. GUARDE o valor devolvido na inclusão. Comportamento observado na SulAmérica (homologação): nas consultas este campo volta nulo e o mesmo valor aparece em matriculaFamilia.
Um item por vida enviada, na inclusão (o único movimento que aceita várias vidas). Cada entrada traz o codigoMovimentacao (protocolo) daquela vida.
Vem vazia em consulta, alteração e exclusão, que movimentam uma vida só.
protocolo e beneficiario no topo seguem apontando para a primeira vida, por compatibilidade. Em lote, use esta lista.
Vem vazia em consulta.
items
Validações retornadas pela operadora (wrappers). A mensagem do wrapper marca a severidade das críticas internas: "Critica Bloqueante" (rejeição) ou "Critica Não Bloqueante" (aviso; a movimentação segue o fluxo).
items
items
Erros críticos de regra de negócio.
items
Crítica de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
URI exata da operadora chamada (auditoria).
Eco do payload enviado à operadora (auditoria/troubleshooting), com credenciais sempre mascaradas (***); login/senha nunca são ecoados.
Retorno cru (raw) devolvido pela API da operadora.
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 de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
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 de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
Corpo da requisição acima do limite aceito pela fachada: 1 MB nas rotas de dados, 12 MB em POST /v1/faturas/interpretacoes, que recebe o PDF em base64.
Não há limite de ITENS no lote: o teto é de bytes, e existe para que um corpo gigante não derrube o processo. Lote grande que estoure o limite deve ser dividido em requisições; cada uma é independente na operadora.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.
Não foi possível concluir a operação junto à operadora.
Em consulta, sem repetir no corpo a falha pode ser transitória e nova tentativa é segura.
Em escrita (POST, PATCH, DELETE) o corpo traz repetir: false, e o desfecho é indeterminado: a operadora pode ter processado e só a resposta ter se perdido. Não reenvie. Se o corpo trouxer protocolo, consulte-o em GET /v1/movimentacoes/{protocolo}; se não, confira o beneficiário pelo CPF antes de tentar de novo.
Erro gerado pela própria API, antes ou depois de falar com a operadora. Formato distinto do Erro, que é usado quando o desfecho vem da operadora.
Motivo resumido.
Detalhe técnico, quando existe.
Quando false, não reenvie. Em consulta significa que repetir devolve o mesmo resultado; em escrita significa que o desfecho é indeterminado, porque a operadora pode ter processado e só a resposta ter se perdido. Ausente quando a falha pode ser transitória, o que só ocorre em consulta.
Protocolo da movimentação, quando a operadora devolveu um antes de falhar. **Em escrita com 502, consulte este protocolo em GET /v1/movimentacoes/{protocolo} em vez de reenviar.**
Caminho chamado na operadora, sem host. Para diagnóstico.
Resposta da operadora, para diagnóstico. Formato variável.
Outro status de transporte, repassado do provedor como veio (ex. 403, 404, 409, 429). A fachada não os traduz: mascará-los de 400 esconderia do consumidor a diferença entre pedido inválido e limite de uso, por exemplo.
Não são desfecho de negócio. Rejeição da operadora chega em HTTP 200 com criticas; ausência de registro também é 200. Um status aqui indica problema de integração, não de cadastro, e vale acionar o suporte.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica de validação devolvida pela operadora. bloqueante vem do wrapper de validacoes (mensagem "Critica Bloqueante" / "Critica Não Bloqueante"): false = aviso (a movimentação segue e pode liberar, ex. 2401); true = rejeição (corrigir e reenviar); null = a operadora não marcou.