Aqui você encontrará toda a documentação da gem de integração: como configurar, como utilizar e como trabalhar com os retornos.

COMEÇANDO

Caso não esteja utilizando o Rails você pode integrar seu sistema com o Soullab por meio de nossa ruby gem. Para fazer o download acesse um terminal e digite:

gem install soullab
Este comando instalará a soullab gem e todas as dependências para você. Caso você use o Rails adicione em seu Gemfile a seguinte linha:
gem 'soullab'
Salve o arquivo Gemfile e em seguida execute:
bundle install
Este conjunto de comandos também instalará a soullab gem e todas as dependências para você.

UTILIZANDO

Agora que a gem foi instalada é possível utilizá-la em seu sistema. Abra um controlador e crie um objeto para gerenciar a integraçáo:

soullab = Soullab.new("CODIGO DA EMPRESA", "CAMINHO/PARA/CHAVE/PRIVADA", "SENHA DA CHAVE", IDIOMA_PADRAO)
Neste ponto será necessário que você entre em contato conosco, por email, para que sua empresa seja autorizada... Ao final deste processo você receberá o seu código, chave privada e senha da mesma. O idioma padrão é definido através de códigos, estes estáo definidos em uma tabela disponibilizada no final desta página.

Com o objeto pronto para uso, você terá acesso aos seguintes métodos:

  • check_circleintegrarEscola
  • check_circleintegrarProfessor
  • check_circleintegrarTurma
  • check_circleintegrarAluno
  • check_circleintegrarHorarios
  • check_circleintegrarEnturmamento
DETALHAMENTO DOS MÉTODOS

integrarEscola("CODIGO","NOME DA ESCOLA","CEP: XXXXX-XXX","NOME CIDADE","UF","BAIRRO","RUA","NUMERO","COMPLEMENTO","TELEFONE FIXO: (XX)XXXX-XXXX ou (XX)XXXX-XXXXX","TELEFONE CELULAR: (XX)XXXX-XXXX ou (XX)XXXX-XXXXX","NOME DO GESTOR","EMAIL DO GESTOR","LOGIN DO GESTOR")

integrarProfessor("CODIGO DA ESCOLA", "LOGIN DO PROFESSOR", "NOME DO PROFESSOR", "RUA", "NUMERO", "COMPLEMENTO", "BAIRRO", "CIDADE", "CEP: XXXXX-XXX", "UF", "TELEFONE FIXO: (XX)XXXX-XXXX ou (XX)XXXX-XXXXX", "TELEFONE CELULAR: (XX)XXXX-XXXX ou (XX)XXXX-XXXXX", "EMAIL DO PROFESSOR")

integrarTurma("CODIGO DA ESCOLA", "CODIGO DA TURMA", "LOGIN DO PROFESSOR", "DATA INICIO: VERIFICAR FORMATO NA PLANILHA", "DATA FIM: VERIFICAR FORMATO NA PLANILHA", array_de_avisos)

integrarAluno("CODIGO DA ESCOLA", "LOGIN DO ALUNO", "NOME DO ALUNO", "RUA", "NUMERO", "COMPLEMENTO", "BAIRRO", "CIDADE", "CEP: XXXXX-XXX", "UF", "TELEFONE FIXO: (XX)XXXX-XXXX ou (XX)XXXX-XXXXX", "TELEFONE CELULAR: (XX)XXXX-XXXX ou (XX)XXXX-XXXXX", "EMAIL DO ALUNO")

integrarHorarios("CODIGO DA ESCOLA", "CODIGO DA TURMA", hash_de_horarios)

integrarEnturmamento("CODIGO DA ESCOLA", "CODIGO DA TURMA", hash_de_matriculas)

array_de_avisos: deve conter no máximo 3 avisos ou uma array vazia. Cada aviso pode conter até 29 caracteres. Exemplo: ["Aviso1", "Aviso2", "Aviso3"] ou []

array_de_horarios: deve conter uma hash no seguinte formato [{inicio: "dd/mm/yyyy hh:mm:ss", fim: "dd/mm/yyyy hh:mm:ss"}, ...]

array_de_matriculas: deve conter uma hash no seguinte formato [{login: "LOGIN DO ALUNO"}, ...]

* As reticências significam que podem existir mais elementos na array seguindo o formato proposto.

RETORNOS

Todo retorno do webservice é um objeto JSON e para uma melhor manipulação do objeto este é convertido para uma hash: {"success"=>false/true, "message"=>"CODE"}

