API Documentation - Aiqbridge

API de Integracao

O Aiqbridge consome a API V2 do Aiqfome (V1 sera descontinuada em 07/04/2026) e expoe endpoints compativeis com iFood e Open Delivery. Se voce ja integra com uma dessas plataformas, basta apontar para nossos endpoints — sem reescrever seu sistema. Cada loja autoriza o bridge individualmente via OAuth V2 (Magalu ID).

Quick Start

Dois passos para comecar a receber pedidos.

Adicione uma loja e gere seu token

Acesse o painel do Aiqbridge, crie sua conta, adicione a loja que deseja integrar e gere o token JWT.

Faca sua primeira chamada

Envie o token no header Authorization: Bearer <token> e chame qualquer endpoint.

Autenticacao

Cada loja possui seu proprio token JWT, gerado no painel do Aiqbridge. Envie o token no header Authorization de todas as requisicoes:

Authorization: Bearer SEU_TOKEN_JWT

Autorizacao por loja (OAuth V2)

Na API V2 do Aiqfome cada loja autoriza individualmente o bridge. Sem essa autorizacao, qualquer chamada retorna 401.

Autorizar nova loja

Abra o link abaixo no navegador (logado no Magalu ID) para conceder acesso. Apos consentimento, o token JWT da loja fica disponivel no painel.

https://www.aiqbridge.com.br/aiq/oauth/v2/authorize-store/{store_id}

Reauth (token expirado ou revogado)

Endpoints retornam { "requires_reauth": true, "reconnect_url": "..." } quando o token nao funciona mais. O reconnect_url aponta para o mesmo fluxo de autorizacao acima.

{
  "error": "store_not_authorized",
  "requires_reauth": true,
  "reconnect_url": "https://www.aiqbridge.com.br/aiq/oauth/v2/authorize-store/40529"
}

Scopes do token

O JWT do bridge (gerado em /developers) carrega scopes que limitam quais operacoes sao permitidas. Tentar uma operacao fora do scope retorna 403 Forbidden com {"error": "insufficient_scope"}.

Importante: dois conjuntos de scopes

