Consumo de Pedidos - Queues

Nesta seção mostraremos como é realizado o consumo de pedidos criados e atualizados pelo marketplace

Quando criado no marketplace, o pedido tem suas informações encaminhadas para a API, cabendo a plataforma/ERP o consumo de seus dados. O mesmo ocorre para atualizações do pedido: A informação será disponibilizada na API para consumo da plataforma/ERP.

Tanto criação quanto atualização serão notificadas pelo marketplace e deverão ser consumidas no recurso /queues/orders.

GET - Baixando pedidos (fila de integração)

Quando um pedido é gerado ou tem o status atualizado pelo o marketplace ele (pedido) é colocado em uma fila de integração e fica disponível para a baixa, que deve ser realizada através de um GET no endpoint visto a seguir:

https://api.skyhub.com.br/queues/orders

Request headers:

Key	Value
X-User-Email	email_de_usuario
X-Api-Key	token_de_integracao de sua conta SkyHub
X-Accountmanager-Key	token_account único de cada Plataforma/ERP
Accept	application/json
Content-Type	application/json

Example request:

curl --location --request GET 'https://api.skyhub.com.br/queues/orders' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Response esperado:

Dois possíveis retornos são esperados para o GET:

204 [Success] - No content: Retorno esperado caso não hajam pedidos novos/atualizados para consumo;

200 [Success] - OK: Caso existam pedidos novos/atualizados, será visualizado status 200 e o response body trará as informações da entrega, conforme exemplo:

{
    "channel": "AMERICANAS",
    "calculation_type": "b2wentregacorreios",
    "shipping_carrier": "Courier",
    "invoices": [],
    "tags": [],
    "expedition_limit_date": null,
    "code": "Lojas Americanas-1000000000005",
    "approved_date": "",
    "delivered_date": null,
    "shipping_cost": 0.0,
    "shipped_date": "",
    "items": [
        {
            "special_price": 39.9,
            "shipping_cost": null,
            "remote_store_id": null,
            "qty": 1,
            "product_id": "2023001",
            "original_price": 39.9,
            "name": "Camiseta Branca Tam. Único",
            "listing_type_id": null,
            "id": "2023001",
            "gift_wrap": null,
            "detail": null,
            "delivery_line_id": null
        }
    ],
    "imported_at": "2023-03-27T16:48:07-03:00",
    "import_info": {
        "ss_name": "Lojas Americanas",
        "remote_id": null,
        "remote_code": "1000000000005",
        "pack_id": null,
        "cart_id": null
    },
    "target_order": null,
    "shipping_method": "Courier",
    "shipping_address": {
        "street": "Avenida Paulista",
        "secondary_phone": "99 999999999",
        "region": "SP",
        "reference": null,
        "postcode": "90000000",
        "phone": "99 999999999",
        "number": "1000",
        "neighborhood": "Bela Vista",
        "full_name": "João dos Santos",
        "detail": "Ao lado da cafeteria",
        "country": "BR",
        "complement": null,
        "city": "São Paulo"
    },
    "sync_sale_system": null,
    "discount": 0.0,
    "first_exported_at": null,
    "billing_address": {
        "street": "Avenida Paulista",
        "secondary_phone": "99 999999999",
        "region": "SP",
        "reference": null,
        "postcode": "90000000",
        "phone": "99 999999999",
        "number": "1234",
        "neighborhood": "Bela Vista",
        "full_name": "João dos Santos",
        "detail": "Próximo ao museu",
        "country": "BR",
        "complement": null,
        "city": "São Paulo"
    },
    "interest": 0.0,
    "available_to_sync": true,
    "payments": [
        {
            "value": 39.9,
            "type": null,
            "transaction_date": null,
            "status": null,
            "sefaz": {
                "type_integration": null,
                "payment_indicator": null,
                "name_payment": null,
                "name_card_issuer": null,
                "id_payment": null,
                "id_card_issuer": null
            },
            "parcels": 1,
            "method": "CREDIT_CARD",
            "description": "SkyHub",
            "card_issuer": null,
            "autorization_id": null
        }
    ],
    "placed_at": "2023-03-27T16:48:07-03:00",
    "delivery_contract_type": "",
    "shipping_estimate_id": "",
    "linked_order": null,
    "estimated_delivery_shift": null,
    "shipping_method_id": null,
    "estimated_delivery": "2023-03-30T00:00:00-03:00",
    "id": "6000f0f0d0ee0000000f0e00",
    "shipments": [],
    "total_ordered": 39.9,
    "updated_at": "2023-03-27T16:48:07-03:00",
    "status": {
        "type": "NEW",
        "label": "Pagamento Pendente (new) (SkyHub)",
        "code": "book_product"
    },
    "customer": {
        "vat_number": "23455567899",
        "phones": [
            "99 999999999"
        ],
        "name": "João dos Santos",
        "gender": "male",
        "email": "[e-mail]",
        "date_of_birth": "1989-01-01"
    },
    "delivery_token": {
        "takeout": null,
        "failure": null,
        "customer": null
    },
    "sync_status": "NOT_SYNCED",
    "exported_at": null
}

