API
Introdução
A API da Superlógica é impementada com JSON (http://pt.wikipedia.org/wiki/JSON ) sobre HTTP usando verbos como GET/POST/PUT/DELETE.
Tentamos seguir os padrões de APIs REST (http://en.wikipedia.org/wiki/Representational_State_Transfer) o máximo que nossos sitemas legados nos permitiram.
Versionamento
A API pode ser versionada ou não. Isto depende do servidor a ser utilizado. A versão a qual se pretende utilizar é definida na URL de requisição.
O formato padrão da URL é este: http://HOST/APPID/VERSAO/. Em versão, é possível utilizar a constante "atual" para acessar a última versão disponível, ou escolha uma da lista de versões disponíveis em: http://HOST/ . APPID é a identificação do aplicativo que pode ser: financeiro ou condor.
Requisição
As requisições devem seguir o padrão JSON passados via POST identificado pela string "JSON". As requisições devem conter as seguintes informações:
- url: devido a sistema legado é recomendado que a url seja informada aqui também;
- session: após a autenticação um número de sessão é informado o qual deve ser passado nas requisições posteriores;
- params: Um array de array contendo as informações a serem passadas para o sistema. Permite realizar diversas requisições em lote para a mesma URL. Sugerimos enviar lotes de no máximo 50 requisições por vez.
{ "url": "sacados/put", "session": "7738779ffbb02d30dc92b8c1de614247","params": {
"0": {
"ST_CEP_SAC": "",
"DT_CADASTRO_SAC": "03\/05\/2012",
"ST_DIAVENCIMENTO_SAC": "0",
"ST_NOME_SAC": "Cliente teste",
"ST_CONTRATO_SAC": "",
"DT_DESATIVACAO_SAC": "",
"ST_CGC_SAC": "",
"ST_CIDADE_SAC": "Campinas",
"ST_NOMEREF_SAC": "Cliente teste",
"ST_EMAIL_SAC": "",
"ST_SACADORCGC_SAC": "",
"TX_OBSERVACAO_SAC": "",
"ST_ESTADO_SAC": "SP",
"ST_SINCRO_SAC": "",
"ST_TELEFONE_SAC": "",
"ST_COMPLEMENTO_SAC": "",
"ST_NUMERO_SAC": "",
"DT_ALTERACAO_SINCRO": "05\/03\/2012",
"ST_ENDERECO_SAC": "Rua Teste",
"ST_INSCRICAO_SAC": "",
"ST_SACADORNOME_SAC": ""
}
"1": {
"ST_CEP_SAC": "",
"DT_CADASTRO_SAC": "03\/05\/2012",
"ST_DIAVENCIMENTO_SAC": "0",
"ST_NOME_SAC": "Cliente teste",
"ST_CONTRATO_SAC": "",
"DT_DESATIVACAO_SAC": "",
"ST_CGC_SAC": "",
"ST_CIDADE_SAC": "Campinas",
"ST_NOMEREF_SAC": "Cliente teste",
"ST_EMAIL_SAC": "",
"ST_SACADORCGC_SAC": "",
"TX_OBSERVACAO_SAC": "",
"ST_ESTADO_SAC": "SP",
"ST_SINCRO_SAC": "",
"ST_TELEFONE_SAC": "",
"ST_COMPLEMENTO_SAC": "",
"ST_NUMERO_SAC": "",
"DT_ALTERACAO_SINCRO": "05\/03\/2012",
"ST_ENDERECO_SAC": "Rua Teste",
"ST_INSCRICAO_SAC": "",
"ST_SACADORNOME_SAC": ""
}
}
}
Resposta
A resposta é dada também em formato JSON e contem os campos:
- status = obedece, sempre que possível, os códigos de status do http (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html ). Se o código for maior ou igual que 400 significa que houve um erro no processamento. Se tudo deu certo é provável que o status seja o 200;
- session = o número da sessão;
- msg = Em caso de erro, descreve qual foi o problema;
- data = Em caso de sucesso, um array com dados;
- executiontime = o tempo que a requisição levou para ser executada;
{"status":"200","session":"1bcf1b22da415ffb82176f9b67003b67","msg":"","data":[{"CAMPO1":"VALORCAMPO1","CAMPO2":" VALORCAMPO2"],"executiontime":"0.7681s"}
Observe que as requisições que retornam dados são paginadas em, normalmente, 50 itens. Este valor pode ser redefinido passando, a cada requisição, via post ou get "itensPorPagina". A próxima página pode ser obtida passando via post ou get a "pagina".
Autenticação
A autenticação ocorre via uma requisição a url "/auth/post", uma sessão é criada, o que permite o usuário fazer outras requisições sem precisar se autenticar, desde que informe o número de identificação da sessão na requisição. Para o login é necessário que as seguintes informações sejam passadas via POST: username, password, filename (filename é uma string que indica a instância ou licença a ser utilizada e é informada pela Superlógica).
No momento do login é possível que o sistema seja forçado a se atualizar (mudar de uma versão para a outra), se isto ocorrer o status de retorno será o 409, e é obrigatório uma requisição a url "auth/updateschema" para que isto ocorra, passando via POST novamente o filename. Após a atualização uma nova autenticação será exigida de todos os usuários logados.
Como utilizar
No final de cada página do software existe um link para o JSON que simular a mesma requisição feita pela página. Além disto, no Chrome é possível ver a troca de mensagens entre o servidor e o browser, que podem ser reproduzidas para se fazer o que necessita. Se você tem o navegador Chrome pressione CTRL+ SHIFT + I, entre na aba "Network" e faça uma requisição. Em Headers é possível ver a requisição e em Response a resposta do servidor.
