logo
logo

Docs / Merchant

A API de Merchant oferece recursos para gestão dos merchants, isto é, das lojas.

Merchant é o estabelecimento que oferece pratos/produtos na plataforma iFood. Pode ser um restaurante, mercado, farmácia, petshop dentre outros tipos de estabelecimentos comerciais.

Consulta de lojas

O Endpoint /merchants retorna o ID, nome e nome corporativo de todas as lojas às quais o usuário tem acesso. O usuário em questão é o usuário do token de autorização utilizado na requisição.

O Endpoint /merchants/{id} retorna os detalhes da loja consultada, como nome, endereço e operações.

Status

Para que uma loja apareça na plataforma, é preciso que:

  1. Esteja dentro do Horário de Funcionamento.
  2. Tenha um catálogo configurado. É importante se certificar de que exista ao menos um cardápio habilitado.
  3. Tenha uma área de entrega configurada. É importante verificar se o endereço do pedido do cliente está dentro da área de entrega da loja.
  4. Não tenha interrupções vigentes. Deve-se verificar se não existe algum bloqueio ou restrição para essa loja.
  5. Loja esteja fazendo polling a cada 30 segundos para receber novos pedidos.

Dada uma operação, é possível, através das APIs de Status, descobrir se uma loja está aberta na plataforma, isto é, apta para receber pedidos imediatamente. Esse Status principal vem resumido atráves de um campo State. No caso em que o State é diferente de OK, os motivos para tal são definidos numa lista de Validações.

As operações estão bem descritas aqui.

Os valores possíveis para o campo state são:

StateCor (Sugestão)Descrição
OKVerdeIndica que a loja está online.
WARNINGAmarelaIndica que a loja está online, mas podem haver restrições como redução de área de entrega.
CLOSEDCinzaIndica que a loja está fechada conforme esperado, como em casos de "fora do horário de funcionamento" ou "em pausa programada". Não requer nenhuma ação.
ERRORVermelhaIndica que a loja está fechada por algum motivo não esperado. Requer uma ação da loja.

As validações is-connected e opening-hours sempre serão retornadas, diferentemente das demais, que só serão retornadas quando o state for ERROR ou WARNING.

Na tabela seguinte, são listados os motivos que podem fazer uma loja não estar disponível em uma das operações da plataforma. Note que uma loja pode ter disponibilidades diferentes para cada uma de suas operações.

IDValidação
is-connectedA loja está fazendo polling regularmente a cada 30 segundos.
opening-hoursO horário atual está dentro de algum horário de funcionamento.
unavailabilitiesHá alguma interrupção no horário atual.
radius-restrictionHá disponibilidade de entregadores na área.
payout-blockedHá pendências financeiras da loja.
logistics-blockedHá problemos logísticos na área da loja, vide festivais, trânsito intenso, etc.
terms-service-violationA loja violou os Termos de Serviço do iFood.
status-availabilityA loja está desativada, em fase de testes ou durante uma interrupção.

Caso exista alguma dúvida sobre o porquê de sua loja não ter passado em uma das validações acima, abra um chamado através do Portal do Parceiro.

Existem alguns casos em que uma loja pode sofrer uma penalidade. Em geral, uma penalidade é aplicada quando a loja viola os Termos de Serviço.

Determinadas penalidades não permitem a reabertura instantânea. Um exemplo disso é quando uma loja cancela muitos pedidos em um pequeno período de tempo. Nessas situações, faz-se necessário aguardar até o fim da penalidade. Essas interrupcões automáticas ocorrem para garantir uma melhor experiência do cliente, isto é, evitar que pedidos não sejam atendidos.

Em outros casos, é possível que a loja solicite a reabertura, como por exemplo quando a própria loja cria uma interrupção.

O objeto reopenable informa se é possível reabrir uma loja ou não.

CampoDescrição/Valores
reopenabletrue/false
typeTipo ou motivo do fechamento Ex: "UNAVAILABILITY"
identifierIdentificador (id) para reabrir. Ex: "cca57aab-5ac0-4af4-a04d-48261350bebc"

Nos casos em que a reabertura é permitida, devolve-se um objeto parecido com o abaixo:

reopenable: {
	identifier: "cca57aab-5ac0-4af4-a04d-48261350bebc",
	type: "UNAVAILABILITY",
	reopenable: true
}

Note que, por se tratar de uma indisponibilidade, é possível utilizar a API de interrupção, detalhada na seção abaixo, para remover a pausa e voltar a receber pedidos.

Nos casos em que o reopenable é falso, os detalhes estarão no objeto message da API de Status.

Interrupções

É possível fechar uma loja temporariamente, caso seja necessário. Dessa forma, ela não receberá pedidos durante o período. Esses fechamentos e a gerência dos mesmos são feitos através da API de interrupções.

Para obter todas as interrupções vigentes e futuras de uma loja, utilize o endpoint de GET.

Para criar uma interrupção, utilize o endpoint de POST. Note que uma interrupção deve ser criada no corpo da requisição.

A API só aceita datas conforme a ISO 8601. Caso a criação seja bem sucedida, o endpoint devolverá a interrupção no corpo da resposta, contendo seu novo ID, descrição e início e fim formatados de acordo com o ISO 8601 extendido simplificado ou ECMA.

Para remover uma interrupção, é necessário utilizar o endpoint de DELETE. É necessário apenas o ID do merchant e da interrupção.