NAV Navbar

Introdução

A Quero Educação deu mais um passo no gerenciamento do estoque de bolsas de estudo por seus parceiros e agora esse processo passou por uma grande melhoria. Tudo isso para estreitar ainda mais os laços e reafirmar seu compromisso como Marketplace.

A partir de agora abrimos nosso modelo de estoque para ser acessado programaticamente via conjunto de APIs. O serviço permitirá que o parceiro consulte, crie, altere ou delete seu portfólio de bolsas como desejar.

O objetivo dessa melhoria é garantir a consistência entre as bases de dados da Quero Educação e da instituição de ensino superior, além de dar uma maior liberdade e autonomia para que se opere as bolsas.

Em poucas palavras, por meio das APIs o parceiro poderá integrar suas aplicações (sistemas de uso interno) diretamente no nosso modelo e, assim, fazer a gestão de suas bolsas de estudo do modo que preferir.

Para otimizar esse processo, implementamos uma Interface de Aplicações (API) REST. Ela é composta por dois serviços interdependentes (“Campi” e “Cursos”), os quais possuem seus respectivos métodos, conforme especificado abaixo.

Autenticação

Modo de autenticação

A autenticação é realizada por meio de uma combinação de usuário e senha. Caso a autenticação seja realizada com sucesso, o cliente receberá um token válido para a sessão por um tempo determinado, conforme descrito na documentação de login.

O nome do usuário e a senha são gerados através de um cadastro feito junto à Quero Educação. Para mais informações, contate seu Key Account Manager.

Requisição sem token

Ausência de Token
Status Code: 401 Unauthorized
www-authenticate: 'Token realm="StockIntegration"'

Em caso de requisição sem o envio do token, é retornado status 401 - Unauthorized.

Requisição com token inválido

Formato de token inválido
Status Code: 400 Bad Request

Em caso de token em formato inválido, é retornado status 400 - Bad Request.

Requisição com token não autorizado

Não autorizado
Status Code: 403 Forbidden

Em caso de token não autorizado, é retornado erro 403 - Forbidden.

Requisição com token sem permissão

Sem permissão
Status Code: 200 OK

{
  "error": true,
  "errors": [{
    "title": "Invalid Permission",
    "detail": "You are not authorized to access this resource with these parameters"
  }]
}

Em caso de token válido mas sem permissão de acesso ao recurso específico, é retornado o status 200 - OK com mensagem de erro no payload.

Login

A sessão é criada por meio da autenticação utilizando uma combinação de usuário e senha. Caso seja autenticado com sucesso, o cliente recebe um token válido por 4 horas. Após este período, o token expira e um novo token deve ser solicitado.

É necessário enviar este token no cabeçalho das requisições para ter permissão de executar as solicitações desta API.

Iniciar uma sessão

Exemplo de requisição

curl -X POST "https://stock.querobolsa.com.br/api/sessions" \
  -H 'Content-Type: application/json' \
  -d '{
    "authentication": {
      "username": "teste@teste.com",
      "password": "teste123!"
    }
  }'

Exemplo de retorno JSON para esta requisição

{
  "access_token": "qPWFZr3CSX52SLeUWdP9XXL5"
}

É necessário enviar uma requisição com o username e password para iniciar uma sessão.

A resposta da requisição retorna o token da sessão, que ficará válido por 4 horas. Esse token precisará estar presente no campo Authorization no cabeçalho das outras ações da API.

Parâmetros para criar uma sessão

Nome Tipo Descrição
session object Objeto com dados das credenciais para login
username sting Nome de usuário para login fornecido pelo Quero Bolsa
password sting Senha para login fornecido pelo Quero Bolsa

Parâmetros da resposta

Nome Tipo Descrição
access_token sting Token de acesso da sessão

Paginação

Exemplo de paginação

Exemplo de requisição

curl "https://stock.querobolsa.com.br/api/universities/65605bf0-cad2-4dc2-ae11-65c77bc36508/campuses" \
  -H 'Authorization: Bearer ##########' \
  -H 'Content-Type: application/json'

Exemplo de retorno JSON para esta requisição

{
  "has_more": true,
  "items": [
    {
      "id": "30fe7edb-ef73-4538-912a-26d5126a81a9",
      "university": {
        "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
        "name": "UniQuero",
      },
      "name": "Caxias",
      "address": "Rua Araão Reis, 1789, Bloco 1",
      "neighborhood": "Centro",
      "city": "Caxias",
      "state": "MA",
      "zip_code": "65604-060",
      "phone": "(00) 00000000",
      "latitude": -23.198976,
      "longitude": -45.901692
    },
    ...,
    {
      "id": "6cc4aa4f-ef6d-48d0-b73c-cf5c5126fd1c",
      "university": {
        "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
        "name": "UniQuero",
      },
      "name": "Sorocaba",
      "address": "Av. Independência, 210",
      "neighborhood": "Éden",
      "city": "Sorocaba",
      "state": "SP",
      "zip_code": "18087-101",
      "phone": "(00) 00000000",
      "latitude": -23.198976,
      "longitude": -45.901692
    }
  ]
}

A API de integração de estoque possui requisições de listagem de dados que podem resgatar quantidades massivas de informação. É utilizada paginação para evitar com que essas requisições não sobrecarreguem o banco de dados.

