Baixar pagamento de agendamento

Registra a liquidação financeira de um agendamento particular a partir de um pagamento processado externamente, executando o fluxo integrado de faturamento e baixa contábil imediata no Clínica nas Nuvens.

Pagamento Externo e Conciliação Esta operação destina-se a canais de autoatendimento externo (totens físicos, terminais TEF, maquininhas, WhatsApp e portais de pacientes). A API não captura a transação financeira diretamente nem atua como adquirente: o pagamento deve ser previamente cobrado e aprovado no meio de pagamento externo. Em seguida, este endpoint deve ser acionado enviando os dados da transação para que o sistema registre a quitação e vincule os comprovantes de conciliação (nsu, adquirente, autorizacao, terminalId).

Fluxo de Faturamento e Baixa Integrada vs. Fluxo pelo Sistema

• No fluxo operacional pelo sistema (Recepção): Na rotina presencial de balcão, a recepcionista abre o agendamento, acessa a tela de faturamento para gerar o título a receber e, em seguida, lança manualmente o recebimento e forma de pagamento no caixa da clínica.
• No fluxo de checkout externo (API): A operação é totalmente automatizada e integrada em uma única transação:
  1. A aplicação externa identifica o agendamento pendente (GET /v1/checkout/pacientes/{idPaciente}/em-aberto) e captura o pagamento no terminal;
  2. Ao receber a confirmação de sucesso, invoca este endpoint com os dados da transação aprovada;
  3. O sistema valida as regras de negócio e executa atomicamente o faturamento contábil (atualizando o status da agenda e procedimentos para faturado) e a baixa financeira imediata na conta bancária de destino vinculada à forma de pagamento, eliminando qualquer intervenção manual na recepção.

Baixar pagamento de agendamento

curl -X POST "https://api.clinicanasnuvens.com.br/v1/checkout/agendas/107598234/baixar" \
  -H "Authorization: Basic BASE64_DO_CLIENT_ID_E_SECRET" \
  -H "clinicaNasNuvens-cid: SEU_TOKEN_DE_CLINICA" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": 280.00,
    "idFormaPagamento": 224309,
    "parcelas": 1,
    "adquirente": "CIELO",
    "estabelecimento": "1234567890",
    "nsu": "123456789012",
    "autorizacao": "A1B2C3",
    "aprovadoEm": "2026-10-14T14:02:10",
    "terminalId": "totem01-unid42"
  }'

Parâmetros de rota (Path Params)

Parâmetro	Tipo	Obrigatório	Descrição
idAgenda	Integer	Sim	Identificador único do agendamento a ser faturado e baixado.

Corpo da requisição (Request Body)

Campo	Tipo	Obrigatório	Descrição
valor	Number (Double)	Sim	Valor total cobrado na transação (deve corresponder exatamente ao valor dos procedimentos particulares da agenda). Mínimo 0.01.
idFormaPagamento	Integer	Sim	Identificador único da forma de pagamento configurada no sistema.
parcelas	Integer	Sim	Quantidade de parcelas da transação (mínimo 1).
adquirente	String	Apenas Cartão	Nome da adquirente / operadora (ex. CIELO, REDE, STONE, PAGSEGURO). Obrigatório quando a forma de pagamento for do tipo cartão.
estabelecimento	String	Apenas Cartão	Código do estabelecimento comercial / credenciamento retornado pela adquirente. Obrigatório quando a forma de pagamento for do tipo cartão.
nsu	String	Apenas Cartão	Número Sequencial Único (NSU) gerado na transação. Obrigatório quando a forma de pagamento for do tipo cartão.
autorizacao	String	Não	Código de autorização retornado pela adquirente.
aprovadoEm	String (ISO 8601 sem timezone)	Apenas Cartão	Data e hora em que a transação foi aprovada na maquininha/gateway (ex: 2026-10-14T14:02:10). Obrigatório quando a forma de pagamento for do tipo cartão.
terminalId	String	Não	Identificador do totem, maquininha ou terminal que originou a transação.

Regras de negócio

