Pedidu API

Uma referência única para as duas integrações do Pedidu: a API de Pedidos (delivery / retirada, via webhook) e a API de Mesas (salão, REST somente-leitura). Escolha abaixo por onde começar.

Visão geral

O Pedidu expõe duas APIs, com propósitos e modelos diferentes:

Introdução

A integração de pedidos do Pedidu funciona via webhook (push): você não precisa ficar consultando a API atrás de pedidos novos — o Pedidu te avisa. Assim que um pedido muda de estado, o Pedidu faz uma requisição POST para a URL do seu sistema com o objeto inteiro do pedido em JSON.

É o mesmo modelo usado por roteirizadores e integradores (ex.: Agilizone, Husky): o Pedidu é a origem do pedido e empurra os dados pra fora.

Como funciona

1. O cliente faz um pedido no seu cardápio digital, PDV, balcão ou marketplace (iFood/99Food).
2. O lojista aceita / o pedido muda de status (entra em produção, sai pra entrega, é cancelado…).
3. O Pedidu monta o objeto do pedido e faz POST na sua webhookApi.
4. Seu sistema recebe o JSON { type, order } e processa (cria a entrega, imprime, dá baixa, etc.).

Configuração do webhook

A URL de destino é configurada por loja. No painel do Pedidu (gestor), o campo webhookApi recebe a URL completa (com https://) do seu endpoint. Enquanto estiver vazio ou inválido, nenhum disparo é feito.

A requisição (POST)

O Pedidu sempre envia uma requisição com este formato:

Cabeçalhos e corpo:

POST /webhook/pedidu HTTP/1.1
Host: seu-sistema.com
Content-Type: application/json

{
  "type": "order.updated",
  "order": { ... objeto completo do pedido ... }
}

O corpo tem sempre dois campos no topo:

Eventos (type)

O campo type indica o que aconteceu com o pedido:

Entrega & reenvio

• O disparo é best-effort: o Pedidu envia e segue o fluxo, sem travar a operação da loja se o seu endpoint falhar.
• Trate seu handler como idempotente: o mesmo pedido (mesmo order.id / order.id_order) pode chegar mais de uma vez conforme muda de status.
• Use order.id (id interno) ou order.id_order (número público) como chave de deduplicação.

Objeto order

O order carrega o pedido inteiro. Abaixo, os campos agrupados por tema. A tabela consolidada de todos os campos está em Tabela de campos.

Identificação

Itens & valores

Datas

Itens do pedido

O campo purchase é um array JSON (codificado como string) com um objeto por item. Cada item tem produto, quantidade, adicionais e observação:

[
  {
    "product_id": 20,          // id do produto
    "product_quantity": 2,     // quantidade
    "product_optional": "Sem cebola",  // observação do cliente (ou null)
    "additional": [            // adicionais / opcionais escolhidos
      {
        "name": "Bacon extra",
        "price": 5.00,
        "qty": 1,
        "hight_price": "no"   // "yes" = preço do item vem do adicional (ex.: tamanho)
      }
    ]
  }
]

Cliente & endereço

O order referencia o cliente por id_user. O card completo (como aparece na comanda) resolve esses dados na base de clientes da loja. Os campos do cliente são:

Forma de pagamento

O campo payment_option define a forma de pagamento:

Forma de entrega

O campo delivery_option define como o cliente recebe o pedido:

Pedido agendado

Um pedido é agendado quando o cliente escolhe data/horário para receber. Identifique pela presença dos campos abaixo:

Status do pedido

O campo status indica o estado atual do pedido:

Origem / canal

O campo type do order indica de qual canal o pedido veio:

Totais & descontos

O total do pedido é composto assim:

total = product_price
      + delivery_price        (se delivery_option == 1)
      + manual_addition
      − manual_discount
      − cashback_discount
      − desconto do cupom     (se payment_coupon_id != 0)

Exemplo completo

Um pedido de delivery, pago em dinheiro com troco, não agendado:

{
  "type": "order.updated",
  "order": {
    "id": 83,
    "id_order": "1781804869",
    "num_order": 42,
    "pin_order": "506867",
    "id_user": 1,
    "type": "cardapio",
    "status": "preparation",

    "delivery_option": "1",
    "delivery_price": "7.00",
    "delivery_time": null,
    "delivery_motoboy_id": null,
    "car_board": "0",
    "table_number": 0,

    "payment_option": "money",
    "payment_moneyback": "150.00",
    "payment_card_id": 0,
    "payment_coupon_id": 0,
    "online_payment_fee": "0.00",

    "product_price": "108.00",
    "subtotal_value": "108.00",
    "manual_addition": "0.00",
    "manual_discount": "0.00",
    "cashback_discount": "0.00",

    "agendamented_date": null,
    "agendamented_hours": null,
    "order_note": "Apertar a campainha",

    "purchase": "[{\"product_id\":20,\"product_quantity\":2,\"product_optional\":\"Sem cebola\",\"additional\":[{\"name\":\"Bacon extra\",\"price\":5,\"qty\":1,\"hight_price\":\"no\"}]}]",

    "created_at": "2026-06-18 14:47:49",
    "accepted_at": "2026-06-18 14:47:51",
    "updated_at": "2026-06-18 14:50:02"
  }
}

Tabela de campos (referência)

Todos os campos do objeto order:

Introdução

Diferente da API de pedidos do delivery (que é push, via webhook), a API de Mesas é pull: o seu sistema consulta quando quiser. Você faz uma requisição GET autenticada e recebe os dados das mesas em JSON.

São três endpoints, todos sob o prefixo /api/v1/mesas:

• GET /summary — números fechados do período (dashboard).
• GET /sessions — a lista de aberturas de mesa (uma por sessão).
• GET /sessions/{id} — o detalhe completo de uma sessão (comandas, itens, pagamentos).

Autenticação (token)

Toda requisição precisa do Token de API da sua loja, enviado no cabeçalho Authorization no formato Bearer. É o mesmo token usado na API de pedidos (delivery/retirada), configurado em Configurações → Integrações no gestor.

Authorization: Bearer SEU_TOKEN_DE_API

Exemplo com curl:

curl -s https://SUA-LOJA.com.br/api/v1/mesas/summary \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"

Por compatibilidade, o token também é aceito no cabeçalho cru token: SEU_TOKEN, mas o Bearer é o recomendado. Nunca passe o token pela URL (query string) — ele vazaria em logs e histórico.

URL base & formato

• Respostas em JSON (UTF-8, acentos preservados).
• Datas em ISO 8601 com fuso, ex.: 2026-05-29T19:21:10-03:00.
• Valores monetários em reais, com 2 casas (número, não string): 46.44.
• Todo corpo de sucesso traz "ok": true; erros trazem "ok": false e "error".

Resumo do período GET

Os números fechados de um intervalo — ideal para um card/dashboard no seu financeiro.

Parâmetros (query)

O período filtra pela abertura da mesa (opened_at): uma sessão aberta no intervalo entra no resumo com todo o seu consumo e pagamento.

{
  "ok": true,
  "period": { "from": "2026-05-01T00:00:00-03:00", "to": "2026-05-31T23:59:59-03:00" },
  "sessions_opened": 86,      // mesas abertas no período (cada abertura conta)
  "sessions_closed": 81,      // dessas, quantas já foram fechadas
  "sessions_open_now": 5,     // ainda abertas
  "distinct_tables": 29,      // mesas físicas distintas usadas
  "items_sold": 518,          // itens vendidos (soma das quantidades, exclui cancelados)
  "items_gross": 237565.38,   // soma dos itens (price x quantity) — NÃO é o pago
  "revenue_paid": 250451.26,  // valor efetivamente pago (líquido de troco)
  "avg_ticket": 3091.99,      // revenue_paid / sessions_closed
  "by_payment_method": [
    { "method": "money",  "gross": 2624.00, "change_back": 1146.53, "net": 1477.47, "count": 10 },
    { "method": "pix",    "gross": 2482.25, "change_back": 0,       "net": 2482.25, "count": 14 },
    { "method": "credit", "gross": 241523.00, "change_back": 0,     "net": 241523.00, "count": 18 },
    { "method": "debit",  "gross": 4867.24, "change_back": 0,       "net": 4867.24, "count": 45 }
  ],
  "extras": { "increase": 101.30, "discount": 0, "tip": 0 }
}

Listar sessões GET

A lista de aberturas de mesa no período, paginada, cada uma com seus totais e o cliente.

Parâmetros (query)

{
  "ok": true,
  "period": { "from": "2026-05-01T00:00:00-03:00", "to": "2026-06-30T23:59:59-03:00" },
  "total": 86,
  "page": 1,
  "per_page": 2,
  "total_pages": 43,
  "sessions": [
    {
      "session_id": 87,          // id da ABERTURA (único) — use no /sessions/{id}
      "table_number": 10,        // número da mesa física (pode repetir no dia)
      "label": "Joao",           // rótulo/nome digitado na mesa
      "status": "open",          // open | closed
      "opened_at": "2026-06-20T15:28:05-03:00",
      "closed_at": null,
      "duration_min": null,
      "customer": { "name": "Joao da Silva", "phone": "12991251886" },
      "items_count": 3,
      "comandas_count": 3,
      "items_gross": 42.00,
      "total_paid": 0
    }
  ]
}

Detalhe da sessão GET

Tudo de uma sessão: cabeçalho + cliente, comandas agrupadas, cada item (com adicionais e observação) e todos os pagamentos com troco.

{
  "ok": true,
  "session_id": 81,
  "table_number": 5,
  "label": "",
  "status": "closed",
  "opened_at": "2026-05-29T19:21:10-03:00",
  "closed_at": "2026-05-31T04:33:30-03:00",
  "duration_min": 1992,
  "customer": { "name": null, "phone": null },
  "items_count": 6,
  "comandas_count": 3,
  "items_gross": 43.00,
  "total_paid": 46.44,
  "by_payment_method": [
    { "method": "credit", "gross": 46.44, "change_back": 0, "net": 46.44, "count": 1 }
  ],
  "extras": { "increase": 0, "discount": 0, "tip": 0 },
  "comandas": [
    {
      "num_order": 183,           // id da comanda (0 = itens avulsos/não confirmados)
      "total": 8.00,              // total da comanda (exclui cancelados)
      "items": [
        {
          "id": 573,
          "comanda": 183,
          "product_id": 38,
          "name": "FANTA UVA",
          "quantity": 1,
          "unit_price": 8.00,
          "total": 8.00,
          "additionals": null,    // adicionais/complementos (quando houver)
          "note": null,           // observação do item
          "status": "preparando",
          "waiter_id": 1304,      // garçom que lançou o item
          "printed_at": "2026-05-29T20:56:39-03:00",
          "paid_at": null,
          "created_at": "2026-05-29T20:56:33-03:00"
        }
      ]
    }
  ],
  "items": [ /* todos os itens da sessão, na mesma forma de cima */ ],
  "payments": [
    {
      "id": 240,
      "type": "payment",          // payment | increase | discount | tip
      "method": "credit",         // money | pix | credit | debit ...
      "amount": 46.44,
      "change_back": 0,           // troco (só faz sentido em dinheiro)
      "net": 46.44,               // amount - change_back
      "created_at": "2026-05-31T04:33:30-03:00"
    }
  ]
}

Sessão de mesa

No Pedidu, cada abertura de mesa é uma sessão independente, com um session_id único. Quando a mesa é fechada e depois reaberta, nasce uma nova sessão — por isso a mesma table_number aparece várias vezes no mesmo dia. Isso é o comportamento normal do salão.

Comandas & itens

Dentro de uma sessão, os itens são agrupados por comanda (num_order). Uma sessão pode ter várias comandas — por exemplo, uma por rodada ou por garçom. Itens com num_order = 0 são avulsos/não confirmados.

• O total de cada comanda e da sessão exclui itens cancelados (status: "cancelado").
• product_id: 0 é uma linha de couvert / taxa (não é um produto do catálogo) — o name vem como "Couvert / taxa".
• additionals traz os complementos/adicionais do item (quando houver), já decodificados.
• waiter_id é o garçom que lançou o item.

Formas de pagamento

O array payments lista cada lançamento financeiro da mesa. O campo type separa o que é pagamento do que é ajuste:

A quebra em by_payment_method considera apenas type: "payment", agrupado por method. Para cada método:

Dados do cliente

O objeto customer traz o que se sabe do cliente daquela sessão:

Exemplo completo

Buscando o resumo de um dia e depois abrindo uma sessão específica:

# 1) Resumo de um dia
curl -s "https://SUA-LOJA.com.br/api/v1/mesas/summary?date=2026-05-29" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"

# 2) Sessões abertas/fechadas de um intervalo (máx. 92 dias)
curl -s "https://SUA-LOJA.com.br/api/v1/mesas/sessions?from=2026-05-01&to=2026-05-31&status=close&per_page=50" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"

# 3) Detalhe completo de uma sessão
curl -s "https://SUA-LOJA.com.br/api/v1/mesas/sessions/81" \
  -H "Authorization: Bearer SEU_TOKEN_DE_API"

Códigos de erro

Tabela de campos

Objeto session

Objeto item

Objeto payment