Informações do Merchant

Esta seção contém informações sobre os endpoints de merchant da API OpenDelivery. Através destas rotas, é possível consultar informações completas sobre o estabelecimento, incluindo cardápio, serviços, horários e área de cobertura.

Visão Geral

O módulo de merchant permite que aplicações externas obtenham informações completas sobre um estabelecimento, seguindo o padrão OpenDelivery. Os dados retornados incluem informações básicas, serviços disponíveis (delivery, retirada e consumo no local), horários de funcionamento, área de cobertura, cardápio completo com categorias, itens, grupos de opcionais e disponibilidades.

Endpoints Principais

Método	Endpoint	Descrição
GET	/opendelivery/v1/merchant	Obtém informações completas do estabelecimento

Autenticação

Este endpoint utiliza autenticação via API Key.

Header Obrigatório

x-api-key: {sua_api_key}

Header	Tipo	Obrigatório	Descrição
x-api-key	string	Sim	Chave de API fornecida pela Goomer para integração com o hub

Importante: O endpoint de merchant é exclusivo para integradores do tipo Ordering Application registrados na plataforma Goomer.

Limites de Uso (Rate Limiting)

Este endpoint possui as seguintes restrições de uso:

Limite	Janela de Tempo
10 requisições	1 minuto

Quando o limite é excedido, a API retorna o código de status HTTP 429 (Too Many Requests).

Estrutura de Dados

Campos Raiz

Campo	Tipo	Descrição
lastUpdate	string (ISO 8601)	Data e hora da última atualização dos dados
TTL	number	Tempo de vida do cache em segundos (entre 500 e 86400)
id	string	Identificador único do merchant no formato {CNPJ}-{UUID}
status	string	Status do merchant: AVAILABLE ou UNAVAILABLE
basicInfo	object	Informações básicas do estabelecimento
services	array	Lista de serviços disponíveis
menus	array	Cardápios do estabelecimento
categories	array	Categorias de produtos
itemOffers	array	Ofertas de produtos (preços e disponibilidade)
items	array	Produtos disponíveis
optionGroups	array	Grupos de opcionais (complementos e adicionais)
availabilities	array	Disponibilidades especiais (horários diferenciados por item/categoria)

basicInfo

Campo	Tipo	Descrição
name	string	Nome público do estabelecimento
document	string	CNPJ (14 dígitos, sem formatação)
corporateName	string	Razão social
description	string	Descrição do estabelecimento
averageTicket	number (opcional)	Ticket médio em reais
averagePreparationTime	number	Tempo médio de preparo em minutos
minOrderValue	object	Valor mínimo do pedido { value, currency }
merchantType	string	Tipo do estabelecimento (sempre RESTAURANT)
merchantCategories	string[]	Categorias de culinária (ex: BURGERS, PIZZA, JAPANESE)
address	object	Endereço completo com coordenadas geográficas
contactEmails	string[]	Lista de e-mails de contato
contactPhones	object	Telefones de contato { commercialNumber, whatsappNumber? }
logoImage	object	URL da imagem de logo { URL }
bannerImage	object (opcional)	URL da imagem de banner { URL }
createdAt	string (ISO 8601)	Data de criação do estabelecimento
acceptedCards	string[]	Bandeiras e métodos de pagamento aceitos (ex: VISA, MASTERCARD, PIX)

services

Cada item do array de serviços representa um canal de atendimento (delivery, retirada ou consumo no local).

Campo	Tipo	Descrição
id	string (UUID)	Identificador único do serviço
status	string	Status do serviço: AVAILABLE ou UNAVAILABLE
serviceType	string	Tipo: DELIVERY, TAKEOUT ou INDOOR
serviceTiming	object (opcional)	Configuração de timing do serviço
serviceTiming.timing	string[]	Modos: INSTANT, SCHEDULED, ONDEMAND
serviceTiming.schedule	object (opcional)	Janelas de agendamento
servicePriority	string[] (opcional)	Prioridade do serviço: PRIORITY1 a PRIORITY5
menuId	string (UUID)	ID do cardápio associado a este serviço
targetAppId	string (UUID, opcional)	ID da aplicação destino
serviceArea	object (opcional)	Área de cobertura (apenas para DELIVERY)
serviceHours	object	Horários de funcionamento do serviço

