Manual de Integração do icarta

Transcrição

1 Manual de Integração do icarta Versão 1.00 Abril 2014

2 Controle de Versões Versão Data /04/2014

3 1. Introdução Este documento tem por objetivo a definição das especificações e critérios técnicos necessários para a integração entre o servidor do icarta e os sistemas das empresas que contrataram o serviço. # Legendas: - Coluna Elem. (Elemento): - G: Grupo; - E: Elemento; - A: Atributo; - Coluna Tipo : - C: Carácter; - N: Número; 2. Integração por Web Service SOAP As aplicações que utilizarem este método de envio de deverão implementar a comunicação via SOAP. A seguir apresentamos mais informações como: URL do WSDL, leiaute do XML de envio, leiaute do XML de retorno, entre outros. No icarta Web, o cliente deve acessar a edição da Organização para gerar as credenciais de acesso ao Web Service. Todo deve conter uma referência única, gerado pelo cliente, inserida no atributo do message-id para identificação no retorno da conexão e futuras consultas e notificações URL do WSLD Toda a configuração da comunicação SOAP é encontrada na URL do WSDL abaixo: Leiaute do XML de Envio O XML deve ser montado de acordo com a estrutura definida abaixo e o modelo a seguir.

4 # Estrutura do XML de envio: # Campo Nível Descrição Elem. Tipo Ocorr. Observações 1 sendtrackedemai 0 Raiz do XML de envio G 1-1 l 2 versao 1 Versão do leiaute A C 1-1 Ex: credentials 1 Tag das credenciais G appid 2 ID da aplicação E C 1-1 Gerado através do icarta 5 appsecret 2 Chave da ID da E C 1-1 Gerado através do icarta aplicação 6 tracked s 1 Tag dos s G 1-n 7 tracked 2 Tag de G 1-1 Dados do 8 message-id 3 ID únido do A C 1-1 Gerado pelo cliente 9 subject 3 Assunto do E C sender 3 Dados do remetente G name 4 Nome do remetente E C do remetente E C 1-1 Deve estar cadastrado e ativo no icarta 13 recipients 3 Tag dos destinatários G 1-n 14 recipient 4 Tag de destinatário G type 5 Tipo do destinatário A C 1-1 Preencher com: TO, CC ou BCC 16 name 5 Nome do destinatário E C do destinatário E C content 3 Corpo do E C 1-1 Pode ser no formato texto ou HTML 19 trackedresponse 3 Resposta rastreado E C 1-1 Se deseja que a resposta do destinatário também seja rastreada. Preencher com: NO ou YES 20 attachments 3 Tag de anexos G 0-n 21 attachment 4 Tag de anexo G filename 5 Nome do arquivo E C 1-1 Nome do arquito com a extensão. Ex: teste.txt 23 contenttype 5 Tipo do arquivo E C 1-1 Preencher no formato correto. Ex: text/plain, application/pdf, image/jpeg, etc. 24 content 5 Conteúdo do arquivo E C 1-1 Conteúdo deve estar codificado em Base64

5 # Modelo do XML de envio: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <sendtracked versao="1.00"> <credentials> <appid>9fdb9d925604fa073bdc687cb761b69b</appid> <appsecret>f99efba6-3b04-454b-802c-ba3f081ec3c3</appsecret> </credentials> <tracked s> <tracked message-id="14589e8e-c9f df0cfb33a5"> <subject>icarta WebService</subject> <sender> <name>desenvolvimento</name> </sender> <recipients> <recipient type="to"> <name>suporte</name> </recipient> </recipients> <content>apresentando o WebService do icarta</content> <trackedresponse>no</trackedresponse> <attachments> <attachment> <filename>teste.txt</filename> <contenttype>text/plain</contenttype> <content>dgvzdgu=</content> </attachment> </attachments> </tracked > </tracked s> </sendtracked >

