POST Receber Pagamento
Registra um pagamento (movimentação) no orçamento do agendamento, dentro do caixa aberto do usuário.
Envie o header Authorization: Bearer {accessToken} (token de usuário) ou x-api-key: {apiKey} (integrações). Veja Autenticação.
O id pode ser obtido na rota de Listar Agendamentos, no campo data[].id de cada agendamento.
1. O orçamento do agendamento precisa ter sido preparado antes, com POST /api/appointments/{id}/prepare-payment (cria o orçamento se ainda não existir — idempotente). Sem isso a rota retorna 400.
2. O usuário precisa ter um caixa aberto — veja Abrir Caixa. O cashManagementId é o data.id retornado em Buscar Caixa do Usuário.
Quando o orçamento fica totalmente coberto (pago, ou pendente via skipPayment), o sistema enfileira internamente a entrada do agendamento na fila de atendimento e o envio do pedido ao laboratório. O status do agendamento não é alterado diretamente por esta rota.
Endpoint
POST https://api-dev.imagemais.com.br/api/appointments/{id}/receive-payment
Path Parameter
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | number | ✅ | ID do agendamento |
Corpo da Requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
cashManagementId | number | ✅ | ID do caixa aberto do usuário (inteiro positivo) |
paymentMethod | string (enum) | ✅ | Método de pagamento — ver valores abaixo |
value | number | ✅ | Valor pago (>= 0). A soma dos pagamentos não pode ultrapassar o total do orçamento |
action | string (enum) | ✅ | Obrigatório pela validação (herdado de Atualizar Status): Agendado, Confirmado, Na fila, Em atendimento, Cancelado, Finalizado, Faltou. Não é usado para alterar o status |
flag | string (enum) | ❌ | Bandeira do cartão: Visa, Mastercard, Elo, American Express, Hipercard |
installments | number | ❌ | Número de parcelas (inteiro positivo). Só é gravado quando flag é informado |
skipPayment | boolean | ❌ | true pula o pagamento e cria uma movimentação pendente pelo saldo restante (ignora value). Requer a permissão skip_payment |
protocol | string | ❌ | Aceito pela validação, mas não é gravado |
doctorId | number | ❌ | Aceito pela validação, mas não é usado |
Valores de paymentMethod
BOLETO_BANCARIO, CARTAO_CREDITO, CARTAO_DEBITO, CARTEIRA_DIGITAL, CASHBACK, CHEQUE, CREDITO_LOJA, CREDITO_VIRTUAL, DEPOSITO_BANCARIO, DINHEIRO, OUTRO, DEBITO_AUTOMATICO, CARTAO_CREDITO_VIA_LINK, PIX_PAGAMENTO_INSTANTANEO, PIX_COBRANCA, PROGRAMA_FIDELIDADE, SEM_PAGAMENTO, TRANSFERENCIA_BANCARIA, VALE_ALIMENTACAO, VALE_COMBUSTIVEL, VALE_PRESENTE, VALE_REFEICAO
Requisição
curl -X 'POST' \
'https://api-dev.imagemais.com.br/api/appointments/5285/receive-payment' \
-H 'accept: */*' \
-H 'Authorization: Bearer {accessToken}' \
-H 'Content-Type: application/json' \
-d '{
"action": "Na fila",
"cashManagementId": 12,
"paymentMethod": "CARTAO_CREDITO",
"value": 252,
"flag": "Visa",
"installments": 1
}'
Respostas
200 Sucesso
Retorna corpo vazio. O pagamento foi registrado.
400 Bad Request
Retornado quando o orçamento do agendamento ainda não foi preparado.
{
"message": "Orçamento não preparado. Acesse a tela de pagamento novamente.",
"error": "Bad Request",
"statusCode": 400
}
Retornado quando o valor faria a soma dos pagamentos ultrapassar o total do orçamento.
{
"message": "Valor do movimento não pode ser maior que o orçamento",
"error": "Bad Request",
"statusCode": 400
}
Retornado quando skipPayment é enviado mas o orçamento já está totalmente coberto.
{
"message": "Orçamento já está totalmente coberto",
"error": "Bad Request",
"statusCode": 400
}
Retornado quando algum campo obrigatório falta ou é inválido (exemplo com corpo vazio).
{
"message": [
"paymentMethod should not be empty",
"Método de pagamento inválido",
"Valor deve ser maior que 0",
"Valor deve ser um número",
"cashManagementId should not be empty",
"cashManagementId must be a positive number",
"cashManagementId must be an integer number",
"action should not be empty",
"action must be one of the following values: Agendado, Confirmado, Na fila, Em atendimento, Cancelado, Finalizado, Faltou"
],
"error": "Bad Request",
"statusCode": 400
}
403 Sem permissão para pular o pagamento
Retornado quando skipPayment: true é enviado por um usuário sem a permissão skip_payment.
{
"message": "Permissões insuficientes para pular o pagamento",
"error": "Forbidden",
"statusCode": 403
}
404 Não Encontrado
Retornado quando o agendamento não existe na conta.
{
"message": "Agendamento não encontrado",
"error": "Not Found",
"statusCode": 404
}
Retornado quando o cashManagementId não corresponde a um caixa aberto.
{
"message": "Caixa aberto não encontrado",
"error": "Not Found",
"statusCode": 404
}