Skip to main content

POST Receber Pagamento

Registra um pagamento (movimentação) no orçamento do agendamento, dentro do caixa aberto do usuário.

Autenticação necessária

Envie o header Authorization: Bearer {accessToken} (token de usuário) ou x-api-key: {apiKey} (integrações). Veja Autenticação.

ID do agendamento

O id pode ser obtido na rota de Listar Agendamentos, no campo data[].id de cada agendamento.

Pré-requisitos

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.

O que acontece depois

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​

CampoTipoObrigatórioDescrição
idnumber✅ID do agendamento

Corpo da Requisição​

CampoTipoObrigatórioDescrição
cashManagementIdnumber✅ID do caixa aberto do usuário (inteiro positivo)
paymentMethodstring (enum)✅Método de pagamento — ver valores abaixo
valuenumber✅Valor pago (>= 0). A soma dos pagamentos não pode ultrapassar o total do orçamento
actionstring (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
flagstring (enum)❌Bandeira do cartão: Visa, Mastercard, Elo, American Express, Hipercard
installmentsnumber❌Número de parcelas (inteiro positivo). Só é gravado quando flag é informado
skipPaymentboolean❌true pula o pagamento e cria uma movimentação pendente pelo saldo restante (ignora value). Requer a permissão skip_payment
protocolstring❌Aceito pela validação, mas não é gravado
doctorIdnumber❌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
}