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
email 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.

Atendimento