Pular para o conteúdo

Dados do merchant

Requisição

Host: Software Service. A Keeta chama este endpoint para obter dados básicos, serviços e cardápio completo. Pode exigir apiKey (decisão sua).

Todo item precisa ter preço de delivery ou de retirada; item apenas com preço indoor não é aceito.

Campos de primeiro nível da resposta 200:

CampoTipoObrig.Observação Keeta
idstringsimID do merchant no seu sistema
statusstringsimAVAILABLE / UNAVAILABLE
basicInfoobjectsimVer abaixo
services[]arraysimKeeta só usa serviceType=DELIVERY
menus[], categories[], itemOffers[], items[]arraysimCardápio
optionGroups[], availabilities[]arraynãoComplementos e disponibilidade
lastUpdate, TTLstring / integernãoIgnorados pela Keeta

basicInfo — Campos considerados pela Keeta: contactEmails[] (até 3, obrigatório), contactPhones.commercialNumber (obrigatório, com DDD, ex.: 55-11999999999). Ignorados: name, document, corporateName, description, averageTicket, averagePreparationTime, minOrderValue, merchantType, merchantCategories, address, contactPhones.whatsappNumber, logoImage, bannerImage, acceptedCards.

Formato de endereço (quando aplicável): country (BR), state (BR-SP, ISO 3166-2), city, district (bairro), street, number, postalCode (CEP, 01310-100), complement, reference, latitude, longitude.

services[]

CampoDescrição
id (obrig.), statusIdentificador e status do serviço. O campo status de services[] é ignorado pela Keeta
serviceType (obrig.)DELIVERY (único suportado pela Keeta), TAKEOUT, INDOOR
menuId (obrig.)Menu associado
serviceHours (obrig.)id, weekHours[] (dayOfWeek[] + timePeriods{startTime,endTime}), holidayHours[] (date + timePeriods) — tudo em UTC+0
serviceAreaIgnorado pela Keeta. No padrão Open Delivery, é obrigatório para DELIVERY: polygon[] (geoCoordinates[], price, estimateDeliveryTime) ou geoRadius (geoMidpointLatitude, geoMidpointLongitude, radius[]), mais exclusionAreaPolygon[]
serviceTiming, servicePriority, targetAppIdTodos estes campos são ignorados pela Keeta

menus[]: id, name, externalCode, categoryId[] (obrigatórios); description. disclaimer e disclaimerURL são ignorados.

categories[]: id, index, name, externalCode, status, itemOfferId[] (obrigatórios); description, image{URL, CRC-32}, availabilityId[]. O status de categoria hoje não é processado.

itemOffers[]: id, itemId, index, status, price (obrigatórios); availabilityId[], optionGroupsId[]. Em price: originalValue (obrig.), value (preço com desconto). O campo currency é ignorado — a moeda é a da região da loja (BRL no Brasil).

items[]: id, name, externalCode (código PDV), status (obrigatórios); description, image, images[] (type: main/thumb), nutritionalInfo (description, calories, allergen[], additives[], suitableDiet[], isAlcoholic), serving, unit. Para items[].unit do cardápio, a Keeta suporta atualmente apenas UN; KG, L, OZ, LB e GAL não são suportados. ean é ignorado.

optionGroups[]: id, index, name, externalCode, status, minPermitted, maxPermitted (obrigatórios); description, options[] (id, itemId, index, status, price). priceMethod e options[].maxPermitted são ignorados.

Se um grupo ficar com menos opções disponíveis do que o minPermitted, ele se torna impossível de preencher e todos os itens que o usam somem do app.

availabilities[]: id, hours[] (dayOfWeek[] + timePeriods). startDate/endDate são ignorados; não combine faixa de datas com agenda semanal.

Exemplo resumido (lanchonete em São Paulo):

