Empresas
Empresas são as pessoas jurídicas que contratam os treinamentos do cliente. Cada empresa tem contatos, centros de custo, arquivos, treinamentos, interações comerciais e propostas, consultados nas páginas deste recurso.
Tela no Pedagogo: Empresas (módulo Administrativo).
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
| GET | /administrative/business | Lista as empresas |
| POST | /administrative/business | Cadastra uma empresa |
| GET | /administrative/business/{uuid} | Consulta uma empresa |
| PUT | /administrative/business/{uuid} | Altera uma empresa |
| DELETE | /administrative/business/{uuid} | Apaga uma empresa |
| POST | /administrative/business/{uuid}/photo | Envia a foto da empresa |
| PATCH | /administrative/business/{uuid}/allow-certificate-viewing | Liga ou desliga a restrição de visualização de certificado |
| PATCH | /administrative/business/{uuid}/defaulter | Marca ou desmarca a empresa como inadimplente |
| GET | /administrative/business/export | Baixa a lista de empresas em Excel |
| POST | /administrative/business/change-responsible | Troca o responsável ou o representante de várias empresas |
| GET | /administrative/business/classifications | Lista as classificações de A a E |
| GET | /administrative/business/purchase-frequency | Lista as frequências de compra |
| GET | /administrative/customers/purchase-frequencies | Lista as frequências de compra (caminho equivalente) |
| GET | /administrative/customers/purchase-frequencies/{id} | Consulta uma frequência de compra (caminho equivalente) |
| GET | /administrative/companies/purchase-frequencies | Lista as frequências de compra (caminho equivalente) |
| GET | /administrative/companies/purchase-frequencies/{id} | Consulta uma frequência de compra (caminho equivalente) |
Os recursos de cada aba têm página própria:
| Aba da tela | Página |
|---|---|
| Cadastros: contatos | Contatos |
| Cadastros: centros de custo | Centros de custo |
| Arquivos | Arquivos |
| Treinamentos | Treinamentos |
| Interações | Interações |
| Propostas | Propostas |
Endereços (caminhos customers e companies) | Endereços |
Os caminhos /administrative/customers/... e /administrative/companies/...
são o mesmo recurso com outro nome e aceitam os mesmos parâmetros.
Para autenticação, formato de respostas, paginação e erros, veja Autenticação e Convenções.
Regras
- CNPJ repetido. Se o CNPJ já existe no cliente, inclusive em cadastro apagado, o cadastro existente é atualizado e reativado, em vez de criar outro. A resposta de criação devolve esse cadastro com status 201.
- E-mail repetido. Se o e-mail já pertence a outro cadastro do mesmo cliente, ele não é gravado e a resposta não traz aviso. Os demais campos são gravados.
- Exclusão. A exclusão é lógica e remove a foto da empresa. A exclusão não é bloqueada quando a empresa tem alunos, treinamentos, propostas ou lançamentos.
- Classificação e frequência de compra são calculadas pelo sistema e não podem ser enviadas nas chamadas de gravação.
Consultar classificações e frequências de compra
GET /administrative/business/classifications
Lista as classificações de A a E. A classificação mede o atraso médio no pagamento dos lançamentos financeiros da empresa: A até 5 dias, B de 6 a 15 dias, C de 16 a 30 dias, D de 31 a 60 dias e E mais de 60 dias.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
| columnName e orderData | Ordenação: coluna e direção (asc ou desc) |
| per_page e page | Paginação |
Resposta: 200, lista com os campos da classificação (classification,
description).
GET /administrative/business/purchase-frequency
Lista as frequências de compra. Aceita os mesmos parâmetros da classificação.
Resposta: 200, lista com os campos da frequência (purchase_frequency).
GET /administrative/customers/purchase-frequencies
GET /administrative/companies/purchase-frequencies
GET /administrative/customers/purchase-frequencies/{id}
GET /administrative/companies/purchase-frequencies/{id}
Mesma lista de frequências de compra, por caminho equivalente. A versão com {id}
devolve uma frequência pelo seu id numérico.
Resposta: 200, lista ou registro, no mesmo formato de
/administrative/business/purchase-frequency.
Listar, consultar, cadastrar, alterar e apagar
GET /administrative/business
Lista as empresas do cliente. Sem per_page, a resposta é a lista direta; com
per_page, a resposta é paginada.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
| search | Busca por nome, nome fantasia, CNPJ, frequência de compra ou uuid |
| name | Nome ou nome fantasia |
| document | CNPJ ou CPF (busca parcial) |
| responsible_id | Id do usuário responsável |
| agent_id | Id do usuário representante |
| purchase_frequency_id | Id da frequência de compra. Aceita uma lista |
| classification_id | Id da classificação. Aceita uma lista |
| defaulter | 1 para inadimplentes, 0 para adimplentes |
| allow_certificate_viewing | 1 ou 0 para a restrição de visualização de certificado |
| limit | Quantidade máxima de registros |
| columnName e orderData | Ordenação: coluna e direção |
| per_page e page | Paginação |
Resposta: 200, lista de empresas. Cada item traz os dados do cadastro
(uuid, name, company_name, document, email, cellphone,
phonenumber, url, observation), o nome do responsável (responsible) e do
representante (agent), a frequência de compra, a classificação, o endereço
resumido, a chave da foto (photo_key) e os nomes de quem criou e alterou o
registro.
curl "https://api.pedagogo.app/administrative/business?search=Empresa%20exemplo&per_page=15" \
-H "Accept: application/json" \
-H "Authorization: Bearer <token-de-sessao>"
POST /administrative/business
Cadastra uma empresa. Os campos de endereço são gravados no endereço do cadastro. Veja as regras de CNPJ e e-mail repetidos.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| name | Sim | Texto | Nome da empresa |
| responsible_id | Sim | Inteiro | Id do usuário responsável. Deve existir |
| document | Não | Texto | CNPJ ou CPF válido, no formato 00.000.000/0000-00 ou 000.000.000-00 |
| company_name | Não | Texto | Nome fantasia |
| birth_date | Não | Data (AAAA-MM-DD) | Data de abertura |
| Não | Texto | ||
| cellphone | Não | Texto | Celular |
| phonenumber | Não | Texto | Telefone fixo |
| url | Não | Texto | Site |
| observation | Não | Texto | Observação |
| agent_id | Não | Inteiro | Id do usuário representante |
| zip_code | Não | Texto | CEP |
| street | Não | Texto | Endereço (rua) |
| number | Não | Texto | Número |
| complement | Não | Texto | Complemento |
| neighborhood | Não | Texto | Bairro |
| city | Não | Texto | Cidade |
| state | Não | Texto | Estado |
Resposta: 201, com o cadastro criado. O campo uuid identifica a empresa
nas demais chamadas.
curl -X POST https://api.pedagogo.app/administrative/business \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token-de-sessao>" \
-d '{"name": "Empresa exemplo", "responsible_id": 1, "email": "[email protected]"}'
GET /administrative/business/{uuid} e DELETE /administrative/business/{uuid}
Consultar e apagar uma empresa. A consulta devolve o cadastro com a foto e o endereço. A exclusão é lógica e segue as regras desta página.
Resposta: 200.
PUT /administrative/business/{uuid}
Altera uma empresa. Envie os campos que serão alterados, incluindo name e
responsible_id, que são obrigatórios nesta chamada. O corpo aceita os mesmos
campos do cadastro.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| name | Sim | Texto | Nome da empresa |
| responsible_id | Sim | Inteiro | Id do usuário responsável |
| document | Não | Texto | CNPJ ou CPF válido, no mesmo formato do cadastro |
Os demais campos aceitos são os mesmos da criação.
Resposta: 200, com o cadastro alterado.
Foto
POST /administrative/business/{uuid}/photo
Envia ou troca a foto da empresa. Envie o arquivo de imagem no campo file,
em multipart/form-data. Se nenhum arquivo for enviado, nada é alterado.
Resposta: 200, com o cadastro. A chave da nova foto aparece em photo_key
na listagem.
Alternar indicadores
PATCH /administrative/business/{uuid}/defaulter
PATCH /administrative/business/{uuid}/allow-certificate-viewing
Cada chamada inverte o valor atual do indicador. O defaulter marca a empresa como inadimplente, e isso aparece na lista e na inscrição de alunos em turmas. O indicador de visualização de certificado bloqueia a visualização do certificado pela empresa.
Corpo: não há.
Resposta: 200.
Exportar
GET /administrative/business/export
Baixa um arquivo .xlsx com a lista de empresas. A planilha respeita o parâmetro
search e traz até 5.000 empresas. O nome do arquivo tem o formato
<sufixo>_company_listing.xlsx.
Resposta: 200, arquivo para download.
Alterar responsável ou representante
POST /administrative/business/change-responsible
Transfere várias empresas para outro responsável ou representante. Informe
responsible_id ou agent_id, mas não os dois. Quando start_date é informado,
só mudam as inscrições de alunos feitas pela empresa com início nessa data ou
depois. Sem start_date, mudam todas as inscrições da empresa.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| uuids | Sim | Lista de uuids | Empresas que serão alteradas |
| responsible_id | Um dos dois | Inteiro | Novo responsável. Não pode ser enviado junto com agent_id |
| agent_id | Um dos dois | Inteiro | Novo representante. Não pode ser enviado junto com responsible_id |
| start_date | Não | Data (AAAA-MM-DD) | Data de início a partir da qual as inscrições são alteradas |
Resposta: 200.
{
"message": "Responsável alterado com sucesso."
}