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:

1. Você registra sua conta e assina o plano.
2. No painel, configura o domínio e a URL de webhook do seu sistema.
3. Inicia o processo de vinculação de uma loja iFood (merchant) via API.
4. A partir daí, o iHub envia todos os pedidos e eventos diretamente para seu webhook.

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 detalhes do pedido e motivos de cancelamento, o domínio é obtido automaticamente a partir do token — não é necessário enviá-lo na URL.

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.

$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.

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

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

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.

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"
  }'

{
    "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": "..."
    }
}

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

Payload dos Webhooks

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

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.

{
    "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:

{
    "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.

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"
  }'

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"
  }'

{
    "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.

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"

Motivos de Cancelamento

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

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"

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.

{
    "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.

{
    "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.

{
    "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"
}