O que são Data Providers?

Os data providers (ou provedores de dados) são uma ponte entre os templates e a base de dados da plataforma. Nos e-mails transacionais, eles podem ser utilizados para exibir dados do destinatário do e-mail, detalhes de pedidos, dados de assinatura, entre outros.

Por padrão uma série de e-mails transacionais são cadastrados na instância do projeto já relacionados com seus respectivos data providers para um funcionamento padrão. Entretanto, é possível criar novos e-mails transacionais (alinhar o disparo com a equipe de suporte) e/ou relacionar novos data providers a e-mails transacionais existentes. Para isso, acesse a listagem de emails transacionais a partir da Listagem de lojas > E-mails transacionais, escolha um e-mail transacional e nas ações do mesmo a opção de Data Providers deverá estar disponível.
Na tela de criação, escolha um alias (a ser acessado no template como uma variável) e o Data Provider e salve.

Ao relacionar um data provider a um template de e-mail transacional, o mesmo ficará disponível em uma variável e sua utilização deverá seguir a sintaxe do gerenciador de templates da plataforma, que dispõe, além de variáveis, estruturas de repetição e condicionais.

Na lista abaixo estão os data providers disponíveis hoje pela plataforma e alguns detalhes sobre seu funcionamento e alguns exemplos de utilização.

Todos os Data Providers

• Dados básicos do cliente
  • Atributos disponíveis
  • Exemplo de utilização
• Dados básicos da venda
  • Atributos disponíveis
  • Exemplo de utilização
• Dados de pagamento da venda
  • URL do boleto do pedido
  • Código de pagamento do pedido
• Dados básicos da assinatura
  • Atributos disponíveis
  • Exemplo de utilização

Data Providers

Dados básicos do cliente

Fornece dados básicos sobre o cliente destinatário do e-mail transacional.

Atributos disponíveis

• data
  Retorna um objeto com os dados do cliente:
  • id
    Número de identificação do cliente
  • date_of_birth
    Data de nascimento do cliente
  • email->address
    E-mail do cliente
  • document1
    Documento principal do cliente
  • document2
    Documento secundário do cliente
  • name1
    Nome principal (nome ou razão social) do cliente
  • name2
    Nome secundário (sobrenome ou nome fantasia) do cliente

Exemplo de utilização

Prezado $dataProvider->data->name1,

Abaixo os seus dados de cadastro:
Nome completo: {{ $dataProvider->data->name1 }} {{ $dataProvider->data->name2 }}
E-mail: {{ $dataProvider->data->email->address }}
CPF: {{ $dataProvider->data->document1 }}

Dados básicos da venda

Fornece os dados básicos da venda.

Atributos disponíveis

• data
  Retorna um objeto com os dados da venda:
  • id
    Número de identificação da venda
  • datetime
    Data e hora de criação da venda
  • discount
    Valor de desconto da venda
  • freight
    Valor do frete de entrega da venda
  • subtotal
    Soma dos itens da venda
  • total
    Valor total da venda
  • items
    Coleção com os itens da venda, onde cada item é um registro de Item com os seguintes dados disponíveis:
    
    • quantity
      Quantidade do item vendido
    • unit_price
      Preço unitário do item vendido
    • item
      Acesso ao objeto com os detalhes do item vendido:
      • prices
        Coleção de preços do item. Cada preço tem:
        
        • price
          Valor do preço do item
      • main_image
        Imagem principal do item
      • images
        Coleção com todas as imagens do item. Cada imagem tem:
        • source
          Caminho da imagem no servidor
        • main
          Flag sobre a imagem ser a principal ou não
      • tags
        Coleção com as tags do item. Cada tag tem:
        
        • name
          Nome da tag
      • identification
        Coleção com os dados de identificação do item. Cada identificação tem:
        
        • name
          Nome do item
        • sku
          Código SKU do item
        • ean
          Código EAN do item
      • urls
        Coleção de URLs do item. Cada URL tem:
        • url
          URL do item
        • redirect_to
          Caminho de redirecionamento da URL do item
  • deliveries
    Dados de entrega da venda
    • address
      Dados do endereço de entrega da venda
      • zip_code
        CEP do endereço de entrega
      • address
        Logradouro do endereço de entrega
      • number
        Número do endereço de entrega
      • complement
        Complemento do endereço de entrega
      • neighborhood
        Bairro do endereço de entrega
      • city
        Cidade do endereço de entrega
      • state
        Estado do endereço de entrega
      • country
        País do endereço de entrega
    • zipCodeRange
      Dados da modalidade de entrega da venda
      • description
        Descrição da modalidade de entrega
      • time_cost
        Prazo de entrega
      • time_cost_limit
        Limite do prazo de entrega
      • deadline
        Data prevista para entrega
      • deadline_limit
        Limite da data prevista para entrega
      • days_to_deadline
        Diferença em dias até o deadline da entrega
      • days_to_deadline_limit
        Diferença em dias até o limite do deadline da entrega
      • shipper
        Retorna o objeto do registro da transportadora, se houver
  • schedule
    Dados do agendamento da venda
    • date
      Data do agendamento da venda
    • period
      Dados sobre o período de agendamento da venda:
      • description
        Descrição do período de agendamento da venda
      • start_at
        Horário de início do período de agendamento da venda
      • end_at
        Horário de término do período de agendamento da venda
  • paymentMethod
    Dados da forma de pagamento da venda
    • name
      Nome da forma de pagamento da venda
    • type
      Tipo da forma de pagamento da venda. Pode ser "bank slip", "credit card", "payment on shipping" ou "pix".
  • extraFields
    Coleção com os campos extras relacionados à venda
  • billingAttempt
    Retorna um objeto com os dados da tentativa de cobrança:
    • number
      Número da tentativa de cobrança.
  • subscriptionRelation
    Retorna um objeto com os dados da relação entre a venda e a sua assinatura, se houver:
    • cycle_count
      Número do ciclo da venda dentro da assinatura
    • subscription
      Retorna o objeto com os detalhes da assinatura
  • last_transaction
    Retorna um objeto com os dados da transação mais recente da venda.
    • bank_slip_url
      URL do boleto bancário, se houver.
    • payment_code
      Código de pagamento, se houver.
    • last_status
      Histórico de status mais recente da transação da venda.
      • new_status
        Código descritivo do status. Pode ter os valores "paid" ou "processing" ou "authorized" ou "waiting payment" ou "canceled'" ou "refunded" ou "pending refund" ou "refused" ou "chargeback".
      • status_reason
        Descrição da causa do status retornado pelo gateway de pagamento.

