Documentação da API

Guia completo para integrar seu sistema de delivery com o iFood através do iHub. Configure webhooks, vincule lojas e gerencie pedidos.

Introdução

O iHub atua como intermediário entre a API do iFood e o seu sistema de delivery. Após configurar seu webhook no painel, o iHub cuida de todo o polling, autenticação e reenvio — seu sistema só precisa receber requisições POST.

O fluxo funciona assim:

Você registra sua conta e assina o plano.
No painel, configura o domínio e a URL de webhook do seu sistema.
Inicia o processo de vinculação de uma loja iFood (merchant) via API.
A partir daí, o iHub envia todos os pedidos e eventos diretamente para seu webhook.
Use o módulo Merchant para consultar status da loja, pausas, horários e demais operações da API de lojas do iFood.

Base URL

Todas as requisições à API devem usar o prefixo:

https://ihub.arcn.com.br/api

Autenticação

Todas as rotas protegidas exigem o header Authorization: Bearer {token}.

Chamadas do seu sistema para o iHub

Use o token secreto (UUID) exibido no painel após salvar as configurações. Esse token identifica seu cadastro na tabela de clientes.

Envie: Authorization: Bearer {seu_secret_token}
Nos endpoints que enviam domain no JSON (ex.: vincular merchant, ações em pedido), o valor deve ser o mesmo domínio cadastrado no painel — caso contrário o iHub retorna 403.
Nas rotas GET de pedidos e em todo o módulo Merchant (/api/merchants/...), o domínio é obtido automaticamente a partir do token — não é necessário enviá-lo na URL ou no corpo.

Segurança: trate o token como senha. Não commite em repositórios públicos; use variáveis de ambiente no seu servidor.

Webhooks do iHub para o seu sistema

Na direção oposta (iHub → sua URL de webhook), o iHub envia o mesmo valor no header X-iFood-Hub-Signature para você validar a origem da requisição.

Validação no seu endpoint

$hubSignature = $request->header('X-iFood-Hub-Signature');
// Compare com o token secreto que você armazenou (mesmo valor do painel)

if ($hubSignature !== $seuTokenArmazenadoComSeguranca) {
    return response()->json(['message' => 'Unauthorized'], 401);
}

Gerar User Code

Primeiro passo para vincular uma loja iFood. Gera um código que o lojista deve inserir na página de vinculação do iFood.

POST /api/auth/generate-user-code

Exemplo de requisição

cURL

curl -X POST https://ihub.arcn.com.br/api/auth/generate-user-code \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Accept: application/json"

Resposta de sucesso

JSON

{
    "userCode": "ABCD-EFGH",
    "authorizationCodeVerifier": "um-codigo-verificador-longo",
    "verificationUrl": "https://portal.ifood.com.br/...",
    "verificationUrlComplete": "https://portal.ifood.com.br/...?code=ABCD-EFGH"
}

Fluxo: Exiba o userCode ou redirecione o lojista para verificationUrlComplete. Após o lojista autorizar no portal do iFood, use authorizationCodeVerifier na próxima etapa.

Vincular Merchant

Após o lojista autorizar o acesso no portal do iFood, envie os dados de autorização para vincular a loja ao seu sistema.

POST /api/auth/link-merchant

Parâmetros

Campo	Tipo	Descrição
domain	`string`	Domínio do seu sistema cadastrado no painel.
authorizationCode	`string`	Código de autorização retornado pelo iFood após o lojista aprovar.
authorizationCodeVerifier	`string`	Verificador obtido na etapa anterior (`generate-user-code`).

Exemplo de requisição

cURL

curl -X POST https://ihub.arcn.com.br/api/auth/link-merchant \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "app.meudelivery.com.br",
    "authorizationCode": "codigo-do-ifood",
    "authorizationCodeVerifier": "verificador-da-etapa-1"
  }'

Resposta de sucesso

JSON

{
    "message": "Merchant linked successfully",
    "merchant": {
        "id": 1,
        "client_id": 5,
        "merchant_id": "abcd-1234-efgh-5678",
        "access_token": "...",
        "refresh_token": "...",
        "expires_at": "2026-04-15T00:00:00.000000Z"
    },
    "ifood_details": {
        "id": "abcd-1234-efgh-5678",
        "name": "Restaurante Exemplo",
        "corporateName": "..."
    }
}

