A plataforma possui uma série de recursos e funcionalidades para permitir a integração de transportadoras / fretes e a geração de etiqueta de envio.

A API ainda pode (e deve) ser utilizada, porém, apenas ela não é suficiente para que todas as interações de cotação de frete e geração de etiqueta sejam possíveis.

Neste artigo, vou explicar como fazer essa integração.

Cotação de frete

A cotação de frete é acontece sempre que o cliente, no frontend de loja, deseja calcular quais fretes estão disponíveis para o seu local de entrega. Essa cotação geralmente acontece na tela de carrinho e na tela de fechamento de pedido.

Para adicionar novas formas de entrega, você deverá disponibilizar uma API que irá responder quais as formas de entrega disponíveis. Essa API será chamada a cada solicitação do cliente.

Será feito um POST para a URL que você definir, com o seguinte JSON como body:

{
    "recipient_zip_code": "00000000", // CEP de destino
    "total": 150, // Valor da venda
    "items": [ // Array de produtos (neste exemplo, com apenas um objeto)

        {
            "quantity": 1, // Quantidade deste produto no carrinho
            "weight": 0.5, // Em kg
            "height": 10, // Em cm
            "length": 20, // Em cm
            "width": 30, // Em cm
            "sku": "SKU-01", // SKU do produto, não obrigatório
            "id": 12, // ID do produto
            "categories": ["nome da categoria"] // Array de categorias deste produto
        }
    ]
}

Esta URL, deverá retornar as formas de entrega no seguinte formato:

{
    "data": [ // Array com as opções de forma de entrega
        {
            "amount": 10.88, // Valor do frete
            "shipper": "Correios", // Nome da transportadora
            "description": "SEDEX", // Nome do frete
            "zip_code_start": "00000000", // Início da faixa de CEP em questão (pode ser o mesmo CEP consultado)
            "zip_code_end": "00000000", // Término da faixa de CEP em questão (pode ser o mesmo CEP consultado)
            "max_weight_volume": 0.5, // Peso máximo aceito pela transportadora para esse valor de frete
            "correios_service_code": "01234", // Código dos Correios, se for o caso (não obrigatório)
            "min_weight_volume": 0.5, // Peso mínimo aceito pela transportadora para esse valor de frete
            "time_cost": "5.00:00:00" // Prazo de entrega, no formato "[número de dias].00:00:00"
        }
    ]
}

Assim, a loja exibirá as formas de entrega disponibilizadas.

Geração de etiquetas

O processo de geração de etiquetas geralmente acontece em 2 passos:

1. Geração de etiquetas
2. Impressão das etiquetas

A geração de etiquetas é um processo que acontece em segundo plano. Ou seja, o usuário faz a solicitação e o processamento será feito pelo sistema em background; ele não ficará preso na requisição.

Mas antes da geração da etiqueta em si, você deve se preocupar com o menu de ação.

Menu de ação

O menu de ação são as opções que o usuário tem ao selecionar uma ou mais vendas.

Neste momento, você receberá os pedidos que o usuário selecionou e poderá exibir ou não a opção de gerar ou imprimir etiqueta.

Devem ser disponibilizados duas APIs: uma para quando o usuário selecionar uma venda e outra para quando selecionar várias vendas.

A URL de uma venda, receberá o ID da venda na própria URL. Por exemplo:

/orders/{orderId}/action-menu

Neste caso, será feito um GET para essa URL.

Já no caso de várias vendas, será feito um POST para a URL. Sendo que os IDs serão enviados em um JSON no body:

{
    "orders": [1, 2, 5] // IDs das vendas selecionadas
}

As opções devem ser retornadas no seguinte formato:

{
    "data": [
        {
            "label": "Rótulo do menu",
            "endpoint": "https://endpoint", // Endpoint que o request deverá ser feito
            "http_method": "POST", // Tipo de request
            "type": "ajax" // Modalidade de request
        }
    ]
}

É possível também definir que um menu de ação direcione o usuário para uma URL. Esse formato é especialmente útil no caso da impressão de etiqueta, que o usuário poderá ser direcionado para uma página que contêm a etiqueta em si.

{
    "data": [
        {
            "label": "Rótulo do menu",
            "redirect_url": "https://endpoint", // Endpoint para redirecionamento
            "type": "redirect-blank" // Modalidade de request
        }
    ]
}

Cabe a esses serviços definir se a etiqueta da venda em si deve ser gerada ou já pode ser impressa.

Geração e impressão

Perceba que é você que define quais são os passos para geração da etiqueta. Você poderia, por exemplo, definir apenas o menu de ação de redirecionamento que faria a geração da etiqueta e exibiria a opção de imprimir a etiqueta.

O endpoint que for definido no menu deverá fazer o serviço do menu. A plataforma não irá obrigar nenhum tipo de processo ou passo-a-passo.

Instalação e homologação

Após todos os serviços estarem desenvolvidos, a Betalabs deve ser informada quais são as URLs de cotação de frete e de menu.

Depois disso, o app será instalado e homologado.