A API utiliza paginação baseada em cursor atráves dos parâmetros starting_after e ending_before. Ambos recebem um ID de um dado existente e retorna uma lista com até 1000 elementos no máximo.

Os objetos são retornados ordenados pela data de criação decrescentemente. O parâmetro ending_before faz a requisição retornar elementos criados anteriormente ao dado cujo ID foi indicado pelo parâmetro. Em contrapartida, o parâmetro starting_after faz a requisição retornar elementos listados criados após o dado cujo ID foi indicado.

O atributo has_more da resposta indica se há mais dados disponíveis depois dessa página. Se for false, significa que é o fim da lista e não há mais dados. Se for true, significa que há mais dados a serem resgatados. Após uma requisição utilizando o parâmetro ending_before, o atributo has_more se refere a possibilidade de retornar mais dados anteriores à página atual.

Parâmetros de paginação

Nome Tipo Descrição
starting_after cursor Cursor para uso em paginação. Retorna elementos listados após o dado cujo ID foi indicado
ending_before cursor Cursor para uso em paginação. Retorna elementos listados antes do dado cujo ID foi indicado

Informações de resultado de dados com paginação

Nome Tipo Descrição
has_more boolean Indica se há mais elementos disponíveis antes ou após essa página
items array Lista dos elementos retornados pela requisição

Uso do cursor ending_before

Exemplo de requisição

curl "https://stock.querobolsa.com.br/api/universities/65605bf0-cad2-4dc2-ae11-65c77bc36508/campuses?ending_before=6cc4aa4f-ef6d-48d0-b73c-cf5c5126fd1c" \
  -H 'Authorization: Bearer ##########' \
  -H 'Content-Type: application/json'

Retorno

{
  "has_more": false,
  "items": [
    {
      "id": "7c11e1d0-1b96-412d-98db-db5fee90492d",
      "university": {
        "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
        "name": "UniQuero",
      },
      "name": "São Paulo",
      "address": "Rua Henri Dunant, 203",
      "neighborhood": "Chácara Santo Amaro",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "04709-110",
      "phone": "(00) 00000000",
      "latitude": -23.198976,
      "longitude": -45.901692
    },
    ...,
    {
      "id": "4ba0104a-fbac-4c67-942c-3fcd96b77a83",
      "university": {
        "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
        "name": "UniQuero",
      },
      "name": "SP",
      "address": "Av. Marquês de São Vicente, 2900",
      "neighborhood": "Água Branca",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "05036-040",
      "phone": "(00) 00000000",
      "latitude": -23.198976,
      "longitude": -45.901692
    }
  ]
}

No exemplo acima, vimos que has_more retornou true, portanto existem mais dados a serem resgatados após essa página. Para poder consultá-los, na próxima requisição o parâmetro starting_after precisa ter o ID do último elemento da lista items. A requisição e retorno ao lado são referentes ao exemplo acima.

Parâmetros de paginação

Nome Tipo Descrição
starting_after cursor Cursor para uso em paginação. Retorna elementos listados após o dado cujo ID foi indicado
ending_before cursor Cursor para uso em paginação. Retorna elementos listados antes do dado cujo ID foi indicado

Informações de resultado de dados com paginação

Nome Tipo Descrição
has_more boolean Indica se há mais elementos disponíveis antes ou após essa página
items array Lista dos elementos retornados pela requisição

Uso do cursor starting_after

Exemplo de requisição

curl "https://stock.querobolsa.com.br/api/universities/65605bf0-cad2-4dc2-ae11-65c77bc36508/campuses?starting_after=7c11e1d0-1b96-412d-98db-db5fee90492d" \
  -H 'Authorization: Bearer ##########' \
  -H 'Content-Type: application/json'

Retorno

{
  "has_more": false,
  "items": [
    {
      "id": "30fe7edb-ef73-4538-912a-26d5126a81a9",
      "university": {
        "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
        "name": "UniQuero",
      },
      "name": "Caxias",
      "address": "Rua Araão Reis, 1789, Bloco 1",
      "neighborhood": "Centro",
      "city": "Caxias",
      "state": "MA",
      "zip_code": "65604-060",
      "phone": "(00) 00000000",
      "latitude": -23.198976,
      "longitude": -45.901692
    },
    ...,
    {
      "id": "6cc4aa4f-ef6d-48d0-b73c-cf5c5126fd1c",
      "university": {
        "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
        "name": "UniQuero",
      },
      "name": "Sorocaba",
      "address": "Av. Independência, 210",
      "neighborhood": "Éden",
      "city": "Sorocaba",
      "state": "SP",
      "zip_code": "18087-101",
      "phone": "(00) 00000000",
      "latitude": -23.198976,
      "longitude": -45.901692
    }
  ]
}

Assim como avançamos uma página, é possível facilmente retornar a dados anteriores à página atual. Para fazer isso, na próxima requisição o parâmetro starting_after precisa ter o ID do primeiro elemento da lista items. A requisição e retorno ao lado são referentes ao exemplo acima.

Parâmetros de paginação

Nome Tipo Descrição
starting_after cursor Cursor para uso em paginação. Retorna elementos listados após o dado cujo ID foi indicado
ending_before cursor Cursor para uso em paginação. Retorna elementos listados antes do dado cujo ID foi indicado