Pronto! A partir deste momento, o iHub começa a monitorar os pedidos e eventos desta loja e os envia para o webhook configurado no seu painel.

Recebendo Webhooks

Após vincular um merchant, o iHub envia automaticamente todos os eventos de pedidos para a URL de webhook configurada no seu painel via POST.

Headers enviados

Header	Descrição
Content-Type	`application/json`
Accept	`application/json`
X-iFood-Hub-Signature	Seu token secreto (compare para validar autenticidade).

Importante: Seu endpoint deve retornar HTTP 2xx para confirmar o recebimento. Caso contrário, o evento será marcado como falha.

Payload dos Webhooks

O corpo de cada webhook segue a estrutura de eventos do iFood:

Campo	Tipo	Descrição
id	`string`	ID único do evento.
code	`string`	Código resumido do evento (ex.: `PLC`, `CFM`, `CAN`).
fullCode	`string`	Código completo (ex.: `PLACED`, `CONFIRMED`).
orderId	`string`	ID do pedido no iFood.
merchantId	`string`	ID da loja (merchant) no iFood.
createdAt	`string`	Timestamp ISO 8601 do evento.

Pedido Novo (PLC)

Quando um novo pedido é criado (code: PLC), o iHub automaticamente busca os detalhes completos do pedido na API do iFood e os inclui no campo order_details — assim seu sistema não precisa fazer uma segunda requisição.

JSON

{
    "id": "evt-abc-123",
    "code": "PLC",
    "fullCode": "PLACED",
    "orderId": "order-xyz-789",
    "merchantId": "merchant-aaa-111",
    "createdAt": "2026-04-14T22:30:00Z",
    "order_details": {
        "id": "order-xyz-789",
        "type": "DELIVERY",
        "displayId": "1234",
        "orderType": "DELIVERY",
        "customer": {
            "name": "João da Silva",
            "phone": { "number": "11999999999" }
        },
        "deliveryAddress": {
            "streetName": "Rua Exemplo",
            "streetNumber": "100",
            "neighborhood": "Centro",
            "city": "São Paulo",
            "state": "SP",
            "postalCode": "01000-000",
            "complement": "Apto 42",
            "reference": "Próximo ao mercado"
        },
        "items": [
            {
                "id": "item-001",
                "name": "X-Burger",
                "quantity": 2,
                "unitPrice": 25.90,
                "totalPrice": 51.80,
                "subItems": [],
                "observations": "Sem cebola"
            }
        ],
        "payments": {
            "methods": [
                { "method": "CREDIT", "type": "ONLINE", "value": 51.80 }
            ]
        },
        "total": {
            "subTotal": 51.80,
            "deliveryFee": 5.00,
            "benefits": 0,
            "orderAmount": 56.80
        }
    }
}

Eventos de Status

Eventos subsequentes (confirmação, despacho, cancelamento, etc.) seguem a mesma estrutura, sem o campo order_details:

Código	fullCode	Descrição
PLC	`PLACED`	Novo pedido criado.
CFM	`CONFIRMED`	Pedido confirmado pelo restaurante.
PSP	`PREPARATION_STARTED`	Preparo iniciado.
DSP	`DISPATCHED`	Pedido despachado.
RTP	`READY_TO_PICKUP`	Pronto para retirada.
CAN	`CANCELLED`	Pedido cancelado.
CON	`CONCLUDED`	Pedido concluído.

Exemplo — Confirmação

{
    "id": "evt-abc-456",
    "code": "CFM",
    "fullCode": "CONFIRMED",
    "orderId": "order-xyz-789",
    "merchantId": "merchant-aaa-111",
    "createdAt": "2026-04-14T22:32:00Z"
}

Executar Ação em Pedido

Use esta rota para confirmar, despachar, cancelar ou gerenciar pedidos no iFood.

POST /api/ifood/action

Parâmetros

