wiki:WebServiceDraft

Version 47 (modified by pereira.jair, 12 years ago) (diff)

--

Expresso Web Service

Este Draft é destinado à especificação dos requisitos referentes à implementação do Web Service do Expresso. 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


2. Compatibilidade

API: Versões > 2.2

ExpressoMail?: Versões > 2.2

ContactCenter?: Versões > 2.2


3. Arquitetura


4. Protocolo de Comunicação

JSON-RPC versão 1.0


5. Recursos disponíveis



Método:Expresso.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-auth: Chave de autenticacao do expresso (KP3+SESSIONID do usuario).
Retorno de Exemplo (JSON):{"result":{"auth":"f8c778cb6e1f45b123fa2458aebf7900:c0bf68e65e59d2dc16999299fb3c0e04"},"error":null,"id":"2"}



Método:Expresso.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.getUserFoldersListar 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.getUserMessagesListar 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:Catalog.getUserContactsRetorna 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.getImagePictureRetorna 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:Mail.addUserFolderAdiciona 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"}




6. Recursos a serem implementados



Método:Mail.delUserFolderRemove uma pasta de um usuario.
Parâmetros:-auth
-folderID
auth:Autenticacao do usuario.
folderID:FolderID da pasta que sera removida.



Método:Mail.moveMessageMove 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.delMessageApaga uma Mensagem do Servidor.
Parâmetros:-auth
-msgID
auth:Autenticacao do usuario.
msgID:ID da mensagem que sera apagada.



Método:Mail.cleanTrashLimpa a lixeira.
Parâmetros:-authauth:Autenticacao do usuario.



Método:Mail.sendMessageEnvia 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.saveMessageAsDraftSalva 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.