Listar pedidos

curl -G https://{loja}.com.br/api/hunter/v1/pedidos \
  --data-urlencode "limit=100" \
  -H "X-API-Key: hk_..."

curl -G https://{loja}.com.br/api/hunter/v1/pedidos \
  --data-urlencode "updated_since=2026-07-13T14:00:00Z" \
  --data-urlencode "limit=100" \
  -H "X-API-Key: hk_..."

{
  "codigo": "PED-000123",
  "status": "pagamento_aprovado",
  "criado_em": "2026-07-13T09:15:00Z",
  "atualizado_em": "2026-07-13T09:20:00Z",
  "hunter_processado_em": null,
  "pago_em": "2026-07-13T09:20:00Z",
  "total": 179.80,
  "subtotal": 159.80,
  "frete": 20.00,
  "desconto": 0.00,
  "cupom_codigo": null,
  "forma_pagamento": "pix",
  "cliente": {
    "tipo_pessoa": "fisica",
    "nome": "João da Silva",
    "email": "joao@exemplo.com",
    "telefone": "35999999999",
    "cpf": "12345678909",
    "cnpj": null,
    "razao_social": null,
    "inscricao_estadual": null
  },
  "endereco_entrega": {
    "razao_social": null,
    "cep": "35000000",
    "logradouro": "Rua Exemplo",
    "numero": "123",
    "complemento": "Apto 45",
    "bairro": "Centro",
    "cidade": "Cidade Exemplo",
    "uf": "MG"
  },
  "itens": [
    {
      "variante_hunter_id": "VAR-001",
      "sku": "SKU-001-P-PT",
      "produto_nome": "Produto Exemplo A",
      "variante_descricao": "P PRETO",
      "quantidade": 2,
      "preco_unitario": 89.90,
      "subtotal_item": 179.80
    }
  ],
  "rastreio": null,
  "cancelamento": null
}

{
  "codigo": "PED-000124",
  "status": "enviado",
  "atualizado_em": "2026-07-15T14:00:00Z",
  "hunter_processado_em": "2026-07-14T10:00:00Z",
  "rastreio": {
    "codigo": "AA123456789BR",
    "transportadora": "Correios PAC",
    "url": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR"
  },
  "cancelamento": null
}

{
  "codigo": "PED-000125",
  "status": "cancelado",
  "atualizado_em": "2026-07-13T09:00:00Z",
  "hunter_processado_em": null,
  "rastreio": null,
  "cancelamento": {
    "cancelado_em": "2026-07-13T09:00:00Z",
    "motivo": "Cliente solicitou cancelamento antes do pagamento."
  }
}

{
  "cliente": {
    "tipo_pessoa": "juridica",
    "nome": "Boutique Exemplo",
    "email": "compras@boutiqueexemplo.com.br",
    "telefone": "1133334444",
    "cpf": null,
    "cnpj": "11222333000181",
    "razao_social": "BOUTIQUE EXEMPLO COMÉRCIO LTDA",
    "inscricao_estadual": "1234567890"
  },
  "endereco_entrega": {
    "razao_social": "BOUTIQUE EXEMPLO COMÉRCIO LTDA",
    "cep": "01310000",
    "logradouro": "Av. Paulista",
    "numero": "1000",
    "complemento": null,
    "bairro": "Bela Vista",
    "cidade": "São Paulo",
    "uf": "SP"
  }
}

GET

api

hunter

pedidos

curl -G https://{loja}.com.br/api/hunter/v1/pedidos \
  --data-urlencode "limit=100" \
  -H "X-API-Key: hk_..."

curl -G https://{loja}.com.br/api/hunter/v1/pedidos \
  --data-urlencode "updated_since=2026-07-13T14:00:00Z" \
  --data-urlencode "limit=100" \
  -H "X-API-Key: hk_..."