Nao confunda os scopes do JWT do bridge (tabela abaixo, usados nas chamadas /ifood/*, /od/*) com os scopes do OAuth V2 do Aiqfome (com prefixo aqf:, usados so durante a autorizacao da loja).

Scope (JWT bridge)	Permite
`orders:read`	GET pedidos, polling de eventos
`orders:write`	Confirmar, preparar, despachar, entregar, cancelar pedidos
`orders:ack`	POST `/events/acknowledgment`
`catalog:read`	GET cardapio, categorias, items
`catalog:write`	Criar / atualizar items, categorias, modificadores
`merchant:read`	GET dados da loja, horarios, taxas
`merchant:write`	Atualizar status, horarios, taxas, bairros
`webhooks:read`	GET configuracao de webhook
`webhooks:write`	Criar / atualizar / deletar / testar webhook

O scope necessario por endpoint esta documentado em src/infra/auth_middleware.py (mapping REQUIRED_SCOPES_BY_PREFIX + SCOPE_REQUIREMENTS).

Formato de preços

Cada skin segue o protocolo original. Bridge não converte: apenas repassa.

iFood: centavos na leitura (ex: "unitPrice": 2500 = R$ 25,00), reais na escrita do catálogo (ex: "price": {"value": 25.00}). É regra do iFood, replicada aqui.
OpenDelivery: Price object {"value": 25.00, "currency": "BRL"} em todo lugar (leitura e escrita). Regra da spec OD.

Polling (alternativa a webhook)

Se voce nao consegue expor uma URL publica para webhooks, use polling para puxar eventos a cada 30s. Disponivel apenas para Open Delivery. Para iFood, use webhook (a versao iFood do polling nao esta implementada na bridge no momento).

Open Delivery

# Buscar eventos pendentes
curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/events:polling"

# Confirmar recebimento (apos processar)
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id": "EVENT_ID"}]' \
  "https://www.aiqbridge.com.br/od/v1/events/acknowledgment"

Eventos nao confirmados sao reentregues no proximo polling. Confirme apenas apos persistir no seu lado. Detalhes completos em Open Delivery → Eventos.

iFood

Open Delivery

Pedidos

Gerencie o ciclo de vida dos pedidos: consulte, confirme, prepare, despache e entregue.

GET /ifood/order/v1.0/orders/{orderId} Detalhes do pedido ▶

Quando usar: ao receber qualquer evento (webhook ou polling) para obter os detalhes completos do pedido. Sempre busque os detalhes antes de confirmar — o evento traz so o ID.

Retorna o pedido completo no formato iFood (itens, pagamento, endereco).

Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/order/v1.0/orders/abc-123"

Response 200

{
  "id": "132095063",
  "displayId": "132095063",
  "createdAt": "2026-02-12T18:18:42-03:00",
  "preparationStartDateTime": "2026-02-12T18:19:21-03:00",
  "orderType": "DELIVERY",
  "orderTiming": "IMMEDIATE",
  "salesChannel": "AIQFOME",
  "merchant": { "id": "40529", "name": "Pizzaria Exemplo" },
  "customer": {
    "id": "52d2c97b-3d89-4996-9386-003482f8b017",
    "name": "Joao Silva",
    "documentNumber": "",
    "phone": { "number": "44999990000", "localizer": null, "localizerExpiration": null },
    "ordersCountOnMerchant": 3,
    "segmentation": "Cliente"
  },
  "items": [
    {
      "id": "225469144",
      "name": "X-Burger",
      "externalCode": "",
      "unit": "UN",
      "index": 1,
      "unitPrice": 2500,
      "quantity": 1,
      "price": 2500,
      "totalPrice": 2500,
      "optionsPrice": 0,
      "observations": "",
      "imageUrl": "",
      "options": []
    }
  ],
  "total": {
    "subTotal": 2500,
    "deliveryFee": 500,
    "benefits": 0,
    "orderAmount": 3000,
    "additionalFees": 0
  },
  "payments": {
    "prepaid": 0,
    "pending": 3000,
    "methods": [
      { "method": "PIX", "type": "ONLINE", "currency": "BRL", "value": 3000, "prepaid": false }
    ]
  },
  "benefits": [],
  "additionalFees": [],
  "delivery": {
    "mode": "DEFAULT",
    "deliveryAddress": {
      "streetName": "Rua Exemplo",
      "streetNumber": "123",
      "neighborhood": "Centro",
      "complement": "Apto 4",
      "city": "Maringa",
      "state": "PR",
      "postalCode": "87000-000",
      "coordinates": { "latitude": -23.4205, "longitude": -51.9333 }
    },
    "deliveryDateTime": "2026-02-12T18:58:42-03:00"
  },
  "takeout": null,
  "extraInfo": "Sem cebola"
}

POST /ifood/order/v1.0/orders/{orderId}/confirm Confirmar pedido ▶

Quando usar: imediatamente apos receber um pedido novo (evento PLC) e validar que voce consegue prepara-lo. Confirmar dispara CFM para a plataforma cliente.

Aceita o pedido. Equivale a clicar em "Aceitar" no painel.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/order/v1.0/orders/abc-123/confirm"

Response: 202 Accepted

POST /ifood/order/v1.0/orders/{orderId}/startPreparation Iniciar preparo ▶

Quando usar: quando a cozinha comeca a preparar o pedido. Notifica o cliente que o pedido saiu da fila.

Sinaliza que o pedido comecou a ser preparado.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/order/v1.0/orders/abc-123/startPreparation"

Response: 202 Accepted

POST /ifood/order/v1.0/orders/{orderId}/readyToPickup Pronto para retirada ▶

Quando usar: quando o pedido esta pronto e aguardando o entregador (modelo TAKEOUT) ou motoboy.

Marca o pedido como pronto para retirada pelo entregador ou cliente.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/order/v1.0/orders/abc-123/readyToPickup"

Response: 202 Accepted

POST /ifood/order/v1.0/orders/{orderId}/dispatch Despachar pedido ▶

Quando usar: quando o motoboy sai com o pedido para entrega. So faz sentido em modelo de entrega propria do estabelecimento.

Informa que o pedido saiu para entrega.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/order/v1.0/orders/abc-123/dispatch"

Response: 202 Accepted

POST /ifood/order/v1.0/orders/{orderId}/delivered Marcar como entregue ▶

Quando usar: quando o pedido foi efetivamente entregue ao cliente. Estado terminal — encerra o ciclo de vida.

Confirma que o pedido foi entregue ao cliente.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/order/v1.0/orders/abc-123/delivered"

Response: 202 Accepted

POST /ifood/order/v1.0/orders/{orderId}/cancel Cancelar pedido ▶

Quando usar: a qualquer momento antes de delivered. Sempre envie o motivo no body — aparece no historico do cliente.

Body schema

{
  "reason": "string"   // opcional. Default: "Cancelled via iFood"
}

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Cliente desistiu"}' \
  "https://www.aiqbridge.com.br/ifood/order/v1.0/orders/132095063/cancel"

Response: 202 Accepted

Catalogo

Gerencie o cardapio: catalogos, categorias, itens, precos e disponibilidade.

GET /ifood/catalog/v1.0/merchants/{merchantId}/catalogs Listar catalogos ▶

Quando usar: para listar todos os catalogos disponiveis da loja (ex: principal, lanche, jantar). Cada catalogo agrupa categorias e items.

Retorna os catalogos do merchant. Cada merchant possui um catalogo principal.

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/m-456/catalogs"

GET /ifood/catalog/v1.0/merchants/{merchantId}/catalogs/{catalogId} Detalhes do catalogo ▶

Quando usar: para detalhes de um catalogo especifico. Use antes de qualquer mutacao para confirmar o catalogo certo.

Retorna o catalogo com todas as categorias e itens.

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/m-456/catalogs/default"

GET .../{catalogId}/categories Listar categorias ▶

Retorna as categorias. Use ?include_items=true para incluir itens.

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/m-456/catalogs/default/categories?include_items=true"

PUT /ifood/catalog/v1.0/merchants/{merchantId}/items Criar ou atualizar item ▶

Quando usar: para criar/atualizar items em batch. Sobrescreve campos enviados — envie tudo que deve permanecer.

Cria ou atualiza um produto. Se o externalCode ja existir, atualiza.

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"externalCode":"item-100","name":"X-Tudo","description":"Hamburguer completo","price":{"value":32.90}}' \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/m-456/items"

PATCH /ifood/catalog/v1.0/merchants/{merchantId}/items/price Atualizar preco ▶

Quando usar: para ajuste rapido de preco sem reescrever o item inteiro. Preco em reais decimais.

Altera o preco de um item.

curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"itemId":"item-100","price":{"value":29.90}}' \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/m-456/items/price"

PATCH /ifood/catalog/v1.0/merchants/{merchantId}/items/externalCode Atualizar externalCode (SKU) ▶

Quando usar: para sincronizar SKU/codigo interno dos items com seu PDV.

Altera o externalCode (SKU) de um item. O itemId e o UUID do item no Aiqfome.

curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"itemId":"d94896a9-8240-4a8f-9407-d2c6bd745153","externalCode":"MEU-SKU-001"}' \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/m-456/items/externalCode"

PATCH /ifood/catalog/v1.0/merchants/{merchantId}/items/status Atualizar disponibilidade ▶

Quando usar: para pausar item esgotado sem deletar (status UNAVAILABLE) ou reativar (AVAILABLE).

Altera o status (AVAILABLE / UNAVAILABLE) de um ou mais itens.

curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"UNAVAILABLE","items":["item-100","item-101"]}' \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/m-456/items/status"

DELETE /ifood/catalog/v1.0/merchants/{merchantId}/items/{itemId} Remover item ▶

Quando usar: para remover item permanentemente. Para pausar temporariamente, prefira PATCH status com UNAVAILABLE.

Remove um item do cardapio permanentemente.

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/m-456/items/item-100"

Response: 204 No Content

GET /ifood/catalog/v1.0/merchants/{merchantId}/catalogs/{catalogId}/categories Listar categorias do catalogo ▶

Quando usar: para listar todas as categorias do catalogo (Lanches, Bebidas, etc) com seus itens. Use antes de exibir o cardapio agrupado no seu sistema.

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/40529/catalogs/main/categories"

PATCH /ifood/catalog/v1.0/merchants/{merchantId}/products/statuses Batch de status de produtos ▶

Quando usar: para alterar status (AVAILABLE/UNAVAILABLE) de varios produtos de uma vez. Mais eficiente que chamar /items/status individualmente quando voce precisa pausar dezenas de itens.

curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id":"item-1","status":"UNAVAILABLE"},{"id":"item-2","status":"AVAILABLE"}]' \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/40529/products/statuses"

Response: 202 Accepted

PATCH /ifood/catalog/v1.0/merchants/{merchantId}/options/status Status de modificadores (borda, tamanho, adicionais) ▶

Quando usar: para alterar disponibilidade de opcoes/modificadores (borda recheada, tamanho grande, adicional de bacon, etc) sem mexer no item principal. Usado para indicar "borda catupiry esgotou" mantendo a pizza disponivel.

curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id":"opt-borda-catupiry","status":"UNAVAILABLE"}]' \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/40529/options/status"

Response: 202 Accepted

PATCH /ifood/catalog/v1.0/merchants/{merchantId}/options/externalCode SKU dos modificadores ▶

Quando usar: para sincronizar SKU/codigo interno dos modificadores com o seu PDV. Permite que o seu sistema reconheca cada borda/adicional pelo seu proprio codigo.

curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id":"opt-borda-catupiry","externalCode":"BRD-CAT-001"}]' \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/40529/options/externalCode"

Response: 202 Accepted

PATCH /ifood/catalog/v1.0/merchants/{merchantId}/options/price Preco dos modificadores ▶

Quando usar: para ajustar preco de modificadores (ex: aumentar valor da borda recheada). Preco em reais decimais ({ "value": 5.00 }), nao em centavos.

curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id":"opt-borda-catupiry","price":{"value":5.00}}]' \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/40529/options/price"

Response: 202 Accepted

POST /ifood/catalog/v1.0/merchants/{merchantId}/categories Criar categoria ▶

Quando usar: ao adicionar uma nova categoria ao cardapio (ex: "Sobremesas", "Vegetariano"). Items podem ser vinculados depois via PUT items.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sobremesas","externalCode":"CAT-SOB"}' \
  "https://www.aiqbridge.com.br/ifood/catalog/v1.0/merchants/40529/categories"

Response: 201 Created

Loja (Merchant)

Gerencie o status, horarios, taxas de entrega, bairros e metodos de pagamento da loja.

Endpoints exclusivos do Aiqbridge

Estes endpoints nao existem na API real do iFood. Sao funcionalidades do Aiqfome expostas pelo bridge em formato camelCase, com campos internos removidos e precos convertidos para centavos (inteiro). IDs de lojas sao numericos do Aiqfome (nao UUIDs). Endpoints como /neighborhoods, /delivery-fees e /payment-methods sao especificos do Aiqfome.

GET /ifood/merchant/v1.0/merchant Info da loja ▶

Quando usar: para sincronizar dados completos da loja (logo, ratings, horarios, raio) com seu sistema.

Retorna informacoes da loja (nome, status, endereco, etc.).

Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant"

Response 200

Dados da loja mapeados para formato iFood (camelCase, campos internos removidos).

{
  "id": "53191",
  "name": "Pizzaria Exemplo",
  "corporateName": "Pizzaria Exemplo LTDA",
  "preparationTime": 40,
  "deliveryTime": "40 - 60",
  "isDeliveryRadiusActive": false,
  "cityId": 4006,
  "ratings": {
    "average": 4.5,
    "count": 128,
    "details": { "quality": 4.3, "delivery": 4.6, "accuracy": 4.5 }
  },
  "workingHours": [
    { "weekDayNumber": 1, "hours": "08:00 - 22:00", "status": 1 }
  ]
}

POST /ifood/merchant/v1.0/merchant/status Alterar status ▶

Quando usar: para abrir/fechar/standby a loja remotamente. STANDBY pausa novos pedidos sem fechar de fato.

Abre, fecha ou coloca a loja em standby.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"operation":"CLOSE"}' \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant/status"

Valores: OPEN, CLOSE, STANDBY

Response 200

{
  "store_id": 53191,
  "status": "CLOSED"
}

GET /ifood/merchant/v1.0/merchant/hours Horarios ▶

Quando usar: para ler os horarios atuais antes de mostrar/editar no seu painel.

Retorna os horarios de funcionamento configurados.

Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant/hours"

Response 200

[
  { "weekDayNumber": 1, "hours": "08:00 - 22:00", "status": 1 },
  { "weekDayNumber": 2, "hours": "08:00 - 22:00", "status": 1 }
]

PUT /ifood/merchant/v1.0/merchant/hours Atualizar horarios ▶

Quando usar: ao editar horarios de funcionamento. Aceita multiplos turnos por dia (ex: almoco + jantar).

Atualiza os horarios de funcionamento.

Request

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"working_hours":[{"weekday":1,"status":true,"hours":[{"open":"08:00","close":"22:00"}]}]}' \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant/hours"

Response: 200 OK

PUT /ifood/merchant/v1.0/merchant/preparation-time Tempo de preparo ▶

Quando usar: ajuste dinamico em horarios de pico ou quando a cozinha esta sobrecarregada.

Atualiza o tempo medio de preparo (10 a 60 minutos).

Request

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"preparation_time":30}' \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant/preparation-time"

Response 200

{
  "store_id": 53191,
  "preparation_time": 30
}

PUT /ifood/merchant/v1.0/merchant/delivery-time Tempo de entrega ▶

Quando usar: atualizar SLA de entrega exibido ao cliente. Ex: 40-60 min em horario normal, 60-90 em pico.

Atualiza o tempo estimado de entrega.

Request

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"delivery_time":"30 - 50"}' \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant/delivery-time"

Response 200

{
  "store_id": 53191,
  "delivery_time": "30 - 50"
}

GET /ifood/merchant/v1.0/merchant/delivery-fees Taxas de entrega ▶

Quando usar: consultar taxas atuais antes de criar/editar.

Retorna as faixas de entrega por raio.

Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant/delivery-fees"

Response 200

{
  "store": { "id": "53191", "name": "Pizzaria Exemplo" },
  "city": { "id": 4006, "name": "Maringa" },
  "radius": [
    { "id": 229, "distanceKm": 3, "value": 500, "returnTaxValue": 0 },
    { "id": 230, "distanceKm": 5, "value": 800, "returnTaxValue": 0 }
  ]
}

POST /ifood/merchant/v1.0/merchant/delivery-fees Criar faixas ▶

Quando usar: ao adicionar taxa nova por bairro. Substitui o conjunto inteiro — envie todas que devem permanecer.

Cria novas faixas de entrega por raio.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"radius":[{"distance_km":3.0,"value":5.00},{"distance_km":5.0,"value":8.00}]}' \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant/delivery-fees"

Response: 200 OK

PUT /ifood/merchant/v1.0/merchant/delivery-fees Atualizar faixas ▶

Quando usar: para ajuste de taxa existente sem sobrescrever as outras.

Atualiza faixas de entrega existentes.

Request

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"radius":[{"id":229,"distance_km":3,"value":6.00,"return_tax_value":1.00}]}' \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant/delivery-fees"

Response 200

{
  "radius": [
    { "id": 229, "distance_km": 3, "value": 6.00, "return_tax_value": 1.00 }
  ]
}

DELETE /ifood/merchant/v1.0/merchant/delivery-fees/{id} Remover faixa ▶

Quando usar: ao remover bairro do raio de entrega.

Remove uma faixa de entrega especifica.

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant/delivery-fees/123"

Response: 200 OK

GET /ifood/merchant/v1.0/merchant/neighborhoods Bairros atendidos ▶

Quando usar: para listar bairros configurados (lista canonica do Aiqfome).

Retorna os bairros e suas taxas de entrega.

Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant/neighborhoods"

Response 200

[
  { "id": 472, "name": "Centro", "deliveryTax": 450 },
  { "id": 6571, "name": "Zona 07", "deliveryTax": 700 }
]

POST /ifood/merchant/v1.0/merchant/neighborhoods Sincronizar bairros ▶

Quando usar: para sincronizar lista de bairros atendidos com o Aiqfome.

Sincroniza a lista de bairros atendidos com suas taxas.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"store_neighborhoods":[{"neighborhood_id":"123","delivery_tax":5.00}]}' \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant/neighborhoods"

Response: 200 OK

GET /ifood/merchant/v1.0/merchant/payment-methods Metodos de pagamento ▶

Quando usar: consultar metodos aceitos antes de exibir checkout.

Retorna os metodos de pagamento aceitos pela loja.

Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant/payment-methods"

Response 200

[
  { "id": 121, "name": "Visa Credito" },
  { "id": 163, "name": "Mastercard Credito" },
  { "id": 1, "name": "Dinheiro" }
]

POST /ifood/merchant/v1.0/merchant/payment-methods Configurar pagamentos ▶

Quando usar: vincular metodos de pagamento a loja (PIX, dinheiro, cartao na entrega).

Define quais metodos de pagamento a loja aceita.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payment_methods_ids":[1,2,3]}' \
  "https://www.aiqbridge.com.br/ifood/merchant/v1.0/merchant/payment-methods"

Response: 200 OK

Webhooks

Receba eventos de pedidos em tempo real via push. Cada evento e assinado com HMAC-SHA256.

POST /ifood/order/v1.0/webhook/config Registrar webhook ▶

Quando usar: primeira configuracao apos cadastrar a loja. Define a URL que recebera POST quando eventos ocorrerem.

Registra ou atualiza a URL de webhook. Um secret_key e gerado automaticamente — guarde-o, ele so e retornado nesta chamada.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url":"https://meu-sistema.com/webhook"}' \
  "https://www.aiqbridge.com.br/ifood/order/v1.0/webhook/config"

Response 200

{
  "merchant_id": "m-456",
  "webhook_url": "https://meu-sistema.com/webhook",
  "secret_key": "whsec_abc123...",
  "is_active": true,
  "event_types": null,
  "timeout_seconds": 30,
  "max_retries": 3
}

Payload recebido na sua URL

POST https://meu-sistema.com/webhook
X-Signature: sha256=a1b2c3d4...
Content-Type: application/json

{
  "event": "NEW_ORDER",
  "order_id": "abc-123",
  "merchant_id": "m-456",
  "timestamp": "2026-02-13T10:30:00Z"
}

Validacao HMAC

import hmac, hashlib

expected = "sha256=" + hmac.new(
    secret_key.encode(),
    body.encode(),
    hashlib.sha256
).hexdigest()

assert hmac.compare_digest(expected, request.headers["X-Signature"])

GET /ifood/order/v1.0/webhook/config Ver configuracao ▶

Quando usar: para verificar config atual (URL, secret, status). Util para debug.

Retorna a configuracao atual do webhook (URL, status, filtros).

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/order/v1.0/webhook/config"

DELETE /ifood/order/v1.0/webhook/config Remover webhook ▶

Quando usar: ao trocar de provider de webhook ou desligar webhook.

Remove a configuracao de webhook.

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/order/v1.0/webhook/config"

Response: 204 No Content

PUT /ifood/order/v1.0/webhook/config/toggle Ativar/desativar ▶

Quando usar: pausar/retomar webhook sem perder a config. Util durante manutencao no seu sistema.

Ativa ou desativa o envio sem remover a configuracao.

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/order/v1.0/webhook/config/toggle?enabled=true"

POST /ifood/order/v1.0/webhook/config/test Evento de teste ▶

Quando usar: validar que sua URL recebe corretamente. Envia evento sintetico para a URL configurada.

Dispara um evento WEBHOOK_TEST para validar conectividade.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/ifood/order/v1.0/webhook/config/test"

Eventos (Polling)

Eventos sao notificacoes de mudanca no pedido (novo pedido, cancelamento, atualizacao de status). Use polling como alternativa ao webhook quando voce nao consegue expor uma URL publica.

Como funciona

1. Voce chama GET /events:polling a cada 30s. 2. Recebe uma lista de eventos pendentes. 3. Processa cada evento (consulta detalhes via GET /orders/{id}, atualiza seu sistema). 4. Confirma o recebimento via POST /events/acknowledgment — eventos nao confirmados sao reentregues no proximo polling.

Sempre confirme apos persistir no seu lado. Se confirmar antes e seu sistema cair, voce perde o evento.

GET /od/v1/events:polling Buscar eventos pendentes ▶

Quando usar: a cada 30 segundos para receber eventos pendentes (novos pedidos, cancelamentos). Substitui o webhook se voce nao tem URL publica.

Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/events:polling"

Response 200

[
  {
    "id": "evt_abc123",
    "code": "PLC",
    "fullCode": "PLACED",
    "orderId": "132095063",
    "createdAt": "2026-05-06T10:30:00Z"
  }
]

Resposta vazia ([]) significa que nao ha eventos pendentes. Codigos comuns: PLC (pedido criado), CFM (confirmado), RDY (pronto), DSP (despachado), CON (concluido), CAN (cancelado).

POST /od/v1/events/acknowledgment Confirmar recebimento de eventos ▶

Quando usar: apos persistir cada evento no seu lado. Eventos nao confirmados sao reentregues no proximo polling.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id": "evt_abc123"}, {"id": "evt_def456"}]' \
  "https://www.aiqbridge.com.br/od/v1/events/acknowledgment"

Response: 202 Accepted

Pedidos

Gestao do ciclo de vida do pedido. Os endpoints seguem o fluxo: PLACED → CONFIRMED → PREPARING → READY → DISPATCHED → CONCLUDED (ou CANCELLED a qualquer momento).

Fluxo tipico

Quando um novo pedido chega (evento PLC via webhook ou polling), busque os detalhes com GET /orders/{id}, confirme com /confirm, inicie preparo com /preparing, marque pronto com /readyForPickup ou despache com /dispatch, e finalize com /delivered. Para cancelar a qualquer momento, use /requestCancellation com motivo no body.

GET /od/v1/orders/{orderId} Detalhes do pedido ▶

Quando usar: ao receber qualquer evento (webhook ou polling) para obter o pedido completo. Sempre busque os detalhes antes de confirmar — o evento traz so o ID.

Retorna o pedido completo no formato Open Delivery.

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/orders/132095063"

Response 200

{
  "id": "132095063",
  "type": "DELIVERY",
  "displayId": "132095063",
  "category": "FOOD",
  "createdAt": "2026-02-12T18:18:42-03:00",
  "lastEvent": "PLACED",
  "orderTiming": "INSTANT",
  "preparationStartDateTime": "2026-02-12T18:19:21-03:00",
  "merchant": { "id": "40529", "name": "Pizzaria Exemplo" },
  "items": [
    {
      "id": "0b50304b-8daf-5fe9-abca-361d1573bd60",
      "name": "X-Burger",
      "externalCode": "225469144",
      "unit": "UN",
      "quantity": 1,
      "unitPrice": { "value": 25.00, "currency": "BRL" },
      "totalPrice": { "value": 25.00, "currency": "BRL" },
      "options": []
    }
  ],
  "total": {
    "itemsPrice": { "value": 25.00, "currency": "BRL" },
    "otherFees": { "value": 0.00, "currency": "BRL" },
    "discount": { "value": 0.00, "currency": "BRL" },
    "orderAmount": { "value": 30.00, "currency": "BRL" }
  },
  "payments": {
    "prepaid": 0,
    "pending": 30.00,
    "methods": [
      { "method": "PIX", "type": "PENDING", "value": 30.00, "currency": "BRL" }
    ]
  },
  "customer": {
    "id": "b80473e2-94b5-5b06-b5e2-cea36714fc78",
    "name": "Joao Silva",
    "documentNumber": "",
    "phone": { "number": "(44) 9-9999-0000" },
    "ordersCountOnMerchant": 3
  },
  "sendPreparing": true,
  "sendDelivered": false,
  "sendPickedUp": true,
  "sendTracking": false,
  "extraInfo": "Sem cebola",
  "delivery": {
    "mode": "DEFAULT",
    "deliveryAddress": {
      "streetName": "Rua Exemplo",
      "streetNumber": "123",
      "neighborhood": "Centro",
      "city": "Maringa",
      "state": "PR",
      "postalCode": "87000-000"
    }
  },
  "takeout": null,
  "otherFees": [],
  "discounts": []
}

POST /od/v1/orders/{orderId}/confirm Confirmar pedido ▶

Quando usar: imediatamente apos receber um pedido novo (evento PLC) e validar que voce consegue prepara-lo. Confirmar dispara CFM para a plataforma cliente.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/orders/132095063/confirm"

Response: 202 Accepted

POST /od/v1/orders/{orderId}/preparing Iniciar preparo ▶

Quando usar: quando a cozinha comeca a preparar o pedido. Notifica o cliente que o pedido saiu da fila. Aceita alias /startPreparation por compatibilidade.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/orders/132095063/preparing"

Response: 202 Accepted

POST /od/v1/orders/{orderId}/readyForPickup Pronto para retirada ▶

Quando usar: quando o pedido esta pronto e aguardando o entregador (modelo TAKEOUT) ou o motoboy (entrega propria). Aceita alias /ready por compatibilidade.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/orders/132095063/readyForPickup"

Response: 202 Accepted

POST /od/v1/orders/{orderId}/dispatch Despachar pedido ▶

Quando usar: quando o motoboy sai com o pedido para entrega. So faz sentido em modelo de entrega propria do estabelecimento.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/orders/132095063/dispatch"

Response: 202 Accepted

POST /od/v1/orders/{orderId}/pickedUp Retirado pelo entregador ▶

Quando usar: quando o entregador da plataforma cliente coleta o pedido na loja (modelo logistica terceirizada, nao entrega propria).

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/orders/132095063/pickedUp"

Response: 202 Accepted

POST /od/v1/orders/{orderId}/delivered Marcar como entregue ▶

Quando usar: quando o pedido foi efetivamente entregue ao cliente. Estado terminal — encerra o ciclo de vida.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/orders/132095063/delivered"

Response: 202 Accepted

POST /od/v1/orders/{orderId}/tracking Atualiza progresso da entrega ▶

Quando usar: quando seu PDV/entregador atualiza o progresso da entrega. Bridge mapeia pra /api/v2/logistic/{order_id}/* da Aiqfome.

Eventos suportados (campo deliveryTrackingInfo.event.type):

PICKUP_ONGOING — entregador a caminho da loja
ARRIVED_AT_MERCHANT — entregador chegou na loja
DELIVERY_ONGOING — pedido a caminho do cliente
ARRIVED_AT_CUSTOMER — entregador chegou no cliente
ORDER_DELIVERED — pedido entregue

Outros tipos da spec OD (ORDER_PICKED, CANCELLED) retornam 422.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryTrackingInfo": {
      "event": {"type": "DELIVERY_ONGOING", "datetime": "2026-05-08T15:30:00Z"}
    }
  }' \
  "https://www.aiqbridge.com.br/od/v1/orders/132095063/tracking"

Response: 202 Accepted (sem body) ou 422 se evento não suportado.

PATCH /od/v1/orders/{orderId}/details Atualizar campos do pedido (não suportado) ▶

Status: Aiqfome não suporta atualização genérica do pedido via API. Endpoint exposto pra spec compliance, retorna 422. Para alterações em itens, use o painel ou o Geraldo Lojista.

POST /od/v1/orders/{orderId}/validateCode Validar código de retirada (não suportado) ▶

Status: Aiqfome não usa código de retirada no fluxo atual. Retorna 422.

Cancelamento de pedidos

O Aiqfome não aceita cancelamento via API hoje. Os endpoints OD de cancelamento (requestCancellation, acceptCancellation, denyCancellation) estão expostos pra spec compliance, mas retornam 422 com instruções: o lojista precisa cancelar pelo chat no Geraldo Lojista.

POST /od/v1/orders/{orderId}/requestCancellation Solicitar cancelamento (não suportado via API) ▶

Status: indisponível via API. Retorna 422 com link pro Geraldo Lojista. Aceita alias /cancel por compatibilidade.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/orders/132095063/requestCancellation"

Response 422

{
  "order_id": "132095063",
  "error": "cancellation_via_api_unavailable",
  "message": "O cancelamento de pedidos do Aiqfome ainda não é suportado via API. Para cancelar este pedido, o lojista precisa entrar em contato pelo chat do Geraldo Lojista.",
  "action_required": "human",
  "geraldo_url": "https://geraldo-restaurantes.aiqfome.com/"
}

POST /od/v1/orders/{orderId}/acceptCancellation Aceitar cancelamento (não suportado via API) ▶

Status: indisponível via API. Mesma resposta de requestCancellation. Use o chat do Geraldo Lojista.

POST /od/v1/orders/{orderId}/denyCancellation Negar cancelamento (não suportado via API) ▶

Status: indisponível via API. Mesma resposta de requestCancellation. Use o chat do Geraldo Lojista.

Loja (Merchant)

Status, horários, taxas de entrega, bairros e métodos de pagamento.

Atualizações granulares

Endpoints pra atualizar campos isolados da loja (horários, tempo de preparo, taxas, bairros, métodos de pagamento) sem reenviar o objeto completo do merchant. Preços usam Price objects ({"value": 5.00, "currency": "BRL"}).

GET /od/v1/merchant/{id}/status Status + serviceHours (spec OD 1.7.0) ▶

Quando usar: consultar disponibilidade da loja antes de mandar pedido (spec OD 1.7.0). O {id} aceita o ID Aiqfome direto OU o merchantId registrado em PUT /merchantOnboarding.

Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/merchant/40529/status"

Response 200

{
  "status": "AVAILABLE",
  "services": [{"id": "40529", "serviceType": "DELIVERY", "serviceHours": [...]}],
  "sourceAppId": "aiqbridge"
}

POST /od/v1/confirmationCode Notificar código de confirmação (não suportado) ▶

Status: Aiqfome não emite código de confirmação no fluxo atual. Endpoint exposto pra spec compliance, retorna 422.

GET /od/v1/versions/merchant Versão dos endpoints de merchant ▶

Spec OD 1.7.0. Stateless — retorna a versão suportada pelo Bridge.

Response 200

{
  "merchantEndpoint": "1.7.0",
  "ordersWebhook": "1.7.0"
}

GET /od/v1/versions/orderingApp Versão dos endpoints da Ordering Application ▶

Spec OD 1.7.0.

Response 200

{
  "merchant": {"version": "1.7.0"},
  "orders": {"version": "1.7.0"}
}

GET /od/v1/merchant Info do merchant ▶

Quando usar: para sincronizar dados completos da loja com seu sistema (logo, ratings, horarios, raio).

Dados da loja mapeados para formato Open Delivery (camelCase, campos internos removidos).

Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/merchant"

Response 200

{
  "id": "53191",
  "name": "Pizzaria Exemplo",
  "corporateName": "Pizzaria Exemplo LTDA",
  "preparationTime": 40,
  "deliveryTime": "40 - 60",
  "isDeliveryRadiusActive": false,
  "cityId": 4006,
  "ratings": {
    "average": 4.5,
    "count": 128,
    "details": { "quality": 4.3, "delivery": 4.6, "accuracy": 4.5 }
  },
  "workingHours": [
    { "weekDayNumber": 1, "hours": "08:00 - 22:00", "status": 1 }
  ]
}

POST /od/v1/merchant/status Alterar status ▶

Quando usar: para abrir/fechar/standby a loja remotamente. STANDBY pausa novos pedidos sem fechar.

Abre, fecha ou coloca a loja em standby.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"operation":"OPEN"}' \
  "https://www.aiqbridge.com.br/od/v1/merchant/status"

Valores: OPEN, CLOSE, STANDBY

Response 200

{
  "store_id": 53191,
  "status": "OPEN"
}

GET /od/v1/merchant/hours Horarios ▶

Quando usar: para ler os horarios atuais antes de mostrar/editar no seu painel.

Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/merchant/hours"

Response 200

[
  { "weekDayNumber": 1, "hours": "08:00 - 22:00", "status": 1 },
  { "weekDayNumber": 2, "hours": "08:00 - 22:00", "status": 1 }
]

PUT /od/v1/merchant/hours Atualizar horarios ▶

Quando usar: ao editar horarios de funcionamento. Aceita multiplos turnos por dia (ex: almoco + jantar).

Request

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"working_hours":[{"weekday":1,"status":true,"hours":[{"open":"08:00","close":"22:00"}]}]}' \
  "https://www.aiqbridge.com.br/od/v1/merchant/hours"

Response: 200 OK

PUT /od/v1/merchant/preparation-time Tempo de preparo ▶

Quando usar: ajuste dinamico em horarios de pico ou quando a cozinha esta sobrecarregada.

Request

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"preparation_time":30}' \
  "https://www.aiqbridge.com.br/od/v1/merchant/preparation-time"

Response 200

{
  "store_id": 53191,
  "preparation_time": 30
}

PUT /od/v1/merchant/delivery-time Tempo de entrega ▶

Quando usar: atualizar SLA de entrega exibido ao cliente. Ex: 40-60 min em horario normal, 60-90 em pico.

Request

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"delivery_time":"30 - 50"}' \
  "https://www.aiqbridge.com.br/od/v1/merchant/delivery-time"

Response 200

{
  "store_id": 53191,
  "delivery_time": "30 - 50"
}

GET /od/v1/merchant/delivery-fees Taxas de entrega ▶

Quando usar: consultar taxas atuais antes de criar/editar.

Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/merchant/delivery-fees"

Response 200

{
  "store": { "id": "53191", "name": "Pizzaria Exemplo" },
  "city": { "id": 4006, "name": "Maringa" },
  "radius": [
    { "id": 229, "distanceKm": 3, "value": { "value": 5.00, "currency": "BRL" }, "returnTaxValue": { "value": 0, "currency": "BRL" } },
    { "id": 230, "distanceKm": 5, "value": { "value": 8.00, "currency": "BRL" }, "returnTaxValue": { "value": 0, "currency": "BRL" } }
  ]
}

POST /od/v1/merchant/delivery-fees Criar faixas ▶

Quando usar: ao adicionar taxa nova por bairro. Substitui o conjunto inteiro - envie todas que devem permanecer.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"radius":[{"distance_km":3.0,"value":5.00}]}' \
  "https://www.aiqbridge.com.br/od/v1/merchant/delivery-fees"

Response: 200 OK

PUT /od/v1/merchant/delivery-fees Atualizar faixas ▶

Quando usar: para ajuste de taxa existente sem sobrescrever as outras.

Atualiza faixas de entrega existentes.

Request

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"radius":[{"id":229,"distance_km":3,"value":6.00,"return_tax_value":1.00}]}' \
  "https://www.aiqbridge.com.br/od/v1/merchant/delivery-fees"

Response 200

{
  "radius": [
    { "id": 229, "distance_km": 3, "value": 6.00, "return_tax_value": 1.00 }
  ]
}

DELETE /od/v1/merchant/delivery-fees/{id} Remover faixa ▶

Quando usar: ao remover bairro do raio de entrega.

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/merchant/delivery-fees/123"

Response: 200 OK

GET /od/v1/merchant/neighborhoods Bairros ▶

Quando usar: para listar bairros configurados (lista canonica do Aiqfome).

Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/merchant/neighborhoods"

Response 200

[
  { "id": 472, "name": "Centro", "deliveryTax": { "value": 4.50, "currency": "BRL" } },
  { "id": 6571, "name": "Zona 07", "deliveryTax": { "value": 7.00, "currency": "BRL" } }
]

POST /od/v1/merchant/neighborhoods Sincronizar bairros ▶

Quando usar: para sincronizar lista de bairros atendidos com o Aiqfome.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"store_neighborhoods":[{"neighborhood_id":"123","delivery_tax":5.00}]}' \
  "https://www.aiqbridge.com.br/od/v1/merchant/neighborhoods"

Response: 200 OK

GET /od/v1/merchant/payment-methods Pagamentos ▶

Quando usar: consultar metodos aceitos antes de exibir checkout.

Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/merchant/payment-methods"

Response 200

[
  { "id": 121, "name": "Visa Credito" },
  { "id": 163, "name": "Mastercard Credito" },
  { "id": 1, "name": "Dinheiro" }
]

POST /od/v1/merchant/payment-methods Configurar pagamentos ▶

Quando usar: vincular metodos de pagamento a loja (PIX, dinheiro, cartao na entrega).

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payment_methods_ids":[1,2,3]}' \
  "https://www.aiqbridge.com.br/od/v1/merchant/payment-methods"

Response: 200 OK

Cardapio (Catalog)

Consulte o cardapio publicado da loja e notifique mudancas.

Diferenca importante

O cardapio Aiqfome e gerenciado no painel/app do lojista. Esses endpoints sao read-only do lado do bridge — voce le o catalogo publicado e pode notificar quando ele mudar (nao edita itens via API). Para mutacoes de cardapio, use os endpoints iFood Catalog.

GET /od/v1/merchant/menu Consultar cardapio publicado ▶

Quando usar: para sincronizar o cardapio Aiqfome com seu PDV / sistema externo. Retorna a estrutura completa (categorias, items, sizes, modificadores) no formato Open Delivery.

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/merchant/menu"

Response 200 (resumido)

{
  "id": "menu-40529",
  "merchantId": "40529",
  "categories": [
    {
      "id": "cat-1",
      "name": "Lanches",
      "items": [
        {
          "id": "item-225469144",
          "name": "X-Burger",
          "price": { "value": 25.00, "currency": "BRL" },
          "status": "AVAILABLE"
        }
      ]
    }
  ]
}

POST /od/v1/menuUpdated Notificar cardapio atualizado ▶

Quando usar: apos detectar mudanca no cardapio do seu lado e quiser sinalizar para o bridge invalidar cache. O bridge entao re-consulta a Aiqfome na proxima leitura.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/menuUpdated"

Response: 202 Accepted

GET /od/v1/merchantStatus Status agregado da loja ▶

Quando usar: para health-check rapido. Retorna se a loja esta operando e aceitando pedidos. Mais leve que GET /merchant.

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/merchantStatus"

Response 200

{
  "merchantId": "40529",
  "status": "AVAILABLE",
  "availableAt": "2026-05-06T10:30:00Z"
}

Merchant Update

Notifique mudanças no merchant (status open/close, atualização de menu) seguindo a spec OpenDelivery.

Dois paths, mesmo handler

Spec OD pura. Use PUT /merchantOnboarding uma vez pra registrar o ID do seu PDV (CNPJ+UUID) e os endpoints; depois use POST /merchantUpdate pra notificar mudanças de status/menu. Aiqbridge aceita ambos /merchantUpdate e /menuUpdated (alias).

PUT /od/v1/merchantOnboarding Registra ID do seu PDV + endpoints ▶

Quando usar: uma vez por loja, antes de chamar qualquer outro endpoint OD com seu merchantId custom. Após esse onboarding, todos endpoints OD do Aiqbridge passam a aceitar e devolver esse merchantId (no campo merchant.id dos pedidos, em updatedObjects[].id, etc).

Spec OD oficial: merchantId deve ser gerado pelo seu PDV. Recomendado: CNPJ + UUID (minLength 36).

Request

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "getMerchantURL": {"baseURL": "https://meu-pdv.com/od/v1"},
    "ordersWebhookURL": "https://meu-pdv.com/od/v1/orderUpdate"
  }' \
  "https://www.aiqbridge.com.br/od/v1/merchantOnboarding?merchantId=0989-9969-34296648000179-5d380882-efc4-48dc-91d7-f6bdcbca83ed"

Response 201 (criado) ou 204 (já existia)

{
  "orderingAppMerchantId": "40529",
  "getMerchantURL": {"baseURL": "https://meu-pdv.com/od/v1"},
  "ordersWebhookURL": "https://meu-pdv.com/od/v1/orderUpdate"
}

Erros: 403 (merchantId já registrado pra outra loja deste cliente), 409 (merchantId em uso por outro cliente).

POST /od/v1/merchantUpdate Notifica update do merchant (status, menu) ▶

Quando usar: seu PDV avisa o Aiqbridge que houve mudança (status da loja AVAILABLE/UNAVAILABLE, ou menu atualizado).

Body modos (spec OD):

Vazio → ack (cliente deve buscar GET /merchant/menu)
Só merchantStatus → abre/fecha loja no Aiqfome
entityType + updatedObjects → atualização parcial

updatedObjects[].id aceita o merchantId registrado em PUT /merchantOnboarding ou o ID Aiqfome direto. Bridge valida que o ID pertence ao token (403 se não bater).

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantStatus": "AVAILABLE",
    "entityType": "MERCHANT",
    "updatedObjects": [{"id": "0989-9969-34296648000179-5d380882-efc4-48dc-91d7-f6bdcbca83ed"}]
  }' \
  "https://www.aiqbridge.com.br/od/v1/merchantUpdate"

Response 204

Sem body. Erros: 403 (id não pertence ao token), 500 (falha ao processar).

POST /od/v1/menuUpdated Mesma rota, path alternativo ▶

Idêntico ao /merchantUpdate. Use o que sua integração preferir.

Webhooks

Receba eventos em tempo real. Funciona identicamente aos webhooks iFood, com assinatura HMAC-SHA256.

Webhook vs Polling

Use webhook se voce tem URL publica acessivel pela internet (recomendado — latencia menor). Use polling se nao tem (ver Eventos). Os dois canais sao mutuamente exclusivos: configurar webhook desativa o polling para a mesma loja.

POST /od/v1/webhook/config Registrar webhook ▶

Quando usar: primeira configuracao apos cadastrar a loja. Define a URL que recebera POST quando eventos ocorrerem.

Registra ou atualiza a URL. Um secret_key e gerado automaticamente.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url":"https://meu-sistema.com/od-webhook"}' \
  "https://www.aiqbridge.com.br/od/v1/webhook/config"

GET /od/v1/webhook/config Ver configuracao ▶

Quando usar: para verificar config atual (URL, secret, status). Util para debug.

curl -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/webhook/config"

DELETE /od/v1/webhook/config Remover webhook ▶

Quando usar: ao trocar de provider de webhook ou voltar pro polling.

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/webhook/config"

Response: 204 No Content

PUT /od/v1/webhook/config/toggle Ativar/desativar ▶

Quando usar: pausar/retomar webhook sem perder a config. Util durante manutencao no seu sistema.

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/webhook/config/toggle?enabled=true"

POST /od/v1/webhook/config/test Evento de teste ▶

Quando usar: validar que sua URL recebe corretamente. Envia evento sintetico para a URL configurada.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://www.aiqbridge.com.br/od/v1/webhook/config/test"

Codigos de Erro

Todos os endpoints retornam erros no formato {"detail": "mensagem"}.

Status	Significado	Quando ocorre
`400`	Bad Request	Body invalido, campos obrigatorios ausentes
`401`	Unauthorized	Token ausente ou invalido. Resposta inclui `reconnect_url` se a loja precisa reautorizar (ver OAuth V2)
`403`	Forbidden	Token sem o scope necessario. Veja scopes do token
`404`	Not Found	Pedido ou recurso nao encontrado
`409`	Conflict	Acao fora de ordem (ex: despachar antes de confirmar)
`422`	Unprocessable Entity	Validacao Pydantic falhou; resposta inclui `detail[].loc` apontando o campo problematico
`429`	Too Many Requests	Rate limit excedido. Espere alguns segundos antes de retentar
`500`	Internal Error	Erro inesperado — reporte ao suporte