menus

Campo	Tipo	Descrição
id	string (UUID)	Identificador único do cardápio
name	string	Nome do cardápio
description	string (opcional)	Descrição do cardápio
externalCode	string	Código externo para identificação no sistema do parceiro
disclaimer	string (opcional)	Aviso legal do cardápio
disclaimerURL	string (opcional)	URL com informações adicionais do aviso
categoryId	string[]	Lista de IDs das categorias pertencentes a este cardápio

categories

Campo	Tipo	Descrição
id	string (UUID)	Identificador único da categoria
index	number	Posição de ordenação da categoria no cardápio
name	string	Nome da categoria
description	string (opcional)	Descrição da categoria
image	object (opcional)	Imagem da categoria { URL }
externalCode	string	Código externo para identificação no sistema do parceiro
status	string	Status: AVAILABLE ou UNAVAILABLE
availabilityId	string[] (opcional)	IDs de disponibilidades especiais vinculadas
itemOfferId	string[] (opcional)	IDs das ofertas de itens pertencentes a esta categoria

itemOffers

Representa a oferta de um produto: seu preço atual, status e referências.

Campo	Tipo	Descrição
id	string (UUID)	Identificador único da oferta
itemId	string (UUID)	ID do item (produto) relacionado
index	number	Posição de ordenação dentro da categoria
status	string	Status: AVAILABLE ou UNAVAILABLE
price	object	Preço da oferta
price.value	number	Preço atual em reais
price.originalValue	number	Preço original (sem promoção) em reais
price.currency	string	Código da moeda (ISO 4217, ex: BRL)
availabilityId	string[] (opcional)	IDs de disponibilidades especiais vinculadas
optionGroupsId	string[] (opcional)	IDs dos grupos de opcionais disponíveis para este item

items

Campo	Tipo	Descrição
id	string (UUID)	Identificador único do item
name	string	Nome do produto
description	string	Descrição do produto
externalCode	string	Código externo para identificação no sistema do parceiro
status	string	Status: AVAILABLE ou UNAVAILABLE
image	object (opcional)	Imagem principal { URL }
images	array (opcional)	Lista de imagens com tipo: MAIN ou THUMB
nutritionalInfo	object (opcional)	Informações nutricionais e alérgenos
serving	number (opcional)	Porção/quantidade por unidade
unit	string	Unidade: UN, KG, L, OZ, LB ou GAL
ean	string (opcional)	Código de barras EAN

optionGroups

Campo	Tipo	Descrição
id	string (UUID)	Identificador único do grupo
index	number	Posição de ordenação
name	string	Nome do grupo (ex: "Escolha o tamanho")
description	string (opcional)	Descrição do grupo
externalCode	string	Código externo para identificação no sistema do parceiro
status	string	Status: AVAILABLE ou UNAVAILABLE
minPermitted	number	Quantidade mínima de opções que o cliente deve selecionar
maxPermitted	number	Quantidade máxima de opções que o cliente pode selecionar
priceMethod	string	Método de cálculo do preço: SUM (soma), MAX (maior valor) ou AVG (média)
options	array (opcional)	Lista de opções do grupo

availabilities

Define janelas de disponibilidade especiais que podem ser vinculadas a categorias ou itens.

Campo	Tipo	Descrição
id	string (UUID)	Identificador único da disponibilidade
startDate	string (opcional)	Data de início da vigência
endDate	string (opcional)	Data de fim da vigência
hours	array	Horários semanais de disponibilidade
hours[].dayOfWeek	string[]	Dias da semana: MONDAY, TUESDAY, ..., SUNDAY
hours[].timePeriods	object	Período: { startTime, endTime } no formato HH:mm:ss

Exemplo de Resposta

GET /opendelivery/v1/merchant

GET /opendelivery/v1/merchant HTTP/1.1
Host: partner-api.goomer.app
x-api-key: sua_api_key_aqui

