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
- JSON-RPC 1.0 Specification -> http://json-rpc.org/wiki/specification
- Specification for Fault Code Interoperability -> http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php
- 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@…"}],"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). |