Informações de resultado de dados com paginação

Nome Tipo Descrição
has_more boolean Indica se há mais elementos disponíveis antes ou após essa página
items array Lista dos elementos retornados pela requisição

Universidades

Listar universidades

Exemplo de requisição

curl "https://stock.querobolsa.com.br/api/universities" \
  -H 'Authorization: Bearer ##########' \
  -H 'Content-Type: application/json'

Exemplo de retorno JSON para esta requisição

{
  "has_more": false,
  "items": [
    {
      "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
      "name": "UniQuero",
    },
    {
      "id": "f21d030e-b40d-4ecf-a0a3-fd7d2cbd06e5",
      "name": "Faculdade Quero",
    }
  ]
}

Lista todas as universidades associadas ao usuário que possui o token de autenticação enviado na requisição.

Universidades são retornadas em páginas de até 1000 elementos, ordenadas pela última criação realizada. Se houver mais resultados, has_more retorna true indicando que é possível usar o parâmetro ending_before para consultar objetos antecessores à lista atual. Para mais informações, consulte a seção de paginação.

Requisição HTTP

GET https://stock.querobolsa.com.br/api/universities

Parâmetros da resposta

Nome Tipo Descrição
id string Identificador único de universidade
name string Nome da universidade

Campi

Listar campi

Exemplo de requisição

curl "https://stock.querobolsa.com.br/api/universities/65605bf0-cad2-4dc2-ae11-65c77bc36508/campuses" \
  -H 'Authorization: Bearer ##########' \
  -H 'Content-Type: application/json'

Exemplo de retorno JSON para esta requisição

{
  "has_more": false,
  "items": [
    {
      "id": "00d9ef5a-d003-4212-99ff-c4308f18803d",
      "university": {
        "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
        "name": "UniQuero",
      },
      "name": "Caxias",
      "address": "Rua Araão Reis, 1789, Bloco 1",
      "neighborhood": "Centro",
      "city": "Caxias",
      "state": "MA",
      "zip_code": "65604-060",
      "phone": "(00) 00000000",
      "latitude": -23.198976,
      "longitude": -45.901692
    },
    {
      "id": "9d49f7f8-5994-40ae-a8fa-b9c9d66adef8",
      "university": {
        "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
        "name": "UniQuero",
      },
      "name": "Sorocaba",
      "address": "Av. Independência, 210",
      "neighborhood": "Éden",
      "city": "Sorocaba",
      "state": "SP",
      "zip_code": "18087-101",
      "phone": "(00) 00000000",
      "latitude": -23.198976,
      "longitude": -45.901692
    }
  ]
}

Lista os campus de uma dada faculdade. Apenas faculdades associadas ao usuário podem ser solicitadas. Em outros casos, a API retorna 404 - Not Found.

Campi são retornados em páginas de até 1000 elementos, ordenadas pela última criação realizada. Se houver mais resultados, has_more retorna true indicando que é possível usar o parâmetro ending_before para consultar objetos antecessores à lista atual. Para mais informações, consulte a seção de paginação.

Requisição HTTP

GET https://stock.querobolsa.com.br/api/universities/<UNIVERSITY_ID>/campuses

Parâmetros da requisição

Nome Tipo Descrição
UNIVERSITY_ID path ID da universidade onde deseja realizar a ação

Parâmetros da resposta

Nome Tipo Descrição
has_more boolean Indica se há mais elementos disponíveis antes ou após essa página
items object array Arranjo de objetos com dados de campus
id string Código identificador de campus
university object Objeto com dados de universidade
[university] id string Código identificador de universidade
[university] name string Nome da universidade
name string Nome do campus
address string Endereço do campus
neighborhood string Bairro do campus
city string Cidade do campus
state string Estado do campus
zip_code string Código CEP do campus
phone string Telefone do campus
latitude float Coordenada de latitude do campus
longitude float Coordenada de longitude do campus

Informações de um campus específico

Exemplo de requisição

curl "https://stock.querobolsa.com.br/api/universities/65605bf0-cad2-4dc2-ae11-65c77bc36508/campuses/00d9ef5a-d003-4212-99ff-c4308f18803d" \
  -H 'Authorization: Bearer ##########' \
  -H 'Content-Type: application/json'

Exemplo de retorno JSON para esta requisição

{
  "id": "00d9ef5a-d003-4212-99ff-c4308f18803d",
  "university": {
    "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
    "name": "UniQuero",
  },
  "name": "Caxias",
  "address": "Rua Araão Reis, 1789, Bloco 1",
  "neighborhood": "Centro",
  "city": "Caxias",
  "state": "MA",
  "zip_code": "65604-060",
  "phone": "(00) 00000000",
  "latitude": -23.198976,
  "longitude": -45.901692
}

Retorna informações de um campus específico.

Requisição HTTP

GET https://stock.querobolsa.com.br/api/universities/<UNIVERSITY_ID>/campuses/<CAMPUS_ID>

Parâmetros da requisição

Nome Tipo Descrição
UNIVERSITY_ID path ID da universidade onde deseja realizar a ação
CAMPUS_ID path ID do campus que deseja resgatar informações

Parâmetros da resposta