Campo	Tipo	Obrigatório	Descrição
domain	`string`	Sim	Domínio do seu sistema.
merchantId	`string`	Sim	ID do merchant no iFood.
orderId	`string`	Sim	ID do pedido.
action	`string`	Sim	Ação a executar (ver tabela abaixo).
cancelCode	`string`	Se `cancel`	Código do motivo de cancelamento.
cancelReason	`string`	Se `cancel`	Descrição do motivo.

Ações disponíveis

Ação	Descrição
confirm	Confirma o recebimento do pedido.
startPreparation	Marca o início do preparo.
readyToPickup	Marca como pronto para retirada.
dispatch	Despacha o pedido para entrega.
cancel	Cancela o pedido (requer `cancelCode` e `cancelReason`).

Exemplo — Confirmar pedido

cURL

curl -X POST https://ihub.arcn.com.br/api/ifood/action \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "app.meudelivery.com.br",
    "merchantId": "abcd-1234-efgh-5678",
    "orderId": "order-xyz-789",
    "action": "confirm"
  }'

Exemplo — Cancelar pedido

cURL

curl -X POST https://ihub.arcn.com.br/api/ifood/action \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "app.meudelivery.com.br",
    "merchantId": "abcd-1234-efgh-5678",
    "orderId": "order-xyz-789",
    "action": "cancel",
    "cancelCode": "501",
    "cancelReason": "Falta de ingredientes"
  }'

Resposta de sucesso

JSON

{
    "success": true,
    "message": "Order confirmed successfully"
}

Detalhes do Pedido

Busca os dados completos de um pedido diretamente na API do iFood. O cadastro é identificado pelo Authorization: Bearer; não é necessário informar o domínio na URL.

GET /api/orders/{merchantId}/{orderId}

Exemplo

cURL

curl https://ihub.arcn.com.br/api/orders/abcd-1234-efgh-5678/order-xyz-789 \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Accept: application/json"

Retorna o JSON completo com dados do pedido (itens, cliente, endereço, pagamento).

Motivos de Cancelamento

Obtém a lista de motivos de cancelamento válidos para um pedido. O domínio é inferido do token.

GET /api/orders/{merchantId}/{orderId}/cancellation-reasons

Exemplo

cURL

curl https://ihub.arcn.com.br/api/orders/abcd-1234-efgh-5678/order-xyz-789/cancellation-reasons \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Accept: application/json"

Retorna um array de objetos com cancelCodeId e description. Use o código na ação cancel.

Validar Código de Retirada

Valida o código de retirada apresentado pelo entregador no momento da coleta do pedido. Utilizado em pedidos com entrega própria (self-delivery) onde o entregador precisa confirmar a retirada.

POST /api/orders/validate-pickup-code

Parâmetros

Campo	Tipo	Obrigatório	Descrição
domain	`string`	Sim	Domínio do seu sistema cadastrado no painel.
merchantId	`string`	Sim	ID do merchant no iFood.
orderId	`string`	Sim	ID do pedido no iFood.
code	`string`	Sim	Código de retirada apresentado pelo entregador.

Exemplo

cURL

curl -X POST https://ihub.arcn.com.br/api/orders/validate-pickup-code \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "app.meudelivery.com.br",
    "merchantId": "abcd-1234-efgh-5678",
    "orderId": "order-xyz-789",
    "code": "9999"
  }'

Resposta de sucesso

JSON

{
    "success": true
}

Códigos de erro

Status	Descrição
400	Tipo de validação incorreto para este pedido.
404	Pedido não encontrado ou endpoint indisponível (entrega iFood + recurso habilitado). Entrega própria valida localmente via pickupCode.
412	Status de handshake inválido — o pedido deve ter sido aceito pelo entregador antes da validação.

Verificar Código de Entrega

Verifica o código de confirmação de entrega apresentado pelo destinatário no momento da entrega do pedido.

POST /api/orders/verify-delivery-code

Parâmetros

Campo	Tipo	Obrigatório	Descrição
domain	`string`	Sim	Domínio do seu sistema cadastrado no painel.
merchantId	`string`	Sim	ID do merchant no iFood.
orderId	`string`	Sim	ID do pedido no iFood.
code	`string`	Sim	Código de entrega apresentado pelo destinatário.

Exemplo

cURL

