Integração
O webservice do CobreDireto foi construído usando o padrão SOAP, bastante popular. Não importa em que linguagem seja construída sua loja, é muito provável que haja pacotes ou bibliotecas SOAP prontas para ela, que vão facilitar a integração.
Há apenas um método disponível no webservice: doService. Os parâmetros que esse método recebe são:
- Version: a versão do webservice que sua loja utiliza. Use “1.1.0”
- Action: “payOrder” se você estiver criando um pedido e “probe” se estiver consultando o status de um pedido.
- Merchant: o código de sua loja no CobreDireto
- User: o login de sua loja no CobreDireto
- Password: a senha de sua loja no CobreDireto
- Data: um XML com os dados necessários para a ação solicitada.
O método doService sempre retornará uma variável doServiceReturn com uma string XML. Veja as seções “Criando o pedido” e “Recebendo o retorno” para mais detalhes sobre o XML enviado no parâmetro “Data” e recebido no retorno do método.
Criando o pedido
Para a criação do pedido, na chamada do SOAP o action deve ser “payOrder”, o XML a ser enviado no parametro Data deve seguir uma estrutura pré-definida.
- ‘order_data’, onde estarão todos os dados do pedido;
- ‘behavior_data’ com as configurações das URL’s de recibo, erro e retorno;
- ‘payment_data’ com as configurações de pagamento;
- ‘customer_data’ com as informações do consumidor, entrega e cobrança.
Você deve ter um nó mestre nomeado ‘payOrder’, dentro deste é necessário ter a sequência abaixo de tags:
Ficando a estrutura inicial desse modo:
<payOrder> <order_data> Informações do Pedido </order_data> <behavior_data> Configuração de URLs para retorno </behavior_data> <payment_data> Informações sobre o Pagamento </payment_data> <customer_data> Informações do Comprador </customer_data> </payOrder>
Essas tags devem respeitar a ordem mostrada.
1 – Criando a ‘order_data’
A tag ‘order_data’ contém as informações do pedido.
Campo | Descrição | Tipo | Tamanho | Comentário |
---|---|---|---|---|
1 . Objeto ‘order_data’ | ||||
merch_ref | Número do pedido | String Alfanumérico | 20 | |
tax_freight | Valor do frete | Long Numérico | 18 | Somente valores positivos são aceitos. Valor sem formatação. Os dois últimos digitos são centavos: Ex. 1234 = 12,34 |
order_subtotal | Subtotal do pedido | Long Numérico | 18 | Somente valores positivos são aceitos. Valor sem formatação. Os dois últimos digitos são centavos: Ex. 1234 = 12,34 |
order_total | Valor total = taxas + discount_plus + subtotal + interests_value | Long Numérico | 18 | Somente valores positivos são aceitos. Valor sem formatação. Os dois últimos digitos são centavos: Ex. 1234 = 12,34 |
order_items | Itens do pedido | Objetos order_item | O primeiro item representa o primeiro item comprado neste pedido, o segundo item representa o segundo item comprador neste pedido e assim por diante. |
Campo | Descrição | Tipo | Tamanho | Comentário |
---|---|---|---|---|
Objeto order_item | ||||
code | Código do item na loja | String Alfanumérico | 18 | |
description | Descrição do item | String Alfanumérico | 300 | Não utilizar caracteres especiais: Ex. & |
units | Quantidade de unidades | Integer Numérico | 9 | |
units_value | Valor unitário do item | Integer Numérico | 18 | Somente valores positivos são aceitos. Valor sem formatação. Os dois últimos digitos são centavos: Ex. 1234 = 12,34 |
<order_data> <merch_ref>número do pedido</merch_ref> <tax_freight>Valor do frete</tax_freight> <order_subtotal>Subtotal do pedido</order_subtotal> <order_total>Total do pedido</order_total> <order_items> <!-- Os items do pedido, serão descritos aqui, separe cada item dentro de uma tag 'order_item' --> <order_item> <code>Código do item</code> <description>Descrição do item</description> <units>Quantidade do item</units> <unit_value>Valor unitário do item</unit_value> </order_item> </order_items> </order_data>
Todas as tags que recebem um valor devem recebê-lo como um inteiro, em centavos. Ex.: R$ 10,50 ==> 1050
2 – Criando a ‘behavior_data’
Dentro da tag ‘behavior_data’ estarão as configurações das URL’s para o CobreDireto, são elas:
<behavior_data> <url_post_bell>URL de retorno, para onde será enviada a campainha</url_post_bell> <url_redirect_success>URL em caso de sucesso, normalmente o recibo</url_redirect_success> <url_redirect_error>URL para o caso de algum erro durante a transação</url_redirect_error> </behavior_data>
Todas URLs deverão estar com disponibilidade para acesso, através da porta 443 ou 80.
Campo | Descrição | Tipo | Tamanho | Comentário |
---|---|---|---|---|
2. Objeto ‘behavior_data’ | ||||
url_post_bell | URL para envio do post de aviso de mudança de status. | String Alfanumérico | 256 | Retorno do pagamento |
url_redirect_success | URL de direcionamento em caso de termino de processamento com sucesso. | String Alfanumérico | 256 | |
url_redirect_error | URL de direcionamento em caso de termino de processamento com erro. | String Alfanumérico | 256 | Usada quando algum erro ocorre durante o processo do pagamento ou quando o pagamento não é autorizado. |
3 – Criando a ‘payment_data’
Você pode pedir ao usuário que escolha o meio e condições de pagamento em seu site. Se o fizer, deverá enviar ao CobreDireto a tag payment_data:
<payment_data> <payment> <payment_method>Meio de pagamento</payment_method> <installments>Quantidade de Parcelas</installments> </payment> </payment_data>
Se você não enviar payment_data, está dizendo ao CobreDireto que não perguntou ao usuário nada sobre forma de pagamento em seu site. Nesse caso, o CobreDireto permitirá ao usuário escolher meio e condições de pagamento.
Campo | Descrição | Tipo | Tamanho | Comentário |
---|---|---|---|---|
3. Objeto ‘payment_data’ | ||||
payment_method | Meio de pgamento | String Alfanumérico | 50 | Se não enviar o meio de pagamento escolhido, o CobreDireto apresenta a tela com os meios de pagamento configurados da sua loja. Para enviar o ‘payment_method’, consulte a Tabela de Meios de Pagamento |
installments | Número de parcelas | Integer Numérico | 9 | Se o número de parcelas não for enviado, o CobreDireto assumirá que a loja deseja que o usuário escolha o parcelamento na tela de pagamento do CobreDireto. |
4 – Criando a ‘customer_data’
Dentro do customer_data, existem mais três tags (customer_info, billing_info, shipment_info).
Campo | Descrição | Tipo | Tamanho | Comentário |
---|---|---|---|---|
4. Objeto ‘customer_data’ | ||||
customer_info | Dados do consumidor | Objeto do tipo customer_item | Tag obrigatória caso criado “customer_data”. | |
billing_info | Dados da cobrança | Objeto do tipo customer_item | Opcional, caso queira enviar os dados de cobrança seguir mesma estrutura customer_info. | |
shipment_info | Dados da entrega | Objeto do tipo customer_item | Opcional, caso queira enviar os dados de entrega seguir mesma estrutura customer_info. |
A tag customer_data é opcional. Se for criada, a tag customer_info é obrigatória.
Campo | Descrição | Tipo | Tamanho | Comentário |
---|---|---|---|---|
Objeto customer_item | ||||
fist_name | Primeiro nome do consumidor | String Alfanumérico | 30 | |
middle_name | Nome do meio do consumidor | String Alfanumérico | 60 | |
last_name | Último nome | String Alfanumérico | 30 | |
E-mail válido | String Alfanumérico | 256 | ||
document | Documento (normalmente CPF) | String Alfanumérico | 50 | |
phone_home | Telefone residencial | Obejto do tipo Phone | ||
address_zip | CEP | String Numérico | 8 |
Campo | Descrição | Tipo | Tamanho | Comentário |
---|---|---|---|---|
Objeto phone | ||||
area_code | Código de area | String Numérico | 4 | |
phone_number | Número de telefone | String Numérico | 15 |
<customer_data> <customer_info> Informações do consumidor </customer_info> <billing_info> Informações de cobrança </billing_info> <shipment_info> Informações de entrega </shipment_info> </customer_data>
Cada uma delas segue a mesma estrutura de XML. A tag phone_home é mais especifica, contendo dentro dela duas outras tags (area_code e phone_number).
Segue a estrutura:
<customer_info> <first_name>Primeiro nome</first_name> <middle_name>Nome do meio</middle_name> <last_name>Último nome</last_name> <email>Email válido</email> <document>Documento, normalmente o CPF</document> <phone_home> <area_code>Código DDD</area_code> <phone_number>O telefone sem o hifen</phone_number> </phone_home> <address_zip>CEP sem o hifen</address_zip> </customer_info>
Com toda a estrutura do payOrder montada, é só requisitar o SOAP passando o payOrder no campo data, com isso feito o webservice do CobreDireto retornará a variável doServiceReturn. Nela esta contida um XML com a seguinte estrutura:
<payOrder> <status>Status da comunicação, o status do pedido deve ser visto dentro de bpag_data.status</status> <msg></msg> <bpag_data> <status>Status do Pedido</status> <msg></msg> <url>URL para redirecionamento</url> <id>Código do pedido no CobreDireto</id> </bpag_data> </payOrder>
Após receber esse retorno, redirecione o usuário para a URL que você recebeu. Lá ele verá a tela de pagamento. A cada mudança de status do pagamento, você será avisado pelo CobreDireto através da campainha.