Nome Tipo Descrição
id string Código identificador de campus
name string Nome do campus
university object Objeto com dados de universidade
[university] id string Código identificador de universidade
[university] name string Nome da universidade
address string Endereço do campus
neighborhood string Bairro do campus
city string Cidade do campus
state string Estado do campus
zip_code string Código CEP do campus
phone string Telefone do campus
latitude float Coordenada de latitude do campus
longitude float Coordenada de longitude do campus

Inserir campi

Exemplo de requisição

curl -X POST "https://stock.querobolsa.com.br/api/universities/65605bf0-cad2-4dc2-ae11-65c77bc36508/campuses" \
  -H 'Authorization: Bearer ##########' \
  -H 'Content-Type: application/json' \
  -d @campus_data.json

Exemplo da estrutura JSON esperada:

{
  "campuses": [
    {
      "name": "Caxias",
      "address": "Rua Araão Reis, 1789, Bloco 1",
      "neighborhood": "Centro",
      "city": "Caxias",
      "state": "MA",
      "zip_code": "65604-060",
      "phone": "(00) 00000000",
      "latitude": -23.198976,
      "longitude": -45.901692
    },
    {
      "name": "Sorocaba",
      "address": "Av. Independência, 210",
      "neighborhood": "Éden",
      "city": "Sorocaba",
      "state": "SP",
      "zip_code": "18087-101",
      "phone": "(00) 00000000",
      "latitude": -23.198976,
      "longitude": -45.901692
    }
  ]
}

Resposta

Status Code: 200 OK

{
  "error": false,
  "operation_id": "4e8c23c3-fab1-486d-9c0e-c49301305d94"
}

Esse endpoint cria campus em lote com informações enviadas em JSON.

Na inserção de campus, caso o ID seja enviado, o serviço irá fazer uma operação de atualização de informação, sobrescrevendo os dados enviando no modelo do banco.

Caso o ID do campus não seja enviado, uma validação com a base de dados será feita, a fim de evitar campi duplicados na nossa base.

Requisição HTTP

POST https://stock.querobolsa.com.br/api/universities/<UNIVERSITY_ID>/campuses/

Parâmetros da requisição

Nome Tipo Descrição
UNIVERSITY_ID path ID da universidade onde deseja realizar a ação

Parâmetros da requisição

Nome Tipo Descrição
campuses object array Arranjo de objetos com dados de campus
[campuses] name string Nome do campus
[campuses] address string Endereço do campus
[campuses] neighborhood string Bairro do campus
[campuses] city string Cidade do campus
[campuses] state string Estado do campus
[campuses] zip_code string Código CEP do campus
[campuses] phone string Telefone do campus
[campuses] latitude float Coordenada de latitude do campus
[campuses] longitude float Coordenada de longitude do campus

Parâmetros da resposta

Nome Tipo Descrição
error boolean Indicador de ocorrência de erro na operação
operation_id string ID da operação de estoque criada

Cursos

Atributos de curso

Alguns campos do curso possuem atributos com um conjunto restrito de valores válidos (enumeration). Esta seção aborda estes campos.

Modalidade (kind)

O atributo kind indica a modalidade do curso.

De uma forma geral, a modalidade informa a forma que o aluno irá fazer o curso.

Segue a tabela com possíveis valores para esse campo:

Valor
Presencial
EaD
EaD Mais
Flex
SEPI
Semipresencial

Grau (level)

O atributo level indica o grau do curso.

O grau é o nível do curso oferecido, ou seja, é referente ao título que o aluno irá obter após concluir o curso.

Segue a tabela com possíveis valores para esse campo:

Valor
Licenciatura (graduação)
Bacharelado (graduação)
Bacharelado + Licenciatura (graduação)
Tecnólogo (graduação)
Pós-graduação Lato Sensu
Mestrado
Doutorado
Pós-doutorado
Técnico
Profissionalizante
Curso Livre
Pré-vestibular
Ensino Fundamental
Ensino Infantil
Ensino Médio
Sequencial
Segunda Graduação
Bootcamp

Turno (shift)

O atributo shift indica o turno do curso.

O turno do curso é o período de dia que o aluno estará cursando.

Segue a tabela com possíveis valores para esse campo:

Valor
Manhã
Tarde
Noite
Integral
Virtual
Outro

Periodicidade (period_kind)

O atributo period_kind indica a periodicidade do curso.

A peridicidade é a forma como o curso está dividido e também serve para informar a duração do mesmo quando combinado com o campo max_periods, que indica a quantidade dessa periodicidade. Por exemplo: se uma entidade de curso possui o valor 6 no atributo max_periods e semestre em period_kind, isso quer dizer que é um curso com duração de 6 semestres.

Segue a tabela com possíveis valores para esse campo:

Valor
hora
dia
modulo
semanal
quinzenal
mes
trimestre
quadrimestre
semestre
ano

Listar cursos

Exemplo de requisição

curl "https://stock.querobolsa.com.br/api/universities/65605bf0-cad2-4dc2-ae11-65c77bc36508/courses" \
  -H 'Authorization: Bearer ##########' \
  -H 'Content-Type: application/json'

Exemplo de retorno JSON para esta requisição