curl -X POST https://ihub.arcn.com.br/api/orders/verify-delivery-code \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "app.meudelivery.com.br",
    "merchantId": "abcd-1234-efgh-5678",
    "orderId": "order-xyz-789",
    "code": "9999"
  }'

Resposta de sucesso

JSON

{
    "success": true
}

Códigos de erro

Status	Descrição
400	Código de confirmação inválido (não confundir com código de retirada).
404	Pedido não encontrado. Entrega própria: compare com `customer.phone.localizer`.

Módulo Merchant (Loja)

Endpoints para consultar e gerenciar lojas vinculadas ao iFood: listagem, detalhes, status operacional, pausas (interrupções), horários de funcionamento e QR code de check-in (Grocery).

Todas as rotas exigem Authorization: Bearer SEU_TOKEN_SECRETO. O {merchant_id} na URL deve ser o UUID da loja já vinculada ao seu cadastro no iHub (via Vincular Merchant).

Respostas: o iHub repassa o JSON da API Merchant do iFood quando possível. Erros comuns: 404 (loja não vinculada), 401 (token iFood expirado), 403 (sem permissão), 429 (rate limit — respeite o header Retry-After).

Listar lojas

Lista todas as lojas associadas ao token OAuth do merchant informado (paginação opcional).

GET /api/merchants/{merchantId}/list

Query (opcional)

Campo	Tipo	Descrição
page	`integer`	Página (mín. 1).
size	`integer`	Itens por página (máx. 100).

Exemplo

cURL

curl "https://ihub.arcn.com.br/api/merchants/abcd-1234-efgh-5678/list?page=1&size=50" \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Accept: application/json"

Detalhes da loja

Retorna informações completas de uma loja específica (nome, endereço, categorias, etc.).

GET /api/merchants/{merchantId}

Exemplo

cURL

curl https://ihub.arcn.com.br/api/merchants/abcd-1234-efgh-5678 \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Accept: application/json"

Status da loja

Consulta o status operacional geral da loja (aberta, fechada, pausada, etc.).

GET /api/merchants/{merchantId}/status

Exemplo

cURL

curl https://ihub.arcn.com.br/api/merchants/abcd-1234-efgh-5678/status \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Accept: application/json"

Status por operação

Status filtrado por tipo de operação da loja.

GET /api/merchants/{merchantId}/status/{operation}

Parâmetros de URL

Campo	Valores	Descrição
operation	`DELIVERY`, `TAKEOUT`, `INDOOR`	Tipo de operação (maiúsculas).

Exemplo

cURL

curl https://ihub.arcn.com.br/api/merchants/abcd-1234-efgh-5678/status/DELIVERY \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Accept: application/json"

Erros

Status	Descrição
400	`operation` inválida (use DELIVERY, TAKEOUT ou INDOOR).

Listar pausas (interrupções)

Lista interrupções temporárias ativas da loja (pausas programadas ou em andamento).

GET /api/merchants/{merchantId}/interruptions

Exemplo

cURL

curl https://ihub.arcn.com.br/api/merchants/abcd-1234-efgh-5678/interruptions \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Accept: application/json"

Criar pausa

Cria uma interrupção temporária de operação (ex.: pausa para manutenção ou falta de equipe).

POST /api/merchants/{merchantId}/interruptions

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
description	`string`	Sim	Motivo da pausa (máx. 255 caracteres).
start	`date`	Sim	Início da pausa (ISO 8601).
end	`date`	Sim	Fim da pausa (deve ser posterior a `start`).

Exemplo

cURL

curl -X POST https://ihub.arcn.com.br/api/merchants/abcd-1234-efgh-5678/interruptions \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Pausa para manutenção",
    "start": "2026-05-20T14:00:00Z",
    "end": "2026-05-20T16:00:00Z"
  }'

Resposta de sucesso

Status 201 Created com o objeto da interrupção criada (inclui id para remoção posterior).

Erros

Status	Descrição
409	Sobreposição com outra interrupção já existente.

Remover pausa

Remove uma interrupção ativa pelo ID retornado na criação ou listagem.

DELETE /api/merchants/{merchantId}/interruptions/{interruptionId}

Exemplo

cURL

curl -X DELETE https://ihub.arcn.com.br/api/merchants/abcd-1234-efgh-5678/interruptions/interruption-uuid-aqui \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO"

