Hoje, a maior parte dos webservices utilizam a arquitetura REST para comunicação entre ambientes e troca de dados, principalmente em e-commerces, onde muitos serviços são consumidos, como consulta de CEP, integração com meio de pagamento, geração de etiqueta para correios, integração com ferramenta anti-fraude, geração de boleto e muitos outros.

Meu objetivo neste artigo é mostrar minha rotina quando vou realizar qualquer integração com REST, neste exemplo vamos utilizar a API de abertura de pedido da Stelo.

O primeiro passo é ver que formato de dados a API permite, no meu caso dou sempre preferência a utilizar o JSON, quando possível.

Outro ponto que devemos entender bem é o fluxo do processo, que normalmente é descrito no manual. O que acontece no caso dos meios de pagamento é:

• Cliente seleciona produtos que deseja comprar na loja
• Preenche os dados de cadastro e entrega
• Seleciona o meio de pagamento e clica em pagar
• A loja realiza uma requisição ao meio de pagamento passando informações da compra para processar o pedido e informações do cliente para análise anti-fraude.
• A API retorna o link para o comprador acessar o ambiente do meio de pagamento e finalizar a compra.

Normalmente, as APIs fornecem alguns exemplos de integração. Neste caso, solicitar um exemplo da estrutura JSON da chamada pode ajudar muito, afinal é bem mais simples ver como a requisição deve ser feita na prática do que aquelas tabelas de parâmetros com seus significados e tipos em um enorme PDF. No caso da Stelo, temos o JSON de exemplo fornecido pela empresa com o manual de integração.

Post Request

Content-type: application/json 
Authentication Base64(ClientId:ClientSecret)
{  
   "orderData":{  
      "orderId":"100000309",
      "plataformId":"1",
      "transactionType":"w",
      "country":"BR"
   },
   "paymentData":{  
      "amount":139.99,
      "discountAmount":"",
      "freight":"5.0",
      "currency":"BRL",
      "maxInstallment":"3",
      "cartData":[  
         {  
            "productName":"Produto Teste",
            "productPrice":"134.9900",
            "productQuantity":1,
            "productSku":"asc"
         }
      ]
   },
   "customerData":{  
      "customerIdentity":"39488996811",
      "customerName":"teste testador",
      "customerEmail":"teste@teste.com.br",
      "birthDate":"1991-01-14",
      "billingAddress":{  
         "street":"endereco teste ",
         "number":"123",
         "complement":"ap12",
         "neighborhood":"centro",
         "zipCode":"07114000",
         "city":"Guarulhos",
         "state":"SP",
         "country":"BR"
      },
      "shippingAddress":{  
         "street":"endereco teste ",
         "number":"123",
         "complement":"ap12",
         "neighborhood":"centro",
         "zipCode":"07114000",
         "city":"Guarulhos",
         "state":"SP",
         "country":"BR"
      },
      "phoneData":[  
         {  
            "type":"landline",
            "number":"1124242424"
         },
         {  
            "type":"cell",
            "number":"11978787878"
         }
      ]
   }
}

Podemos ver que a API tem três parâmetros que encabeçam os outros: OrderData, PaymentData e CustomerData. Vendo o exemplo em JSON, conseguimos identificar quase todos os significados e formatos esperados nos parâmetros. Agora, o que faço é identificar quais parâmetros restam dúvidas e consultar no manual ou entrar em contato com a equipe do produto.

O que fizemos até agora?

• Escolhemos qual formato de dados iríamos utilizar (JSON)
• Entendemos o fluxo do serviço a ser integrado
• Solicitamos exemplos aos fornecedores da API
• Identificamos a maioria dos dados pelo exemplo e os que restaram consultamos no manual de integração da API.

Somente após a identificação de todos os dados necessários é que iniciamos o desenvolvimento. Sabemos que precisaremos de métodos para:

• obter todos os dados do comprador
• obter os dados de pagamento (frete, produtos do carrinho e desconto)
• estruturar a chamada REST ao serviço (neste caso usará o método POST e no header terão os dados de identificação do lojista)
• executar os métodos anteriores coletando os dados e requisitando a chamada ao serviço após o comprador acionar o evento (clicando no botão “Finalizar compra” por exemplo) e tratar o retorno da chamada (neste caso abrindo o link para a página de pagamento)

Em seguida, durante o desenvolvimento dos métodos que obterão os dados devemos nos preocupar com os campos que podem causar problemas de formatação, neste caso são:

• Estado e País -> Devem ser enviadas as siglas dos mesmos.
• CEP e CPF -> Devem ser enviados com apenas números (sem hífen ou ponto)
• Valores de moeda -> Todos os valores de moeda devem ser enviados com ponto para separar centavos e tratar também para retirar qualquer outro separador (de:1.500,50 para 1500.50).

Outros campos podem causar problemas de formatação, mas estes são muito comuns em qualquer API que os receba. Para tratar de maneira organizada, sempre crio uma classe “Helper” com pequenas funções como formatar moeda, gerar sigla e limpar caracteres.

Neste ponto, praticamente finalizamos a integração com a API, basta criar um método para fazer uma chamada ao REST que estará esperando o Header o Body e o Method da requisição, e criar o método principal que será executado quando o botão “finalizar compra” for clicado. Este método final deve tratar o retorno da API, normalmente para facilitar a chamada ao serviço e a tratativa do retorno utilizo o plugin do chrome – Rest Console – e com ele e o exemplo JSON, consigo simular as chamadas e programar o tratamento do retorno e então finalizamos nossa integração.

Você tem dicas, plug-ins ou ferramentas que facilitam a utilização de APIs em REST? Deixe nos comentários.