Documentação da API.NET do idrake Service

Transcrição

1 Documentação da API.NET do idrake Service Pré-requisitos Framework.NET 4 Preparação Via FTP Obter as seguintes DLLs e referenciar em seu projeto: idrake.client.dll (versão X) Constant.Utils.dll Constant.Web.Utils.dll AutoMapper.dll (versão ) Castle.Core (versão 3.3.0) Newtonsoft.Json.dll (versão 6.0.3) Caminho para download: ftp://api.drake.bz/idrake Configuração Adicione as seguintes entradas no Web.config ou App.config: <appsettings> <add key="senderid" value="<<código da entidade>>" /> <add key="privatekey" value="<<chave privada>>" /> <add key="drakeintegrationserviceurl" value=" /> </appsettings>

2 Changelog Versão Suporte a mensagem de envio de aprovação de fatura Suporte a mensagem de recusa de fatura Suporte a mensagem de aprovação de fatura Suporte a reuso de atendimentos não concluídos Suporte a aviso de leitura de mensagens Alteração na mensagem de confirmação de atendimento Inclusão da propriedade Provider Substituição da propriedade Price por Value, Fees e Comission Inclusão da propriedade RebatesByReuse Inclusão da propriedade ReservationNumberReused Inclusão da propriedade TreatmentId Alteração na mensagem de solicitação de mudança de serviço Inclusão da propriedade ServiceOrder Inclusão da propriedade TreatmentIdToTryReuse Alteração na classe Participant Substituição da propriedade CPF por Cpf Substituição da propriedade Passport por Passports Substituição da propriedade Tels por PhoneNumbers Substituição da propriedade CostCenter por CostCenterCode e CostCenterName Substituição da propriedade por s Alteração na classe LogisticNeed Inclusão da propriedade CostCenterCode Inclusão da propriedade CostCenterName Alteração na mensagem de leitura de mensagens Possibilidade para ler mensagens específicas, bastando informar o código das mensagens. Versão Alteração do namespace de todas as classes. Suporte a mensagem para obtenção de informações sobre relatório de custos atuais

3 Usando a API Como obter as mensagens não confirmadas Toda mensagem enviada para um destinatário fica na caixa de saída do mesmo até ser confirmada sua leitura. Para ler as mensagens que estão nesta caixa de saída, basta utilizar o código a seguir: var operacao = new ReadOperation(); var mensagens = operacao.readmessages(); Esta operação irá retornar uma lista de mensagens que podem ser de vários tipos. A seguir os possíveis tipos de mensagens retornadas: ServiceRequestMessage Mensagem enviada pelo cliente quando o mesmo deseja um serviço. Possui as seguintes informações: Código da mensagem Código DRAKE Código do remetente Código do destinatário Necessidade de logística referente ao serviço solicitado ChangeRequestMessage Mensagem enviada pelo cliente quando o mesmo deseja alterar as informações de um serviço solicitado anteriormente. Possui as seguintes informações: Código da mensagem Código DRAKE Código usado pelo fornecedor Código do remetente Código do destinatário Novas informações sobre a necessidade de logística do serviço solicitado CancelationRequestMessage Mensagem enviada pelo cliente quando o mesmo deseja solicitar o cancelamento de uma solicitação de serviço. Possui as seguintes informações: Código da mensagem (Id) Código usado pelo fornecedor (ExternalId) Código do remetente (SenderId)

4 RefuseInvoiceMessage Mensagem enviada pelo cliente quando o mesmo deseja recusar uma fatura enviada pelo fornecedor. Possui as seguintes informações: Código da mensagem (Id) Código DRAKE da fatura (DrakeId) Código usado pelo fornecedor que representa o código da fatura (ExternalId) Código do remetente (SenderId) Itens da fatura (Items) Código DRAKE da necessidade referenciada no item da fatura (DrakeId) Total cobrado (Total) Descontos (Rabate) Parecer do cliente sobre o item da fatura cobrado (Appraisal) Estado do item da fatura (Status) Aprovação solicitada (ApprovalRequested) Aprovado (Approved) Recusado (Refused) Valores adicionais (ExtraValues) Valor (Value) Comentários sobre o valor adicional (Comments) Trabalhador (Participant) Código DRAKE do trabalhador (DrakeId) Nome do trabalhador (Name) ApproveInvoiceMessage Mensagem enviada pelo cliente quando o mesmo deseja aprovar uma fatura enviada pelo fornecedor. Possui as seguintes informações: Código da mensagem (Id) Código DRAKE da fatura (DrakeId) Código usado pelo fornecedor que representa o código da fatura (ExternalId) Código do remetente (SenderId)