{
  "has_more": false,
  "items": [
    {
      "id": "accf676c-b200-485f-9c96-f887eae531d0",
      "campus": {
        "id": "00d9ef5a-d003-4212-99ff-c4308f18803d",
        "university": {
          "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
          "name": "UniQuero",
        },
        "name": "Caxias",
        "address": "Rua Araão Reis, 1789, Bloco 1",
        "neighborhood": "Centro",
        "city": "Caxias",
        "state": "MA",
        "zip_code": "65604-060",
        "phone": "(00) 00000000",
        "latitude": -23.198976,
        "longitude": -45.901692
      },
      "name": "MBA em Auditoria",
      "level": "Pós-graduação Lato Sensu",
      "kind": "EaD",
      "shift": "Virtual",
      "period_kind": "mes",
      "max_periods": 6,
      "enrollment_semester": "2019.1",
      "full_price": 299.99,
      "discount_percentage": 50.00,
      "price_with_discount": 149.99,
      "fixed_commercial_discount": 20.00,
      "end_date": "2019-06-30",
      "number_of_installments": 12,
      "extra_warning": "* &bull; Após garantir a bolsa, o aluno deverá entrar em contato com a faculdade pelo número (00) 0000-0000",
      "extra_benefit": "* &bull; Primeira parcela grátis"
    },
    {
      "id": "5b0a5715-f21c-43c7-9db8-1df8aa464494",
      "campus": {
        "id": "9d49f7f8-5994-40ae-a8fa-b9c9d66adef8",
        "university": {
          "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
          "name": "UniQuero",
        },
        "name": "Sorocaba",
        "address": "Av. Independência, 210",
        "neighborhood": "Éden",
        "city": "Sorocaba",
        "state": "SP",
        "zip_code": "18087-101",
        "phone": "(00) 00000000",
        "latitude": -23.198976,
        "longitude": -45.901692
      },
      "name": "Direito",
      "level": "Bacharelado (graduação)",
      "kind": "Presencial",
      "shift": "Noite",
      "period_kind": "semestre",
      "max_periods": 10,
      "enrollment_semester": "2019.1",
      "full_price": 649.00,
      "discount_percentage": 25.00,
      "price_with_discount": 486.75,
      "regressive_commercial_discount": 10.00,
      "end_date": "2019-03-31",
      "number_of_installments": 60,
      "extra_warning": "* &bull; Após garantir a bolsa, o aluno deverá entrar em contato com a faculdade pelo número (00) 0000-0000",
      "extra_benefit": "* &bull; Primeira mensalidade grátis"
    }
  ]
}

Lista todos os cursos disponibilizados pela universidade.

Cursos são retornados em páginas de até 1000 elementos, ordenadas pela última criação realizada. Se houver mais resultados, has_more retorna true indicando que é possível usar o parâmetro ending_before para consultar objetos antecessores à lista atual. Para mais informações, consulte a seção de paginação.

Requisição HTTP

GET https://stock.querobolsa.com.br/api/universities/<UNIVERSITY_ID>/courses

Parâmetros da requisição

Nome Tipo Descrição
UNIVERSITY_ID path ID da universidade onde deseja realizar a ação

Parâmetros da resposta

Nome Tipo Descrição
has_more boolean Indica se há mais elementos disponíveis antes ou após essa página
items object array Arranjo de objetos com dados de curso
id string Código identificador de curso
campus object Objeto com dados de campus do curso
[campus] id string Código identificador de campus
[campus] university object Objeto com dados de universidade
[campus] [university] id string Código identificador de universidade
[campus] [university] name string Nome da universidade
[campus] name string Nome do campus
[campus] address string Endereço do campus
[campus] neighborhood string Bairro do campus
[campus] city string Cidade do campus
[campus] state string Estado do campus
[campus] zip_code string Código CEP do campus
[campus] phone string Telefone do campus
[campus] latitude float Coordenada de latitude do campus
[campus] longitude float Coordenada de longitude do campus
level string Grau do curso. Mais informações sobre esse atributo aqui
kind string Modalidade do curso. Mais informações sobre esse atributo aqui
shift string Turno do curso. Mais informações sobre esse atributo aqui
period_kind string Periodicidade do curso. Mais informações sobre esse atributo aqui
max_periods string Quantidade de periodicidade. Mais informações sobre esse atributo aqui
enrollment_semester string Semestre de matrícula do curso
full_price float Preço do curso sem desconto
discount_percentage float Porcentagem de desconto do Quero Bolsa
price_with_discount float Preço do curso com desconto
regressive_commercial_discount float Desconto regressivo disponibilizado pela universidade. Esta parcela do desconto pode ser alterada ao longo do curso. Quando não fornecido, assume-se 0
fixed_commercial_discount float Desconto fixo disponibilizado pela instituição no seu balcão. Esta parcela do desconto não é alterado ao longo do curso. Quando não fornecido, assume-se 0
end_date string Data de término da validade da oferta
number_of_installments integer Número de parcelas que o curso será pago. Caso não informado, será considerado que o curso é pago em mensalidades e na mesma duração do mesmo.
extra_warning string Avisos sobre a bolsa. Essa informação é adquirida diretamente dos meios de comunicação da faculdade por um time da Quero Educação
extra_benefit string Benefícios adicionais da bolsa. Essa informação é adquirida diretamente dos meios de comunicação da faculdade por um time da Quero Educação