Resposta de sucesso

Status 204 No Content (corpo vazio).

Horários de funcionamento

Consulta os turnos de funcionamento cadastrados no iFood para a loja.

GET /api/merchants/{merchantId}/opening-hours

Exemplo

cURL

curl https://ihub.arcn.com.br/api/merchants/abcd-1234-efgh-5678/opening-hours \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Accept: application/json"

Atualizar horários

Substitui todos os turnos de funcionamento da loja. Dias da semana não enviados no array shifts ficam fechados.

Atenção: esta operação é destrutiva — envie a grade completa de turnos que deseja manter, não apenas o dia alterado.

PUT /api/merchants/{merchantId}/opening-hours

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
storeId	`uuid`	Sim	ID da loja no iFood (obtido em detalhes da loja).
shifts	`array`	Sim	Lista de turnos (mín. 1).
shifts[].dayOfWeek	`string`	Sim	`MONDAY` … `SUNDAY`
shifts[].start	`string`	Sim	Horário de abertura (`H:i:s`, ex.: `08:00:00`).
shifts[].duration	`integer`	Sim	Duração do turno em minutos.

Exemplo

cURL

curl -X PUT https://ihub.arcn.com.br/api/merchants/abcd-1234-efgh-5678/opening-hours \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "c54bb20a-bce0-4e38-bd4a-fe5f0a7b6b5a",
    "shifts": [
      {
        "dayOfWeek": "MONDAY",
        "start": "08:00:00",
        "duration": 720
      },
      {
        "dayOfWeek": "TUESDAY",
        "start": "08:00:00",
        "duration": 720
      }
    ]
  }'

Resposta de sucesso

Status 201 Created com os turnos criados/atualizados.

Erros

Status	Descrição
400	Validação (turnos sobrepostos, formato inválido, etc.).
409	Conflito na atualização.

QR Code de check-in

Gera um PDF com QR codes de check-in para entregadores. Destinado a lojas do tipo Grocery. Aceita de 1 a 20 lojas por requisição.

POST /api/merchants/checkin-qrcode

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
merchantIds	`uuid[]`	Sim	IDs das lojas (1 a 20). O token é resolvido pela primeira loja da lista.

Exemplo

cURL

curl -X POST https://ihub.arcn.com.br/api/merchants/checkin-qrcode \
  -H "Authorization: Bearer SEU_TOKEN_SECRETO" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantIds": [
      "abcd-1234-efgh-5678",
      "9876-5432-1111-2222-333344445555"
    ]
  }' \
  --output checkin-qrcode.pdf

Resposta de sucesso

Status 200 com corpo binário application/pdf (arquivo para download/impressão).

Nas requisições POST /api/ifood/action abaixo, envie sempre Authorization: Bearer SEU_TOKEN_SECRETO (igual às demais rotas).

Aceitar Disputa

Aceita uma disputa aberta pelo cliente no iFood.

POST /api/ifood/action

JSON

{
    "domain": "app.meudelivery.com.br",
    "merchantId": "abcd-1234-efgh-5678",
    "orderId": "order-xyz-789",
    "action": "acceptDispute",
    "disputeId": "dispute-id-aqui",
    "reason": "Concordo com o cliente",
    "detailReason": "Produto realmente estava errado"
}

Rejeitar Disputa

Rejeita uma disputa. disputeId e reason são obrigatórios.

POST /api/ifood/action

JSON

{
    "domain": "app.meudelivery.com.br",
    "merchantId": "abcd-1234-efgh-5678",
    "orderId": "order-xyz-789",
    "action": "rejectDispute",
    "disputeId": "dispute-id-aqui",
    "reason": "Pedido foi entregue corretamente"
}

Propor Reembolso

Propõe um reembolso parcial em uma disputa. disputeId, alternativeId e refundAmount são obrigatórios.

POST /api/ifood/action

JSON

{
    "domain": "app.meudelivery.com.br",
    "merchantId": "abcd-1234-efgh-5678",
    "orderId": "order-xyz-789",
    "action": "proposeRefund",
    "disputeId": "dispute-id-aqui",
    "alternativeId": "alternative-id",
    "refundAmount": "15.50"
}