5 Como confirmar as mensagens lidas Após serem lidas, é preciso tratá-las e informar ao serviço de integração que elas podem ser removidas da caixa de saída. Para removê-las da caixa de saída basta chamar o método ConfirmReadedMessages() na mesma instância de ReadOperation onde as mensagens foram lidas: var operacao = new ReadOperation(); var mensagens = operacao.readmessages(); // ( Faz alguma coisa com as mensagens lidas ) operacao.confirmreadedmessages();

6 Como confirmar a solicitação de atendimento a um serviço Para confirmar a solicitação de atendimento para um cliente, é preciso informar os seguintes dados: Número da reserva (ReservationNumber) Início do serviço (Start) Término do serviço (End) Endereço de origem (Origin) Endereço de destino (Destination) Ordem em que o serviço será atendido (ServiceOrder) A seguir um exemplo de código para realizar esta operação: var ordem = new List<ServiceOrder>(); ordem.add(new ServiceOrder() Participant = new Participant() Name = "João", Identity = " " }, DeliveryOrder = 1, PickupOrder = 2 ordem.add(new ServiceOrder() Participant = new Participant() Name = "Maria", Identity = "XX1234" }, DeliveryOrder = 2, PickupOrder = 1 operacao.confirmservice(new ConfirmServiceMessage()

7 Start = new DateTime(2000, 1, 1), End = new DateTime(2010, 1, 1), Value = 120, Fees = 10, Comission = 20, Acknowledgment = true, ReservationNumber = "RN10000", DrakeId = , ExternalId = "EXT200000", Origin = new Address() Street = "Rua das Bromélias", Complement = "Número 2000", District = "Centro", City = "Macaé", State = "RJ", Country = "Brasil" }, ServiceOrder = ordem

