Baixar pagamento de fatura existente

Registra a liquidação financeira de uma fatura ou conta a receber em aberto no sistema a partir de um pagamento processado externamente, executando a baixa direta do título contábil 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 realiza a captura financeira nem processa cobranças diretamente no cartão: a cobrança deve ser efetuada e aprovada previamente no meio de pagamento externo. Em seguida, este endpoint deve ser acionado informando os dados da transação para que o sistema liquide a fatura e armazene os comprovantes de conciliação (nsu, adquirente, autorizacao, terminalId).

Fluxo de Baixa Direta Externa vs. Fluxo pelo Sistema

• No fluxo operacional pelo sistema (Financeiro/Recepção): No dia a dia da clínica, o operador acessa o módulo financeiro em Contas a Receber, localiza o título do paciente e realiza a quitação manual, selecionando o caixa e a forma de pagamento recebida no balcão.
• No fluxo de checkout externo (API): A liquidação é feita de forma automática e integrada:
  1. A aplicação externa consulta as pendências do paciente (GET /v1/checkout/pacientes/{idPaciente}/em-aberto) e apresenta a fatura para pagamento;
  2. O paciente conclui o pagamento no terminal externo (maquininha TEF, cartão ou Pix);
  3. A aplicação externa invoca este endpoint informando o idFatura e os dados do comprovante da transação aprovada;
  4. O sistema valida se a fatura está ativa e em aberto, confirma a exatidão do valor pago e registra a baixa financeira imediata na conta de destino vinculada à forma de pagamento, atualizando o saldo devedor sem necessidade de intervenção manual da equipe da clínica.

Baixar pagamento de fatura

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

Parâmetros de rota (Path Params)

Parâmetro	Tipo	Obrigatório	Descrição
idFatura	Integer	Sim	Identificador único da fatura a ser baixada.

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 saldo em aberto da fatura). 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:15:30). 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

• Baixa Financeira Direta com Pagamento Externo: A fatura em aberto é localizada e a quitação é registrada imediatamente na conta de destino vinculada à forma de pagamento com base na transação aprovada externamente.
• Validação da Fatura:
  • A fatura informada deve existir no sistema. Caso não seja encontrada, retorna erro 400 Bad Request com "Fatura não encontrada.".
  • Faturas com vencimento em atraso (com vencimento anterior à data atual, vencimento < hoje) não podem ser baixadas por esta operação, retornando erro 400 Bad Request com "Faturas com vencimento em atraso não podem ser baixadas por esta operação.".
  • Se a fatura tiver sido cancelada ou estornada no sistema, a baixa é impedida retornando erro 400 Bad Request com "Esta fatura foi cancelada ou estornada no sistema.".
  • Se a fatura já se encontrar quitada (seja por quitação anterior no balcão ou chamada duplicada), a operação é bloqueada retornando erro 400 Bad Request com "Esta fatura já foi quitada.".
• Validação de Valor e Arredondamento:
  • O campo valor informado na requisição deve corresponder exatamente ao saldo em aberto da fatura (valorRestante, arredondado em duas casas decimais).
  • Em caso de qualquer divergência, a API rejeita a baixa retornando 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 superior a 1, a forma de pagamento deve ser de um tipo de documento que permita parcelamento e a quantidade não pode ultrapassar o limite máximo (maximo_parcelas). 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 são obrigatórios. O envio de campos vazios ou nulos resulta em erro de validação (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.
• Composição e Vencimento das Parcelas:
  • Quando a transação for parcelada (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 de acordo com as regras de previsão de vencimento da forma de pagamento.
• Rastreabilidade e TEF:
  • Para pagamentos em cartão, os dados de comprovante (nsu, adquirente, estabelecimento, autorizacao, parcelas e terminalId) são gravados na transação financeira para conferência no financeiro e auditoria contábil.

Exemplos de resposta

Pagamento processado com sucesso (200 OK)

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

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

{
  "mensagem": "Esta fatura já foi quitada."
}

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

{
  "mensagem": "Esta fatura foi cancelada ou estornada no sistema."
}

{
  "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.