POSSÍVEIS RETORNOS DO WEBSERVICE
CÓDIGO DESCRIÇÃO
1 A requisição não foi processada: a ação solicitada não foi executada devido a algum problema em nossos servidores.
2 Requisição processada: a ação solicitada foi executada.
3 Existem parâmetros inválidos em sua requisição. Verifique a documentação.
4 Esta requisição foi ignorada porque seu tempo já se esgotou.
5 Houve quebra na integridade da mensagem! A requisição foi ignorada.
6 Falha no cadastro das informações contidas na requisição.
7 Falha na inicialização da escola.
21 Empresa não autorizada.
22 A escola informada não pertence a sua empresa ou não existe. Verifique o código da escola.
POSSÍVEIS RETORNOS NO CADASTRO DE ESCOLA
CÓDIGO DESCRIÇÃO
8 Código da escola inválido. Este parâmetro deve ser alfanumérico.
9 Nome da escola inválido. Este parâmetro deve conter apenas letras (A-Z ou a-z).
10 Nome do gestor inválido. Este parâmetro deve conter apenas letras (A-Z ou a-z).
11 Email do gestor inválido. Este parâmetro deve conter um email válido.
12 Telefone inválido. Este campo não é obrigatório pode ser usado uma string vazia (“”) ou formatar o dado para (xx)xxxx-xxxx ou (xx)xxxxx-xxxx
13 Celular inválido. Este campo não é obrigatório pode ser usado uma string vazia (“”) ou formatar o dado para (xx)xxxx-xxxx ou (xx)xxxxx-xxxx
14 Rua inválida. Este parâmetro deve conter apenas letras (A-Z ou a-z).
15 Número da residência inválido. Este parâmetro deve conter apenas números.
16 Complemento inválido. Este parâmetro não é obrigatório use uma string vazia (“”) ou garanta que o dado contenha apenas caracteres alfanuméricos.
17 Bairro inválido. Este parâmetro deve conter apenas letras (A-Z ou a-z)
18 Cidade inválida. Este parâmetro deve conter apenas letras (A-Z ou a-z)
19 CEP inválido. Este parâmetro deve seguir o formato xxxxx-xxx
20 Login inválido. Este parâmetro deve conter dados no formato alfanumérico.
36 UF inválida. Este parâmetro deve conter apenas 2 caracteres no format (A-Z).
38 Sua empresa já possui uma escola com este código. O Código deve ser único.
39 Já existe um gestor com este login, escolha um outro. O login deve ser único.
POSSÍVEIS RETORNOS NO CADASTRO DE PROFESSOR
CÓDIGO DESCRIÇÃO
23 Login do professor inválido. Este parâmetro deve ser alfanumérico.
24 Telefone inválido. Este campo não é obrigatório pode ser usado uma string vazia (“”) ou formatar o dado para (xx)xxxx-xxxx ou (xx)xxxxx-xxxx
25 Celular inválido. Este campo não é obrigatório pode ser usado uma string vazia (“”) ou formatar o dado para (xx)xxxx-xxxx ou (xx)xxxxx-xxxx
26 Rua inválida. Este parâmetro deve conter apenas letras (A-Z ou a-z). Campo não obrigatório.
27 Número da residência inválido. Este parâmetro deve conter apenas números. Campo não obrigatório.
28 Complemento inválido. Este parâmetro não é obrigatório use uma string vazia (“”) ou garanta que o dado contenha apenas caracteres alfanuméricos.
29 Bairro inválido. Este parâmetro deve conter apenas letras (A-Z ou a-z). Campo não obrigatório.
30 Cidade inválida. Este parâmetro deve conter apenas letras (A-Z ou a-z). Campo não obrigatório.
31 CEP inválido. Este parâmetro deve seguir o formato xxxxx-xxx. Campo não obrigatório.
32 Código da escola inválido. Este parâmetro deve ser alfanumérico.
33 Email do professor inválido. Este parâmetro deve conter um email válido.
34 Nome do professor inválido. Este parâmetro deve conter apenas letras (A-Z ou a-z).
35 UF inválida. Este parâmetro deve conter apenas 2 caracteres no format (A-Z). Campo não obrigatório.
37 Um professor com este login já existe em sua escola. O login deve ser único.
POSSÍVEIS RETORNOS NO CADASTRO DE TURMA
CÓDIGO DESCRIÇÃO
40 Código da escola inválido. Este parâmetro deve ser alfanumérico.
41 Código da turma inválido. Este parâmetro deve ser alfanumérico.
42 Ano da turma inválido. Este parâmetro deve ser numérico e deve ser igual ou superior ao ano atual.
43 Período da turma inválido. Este parâmetro deve ser numérico e deve assumir o valor de 1 ou 2 (primeiro ou segundo semestre do ano).
44 Login do professor inválido. Este parâmetro deve ser alfanumérico.
45 Data início inválida. Este parâmetro deve ser formatado de acordo com o idioma. PORTUGUÊS e ESPANHOL → dia/mês/ano / INGLÊS → ano-mês-dia.
46 Data término inválida. Este parâmetro deve ser formatado de acordo com o idioma. PORTUGUÊS e ESPANHOL → dia/mês/ano / INGLÊS → ano-mês-dia.
47 Campo não obrigatório. Deve conter um vetor vazio ou um vetor com no máximo 3 mensagens de 29 caracteres cada.
48 Um dos avisos informados possui mais de 29 caracteres. Verifique-os ou use um vetor vazio ( [ ] ) para pular este parâmetro.
49 Uma turma com o código informado já existe. O código da turma deve ser único dentro de uma escola.
50 Não foi encontrado nenhum professor com o login informado. Verifique o login do professor e tente novamente.
POSSÍVEIS RETORNOS NO CADASTRO DE ALUNO
CÓDIGO DESCRIÇÃO
51 Login do aluno inválido. Este parâmetro deve ser alfanumérico.
52 Telefone inválido. Este campo não é obrigatório pode ser usado uma string vazia (“”) ou formatar o dado para (xx)xxxx-xxxx ou (xx)xxxxx-xxxx
53 Celular inválido. Este campo não é obrigatório pode ser usado uma string vazia (“”) ou formatar o dado para (xx)xxxx-xxxx ou (xx)xxxxx-xxxx
54 Rua inválida. Este parâmetro deve conter apenas letras (A-Z ou a-z). Campo não obrigatório.
55 Número da residência inválido. Este parâmetro deve conter apenas números. Campo não obrigatório.
56 Complemento inválido. Este parâmetro não é obrigatório use uma string vazia (“”) ou garanta que o dado contenha apenas caracteres alfanuméricos.
57 Bairro inválido. Este parâmetro deve conter apenas letras (A-Z ou a-z). Campo não obrigatório.
58 Cidade inválida. Este parâmetro deve conter apenas letras (A-Z ou a-z). Campo não obrigatório.
59 CEP inválido. Este parâmetro deve seguir o formato xxxxx-xxx. Campo não obrigatório.
60 UF inválida. Este parâmetro deve conter apenas 2 caracteres no format (A-Z). Campo não obrigatório.
61 Código da escola inválido. Este parâmetro deve ser alfanumérico.
62 Email do aluno inválido. Este parâmetro deve conter um email válido.
63 Nome do aluno inválido. Este parâmetro deve conter apenas letras (A-Z ou a-z).
64 Um aluno com este login já existe em sua escola. O login deve ser único.
POSSÍVEIS RETORNOS NO CADASTRO DE HORÁRIOS
CÓDIGO DESCRIÇÃO
65 A turma informada não existe. Verifique o código da mesma.
66 Não existem horários a serem cadastrados em sua requisição.
67 Código da escola inválido. Este parâmetro deve ser alfanumérico.
68 Código da turma inválido. Este parâmetro deve ser alfanumérico.
69 Verifique o formato dos horários iniciais, os mesmos devem seguir o formato dia/mes/ano hora:minuto:segundo quando usado o idioma PORTUGUÊS ou ESPANHOL. Quando o idioma for INGLÊS o formato deve ser ano-mes-dia hora:minuto:segundo
70 Verifique o formato dos horários de término, os mesmos devem seguir o formato dia/mes/ano hora:minuto:segundo quando usado o idioma PORTUGUÊS ou ESPANHOL. Quando o idioma for INGLÊS o formato deve ser ano-mes-dia hora:minuto:segundo
71 Na lista de horários existe(m) horário(s) onde o horário de término é menor que o horário de início.
72 Na lista de horários existe(m) horário(s) onde a diferença de tempo entre o horário de término e o horário de início é menor que uma hora. Obrigatóriamente os horários devem cobrir o período de uma ou mais horas... Ex: (Horário Inicial → 04/12/2015 10:30:00 / Horário de Término → 04/12/2015 11:30:00)
73 Existem horários duplicados na lista informada.
74 Existem horários que se intersectam na lista informada.
POSSÍVEIS RETORNOS NO CADASTRO DE ENTURMAMENTOS
CÓDIGO DESCRIÇÃO
75 A turma informada não existe. Verifique o código da mesma.
76 Código da escola inválido. Este parâmetro deve ser alfanumérico.
77 Código da turma inválido. Este parâmetro deve ser alfanumérico.
78 Não existem alunos a serem cadastrados em sua requisição. Envie uma lista com os logins dos alunos a serem enturmados.
79 Na lista de alunos existe um ou mais alunos inválidos. Os logins devem ser alfanuméricos e não é aceito strings vazias.
80 Existem alunos na lista de enturmamento que não existem. Cadastre-os e tente novamente.
DEFINIÇÃO DE IDIOMAS
CÓDIGO DESCRIÇÃO
0 Português
1 Inglês
2 Espanhol