8 Como recusar uma solicitação de atendimento Para recusar uma solicitação de atendimento de um cliente, é preciso informar os seguintes dados: Motivo da recusa (Details) A seguir um exemplo de código para realizar esta operação: operacao.refuserequest(new RefuseRequestMessage() Details = "Não tenho condições de atendê-lo.", DrakeId =

9 Como cancelar um serviço Para cancelar um serviço, é preciso informar os seguintes dados: Motivo da recusa (Details) A seguir um exemplo de código para realizar esta operação: operacao.refuserequest(new RefuseRequestMessage() Details = "Carro quebrou.", DrakeId = Como recusar uma solicitação de cancelamento Para recusar uma solicitação de cancelamento de um serviço, é preciso informar os seguintes dados: A seguir um exemplo de código para realizar esta operação: operacao.refuserequest(new RefuseCancelationMessage() DrakeId =

10 Como confirmar um cancelamento solicitado pelo cliente Existem duas formas para confirmar um cancelamento solicitado pelo cliente: sem reembolso e com reembolso. Para cancelar sem reembolso é preciso informar os seguintes dados: A seguir um exemplo de código para realizar esta operação: operacao.cancelconfirmation(new CancelationConfirmationMessage() DrakeId = Para cancelar com reembolso é preciso informar os seguintes dados: Valor do reembolso (RefundValue) A seguir um exemplo de código para realizar esta operação: operacao.cancelconfirmationwithrefund(new CancelationConfirmationWithRefundMessage() DrakeId = , RefundValue = 50 Como notificar o uso de um serviço Para notificar o uso de um serviço, é preciso informar os seguintes dados:

11 A seguir um exemplo de código para realizar esta operação: operacao.notifyuse(new NotifyUseMessage() DrakeId = Como notificar o não uso do serviço Para notificar a não utilização de um serviço, é preciso informar os seguintes dados: A seguir um exemplo de código para realizar esta operação: operacao.notifynoshow(new NotifyNoShowMessage() DrakeId =

12 Como solicitar a aprovação de uma fatura Após um ciclo de atendimento, é preciso solicitar enviar para o cliente a fatura que será cobrada. Esta tarefa pode ser feita através do idrake. A seguir um exemplo de código que envia uma fatura com dois itens, onde um deles possui um valor adicional referente ao consumo de frigobar de um funcionário: var codigofaturanofornecedor = FAT ; var mensagem = new InvoiceApprovalRequestMessage() ExternalId = codigofaturanofornecedor }; var itemfatura01 = new InvoiceItem DrakeId = 1000, Comments =, Total = 200, Rebate = 10 }; var itemfatura02 = new InvoiceItem DrakeId = 1001, Comments =, Total = 250, Rebate = 5 }; var itemfatura02.extravalues.add(new InvoiceItemExtraValue Comments = Funcionário consumiu frigobar, Value = 120, Participant = new Participant DrakeId = 100, Name = JOÃO DA SILVA } mensagem.additem(itemfatura01); mensagem.additem(itemfatura02); operacao.invoiceapprovalrequest(mensagem);

13 Como realizar várias operações de uma única vez A classe ProviderOperation implementa o padrão Unit of Work, dessa forma é possível adicionar várias suboperações antes de chamar a função Execute. A seguir um exemplo de código: operacao.refuserequest(new RefuseRequestMessage() Details = "Não tenho condições...", DrakeId = operacao.cancelservice(new CancelServiceMessage() DrakeId = , Details = "Carro quebrou." operacao.notifyuse(new NotifyUseMessage() DrakeId = operacao.notifynoshow(new NotifyNoShowMessage() DrakeId = 7000

14 Como definir um código de destinatário padrão em uma operação Para o código não ficar repetitivo, é possível definir o código do destinatário ao instanciar a operação. A seguir um exemplo de código: var operacao = new ProviderOperation(2); // Valor padrão do código do destinatário. operacao.refuserequest(new RefuseRequestMessage() // Como não foi informado um RecipientId aqui, será usado o valor 2. Details = "Não tenho condições...", DrakeId = operacao.cancelservice(new CancelServiceMessage() // Como não foi informado um RecipientId aqui, será usado o valor 2. DrakeId = , Details = "Carro quebrou." operacao.notifynoshow(new NotifyNoShowMessage() RecipientId = 3, // Como foi informado um RecipientId aqui, ele irá ignorar o padrão DrakeId = 7000

15 Como definir várias mensagens do mesmo tipo de uma só vez Caso tenha mais de uma mensagem do mesmo tipo para ser enviada em uma mesma operação, basta usar um dos métodos que recebem uma lista de mensagens. A seguir alguns exemplos de código: var operacao = new ProviderOperation(2); var mensagens_de_recusa = List<RefuseRequestMessage>(); mensagens_de_recusa.add(...); mensagens_de_recusa.add(...); mensagens_de_recusa.add(...); operacao.refuserequests(mensagens_de_recusa); Todas as operações descritas nesse documento possuem um método que recebe uma lista de mensagens. Como obter os dados para geração do relatório de custos atuais A API possui uma operação de consulta que permite obter informações para geração do relatório de custos atuais. Esta operação retorna todas as entradas de faturamento relacionados à conta do cliente que está se conectando ao serviço do idrake. A seguir um exemplo de código que mostra como obter essas informações: var operacao = new ReportOperation(2); // obtém o relatório com as entradas da fatura do momento. var relatorio = operacao.getbillentriesreport(datetime.now); // Início do período da fatura var inicio = relatorio.start; var termino = relatorio.end; // Valor da fatura sem desconto. var custo_total = relatorio.totalcost;

16 // Valor da fatura com desconto. var custo_total_com_desconto = relatorio.totalcostwithdiscount; // Descontos obtidos na fatura. var desconto = relatorio.discount; // Momentos do relatório. Representa cada dia do período do relatório. var momentos = relatorio.moments; // Períodos disponíveis para serem consultados. var períodos = relatorio.periods; Os gráficos abaixo são exemplos do que pode ser feito com as informações retornadas por este método:

17 Como receber uma mensagem de confirmação de leitura Em alguns casos é necessário saber quando uma mensagem enviada para um cliente foi processada. Para fazer isto, basta alterar o valor da propriedade Acknowledgment da mensagem enviada para true. Conforme exemplo abaixo: var minhamensagem = new ConfirmServiceMessage Acknowledgment = true, }; Ao enviar esta mensagem com sucesso, a propriedade Id será carregada com um valor único para controle (minhamensagem.id). Quando esta mensagem for processada pelo cliente, uma mensagem do tipo MessageType.Acknowledgment será colocada na sua caixa de leitura. Esta mensagem possui duas propriedades importantes: o ReceivedMessageId Código da mensagem que foi processada o Sent Data em que mensagem foi processada.