Contratos
Esta página descreve os endpoints da tela Contratos, do menu Comercial. Um contrato registra o acordo com uma empresa cliente para um conjunto de cursos com valores fixos. Ao concluir o contrato, o sistema vincula os alunos elegíveis e aplica a eles o valor contratado.
Os cursos do contrato têm a página Cursos do contrato, e os alunos vinculados têm a página Alunos do contrato.
As regras gerais (cabeçalhos, paginação e erros) estão em Convenções.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
| GET | /comercial/contracts | Lista os contratos |
| POST | /comercial/contracts | Cadastra um contrato |
| GET | /comercial/contracts/{uuid} | Consulta um contrato |
| PUT | /comercial/contracts/{uuid} | Altera um contrato em preparação |
| DELETE | /comercial/contracts/{uuid} | Apaga um contrato sem alunos vinculados |
| PATCH | /comercial/contracts/{uuid}/conclude | Conclui o contrato e vincula os alunos |
| PATCH | /comercial/contracts/{uuid}/cancel | Cancela o contrato |
| PATCH | /comercial/contracts/{uuid}/check-students | Reprocessa a vinculação dos alunos |
| GET | /comercial/contracts/statuses | Lista os status de contrato |
| GET | /comercial/contracts/modalities | Lista as modalidades de treinamento |
| GET | /comercial/contracts/companies | Lista as empresas do cadastro do cliente, para o campo Filial |
| GET | /comercial/contracts/business | Lista as empresas clientes ativas, para o campo Empresa |
Status do contrato
O campo status_id do contrato tem estes valores:
status_id | Status | Significado |
|---|---|---|
| 1 | Em preparação | Contrato em montagem. Pode ser alterado, e os cursos podem ser incluídos, alterados ou removidos |
| 2 | Ativo | Contrato concluído. Não pode mais ser alterado, e os alunos elegíveis já foram vinculados |
| 3 | Cancelado | Contrato cancelado |
Um contrato ativo cuja data de término já passou passa a Vencido automaticamente, por rotina diária do sistema. A lista completa de status está em GET /comercial/contracts/statuses.
Consultar
GET /comercial/contracts
Lista os contratos da empresa cliente. Sem ordenação, os contratos em preparação e ativos aparecem primeiro; dentro de cada grupo, o contrato com data de início mais recente vem antes.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
search | Texto livre: código, nome da empresa, filial, cliente (nome, razão social ou documento), status, observação e curso (nome, nome curto ou código) |
code | Código do contrato |
customer_vendor_id | Contratos da empresa cliente informada (id) |
customer_vendor_uuid | Contratos da empresa cliente informada (uuid) |
status_id | Contratos com o status informado |
start_date e end_date | Filtro por período. Com os dois, ambas as datas do contrato devem estar dentro do período informado. Com um só, filtra pela data exata |
column e order | Ordenação: nome da coluna e asc ou desc |
Resposta: lista. Campos principais: uuid, id, code, company_uuid, company_name, company_document, customer_vendor_id, customer_name, customer_document, start_date, end_date, status_id, status_name, origin_contract_id, observation, students_count (quantidade de alunos vinculados) e os dados de criação e alteração.
GET /comercial/contracts/{uuid}
Consulta um contrato. A resposta traz os cursos do contrato (contract_courses), a filial, o cliente e o status.
Cadastrar e alterar
POST /comercial/contracts
Cadastra um contrato. O contrato entra em preparação, com código sequencial por cliente.
Para copiar um contrato, envie source_uuid. O novo contrato recebe os cursos do contrato de origem, com curso, modalidade, quantidade, valor, vouchers e a marcação de online. Os alunos não são copiados, e o novo contrato guarda a referência ao contrato de origem.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
customer_vendor_id | Sim | Número (id) | Empresa cliente do contrato. Veja GET /comercial/contracts/business |
start_date | Condicional | Data | Início do período. Obrigatória quando há end_date |
end_date | Não | Data | Fim do período |
company_id | Não | Número (id) | Filial, quando o contrato é de uma empresa do próprio cliente. Veja GET /comercial/contracts/companies |
observation | Não | Texto | Texto livre sobre o contrato |
source_uuid | Não | Texto (uuid) | uuid de um contrato existente, para copiar os cursos dele |
Exemplo
curl -X POST "https://api.pedagogo.app/comercial/contracts" \
-H "Authorization: Bearer <token-de-sessao>" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"customer_vendor_id": 123, "start_date": "2026-01-01", "end_date": "2026-12-31", "observation": "Contrato exemplo"}'
Resposta: 200 com o contrato criado, incluindo uuid, id, code e status_id (1).
PUT /comercial/contracts/{uuid}
Altera um contrato. Só é possível alterar contrato em preparação. Para outros status, a alteração é recusada com a mensagem You cannot edit a contract that is not In preparation..
Os campos são os mesmos do cadastro, todos opcionais nesta alteração, exceto a regra de start_date quando há end_date.
Resposta: 200 com o contrato alterado. Se recusado, a resposta traz message.
DELETE /comercial/contracts/{uuid}
Apaga o contrato. A exclusão é lógica. Contrato com alunos vinculados não pode ser apagado, independentemente do status: a resposta traz a mensagem You cannot delete a contract that has students..
Resposta: 200, sem corpo. Se recusado, a resposta traz message.
Conclusão, cancelamento e alunos
PATCH /comercial/contracts/{uuid}/conclude
Conclui o contrato. Só é possível concluir contrato em preparação. O contrato passa para Ativo (status_id 2), e um job em fila vincula os alunos elegíveis. As regras de elegibilidade estão na tela Contratos. A vinculação roda em segundo plano, e não aparece na resposta.
Se o contrato não está em preparação, a conclusão é recusada com a mensagem You cannot conclude a contract that is not In preparation..
Não há corpo nesta chamada.
Resposta: 200 com o contrato concluído.
PATCH /comercial/contracts/{uuid}/cancel
Cancela o contrato. O status passa para Cancelado (status_id 3). Os alunos já vinculados continuam vinculados ao contrato. O vínculo de um aluno só muda quando o contrato dele passa a Vencido ou é apagado.
Não há corpo nesta chamada.
Resposta: 200 com o contrato cancelado.
PATCH /comercial/contracts/{uuid}/check-students
Dispara um job em fila que reprocessa a vinculação dos alunos do contrato.
Resposta: 200 com {"message": "Students updated successfully"}.
Listas de apoio
GET /comercial/contracts/statuses
Lista os status de contrato. Campos: id e status. Parâmetros: column e order.
GET /comercial/contracts/modalities
Lista as modalidades de treinamento. Use o id no campo modality_id dos cursos do contrato. Campos: id, uuid e modality. Parâmetro: search.
GET /comercial/contracts/companies
Lista as empresas do cadastro do cliente, para o campo company_id (Filial). Use o id retornado.
GET /comercial/contracts/business
Lista as empresas clientes ativas, para o campo customer_vendor_id (Empresa). Use o id retornado.