Consultar itens em aberto do paciente

Retorna os itens passíveis de cobrança para um paciente de forma paginada (PageAPI), consolidando agendamentos particulares pendentes de faturamento (apresentados primeiro) e faturas ou contas a receber em aberto (apresentadas em seguida).

Papel no Fluxo de Pagamento Externo

Este endpoint é a etapa inicial dos fluxos de autoatendimento e pagamento externo (totens físicos, TEF, WhatsApp e portais de pacientes). Ele permite que a aplicação externa consulte previamente o extrato financeiro pendente do paciente e apresente os débitos elegíveis para quitação no terminal de autoatendimento.

Diferenciação do fluxo financeiro pelo sistema:

• No fluxo operacional pelo sistema: A recepção realiza a cobrança presencial consultando as telas internas de Atendimento a Faturar (para agendamentos) e de Contas a Receber (para faturas existentes), realizando o lançamento e a baixa manual de cada título.
• No fluxo de checkout externo: A aplicação externa lista as pendências do paciente de forma consolidada, permitindo que o paciente selecione o débito a pagar diretamente no totem ou aplicativo. Após a captura e aprovação do valor no meio de pagamento externo (TEF/maquininha/Pix), a aplicação direciona a requisição para o endpoint de baixa específico (/agendas/{idAgenda}/baixar para faturamento + baixa ou /faturas/{idFatura}/baixar para baixa direta).

Consultar itens em aberto

curl -G "https://api.clinicanasnuvens.com.br/v1/checkout/pacientes/1001/em-aberto" \
  -H "Authorization: Basic BASE64_DO_CLIENT_ID_E_SECRET" \
  -H "clinicaNasNuvens-cid: SEU_TOKEN_DE_CLINICA" \
  --data-urlencode "tipo=TODOS" \
  --data-urlencode "pagina=0" \
  --data-urlencode "registrosPorPagina=50"

Parâmetros de rota (Path Params)

Parâmetro	Tipo	Obrigatório	Descrição
idPaciente	Integer	Sim	Identificador único do paciente no sistema.

Parâmetros de consulta (Query Params)

Parâmetro	Tipo	Padrão	Descrição
tipo	String	TODOS	Filtra por tipo de pendência (AGENDAS, FATURAS ou TODOS).
dataInicio	String	Data de hoje	Data inicial no formato AAAA-MM-DD. Se não informada ou se for anterior à data atual (hoje), é ajustada automaticamente para hoje.
dataFim	String	-	Data final no formato AAAA-MM-DD. Opcional (se omitida, não impõe data final limite).
pagina	Integer	0	Número da página desejada (0-indexada).
registrosPorPagina	Integer	50	Quantidade máxima de registros retornados por página (máx. 100).

Regras de negócio

• Paginação e Flag de Débitos em Atraso: A resposta é encapsulada em um objeto de resposta paginado contendo:
  • debitosEmAtraso: Flag booleana na raiz do retorno que indica se o paciente possui títulos/faturas financeiras em aberto com vencimento anterior à data de hoje (dataVencimento < hoje). Ideal para totens ou canais de autoatendimento alertarem o paciente sobre pendências financeiras passadas.
  • pagina, totalPaginas e lista: Dados da paginação padrão da API.
• Filtro por Tipo de Item (tipo): Permite selecionar entre TODOS, AGENDAS ou FATURAS. Qualquer valor não reconhecido ou ausente assume o padrão TODOS.
• Filtro de Período e Proteção de Data (dataInicio e dataFim):
  • dataInicio é restrita a partir de hoje: caso a requisição não envie dataInicio ou envie uma data anterior ao dia de hoje, o sistema assume automaticamente a data atual (hoje). Isso assegura que o canal de checkout externo consulte apenas débitos e atendimentos vigentes a partir do dia corrente.
  • dataFim é opcional. Quando não enviada na requisição, o sistema busca os itens a partir de dataInicio sem restrição de data final máxima.
  • Caso dataFim seja anterior a dataInicio, a API retorna de imediato uma página vazia (totalPaginas: 0, lista: []), mantendo a avaliação da flag debitosEmAtraso.
• Critérios de Elegibilidade de Agendamentos:
  • Apenas consultas vinculadas a convênios particulares.
  • Situação de faturamento em PENDENTE_FATURACAO (aguardando faturamento na recepção).
  • Consultas canceladas ou com ausência registrada (Cancelado, CanceladoPaciente, Faltou) são automaticamente excluídas da busca.
  • O valor calculado dos procedimentos particulares vinculados deve ser superior a zero.
  • Agendamentos são ordenados cronologicamente por data da consulta e horário de início, sendo posicionados antes das faturas para priorizar o atendimento imediato na recepção.
