Listar / buscar beneficiários
/v1/beneficiariosConsulta o cadastro de beneficiários (vidas) na operadora de destino. Equivale ao movimento C (Consulta) do contrato legado. Os filtros podem não ser aplicados pela operadora; para acompanhar movimentação, prefira a consulta por protocolo.
Query Parameters
cpfstring
CPF do titular para filtrar.
cpfDependentestring
CPF de um dependente específico.
nomestring
Nome (ou parte) do beneficiário.
apolicestring
Número da apólice/contrato.
empresastring
CNPJ ou identificador da empresa estipulante.
carteirinhastring
Número da carteirinha.
ufstring
UF para filtrar.
statusstring
Desambigua CPF com mais de um vínculo. 1 ATIVO, 2 EXCLUIDO, 3 DEMITIDO, 4 REMIDO.
Sem este filtro, a operadora retorna todos os vínculos do CPF, em ordem própria. Use-o sempre que precisar do cadastro vigente. Como mais de um vínculo pode compartilhar o mesmo status, o filtro nem sempre reduz a um: a lista completa sai em vinculos.
codigoRdpstring
Código RDP do beneficiário.
matriculaFamiliastring
Matrícula da família (a mesma para todas as vidas do grupo).
titularboolean
true para restringir aos titulares.
origemstring
Origem do vínculo (ex. SAUDE).
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.
Responses
Lista de beneficiários encontrados. Não assuma paginação.
Estrutura ResponseBase traduzida (movimentacoes[]).
Ver schema bruto / exemplo JSON
{
"type": "object",
"description": "Estrutura ResponseBase traduzida (movimentacoes[])."
}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.
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.
Listar / buscar beneficiários
/v1/beneficiariosConsulta o cadastro de beneficiários (vidas) na operadora de destino. Equivale ao movimento C (Consulta) do contrato legado. Os filtros podem não ser aplicados pela operadora; para acompanhar movimentação, prefira a consulta por protocolo.
Query Parameters
cpfstring
CPF do titular para filtrar.
cpfDependentestring
CPF de um dependente específico.
nomestring
Nome (ou parte) do beneficiário.
apolicestring
Número da apólice/contrato.
empresastring
CNPJ ou identificador da empresa estipulante.
carteirinhastring
Número da carteirinha.
ufstring
UF para filtrar.
statusstring
Desambigua CPF com mais de um vínculo. 1 ATIVO, 2 EXCLUIDO, 3 DEMITIDO, 4 REMIDO.
Sem este filtro, a operadora retorna todos os vínculos do CPF, em ordem própria. Use-o sempre que precisar do cadastro vigente. Como mais de um vínculo pode compartilhar o mesmo status, o filtro nem sempre reduz a um: a lista completa sai em vinculos.
codigoRdpstring
Código RDP do beneficiário.
matriculaFamiliastring
Matrícula da família (a mesma para todas as vidas do grupo).
titularboolean
true para restringir aos titulares.
origemstring
Origem do vínculo (ex. SAUDE).
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.
Responses
Lista de beneficiários encontrados. Não assuma paginação.
Estrutura ResponseBase traduzida (movimentacoes[]).
Ver schema bruto / exemplo JSON
{
"type": "object",
"description": "Estrutura ResponseBase traduzida (movimentacoes[])."
}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.
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.