{
  "id": "LOJA-SP-001",
  "status": "AVAILABLE",
  "basicInfo": {
    "contactEmails": ["operacao@lanchonetemoema.com.br"],
    "contactPhones": { "commercialNumber": "55-11987654321" }
  },
  "services": [{
    "id": "svc-delivery",
    "serviceType": "DELIVERY",
    "menuId": "menu-principal",
    "serviceHours": {
      "id": "sh-1",
      "weekHours": [
        { "dayOfWeek": ["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY"], "timePeriods": { "startTime": "14:00:00.000Z", "endTime": "23:59:00.000Z" } },
        { "dayOfWeek": ["TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY"], "timePeriods": { "startTime": "00:00:00.000Z", "endTime": "02:00:00.000Z" } }
      ]
    }
  }],
  "menus": [{ "id": "menu-principal", "name": "Cardápio", "externalCode": "M1", "categoryId": ["cat-salgados"] }],
  "categories": [{ "id": "cat-salgados", "index": 0, "name": "Salgados", "externalCode": "C10", "status": "AVAILABLE", "itemOfferId": ["of-coxinha"] }],
  "itemOffers": [{ "id": "of-coxinha", "itemId": "it-coxinha", "index": 0, "status": "AVAILABLE",
                   "price": { "originalValue": 8.5, "value": 7.9 }, "optionGroupsId": ["og-molho"] }],
  "items": [
    { "id": "it-coxinha", "name": "Coxinha de frango com catupiry", "externalCode": "PDV-1001", "status": "AVAILABLE", "unit": "UN" },
    { "id": "it-molho-pimenta", "name": "Molho de pimenta", "externalCode": "PDV-9001", "status": "AVAILABLE", "unit": "UN" }
  ],
  "optionGroups": [{ "id": "og-molho", "index": 0, "name": "Molho extra", "externalCode": "G20", "status": "AVAILABLE",
                     "minPermitted": 0, "maxPermitted": 1,
                     "options": [{ "id": "op-pimenta", "itemId": "it-molho-pimenta", "index": 0, "status": "AVAILABLE", "price": { "originalValue": 1.0 } }] }]
}

Loja aberta de segunda a sexta, das 11:00 às 23:00 em horário de Brasília → convertido para UTC+0 e dividido na virada do dia.

Respostas: 200, 403, 404, 503.

Segurança
apiKey
curl -i -X GET \
  https://api.example.com/v1/merchant \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Respostas

Successful returns Merchant information.

Corpoapplication/json
lastUpdatestring, (date-time)

Data e hora da última alteração no formato ISO, armazenadas como string. Use em conjunto com TTL para atualizar as informações do aplicativo de pedidos. Data e hora em UTC no formato ISO.

A Keeta não suporta este campo e o ignora.

Exemplo:"2021-05-27T20:45:10.332Z"
TTLinteger

Tempo de vida, em segundos.

  • Mínimo: 500
  • Máximo: 86400

Faça uma nova solicitação quando o TTL expirar.

A Keeta não suporta este campo e o ignora.

Exemplo:500
idstring, [ 36 .. 100 ] charactersobrigatório

Identificador único do merchant nos sistemas com os quais ele se comunica. Este ID deve ser gerado pelo Software Service do merchant.

O Software Service deve garantir que o merchantId seja único. Recomenda-se usar um UUID quando isso não for possível.

Exemplo:"22815773000169-dbc7e35a-c936-4665-9e13-eb55eb8b6824"
statusstringobrigatório

Indica se o merchant está disponível ou indisponível. Use para fechar o merchant devido a um evento inesperado, quando não houver previsão de restabelecimento do serviço. Não use para feriados.

Enum:"AVAILABLE""UNAVAILABLE"
Exemplo:"AVAILABLE"
basicInfoobject(BasicInfo)obrigatório

Entidade obrigatória com as informações básicas do merchant.

servicesArray of objects(Service)obrigatório

Entidade obrigatória com os detalhes dos serviços de pedidos do merchant.

menusArray of objects(Menu)obrigatório

Entidade obrigatória que descreve os menus do merchant.

categoriesArray of objects(Category)obrigatório

Entidade obrigatória que descreve as categorias do menu onde as ItemOffers serão exibidas.

itemOffersArray of objects(ItemOffer)obrigatório

Entidade obrigatória que descreve as ofertas dos Items.

itemsArray of objects(Item)obrigatório

Entidade obrigatória que descreve os itens usados por uma ItemOffer ou Option.

optionGroupsArray of objects(Option Group)

Entidade opcional que descreve opções adicionais de uma ItemOffer.

availabilitiesArray of objects(Availability)

Entidade opcional que descreve o período em que uma Category ou ItemOffer é atendida.

Observação: o modelo de menu aceita uma faixa definida por startDate e endDate ou uma agenda semanal em hours. Não combine as duas opções.

Resposta
{ "lastUpdate": "2021-05-27T20:45:10.332Z", "TTL": 500, "id": "22815773000169-dbc7e35a-c936-4665-9e13-eb55eb8b6824", "status": "AVAILABLE", "basicInfo": { "name": "Pizza Plaza", "document": "22815773000169", "corporateName": "Food Company", "description": "Food company specializing in pizzas.", "averageTicket": 90, "averagePreparationTime": 20, "minOrderValue": { … }, "merchantType": "RESTAURANT", "merchantCategories": [ … ], "address": { … }, "contactEmails": [ … ], "contactPhones": { … }, "logoImage": { … }, "bannerImage": { … }, "createdAt": "2021-05-10T20:45:10.332Z" }, "services": [ { … } ], "items": [ { … }, { … }, { … }, { … }, { … } ], "menus": [ { … } ], "categories": [ { … }, { … } ], "itemOffers": [ { … }, { … } ], "optionGroups": [ { … }, { … } ], "availabilities": [ { … } ] }