Exemplo de utilização

Obrigado por comprar conosco!
Veja abaixo os detalhes do pedido #{{ $dataProvider->data->id }}

Data de realização do pedido: {{ $dataProvider->data->datetime->format('d/m/Y') }}
Forma de pagamento: {{ $dataProvider->data->paymentMethod->name }}
Itens do pedido:
@foreach($dataProvider->data->items as $orderItem)
    {{ $orderItem->item->identification->first()->name }}
    {{ $orderItem->quantity }}x R$ {{ $orderItem->unit_price }}
@endforeach

{{-- Verificação se a venda possui dados de agendamento --}}
@if(null !== $dataProvider->data->schedule)
    Sua venda foi agendada para entrega em:
    Data: {{ $dataProvider->data->schedule->date->format('d/m/Y') }}
    Período: {{ $dataProvider->data->schedule->period->description }} das {{ $dataProvider->data->schedule->period->start_at }} as {{ $dataProvider->data->schedule->period->end_at }}
@endif

Dados adicionais da venda:
<ul>
@foreach($dataProvider->data->extraFields as $slug => $extraField)
    <li>
        {{$extraField->label}}
        <ul>
            @foreach($extraField->values as $extraFieldValue)
                <li>
                // Para campos de valores simples (texto, numérico) ou valores grandes (textarea, wysiwyg)
                {{$value->value}}
 
                // Para campos com opções
                {{$value->extraFieldOption->key}}
                {{$value->extraFieldOption->label}}
                {{$value->extraFieldOption->order}}
 
                // Para campos de relação com entidade, onde 'record' retorna uma instancia da entidade relacionada
                {{$value->record->...}
 
                // Para campos de arquivos/imagens
                {{$value->source}}
                </li>
            @endforeach
       </ul>
    </li>
@endforeach
</ul>

Dados de pagamento da venda

URL do boleto do pedido

Fornece dados sobre a URL do boleto do pedido que está sendo tratado no email transacional.

Atributos disponíveis

• has
  Retorna verdadeiro ou falso sobre a existência de uma URL do boleto para este pedido.
• url
  Retorna a URL do boleto deste pedido.

Exemplo de utilização

@if($bankSlip->has)
    <a href="{{ $bankSlip->url }}">Clique aqui para acessar o boleto do seu pedido</a>
@endif

Código de pagamento do pedido

Fornece dados sobre o código de pagamento do pedido que está sendo tratado no email transacional.

Atributos disponíveis

• has
  Retorna verdadeiro ou falso sobre a existência de um código de pagamento para este pedido.
• paymentCode
  Retorna o código de pagamento como texto.
• qrCode
  Imagem do QR Code gerado a partir do código de pagamento.

Exemplo de utilização

@if($paymentCode->has)
    O código de pagamento do seu pedido é: {{ $paymentCode->paymentCode }}
    Fotografe o QR Code a seguir para efetuar o pagamento:
    <img src="{{ $paymentCode->qrCode }}">
@endif

Dados básicos da assinatura

Fornece os dados básicos da assinatura e o plano assinado.

Atributos disponíveis

• data
  Retorna um objeto com os dados da assinatura:
  • id
    Número de identificação da assinatura
  • start_at
    Data de início da assinatura
  • end_at
    Data de término da assinatura
  • discount
    Valor de desconto aplicado à assinatura
  • freight
    Valor de frete da assinatura
  • total
    Valor total da assinatura
  • deliveries
    Dados de entrega da venda
    • address
      Dados do endereço de entrega da venda
      • zip_code
        CEP do endereço de entrega
      • address
        Logradouro do endereço de entrega
      • number
        Número do endereço de entrega
      • complement
        Complemento do endereço de entrega
      • neighborhood
        Bairro do endereço de entrega
      • city
        Cidade do endereço de entrega
      • state
        Estado do endereço de entrega
      • country
        País do endereço de entrega
    • zipCodeRange
      Dados da modalidade de entrega da venda
      • description
        Descrição da modalidade de entrega
      • time_cost
        Prazo de entrega
      • time_cost_limit
        Limite do prazo de entrega
      • deadline
        Data prevista para entrega
      • deadline_limit
        Limite da data prevista para entrega
      • days_to_deadline
        Diferença em dias até o deadline da entrega
      • days_to_deadline_limit
        Diferença em dias até o limite do deadline da entrega
  • extraFields
    Coleção com os campos extras relacionados à assinatura
• plan
  Retorna um objeto com os dados do plano assinado:
  
  • description
    Descrição do plano assinado
  • amount
    Valor do plano assinado
  • cycles
    Coleção com todos os ciclos do plano assinado. Cada ciclo tem a mesma estrutura do atributo currentCycle abaixo.
  • currentCycle
    Dados do ciclo vigente do plano:
    • start_at
      Data de início do ciclo
    • end_at
      Data de término do ciclo
    • items
      Coleção com todos os itens compõem o ciclo. Cada item de ciclo tem:
      
      • quantity
        Quantidade do item a ser incluída na venda gerada pra esse ciclo
      • unit_price
        Preço unitário do item a ser incluído na venda gerada pra esse ciclo
      • item
        Acesso ao objeto com os detalhes do item a ser incluído na venda gerada pra esse ciclo:
        • prices
          Coleção de preços do item. Cada preço tem:
          • price
            Valor do preço do item
        • main_image
          Imagem principal do item
        • images
          Coleção com todas as imagens do item. Cada imagem tem:
          • source
            Caminho da imagem no servidor
          • main
            Flag sobre a imagem ser a principal ou não
        • tags
          Coleção com as tags do item. Cada tag tem:
          • name
            Nome da tag
        • identification
          Coleção com os dados de identificação do item. Cada identificação tem:
          • name
            Nome do item
          • sku
            Código SKU do item
          • ean
            Código EAN do item
        • urls
          Coleção de URLs do item. Cada URL tem:
          • url
            URL do item
          • redirect_to
            Caminho de redirecionamento da URL do item

Exemplo de utilização

Obrigado por comprar conosco!
Veja abaixo os detalhes da sua assinatura do plano {{ $dataProvider->plan->description }}

Data de realização do assinatura: {{ $dataProvider->data->start_at->format('d/m/Y') }}
Itens a serem entregues no ciclo de {{ $dataProvider->plan->currentCycle->start_at->format('d/m/Y') }} a {{ $dataProvider->plan->currentCycle->end_at->format('d/m/Y') }}:
@foreach($dataProvider->plan->currentCycle->items as $cycleItem)
    {{ $cycleItem->item->identification->first()->name }}
    {{ $cycleItem->quantity }}x R$ {{ $cycleItem->unit_price }}
@endforeach

Dados adicionais da assinatura:
<ul>
@foreach($dataProvider->data->extraFields as $slug => $extraField)
    <li>
        {{$extraField->label}}
        <ul>
            @foreach($extraField->values as $extraFieldValue)
                <li>
                // Para campos de valores simples (texto, numérico) ou valores grandes (textarea, wysiwyg)
                {{$value->value}}
 
                // Para campos com opções
                {{$value->extraFieldOption->key}}
                {{$value->extraFieldOption->label}}
                {{$value->extraFieldOption->order}}
 
                // Para campos de relação com entidade, onde 'record' retorna uma instancia da entidade relacionada
                {{$value->record->...}
 
                // Para campos de arquivos/imagens
                {{$value->source}}
                </li>
            @endforeach
       </ul>
    </li>
@endforeach
</ul>