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.

Definições

Critérios para homologação

Listar Lojas fazendo requests no endpoint GET /merchants.
Listar detalhes da loja fazendo requests no endpoint GET /merchants/{merchantId}. O resultado esperado é chamar o endpoint com algum merchant da lista retornado pelo endpoint GET /merchants.
Listar status da loja fazendo requests no endpoint GET /merchants/{merchantId}/status.
Criar uma interrupção fazendo requests no endpoint POST /merchants/{merchantId}/interruptions.
Listar uma interrupção fazendo requests no endpoint GET /merchants/{merchantId}/interruptions.
Remover uma interrupção fazendo requests no endpoint DELETE /merchants/{merchantId}/interruptions/{interruptionId}.
Listar horário de funcionamento fazendo requests no endpoint GET /merchants/{merchantId}/opening-hours
Criar horário de funcionamento fazendo requests no endpoint PUT /merchants/{merchantId}/opening-hours

Consulta de lojas

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

Detalhes da loja

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:

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

Disponibilidade da loja

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 através 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.

Operação

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

Estado

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

State	Cor (Sugestão)	Descrição
OK	Verde	Indica que a loja está online.
WARNING	Amarela	Indica que a loja está online, mas podem haver restrições como redução de área de entrega.
CLOSED	Cinza	Indica 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.
ERROR	Vermelha	Indica que a loja está fechada por algum motivo não esperado. Requer uma ação da loja.

Validações

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.

ID	Validação
is-connected	A loja está fazendo polling regularmente a cada 30 segundos.
opening-hours	O horário atual está dentro de algum horário de funcionamento.
unavailabilities	Há alguma interrupção no horário atual.
radius-restriction	Há disponibilidade de entregadores na área.
payout-blocked	Há pendências financeiras da loja.
logistics-blocked	Há problemas logísticos na área da loja, vide festivais, trânsito intenso, etc.
terms-service-violation	A loja violou os Termos de Serviço do iFood.
status-availability	A 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.

Penalidades

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 interrupçõ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.

Campo	Descrição/Valores
reopenable	true/false
type	Tipo ou motivo do fechamento Ex: "UNAVAILABILITY"
identifier	Identificador (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.

Listar

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

Criar

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, início e fim formatados de acordo com o ISO 8601 estendido simplificado ou ECMA.

Horário de execução das interrupções

Todas as interrupções criadas irão entrar em vigor no Fuso Horário da loja, ou seja, mesmo enviando o timezone no payload o mesmo será descartado.

Pedidos imediatamente após fechamento da loja

Ao cadastrar uma interrupção para que a loja fique fechada, essa requisição será processada internamente e pode levar alguns segundos até que a loja seja efetivamente fechada no aplicativo. Nesse intervalo, alguns pedidos podem acabar sendo realizados. Por esse motivo, recomendamos que ao cadastrar uma interrupção, seu aplicativo continue fazendo polling por alguns minutos para evitar que algum desses pedidos sejam perdidos.

Remover

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

Horário de Funcionamento

Agora você pode ajustar o horário de funcionamento de uma loja conforme desejado. Essas configurações e gerenciamentos são feitos de maneira intuitiva e simplificada através da API de horário de funcionamento.

Funcionalidade Específica

É importante notar que esta API é para o horário de funcionamento padrão do estabelecimento, focado no iFood Marketplace. Novos negócios ou recursos adicionais, como catálogo digital, ainda não serão modificados por esta API. Para gerenciamento de novos negócios, utilize o Portal do Parceiro.

Listar horários

Você pode consultar todos os horários de funcionamento de uma loja utilizando o endpoint GET.

Criar horário de funcionamento

Para adicionar um novo horário de funcionamento, utilize o endpoint PUT. Lembre-se de fornecer os detalhes do horário no corpo da requisição.

Atenção Não recomendamos o uso do horário de funcionamento para determinar se o estabelecimento está aberto ou fechado para ações temporárias. Utilize a API de interrupções para gerenciar essa funcionalidade de forma mais precisa e eficiente.

Configuração dos horários

Este endpoint efetua uma alteração em massa nos horários de funcionamento da loja. É importante compreender como essa alteração afetará os horários existentes. Tenha cuidado ao utilizar este endpoint para garantir que os horários de funcionamento sejam configurados conforme desejado:

Se apenas os dias da semana forem fornecidos no corpo da requisição, os horários de sábado e domingo serão removidos, indicando que a loja estará fechada nesses dias, a menos que os horários sejam especificados separadamente.
Se apenas o horário de um dia específico for fornecido no corpo da requisição (por exemplo: segunda-feira), somente o horário da segunda-feira será atualizado. Todos os outros dias permanecerão sem horário de funcionamento especificado e serão considerados como fechados, caso nenhum horário tenha sido fornecido para esses dias no corpo da requisição.
Além disso, é importante notar que cada dia pode ter múltiplos horários configurados, contudo, certifique-se de que esses horários não se sobreponham ou interfiram uns com os outros dentro do mesmo dia.
Os horários devem sempre permanecer no intervalo de 00:00 a 23:59, garantindo que cada dia seja completo e não ultrapasse os limites do outro. Na nossa gestão, lidamos apenas com horas e minutos. Em cenários nos quais a loja opera de um dia para o outro, poderíamos ter um intervalo de 1 minuto entre 23:59 no final da última janela e 00:00 no início da próxima. Para evitar que a loja fique fechada durante esse intervalo, sempre adicionamos 59 segundos às janelas que vão até 23:59.

Configuração no Portal do Parceiro

Aqui está como a configuração dos horários aparece no Portal do Parceiro:

Corpo da Requisição

Os dados fornecidos no corpo da requisição determinam a configuração exibida no Portal do Parceiro:

{
  "storeId": "09e9a8c8-fda3-4991-acfc-43b15397caf6",
  "shifts": [
    {
      "dayOfWeek": "MONDAY",
      "start": "09:00:00",
      "duration": 360
    },
    {
      "dayOfWeek": "TUESDAY",
      "start": "09:00:00",
      "duration": 360
    },
    {
      "dayOfWeek": "WEDNESDAY",
      "start": "09:00:00",
      "duration": 360
    },
    {
      "dayOfWeek": "THURSDAY",
      "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
    }
  ]
}