POST Juntar Cadastros
Junta dois cadastros do mesmo paciente: move o histórico do cadastro absorvido (sourceId) para o que fica (targetId) e aposenta o absorvido (exclusão lógica, apontando para o que ficou). A junção pode ser desfeita em até 30 dias. Use Prévia da Junção antes, para conferir o resultado.
Envie o header Authorization: Bearer {accessToken} (token de usuário) ou x-api-key: {apiKey} (integrações). Veja Autenticação.
Exige a permissão update_patients.
A junção precisa ser feita por um usuário: com API Key a rota responde 403, porque o responsável fica registrado.
Endpoint
POST https://api-dev.imagemais.com.br/api/patients/merge
Corpo da Requisição
| Campo | Tipo | Obrigatório | Valores válidos | Descrição |
|---|---|---|---|---|
sourceId | number | ✅ | inteiro, mínimo 1 | Cadastro absorvido |
targetId | number | ✅ | inteiro, mínimo 1 | Cadastro que fica |
fields | object | ❌ | — | Escolhas de campo quando os dois cadastros têm valores diferentes. Chaves: name, cpf, dateBirth, gender, rg, phone, secondary_phone, email, address |
fields.{campo} | string | ❌ | source ou target | De qual cadastro vem o valor do campo. Sem escolha, vale o do cadastro que fica; campo vazio no que fica é preenchido pelo absorvido |
reason | string | ❌ | até 500 caracteres | Motivo da junção (texto livre) |
Requisição
curl -X 'POST' \
'https://api-dev.imagemais.com.br/api/patients/merge' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
-d '{
"sourceId": 205,
"targetId": 118,
"fields": {
"name": "target",
"phone": "source"
},
"reason": "Cadastro duplicado na recepção"
}'
Respostas
201 Sucesso
{
"id": 12,
"sourceId": 205,
"targetId": 118,
"moved": {
"appointments": 3,
"consultations": 2,
"budgets": 1
}
}
moved conta os registros movidos por tabela (agendamentos, consultas, orçamentos, triagens, exames, alergias etc.). As declarações do paciente são copiadas depois, em segundo plano (status FILES_PENDING até terminar).
400 Requisição inválida
Retornado quando o corpo ou a query não passam na validação. A lista message traz um item por regra violada, por exemplo:
{
"message": [
"sourceId must not be less than 1",
"targetId must be an integer number"
],
"error": "Bad Request",
"statusCode": 400
}
Outra mensagem possível: Escolha dois cadastros diferentes (sourceId igual a targetId).
403 Sem permissão
Além de Permissões insuficientes, a rota responde assim quando chamada com API Key.
{
"message": "A junção precisa ser feita por um usuário",
"error": "Forbidden",
"statusCode": 403
}
404 Não encontrado
{
"message": "Paciente #205 não encontrado",
"error": "Not Found",
"statusCode": 404
}
409 Conflito
Mensagens possíveis:
O cadastro #{id} não está disponível para junção(excluído ou já juntado)Os dois têm CPF válido e diferente: são pessoas diferentes.O cadastro #{id} tem atendimento em andamento hoje. Termine antes de juntar.O cadastro #{id} já foi juntado ao #{outro}.O cadastro #{id} foi excluído.
{
"message": "Os dois têm CPF válido e diferente: são pessoas diferentes.",
"error": "Conflict",
"statusCode": 409
}
500 Erro interno
{
"message": "Não foi possível juntar os cadastros",
"error": "Internal Server Error",
"statusCode": 500
}