= Expresso Web Service =


Este ''Draft'' é destinado à especificação dos requisitos referentes à implementação da ''API'' do Expresso para aplicativos móveis. Todas as informações contidas neste documento poderão sofrer alterações sem aviso prévio, até o fechamento do escopo deste subprojeto do Expresso.


----
== 1. Objetivo ==

Realizar tarefas de Email/Contatos/Agenda entre outros módulos com a autenticação do usuário, através de uma requisição para a API.


----
== 2. Compatibilidade ==

API: Versões = 2.2 e 2.4

ExpressoMail: Versões = 2.2 e 2.4

ContactCenter: Versões = 2.2 e 2.4


----
== 3. Arquitetura ==



----
== 4. Protocolo de Comunicação ==

Versão atual do JSON-RPC: 2.0


----
== 5. Referências ==

 * JSON-RPC 2.0 Specification -> [http://www.jsonrpc.org/specification http://www.jsonrpc.org/specification]

 * JSON-RPC 1.0 Specification -> [http://json-rpc.org/wiki/specification http://json-rpc.org/wiki/specification]

 * Specification for Fault Code Interoperability -> [http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php]

 * JSON-RPC Implementations -> [http://en.wikipedia.org/wiki/JSON-RPC#Implementations http://en.wikipedia.org/wiki/JSON-RPC#Implementations]


----
== 6. Recursos disponíveis ==


=== Métodos implementados no site Expresso Livre.org ===
\
\
||'''Método:'''||'''/AvailableServers'''||Retorna uma lista de servidores do expresso, para que centralize uma lista de servidores ativos que estao utilizando a nova API.||
||'''Parâmetros:'''|| Sem Parametros || ||
||'''Retorno:'''||-serverName,\-serverDescription,\-serverUrl,\-serverContext,\-serverStatus|| ||
||Retorno de Exemplo (JSON):||||{"result":{"servers":[{"serverID":"007","serverName":"dev.expresso.celepar.parana","serverDescription":" Servidor de Homologau00e7u00e3o - versu00e3o 2.4","serverUrl":"http://dev.expresso.celepar.parana","serverContext":"/api/rest/","serverStatus":"1"}]},"error":null,"id":"1"}
\

=== Métodos implementados na API do Expresso ===

\
\
||'''Método:'''||'''/Login'''||Criar sessão autenticada no Expresso||
||'''Parâmetros:'''||-user\-password\-auth||-Login do Usuario.\-Senha do usuario.\-Autenticacao existente, caso ja esteja logado.||
||'''Retorno:'''||-auth\-profile[] array(\contactID,\contactMails[],\contactPhones[],\contactFullName\)\||auth: Chave de autenticacao do expresso (KP3+SESSIONID do usuario).\profile: Array Contendo informações do usuário.\contactID: uidNumber do usuário\contactMails[]: Endereço de email\contactPhones[]: Telefone comercial (corporativo)\contactFullName: Nome completo\\||
||Retorno de Exemplo (JSON):||||{"result":{"auth":"m23clvc6r737paho9d1oeu2527:22503c5682f25bf48bbe7b172c742e0d","profile":[{"contactID":1010,"contactMails":["niltonneto@ecelepar16828.celepar.parana"],"contactPhones":["(41)3200-5297"],"contactFullName":"Nilton Neto"}]},"error":null,"id":1}
\
\
||'''Método:'''||'''/Logout'''||Finalizar sessão autenticada no Expresso||
||'''Parâmetros:'''||-auth||auth:Autenticacao existente, necessaria para destruir a sessao do usuario.||
||'''Retorno:'''||-hasLogout||-hasLogout:(Boolean 0 ou 1 indicando se o logout foi realizado com sucesso)||
\
\
||'''Método:'''||'''/Mail/Folders'''||Listar pastas de Email||
||'''Parâmetros:'''||-auth\-search\-page\-resultsPerPage||auth:Autenticacao do usuario.\search:filtro por nome de pasta\page:pagina atual\resultsPerPage:Numero de resultados a retornar por pagina.||
||'''Retorno:'''||-folders array(\folderName,\folderID,\folderType,\folderParentID,\folderHasChildren,\qtdMessages,\qtdUnreadMessages,\percentUsageOfTotalQuota,\diskSize\)\-diskSizeUsed\-diskSizeLimit\-diskSizePercent||folders:Array com todas as pastas retornadas.\folderName:Nome da pasta.\folderID:Caminho da pasta\folderType:(1-Caixa de Entrada,2-Enviadas,3-Rascunhos,4-Lixeira,5-Pasta Comum,6-Pasta Compartilhada)\folderHasChildren:(Boolean 0 ou 1)Indica se a pasta possui sub-pastas ou nao.\qtdMessages:Quantidade de Mensagens na pasta.\qtdUnreadMessages:Quantidade de Mensagens nao lidas.\percentUsageOfTotalQuota:Percentual utilizado da quota do usuario para esta pasta.\diskSize:Tamanho total da pasta utilizado do disco em Bytes.\\diskSizeUsed:Utilizacao total da quota do usuario\diskSizeLimit:Limite de Quota total do Usuario.\diskSizePercent:Percentual de utilizacao da quota total do usuario.||
||Exemplo de Retorno (JSON):||||{"result":{"folders":[{"folderName":"Caixa de Entrada","folderParentID":"","folderHasChildren":0,"qtdUnreadMessages":0,"qtdMessages":1176,"folderID":"INBOX","folderType":0,"diskSizeUsed":"43526754","diskSizePercent":0.297},{"folderName":"Enviado","folderParentID":"","folderHasChildren":0,"qtdUnreadMessages":0,"qtdMessages":412,"folderID":"INBOX/Enviado","folderType":1,"diskSizeUsed":"4898464","diskSizePercent":0.033},{"folderName":"Spam","folderParentID":"","folderHasChildren":0,"qtdUnreadMessages":0,"qtdMessages":0,"folderID":"INBOX/Spam","folderType":2,"diskSizeUsed":"0","diskSizePercent":0},{"folderName":"Lixeira","folderParentID":"","folderHasChildren":0,"qtdUnreadMessages":135,"qtdMessages":135,"folderID":"INBOX/Lixeira","folderType":3,"diskSizeUsed":"133650","diskSizePercent":0.001}],"diskSizeUsed":95126528,"diskSizeLimit":146800640,"diskSizePercent":0.64},"error":null,"id":"3"}
\
\
||'''Método:'''||'''/Mail/Messages'''||Listar mensagens de uma pasta de Email||
||'''Parâmetros:'''||-auth\-folderID\-msgID\-search\-page\-resultsPerPage||auth:Autenticacao do usuario.\folderID:Filtro por pastas (so retornara mensagens da pasta informada)\\search:filtro por assunto da mensagem, conteudo.\page:pagina atual\resultsPerPage:Numero de resultados a retornar por pagina.||
||'''Retorno:'''||messages array(\msgID,\folderID,\msgDate,\msgFrom array(fullName,mailAddress),\msgTo array(array(fullName,mailAddress)),\msgReplyTo array(array(fullName,mailAddress)),\msgCC array(array(fullName,mailAddress)),\msgBCC array(array(fullName,mailAddress)),\msgBodyResume,\msgBody,\msgSeen,\msgHasAttachments,\msgAnswered,\msgFlagged,\msgDeleted,\msgDraft,\msgForwarded,\msgSize\)||-messages:Array com todas as mensagens retornadas.\msgID:Identificador da mensagem.\folderID:Identificador da Pasta da Mensagem.\msgDate:(YYYY-mm-dd H:i:s) \msgFrom: Array com o Nome do contato e email (fullName,mailAddress)\msgReplyTo,msgTo,msgCC,msgBCC: Sao arrays e retornam N arrays contendo (fullName,mailAddress)\msgBodyResume:Resumo do conteudo da mensagem (sem tags html)\msgBody:Conteudo da Mensagem, campo somente retorna valores quando e passado o parametro msgID que especifica qual mensagem sera exibida.\msgSeen:Boolean indicando se a mensagem foi marcada como lida.\msgHasAttachments:Boolean - indica se tem anexos ou nao.\msgAnswered:Boolean - flag do imap para Respondida\msgFlagged:Boolean - flag do imap para importantes\msgDeleted:Boolean - flag do imap para Deleted.\msgDraft:Boolean - flag do imap para Drafts.\msgForwarded:\msgSize:Tamanho da mensagem em Bytes.||
||Retorno de Exemplo (JSON):||||{"result":{"messages":[{"msgID":2247,"folderID":"INBOX","msgDate":"21/03/2012 11:24","msgFrom":{"fullName":"Servi","mailAddress":"no-reply-workflow"},"msgTo":[{"fullName":"pereira.jair","mailAddress":"pereira.jair"}],"msgReplyTo":[{"fullName":"","mailAddress":"no-reply-workflow@celepar.pr.gov.br"}],"msgSubject":"Solicitau00e7u00e3o ABORTADA: P-336589","msgHasAttachments":"0","msgFlagged":"0","msgForwarded":"0","msgAnswered":"0","msgDraft":"0","msgSeen":"1","ContentType":"normal","msgSize":"5120","msgBodyResume":" ATENu00c7u00c3O: Essa mensagem foi gerada pelo sistema e nu00e3o deve ser respondida!SUA SOLICITAu00c7u00c3O FOI ABORTADA!Dados da solicitau00e7u00e3oPROTOCOLOP-336589 Clique aqui para visualizar a solicitau00e7u00e3oSolicitanteJair Goncalves Pereira JuniorCategoriaAmbientes - Estau00e7u00e3oServiu00e7oDesktop - Suporte avanu00e7ado, 2o. nu00edve"}],"timeZone":-10800,"totalUnseen":0},"error":null,"id":"16"}||
\
\
||'''Método:'''||'''/Mail/RenameFolder'''||Renomeia uma pasta, Retorna um erro caso ja exista uma pasta com esse nome.||
||'''Parâmetros:'''||-auth\-folderID\-folderName||auth:Autenticacao do usuario.\folderID: ID da pasta na qual sera renomeada.\folderName:Nome da Nova Pasta.||
||'''Retorno:'''||-folderID||folderID: Identificador da nova pasta.||
||Retorno de Exemplo (JSON):||||{"result":{"folderID":"INBOX/NovaPasta"},"error":null,"id":"6"}||
\
\
||'''Método:'''||'''/Mail/AddFolder'''||Adiciona uma nova pasta, Retorna um erro caso ja exista uma pasta com esse nome.||
||'''Parâmetros:'''||-auth\-parentFolderID\-folderName||auth:Autenticacao do usuario.\parentFolderID:Pasta Raiz na qual sera criada uma nova pasta.\folderName:Nome da Nova Pasta.||
||'''Retorno:'''||-folderID||folderID: Identificador da nova pasta.||
||Retorno de Exemplo (JSON):||||{"result":{"folderID":"INBOX/NovaPasta"},"error":null,"id":"6"}||
\
\
||'''Método:'''||'''/Mail/DelFolder'''||Remove uma pasta de um usuario.||
||'''Parâmetros:'''||-auth\-folderID||auth:Autenticacao do usuario.\folderID:FolderID da pasta que sera removida.||
\
\
||'''Método:'''||'''/Mail/CleanTrash'''||Limpa a lixeira.||
||'''Parâmetros:'''||-auth||auth:Autenticacao do usuario.||
||'''Retorno:'''||-TRUE||- Boolean TRUE, caso tenha sido enviado, ou erro ''1003 - "Your trash folder could not be cleaned."''||
\
\
||'''Método:'''||'''/Mail/SendSupportFeedback'''||Envia um email de sugestao para o administrador do expresso, a funcao devera enviar uma mensagem como se fosse o usuario logado para o administrador.||
||'''Parâmetros:'''||-auth\-message||auth:Autenticacao do usuario.\message:Mensagem que sera enviada para o administador do expresso.||
||'''Retorno:'''||-TRUE||- Boolean TRUE, caso tenha sido enviado, ou erro ''1002 - "Your mail could not be sent."''||
||Retorno de Exemplo (JSON):||||{"result":TRUE,"error":null,"id":"6"}||
\
\
||'''Método:'''||'''/Catalog/Contacts'''||Retorna os Contatos do usuario, pode trazer os contatos pessoais da agenda, como do catalogo geral, diferenciando-os apenas pelo type.||
||'''Parâmetros:'''||-auth\-search\-contactType\-page\-resultsPerPage||auth:Autenticacao do usuario.\search: busca por nome ou email do contato.\contactType:(1:Agenda do Expresso,2:Catalogo Geral.)||
||'''Retorno:'''||-contacts array(\contactID,\contactFullName,\contactAlias,\contactFirstName,\contactLastName,\contactHasImagePicture,\contactType,\contactMails array(),\contactPhones,\contactBirthDate,\contactNotes\)||contactID: Identificador do Contato.\contactFullName:Nome completo do Contato\contactFirstname:Primeiro nome do contato\contactLastName:Ultimo Nome do Contato\contactHasImagePicture:Boolean (0:Nao tem foto,1:possui foto).\contactType:(1:Agenda do Expresso,2:Catalogo Geral.)\contactMails:Array com os Emails do contato.\contactPhones:Array com os telefones do contato.||
||Retorno de Exemplo (JSON):||||{"result":{"contacts":[{"contactID":"817662","contactMails":["exemplodecontato@celepar.pr.gov.br"],"contactAlias":"nome do contato","contactFirstName":"nome do contato","contactLastName":"","contactFullName":"nome do contact","contactBirthDate":"","contactNotes":"","contactHasImagePicture":0}]},"error":null,"id":"4"}||
\
\
||'''Método:'''||'''/Catalog/ContactPicture'''||Retorna o BASE64 da Imagem de Um contato.||
||'''Parâmetros:'''||-auth\-search\-contactType\contactID||auth:Autenticacao do usuario.\contactType:(1:Agenda do Expresso,2:Catalogo Geral.)\contactID:Identificador do Contato.||
||'''Retorno:'''||-contacts array(\contactID,\contactImagePicture\)||contactID: Identificador do Contato.\contactImagePicture:Base64 da foto do contato.||
||Retorno de Exemplo (JSON):||||{"result":{"contacts":[{"contactID":"811138","contactImagePicture":"BASE64"}]},"error":null,"id":"6"}||
\
\
||'''Método:'''||'''/Calendar/Events'''||Retorna os Eventos do usuario em um determinado periodo.||
||'''Parâmetros:'''||-auth\-dateStart\-dateEnd\-splitEvent||-Autenticacao do Usuario\-Data Inicial de Pesquisa\-Data Final de Pesquisa\-Boolean (1 ou 0) Indicando se os eventos de mais de 1 dia devem ser quebrados, ou não||
||'''Retorno:'''||-events array (\ - eventID\ - eventStartDate\ - eventEndDate\ - eventName\ - eventDescription\ - eventLocation\)||||
\
\
||'''Método:'''||'''/Mail/MoveMessage'''||Move uma mensagem de uma pasta para outra.||
||'''Parâmetros:'''||-auth\-msgID\-folderID\-newFolderID||auth:Autenticacao do usuario.\msgID:ID da mensagem que sera movida.\folderID:FolderID da pasta que esta a mensagem.\ newFolderID:ID da pasta para qual a mensagem sera movida.||
\
\
||'''Método:'''||'''/Mail/DelMessage'''||Apaga uma Mensagem do Servidor.||
||'''Parâmetros:'''||-auth\-msgID||auth:Autenticacao do usuario.\msgID:ID da mensagem que sera apagada.||
\
\
||'''Método:'''||'''/Mail/Send'''||Envia uma Mensagem.||
||'''Parâmetros:'''||-auth\-msgSubject\-msgTo\-msgFrom\-msgContent\-msgForwardTo\-msgCcTo\-msgBccTo\-originalMsgID\-originalUserAction - (1:Forwarded,2:Reply,3:ReplyToAll)||auth:Autenticacao do usuario.||
\
\
||'''Método:'''||'''/Mail/SaveAsDraft'''||Salva uma mensagem como Rascunho.||
||'''Parâmetros:'''||-auth\-msgSubject\-msgTo\-msgFrom\-msgContent\-msgForwardTo\-msgCcTo\-msgBccTo\-originalMsgID\-originalUserAction - (1:Forwarded,2:Reply,3:ReplyToAll)||auth:Autenticacao do usuario.||



\
\
== 7. Tabela com Código de Erros ==
\
\
# Errors from -32000 to -32099 => Server error: Reserved for implementation-defined server-errors.

||-32700||E_PARSE_ERROR||Parse error||
||-32600||E_INVALID_REQUEST||Invalid Request||
||-32601||E_METHOD_NOT_FOUND||Method not found||
||-32602||E_INVALID_PARAMS||Invalid params||
||-32603||E_INTERNAL_ERROR||Internal error||
||404||E_HTTP_NOT_FOUND||A resource matching URI '%1' was not found||
||500||E_UNKNOWN_ERROR||HTTP Unknown error||

# Errors inherited from Expresso Application.
||1||LOGIN_SUCCESS_LOGOUT||You have been successfully logged out||
||2||LOGIN_SESSION_EXPIRED||Sorry, your login has expired||
||3||LOGIN_NOT_LOGGED_IN||You are not logged in||
||4||LOGIN_COOKIES_REQUIRED||Cookies are required to login to this site.||
||5||LOGIN_BADLOGIN||bad login or password||
||6||LOGIN_PASSWORD_EXPIRED||Your password has expired, and you do not have access to change it||
||7||LOGIN_AUTH_INVALID||Your auth is invalid||
||10||LOGIN_SESSION_NOT_VERIFIED||Your session could not be verified.||
||98||LOGIN_ACCOUNT_EXPIRED||Account is expired||
||99||LOGIN_LOGIN_BLOCKED||Blocked, too many attempts!||
||200||LOGIN_INVALID_LOGIN||Bad login or password||
	
||1001||CATALOG_MIN_ARGUMENT_SEARCH||Your search argument must be longer than %1 characters.||
||1002||MAIL_NOT_SENT||Your mail could not be sent.||
||1003||MAIL_TRASH_NOT_CLEANED||Your trash folder could not be cleaned.||
||1004||MAIL_MESSAGE_NOT_FOUND||Message not found in folder %1.||
||1005||MAIL_INVALID_NEW_FOLDER_NAME||Invalid folder name.||
||1006||MAIL_INVALID_OLD_FOLDER||Invalid old folder.||
||1007||MAIL_INVALID_FOLDER||Invalid folder.||
||1008||MAIL_CANNOT_DEL_DEFAULT_FOLDER||Cannot delete a default folder.||
||1009||MAIL_FOLDER_NOT_EMPTY||The folder is not empty.||
||1010||MAIL_FOLDER_NOT_RENAMED||The folder could not be renamed.||
||1011||MAIL_FOLDER_NOT_ADDED||The folder could not be added.||
||1012||MAIL_FOLDER_NOT_DELETED||The folder could not be deleted.||
||1013||MAIL_FOLDER_LIMIT_REACHED||Folder limit has been reached.||
||1014||CALENDAR_INVALID_START_DATE||Invalid start date.||
||1015||CALENDAR_INVALID_END_DATE||Invalid end date.||
||1016||MAIL_INVALID_MESSAGE||Message does not exists.||
||1017||MAIL_TRASH_FOLDER_NOT_EXISTS||Trash folder does not exists.||
||1018||MAIL_NOT_SENT_LIMIT_EXCEEDED||The size of this message has exceeded  the limit (%1B).||