Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Como funciona

Integre o módulo Merchant e gerencie suas lojas em tempo real.

Fluxo de integração

1. Descoberta

Descubra quais lojas você pode gerenciar:

GET /merchants — Lista todas as lojas vinculadas ao token
GET /merchants/{merchantId} — Obtém detalhes completos de uma loja

2. Monitoramento

Verifique o status operacional em tempo real:

GET /merchants/{merchantId}/status — Consulta disponibilidade da loja

Possíveis estados:

OK — Pronta para receber pedidos
WARNING — Online com restrições
CLOSED — Fechada (esperado, fora do horário)
ERROR — Problema a investigar

3. Gerenciamento operacional

Configure horários de funcionamento e pausas temporárias:Horários de funcionamento:

PUT /merchants/{merchantId}/opening-hours — Configura horários semanais
GET /merchants/{merchantId}/opening-hours — Consulta horários configurados

Interrupções (pausas temporárias):

POST /merchants/{merchantId}/interruptions — Cria pausa no recebimento de pedidos
GET /merchants/{merchantId}/interruptions — Lista pausas ativas
DELETE /merchants/{merchantId}/interruptions/{interruptionId} — Remove pausa e reabre loja

4. Coleta (Lojas Groceries)

Gere QR codes para check-in de entregadores:

POST /merchants/checkin-qrcode — Gera PDF com QR codes para impressão

Fluxo típico de monitoramento:

Listar todas as lojas vinculadas ao seu token
A cada 30 segundos: Consultar status de cada loja
Se status = ERROR: Investigar validações específicas
Se necessário pausar: Criar interrupção
Para lojas Groceries: Gerar e manter QR codes impressos

Consulta de lojas

Listar todas as lojas

Para listar todas as lojas vinculadas ao seu token:

curl --location 'https://merchant-api.ifood.com.br/merchant/v1.0/merchants' \
  --header 'Authorization: Bearer TOKEN'

Parâmetros de query (opcionais):

page — Número da página (começando em 1)
size — Quantidade de lojas por página (padrão: 100)

Response 200:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Pizzaria Central",
    "corporateName": "Pizzaria Central LTDA"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Burger King #42",
    "corporateName": "Restaurant Brands International Brazil"
  }
]

Campos retornados:

Campo	Tipo	Descrição
`id`	`uuid`	Identificador único
`name`	`string`	Nome exibido no app
`corporateName`	`string`	Razão social

Códigos de erro:

HTTP	Código	Descrição
`401`	`Unauthorized`	Token de acesso inválido ou expirado
`500`	`InternalServerError`	Erro ao buscar lista de lojas

AutenticaçãoUse o token Bearer fornecido durante o onboarding. O token determina quais lojas você pode acessar via API.

Obter detalhes de uma loja

Para obter informações completas sobre uma loja específica, use:

curl --location 'https://merchant-api.ifood.com.br/merchant/v1.0/merchants/550e8400-e29b-41d4-a716-446655440000' \
  --header 'Authorization: Bearer TOKEN'

Response 200:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Pizzaria Central",
  "corporateName": "Pizzaria Central LTDA",
  "description": "Pizzaria especializada em pizza napoletana",
  "averageTicket": 85.50,
  "exclusive": false,
  "type": "RESTAURANT",
  "status": "AVAILABLE",
  "createdAt": "2024-01-15T10:30:00",
  "address": {
    "street": "Rua das Flores",
    "number": "123",
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01310-100",
    "country": "BR",
    "district": "Centro",
    "latitude": -23.5505,
    "longitude": -46.6333
  },
  "operations": {
    "name": "delivery",
    "salesChannel": {
      "name": "ifood-app",
      "enabled": true
    }
  }
}

Campos retornados:

Campo	Tipo	Descrição
`id`	`uuid`	Identificador único da loja
`name`	`string`	Nome exibido aos clientes
`corporateName`	`string`	Razão social / nome legal
`description`	`string`	Descrição da loja
`averageTicket`	`number`	Ticket médio
`exclusive`	`boolean`	Se a loja é exclusiva
`type`	`string`	`RESTAURANT`, `STORE`, `GROUP`
`status`	`string`	`AVAILABLE`, `UNAVAILABLE`, `DISABLED`
`createdAt`	`string`	Data de criação (ISO 8601)
`address.street`	`string`	Rua
`address.number`	`string`	Número
`address.city`	`string`	Cidade
`address.state`	`string`	Estado
`address.postalCode`	`string`	CEP
`address.country`	`string`	País
`address.district`	`string`	Bairro
`address.latitude`	`number`	Latitude
`address.longitude`	`number`	Longitude
`operations.name`	`string`	`delivery`, `indoor`
`operations.salesChannel`	`object`	`ifood-app` e outros

Códigos de erro:

HTTP	Código	Descrição	Solução
`401`	`Unauthorized`	Token inválido ou expirado	Verifique o token
`403`	`Forbidden`	Sem permissão para esta loja	Token não vinculado
`500`	`InternalServerError`	Erro ao buscar detalhes	Tente novamente

Próximo passo: Verificar disponibilidadeApós obter os detalhes da loja, use a API de Status para verificar em tempo real se a loja pode receber pedidos.

Status da loja

Requisitos operacionais

A loja receberá pedidos quando atender esses requisitos:

Dentro do horário de funcionamento — Configurado via API de Opening Hours
Catálogo ativo — Ao menos um cardápio habilitado
Área de entrega — Uma zona de entrega configurada
Sem interrupções — Nenhuma pausa ativa
Polling ativo — Polling a cada 30 segundos para validar conectividade

Frequência mínima de pollingA plataforma espera que você faça requisições HTTP a cada 30 segundos como forma de validar que sua integração está ativa. Sem polling regular, a loja pode ser marcada como offline e parar de receber pedidos.

Verificar disponibilidade

Para saber se uma loja está operacional e pronta para receber pedidos, use:

curl --location 'https://merchant-api.ifood.com.br/merchant/v1.0/merchants/550e8400-e29b-41d4-a716-446655440000/status' \
  --header 'Authorization: Bearer TOKEN'

Parâmetros de path:

merchantId (obrigatório): ID da loja

Response 200:

[
  {
    "operation": "delivery",
    "salesChannel": "ifood-app",
    "available": true,
    "state": "OK",
    "validations": [
      {
        "id": "val-001",
        "code": "is-connected",
        "state": "OK",
        "message": {
          "title": "Conectado",
          "subtitle": "Loja está respondendo",
          "description": "Polling recebido nos últimos 30 segundos"
        }
      },
      {
        "id": "val-002",
        "code": "opening-hours",
        "state": "OK",
        "message": {
          "title": "Horário válido",
          "subtitle": "Dentro do horário de funcionamento",
          "description": "Loja está dentro do horário configurado"
        }
      }
    ],
    "message": {
      "title": "Loja Online",
      "subtitle": "Pronta para receber pedidos",
      "description": "Todas as validações passaram com sucesso"
    }
  }
]

Campos principais:

Campo	Tipo	Descrição
`state`	`string`	`OK`, `WARNING`, `CLOSED`, `ERROR`
`available`	`boolean`	Loja disponível para receber pedidos
`validations[]`	`array`	Detalhes por validação
`message`	`object`	Mensagem geral do status

Interpretando o estado

Estado	Significado
`OK`	Online e pronta para receber pedidos
`WARNING`	Online com restrições (investigar validações)
`CLOSED`	Fechada (fora do horário configurado)
`ERROR`	Offline (investigar validações para resolver)

Entender validações

Cada validação indica um requisito operacional. Estado OK significa tudo pronto. Estados WARNING ou ERROR requerem ação.Validações comuns:

is-connected — Polling ativo nos últimos 30s
opening-hours — Dentro do horário configurado
unavailabilities — Pausas ativas. Use a API de Interrupções para remover.
radius-restriction — Sem entregadores na área (expanda a zona)
payout-blocked — Resolver via Portal do Parceiro
terms-service-violation — Entre em contato com suporte

O campo message fornecerá detalhes específicos sobre como resolver cada problema.Resposta com problemas (estado ERROR)Quando há problemas, o endpoint retorna validações com detalhes:

[
  {
    "operation": "delivery",
    "salesChannel": "ifood-app",
    "available": false,
    "state": "ERROR",
    "reopenable": {
      "identifier": "cca57aab-5ac0-4af4-a04d-48261350bebc",
      "type": "UNAVAILABILITY",
      "reopenable": true
    },
    "validations": [
      {
        "id": "val-001",
        "code": "is-connected",
        "state": "OK"
      },
      {
        "id": "val-003",
        "code": "unavailabilities",
        "state": "ERROR",
        "message": {
          "title": "Loja em pausa",
          "subtitle": "Existem interrupções ativas",
          "description": "Use a API de Interrupções para remover"
        }
      }
    ]
  }
]

Verificar status por operação específica

Para obter o status de uma operação específica (ex: delivery):

curl --location 'https://merchant-api.ifood.com.br/merchant/v1.0/merchants/550e8400-e29b-41d4-a716-446655440000/status/delivery' \
  --header 'Authorization: Bearer TOKEN'

Este endpoint retorna a mesma estrutura de resposta acima, mas apenas para a operação especificada.Códigos de erro:

HTTP	Código	Descrição	Solução
`400`	`BadRequest`	Operação inválida	Verifique se o nome da operação está correto
`401`	`Unauthorized`	Token inválido	Verifique seu token de acesso
`403`	`Forbidden`	Sem permissão para esta loja	Token não está vinculado a esta loja
`500`	`InternalServerError`	Erro ao buscar status	Tente novamente ou contacte suporte

Dúvidas sobre o status?Se tiver dúvidas sobre um status específico ou precisar resolver um bloqueio, abra um chamado no Portal do Parceiro.

Remover bloqueios e pausas

Quando a resposta do status retorna state: "ERROR" com reopenable: true, você pode remover a pausa usando a API de Interrupções:

curl --location --request DELETE \
  'https://merchant-api.ifood.com.br/merchant/v1.0/merchants/550e8400-e29b-41d4-a716-446655440000/interruptions/{interruptionId}' \
  --header 'Authorization: Bearer TOKEN'

Se reopenable: false, a loja está sob penalidade automática. Consulte o campo message na resposta de status para saber quando poderá reabrir. Para violações de Termos de Serviço, abra um chamado no Portal do Parceiro.

Interrupções

Pause temporariamente o recebimento de pedidos sem alterar o horário de funcionamento.

Listar pausas

curl --location 'https://merchant-api.ifood.com.br/merchant/v1.0/merchants/{merchantId}/interruptions' \
  --header 'Authorization: Bearer TOKEN'

Retorna array com id, description, start, e end para cada pausa ativa.

Criar pausa

curl --location --request POST \
  'https://merchant-api.ifood.com.br/merchant/v1.0/merchants/{merchantId}/interruptions' \
  --header 'Authorization: Bearer TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "Manutenção do equipamento",
    "start": "2025-02-05T14:00:00Z",
    "end": "2025-02-05T15:30:00Z"
  }'

Campos obrigatórios:

description — motivo (até 255 caracteres)
start e end — datas em ISO 8601 (timezone local da loja)

Validações: Duração mínima 1 minuto, máxima 7 dias. Pausas não podem se sobrepor.Response 201 retorna o objeto da pausa criada com seu id.

Remover pausa

curl --location --request DELETE \
  'https://merchant-api.ifood.com.br/merchant/v1.0/merchants/{merchantId}/interruptions/{interruptionId}' \
  --header 'Authorization: Bearer TOKEN'

Response 204 indica sucesso. A pausa é removida imediatamente.

Horário de funcionamento