{
  "lastUpdate": "2025-01-27T10:30:00.000Z",
  "TTL": 86400,
  "id": "12345678901234-550e8400-e29b-41d4-a716-446655440000",
  "status": "AVAILABLE",
  "basicInfo": {
    "name": "Restaurante Exemplo",
    "document": "12345678901234",
    "corporateName": "Restaurante Exemplo LTDA",
    "description": "Restaurante especializado em comida brasileira",
    "averageTicket": 45.50,
    "averagePreparationTime": 30,
    "minOrderValue": {
      "value": 20.00,
      "currency": "BRL"
    },
    "merchantType": "RESTAURANT",
    "merchantCategories": ["BRAZILIAN", "COMFORT_FOOD"],
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Centro",
      "street": "Rua Exemplo",
      "number": "123",
      "postalCode": "01234567",
      "complement": "Loja 5",
      "latitude": -23.5505,
      "longitude": -46.6333
    },
    "contactEmails": ["contato@restaurante.com.br"],
    "contactPhones": {
      "commercialNumber": "11999999999",
      "whatsappNumber": "11999999999"
    },
    "logoImage": {
      "URL": "https://example.com/logo.png"
    },
    "bannerImage": {
      "URL": "https://example.com/banner.png"
    },
    "createdAt": "2024-01-01T00:00:00.000Z",
    "acceptedCards": ["VISA", "MASTERCARD", "ELO", "PIX"]
  },
  "services": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "AVAILABLE",
      "serviceType": "DELIVERY",
      "serviceTiming": {
        "timing": ["INSTANT", "SCHEDULED"],
        "schedule": {
          "scheduleTimeWindow": "30_MINUTES",
          "scheduleStartWindow": "45_MINUTES",
          "scheduleEndWindow": "60_MINUTES"
        }
      },
      "servicePriority": ["PRIORITY1"],
      "menuId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "serviceArea": {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "geoRadius": {
          "geoMidpointLatitude": -23.5505,
          "geoMidpointLongitude": -46.6333,
          "radius": [
            {
              "size": 3000,
              "price": {
                "value": 5.00,
                "currency": "BRL"
              },
              "estimateDeliveryTime": 30
            }
          ]
        }
      },
      "serviceHours": {
        "id": "d4e5f6a7-b8c9-0123-def0-123456789abc",
        "weekHours": [
          {
            "dayOfWeek": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"],
            "timePeriods": {
              "startTime": "11:00:00",
              "endTime": "23:00:00"
            }
          },
          {
            "dayOfWeek": ["SATURDAY", "SUNDAY"],
            "timePeriods": {
              "startTime": "11:00:00",
              "endTime": "23:30:00"
            }
          }
        ],
        "holidayHours": []
      }
    },
    {
      "id": "e5f6a7b8-c9d0-1234-ef01-23456789abcd",
      "status": "AVAILABLE",
      "serviceType": "TAKEOUT",
      "serviceTiming": {
        "timing": ["INSTANT"],
        "schedule": {
          "scheduleTimeWindow": "15_MINUTES",
          "scheduleStartWindow": "30_MINUTES",
          "scheduleEndWindow": "45_MINUTES"
        }
      },
      "menuId": "f6a7b8c9-d0e1-2345-f012-3456789abcde",
      "serviceHours": {
        "id": "a7b8c9d0-e1f2-3456-0123-456789abcdef",
        "weekHours": [
          {
            "dayOfWeek": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"],
            "timePeriods": {
              "startTime": "11:00:00",
              "endTime": "23:00:00"
            }
          }
        ],
        "holidayHours": []
      }
    }
  ],
  "menus": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Cardápio Principal",
      "description": "Cardápio completo do restaurante",
      "externalCode": "1",
      "categoryId": [
        "cat-uuid-001",
        "cat-uuid-002"
      ]
    }
  ],
  "categories": [
    {
      "id": "cat-uuid-001",
      "index": 1,
      "name": "Hambúrgueres",
      "description": "Nossos hambúrgueres artesanais",
      "externalCode": "101",
      "status": "AVAILABLE",
      "itemOfferId": [
        "offer-uuid-001",
        "offer-uuid-002"
      ]
    },
    {
      "id": "cat-uuid-002",
      "index": 2,
      "name": "Bebidas",
      "externalCode": "102",
      "status": "AVAILABLE",
      "itemOfferId": [
        "offer-uuid-003"
      ]
    }
  ],
  "itemOffers": [
    {
      "id": "offer-uuid-001",
      "itemId": "item-uuid-001",
      "index": 1,
      "status": "AVAILABLE",
      "price": {
        "value": 32.90,
        "originalValue": 32.90,
        "currency": "BRL"
      },
      "optionGroupsId": [
        "group-uuid-001"
      ]
    },
    {
      "id": "offer-uuid-002",
      "itemId": "item-uuid-002",
      "index": 2,
      "status": "AVAILABLE",
      "price": {
        "value": 28.90,
        "originalValue": 35.90,
        "currency": "BRL"
      }
    },
    {
      "id": "offer-uuid-003",
      "itemId": "item-uuid-003",
      "index": 1,
      "status": "AVAILABLE",
      "price": {
        "value": 8.00,
        "originalValue": 8.00,
        "currency": "BRL"
      }
    }
  ],
  "items": [
    {
      "id": "item-uuid-001",
      "name": "X-Burguer Clássico",
      "description": "Pão brioche, carne 180g, queijo cheddar, alface e tomate",
      "externalCode": "P001",
      "status": "AVAILABLE",
      "images": [
        {
          "URL": "https://example.com/xburguer.jpg",
          "type": "MAIN"
        }
      ],
      "nutritionalInfo": {
        "description": "Hambúrguer artesanal",
        "calories": "650 Cal",
        "allergen": ["GLUTEN", "MILK", "EGG"],
        "isAlcoholic": false
      },
      "unit": "UN"
    },
    {
      "id": "item-uuid-002",
      "name": "X-Burguer Duplo",
      "description": "Pão brioche, duas carnes 180g, queijo cheddar duplo",
      "externalCode": "P002",
      "status": "AVAILABLE",
      "unit": "UN"
    },
    {
      "id": "item-uuid-003",
      "name": "Refrigerante Lata",
      "description": "Escolha entre Coca-Cola, Guaraná ou Sprite",
      "externalCode": "B001",
      "status": "AVAILABLE",
      "unit": "UN"
    }
  ],
  "optionGroups": [
    {
      "id": "group-uuid-001",
      "index": 1,
      "name": "Ponto da carne",
      "externalCode": "G001",
      "status": "AVAILABLE",
      "minPermitted": 1,
      "maxPermitted": 1,
      "priceMethod": "SUM",
      "options": [
        {
          "id": "opt-uuid-001",
          "itemId": "item-uuid-opt-001",
          "index": 1,
          "status": "AVAILABLE",
          "price": {
            "value": 0.00,
            "originalValue": 0.00,
            "currency": "BRL"
          },
          "maxPermitted": 1
        },
        {
          "id": "opt-uuid-002",
          "itemId": "item-uuid-opt-002",
          "index": 2,
          "status": "AVAILABLE",
          "price": {
            "value": 0.00,
            "originalValue": 0.00,
            "currency": "BRL"
          },
          "maxPermitted": 1
        }
      ]
    }
  ],
  "availabilities": []
}

Códigos de Status

Código	Descrição
200	Sucesso
400	Requisição inválida
401	API Key inválida ou ausente
429	Limite de requisições excedido
500	Erro interno do servidor

Cache e TTL

O endpoint retorna dois campos relacionados ao cache dos dados:

• TTL: Tempo sugerido (em segundos) para que o parceiro armazene a resposta em cache local. Varia entre 500 e 86400 segundos (de ~8 minutos a 24 horas).
• lastUpdate: Timestamp da última vez que os dados do merchant foram atualizados. Utilize este campo para verificar se sua cópia local está desatualizada.

Recomendamos que parceiros implementem cache local respeitando o TTL retornado para reduzir o número de requisições e evitar atingir o limite de rate limiting.

Documentação Completa

Para informações detalhadas sobre parâmetros, payload e exemplos adicionais, consulte a documentação técnica completa.