• Critérios de Elegibilidade de Faturas:
  • Apenas títulos a receber (RECEBER) em aberto: sem quitação e sem estorno/cancelamento.
  • Exclusivamente títulos particulares: títulos de convênios de saúde são desconsiderados.
  • Saldo restante em aberto deve ser superior a zero.
  • Faturas são ordenadas por data de vencimento e código do faturamento.
• Titularidade Financeira e Dependentes:
  • Se o paciente possuir Responsável Financeiro cadastrado (como em atendimentos de menores/dependentes), a busca localiza os títulos em aberto associados tanto ao paciente quanto ao titular financeiro e sua pessoa física.
• Composição Inteligente da Descrição:
  • Para AGENDA: lista os nomes dos procedimentos particulares concatenados com " + ".
  • Para FATURA:
    • Se a origem for AGENDA, utiliza os procedimentos da consulta ou do faturamento pai.
    • Se a origem for PRONTUARIO, utiliza os procedimentos registrados no atendimento do prontuário ou do faturamento pai.
    • Se a origem for MANUAL ou ORCAMENTO, preserva a descrição original cadastrada na fatura.

Exemplo de resposta

{
  "debitosEmAtraso": false,
  "pagina": 0,
  "totalPaginas": 1,
  "lista": [
    {
      "id": 107598234,
      "tipoItem": "AGENDA",
      "descricao": "Consulta Cardiológica + Eletrocardiograma",
      "valor": 280.00,
      "data": "2026-10-09",
      "horaInicio": "14:00:00",
      "profissional": "Dra. Ana Paula Silveira",
      "especialidade": "Cardiologia",
      "procedimentos": [
        "Consulta Cardiológica",
        "Eletrocardiograma"
      ],
      "status": "AGENDADO"
    },
    {
      "id": 107598255,
      "tipoItem": "AGENDA",
      "descricao": "Consulta Dermatológica",
      "valor": 200.00,
      "data": "2026-10-16",
      "horaInicio": "09:30:00",
      "profissional": "Dr. Marcos Vinicius",
      "especialidade": "Dermatologia",
      "procedimentos": [
        "Consulta Dermatológica"
      ],
      "status": "AGENDADO"
    },
    {
      "id": 24038497,
      "tipoItem": "FATURA",
      "descricao": "Consulta Oftalmológica + Mapeamento de Retina",
      "valor": 150.00,
      "origem": "AGENDA",
      "titularFinanceiro": "Carlos Eduardo da Silva",
      "vencimento": "2026-10-15"
    }
  ]
}

Campos da resposta

Objeto raiz (CheckoutItensEmAbertoRetornoAPI)

Campo	Tipo	Descrição
debitosEmAtraso	Boolean	Indica se o paciente possui débitos financeiros em aberto com vencimento anterior a hoje (true/false).
pagina	Integer	Número da página atual (iniciando em 0).
totalPaginas	Integer	Quantidade total de páginas disponíveis.
lista	Array	Lista paginada dos itens em aberto (CheckoutItemEmAbertoRetornoAPI).

Itens da lista (lista[])

Campo	Tipo	Presente em	Descrição
id	Integer	Todos	Identificador único do item (código da agenda ou da fatura).
tipoItem	String	Todos	Tipo do item (AGENDA ou FATURA).
descricao	String	Todos	Descrição resumida do agendamento ou dos procedimentos da fatura.
valor	Number	Todos	Valor total particular ou saldo restante a pagar.
data	String	Agenda	Data da consulta no formato AAAA-MM-DD.
horaInicio	String	Agenda	Horário de início no formato HH:mm:ss.
profissional	String	Agenda	Nome do profissional de saúde responsável pelo atendimento.
especialidade	String	Agenda	Especialidade médica do atendimento.
procedimentos	Array de Strings	Agenda	Lista de nomes dos procedimentos incluídos no agendamento.
status	String	Agenda	Status atual da consulta (ex.: AGENDADO, CONFIRMADO).
origem	String	Fatura	Origem do lançamento financeiro (AGENDA, MANUAL, ORCAMENTO ou PRONTUARIO).
titularFinanceiro	String	Fatura	Nome completo da pessoa responsável pelo título (paciente ou responsável).
vencimento	String	Fatura	Data de vencimento no formato AAAA-MM-DD.

Veja na Referência

Os detalhes de cada operação, campo a campo, estão em Referência › Checkout.