VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Hub de marketplaces do seller

Pedidos do canal

Lista e consulta os pedidos que chegaram dos marketplaces, pede nova busca de pedidos e baixa a etiqueta de envio.

Quando um cliente compra no marketplace, o Hub traz o pedido para a loja e o transforma num pedido comum, com o vínculo entre os dois (o "link": id do pedido no canal, número do pedido na loja, nota fiscal, etiqueta e rastreio). Estas rotas mostram esses vínculos. Um vínculo pode existir sem pedido na loja ainda: a busca recebeu o pedido do canal mas a criação local falhou ou está pendente, e a lista mostra create_state e create_error para você agir.

Listar pedidos

GET/api/v1/vendor/markethub/ordersSeller

Lista os pedidos vindos dos canais, nas contas do seller

Parâmetros de consulta

accountuuid
Só pedidos desta conta.
statusstring
Uma letra filtra pela situação do pedido na loja (O pending, P processing, A paid, S shipped, C completed, I cancelled, R refunded, H on_hold, Z chargeback, B backordered, F failed, D voided). Qualquer outro texto filtra pela situação do pedido no canal (ext_status).
ext_order_idstring
Id exato do pedido no canal.
documentstring
CPF (11 dígitos) ou CNPJ (14 dígitos) do comprador. A lista não devolve o documento; ele só filtra.
invoice_neededstring
1
1 traz só pedidos que ainda precisam de nota fiscal.
shippablestring
1
1 traz só pedidos prontos para despachar.
missingstring
1
1 traz só vínculos que ainda não viraram pedido na loja.
fromstring
Data inicial, AAAA-MM-DD.
untilstring
Data final, AAAA-MM-DD. Inclusive: o dia inteiro entra.
exportstring
1
1 pede a lista para exportação: os nomes de cliente e as mensagens de erro saem mascarados.
pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 25
Itens por página, de 1 a 100. Fora disso volta a 25.
200Pedidos do canal
json
{
  "orders": [
    {
      "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
      "account_id": "e4648fc4-dd0d-45cd-9eaf-4fad48de4a78",
      "marketplace": "mercadolivre",
      "account_name": "Mercado Livre (produção)",
      "ext_order_id": "2000008812345678",
      "order_number": "PEDIDO-20261011-0001",
      "ext_status": "paid",
      "local_status": "processing",
      "local_letter": "P",
      "total_cents": 129900,
      "customer_name": "Maria Souza",
      "items_count": 1,
      "invoice_needed": true,
      "invoice_key": null,
      "invoice_uploaded_at": null,
      "tracking_number": null,
      "label_fetched_at": null,
      "shipped_at": null,
      "is_b2b": false,
      "purchase_order": null,
      "fulfillment": "seller",
      "created_at": "2026-10-11T20:00:00Z",
      "updated_at": "2026-10-11T20:05:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 25
}

Campos da resposta

ordersarray
Pedidos da página. [] quando não há nenhum.
totalinteger
Total que casa com os filtros.
pageinteger
Página devolvida.
per_pageinteger
Tamanho aplicado.
orders[].order_iduuid
Pedido na loja. Ausente enquanto o vínculo não virou pedido.
orders[].account_iduuid
Conta do canal.
orders[].marketplacestring
Canal.
orders[].account_namestring
Nome da conta.
orders[].ext_order_idstring
Id do pedido no canal.
orders[].order_numberstring
Número do pedido na loja.
orders[].ext_statusstring
Situação do pedido no canal, com o vocabulário dele.
orders[].local_statusstring
Situação do pedido na loja, por extenso (pending, processing, paid...).
orders[].local_letterstring
Mesma situação, em letra.
orders[].total_centsinteger
Total do pedido, em centavos.
orders[].customer_namestring
Nome do comprador.
orders[].items_countinteger
Quantidade de itens.
orders[].invoice_neededboolean
Se falta enviar a nota fiscal ao canal.
orders[].invoice_keystring
Chave de acesso da NF-e enviada, quando há.
orders[].invoice_uploaded_atstring
Quando a nota foi enviada ao canal.
orders[].invoice_statestring
Situação do envio da nota, quando o canal a controla.
orders[].tracking_numberstring
Código de rastreio.
orders[].label_fetched_atstring
Quando a etiqueta foi baixada.
orders[].shipped_atstring
Quando foi despachado.
orders[].is_b2bboolean
Se é pedido de empresa.
orders[].purchase_orderstring
Pedido de compra do cliente empresa, quando há.
orders[].fulfillmentstring
Quem entrega, conforme o canal (por exemplo, o seller ou o próprio canal).
orders[].create_statestring
Estado da criação do pedido na loja a partir do vínculo.
orders[].create_errorstring
Motivo, quando a criação falhou.
orders[].create_attemptsinteger
Tentativas de criação.
orders[].money_pending_centsinteger
Valor ainda pendente de liquidação, em centavos, quando há.
orders[].created_atstring
Quando o vínculo nasceu (RFC 3339).
orders[].updated_atstring
Última alteração.

Detalhe de um pedido

GET/api/v1/vendor/markethub/orders/detailSeller

Detalhe de um pedido do canal, com pacotes e jobs

Abre um vínculo, mesmo o que ainda não virou pedido na loja. Traz os pacotes (um pedido pode ser dividido em mais de um envio) e os jobs recentes dele. Os dois parâmetros são obrigatórios.

Parâmetros de consulta

accountuuidobrigatório
Conta do canal.
ext_order_idstringobrigatório
Id do pedido no canal.
200Detalhe
json
{
  "order": { "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f", "ext_order_id": "2000008812345678", "ext_status": "paid", "total_cents": 129900 },
  "packages": [
    { "package_number": "PKG-1", "items": [{ "item_id": "MLB123456789", "qty": 1 }] }
  ],
  "jobs": []
}

Campos da resposta

orderobject
O pedido, com os mesmos campos de um item da lista.
packagesarray
Pacotes do pedido no canal. Lista vazia quando o canal não divide.
packages[].package_numberstring
Número do pacote no canal.
packages[].itemsarray
Itens do pacote: item_id, qty e, conforme o canal, model_id, order_item_id.
jobsarray
Jobs recentes deste pedido, no formato da fila da conta.

Pedir nova busca de um período

POST/api/v1/vendor/markethub/orders/pullSeller

Enfileira a busca de pedidos de um período

Pede ao Hub que busque no canal os pedidos de um período, por exemplo quando um webhook se perdeu. Só enfileira: não chama o canal agora. A resposta traz o job criado; consulte-o até virar S. Só contas em sandbox ou em execução seca aceitam este pedido manual; numa conta de produção a busca é feita pela plataforma sozinha.

Corpo da requisição

account_iduuidobrigatório
Conta do canal.
fromstringobrigatório
Início, AAAA-MM-DD. Não pode ser mais antigo que 90 dias.
untilstringobrigatório
Fim, AAAA-MM-DD, inclusive. A janela inteira pode ter no máximo 15 dias e o fim no máximo 48 horas adiante.
200Busca enfileirada
json
{
  "job": {
    "id": 4830,
    "account_id": "e4648fc4-dd0d-45cd-9eaf-4fad48de4a78",
    "kind": "order_pull",
    "status": "P",
    "attempts": 0,
    "run_after": "2026-10-11T22:10:00Z",
    "created_at": "2026-10-11T22:10:00Z"
  },
  "done": false
}

Campos da resposta

jobobject
O job criado, no formato da fila da conta.
doneboolean
true só quando o job já terminou com sucesso. Recém-criado, é false.

Pedir nova busca de pedidos específicos

POST/api/v1/vendor/markethub/orders/retrySeller

Enfileira nova busca de pedidos do canal

Para pedidos que chegaram com erro (create_error), enfileira uma nova leitura de cada um no canal. Mesmas regras de conta do pull: só sandbox ou execução seca.

Corpo da requisição

linksarrayobrigatório
De 1 a 50 pedidos a buscar de novo.
links[].account_iduuidobrigatório
Conta do canal.
links[].ext_order_idstringobrigatório
Id do pedido no canal.
200Buscas enfileiradas
json
{
  "jobs": [
    { "id": 4831, "account_id": "e4648fc4-dd0d-45cd-9eaf-4fad48de4a78", "kind": "order_fetch", "status": "P", "attempts": 0 }
  ],
  "done": false
}

Baixar a etiqueta de envio

GET/api/v1/vendor/markethub/orders/{orderID}/labelSeller

Baixa a etiqueta de envio do pedido

Devolve o arquivo da etiqueta, não JSON: application/pdf (padrão) ou texto text/plain quando o formato é ZPL (impressoras térmicas). Se a etiqueta já foi baixada antes, vem da cópia guardada; se não, é buscada no canal e guardada. orderID é o order_id do pedido na loja.

Parâmetros de caminho

orderIDuuidobrigatório
Id do pedido na loja (order_id da lista).

Parâmetros de consulta

formatstring
pdfzpl
Formato desejado, se o canal oferece mais de um.

Exemplo de requisição

bash
# pedidos pagos dos últimos dias
curl "$BASE_URL/api/v1/vendor/markethub/orders?status=P&from=2026-10-08&until=2026-10-11" \
  -H "Authorization: Bearer $TOKEN"

# etiqueta em PDF
curl "$BASE_URL/api/v1/vendor/markethub/orders/$ORDER_ID/label?format=pdf" \
  -H "Authorization: Bearer $TOKEN" -o etiqueta.pdf

Erros

StatusQuandoCorpo de exemplo
400from ou until fora do formato AAAA-MM-DD.{"error":"invalid from","detail":"data em formato não aceito: \"bad\". ..."}
400detail sem account ou ext_order_id.{"error":"failed to load order","detail":"markethub: invalid input"}
400pull: janela inválida (vazia, maior que 15 dias, início com mais de 90 dias, fim a mais de 48 horas) ou conta de produção.{"error":"failed to queue order pull","detail":"markethub: invalid input"}
400retry: lista vazia, com mais de 50 itens, item sem campos ou conta de produção.{"error":"failed to queue retry","detail":"markethub: invalid input"}
401Sem token.{"error":"authentication required"}
403Módulo desligado.{"error":"module_disabled","module":"marketplace-hub"}
404Pedido ou conta de outro seller, ou inexistente.{"error":"failed to load order","detail":"markethub: order not found"}
409Conta desligada (pull e retry).{"error":"failed to queue order pull","detail":"..."}
500Id que não é UUID, ou etiqueta de pedido sem vínculo com o canal.{"error":"failed to get label","detail":"sql: no rows in result set"}
A mensagem de data é enganosa

O texto do erro de data pede "RFC 3339 com hora e fuso", mas as rotas de pedidos do Hub aceitam e esperam AAAA-MM-DD. Se você mandar 2026-10-11T00:00:00Z, recebe 400.

Etiqueta de pedido que não existe responde 500

Um orderID que não tem vínculo com um canal volta 500, não 404. Use sempre o order_id que veio da lista de pedidos do Hub.

Acompanhe o job

pull e retry só enfileiram. Consulte os jobs da conta com kind=order_pull ou order_fetch até a situação virar S. done: true só aparece quando o job já terminou.

Verificado em parte

A loja de testes não tem pedidos de marketplace, então as respostas de pedido, detalhe, busca e etiqueta são exemplos montados a partir do código. Os erros de validação foram chamados ao vivo.

Veja também

  • Contas, jobs e categorias
  • Pedidos do seller
  • Visão geral
Anterior
Prévia e publicação
Próxima
Webhooks de integração
Nesta página
  • Listar pedidos
  • Detalhe de um pedido
  • Pedir nova busca de um período
  • Pedir nova busca de pedidos específicos
  • Baixar a etiqueta de envio
  • Exemplo de requisição
  • Erros
  • Veja também