Configure quando a loja está aberta para receber pedidos. Use a API de Opening Hours para gerenciar horários por dia da semana.

Escopo da APIEsta API gerencia apenas o horário padrão do iFood Marketplace. Para novos negócios, catálogo digital ou horários especiais, use o Portal do Parceiro.

Consultar horários

curl --location 'https://merchant-api.ifood.com.br/merchant/v1.0/merchants/{merchantId}/opening-hours' \
  --header 'Authorization: Bearer TOKEN'

Retorna array de turnos (shifts) com id, dayOfWeek (MONDAY-SUNDAY), start (HH:MM:SS), e duration (minutos).

Atualizar horários

curl --location --request PUT \
  'https://merchant-api.ifood.com.br/merchant/v1.0/merchants/{merchantId}/opening-hours' \
  --header 'Authorization: Bearer TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "storeId": "{merchantId}",
    "shifts": [
      {
        "dayOfWeek": "MONDAY",
        "start": "09:00:00",
        "duration": 360
      },
      {
        "dayOfWeek": "FRIDAY",
        "start": "05:00:00",
        "duration": 420
      }
    ]
  }'

Campos obrigatórios:

storeId — ID da loja
shifts[] — Array de turnos

Cada turno requer:

dayOfWeek — MONDAY a SUNDAY
start — Abertura em HH:MM:SS (00:00:00 a 23:59:59)
duration — Duração em minutos

Validações: Dias não incluídos ficarão fechados. Múltiplos turnos no mesmo dia são permitidos mas não podem se sobrepor. Duração mínima é 1 minuto.Response 201 retorna os turnos criados.Dica: Para pausas temporárias, use Interrupções em vez de alterar horários permanentes.

Exemplo: Múltiplos turnos

Uma pizzaria pode ter horários diferentes na sexta-feira (pré-expediente, almoço, jantar):

{
  "storeId": "09e9a8c8-fda3-4991-acfc-43b15397caf6",
  "shifts": [
    {"dayOfWeek": "MONDAY", "start": "09:00:00", "duration": 360},
    {"dayOfWeek": "TUESDAY", "start": "09:00:00", "duration": 360},
    {"dayOfWeek": "FRIDAY", "start": "05:00:00", "duration": 420},
    {"dayOfWeek": "FRIDAY", "start": "13:00:00", "duration": 300},
    {"dayOfWeek": "FRIDAY", "start": "19:00:00", "duration": 210}
  ]
}

Check-in do entregador

Entregadores usam QR codes para fazer check-in nas lojas Groceries (supermercados, mercados, farmácias, petshops) e começar a coletar pedidos.

Gerar QR codes para check-in

Gere PDFs com QR codes prontos para impressão (disponível apenas para lojas Groceries):

curl --location --request POST \
  'https://merchant-api.ifood.com.br/merchant/v1.0/merchants/checkin-qrcode' \
  --header 'Authorization: Bearer TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"merchantIds": ["id1", "id2", "id3"]}'

Campo obrigatório:

merchantIds[] — Array de IDs de lojas (máximo 20)

Response 200: PDF binário pronto para impressão.Disponível apenas para lojas Groceries. Solicite novos QR codes a qualquer momento sem duplicação.

Próximos passos

Saiba mais sobre Merchant

Endpoints — Referência técnica de todos os endpoints
Operações — Configure tipos de operação da loja
Boas práticas — Padrões recomendados e resolução de problemas
Homologação — Critérios para validar sua integração

Explore outros módulos

Pedidos (Orders) — Receba, confirme e gerencie pedidos
Logística (Logistics) — Acompanhe a entrega de pedidos
Catálogo (Catalog) — Gerencie cardápios e preços
Eventos (Events) — Receba notificações em tempo real

Referência da API e suporte

API References — Especificação completa de todos os endpoints
Fale com o suporte — Dúvidas ou problemas não resolvidos

Esta página foi útil?

Avalie sua experiência no novo Developer portal: