Incluir beneficiário (movimento I)
/v1/beneficiariosInclusão de uma ou VÁRIAS vidas na operadora de destino. Equivale ao movimento I do contrato legado.
## Grupo familiar: mande a família num array
Não existe campo de dependentes dentro de uma vida. Cada vida é um registro, mas o corpo aceita um array, e é assim que se envia grupo familiar: titular na frente, cônjuge e filhos em seguida, todos com a matriculaFuncionario do titular. Veja o exemplo `grupoFamiliar` abaixo, pronto para copiar.
Enviando uma vida por requisição, o dependente só é aceito depois que o titular propaga na operadora, e até lá a recusa vem como A1083 ("titular não encontrado") ou A015 ("matrícula diferente da do titular", ainda que a matrícula esteja correta). O intervalo não é fixo: medimos de 44 segundos a mais de dez minutos. No array a família entra junta e essa espera não existe.
O lote é tudo ou nada: se uma vida for recusada, nenhuma entra, e isso vem da operadora. validacoes na resposta diz qual vida caiu e por quê.
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).
Se a matriculaProvedor não tiver sido guardada, ela é recuperável: nas consultas esse campo volta nulo e o mesmo valor aparece em beneficiario.matriculaFamilia, tanto na busca por CPF (GET /v1/beneficiarios/{cpf}) quanto na consulta por protocolo.
Regras medidas em homologação SulAmérica: - nome e nomeAbreviado sem acentos: acento gera A1034 (nome completo) e A1046 (nome abreviado), acompanhados de A1080, que já sugere um nome abreviado aceito. - matriculaFuncionario não pode repetir uma já usada no contrato: retorna A015. - CPF já cadastrado retorna A041. - nome e nomeAbreviado podem ser diferentes, e dadosBancarios não é obrigatório: nos dois casos a inclusão passa sem críticas.
Headers
X-Cnpj-Provedorstringrequired
CNPJ da operadora de destino. É ele que define para qual operadora a requisição é encaminhada. Ex.: SulAmérica 01685053000156.
ex: 01685053000156X-Portal-Loginstring
Login do Portal Empresa da empresa cuja vida esta sendo movimentada ou consultada. Alternativa ao login do corpo nas escritas, e o unico canal nas consultas, que nao tem corpo. Enviado sempre junto de X-Portal-Senha: o par vem inteiro de uma fonte so (corpo OU header), nunca metade de cada. O corpo tem precedencia. Nunca e ecoado.
X-Portal-Senhastring
Senha do Portal Empresa, par de X-Portal-Login. Vai para a operadora exatamente como enviada, sem aparar espacos. Nunca e ecoada.
Request Body
application/jsonrequired
Dados de um beneficiário a incluir (titular ou dependente).
Obrigatórios na prática (SulAmérica): nome (sem acentos), nomeAbreviado (igual a nome), cpf, matriculaFuncionario, dataNascimento, grauParentesco, estadoCivil, sexo, nomeMae, pisPasep, cns, dataAdesao, dataAdmissao, dataEvento, certificado, endereco, contato, dadosBancarios, produto (com subContrato), apolice, tipoProduto. Use o example como base.
Fora desta lista: matricula, dataVigencia e codigoSegurado existem no contrato mas o Orquestrador não os lê (medido); enviá-los não dá erro nem crítica, o valor simplesmente não chega à operadora.
Credencial por estipulante (opcional): login/senha do Portal Empresa do CNPJ movimentado podem ser enviados no corpo; vão para o envelope da operadora e nunca são ecoados na resposta (mascarados ***). Quando omitidos, aplica-se a credencial padrão do ambiente (comportamento atual).
Campos adicionais do manual da operadora: a SulAmérica define ainda nacionalidade, matriculaDif, carenciaDif, cids[], setor, cbo, dni e o objeto portabilidade. Este gateway repassa verbatim qualquer campo do corpo para a operação (exceto login/senha, tratados no parágrafo acima). Valide em homologação antes de depender desses campos.
Credencial do Portal Empresa do estipulante (opcional). Nunca ecoada.
Senha do Portal Empresa do estipulante (opcional). Nunca ecoada.
Sem acentos (crítica A1034).
Sem acentos (crítica A1046, com sugestão em A1080).
Não é lido pelo Orquestrador (medido): a matrícula que vale é matriculaFuncionario.
No dependente, é a matrícula do titular: é ela que liga a família.
Até 8 dígitos; acima disso vem A1002 ("São 8 Números"). O preenchimento com zeros à esquerda é indiferente: a operadora normaliza (enviamos 7992, ela gravou 00007992) e 7992, 07992 e 00007992 foram todos aceitos no mesmo titular (medido em 05/10/2026). Não gaste tempo com o formato: se a crítica fala em matrícula divergente, a causa provável é outra, veja A015 na tabela de críticas.
Varrido de 0 a 9 em homologação (05/10/2026), contra um titular já propagado, para seguro do tipo SAÚDE:
| grau | resultado | |---|---| | 0 | titular. Numa matrícula que já tem titular ativo vem A1081 | | 1 | cônjuge: aceito | | 2 | filho(a): aceito | | 3 a 6 | companheiro, pais, agregados, enteados, outros: A1032, exige documento comprobatório, então a vida não entra só pela API | | 7 a 9 | A1019, "Grau Parentesco inválido para seguro tipo saúde" |
Só 1 e 2 entram sozinhos. A varredura precisa de titular já propagado: feita logo após incluir o titular, todos os dez graus devolvem A015 e não se mede grau nenhum.
S=Solteiro, C=Casado, V=Viúvo, D=Divorciado, O=Outros.
Número do PIS/PASEP. O nome do campo é `pisPasep`: era documentado como pis, que o Orquestrador não possui, então o valor era descartado em silêncio (sem erro e sem crítica).
Cartão Nacional de Saúde.
Não é lido pelo Orquestrador (medido). Use dataAdesao e dataEvento.
Local de rateio (somente SulAmérica).
Não é lido pelo Orquestrador na inclusão (medido em 30/09/2026).
OBRIGATÓRIO na prática.
Dados do plano/produto contratado.
SAUDE, ODONTO ou VIDA.
Lote: várias vidas numa requisição. Cada item tem o mesmo formato de uma inclusão avulsa. A resposta traz um item em resultados por vida enviada.
items
Dados de um beneficiário a incluir (titular ou dependente).
Obrigatórios na prática (SulAmérica): nome (sem acentos), nomeAbreviado (igual a nome), cpf, matriculaFuncionario, dataNascimento, grauParentesco, estadoCivil, sexo, nomeMae, pisPasep, cns, dataAdesao, dataAdmissao, dataEvento, certificado, endereco, contato, dadosBancarios, produto (com subContrato), apolice, tipoProduto. Use o example como base.
Fora desta lista: matricula, dataVigencia e codigoSegurado existem no contrato mas o Orquestrador não os lê (medido); enviá-los não dá erro nem crítica, o valor simplesmente não chega à operadora.
Credencial por estipulante (opcional): login/senha do Portal Empresa do CNPJ movimentado podem ser enviados no corpo; vão para o envelope da operadora e nunca são ecoados na resposta (mascarados ***). Quando omitidos, aplica-se a credencial padrão do ambiente (comportamento atual).
Campos adicionais do manual da operadora: a SulAmérica define ainda nacionalidade, matriculaDif, carenciaDif, cids[], setor, cbo, dni e o objeto portabilidade. Este gateway repassa verbatim qualquer campo do corpo para a operação (exceto login/senha, tratados no parágrafo acima). Valide em homologação antes de depender desses campos.
Credencial do Portal Empresa do estipulante (opcional). Nunca ecoada.
Senha do Portal Empresa do estipulante (opcional). Nunca ecoada.
Sem acentos (crítica A1034).
Sem acentos (crítica A1046, com sugestão em A1080).
Não é lido pelo Orquestrador (medido): a matrícula que vale é matriculaFuncionario.
No dependente, é a matrícula do titular: é ela que liga a família.
Até 8 dígitos; acima disso vem A1002 ("São 8 Números"). O preenchimento com zeros à esquerda é indiferente: a operadora normaliza (enviamos 7992, ela gravou 00007992) e 7992, 07992 e 00007992 foram todos aceitos no mesmo titular (medido em 05/10/2026). Não gaste tempo com o formato: se a crítica fala em matrícula divergente, a causa provável é outra, veja A015 na tabela de críticas.
Varrido de 0 a 9 em homologação (05/10/2026), contra um titular já propagado, para seguro do tipo SAÚDE:
| grau | resultado | |---|---| | 0 | titular. Numa matrícula que já tem titular ativo vem A1081 | | 1 | cônjuge: aceito | | 2 | filho(a): aceito | | 3 a 6 | companheiro, pais, agregados, enteados, outros: A1032, exige documento comprobatório, então a vida não entra só pela API | | 7 a 9 | A1019, "Grau Parentesco inválido para seguro tipo saúde" |
Só 1 e 2 entram sozinhos. A varredura precisa de titular já propagado: feita logo após incluir o titular, todos os dez graus devolvem A015 e não se mede grau nenhum.
S=Solteiro, C=Casado, V=Viúvo, D=Divorciado, O=Outros.
Número do PIS/PASEP. O nome do campo é `pisPasep`: era documentado como pis, que o Orquestrador não possui, então o valor era descartado em silêncio (sem erro e sem crítica).
Cartão Nacional de Saúde.
Não é lido pelo Orquestrador (medido). Use dataAdesao e dataEvento.
Local de rateio (somente SulAmérica).
Não é lido pelo Orquestrador na inclusão (medido em 30/09/2026).
OBRIGATÓRIO na prática.
Dados do plano/produto contratado.
SAUDE, ODONTO ou VIDA.
Ver schema bruto / exemplo JSON
{
"nome": "Teste Beneficiario Um",
"nomeAbreviado": "Teste Beneficiario Um",
"cpf": "36442421430",
"matriculaFuncionario": "7700",
"dataNascimento": "1990-01-01",
"grauParentesco": "0",
"estadoCivil": "S",
"sexo": "M",
"nomeMae": "Mae Teste",
"pisPasep": "12056412308",
"cns": "700000000000000",
"dataAdesao": "2026-04-19",
"dataAdmissao": "2026-01-15",
"dataEvento": "2026-04-19",
"local": 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).
Resultado de uma operação, de consulta ou de escrita. Reúne o retorno da operadora, as validações de negócio e os dados de auditoria.
Código HTTP resultante do processamento na operadora.
Protocolo de rastreio gerado pela operadora.
Resumo do beneficiário afetado; cada operação popula um subconjunto dos campos. Eles 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.
Em consulta por CPF é o vínculo mais recente (maior dataExclusao). Em escrita é a vida enviada; em lote, a primeira delas.
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.
Todos os vínculos do CPF consultado, na ordem em que a operadora devolveu. beneficiario é o mais recente desta lista; use vinculos quando precisar dos outros ou de escolher por outro critério.
O vínculo ativo vem com dataExclusao igual a 9999-12-31, e não nula. A operadora não devolve a lista ordenada, então o último item não é necessariamente o mais recente.
Vem vazia quando a consulta não foi por CPF, quando o CPF informado não identifica uma pessoa (dígito repetido) ou quando os registros devolvidos não são todos da mesma pessoa.
items
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.
items
Validações retornadas pela operadora. A mensagem de cada uma marca a severidade das críticas que ela agrupa: "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 devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
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.
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 devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
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 devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
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 devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
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 da operadora como veio (ex. 403, 404, 409, 429).
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 devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
Incluir beneficiário (movimento I)
/v1/beneficiariosInclusão de uma ou VÁRIAS vidas na operadora de destino. Equivale ao movimento I do contrato legado.
## Grupo familiar: mande a família num array
Não existe campo de dependentes dentro de uma vida. Cada vida é um registro, mas o corpo aceita um array, e é assim que se envia grupo familiar: titular na frente, cônjuge e filhos em seguida, todos com a matriculaFuncionario do titular. Veja o exemplo `grupoFamiliar` abaixo, pronto para copiar.
Enviando uma vida por requisição, o dependente só é aceito depois que o titular propaga na operadora, e até lá a recusa vem como A1083 ("titular não encontrado") ou A015 ("matrícula diferente da do titular", ainda que a matrícula esteja correta). O intervalo não é fixo: medimos de 44 segundos a mais de dez minutos. No array a família entra junta e essa espera não existe.
O lote é tudo ou nada: se uma vida for recusada, nenhuma entra, e isso vem da operadora. validacoes na resposta diz qual vida caiu e por quê.
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).
Se a matriculaProvedor não tiver sido guardada, ela é recuperável: nas consultas esse campo volta nulo e o mesmo valor aparece em beneficiario.matriculaFamilia, tanto na busca por CPF (GET /v1/beneficiarios/{cpf}) quanto na consulta por protocolo.
Regras medidas em homologação SulAmérica: - nome e nomeAbreviado sem acentos: acento gera A1034 (nome completo) e A1046 (nome abreviado), acompanhados de A1080, que já sugere um nome abreviado aceito. - matriculaFuncionario não pode repetir uma já usada no contrato: retorna A015. - CPF já cadastrado retorna A041. - nome e nomeAbreviado podem ser diferentes, e dadosBancarios não é obrigatório: nos dois casos a inclusão passa sem críticas.
Headers
X-Cnpj-Provedorstringrequired
CNPJ da operadora de destino. É ele que define para qual operadora a requisição é encaminhada. Ex.: SulAmérica 01685053000156.
ex: 01685053000156X-Portal-Loginstring
Login do Portal Empresa da empresa cuja vida esta sendo movimentada ou consultada. Alternativa ao login do corpo nas escritas, e o unico canal nas consultas, que nao tem corpo. Enviado sempre junto de X-Portal-Senha: o par vem inteiro de uma fonte so (corpo OU header), nunca metade de cada. O corpo tem precedencia. Nunca e ecoado.
X-Portal-Senhastring
Senha do Portal Empresa, par de X-Portal-Login. Vai para a operadora exatamente como enviada, sem aparar espacos. Nunca e ecoada.
Request Body
application/jsonrequired
Dados de um beneficiário a incluir (titular ou dependente).
Obrigatórios na prática (SulAmérica): nome (sem acentos), nomeAbreviado (igual a nome), cpf, matriculaFuncionario, dataNascimento, grauParentesco, estadoCivil, sexo, nomeMae, pisPasep, cns, dataAdesao, dataAdmissao, dataEvento, certificado, endereco, contato, dadosBancarios, produto (com subContrato), apolice, tipoProduto. Use o example como base.
Fora desta lista: matricula, dataVigencia e codigoSegurado existem no contrato mas o Orquestrador não os lê (medido); enviá-los não dá erro nem crítica, o valor simplesmente não chega à operadora.
Credencial por estipulante (opcional): login/senha do Portal Empresa do CNPJ movimentado podem ser enviados no corpo; vão para o envelope da operadora e nunca são ecoados na resposta (mascarados ***). Quando omitidos, aplica-se a credencial padrão do ambiente (comportamento atual).
Campos adicionais do manual da operadora: a SulAmérica define ainda nacionalidade, matriculaDif, carenciaDif, cids[], setor, cbo, dni e o objeto portabilidade. Este gateway repassa verbatim qualquer campo do corpo para a operação (exceto login/senha, tratados no parágrafo acima). Valide em homologação antes de depender desses campos.
Credencial do Portal Empresa do estipulante (opcional). Nunca ecoada.
Senha do Portal Empresa do estipulante (opcional). Nunca ecoada.
Sem acentos (crítica A1034).
Sem acentos (crítica A1046, com sugestão em A1080).
Não é lido pelo Orquestrador (medido): a matrícula que vale é matriculaFuncionario.
No dependente, é a matrícula do titular: é ela que liga a família.
Até 8 dígitos; acima disso vem A1002 ("São 8 Números"). O preenchimento com zeros à esquerda é indiferente: a operadora normaliza (enviamos 7992, ela gravou 00007992) e 7992, 07992 e 00007992 foram todos aceitos no mesmo titular (medido em 05/10/2026). Não gaste tempo com o formato: se a crítica fala em matrícula divergente, a causa provável é outra, veja A015 na tabela de críticas.
Varrido de 0 a 9 em homologação (05/10/2026), contra um titular já propagado, para seguro do tipo SAÚDE:
| grau | resultado | |---|---| | 0 | titular. Numa matrícula que já tem titular ativo vem A1081 | | 1 | cônjuge: aceito | | 2 | filho(a): aceito | | 3 a 6 | companheiro, pais, agregados, enteados, outros: A1032, exige documento comprobatório, então a vida não entra só pela API | | 7 a 9 | A1019, "Grau Parentesco inválido para seguro tipo saúde" |
Só 1 e 2 entram sozinhos. A varredura precisa de titular já propagado: feita logo após incluir o titular, todos os dez graus devolvem A015 e não se mede grau nenhum.
S=Solteiro, C=Casado, V=Viúvo, D=Divorciado, O=Outros.
Número do PIS/PASEP. O nome do campo é `pisPasep`: era documentado como pis, que o Orquestrador não possui, então o valor era descartado em silêncio (sem erro e sem crítica).
Cartão Nacional de Saúde.
Não é lido pelo Orquestrador (medido). Use dataAdesao e dataEvento.
Local de rateio (somente SulAmérica).
Não é lido pelo Orquestrador na inclusão (medido em 30/09/2026).
OBRIGATÓRIO na prática.
Dados do plano/produto contratado.
SAUDE, ODONTO ou VIDA.
Lote: várias vidas numa requisição. Cada item tem o mesmo formato de uma inclusão avulsa. A resposta traz um item em resultados por vida enviada.
items
Dados de um beneficiário a incluir (titular ou dependente).
Obrigatórios na prática (SulAmérica): nome (sem acentos), nomeAbreviado (igual a nome), cpf, matriculaFuncionario, dataNascimento, grauParentesco, estadoCivil, sexo, nomeMae, pisPasep, cns, dataAdesao, dataAdmissao, dataEvento, certificado, endereco, contato, dadosBancarios, produto (com subContrato), apolice, tipoProduto. Use o example como base.
Fora desta lista: matricula, dataVigencia e codigoSegurado existem no contrato mas o Orquestrador não os lê (medido); enviá-los não dá erro nem crítica, o valor simplesmente não chega à operadora.
Credencial por estipulante (opcional): login/senha do Portal Empresa do CNPJ movimentado podem ser enviados no corpo; vão para o envelope da operadora e nunca são ecoados na resposta (mascarados ***). Quando omitidos, aplica-se a credencial padrão do ambiente (comportamento atual).
Campos adicionais do manual da operadora: a SulAmérica define ainda nacionalidade, matriculaDif, carenciaDif, cids[], setor, cbo, dni e o objeto portabilidade. Este gateway repassa verbatim qualquer campo do corpo para a operação (exceto login/senha, tratados no parágrafo acima). Valide em homologação antes de depender desses campos.
Credencial do Portal Empresa do estipulante (opcional). Nunca ecoada.
Senha do Portal Empresa do estipulante (opcional). Nunca ecoada.
Sem acentos (crítica A1034).
Sem acentos (crítica A1046, com sugestão em A1080).
Não é lido pelo Orquestrador (medido): a matrícula que vale é matriculaFuncionario.
No dependente, é a matrícula do titular: é ela que liga a família.
Até 8 dígitos; acima disso vem A1002 ("São 8 Números"). O preenchimento com zeros à esquerda é indiferente: a operadora normaliza (enviamos 7992, ela gravou 00007992) e 7992, 07992 e 00007992 foram todos aceitos no mesmo titular (medido em 05/10/2026). Não gaste tempo com o formato: se a crítica fala em matrícula divergente, a causa provável é outra, veja A015 na tabela de críticas.
Varrido de 0 a 9 em homologação (05/10/2026), contra um titular já propagado, para seguro do tipo SAÚDE:
| grau | resultado | |---|---| | 0 | titular. Numa matrícula que já tem titular ativo vem A1081 | | 1 | cônjuge: aceito | | 2 | filho(a): aceito | | 3 a 6 | companheiro, pais, agregados, enteados, outros: A1032, exige documento comprobatório, então a vida não entra só pela API | | 7 a 9 | A1019, "Grau Parentesco inválido para seguro tipo saúde" |
Só 1 e 2 entram sozinhos. A varredura precisa de titular já propagado: feita logo após incluir o titular, todos os dez graus devolvem A015 e não se mede grau nenhum.
S=Solteiro, C=Casado, V=Viúvo, D=Divorciado, O=Outros.
Número do PIS/PASEP. O nome do campo é `pisPasep`: era documentado como pis, que o Orquestrador não possui, então o valor era descartado em silêncio (sem erro e sem crítica).
Cartão Nacional de Saúde.
Não é lido pelo Orquestrador (medido). Use dataAdesao e dataEvento.
Local de rateio (somente SulAmérica).
Não é lido pelo Orquestrador na inclusão (medido em 30/09/2026).
OBRIGATÓRIO na prática.
Dados do plano/produto contratado.
SAUDE, ODONTO ou VIDA.
Ver schema bruto / exemplo JSON
{
"nome": "Teste Beneficiario Um",
"nomeAbreviado": "Teste Beneficiario Um",
"cpf": "36442421430",
"matriculaFuncionario": "7700",
"dataNascimento": "1990-01-01",
"grauParentesco": "0",
"estadoCivil": "S",
"sexo": "M",
"nomeMae": "Mae Teste",
"pisPasep": "12056412308",
"cns": "700000000000000",
"dataAdesao": "2026-04-19",
"dataAdmissao": "2026-01-15",
"dataEvento": "2026-04-19",
"local": 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).
Resultado de uma operação, de consulta ou de escrita. Reúne o retorno da operadora, as validações de negócio e os dados de auditoria.
Código HTTP resultante do processamento na operadora.
Protocolo de rastreio gerado pela operadora.
Resumo do beneficiário afetado; cada operação popula um subconjunto dos campos. Eles 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.
Em consulta por CPF é o vínculo mais recente (maior dataExclusao). Em escrita é a vida enviada; em lote, a primeira delas.
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.
Todos os vínculos do CPF consultado, na ordem em que a operadora devolveu. beneficiario é o mais recente desta lista; use vinculos quando precisar dos outros ou de escolher por outro critério.
O vínculo ativo vem com dataExclusao igual a 9999-12-31, e não nula. A operadora não devolve a lista ordenada, então o último item não é necessariamente o mais recente.
Vem vazia quando a consulta não foi por CPF, quando o CPF informado não identifica uma pessoa (dígito repetido) ou quando os registros devolvidos não são todos da mesma pessoa.
items
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.
items
Validações retornadas pela operadora. A mensagem de cada uma marca a severidade das críticas que ela agrupa: "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 devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
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.
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 devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
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 devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
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 devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
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 da operadora como veio (ex. 403, 404, 409, 429).
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 devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.