Pedidos

Criar Pedido

Registra uma venda feita fora da loja (marketplace, balcão, outro sistema)

POST

/v1/pedidos

Escopo

pedidos.criar

O pedido aparece no painel como qualquer outro (forma de pagamento "Venda externa (API)"), com histórico de origem api. Cancelado depois, devolve o estoque que baixou.
Mesma referencia_externa: a resposta é 200 (não 201) com o pedido existente e o cabeçalho X-Idempotente: true. Assim um reenvio por falha de rede nunca duplica a venda.
Estoque insuficiente em qualquer item: 409 estoque_insuficiente e nada é criado. O estoque por opção de variação não é baixado: ajuste com Estoque por Variação.
O evento pedido.criado é enviado aos webhooks como nos pedidos do site.

Autorização

Authorizationstringobrigatórioheader

Chave da API no formato Bearer hdl_live_.... Crie no painel da loja em Integração › API e webhooks. Saiba mais.

Corpo da requisição

clienteobjectobrigatóriobody · application/json

{ nome (obrigatório), email, whatsapp, documento }. Liga ao cadastro com o mesmo e-mail ou WhatsApp, ou cria um.

itensobject[]obrigatóriobody · application/json

[{ produto_id ou sku, quantidade (padrão 1), preco_unitario, nome, variacao }] (até 100). Sem preco_unitario vale o preço atual do produto. Item avulso: nome e preco_unitario, sem produto.

referencia_externastringbody · application/json

Id do pedido no seu sistema (até 80). Repetir a mesma referência devolve o pedido já criado, sem duplicar. Também aceita o cabeçalho Idempotency-Key.

entregaobjectbody · application/json

{ forma ("retirada" ou o nome do envio), valor, endereco: { cep, rua, numero, complemento, bairro, cidade, estado, referencia } }.

pagamentoobjectbody · application/json

{ forma (texto livre, ex.: "Pix no balcão"), situacao: pendente (padrão) ou pago }.

descontonumberbody · application/json

Desconto em reais (no máximo o subtotal).

observacaostringbody · application/json

Recado do pedido (até 240).

baixar_estoquebooleanbody · application/json

Padrão true: baixa o estoque dos produtos que controlam estoque (tudo ou nada).

enviar_emailbooleanbody · application/json

true envia ao cliente o e-mail de pedido recebido (padrão false).

Resposta

201 — objeto { "dados": {...} } com um Pedido.

Erros possíveis

HTTP	código	quando
`401`	`nao_autenticado`	Faltou o cabeçalho Authorization: Bearer <chave>.
`401`	`chave_invalida`	Chave inexistente ou revogada.
`403`	`sem_permissao`	A chave não tem o escopo exigido pelo endpoint.
`409`	`mesmo_status`	O pedido já está no status pedido.
`409`	`pedido_encerrado`	Pedido cancelado ou reembolsado não muda mais.
`409`	`estoque_insuficiente`	Saída maior que o saldo.
`409`	`limite_do_plano`	A loja atingiu o limite de produtos do plano.
`409`	`limite_webhooks`	A loja já tem 10 webhooks.
`409`	`limite_imagens`	O produto já tem 20 imagens.
`409`	`cliente_existente`	Já existe cliente com este WhatsApp ou e-mail (id em campos.cliente_id).
`409`	`saldo_insuficiente`	Débito de cashback maior que o saldo do cliente.
`409`	`limite_enderecos`	O cliente já tem 20 endereços.
`409`	`limite_faixas`	A loja já tem 300 faixas de frete.
`409`	`meio_indisponivel`	O meio de pagamento não está instalado, ligado e configurado na loja.
`409`	`pedido_nao_pendente`	Só pedido pendente recebe link de pagamento.
`409`	`aplicativo_nao_instalado`	Instale o aplicativo no painel antes de gravar as regras.
`409`	`canal_inativo`	O canal de marketplace não está ativo na loja.
`409`	`canal_sem_pedidos`	O canal só recebe o catálogo (feed), não tem pedidos.
`422`	`fornecedor_recusou`	O fornecedor (AliExpress) recusou ou a conta não está conectada; a mensagem traz o motivo.
`409`	`categoria_em_uso`	A categoria tem produtos ou subcategorias.
`409`	`conflito`	O recurso mudou durante a chamada: consulte e tente de novo.
`422`	`imagem_invalida`	A imagem não pôde ser baixada ou não é JPG, PNG, WEBP ou GIF de até 5 MB.
`422`	`validacao`	Campos inválidos: veja o objeto "campos".