6 2.3. Validação e Leiaute do XML de Retorno Após enviar para processamento no Web Service, o XML de envio passará por validação do esquema, se não houver falha na validação retornaremos um XML de retorno com as informações de status geral e status de cada , caso contrário uma mensagem SOAPFault será repassada. # Estrutura do XML de envio: # Campo Nível Descrição Elem. Tipo Ocorr. Observações 1 sendtracked response 0 Raiz do XML de retorno G versao 1 Versão do leiaute A C 1-1 Ex: status 1 Status geral do processamento E N 1-1 Preenchido com: 00 Sucesso; 01 Credenciais inválidas 02 Algum inválido; 99 Erro; 4 description 1 Descrição do status E C tracked s 1 Tag dos s G 1-n 6 tracked response 2 Tad do de retorno G messageid 3 ID únido do E C 1-1 Retorno do ID repassado pelo cliente 8 status 3 Status do E N 1-1 Preenchido com: 00 Sucesso; 01 ID do já utilizado; 99 Erro; 9 description 3 Descrição do status do E C 1-1 # Modelo do XML de envio: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <sendtracked response versao="1.00"> <status>00</status> <description> s recebidos com sucesso.</description> <tracked s> <tracked response> <messageid>cc6a859a-7c8c-4e07-9e11-2db5f4dbae4e</messageid> <status >00</status > <description> enviado para processamento.</description>

7 </tracked response> </tracked s> </sendtracked response> 3. Notificações de Evidências por WebHook A notificação pelo conceito de WebHook consiste em o cliente cadastrar uma URL de seu critério para recebimento de requisições POST com, neste caso, conteúdo das evidências. Todas as notificação serão realizadas apenas quando o registrado for de origem Web Service. O icarta disponibiliza a notificação em dois formatos: XML e JSON. Se alguma notificação for perdida pelo cliente, a mesma poderá ser reenviada através do site do icarta Cabeçalho do 'POST' Request URL: url cadastrada Request method: POST Content-Type: application/xml Content-Length: 335 User-Agent: icarta Notification Event X-iCarta-Message-ID: 955f1b cf-a7c4-9b9b63113e00 X-iCarta-Event-ID: 292ae3dd-04a2-42ae-9bac-cb1faf58e7a5 X-iCarta-Event-Type: evidencia X-iCarta-Message-ID é o id passado pelo cliente durante a comunicação via Web Service. X-iCarta-Event-ID é o id de cada evidência gerado pelo icarta. X-iCarta-Event-Type tipo da notificação, neste caso será sempre evidencia Leiaute do 'POST' Abaixo segue a estrutura da notificação e os modelos em XML e JSON.

8 # Estrutura da Notificação da Evidência: # Campo Nível Descrição Elemento Tipo Ocorrência Observações 1 evidencia 0 Raiz da evidência G escopo 1 Tipo da evidência E S 1-1 Preenchido com: PROCESSA_MENSAGEM; HASH_MENSAGEM; CONFIRMACAO_LEITURA; CARIMBO_HLB; PROCESSO_FINAZADO; FALHA_ENVIO; DKIM_SIGNATURE; HASH_DESTINATARIO; RESPOSTA_SMTP; RESPOSTA_RASTREADA; RASTREADO_RESPONDIDO; ORIGEM_ ; 3 status 1 Status da evidência E S 1-1 Preenchido com: ERROR, SUCCESS 4 dataevidencia 1 Data da evidência E S 1-1 Formato da data: AAAA-MM-ddTHH:mm:ss.S 5 mensagem 1 Descrição da evidência E S destinatario 1 Destinatário da evidência E S 1-1 # Modelo da Notificação da Evidência no formato XML: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <evidencia> <escopo>hash_destinatario</escopo> <status>success</status> <dataevidencia> t01:02:30.853</dataevidencia> <mensagem>hash da mensagem icarta do destinatário: 1ce9a27a3600e7132c17e41cbae00f8c</mensagem> <destinatario>suporte@ .com</destinatario> </evidencia>

9 # Modelo da Notificação da Evidência no formato JSON: { } "evidencia": { "escopo":"hash_destinatario", "status":"success", "dataevidencia":" t01:02:30.853", "mensagem":"hash da mensagem icarta do destinatário: 1ce9a27a3600e7132c17e41cbae00f8c", "destinatario":"suporte@ .com" }