Logística do Vendedor (API de Cotação)

Este canal permite que o vendedor utilize sua própria logística para cotação e envio de pedidos.

• A cotação de frete é feita a partir da URL de cotação disponibilizada pelo vendedor.
• O preço de envio e prazo de entrega são fornecidos pelo próprio vendedor.
• O rastreamento dos pedidos é simplificado, ficando sob responsabilidade do vendedor enviar os eventos de “despachado”, “entrega” ou “falha na entrega” via OpenAPI.

Obs: Este canal será disponibilizado a vendedores específicos, cujos produtos não são suportados pela logística própria da Shopee por conta de dimensões e peso, de acordo com as regras estabelecidas pelo time comercial da Shopee.

É a ferramenta que permite ao vendedor enviar para a Shopee o custo do frete e prazo estimados que serão exibidos ao comprador no momento da compra. Para que o vendedor possa utilizar esse recurso, é preciso atender os requisitos de homologação pré-estabelecidos.

*O vendedor tem a opção de integrar diretamente com a Shopee para conectar sua URL de cotação ou se conectar via um Integrador-HUB.

Diferente dos outros tipos de integração, a integração da API de cotação e atualização de status de pedido (do canal seller logistics), exigem uma avaliação e aprovação do time Shopee antes de começar a operar. Para ser aprovado pelo time da Shopee é necessário:

• Cumprimento do contrato da API de cotação de frete:Configurar e disponibilizar a URL via método HTTP POST.Cada solicitação (request) deve conter apenas um item de um vendedor.A URL não tem uma estrutura específica, proporcionando flexibilidade na configuração.
• Payload padrão da requisição e resposta de cotação (e validação com URL da Shopee)
• Tempo de resposta limite de 400ms.
• Tabela de contingência cadastrada diretamente pela Central do Vendedor.
• Monitoramento de erros (e desenvolvimento das mensagens solicitadas)
• Desenvolvimento API de atualização de status (“update_tracking_status);Obs: Os requisitos acima devem ser cumpridos pelo “próprio sistema” do vendedor ou pelo seu ERP/HUB/Integração. Vale ressaltar que sem eles os pedidos serão cancelados, pois o fluxo não pode ser realizado via Central do Vendedor de forma manual.Obs2: Todos que desenvolverem a API de cotação, também devem desenvolver a API de atualização de status;Obs3: O APP Seller Logistics, só é usado para URL de cotação, para usar qualquer API é necessário a criação de um segundo APP;
• Passar e-mail de confirmação e aprovação do time da Shopee via ticket (envolvendo todos critérios acima).

Para conseguir realizar a integração e os testes acima também é necessário:

a) Criar novo APP Seller Logistic na Open Platform e autorizar os sellers a esse APP

b) Ter um APP que seja capaz de chamar a OpenAPI para atualização de status (e também autorizar os sellers a esse APP)

Teste de Homologação

1. Fluxo Logístico do pedido: Será necessário a criação de pelo menos 2 pedidos, que precisarão ser atualizados até os seguintes status:

- order 1: delivery_done

- order 2: delivery_failed

2. Teste de Cotação no item: Um teste interno de cotação também será feito diretamente em um dos anúncios da loja.

Ambas etapas terão validação interna (essas validações podem levar alguns dias) e daremos a confirmação ao parceiro via ticket que foi aberto pelo mesmo.

Observação: Ao completar o fluxo de atualização de status você se compromete que esses status estão corretamente mapeados, integrados e automatizados para envio para API da Shopee. Os pedidos dos vendedores não são atualizados de forma manual pela Shopee, apenas pelo recebimento dos status via API. Caso ocorra problemas futuros, o canal poderá ser desativado após análise da Shopee.

(A inclusão interna do parceiro como opção de TMS para RMs solicitarem ativação de lojas, é responsabilidade de outro time interno e o processo de atualização leva, em torno, de 15 dias úteis.)

Uma vez que sua conta na Open Platform já esteja ativa, o próximo passo é criar um APP que será usado apenas para conectar sua URL de cotação a Shopee e respectivos sellers(shop_Id).

Segue passo a passo, abaixo:

1. Fazer Login na Open Platform e entrar na aba “Console”:

2. Em “App List” clicar em “+ Add new APP”:

3. Selecionar a “App Category” como “Seller Logistics”:

4. Inserir no “App Description” as URLs que serão usadas em Live (produção) e em Test (ambiente de teste), e clicar em “Submit”.

*sem problemas se houver apenas uma URL;

5. Assim o APP já estará criado, então, só seguir com a solicitação de “Go-Live”, que vai disponibilizar o APP no ambiente de produção em até 24 horas.

6. Só é necessário preencher mais algumas infos antes.

Caso não seja possível fornecer um “username” e “password”, podem preencher como no print abaixo:

7. Para “App IP”, informar o IP principal da sua aplicação (vale ressaltar que não vamos limitar o acesso apenas a esse IP).

E para “Other IT Assets Declaration”, preencher como no print abaixo.

24 horas após a solicitação do “Go-live” o partner_id de Live será liberado e você será notificado via e-mail. Assim que receber o e-mail, os próximos passos são:

1 - Abrir um ticket na Plataforma de Tickets da OP, com o assunto “Seller Logistics” informando o shop_id (ou quais Shop IDs) pretende conectar a sua URL, assim que recebermos a solicitação e o time da Shopee finalizando a conexão da URL, e permitindo avançar com a autorização do seller.

Obs: cada shop_id só pode estar conectado a uma URL aqui na Shopee;

2 - Realizar o fluxo de autorização para o seu seller, conforme passo a passo do link (até o tópico 4 do “Autorizando com uma conta de loja”).

3 - Assim que o time da Shopee responder seu ticket, confirmando que a configuração foi feita e seu seller realizar o fluxo de autorização, já será possível realizar os primeiros testes em LIVE.

Payload padrão da requisição e resposta de cotação

Parâmetros da requisição (query)

URL Request Parameters:

Body Request Parameters:

Response Parameters / Resposta da Cotação (erro):

Response Parameters / Resposta da Cotação (sucesso):

Exemplo de requisição

curl --location 'https://api.frete/?partner_id=123456&sign=6b664c45535a544455524f6b565776706752784455784978574361444e795a4c&timestamp=1709843385' \
--header 'Content-Type: application/json' \
--data '{
    "shop_id": 601216389,
    "origin_zip_code": "87952525",
    "destination_zip_code": "17036785",
    "items": [
        {
            "item_id": 892569034,
            "model_id": 1,
            "sku": "",
            "category_id": 1,
            "quantity": 1,
            "price": 12.5,
            "dimensions": {
                "length": 1,
                "width": 1,
                "height": 1,
                "weight": 150
            }
        }
    ]
}'

Exemplo de retorno (sucesso)

• Usar HTTP status code 200

{
    "quotation_id": 1709843321,
    "destination_zip_code": "17036785",
    "packages": [
        {
            "dimensions": {
                "length": 35,
                "width": 90,
                "height": 114,
                "weight": 27300
            },
            "items": [
                {
                    "item_id": 892569034,
                    "model_id": 1,
                    "sku": "",
                    "category_id": 1,
                    "quantity": 1,
                    "price": 12.5,
                    "dimensions": {
                        "length": 1,
                        "width": 1,
                        "height": 1,
                        "weight": 150
                    }
                }
            ],
            "quotations": [
                {
                    "price": 93.55,
                    "handling_time": 1,
                    "shipping_time": 7,
                    "promise_time": 8,
                    "service_code": "50"
                }
            ]
        }
    ]
}

Exemplo de retorno (erro)

• Usar HTTP status code 403

{
    "request_id": "Id da requisição",
    "error": "coluna Error",
    "message": "coluna Message"
}

Retorno padrão para erros não mapeados na tabela de erros

• Usar HTTP status code 500

{
    "request_id": "65e9e26dd9d2565e9e26dd9d64",
    "error": "Internal system error",
    "message": "internal system error"
}

Códigos de retorno esperados

Validação dos responses (com URL da Shopee)

• Para garantir que o response está no formato esperado, temos uma URL que deve ser usada para validar e informar as correções necessárias.
• URL: "https://seller-quotation-api.uat.shps-br-services.com/validate_quotation_endpoint"
• Dentro do parâmetro "x-quotation-id" deve ser usado para inserir a URL que será cadastrada na Shopee.
• Segue payload de exemplo de como utilizar a URL de validação do formato de response:

curl --location 'https://seller-quotation-api.uat.shps-br-services.com/validate_quotation_endpoint' \
--header 'api-key: 8a50d1d005d0649b5bdd9b13f0e871e0bd6439bd8e146577a6d51935a5ccea7c' \
--header 'x-partner-id: 2007416' \
--header 'x-quotation-api-url: https://api.cotação/shopee' \
--header 'x-sign: 658ABD0FD8D8525C0A87B0E360A5C518C2987E5B4A3D20542A4B11594E11CE53' \
--header 'Content-Type: application/json' \
--data '{
    "shop_id": 549724933,
    "origin_zip_code": "16200850",
    "destination_zip_code": "16200850",
    "items": [
        {
            "item_id": 10010394,
            "sku": "10010394",
            "model_id": 1,
            "category_id": 1,
            "quantity": 1,
            "price": 277.67,
            "dimensions": {
                "length": 1,
                "width": 1,
                "height": 1,
                "weight": 10
            }
        }
    ]
}'

• Segue response sem erros (pode ser identificado quando o parâmetro "validation_errors" estiver vazio ("validation_errors:[]"):

{
    "validation_errors": [],
    "details": {
        "called_api": "https://api.cotação/shopee",
        "with_params": {
            "sign": "658ABD0FD8D8525C0A87B0E360A5C518C2987E5B4A3D20542A4B11594E11CE53",
            "partner_id": 2007416,
            "timestamp": 1713445311
        },
        "with_body": {
            "shop_id": 549724933,
            "origin_zip_code": "16200850",
            "destination_zip_code": "16200850",
            "items": [
                {
                    "item_id": 10010394,
                    "model_id": 1,
                    "sku": "10010394",
                    "category_id": 1,
                    "quantity": 1,
                    "price": 277.67,
                    "dimensions": {
                        "length": 1,
                        "width": 1,
                        "height": 1,
                        "weight": 10
                    }
                }
            ]
        },
        "response_from_quotation_api": {
            "status_code": 200,
            "response_body": {
                "quotation_id": 617788888,
                "destination_zip_code": "16200850",
                "packages": [
                    {
                        "dimensions": {
                            "length": 1,
                            "width": 1,
                            "height": 1,
                            "weight": 10
                        },
                        "items": [
                            {
                                "item_id": 10010394,
                                "sku": "10010394",
                                "model_id": 1,
                                "category_id": 1,
                                "quantity": 1,
                                "price": 277.67,
                                "dimensions": {
                                    "length": 1,
                                    "width": 1,
                                    "height": 1,
                                    "weight": 10
                                }
                            }
                        ],
                        "quotations": [
                            {
                                "price": 34.9,
                                "handling_time": 5,
                                "shipping_time": 10,
                                "promise_time": 20,
                                "service_code": "2018605604"
                            }
                        ]
                    }
                ]
            },
            "method_called": "POST"
        }
    }
}

• Segue response com exemplo de erros a serem corrigidos:

{
    "validation_errors": "Input should be a valid string: ('error',)",
    "details": {
        "called_api": "https://api.cotação/shopee": {
            "sign": "658ABD0FD8D8525C0A87B0E360A5C518C2987E5B4A3D20542A4B11594E11CE53",
            "partner_id": 2007416,
            "timestamp": 1713472133
        },
        "with_body": {
            "shop_id": 549724933,
            "origin_zip_code": "16200850",
            "destination_zip_code": "16200850",
            "items": [
                {
                    "item_id": 10010394,
                    "model_id": 0,
                    "sku": "10010394",
                    "category_id": 1,
                    "quantity": 1,
                    "price": 277.67,
                    "dimensions": {
                        "length": 1,
                        "width": 1,
                        "height": 1,
                        "weight": 10
                    }
                }
            ]
        },
        "response_from_quotation_api": {
            "status_code": 403,
            "response_body": {
                "request_id": "17134721330005",
                "error": 403,
                "message": "there is no partner_id in query",
                "msger": "Nao foi possivel concluir sua solicitacao."
            },
            "method_called": "POST"
        }
    }
}

Tempo de resposta limite (da cotação)

• Considerando que o checkout é o momento mais crítico da experiência do usuário durante a compra, é essencial garantir a melhor experiência possível ao comprador.
• O tempo de resposta limite é de 1s. É necessário realizar um teste de carga para garantir que essa exigência seja atendida.
• Tempos de resposta superiores a 1s não serão permitidos, inviabilizando a integração. Dessa forma, manter a otimização desse parâmetro é fator crucial para proporcionar a melhor experiência possível ao comprador.

• Este recurso tem como finalidade apoiar no cálculo do frete, caso ocorra algum problema na cotação de frete via API (timeout ou retorno 500 para as requisições).

Configurações de valor de frete para contingência

• Para que a contingência funcione, é necessário que o vendedor cadastre os valores de frete e habilite o canal Logística do vendedor, conforme passos descritos abaixo.
• Na Central do Vendedor, acesse Configurações de Envio e clique no botão Configuração do canal:

Preenchimento do valor de frete de contingência

Em seguida, será carregada a tela para preenchimento do valor de frete. O valor de frete pode ser preenchido por estado (valor único) ou por localidade.

Valor de frete único por estado

• Selecione os estados
• Preencha o campo valor do frete
• Clique em Salvar

Valor de frete único por cidade

• Selecione os estados
• Desabilite o botão Flat rate for this area
• Desmarque a opção Select All Cities e selecione as cidades que deseja informar o valor do frete
• Preencha o campo Rate das respectivas cidades
• Clique em Salvar

Habilitação do canal Logística do vendedor

Prazo de entrega para valor de frete de contingência

• O prazo de entrega será fixo, quando acionada a tabela de contingência:Prazo mínimo: 10 dias corridosPrazo máximo: 20 dias úteis

Desenvolvimento API de atualização de status:

A atualização de status dos pedidos e rastreamento se dará por meio da API de atualização de tracking e será feita com base no número do pedido criado na Shopee (ID do Pedido, também conhecido por OrderSN). No qual também será obrigatório informar o número de rastreio.

Para atualização do número do rastreio e status do pedido deve ser utilizado o endpoint v2.logistics.update_tracking_status (OpenAPI). Os status possíveis são:

• Pedido Enviado (logistics_pickup_done)A URL e o tracking number podem ser enviados na atualização do status do pedido para Enviado.
• Pedido Entregue (logistics_delivery_done)O status Entregue só será recebido, caso o pedido já possua status o status Enviado.
• Falha na Entrega (logistics_delivery_failed)O status Falha na Entrega só será recebido, caso o pedido já possua status o status Enviado.

IMPORTANTE: após envio dos status Pedido Entregue ou Falha na Entrega não será mais permitida atualização de status, pois ambos são status finalizadores;

*os parâmetros tracking_number e tracking_url devem ser enviados apenas na atualização do status para logistics_pickup_done.

Segue link para documentação da API “/api/v2/logistics/update_tracking_status”.

• O desconto máximo do frete para o comprador é de R$ 20, caso o vendedor esteja no Programa de Frete Grátis
• O vendedor terá uma coparticipação no desconto oferecido ao cliente.

1 - Todos os vendedores tem acesso ao canal Logística do Vendedor?

R: Somente vendedores gerenciados tem acesso ao canal, para mais informações procure seu Gerente de contas.

2 - Como identificar uma cotação no pedido?

R: Uma vez um pedido criado com uma cotação de sucesso, o parâmetro “service_code”, será retornado no parâmetro “shipping_carrier” da API get_order_detail.

Ex1:

• “service_code” enviado: “Canal X”
• retorno do parâmetro “shipping_carrier”: “Logística do vendedor - Canal X”

Ex2:

• Tabela de contingência ativada.
• retorno do parâmetro “shipping_carrier”: “Logística do vendedor”

3 - Posso usar o APP Seller Logistics para chamar a OpenAPI?

R: Não, esse tipo de APP só é usado para API de cotação (URL de cotação).

Para mais dúvidas técnicas, abrir um ticket na Plataforma de Tickets da OP.

Para dúvidas sobre acesso ao canal logístico, segue link.