curl --request POST \ --url 'https://api.hoteldaslojas.com.br/v1/pedidos' \ --header 'Authorization: Bearer <chave>' \ --header 'Content-Type: application/json' \ --data '{"referencia_externa": "ML-2000009876543", "cliente": {"nome": "Marina Duarte", "email": "[email protected]", "whatsapp": "41999990000"}, "itens": [{"sku": "LIV-001", "quantidade": 3}, {"nome": "Embalagem presente", "preco_unitario": 5}], "entrega": {"forma": "Transportadora X", "valor": 15, "endereco": {"cep": "01310100", "rua": "Av. Paulista", "numero": "1000", "bairro": "Bela Vista", "cidade": "São Paulo", "estado": "SP"}}, "desconto": 3, "pagamento": {"forma": "Pix no balcão", "situacao": "pago"}}'

import os, requests resposta = requests.post( "https://api.hoteldaslojas.com.br/v1/pedidos", headers={"Authorization": f"Bearer {os.environ['HDL_CHAVE']}"}, json={ "referencia_externa": "ML-2000009876543", "cliente": { "nome": "Marina Duarte", "email": "[email protected]", "whatsapp": "41999990000" }, "itens": [ { "sku": "LIV-001", "quantidade": 3 }, { "nome": "Embalagem presente", "preco_unitario": 5 } ], "entrega": { "forma": "Transportadora X", "valor": 15, "endereco": { "cep": "01310100", "rua": "Av. Paulista", "numero": "1000", "bairro": "Bela Vista", "cidade": "São Paulo", "estado": "SP" } }, "desconto": 3, "pagamento": { "forma": "Pix no balcão", "situacao": "pago" } }, timeout=30, ) resposta.raise_for_status() print(resposta.json()["dados"])

<?php $ch = curl_init('https://api.hoteldaslojas.com.br/v1/pedidos'); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('HDL_CHAVE'), 'Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode([ 'referencia_externa' => 'ML-2000009876543', 'cliente' => [ 'nome' => 'Marina Duarte', 'email' => '[email protected]', 'whatsapp' => '41999990000' ], 'itens' => [[ 'sku' => 'LIV-001', 'quantidade' => 3 ], [ 'nome' => 'Embalagem presente', 'preco_unitario' => 5 ]], 'entrega' => [ 'forma' => 'Transportadora X', 'valor' => 15, 'endereco' => [ 'cep' => '01310100', 'rua' => 'Av. Paulista', 'numero' => '1000', 'bairro' => 'Bela Vista', 'cidade' => 'São Paulo', 'estado' => 'SP' ] ], 'desconto' => 3, 'pagamento' => [ 'forma' => 'Pix no balcão', 'situacao' => 'pago' ] ]), ]); $resposta = json_decode(curl_exec($ch), true); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); print_r($resposta);

{ "dados": { "id": 2180, "criado_em": "2026-10-28T02:53:20-03:00", "status": "pago", "status_nome": "Pago", "situacao_pagamento": "aprovado", "situacao_entrega": "aguardando", "cliente": { "id": 512, "nome": "Marina Duarte", "email": "[email protected]", "whatsapp": "41999990000", "documento": "" }, "valores": { "subtotal": 184.7, "desconto": 3.0, "frete": 15.0, "total": 196.7 }, "cupom": null, "pagamento": { "forma": "api", "nome": "Venda externa (API)", "informacao": "Pix no balcão", "pago_em": "2026-10-28T02:53:20-03:00", "link": null }, "entrega": { "forma": "Transportadora X", "nome": "Transportadora X", "codigo_rastreio": null, "endereco": { "cep": "01310100", "rua": "Av. Paulista", "numero": "1000", "complemento": "", "bairro": "Bela Vista", "referencia": "", "cidade": "São Paulo", "estado": "SP" } }, "observacao": null, "itens": [ { "id": 771, "produto_id": 2291, "sku": "LIV-001", "nome": "O Farol das Horas Quietas", "variacao": null, "quantidade": 3, "preco_unitario": 59.9, "total": 179.7, "peso_kg": 0.4 }, { "id": 772, "produto_id": null, "sku": "", "nome": "Embalagem presente", "variacao": null, "quantidade": 1, "preco_unitario": 5.0, "total": 5.0, "peso_kg": 0.0 } ], "notas_internas": null, "nota_fiscal": null, "referencia_externa": "ML-2000009876543", "historico": [ { "status": "pago", "origem": "api", "detalhe": "Pedido criado pela API (ML-2000009876543)", "em": "2026-10-28T02:53:20-03:00" } ] } }

{ "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } }