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: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:Body> <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//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.
De 0 a 10, o quanto você recomendaria este artigo para um amigo?