{
  "codigo": "PED-000123",
  "status": "pagamento_aprovado",
  "criado_em": "2026-07-13T09:15:00Z",
  "atualizado_em": "2026-07-13T09:20:00Z",
  "hunter_processado_em": null,
  "pago_em": "2026-07-13T09:20:00Z",
  "total": 179.80,
  "subtotal": 159.80,
  "frete": 20.00,
  "desconto": 0.00,
  "cupom_codigo": null,
  "forma_pagamento": "pix",
  "cliente": {
    "tipo_pessoa": "fisica",
    "nome": "João da Silva",
    "email": "joao@exemplo.com",
    "telefone": "35999999999",
    "cpf": "12345678909",
    "cnpj": null,
    "razao_social": null,
    "inscricao_estadual": null
  },
  "endereco_entrega": {
    "razao_social": null,
    "cep": "35000000",
    "logradouro": "Rua Exemplo",
    "numero": "123",
    "complemento": "Apto 45",
    "bairro": "Centro",
    "cidade": "Cidade Exemplo",
    "uf": "MG"
  },
  "itens": [
    {
      "variante_hunter_id": "VAR-001",
      "sku": "SKU-001-P-PT",
      "produto_nome": "Produto Exemplo A",
      "variante_descricao": "P PRETO",
      "quantidade": 2,
      "preco_unitario": 89.90,
      "subtotal_item": 179.80
    }
  ],
  "rastreio": null,
  "cancelamento": null
}

{
  "codigo": "PED-000124",
  "status": "enviado",
  "atualizado_em": "2026-07-15T14:00:00Z",
  "hunter_processado_em": "2026-07-14T10:00:00Z",
  "rastreio": {
    "codigo": "AA123456789BR",
    "transportadora": "Correios PAC",
    "url": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR"
  },
  "cancelamento": null
}

{
  "codigo": "PED-000125",
  "status": "cancelado",
  "atualizado_em": "2026-07-13T09:00:00Z",
  "hunter_processado_em": null,
  "rastreio": null,
  "cancelamento": {
    "cancelado_em": "2026-07-13T09:00:00Z",
    "motivo": "Cliente solicitou cancelamento antes do pagamento."
  }
}

{
  "cliente": {
    "tipo_pessoa": "juridica",
    "nome": "Boutique Exemplo",
    "email": "compras@boutiqueexemplo.com.br",
    "telefone": "1133334444",
    "cpf": null,
    "cnpj": "11222333000181",
    "razao_social": "BOUTIQUE EXEMPLO COMÉRCIO LTDA",
    "inscricao_estadual": "1234567890"
  },
  "endereco_entrega": {
    "razao_social": "BOUTIQUE EXEMPLO COMÉRCIO LTDA",
    "cep": "01310000",
    "logradouro": "Av. Paulista",
    "numero": "1000",
    "complemento": null,
    "bairro": "Bela Vista",
    "cidade": "São Paulo",
    "uf": "SP"
  }
}

Comportamento

Retorna pedidos que o integrador deve processar ou reconhecer. Modelo pull cursor-based: você consulta periodicamente com um cursor (updated_since) e recebe as mudanças em ordem cronológica.

Filtros implícitos (sem override)

status IN ('pagamento_aprovado', 'em_separacao', 'enviado', 'entregue', 'cancelado')
Pedido tem pelo menos 1 item cuja variante tem hunter_id preenchido (filtro em cascata — evita mostrar pedidos que o integrador não sabe processar)

Dentro do pedido, só os itens com hunter_id aparecem (filtro em cascata). Se pedido tem 5 itens mas só 3 têm variante do integrador, o response traz apenas os 3.

Query params

string (ISO 8601 UTC)

Retorna pedidos com atualizado_em > updated_since. Sem este parâmetro no primeiro pull, retorna tudo (respeitando limit).

integer

default:"50"

Máx 200 por request.

Ordenação

atualizado_em ASC — cursor incremental. O último pedido do response tem o maior atualizado_em; use-o como próximo updated_since.

Payload de cada pedido