Através da queues não é possível consumir um pedido especificamente. A fila deverá ser consumida por completo com as informações disponibilizadas pelo marketplace.

Suponha-se que existam 20 pedidos gerados/atualizados pelo marketplace; as notificações cairão na fila aleatoriamente, porém visando aquelas mais recentes, sendo de responsabilidade da plataforma/ERP o consumo de todas as informações disponibilizadas.

Mantendo a fila de integração "limpa", isto é, consumindo sempre todos os pedidos, garante-se que todos os novos gerados e todas as alterações de status estarão atualizados na plataforma/ERP.

O consumo do pedido sempre trará o campo calculation_type, responsável por identificar o método de cálculo de frete.

Sempre que o calculation_type for preenchido com o valor b2wentregadirect, espera-se para o payload o array pick_ups contendo informações da warehouse (CD) e SKU de venda.

Por padrão, o array pick_ups é incluso apenas para pedidos b2wentregadirect, desta forma, para pedidos cujo calculation_type for b2wentregacorreios não haverá a inclusão do referido array (pick_ups).

Dicas sobre a fila de integração de pedidos

-> Verificar o campo status[code]

Ao recuperar um pedido da fila, a integração deve verificar o campo status[code] para saber qual foi o tipo de evento: pedido novo ou uma atualização (aprovação ou cancelamento).

-> O GET na /queues/orders sempre irá retornar o status atual do pedido

O pedido entra na fila sempre que receber alguma atualização proveniente do marketplace e para a plataforma/ERP será disponibilizada a informação da última alteração sofrida.

Imagine o seguinte cenário:

1. O pedido é gerado no marketplace (status NEW) e entra na fila (/queues/orders);

2. A plataforma/ERP não consome o recurso /queues/orders;

3. O pedido tem o pagamento confirmado no marketplace (status APPROVED) e esta atualização entra novamente na fila /queues/orders;

4. Nesse momento a integração faz uma chamada GET /queues/orders. O JSON do pedido retornado conterá o status APPROVED (status atual do pedido) ao invés do status NEW (status que o pedido tinha quando entrou na fila pela primeira vez);

5. Como o pedido entrou duas vezes na fila e não havia sido consumido, ao ser repetida a chamada GET /queues/orders (sem que haja uma nova atualização do marketplace), a integração receberá o mesmo JSON novamente.

-> Estoque Disponível x Estoque Empenhado

É obrigatório consumir todos os pedidos da fila de integração (/queues) com status NEW para que os produtos sejam empenhados em seus estoques.

Esta obrigatoriedade se dá para que sejam evitadas divergências entre o estoque disponível e o estoque empenhado.

O que pode acontecer caso não consuma todos os status do pedido? Ao não consumir o status de NEW não haverá empenho de estoque na plataforma, assim a API receberá a informação de que há estoque disponível para venda, consequentemente, poderão haver vendas sem estoque.

Vale lembrar:

• As plataformas que não se adequarem a essa regra de negócios podem arcar com prejuízo do seller;

• Para a API deve ser enviado apenas o estoque disponível para venda.

DELETE - Confirmando o consumo do pedido

Após o GET na /queues/orders o pedido apresentado sairá da fila de integração e ficará aguardando por 5 minutos para que a plataforma/ERP confirme o seu processamento. Esta confirmação é realizada utilizando os headers padrões na API e aplicando um DELETE no endpoint:

https://api.skyhub.com.br/queues/orders/{code}

O {code} a ser utilizado é o código de identificação do pedido, visualizado após o GET.

No exemplo disponibilizado acima, temos o "code": "Lojas Americanas-1000000000005".

Se em até 5 minutos a API não receber a confirmação de que a integração conseguiu processar o pedido com sucesso, o mesmo voltará para a fila, ou seja, após o GET na /queues/orders a plataforma/ERP tem até 5 minutos para realizar a confirmação do consumo da informação.

Caso o sistema tente confirmar o consumo (DELETE) após os 5 minutos sem que haja um novo GET na /queues/orders será retornado status 404.

Example request:

curl --location --request DELETE 'https://api.skyhub.com.br/queues/orders/Lojas Americanas-1000000000005' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Response esperado:

204 [Success] - No content

Importante que como boa prática aconselhamos que seja realizado o DELETE logo na sequência do GET, para evitar possíveis furos no consumo de pedidos.