Listar cursos de um campus

Exemplo de requisição

curl "https://stock.querobolsa.com.br/api/universities/65605bf0-cad2-4dc2-ae11-65c77bc36508/courses?campus_id=00d9ef5a-d003-4212-99ff-c4308f18803d" \
  -H 'Authorization: Bearer ##########' \
  -H 'Content-Type: application/json'

Exemplo de retorno JSON para esta requisição

{
  "has_more": false,
  "items": [
    {
      "id": "accf676c-b200-485f-9c96-f887eae531d0",
      "campus": {
        "id": "00d9ef5a-d003-4212-99ff-c4308f18803d",
        "university": {
          "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
          "name": "UniQuero",
        },
        "name": "Caxias",
        "address": "Rua Araão Reis, 1789, Bloco 1",
        "neighborhood": "Centro",
        "city": "Caxias",
        "state": "MA",
        "zip_code": "65604-060",
        "phone": "(00) 00000000",
        "latitude": -23.198976,
        "longitude": -45.901692
      },
      "name": "MBA em Auditoria",
      "level": "Pós-graduação Lato Sensu",
      "kind": "EaD",
      "shift": "Virtual",
      "period_kind": "mes",
      "max_periods": 6,
      "enrollment_semester": "2019.1",
      "full_price": 299.99,
      "discount_percentage": 50.00,
      "price_with_discount": 149.99,
      "fixed_commercial_discount": 20.00,
      "end_date": "2019-06-30",
      "number_of_installments": 12,
      "extra_warning": "* &bull; Após garantir a bolsa, o aluno deverá entrar em contato com a faculdade pelo número (00) 0000-0000",
      "extra_benefit": "* &bull; Primeira parcela grátis"
    }
  ]
}

Esse endpoint lista todos os cursos de um determinado campus, cujo é enviado o ID como parâmetro da requisição.

Cursos são retornados em páginas de até 1000 elementos, ordenadas pela última criação realizada. Se houver mais resultados, has_more retorna true indicando que é possível usar o parâmetro ending_before para consultar objetos antecessores à lista atual. Para mais informações, consulte a seção de paginação.

Requisição HTTP

GET https://stock.querobolsa.com.br/api/universities/<UNIVERSITY_ID>/courses?campus_id=<CAMPUS_ID>

Parâmetros da requisição

Nome Tipo Descrição
UNIVERSITY_ID path ID da universidade onde deseja realizar a ação
CAMPUS_ID path ID do campus onde deseja resgatar cursos

Parâmetros da resposta

Nome Tipo Descrição
has_more boolean Indica se há mais elementos disponíveis antes ou após essa página
items object array Arranjo de objetos com dados de curso
id string Código identificador de curso
campus object Objeto com dados de campus do curso
[campus] id string Código identificador de campus
[campus] university object Objeto com dados de universidade
[campus] [university] id string Código identificador de universidade
[campus] [university] name string Nome da universidade
[campus] name string Nome do campus
[campus] address string Endereço do campus
[campus] neighborhood string Bairro do campus
[campus] city string Cidade do campus
[campus] state string Estado do campus
[campus] zip_code string Código CEP do campus
[campus] phone string Telefone do campus
[campus] latitude float Coordenada de latitude do campus
[campus] longitude float Coordenada de longitude do campus
name string Nome do curso
level string Grau do curso. Mais informações sobre esse atributo aqui
kind string Modalidade do curso. Mais informações sobre esse atributo aqui
shift string Turno do curso. Mais informações sobre esse atributo aqui
period_kind string Periodicidade do curso. Mais informações sobre esse atributo aqui
max_periods string Quantidade de periodicidade. Mais informações sobre esse atributo aqui
enrollment_semester string Semestre de matrícula do curso
full_price float Preço do curso sem desconto
discount_percentage float Porcentagem de desconto do Quero Bolsa
price_with_discount float Preço do curso com desconto
regressive_commercial_discount float Desconto regressivo disponibilizado pela universidade. Esta parcela do desconto pode ser alterada ao longo do curso. Quando não fornecido, assume-se 0
fixed_commercial_discount float Desconto fixo disponibilizado pela instituição no seu balcão. Esta parcela do desconto não é alterado ao longo do curso. Quando não fornecido, assume-se 0
end_date string Data de término da validade da oferta
number_of_installments integer Número de parcelas que o curso será pago. Caso não informado, será considerado que o curso é pago em mensalidades e na mesma duração do mesmo.
extra_warning string Avisos sobre a bolsa. Essa informação é adquirida diretamente dos meios de comunicação da faculdade por um time da Quero Educação
extra_benefit string Benefícios adicionais da bolsa. Essa informação é adquirida diretamente dos meios de comunicação da faculdade por um time da Quero Educação

Informações de um curso específico

Exemplo de requisição

curl "https://stock.querobolsa.com.br/api/courses/accf676c-b200-485f-9c96-f887eae531d0" \
  -H 'Authorization: Bearer ##########' \
  -H 'Content-Type: application/json'

Exemplo de retorno JSON para esta requisição

