Cadastrar um paciente, passo a passo

Este guia descreve o cadastro do paciente até a etapa de agendamento: criação do paciente, vínculo com o convênio e verificação da carteirinha.

1. Origem do cadastro

Campo opcional que indica como o paciente chegou à clínica (Instagram, indicação, entre outros). O idOrigem é obtido em GET /origem/lista, e novas origens são criadas com POST /origem/novo. As regras de criação estão em Origens de cadastro.

2. Criação do paciente

Os campos nome e dataNascimento são obrigatórios. Os demais campos, como o cpfcnpj, podem ser exigidos conforme a configuração da clínica.

curl -X POST "https://api.clinicanasnuvens.com.br/paciente/novo" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "João da Silva",
    "dataNascimento": "2005-07-27",
    "cpfcnpj": "40786523018",
    "sexo": "M",
    "genero": "MASCULINO",
    "estrangeiro": false,
    "numeroIdentificacao": null,
    "idOrigem": 5,
    "idNacionalidade": 1,
    "contato": {
      "telefoneCelular": "49998876655",
      "email": "joao.silva@exemplo.com.br"
    },
    "endereco": {
      "cep": "89820000",
      "rua": "Rua das Flores",
      "numero": "123",
      "bairro": "Centro",
      "idCidade": 1
    }
  }'

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`nome`	String	Sim	Nome civil completo do paciente
`dataNascimento`	String	Sim	Data de nascimento, no formato `AAAA-MM-DD`
`cpfcnpj`	String	Conforme a clínica	CPF ou CNPJ do paciente. Aceita máscara
`nomeSocial`	String	Não	Nome social do paciente
`sexo`	String	Não	Sexo do paciente: `M` ou `F`
`genero`	String	Não	Gênero do paciente, por exemplo `MASCULINO` ou `FEMININO`
`estrangeiro`	Boolean	Não	Indica se o paciente é estrangeiro. Padrão `false`
`numeroIdentificacao`	String	Quando `estrangeiro` é `true`	Documento de identificação do paciente estrangeiro, no lugar do CPF
`numeroControle`	String	Não	Número de controle interno do paciente
`idOrigem`	Integer	Não	Origem do cadastro, obtida em Origens de cadastro
`idNacionalidade`	Integer	Não	Nacionalidade, obtida em `/nacionalidade/lista`
`contato`	Object	Não	Contatos do paciente, compartilhados entre as clínicas do grupo
`contato.telefoneCelular`	String	Não	Telefone celular
`contato.email`	String	Não	Endereço de e-mail
`endereco`	Object	Não	Endereço do paciente, compartilhado entre as clínicas do grupo
`endereco.cep`	String	Não	CEP, somente dígitos
`endereco.rua`	String	Não	Logradouro
`endereco.numero`	String	Não	Número do imóvel
`endereco.complemento`	String	Não	Complemento do endereço
`endereco.bairro`	String	Não	Bairro
`endereco.idCidade`	Integer	Não	Cidade, obtida em `/cidade/lista`

O contato aceita também outros telefones e ramais, descritos na Referência.

Resposta:

{
  "id": 3,
  "ativo": true,
  "nome": "João da Silva",
  "nomeSocial": null,
  "dataNascimento": "2005-07-27",
  "cpfcnpj": "40786523018",
  "numeroIdentificacao": null,
  "numeroControle": "000123",
  "sexo": "M",
  "genero": "MASCULINO",
  "estrangeiro": false,
  "idOrigem": 5,
  "idNacionalidade": 1,
  "contato": {
    "telefoneCelular": "49998876655",
    "telefoneResidencial": null,
    "telefoneComercial": null,
    "telefoneRecados": null,
    "ramalTelefoneResidencial": null,
    "ramalTelefoneComercial": null,
    "ramalTelefoneRecados": null,
    "email": "joao.silva@exemplo.com.br",
    "skype": null
  },
  "endereco": {
    "cep": "89820000",
    "rua": "Rua das Flores",
    "numero": "123",
    "complemento": null,
    "bairro": "Centro",
    "idCidade": 1
  }
}

A resposta contém o cadastro com o id do paciente nesta clínica.

O paciente é criado com status ativo, e o campo ativo não faz parte da requisição de criação. O status é alterado pela operação descrita em Ativar ou inativar.

Paciente estrangeiro

Quando o paciente é estrangeiro, envie estrangeiro igual a true e informe o documento de identificação em numeroIdentificacao, no lugar do cpfcnpj. O numeroIdentificacao deve ser único na clínica.

O idCidade e o idNacionalidade são obtidos nas listas de Cadastros gerais, em /cidade/lista e /nacionalidade/lista.

Erros comuns (Bad Request)

{
  "mensagem": "A nacionalidade informada não existe.",
  "identificador": null,
  "errors": []
}

Situação	Motivo
`400` com "Um ou mais erros de validação ocorreram ao validar a requisição." e `errors` vazio	Mesmo CPF enviado duas vezes em menos de 2 segundos
`400` ao informar a cidade, a nacionalidade ou a origem	O identificador não existe nesta clínica

3. Vínculo com o convênio

Na criação do agendamento, o idPacienteConvenio é obrigatório. Ele identifica o vínculo entre o paciente e o convênio. O idTipoConvenio é obtido em GET /tipo-convenio/lista.

curl -X POST "https://api.clinicanasnuvens.com.br/convenio-paciente/associar" \
  -H "Authorization: Basic <CREDENCIAIS_EM_BASE64>" \
  -H "clinicaNasNuvens-cid: <TOKEN_DA_CLINICA>" \
  -H "Content-Type: application/json" \
  -d '{
    "idPaciente": 3,
    "idTipoConvenio": 12,
    "carteirinha": "123456789012",
    "dataValidade": "2027-12-31"
  }'

Resposta:

{
  "id": 12,
  "idTipoConvenio": 12,
  "nomeTipoConvenio": "Unimed",
  "ativo": true,
  "dataValidade": "2027-12-31",
  "carteirinha": "123456789012"
}

O id retornado é o idPacienteConvenio utilizado no agendamento. As regras de validade estão em Convênios do paciente.

4. Verificação da carteirinha

Etapa opcional, que verifica a elegibilidade do cartão antes de um agendamento por convênio: GET /plano-beneficio/elegibilidade?numeroCartao=.... A consulta é feita pelo número do cartão, e um cartão não apto retorna 200 com elegivel: false. Ver Plano de benefício.

5. Agendamento

Com o paciente criado e o convênio vinculado, os identificadores necessários ao agendamento estão disponíveis. O guia da Agenda descreve a criação do agendamento.

Próximo passo

Manter o cadastro.

1. Origem do cadastro​

2. Criação do paciente​

Campos da requisição​

Erros comuns (Bad Request)​

3. Vínculo com o convênio​

4. Verificação da carteirinha​

5. Agendamento​

Próximo passo​