Faturados
Um faturamento reúne os treinamentos de uma empresa em um período, com os totais e a situação de conclusão. Corresponde à tela Faturados do menu Faturamento. Dentro de cada faturamento, os alunos são incluídos e removidos, os valores são conferidos e o faturamento é concluído. Um faturamento pode ser aberto a partir de À faturar ou cadastrado direto nesta tela.
Os endereços a seguir são relativos a https://api.pedagogo.app. O faturamento é identificado pelo uuid. Os caminhos de alunos e de À faturar do faturamento também são listados em À faturar, com o mesmo comportamento.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
| GET | /invoicing/billings | Lista os faturamentos |
| POST | /invoicing/billings | Cadastra um faturamento |
| GET | /invoicing/billings/{uuid} | Consulta um faturamento |
| PUT | /invoicing/billings/{uuid} | Altera um faturamento |
| DELETE | /invoicing/billings/{uuid} | Apaga um faturamento |
| PATCH | /invoicing/billings/{uuid}/conclude | Conclui o faturamento, ou desfaz a conclusão |
| GET | /invoicing/billings/{uuid}/statement-of-trainigs | Demonstrativo do faturamento em PDF |
| GET | /invoicing/billings/business | Empresas para o campo Empresa (lista de apoio) |
| GET | /invoicing/billings/{billing_uuid}/billed-students | Alunos incluídos no faturamento |
| DELETE | /invoicing/billings/{billing_uuid}/billed-students/{id} | Remove um aluno do faturamento |
| PUT | /invoicing/billings/{billing_uuid}/students/{uuid} | Altera o aluno do treinamento incluído no faturamento |
| GET | /invoicing/billings/{billing_uuid}/to-bill-students | Alunos da empresa que ainda podem ser incluídos |
| POST | /invoicing/billings/{billing_uuid}/to-bill-students | Inclui alunos no faturamento |
Listar
GET /invoicing/billings
Lista os faturamentos da empresa cliente. Sem ordenação informada, a lista vem com os não concluídos primeiro, do início mais recente para o mais antigo.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
search | Texto livre. Busca no nome da empresa, no código do faturamento e no nome ou razão social do cliente |
code | Código do faturamento |
business | Texto. Busca pelo nome ou pela razão social da empresa cobrada |
customer_vendor_id | Filtra pela empresa cobrada (id) |
customer_vendor_uuid | Filtra pela empresa cobrada (uuid) |
company_id | Filtra pela empresa ou filial emissora (id) |
concluded | 1 para concluídos, 0 para não concluídos |
columnName e orderData | Ordena pela coluna informada e pelo sentido (asc ou desc) |
per_page e page | Paginação, conforme Convenções |
Resposta (200): lista de faturamentos, com id, uuid, code, company_id, company_name, customer_vendor_id, customer_vendor_uuid, customer_vendor_name, customer_vendor_document, start_date, end_date, total_students, total_expenses, total_amount, quantity_students, concluded, observations, comments, o objeto invoice quando o faturamento está vinculado a uma nota, e os nomes de quem criou e alterou o registro.
Consultar
GET /invoicing/billings/{uuid}
Devolve o faturamento com o uuid informado, com os dados da empresa cobrada e da empresa emissora.
Cadastrar
POST /invoicing/billings
Cadastra um faturamento. Se a empresa já tiver um faturamento aberto, sem alunos e não concluído, esse faturamento é atualizado com os dados enviados e devolvido, em vez de criar outro.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
customer_vendor_id | Sim | Número | Empresa cobrada (id de /invoicing/billings/business) |
start_date | Sim | Data | Início do período do faturamento |
end_date | Sim | Data | Fim do período do faturamento |
company_id | Não | Número | Empresa ou filial emissora (id de /invoicing/pending-billings/companies) |
observations | Não | Texto | Observações do faturamento |
comments | Não | Texto | Comentários do faturamento |
Resposta (201): o faturamento criado, ou o faturamento aberto que foi atualizado.
curl -X POST https://api.pedagogo.app/invoicing/billings \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token-de-sessao>" \
-d '{"customer_vendor_id": 1, "start_date": "2026-11-01", "end_date": "2026-11-30", "observations": "Observação exemplo"}'
Alterar e apagar
PUT /invoicing/billings/{uuid}
Altera empresa, datas, observações e comentários.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
customer_vendor_id | Sim | Número | Empresa cobrada |
start_date | Sim | Data | Início do período |
end_date | Sim | Data | Fim do período |
company_id | Não | Número | Empresa ou filial emissora |
observations | Não | Texto | Observações |
comments | Não | Texto | Comentários |
Resposta (200): o faturamento alterado.
DELETE /invoicing/billings/{uuid}
Apaga o faturamento e remove os alunos a ele vinculados. Resposta 200, sem corpo.
Concluir
PATCH /invoicing/billings/{uuid}/conclude
Alterna a conclusão do faturamento: se estiver concluído, passa a não concluído, e o contrário. Sem corpo.
Resposta (200): o faturamento, com o campo concluded atualizado.
Ao vincular uma nota fiscal ao faturamento, a conclusão é marcada automaticamente. Veja Notas fiscais.
Demonstrativo
GET /invoicing/billings/{uuid}/statement-of-trainigs
Demonstrativo dos treinamentos do faturamento.
Resposta (200): arquivo PDF para download.
Alunos do faturamento
GET /invoicing/billings/{billing_uuid}/billed-students
Lista os alunos incluídos no faturamento, com os dados do treinamento: aluno, curso, datas, valor, status, centro de custo, código do contrato, código da turma e o total de despesas faturadas.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
search | Texto livre. Busca no nome ou no documento do aluno, no centro de custo, no curso e no código do curso |
cost_center_id | Filtra pelo centro de custo (id). Use -1 para alunos sem centro de custo |
course_id | Filtra pelo curso (id) |
columnName e orderData | Ordena pela coluna informada e pelo sentido (asc ou desc) |
per_page e page | Paginação, conforme Convenções |
Resposta (200): lista de alunos do faturamento, com id (do vínculo), training_student_uuid, student_name, student_document, course_name, start_date, end_date, amount, status_id, student_status, cost_center, code, contract_code, totalExpenses e os nomes de quem criou e alterou o vínculo.
DELETE /invoicing/billings/{billing_uuid}/billed-students/{id}
Remove um aluno do faturamento. O aluno volta a aparecer em to-bill-students. Os totais do faturamento são recalculados. Resposta 200, sem corpo.
PUT /invoicing/billings/{billing_uuid}/students/{uuid}
Altera o treinamento de um aluno incluído no faturamento. O uuid do caminho é o uuid do aluno do treinamento, e o corpo segue as regras do cadastro do aluno no treinamento.
Atenção: a alteração é gravada no treinamento do aluno, no módulo Comercial, e não apenas neste faturamento. O valor e o centro de custo passam a valer também fora do faturamento. Os totais do faturamento são recalculados.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
customer_vendor_student_id | Sim | Número | Aluno (vínculo empresa e aluno) |
start_date | Sim | Data | Data de início do treinamento |
amount | Sim | Número | Valor do treinamento. Se for 0, justification_gratuity é obrigatório |
justification_gratuity | Sim se amount for 0 | Texto | Justificativa da gratuidade |
cost_center_id | Não | Número | Centro de custo do treinamento |
course_id | Não | Número | Curso |
company_id | Não | Número | Empresa |
customer_vendor_business_id | Não | Número | Empresa cobrada |
contract_course_id | Não | Número | Curso do contrato |
validity | Não | Número inteiro | Validade |
end_date | Não | Data | Data de término |
practice_date | Não | Data | Data da prática |
Resposta (200): o registro do aluno do treinamento alterado.
GET /invoicing/billings/{billing_uuid}/to-bill-students
Lista os alunos da empresa cobrada cujo treinamento começou dentro do período do faturamento, e que ainda não estão incluídos em nenhum faturamento. Não entram alunos com status Cancelado nem treinamentos de turmas excluídas.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
search | Texto livre. Busca no nome ou no documento do aluno, no centro de custo e no curso |
columnName e orderData | Ordena pela coluna informada e pelo sentido (asc ou desc) |
per_page e page | Paginação, conforme Convenções |
Resposta (200): lista de alunos, com id, customer_vendor_student_id, student_name, student_document, course_name, start_date, end_date, amount, totalExpenses, student_status, cost_center, company_name, contract_course_name e contract_code.
POST /invoicing/billings/{billing_uuid}/to-bill-students
Inclui alunos no faturamento. Cada aluno incluído passa a constar em billed-students, e o total do faturamento é recalculado.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
training_student_uuids | Sim | Lista de textos | uuid dos alunos do treinamento a incluir |
Resposta (201): corpo null.
curl -X POST https://api.pedagogo.app/invoicing/billings/<uuid-do-faturamento>/to-bill-students \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token-de-sessao>" \
-d '{"training_student_uuids": ["<uuid-do-aluno>"]}'
Listas de apoio
GET /invoicing/billings/business
Empresas cobradas que podem ser escolhidas no campo Empresa. Resposta em lista, com id, uuid, nome e documento.
Totais do faturamento
Os campos total_students, total_expenses e total_amount são recalculados a cada inclusão, remoção ou alteração de aluno:
| Campo | Descrição |
|---|---|
total_students | Soma do valor dos treinamentos dos alunos incluídos |
total_expenses | Soma das despesas de treinamento marcadas como faturadas |
total_amount | Total de treinamentos mais total de despesas |