{
  "id": "accf676c-b200-485f-9c96-f887eae531d0",
  "campus": {
    "id": "00d9ef5a-d003-4212-99ff-c4308f18803d",
    "university": {
      "id": "65605bf0-cad2-4dc2-ae11-65c77bc36508",
      "name": "UniQuero",
    },
    "name": "Caxias",
    "address": "Rua Araão Reis, 1789, Bloco 1",
    "neighborhood": "Centro",
    "city": "Caxias",
    "state": "MA",
    "zip_code": "65604-060",
    "phone": "(00) 00000000",
    "latitude": -23.198976,
    "longitude": -45.901692
  },
  "name": "MBA em Auditoria",
  "level": "Pós-graduação Lato Sensu",
  "kind": "EaD",
  "shift": "Virtual",
  "period_kind": "mes",
  "max_periods": 6,
  "enrollment_semester": "2019.1",
  "full_price": 299.99,
  "discount_percentage": 50.00,
  "price_with_discount": 149.99,
  "fixed_commercial_discount": 20.00,
  "end_date": "2019-06-30",
  "number_of_installments": 12,
  "extra_warning": "* &bull; Após garantir a bolsa, o aluno deverá entrar em contato com a faculdade pelo número (00) 0000-0000",
  "extra_benefit": "* &bull; Primeira parcela grátis"
}

Esse endpoint traz informações de um curso específico.

Requisição HTTP

GET https://stock.querobolsa.com.br/api/universities/<UNIVERSITY_ID>/courses/<COURSE_ID>

Parâmetros da requisição

Nome Tipo Descrição
UNIVERSITY_ID path ID da universidade onde deseja realizar a ação
COURSE_ID path ID do curso que deseja resgatar informações

Parâmetros da resposta

Nome Tipo Descrição
id string Código identificador de curso
campus object Objeto com dados de campus do curso
[campus] id string Código identificador de campus
[campus] id string Código identificador de campus
[campus] university object Objeto com dados de universidade
[campus] [university] id string Código identificador de universidade
[campus] [university] name string Nome da universidade
[campus] name string Nome do campus
[campus] address string Endereço do campus
[campus] neighborhood string Bairro do campus
[campus] city string Cidade do campus
[campus] state string Estado do campus
[campus] zip_code string Código CEP do campus
[campus] phone string Telefone do campus
[campus] latitude float Coordenada de latitude do campus
[campus] longitude float Coordenada de longitude do campus
level string Grau do curso. Mais informações sobre esse atributo aqui
kind string Modalidade do curso. Mais informações sobre esse atributo aqui
shift string Turno do curso. Mais informações sobre esse atributo aqui
period_kind string Periodicidade do curso. Mais informações sobre esse atributo aqui
max_periods string Quantidade de periodicidade. Mais informações sobre esse atributo aqui
enrollment_semester string Semestre de matrícula do curso
full_price float Preço do curso sem desconto
discount_percentage float Porcentagem de desconto do Quero Bolsa
price_with_discount float Preço do curso com desconto
regressive_commercial_discount float Desconto regressivo disponibilizado pela universidade. Esta parcela do desconto pode ser alterada ao longo do curso. Quando não fornecido, assume-se 0
fixed_commercial_discount float Desconto fixo disponibilizado pela instituição no seu balcão. Esta parcela do desconto não é alterado ao longo do curso. Quando não fornecido, assume-se 0
end_date string Data de término da validade da oferta
number_of_installments integer Número de parcelas que o curso será pago. Caso não informado, será considerado que o curso é pago em mensalidades e na mesma duração do mesmo.
extra_warning string Avisos sobre a bolsa. Essa informação é adquirida diretamente dos meios de comunicação da faculdade por um time da Quero Educação
extra_benefit string Benefícios adicionais da bolsa. Essa informação é adquirida diretamente dos meios de comunicação da faculdade por um time da Quero Educação

Inserir cursos

Exemplo de requisição

curl -X POST "https://stock.querobolsa.com.br/api/universities/65605bf0-cad2-4dc2-ae11-65c77bc36508/courses" \
  -H 'Authorization: Bearer ##########' \
  -H 'Content-Type: application/json' \
  -d @course_data.json

Exemplo da estrutura JSON esperada:

{
  "courses": [
    {
      "campus_id": "00d9ef5a-d003-4212-99ff-c4308f18803d",
      "name": "MBA em Auditoria",
      "level": "Pós-graduação Lato Sensu",
      "kind": "EaD",
      "shift": "Virtual",
      "period_kind": "mes",
      "max_periods": 6,
      "enrollment_semester": "2019.1",
      "full_price": 299.99,
      "discount_percentage": 50.00,
      "fixed_commercial_discount": 20.00,
      "regressive_commercial_discount": 10.00,
      "end_date": "2019-06-30",
      "number_of_installments": 12
    },
    {
      "campus_id": "9d49f7f8-5994-40ae-a8fa-b9c9d66adef8",
      "name": "Direito",
      "level": "Bacharelado (graduação)",
      "kind": "Presencial",
      "shift": "Noite",
      "period_kind": "semestre",
      "max_periods": 10,
      "enrollment_semester": "2019.1",
      "full_price": 649.00,
      "price_with_discount": 486.75,
      "regressive_commercial_discount": 10.00,
      "end_date": "2019-03-31"
    }
  ]
}

Resposta

