Integração com PayPal Frete Fácil

Nos tutoriais anteriores, falamos muito sobre as APIs REST da PayPal, como Express Checkout, Adaptive Payments, etc. Ao contrário dessas APIs, o Frete Fácil utiliza uma API SOAP, que é um protocolo para tráfego de objetos simples, utilizando XML na requisição e na resposta. O processo de integração funciona através de requisições, onde objetos simples são encapsulados em um XML, enviados para o servidor SOAP, processados, e retornam como objetos de resposta, encapsulados em um XML.

Quando trabalhamos com orientação a objetos, uma interface define o tipo de um objeto. Em SOAP, a interface é um XML Schema dentro de um WSDL (Web Service Description Language), que define as propriedades dos objetos que trafegarão, as operações da API, etc. O WSDL do PayPal Frete Fácil pode ser baixado em: PayPal Frate Fácil WSDL.

Algumas linguagens, como C# e várias outras, possuem ferramentas para leitura do WSDL e conversão para as respectivas classes, facilitando a integração. Em outras linguagens, principalmente aquelas com tipagem dinâmica, não é necessário criar classes para os objetos que trafegarão. Independentemente da linguagem que será utilizada, o objeto que trafegará será sempre o mesmo, e terá sempre o mesmo tipo:

O tipo tns:getPreco, que será enviado na requisição, possui as seguintes propriedades e os valores esperados:

 

• cepOrigem – O cepOrigem deve ser informado com o CEP do vendedor, de onde o produto será despachado.
• cepDestino – O cepDestino é o CEP do cliente, que informará no momento do checkout.
• largura – A largura da embalagem deve ser informada em centímetros, e possui algumas regras, são elas:
  • 1. A largura não pode ser maior do que 90 centímetros.
  • 2. A largura não pode ser menor do que o 5 centímetros.
  • 3. A largura não pode ser menor do que o 11 centímetros quando o comprimento for menor do que 25 centímetros.
• altura – Assim como a largura da embalagem, a altura também deve ser informada em centímetros, e possui algumas regras, são elas:
  • 1. A altura da embalagem não pode ser maior do que 90 centímetros.
  • 2. A altura da embalagem não pode ser menor do que 2 centímetros.
  • 3. A altura da embalagem não pode ser maior do que o comprimento.
• comprimento – O comprimento também deve ser informado em centímetros, e possui as seguintes regras:
  • 1. O comprimento da embalagem não pode ser maior do que 90 centímetros.
  • 2. O comprimento da embalagem não pode ser menor do que 16 centímetros.
• peso – O peso deve ser informado em Kilogramas. Caso a embalagem tenha menos do que 1 Kilograma, 300 gramas por exemplo, o valor informado deverá ser 0.3.

Requisição e Resposta

Uma requisição SOAP, contendo as propriedades acima, se parecerá como o XML abaixo:

<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"                    xmlns:ns1="https://ff.paypal-brasil.com.br/FretesPayPalWS">     <SOAP-ENV:Body>         <ns1:getPreco>             <cepOrigem>04094-050</cepOrigem>             <cepDestino>01311-100</cepDestino>             <largura>15</largura>             <altura>2</altura>             <profundidade>30</profundidade>             <peso>1</peso>         </ns1:getPreco>     </SOAP-ENV:Body> </SOAP-ENV:Envelope>

A resposta esperada para essa requisição será:

<?xml version='1.0' encoding='UTF-8'?> <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">     <S:Body>         <ns2:getPrecoResponse xmlns:ns2="https://ff.paypal-brasil.com.br/FretesPayPalWS">             <return>9.239999999999998</return>         </ns2:getPrecoResponse>     </S:Body> </S:Envelope>

Abaixo, um código em PHP, utilizando a classe nativa SoapClient, para demonstrar a integração:

<?php //URL da API $endpoint = 'https://ff.paypal-brasil.com.br/FretesPayPalWS/WSFretesPayPal'; //Criação do client SOAP para a integração $client = new SoapClient($endpoint . '?wsdl', array(     'trace'         => true,     'exceptions'    => true,     'style'         => SOAP_DOCUMENT,     'use'           => SOAP_LITERAL,     'soap_version'  => SOAP_1_1,     'location'      => $endpoint,     'encoding'      => 'UTF-8' )); //Criação do objeto que será enviado para o web service via SOAP $request = new stdClass(); $request->cepOrigem = '04094-050'; $request->cepDestino = '01311-100'; $request->altura = 2; $request->largura = 15; $request->profundidade = 30; $request->peso = 1; //Fazendo a requisição e obtendo o valor do frete $valorFrete = $client->getPreco($request)->{'return'};

Assim como diversas tecnologias, o PHP abstrai o trabalho da criação do XML da requisição e manipulação do XML de resposta. Por se tratar de uma API de tráfego de objetos simples, a API PayPal Frete Fácil é, provavelmente, a mais simples para se integrar.