Dados da Loja¶

Capability merchant Merchant · identidade e services

Especificação da API

O contrato implementável está na especificação de Merchant — somente em inglês.

Parte da capability Merchant. O cardápio está em Menus.

Merchant ID — gerado pelo originador¶

Quebra em relação à V1

Na V1 o merchantId vinha do Software Service (PDV). Na V2 o merchantId é gerado pela Ordering Application no cadastro. O PDV guarda o próprio código em externalCode.

sequenceDiagram
 participant OA as Ordering Application
 participant SS as Software Service

 OA->>OA: gera merchantId
 OA->>SS: cadastro / integração com id + externalCode
 Note over OA,SS: mesmo merchantId em todas as ops
 SS->>OA: GET /merchants/{merchantId} (ou OA consome catálogo)

Motivos: eliminar round-trip só para obter ID; referência determinística desde a criação; reconciliação multi-plataforma mais simples.

O merchantId DEVE ser único no escopo da Ordering Application (UUID v4 recomendado).

Identidade e basic info¶

Campos descritivos (nome, endereço, contatos, logo, etc.) via:

Objetivo	Operação
Ler loja	`GET /merchants/{merchantId}`
Atualizar parcial	`PATCH /merchants/{merchantId}`
Listar lojas do token	`GET /merchants`

PATCH — atualizar loja¶

O endpoint PATCH permite atualizar: - externalCode — Novo em V2: agora o Software Service pode atualizar o código interno da loja - name, description, logoUrl — identidade básica - contacts — contatos (telefone, email, etc.)

Resposta: 202 (processamento assíncrono).

merchantType da V1 não existe na V2.

Serviço (`Service`)¶

Cada estabelecimento pode ter múltiplos services. O identificador é o tipo — não há service id separado.

Campo	Obrigatório	Descrição
`type`	SIM	`DELIVERY`, `TAKEOUT` ou `INDOOR`
`status`	SIM	`OPEN`, `CLOSED` ou `PAUSED`
`operatingHours`	SIM (quando aplicável)	Horários por dia da semana
`deliveryArea`	NÃO	Raio ou polígono (`DELIVERY`)
`menuId`	NÃO	Menu ativo — ver Menus
`pauseUntil`	NÃO	Retomada automática se `PAUSED`

GET|PUT|PATCH /merchants/{merchantId}/services/{serviceType}

Estados¶

stateDiagram-v2
 [*] --> OPEN
 OPEN --> PAUSED: POST …/pause
 PAUSED --> OPEN: fim da duração ou PATCH OPEN
 OPEN --> CLOSED: horário / operador
 CLOSED --> OPEN: horário / operador

Status	Significado
`OPEN`	Aceitando pedidos naquele service
`CLOSED`	Fora de horário ou offline do service
`PAUSED`	Pausa operacional temporária

Pausa¶

POST /merchants/{merchantId}/services/{serviceType}/pause

Body: durationMinutes (obrigatório), reason (opcional). Resposta 202.
Não reescreve operatingHours. Retomada: expiração ou PATCH com status: OPEN.

sequenceDiagram
 participant OA as Ordering Application
 participant SS as Software Service

 OA->>SS: POST …/services/DELIVERY/pause { durationMinutes: 30 }
 SS-->>OA: 202 Accepted
 Note over SS: status PAUSED, pauseUntil set
 OA->>SS: PATCH …/services/DELIVERY { status: OPEN }
 SS-->>OA: 202 Accepted

Mapa de operações (loja)¶

Objetivo	operationId
Listar merchants	`listMerchants`
Detalhe da loja	`getMerchant`
Atualizar basic info	`updateMerchant`
Ler service	`getService`
Substituir service	`replaceService`
Atualizar service	`updateService`
Pausar	`pauseService`

Checklists¶

Checklist — Ordering Application

[ ] Gera e mantém merchantId estável
[ ] Correlação com PDV via externalCode
[ ] Consome services por tipo
[ ] Trata pause sem confundir com horário de funcionamento

Checklist — Software Service

[ ] Hospeda GET/PATCH de loja e services
[ ] Aceita merchantId do originador
[ ] POST …/pause → PAUSED + pauseUntil
[ ] Não usa merchantType