Status Code: 200 OK

{
  "error": false,
  "operation_id": "4e8c23c3-fab1-486d-9c0e-c49301305d94"
}

Esse endpoint cria cursos em lote com informações enviadas em JSON.

Observação: Na hora da inserção, apenas um dos campos discount_percentage ou price_with_discount pode ser enviado no mesmo objeto.

Requisição HTTP

POST https://stock.querobolsa.com.br/api/universities/<UNIVERSITY_ID>/courses

Parâmetros da requisição

Nome Tipo Descrição
UNIVERSITY_ID path ID da universidade onde deseja realizar a ação

Parâmetros da requisição

Nome Tipo Descrição
courses object array Arranjo de objetos com dados de curso
[courses] campus_id string Código identificador de campus
[courses] name string Nome do curso
[courses] level string Grau do curso. Mais informações sobre esse atributo aqui
[courses] kind string Modalidade do curso. Mais informações sobre esse atributo aqui
[courses] shift string Turno do curso. Mais informações sobre esse atributo aqui
[courses] period_kind string Periodicidade do curso. Mais informações sobre esse atributo aqui
[courses] max_periods string Quantidade de periodicidade. Mais informações sobre esse atributo aqui
[courses] enrollment_semester string Semestre de matrícula do curso
[courses] full_price float Preço do curso sem desconto
[courses] discount_percentage float Porcentagem de desconto do Quero Bolsa.
[courses] price_with_discount float Preço do curso com desconto
[courses] regressive_commercial_discount float Desconto regressivo disponibilizado pela universidade. Esta parcela do desconto pode ser alterada ao longo do curso. Quando não fornecido, assume-se 0
[courses] fixed_commercial_discount float Desconto fixo disponibilizado pela instituição no seu balcão. Esta parcela do desconto não é alterado ao longo do curso. Quando não fornecido, assume-se 0
[courses] end_date string Data de término da validade da oferta
[courses] number_of_installments integer Número de parcelas que o curso será pago. Caso não informado, será considerado que o curso é pago em mensalidades e na mesma duração do mesmo.

Parâmetros da resposta

Nome Tipo Descrição
error boolean Indicador de ocorrência de erro na operação
operation_id string ID da operação de estoque criada

Operações de estoque

Todas as operações de atualização do estoque são feitas em processos assíncronos. Para ter informações do progresso e estado atual da operação, é fornecido um identificador único da operação no fim de toda ação de atualização da API.

Com esse ID, é possível saber o estado atual da operação, quantas inserções foram feitas com sucesso, quantas inserções tiveram falhas ao serem executadas, entre outras informações.

Atributos de operações de estoque

As entidades de operação de estoque possuem atributos que seguem padrões de preenchimento. Nessa seção, vamos conferir quais são esses atributos e os valores possíveis de cada um.

Status

As operações de estoque têm um estado e esse estado muda conforme a operação é executada.

Lista de valores possíveis do campo status:

Valor Descrição
created Operação criada
validating Operação em processo de validação
validation_ok Operação validada com sucesso
validation_error Erro ao validar a operação
applying Aplicando operação na base de dados
success Operação aplicada com sucesso
error Erro ao aplicar operação

Informações de uma operação de estoque específica

Exemplo de requisição

curl "https://stock.querobolsa.com.br/api/stock_operations/4e8c23c3-fab1-486d-9c0e-c49301305d94" \
  -H 'Authorization: Bearer ##########' \
  -H 'Content-Type: application/json'

Exemplo de retorno JSON para esta requisição:

{
  "id": "4e8c23c3-fab1-486d-9c0e-c49301305d94",
  "status": "success",
  "success_count": 2,
  "error_count": 0,
  "validation_success_count": 2,
  "validation_error_count": 0,
  "created_at": "2019-04-10T03:15:44Z",
  "finished_at": "2019-04-10T03:16:15Z"
}

Retorna dados de operação de estoque específica.

Requisição HTTP

GET https://stock.querobolsa.com.br/api/stock_operations/<STOCK_OPERATION_ID>

Parâmetros da requisição

Nome Tipo Descrição
STOCK_OPERATION_ID path ID da universidade onde deseja realizar a ação

Parâmetros da resposta

Nome Tipo Descrição
id string Código identificador de operação de estoque
status string Estado atual da operação de estoque
success_count integer Número de operações no banco de dados realizadas com sucesso
error_count integer Número de operações no banco de dados realizadas que falharam
validation_success_count integer Número de operações no banco de dados que foram validadas com sucesso
validation_error_count integer Número de validações de operações no banco de dados que falharam
created_at string Data e hora combinadas da criação da operação de estoque em formato UTC ISO 8601
finished_at string Data e hora combinadas da finalização da operação de estoque em formato UTC ISO 8601

Erros

De maneira geral, o Quero Bolsa interpreta as respostas dos serviços de acordo com a especificação abaixo:

Código de erro Descrição
400 Erro de validação dos parâmetros de entrada
401 Cliente do serviço não enviou token de autenticação
403 Cliente do serviço não tem permissão para acessar
404 Dado não encontrado com o caminho ou parâmetros fornecidos
Demais status Serão considerados erros internos do servidor. Entre em contato com o setor de tecnologia do Quero Bolsa.