wiki:WebServiceDraft

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


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 Homologa\u00e7\u00e3o - vers\u00e3o 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:/LoginCriar 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:/LogoutFinalizar sessão autenticada no Expresso
Parâmetros:-authauth: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@…"}],"msgSubject":"Solicita\u00e7\u00e3o ABORTADA: P-336589","msgHasAttachments":"0","msgFlagged":"0","msgForwarded":"0","msgAnswered":"0","msgDraft":"0","msgSeen":"1","ContentType?":"normal","msgSize":"5120","msgBodyResume":" ATEN\u00c7\u00c3O: Essa mensagem foi gerada pelo sistema e n\u00e3o deve ser respondida!SUA SOLICITA\u00c7\u00c3O FOI ABORTADA!Dados da solicita\u00e7\u00e3oPROTOCOLOP-336589 Clique aqui para visualizar a solicita\u00e7\u00e3oSolicitanteJair Goncalves Pereira JuniorCategoriaAmbientes? - Esta\u00e7\u00e3oServi\u00e7oDesktop - Suporte avan\u00e7ado, 2o. n\u00edve"}],"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:-folderIDfolderID: 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:-folderIDfolderID: 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:-authauth: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.

-32700E_PARSE_ERRORParse error
-32600E_INVALID_REQUESTInvalid Request
-32601E_METHOD_NOT_FOUNDMethod not found
-32602E_INVALID_PARAMSInvalid params
-32603E_INTERNAL_ERRORInternal error
404E_HTTP_NOT_FOUNDA resource matching URI '%1' was not found
500E_UNKNOWN_ERRORHTTP Unknown error

# Errors inherited from Expresso Application.

1LOGIN_SUCCESS_LOGOUTYou have been successfully logged out
2LOGIN_SESSION_EXPIREDSorry, your login has expired
3LOGIN_NOT_LOGGED_INYou are not logged in
4LOGIN_COOKIES_REQUIREDCookies are required to login to this site.
5LOGIN_BADLOGINbad login or password
6LOGIN_PASSWORD_EXPIREDYour password has expired, and you do not have access to change it
7LOGIN_AUTH_INVALIDYour auth is invalid
10LOGIN_SESSION_NOT_VERIFIEDYour session could not be verified.
98LOGIN_ACCOUNT_EXPIREDAccount is expired
99LOGIN_LOGIN_BLOCKEDBlocked, too many attempts||
200LOGIN_INVALID_LOGINBad login or password

1001CATALOG_MIN_ARGUMENT_SEARCHYour search argument must be longer than %1 characters.
1002MAIL_NOT_SENTYour mail could not be sent.
1003MAIL_TRASH_NOT_CLEANEDYour trash folder could not be cleaned.
1004MAIL_MESSAGE_NOT_FOUNDMessage not found in folder %1.
1005MAIL_INVALID_NEW_FOLDER_NAMEInvalid folder name.
1006MAIL_INVALID_OLD_FOLDERInvalid old folder.
1007MAIL_INVALID_FOLDERInvalid folder.
1008MAIL_CANNOT_DEL_DEFAULT_FOLDERCannot delete a default folder.
1009MAIL_FOLDER_NOT_EMPTYThe folder is not empty.
1010MAIL_FOLDER_NOT_RENAMEDThe folder could not be renamed.
1011MAIL_FOLDER_NOT_ADDEDThe folder could not be added.
1012MAIL_FOLDER_NOT_DELETEDThe folder could not be deleted.
1013MAIL_FOLDER_LIMIT_REACHEDFolder limit has been reached.
1014CALENDAR_INVALID_START_DATEInvalid start date.
1015CALENDAR_INVALID_END_DATEInvalid end date.
1016MAIL_INVALID_MESSAGEMessage does not exists.
1017MAIL_TRASH_FOLDER_NOT_EXISTSTrash folder does not exists.
1018MAIL_NOT_SENT_LIMIT_EXCEEDEDThe size of this message has exceeded the limit (%1B).