API atual/Referência completa/Webhooks de integração

Canais de venda

Registra na loja um pedido fechado em um canal externo, de forma idempotente (mecanismo antigo).

Este é o mecanismo antigo de canais de venda: o canal (ou um conector seu) avisa a loja de um pedido fechado lá fora. Ele só cria o cabeçalho do pedido, com o total, sem itens, endereço ou pagamento detalhados. Para integrar marketplaces de verdade, com anúncios, estoque, pedidos completos e rastreio, use o Hub de Marketplaces.

POST/api/v1/storefront/channels/{channel}/webhookPública

Registra um pedido vindo de um canal

Recebe de um canal de venda externo um pedido já fechado e o registra na loja. É idempotente pelo par (channel, external_order_id): repetir a chamada com o mesmo par não cria outro pedido.

Parâmetros de caminho

channelstringobrigatório

Nome do canal de origem, como você o usa (shopee, por exemplo). É guardado no pedido como a origem.

Corpo da requisição

vendor_iduuidobrigatório

Seller (lojista) dono do pedido.

external_order_idstringobrigatório

Número do pedido no canal. É a chave de idempotência.

total_centsinteger

Total do pedido em centavos (24990 = R$ 249,90). Vale como subtotal e total.

customer_iduuid

Cliente da loja a vincular ao pedido. Opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/channels/shopee/webhook" \
  -H "Content-Type: application/json" \
  -d '{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "external_order_id": "SHP-240918-001",
  "total_cents": 24990
}'

Resposta

200Pedido criado

json

{ "created": true, "order_id": "3f6c2d8e-91b4-4a7c-b5e0-7d1a2c3b4e5f" }

200Pedido já existia (repetição)

json

{ "created": false, "order_id": "3f6c2d8e-91b4-4a7c-b5e0-7d1a2c3b4e5f" }

Campos da resposta

createdboolean

true quando este pedido foi criado agora; false quando o par já existia.

order_iduuid

Id do pedido na loja (novo ou o que já existia).

Erros

Status	Quando	Corpo
400	Corpo que não é JSON, ou `vendor_id` / `external_order_id` ausentes.	`{"error":"vendor_id and external_order_id required"}`
410	Loja migrada para o Hub de Marketplaces: o mecanismo antigo está desligado.	`{"error":"crs_markethub_only","moved_to":"markethub"}`
500	`vendor_id` que não é UUID, ou falha ao gravar. Deveria ser 400 no primeiro caso.	`{"error":"failed to ingest order","detail":"..."}`

Veja também

Canais de venda

Registra na loja um pedido fechado em um canal externo, de forma idempotente (mecanismo antigo).

POST/api/v1/storefront/channels/{channel}/webhookPública

Registra um pedido vindo de um canal

Recebe de um canal de venda externo um pedido já fechado e o registra na loja. É idempotente pelo par (channel, external_order_id): repetir a chamada com o mesmo par não cria outro pedido.

Parâmetros de caminho

channelstringobrigatório

Nome do canal de origem, como você o usa (shopee, por exemplo). É guardado no pedido como a origem.

Corpo da requisição

vendor_iduuidobrigatório

Seller (lojista) dono do pedido.

external_order_idstringobrigatório

Número do pedido no canal. É a chave de idempotência.

total_centsinteger

Total do pedido em centavos (24990 = R$ 249,90). Vale como subtotal e total.

customer_iduuid

Cliente da loja a vincular ao pedido. Opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/channels/shopee/webhook" \
  -H "Content-Type: application/json" \
  -d '{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "external_order_id": "SHP-240918-001",
  "total_cents": 24990
}'

Resposta

200Pedido criado

json

{ "created": true, "order_id": "3f6c2d8e-91b4-4a7c-b5e0-7d1a2c3b4e5f" }

200Pedido já existia (repetição)

json

{ "created": false, "order_id": "3f6c2d8e-91b4-4a7c-b5e0-7d1a2c3b4e5f" }

Campos da resposta

createdboolean

true quando este pedido foi criado agora; false quando o par já existia.

order_iduuid

Id do pedido na loja (novo ou o que já existia).

Erros

Status	Quando	Corpo
400	Corpo que não é JSON, ou `vendor_id` / `external_order_id` ausentes.	`{"error":"vendor_id and external_order_id required"}`
410	Loja migrada para o Hub de Marketplaces: o mecanismo antigo está desligado.	`{"error":"crs_markethub_only","moved_to":"markethub"}`
500	`vendor_id` que não é UUID, ou falha ao gravar. Deveria ser 400 no primeiro caso.	`{"error":"failed to ingest order","detail":"..."}`