string

required

Código público do pedido (ex: PED-000123). Use nas rotas /processado e /rastreio.

string

required

Um de: pagamento_aprovado, em_separacao, enviado, entregue, cancelado.

string (ISO 8601 UTC)

required

string (ISO 8601 UTC)

required

Cursor pro próximo pull. Guarde o valor do último pedido retornado.

string | null

required

Timestamp de quando o integrador chamou POST /processado. null se ainda não processou. Use pra ignorar replays — se preenchido, você já processou este pedido em algum pull anterior.

number

required

number

required

number

required

number

required

string | null

required

Um de: pix, boleto, cartao. Nunca inclui dados de cartão (número, CVV, bandeira).

object

required

Dados fiscais do cliente. Discrimina PF/PJ.

Show cliente

string

required

fisica ou juridica. Sempre presente, nunca null.

string

required

Nome completo (PF) ou nome fantasia (PJ).

string

required

string | null

Preenchido apenas quando tipo_pessoa='fisica'. Sempre null em PJ.

string | null

Preenchido apenas quando tipo_pessoa='juridica'. Sempre null em PF.

Obrigatório quando PJ, null em PF.

string | null

Opcional (null = isento/MEI). Sempre null em PF.

object | null

required

Show endereco_entrega

Snapshot da razão social do cliente PJ no momento do pedido. Imutável. null em PF ou se cliente era PF na compra.

string

required

string

required

string

required

string | null

string

required

string

required

string (2 chars)

required

array

required

Apenas itens com variante.hunter_id preenchido.

Show itens[]

string

required

string

required

string

required

string

required

integer

required

number

required

number

required

object | null

required

Preenchido apenas quando status IN ('enviado', 'entregue') E existe código de rastreio.

Show rastreio

string

required

string

required

string | null

object | null

required

Preenchido apenas quando status='cancelado'.

Show cancelamento

string (ISO 8601 UTC)

required

string | null

null em cancelamentos automáticos (ex: expiração de reserva de estoque).

Discriminação por status

Como usar o campo status + hunter_processado_em no lado do integrador:

status	hunter_processado_em	Ação sugerida
`pagamento_aprovado`	`null`	Processar: baixa estoque + emite NF + `POST /processado`
`pagamento_aprovado`	`!= null`	Ignorar (replay — já processou)
`em_separacao`	`!= null`	Aguardar postagem física; quando postar, `POST /rastreio`
`enviado`	`!= null`	Ignorar (fim do fluxo pro integrador)
`entregue`	`!= null`	Ignorar (fim do fluxo)
`cancelado`	qualquer	Se pedido está na base do integrador, cancela do lado dele. Se não, ignora.

curl -G https://{loja}.com.br/api/hunter/v1/pedidos \
  --data-urlencode "limit=100" \
  -H "X-API-Key: hk_..."

curl -G https://{loja}.com.br/api/hunter/v1/pedidos \
  --data-urlencode "updated_since=2026-07-13T14:00:00Z" \
  --data-urlencode "limit=100" \
  -H "X-API-Key: hk_..."

{
  "codigo": "PED-000123",
  "status": "pagamento_aprovado",
  "criado_em": "2026-07-13T09:15:00Z",
  "atualizado_em": "2026-07-13T09:20:00Z",
  "hunter_processado_em": null,
  "pago_em": "2026-07-13T09:20:00Z",
  "total": 179.80,
  "subtotal": 159.80,
  "frete": 20.00,
  "desconto": 0.00,
  "cupom_codigo": null,
  "forma_pagamento": "pix",
  "cliente": {
    "tipo_pessoa": "fisica",
    "nome": "João da Silva",
    "email": "joao@exemplo.com",
    "telefone": "35999999999",
    "cpf": "12345678909",
    "cnpj": null,
    "razao_social": null,
    "inscricao_estadual": null
  },
  "endereco_entrega": {
    "razao_social": null,
    "cep": "35000000",
    "logradouro": "Rua Exemplo",
    "numero": "123",
    "complemento": "Apto 45",
    "bairro": "Centro",
    "cidade": "Cidade Exemplo",
    "uf": "MG"
  },
  "itens": [
    {
      "variante_hunter_id": "VAR-001",
      "sku": "SKU-001-P-PT",
      "produto_nome": "Produto Exemplo A",
      "variante_descricao": "P PRETO",
      "quantidade": 2,
      "preco_unitario": 89.90,
      "subtotal_item": 179.80
    }
  ],
  "rastreio": null,
  "cancelamento": null
}

