Fornecedores

Fornecedores são as empresas e pessoas que prestam serviços ao cliente. O cadastro é mais simples que o de empresas: não há responsável, classificação, treinamentos nem propostas. Corresponde à tela Fornecedores (módulo Administrativo), com as abas Contatos, Endereço e Arquivos, descritas nas páginas deste recurso.

Endpoints

Método	Caminho	Descrição
GET	/administrative/vendors	Lista os fornecedores
POST	/administrative/vendors	Cadastra um fornecedor
GET	/administrative/vendors/{uuid}	Consulta um fornecedor
PUT	/administrative/vendors/{uuid}	Altera um fornecedor
DELETE	/administrative/vendors/{uuid}	Apaga um fornecedor
POST	/administrative/vendors/{uuid}/photo	Envia a foto do fornecedor
GET	/administrative/vendors/export	Baixa a lista de fornecedores em Excel
GET	/administrative/vendors/purchase-frequencies	Lista as frequências de compra
GET	/administrative/vendors/purchase-frequencies/{id}	Consulta uma frequência de compra

Os recursos de cada aba têm página própria:

Aba da tela	Página
Contatos	Contatos
Endereço	Endereços
Arquivos	Arquivos

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, o cadastro existente é reaproveitado em vez de criar outro. Nesse caso, a resposta de criação devolve o cadastro existente 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, remove a foto do fornecedor e não é bloqueada por vínculos.

Listar, consultar, cadastrar, alterar e apagar

GET /administrative/vendors

Lista os fornecedores 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 e CNPJ
name	Nome ou nome fantasia
document	CNPJ ou CPF (busca parcial)
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 fornecedores com uuid, name, company_name, document, email, cellphone, phonenumber, url, observation, 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/vendors?search=Fornecedor%20exemplo&per_page=15" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <token-de-sessao>"

POST /administrative/vendors

Cadastra um fornecedor. Os campos de endereço são gravados no endereço do cadastro.

Corpo

Campo	Obrigatório	Tipo	Descrição
name	Sim	Texto	Nome do fornecedor
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
email	Não	Texto	E-mail
cellphone	Não	Texto	Celular
phonenumber	Não	Texto	Telefone fixo
url	Não	Texto	Site
observation	Não	Texto	Observação
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 o fornecedor nas demais chamadas.

curl -X POST https://api.pedagogo.app/administrative/vendors \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token-de-sessao>" \
  -d '{"name": "Fornecedor exemplo", "email": "[email protected]"}'

GET /administrative/vendors/{uuid} e DELETE /administrative/vendors/{uuid}

Consultar e apagar um fornecedor. A consulta devolve o cadastro com a foto e o endereço. A exclusão segue as regras desta página.

Resposta: 200.

PUT /administrative/vendors/{uuid}

Altera um fornecedor. O campo name é opcional nesta chamada. O documento, quando informado, segue o mesmo formato da criação. Os demais campos são os mesmos da criação.

Resposta: 200, com o cadastro alterado.

Foto

POST /administrative/vendors/{uuid}/photo

Envia ou troca a foto do fornecedor. Envie o arquivo de imagem no campo file, em multipart/form-data. Se nenhum arquivo for enviado, nada é alterado.

Resposta: 200, com o cadastro.

Exportar

GET /administrative/vendors/export

Baixa um arquivo .xlsx com a lista de fornecedores. A planilha respeita o parâmetro search.

Resposta: 200, arquivo para download.

Frequências de compra

GET /administrative/vendors/purchase-frequencies

GET /administrative/vendors/purchase-frequencies/{id}

Lista e consulta as frequências de compra, as mesmas usadas nas empresas. A versão com {id} devolve uma frequência pelo seu id numérico.

Resposta: 200, lista ou registro com os campos da frequência (purchase_frequency).