Ponto de venda
Esta página descreve os endpoints da tela Ponto de venda, do menu Comercial. O ponto de venda registra a venda de treinamentos para um aluno. Uma venda reúne cursos avulsos e combos, os pagamentos recebidos e, quando concluída, gera os lançamentos de recebimento no módulo financeiro.
A venda tem três áreas, que correspondem às subpáginas desta referência: Combos, Pagamentos e Cursos.
As regras gerais (cabeçalhos, paginação e erros) estão em Convenções.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
| GET | /comercial/point-of-sales | Lista as vendas |
| POST | /comercial/point-of-sales | Cadastra uma venda |
| GET | /comercial/point-of-sales/{uuid} | Consulta uma venda |
| PUT | /comercial/point-of-sales/{uuid} | Altera a data ou o aluno da venda |
| DELETE | /comercial/point-of-sales/{uuid} | Apaga uma venda (exclusão lógica) |
| PATCH | /comercial/point-of-sales/{uuid}/conclude | Conclui a venda |
| GET | /comercial/point-of-sales/students | Lista os alunos de empresa, para o campo Nome da venda |
| GET | /comercial/point-of-sales/payment-methods | Lista as formas de pagamento |
| GET | /comercial/point-of-sales/{sale_uuid}/payments | Lista os pagamentos da venda |
| POST | /comercial/point-of-sales/{sale_uuid}/payments | Registra um pagamento |
| GET | /comercial/point-of-sales/{sale_uuid}/payments/{id} | Consulta um pagamento |
| PUT | /comercial/point-of-sales/{sale_uuid}/payments/{id} | Altera um pagamento |
| DELETE | /comercial/point-of-sales/{sale_uuid}/payments/{id} | Apaga um pagamento (exclusão lógica) |
| GET | /comercial/point-of-sales/{training_sale_uuid}/combos | Lista os combos da venda |
| POST | /comercial/point-of-sales/{training_sale_uuid}/combos | Adiciona um combo à venda |
| GET | /comercial/point-of-sales/{training_sale_uuid}/combos/{id} | Consulta um combo da venda |
| DELETE | /comercial/point-of-sales/{training_sale_uuid}/combos/{id} | Remove um combo da venda |
| GET | /comercial/point-of-sales/{training_sale_uuid}/combos/{id}/payment-receipt | Gera o recibo em PDF do combo |
| GET | /comercial/point-of-sales/{training_sale_uuid}/courses | Lista os cursos da venda |
| POST | /comercial/point-of-sales/{training_sale_uuid}/courses | Adiciona um curso à venda |
| GET | /comercial/point-of-sales/{training_sale_uuid}/courses/{id} | Consulta um curso da venda |
| PUT | /comercial/point-of-sales/{training_sale_uuid}/courses/{id} | Altera um curso da venda |
| DELETE | /comercial/point-of-sales/{training_sale_uuid}/courses/{id} | Remove um curso da venda |
Vendas
GET /comercial/point-of-sales
Lista as vendas da empresa cliente.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
search | Texto livre: data, valor ou situação de pagamento da venda |
column e order | Ordenação: nome da coluna e asc ou desc |
Resposta: lista. Campos principais: uuid, id, date, amount (total da venda), concluded, customer_vendor_student_id, customer_vendor_name, customer_vendor_document, customer_vendor_passport, user_create_name e user_update_name.
GET /comercial/point-of-sales/{uuid}
Consulta uma venda. A resposta traz os cursos da venda, os pagamentos (com a forma de pagamento) e os combos (com os dados do combo).
POST /comercial/point-of-sales
Cadastra uma venda. A venda entra sem cursos, combos nem pagamentos.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
customer_vendor_student_id | Sim | Número (id) | Aluno de empresa cadastrado para o cliente. Veja GET /comercial/point-of-sales/students |
date | Sim | Data | Data da venda |
Exemplo
curl -X POST "https://api.pedagogo.app/comercial/point-of-sales" \
-H "Authorization: Bearer <token-de-sessao>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"customer_vendor_student_id": 987, "date": "2026-03-10"}'
Resposta: 200 com a venda criada, incluindo uuid e id.
PUT /comercial/point-of-sales/{uuid}
Altera a data ou o aluno da venda. Os dois campos são opcionais.
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
customer_vendor_student_id | Não | Número (id) | Aluno da venda |
date | Não | Data | Data da venda |
Resposta: 200 com a venda alterada.
DELETE /comercial/point-of-sales/{uuid}
Apaga a venda. A exclusão é lógica.
Resposta: 200, sem corpo.
Conclusão
PATCH /comercial/point-of-sales/{uuid}/conclude
Conclui a venda. Para concluir, a venda precisa atender a todas as condições abaixo:
- ainda não estar concluída;
- ter pelo menos um curso, direto ou vindo de um combo;
- a soma dos pagamentos não ser menor que o total da venda.
Ao concluir, cada pagamento gera um lançamento de recebimento no módulo financeiro, com a data e o valor do pagamento e a categoria da forma de pagamento. A venda fica marcada como concluída.
A resposta é texto simples, sem JSON. Quando a conclusão é recusada, o texto traz o motivo:
A venda já foi concluída anteriormente;Deve haver pelo menos um curso registrado;O total de pagamentos registrados deve ser igual ao total de cursos registrados.
Quando a venda é concluída, o texto é A venda foi concluída com sucesso.
Resposta: 200 com o texto do resultado.
Listas de apoio
GET /comercial/point-of-sales/students
Lista os alunos de empresa cadastrados para o cliente. Use o id no campo customer_vendor_student_id. Parâmetro: search (nome, documento, telefone, e-mail ou identificador do aluno).
GET /comercial/point-of-sales/payment-methods
Lista as formas de pagamento cadastradas no módulo financeiro. Use o id no campo payment_method_id dos pagamentos. Parâmetros: search (nome da forma de pagamento), column e order.
Pagamentos da venda
GET /comercial/point-of-sales/{sale_uuid}/payments
Lista os pagamentos da venda. Parâmetros: search (nome da forma de pagamento) e column e order.
Resposta: lista. Campos principais: id, sale_id, payment_method_id, date, amount, document_number, financial_release_id e os dados de criação e alteração.
POST /comercial/point-of-sales/{sale_uuid}/payments
Registra um pagamento recebido pela venda. Não há controle automático de parcelas: para um pagamento parcelado, registre um pagamento para cada parcela, com a data e o valor dela.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
payment_method_id | Sim | Número (id) | Forma de pagamento. Veja GET /comercial/point-of-sales/payment-methods |
date | Sim | Data | Data do pagamento |
amount | Sim | Número | Valor recebido neste pagamento |
document_number | Não | Texto | Número do documento relacionado ao pagamento |
Resposta: 200 com o pagamento registrado.
GET /comercial/point-of-sales/{sale_uuid}/payments/{id}
Consulta um pagamento pelo id. A resposta traz o registro com os dados da venda.
PUT /comercial/point-of-sales/{sale_uuid}/payments/{id}
Altera um pagamento. Os campos são os mesmos do cadastro, todos opcionais nesta alteração.
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
payment_method_id | Não | Número (id) | Forma de pagamento |
date | Não | Data | Data do pagamento |
amount | Não | Número | Valor do pagamento |
document_number | Não | Texto | Número do documento |
Resposta: 200 com o pagamento alterado.
DELETE /comercial/point-of-sales/{sale_uuid}/payments/{id}
Apaga o pagamento. A exclusão é lógica.
Resposta: 200.
Combos da venda
GET /comercial/point-of-sales/{training_sale_uuid}/combos
Lista os combos adicionados à venda. Parâmetro: search (nome do combo).
Resposta: lista. Campos principais: id, training_sale_id, combo_id, combo_uuid, combo e updated_at.
POST /comercial/point-of-sales/{training_sale_uuid}/combos
Adiciona um combo à venda. Todos os cursos do combo entram na venda com o valor definido no combo. Se o combo já tinha sido removido desta venda, a inclusão restaura os cursos. O total da venda é recalculado.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
combo_id | Sim | Texto (uuid) | uuid do combo. Veja GET /comercial/combos |
Resposta: 200 com o combo adicionado à venda.
GET /comercial/point-of-sales/{training_sale_uuid}/combos/{id}
Consulta um combo da venda pelo id. A resposta traz o registro com a venda, o combo e os cursos que vieram dele.
DELETE /comercial/point-of-sales/{training_sale_uuid}/combos/{id}
Remove o combo da venda. Os cursos que vieram do combo também saem da venda, e o total é recalculado. Um combo não pode ser removido de uma venda concluída.
Resposta: 200, sem corpo. Se a venda está concluída, a resposta é 400, com o texto Venda concluída, não é possível remover o combo.
GET /comercial/point-of-sales/{training_sale_uuid}/combos/{id}/payment-receipt
Gera o recibo de pagamento do combo, em PDF.
Resposta: arquivo PDF para download.
Cursos da venda
GET /comercial/point-of-sales/{training_sale_uuid}/courses
Lista os cursos da venda, avulsos e vindos de combos. Parâmetros: search (nome do curso ou do combo) e column e order.
Resposta: lista. Campos principais: id, training_sale_id, course_id, course, combo_course_id, amount, training_student_id, student (nome do aluno, quando o curso está ligado a uma turma) e updated_at.
POST /comercial/point-of-sales/{training_sale_uuid}/courses
Adiciona um curso à venda, com o valor cobrado por ele nesta venda. Se o curso já está na venda, o valor é atualizado, em vez de criar outro registro. O total da venda é recalculado.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
course_id | Sim | Número (id) | Curso vendido. Use o id retornado pela listagem de cursos |
amount | Sim | Número | Valor cobrado por este curso nesta venda |
Resposta: 200 com o curso adicionado à venda.
GET /comercial/point-of-sales/{training_sale_uuid}/courses/{id}
Consulta um curso da venda pelo id. A resposta traz o registro com a venda, o curso, o combo e o aluno, quando houver.
PUT /comercial/point-of-sales/{training_sale_uuid}/courses/{id}
Altera o curso ou o valor dele nesta venda. O total da venda é recalculado quando o valor muda.
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
course_id | Não | Número (id) | Curso vendido |
amount | Não | Número | Valor cobrado por este curso nesta venda |
Resposta: 200 com o registro alterado.
DELETE /comercial/point-of-sales/{training_sale_uuid}/courses/{id}
Remove o curso da venda. O total é recalculado. Não é possível remover um curso de uma venda concluída, nem um curso que veio de um combo enquanto o combo estiver na venda. Para retirar esses cursos, remova o combo.
Resposta: 200. Se a remoção é recusada, a resposta traz message com o motivo.