{
  "codigo": "PED-000124",
  "status": "enviado",
  "atualizado_em": "2026-07-15T14:00:00Z",
  "hunter_processado_em": "2026-07-14T10:00:00Z",
  "rastreio": {
    "codigo": "AA123456789BR",
    "transportadora": "Correios PAC",
    "url": "https://rastreamento.correios.com.br/app/index.php?objetos=AA123456789BR"
  },
  "cancelamento": null
}

{
  "codigo": "PED-000125",
  "status": "cancelado",
  "atualizado_em": "2026-07-13T09:00:00Z",
  "hunter_processado_em": null,
  "rastreio": null,
  "cancelamento": {
    "cancelado_em": "2026-07-13T09:00:00Z",
    "motivo": "Cliente solicitou cancelamento antes do pagamento."
  }
}

{
  "cliente": {
    "tipo_pessoa": "juridica",
    "nome": "Boutique Exemplo",
    "email": "compras@boutiqueexemplo.com.br",
    "telefone": "1133334444",
    "cpf": null,
    "cnpj": "11222333000181",
    "razao_social": "BOUTIQUE EXEMPLO COMÉRCIO LTDA",
    "inscricao_estadual": "1234567890"
  },
  "endereco_entrega": {
    "razao_social": "BOUTIQUE EXEMPLO COMÉRCIO LTDA",
    "cep": "01310000",
    "logradouro": "Av. Paulista",
    "numero": "1000",
    "complemento": null,
    "bairro": "Bela Vista",
    "cidade": "São Paulo",
    "uf": "SP"
  }
}

Paginação com cursor

Não use page — use updated_since como cursor incremental:

async function pullIncremental() {
  let cursor = getSavedCursor(); // guardado localmente entre execuções
  const params = new URLSearchParams({ limit: "200" });
  if (cursor) params.set("updated_since", cursor);

  const res = await fetch(`${BASE_URL}/pedidos?${params}`, {
    headers: { "X-API-Key": API_KEY },
  });
  const { data } = await res.json();

  for (const pedido of data.pedidos) {
    await processarPedido(pedido);
    cursor = pedido.atualizado_em; // avança cursor
  }

  saveCursor(cursor);

  // Se veio `tem_mais: true`, chame de novo sem esperar o próximo tick
  if (data.paginacao.tem_mais) return pullIncremental();
}

Regras adicionais

forma_pagamento é sempre "pix" | "boleto" | "cartao". Nunca inclui dados sensíveis.
endereco_entrega.razao_social (quando presente) deve ser usado como destinatário principal da etiqueta postal, com A/C: {destinatario_do_endereco} como complemento.
Se pedido.hunter_processado_em está preenchido e você recebeu o pedido de novo, é replay — ignore.

Começando

Guias

Produtos

Variantes

Estoque

Preços

Pedidos

Comportamento

Filtros implícitos (sem override)

Query params

Ordenação

Payload de cada pedido

Discriminação por status

Paginação com cursor

Regras adicionais

​Comportamento

​Filtros implícitos (sem override)

​Query params

​Ordenação

​Payload de cada pedido

​Discriminação por status

​Paginação com cursor

​Regras adicionais

Comportamento

Filtros implícitos (sem override)

Query params

Ordenação

Payload de cada pedido

Discriminação por status

Paginação com cursor

Regras adicionais