• Faturamento e Baixa Integrados com Pagamento Externo: Ao receber a requisição com a transação aprovada externamente, o sistema gera o faturamento do agendamento (atualizando o status da agenda e dos procedimentos vinculados para faturado) e registra a quitação financeira imediata na conta de destino associada à forma de pagamento.
• Validação do Agendamento:
  • O agendamento informado deve existir no sistema. Caso não seja localizado, retorna erro 400 Bad Request com "Agendamento não encontrado.".
  • Agendamentos retroativos (com data anterior à data atual, data < hoje) não podem ser faturados por esta operação, retornando erro 400 Bad Request com "Agendamentos com data anterior à data atual não podem ser faturados por esta operação.".
  • Caso o agendamento já tenha sido faturado anteriormente (seja na recepção ou em chamada prévia), a operação é bloqueada retornando erro 400 Bad Request com "Este agendamento já foi faturado na recepção.".
  • O agendamento deve pertencer obrigatoriamente a um convênio particular. Agendas vinculadas a convênios de saúde não podem ser faturadas por este endpoint, retornando erro 400 Bad Request com "Agendamentos vinculados a convênios não podem ser faturados por esta operação.".
  • Agendamentos com faturamento descartado no sistema (marcados como não cobrar ou não faturar) não podem ser faturados, retornando erro 400 Bad Request com "O faturamento deste agendamento foi descartado.".
• Validação de Valor e Arredondamento:
  • O campo valor informado na requisição deve ser exatamente igual ao somatório dos procedimentos particulares do agendamento (avaliado em duas casas decimais).
  • Em caso de qualquer divergência de centavos, retorna erro 400 Bad Request com "O valor informado diverge do saldo a pagar.".
• Validação da Forma de Pagamento e Parcelas:
  • A forma de pagamento indicada em idFormaPagamento deve existir, estar ativa, possuir a opção Disponível para recebimento externo habilitada e não ser do tipo Pagar (apenas tipos Receber ou Ambos são permitidos). Caso contrário, retorna erro 400 Bad Request com "Forma de pagamento inativa ou não habilitada para autoatendimento." ou "Forma de pagamento do tipo Pagar não é permitida para recebimento.".
  • Se a quantidade de parcelas for maior que 1, a forma de pagamento deve ser de um tipo de documento que permita parcelamento e a quantidade não pode exceder o valor limite de maximo_parcelas configurado. Caso contrário, retorna erro 400 Bad Request com "Quantidade de parcelas inválida para a forma de pagamento selecionada.".
• Campos Obrigatórios Condicionais para Cartão:
  • Quando a forma de pagamento for do tipo cartão (CARTAO_CREDITO ou CARTAO_DEBITO), os campos adquirente, estabelecimento, nsu e aprovadoEm tornam-se de preenchimento obrigatório. A ausência de qualquer um deles retorna erro 400 Bad Request com a respectiva mensagem (ex: "O campo adquirente é obrigatório para pagamentos com cartão.").
  • Para formas de pagamento que não envolvam cartão (como Pix ou dinheiro), esses campos são opcionais.
• Rateio e Competência Contábil:
  • O faturamento é criado na competência atual com tipo a receber, associando automaticamente o rateio da receita à subcategoria contábil padrão do cliente/fornecedor ou à primeira categoria de receita ativa configurada na clínica.
• Composição e Vencimento das Parcelas:
  • Quando houver parcelamento (mais de 1 parcela), o montante total é dividido igualmente entre o número de parcelas solicitado, atribuindo eventuais diferenças de centavos resultantes do arredondamento à primeira parcela.
  • As datas de vencimento de cada parcela são calculadas dinamicamente com base nas regras de intervalo de cobrança da forma de pagamento.
• Rastreabilidade e TEF:
  • Para transações efetuadas com cartão, os dados da maquininha (nsu, adquirente, estabelecimento, autorizacao, parcelas e terminalId) são persistidos no registro de pagamento para conciliação contábil e auditoria no Clínica nas Nuvens.

Exemplos de resposta

Pagamento processado com sucesso (200 OK)

{
  "idAgenda": 107598234,
  "idFatura": 24038497,
  "status": "PAGA",
  "resultado": "BAIXADO"
}

Exemplos de erro de validação (400 Bad Request)

{
  "mensagem": "O valor informado diverge do saldo a pagar."
}

{
  "mensagem": "Este agendamento já foi faturado na recepção."
}

{
  "mensagem": "Forma de pagamento inativa ou não habilitada para autoatendimento."
}

{
  "mensagem": "O campo adquirente é obrigatório para pagamentos com cartão."
}

Veja na Referência

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