{
 "openapi": "3.1.0",
 "info": {
  "title": "Chamejar — API de integração",
  "version": "1.0.0",
  "description": "API REST do Chamejar para integrar o seu restaurante a outros sistemas: cardápio, clientes, pedidos, pagamentos, PDV, mesas, cozinha, impressão, entregas, estoque, financeiro, relatórios, fiscal e marketplaces.\n\n- **Autenticação:** `Authorization: Bearer <token>`. Gere o token no painel em Configurações → APIs → Gerar meu token.\n- **Unidade:** quase todas as rotas exigem o cabeçalho `X-Location-Id` com o id da unidade.\n- **Idempotência:** comandos críticos exigem `Idempotency-Key` (até 160 caracteres). Reenviar a mesma chave devolve a resposta original com `Idempotency-Replayed: true`; a mesma chave com outro conteúdo devolve 409.\n- **Valores:** campos terminados em `_minor` estão em centavos (BRL).\n- **Erros:** `{\"error\": {\"code\", \"message\", \"details\"}, \"meta\": {\"correlation_id\"}}`.\n- **Limite:** 60 requisições por minuto por usuário do painel (os tokens do mesmo usuário somam).\n\nDocumentação completa em pt-BR: https://chamejar.com.br/api.html",
  "x-versao-do-contrato": "1.0.0-wave9"
 },
 "servers": [
  {
   "url": "{endereco}/api/v1",
   "variables": {
    "endereco": {
     "default": "https://endereco-do-seu-chamejar",
     "description": "Endereço do seu Chamejar, o mesmo do painel, sem /api/v1"
    }
   }
  }
 ],
 "paths": {
  "/health": {
   "get": {
    "operationId": "getHealth",
    "summary": "Verificar se o serviço está no ar",
    "tags": [
     "Plataforma"
    ],
    "responses": {
     "200": {
      "description": "Processo HTTP ativo",
      "headers": {
       "X-Correlation-Id": {
        "$ref": "#/components/headers/CorrelationId"
       },
       "X-API-Version": {
        "$ref": "#/components/headers/ApiVersion"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/HealthResponse"
        },
        "examples": {
         "real": {
          "summary": "Resposta real (dados fictícios da demonstração)",
          "value": {
           "data": {
            "status": "ok",
            "service": "Chamejar",
            "version": "v1",
            "time": "2026-11-12T16:29:52-03:00"
           },
           "meta": {
            "correlation_id": "a27c133f-0c8e-4818-aaaa-95b642290b2c"
           }
          }
         }
        }
       }
      }
     }
    },
    "description": "Liveness da aplicação",
    "security": []
   }
  },
  "/readiness": {
   "get": {
    "operationId": "getReadiness",
    "summary": "Verificar se banco, cache e fila estão prontos",
    "tags": [
     "Plataforma"
    ],
    "responses": {
     "200": {
      "description": "Dependências disponíveis",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ReadinessResponse"
        }
       }
      }
     },
     "503": {
      "description": "Uma ou mais dependências indisponíveis ou degradadas",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ReadinessResponse"
        }
       }
      }
     }
    },
    "description": "Banco, cache e fila prontos para tráfego",
    "security": []
   }
  },
  "/store": {
   "get": {
    "operationId": "getCurrentStore",
    "summary": "Consultar dados e horários da unidade",
    "description": "Perfil e horários semanais da unidade selecionada\n\nExige `catalog:read` e `X-Location-Id`. Os horários são a grade cadastrada; exceções e disponibilidade no instante da consulta devem ser confirmadas antes de prometer entrega.\n\n**Escopo:** `catalog:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Perfil da unidade e horários por tipo de atendimento",
      "content": {
       "application/json": {
        "examples": {
         "real": {
          "summary": "Resposta real (dados fictícios da demonstração)",
          "value": {
           "data": {
            "id": 1,
            "name": "Pizzaria Brasa Viva",
            "description": "Pizzaria fictícia usada nas telas de demonstração.",
            "telephone": "(91) 3000-0000",
            "enabled": true,
            "address": {
             "line_1": "Travessa das Mangueiras, 120",
             "line_2": null,
             "city": "Belém",
             "state": "PA",
             "postcode": "66000-000",
             "country_id": 32
            },
            "weekly_hours": [
             {
              "type": "opening",
              "weekday": 0,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "opening",
              "weekday": 1,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "opening",
              "weekday": 2,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "opening",
              "weekday": 3,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "opening",
              "weekday": 4,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "opening",
              "weekday": 5,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "opening",
              "weekday": 6,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "delivery",
              "weekday": 0,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "delivery",
              "weekday": 1,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "delivery",
              "weekday": 2,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "delivery",
              "weekday": 3,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "delivery",
              "weekday": 4,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "delivery",
              "weekday": 5,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "delivery",
              "weekday": 6,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "collection",
              "weekday": 0,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "collection",
              "weekday": 1,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "collection",
              "weekday": 2,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "collection",
              "weekday": 3,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "collection",
              "weekday": 4,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "collection",
              "weekday": 5,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             },
             {
              "type": "collection",
              "weekday": 6,
              "opens_at": "00:00:00",
              "closes_at": "23:59:00",
              "enabled": true
             }
            ],
            "updated_at": "2026-11-09T21:51:42.000000Z"
           }
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     }
    },
    "tags": [
     "Plataforma"
    ],
    "x-escopos": [
     "catalog:read"
    ]
   }
  },
  "/catalog/menus": {
   "get": {
    "operationId": "listMenus",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     },
     {
      "name": "search",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "channel",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "all",
        "pos",
        "delivery",
        "table",
        "marketplace",
        "kiosk"
       ]
      }
     },
     {
      "name": "at",
      "in": "query",
      "description": "Instante ISO-8601 usado para avaliação determinística",
      "schema": {
       "type": "string",
       "format": "date-time"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Cardápio efetivo",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaginatedMenus"
        },
        "examples": {
         "real": {
          "summary": "Resposta real (dados fictícios da demonstração)",
          "value": {
           "data": [
            {
             "id": 2,
             "name": "Pizza Calabresa G",
             "description": "Calabresa fatiada, cebola roxa e azeitonas.",
             "price_minor": 5490,
             "currency": "BRL",
             "available": true,
             "priority": 1,
             "image_url": "http://localhost:8092/storage/media/attachments/public/6af/42b/668/6af42b66831c8537261537.jpg",
             "categories": [
              {
               "id": 1,
               "name": "Pizzas"
              }
             ],
             "location_id": 1,
             "options": [
              {
               "id": 2,
               "option_id": 1,
               "name": "Borda",
               "display_type": "radio",
               "is_required": true,
               "min_selected": 1,
               "max_selected": 1,
               "values": [
                {
                 "id": 5,
                 "option_value_id": 1,
                 "name": "Sem borda",
                 "price_minor": 0,
                 "currency": "BRL",
                 "is_default": true
                },
                {
                 "id": 6,
                 "option_value_id": 2,
                 "name": "Catupiry",
                 "price_minor": 990,
                 "currency": "BRL",
                 "is_default": false
                },
                {
                 "id": 7,
                 "option_value_id": 3,
                 "name": "Cheddar",
                 "price_minor": 990,
                 "currency": "BRL",
                 "is_default": false
                },
                {
                 "id": 8,
                 "option_value_id": 4,
                 "name": "Chocolate",
                 "price_minor": 1190,
                 "currency": "BRL",
                 "is_default": false
                }
               ]
              }
             ]
            }
           ],
           "meta": {
            "correlation_id": "e6462312-aca6-4272-9748-117cd346bb35",
            "current_page": 1,
            "per_page": 2,
            "total": 1,
            "last_page": 1
           }
          }
         }
        }
       }
      }
     }
    },
    "summary": "Listar produtos do cardápio",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:read`.",
    "x-escopos": [
     "catalog:read"
    ]
   },
   "post": {
    "operationId": "createMenu",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/MenuInput"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Criado"
     }
    },
    "summary": "Criar produto",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "catalog:write"
    ]
   }
  },
  "/catalog/export": {
   "get": {
    "operationId": "exportCatalog",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "include_disabled",
      "in": "query",
      "schema": {
       "type": "boolean"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Snapshot versionado do catálogo da unidade"
     }
    },
    "summary": "Exportar o catálogo da unidade",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:read`.",
    "x-escopos": [
     "catalog:read"
    ]
   }
  },
  "/catalog/import/preview": {
   "post": {
    "operationId": "previewCatalogImport",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CatalogImportInput"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Plano de importação sem alteração persistida"
     }
    },
    "summary": "Simular importação de catálogo",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:read`.",
    "x-escopos": [
     "catalog:read"
    ]
   }
  },
  "/catalog/import": {
   "post": {
    "operationId": "applyCatalogImport",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CatalogImportInput"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Importação aplicada atomicamente"
     },
     "409": {
      "description": "Preview não confirmado"
     },
     "422": {
      "description": "Preview contém erros"
     }
    },
    "summary": "Importar catálogo",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "catalog:write"
    ]
   }
  },
  "/catalog/categories": {
   "get": {
    "operationId": "listCategories",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     }
    ],
    "responses": {
     "200": {
      "description": "Categorias",
      "content": {
       "application/json": {
        "examples": {
         "real": {
          "summary": "Resposta real (dados fictícios da demonstração)",
          "value": {
           "data": [
            {
             "id": 1,
             "name": "Pizzas",
             "description": "",
             "parent_id": null
            },
            {
             "id": 2,
             "name": "Lanches",
             "description": "",
             "parent_id": null
            },
            {
             "id": 3,
             "name": "Pratos",
             "description": "",
             "parent_id": null
            },
            {
             "id": 4,
             "name": "Porções",
             "description": "",
             "parent_id": null
            },
            {
             "id": 5,
             "name": "Bebidas",
             "description": "",
             "parent_id": null
            },
            {
             "id": 6,
             "name": "Sobremesas",
             "description": "",
             "parent_id": null
            }
           ],
           "meta": {
            "correlation_id": "4c8b7898-923c-46bb-9cdf-4dbb7e802a38",
            "current_page": 1,
            "per_page": 25,
            "total": 6,
            "last_page": 1
           }
          }
         }
        }
       }
      }
     }
    },
    "summary": "Listar categorias",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:read`.",
    "x-escopos": [
     "catalog:read"
    ]
   },
   "post": {
    "operationId": "createCategory",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "responses": {
     "201": {
      "description": "Categoria criada"
     }
    },
    "summary": "Criar categoria",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "catalog:write"
    ]
   }
  },
  "/catalog/options": {
   "get": {
    "operationId": "listOptions",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     }
    ],
    "responses": {
     "200": {
      "description": "Grupos globais de opções; preços e IDs de escolha específicos do produto vêm em /catalog/menus/{menu}"
     }
    },
    "summary": "Listar grupos de opções",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:read`.",
    "x-escopos": [
     "catalog:read"
    ]
   },
   "post": {
    "operationId": "createMenuOption",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "responses": {
     "201": {
      "description": "Grupo de opções criado"
     }
    },
    "summary": "Criar grupo de opções",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "catalog:write"
    ]
   }
  },
  "/customers": {
   "get": {
    "operationId": "listCustomers",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     }
    ],
    "responses": {
     "200": {
      "description": "Clientes com PII autorizada"
     }
    },
    "summary": "Listar clientes",
    "tags": [
     "Clientes"
    ],
    "description": "**Escopo:** `customers:read`.",
    "x-escopos": [
     "customers:read"
    ]
   },
   "post": {
    "operationId": "createCustomer",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "responses": {
     "200": {
      "description": "Cadastro existente vinculado à unidade"
     },
     "201": {
      "description": "Criado"
     },
     "422": {
      "description": "Dados inválidos ou cadastro que exige conferência"
     }
    },
    "summary": "Cadastrar cliente",
    "tags": [
     "Clientes"
    ],
    "description": "**Escopo:** `customers:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "customers:write"
    ]
   }
  },
  "/customers/lookup": {
   "get": {
    "operationId": "lookupCustomerByTelephone",
    "summary": "Buscar cliente pelo telefone",
    "description": "Busca exata de cliente por telefone com DDD\n\nAceita números com ou sem código 55 e pontuação. Retorna apenas clientes vinculados à unidade, até 10 correspondências. Não usa busca parcial para identificar o comprador.\n\n**Escopo:** `customers:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "telephone",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "minLength": 10,
       "maxLength": 32
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Clientes da unidade com o telefone exato"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "tags": [
     "Clientes"
    ],
    "x-escopos": [
     "customers:read"
    ]
   }
  },
  "/orders": {
   "get": {
    "operationId": "listOrders",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     }
    ],
    "responses": {
     "200": {
      "description": "Pedidos da unidade",
      "content": {
       "application/json": {
        "examples": {
         "real": {
          "summary": "Resposta real (dados fictícios da demonstração)",
          "value": {
           "data": [
            {
             "id": 6830,
             "location_id": 1,
             "customer_id": null,
             "state": "accepted",
             "state_version": 2,
             "total_minor": 7970,
             "currency": "BRL",
             "payment": "cash",
             "paid": false,
             "total_items": 2,
             "order_type": "collection",
             "created_at": "2026-11-12T19:29:54.000000Z",
             "items": [
              {
               "id": 4868,
               "menu_id": 2,
               "name": "Pizza Calabresa G",
               "quantity": 1,
               "unit_price_minor": 5490,
               "subtotal_minor": 6480,
               "option_values": [
                6
               ]
              },
              {
               "id": 4869,
               "menu_id": 17,
               "name": "Refrigerante Cola 2L",
               "quantity": 1,
               "unit_price_minor": 1490,
               "subtotal_minor": 1490,
               "option_values": []
              }
             ],
             "totals": [
              {
               "code": "subtotal",
               "title": "Subtotal",
               "amount_minor": 7970
              },
              {
               "code": "total",
               "title": "Total do pedido",
               "amount_minor": 7970
              }
             ]
            },
            {
             "id": 6829,
             "location_id": 1,
             "customer_id": null,
             "state": "preparing",
             "state_version": 3,
             "total_minor": 6480,
             "currency": "BRL",
             "payment": "cash",
             "paid": false,
             "total_items": 1,
             "order_type": "collection",
             "created_at": "2026-11-12T19:29:39.000000Z",
             "items": [
              {
               "id": 4867,
               "menu_id": 2,
               "name": "Pizza Calabresa G",
               "quantity": 1,
               "unit_price_minor": 5490,
               "subtotal_minor": 6480,
               "option_values": [
                6
               ]
              }
             ],
             "totals": [
              {
               "code": "subtotal",
               "title": "Subtotal",
               "amount_minor": 6480
              },
              {
               "code": "total",
               "title": "Total do pedido",
               "amount_minor": 6480
              }
             ]
            }
           ],
           "meta": {
            "correlation_id": "1892e56e-52fa-4a18-acfc-7c1da6edbc9c",
            "current_page": 1,
            "per_page": 2,
            "total": 2031,
            "last_page": 1016
           }
          }
         }
        }
       }
      }
     }
    },
    "summary": "Listar pedidos",
    "tags": [
     "Pedidos"
    ],
    "description": "**Escopo:** `orders:read`.",
    "x-escopos": [
     "orders:read"
    ]
   },
   "post": {
    "operationId": "createOrder",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/OrderInput"
       },
       "examples": {
        "real": {
         "summary": "Requisição usada na demonstração",
         "value": {
          "order_type": "collection",
          "items": [
           {
            "menu_id": 2,
            "quantity": 1,
            "option_values": [
             6
            ],
            "comment": "Bem assada"
           },
           {
            "menu_id": 17,
            "quantity": 1
           }
          ],
          "first_name": "Marina",
          "last_name": "Exemplo",
          "telephone": "(91) 90000-0000",
          "email": "marina@example.com",
          "payment": "cash",
          "expected_total_minor": 7970
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Pedido criado",
      "content": {
       "application/json": {
        "examples": {
         "real": {
          "summary": "Resposta real (dados fictícios da demonstração)",
          "value": {
           "data": {
            "id": 6830,
            "location_id": 1,
            "customer_id": null,
            "state": "placed",
            "state_version": 1,
            "total_minor": 7970,
            "currency": "BRL",
            "payment": "cash",
            "paid": false,
            "total_items": 2,
            "order_type": "collection",
            "created_at": "2026-11-12T19:29:54.000000Z",
            "items": [
             {
              "id": 4868,
              "menu_id": 2,
              "name": "Pizza Calabresa G",
              "quantity": 1,
              "unit_price_minor": 5490,
              "subtotal_minor": 6480,
              "option_values": [
               6
              ]
             },
             {
              "id": 4869,
              "menu_id": 17,
              "name": "Refrigerante Cola 2L",
              "quantity": 1,
              "unit_price_minor": 1490,
              "subtotal_minor": 1490,
              "option_values": []
             }
            ],
            "totals": [
             {
              "code": "subtotal",
              "title": "Subtotal",
              "amount_minor": 7970
             },
             {
              "code": "total",
              "title": "Total do pedido",
              "amount_minor": 7970
             }
            ]
           }
          }
         }
        }
       }
      }
     }
    },
    "summary": "Criar pedido",
    "tags": [
     "Pedidos"
    ],
    "description": "**Escopo:** `orders:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "orders:write"
    ]
   }
  },
  "/checkout-methods": {
   "get": {
    "operationId": "listOnlineCheckoutMethods",
    "summary": "Listar meios de checkout online ativos",
    "description": "Gateways online ativos para Pix e checkout hospedado\n\nRequer `payments:read`. Os códigos retornados podem ser usados em `payment` ao criar o pedido.\n\n**Escopo:** `payments:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Lista de gateways online habilitados, sem credenciais"
     }
    },
    "tags": [
     "Pagamentos"
    ],
    "x-escopos": [
     "payments:read"
    ]
   }
  },
  "/orders/quote": {
   "post": {
    "operationId": "quoteOrder",
    "summary": "Cotar pedido (itens, adicionais, cupom e entrega)",
    "description": "Cotação canônica de itens, adicionais, cupom e entrega\n\nRequer `orders:read`. Para entrega, informe `customer_id` e `address_id` de um endereço cadastrado; o servidor geocodifica o endereço e verifica a área da unidade. Use `data.total_minor` como `expected_total_minor` ao criar o pedido; a API recalcula o preço e recusa divergências.\n\n**Escopo:** `orders:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/OrderInput"
       },
       "examples": {
        "real": {
         "summary": "Requisição usada na demonstração",
         "value": {
          "order_type": "collection",
          "items": [
           {
            "menu_id": 2,
            "quantity": 1,
            "option_values": [
             6
            ],
            "comment": "Bem assada"
           },
           {
            "menu_id": 17,
            "quantity": 1
           }
          ],
          "first_name": "Marina",
          "last_name": "Exemplo",
          "telephone": "(91) 90000-0000",
          "email": "marina@example.com",
          "payment": "cash"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Cotação com total em centavos e linhas de preço",
      "content": {
       "application/json": {
        "examples": {
         "real": {
          "summary": "Resposta real (dados fictícios da demonstração)",
          "value": {
           "data": {
            "order_total": 79.7,
            "order_menus": [
             {
              "id": 2,
              "name": "Pizza Calabresa G",
              "qty": 1,
              "price": 64.8,
              "subtotalWithoutConditions": 64.8,
              "subtotal": 64.8,
              "hasConditions": false,
              "comment": "Bem assada",
              "options": [
               {
                "id": 2,
                "name": "Borda",
                "values": [
                 {
                  "id": 6,
                  "name": "Catupiry",
                  "price": 9.9,
                  "qty": 1
                 }
                ]
               }
              ]
             },
             {
              "id": 17,
              "name": "Refrigerante Cola 2L",
              "qty": 1,
              "price": 14.9,
              "subtotalWithoutConditions": 14.9,
              "subtotal": 14.9,
              "hasConditions": false,
              "comment": "",
              "options": []
             }
            ],
            "order_totals": [
             {
              "code": "subtotal",
              "title": "Subtotal",
              "value": 79.7,
              "priority": 0,
              "is_summable": false
             },
             {
              "code": "total",
              "title": "Total do pedido",
              "value": 79.7,
              "priority": 999,
              "is_summable": false
             }
            ],
            "total_minor": 7970,
            "currency": "BRL"
           }
          }
         }
        }
       }
      }
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "tags": [
     "Pedidos"
    ],
    "x-escopos": [
     "orders:read"
    ]
   }
  },
  "/orders/{order}/checkout": {
   "post": {
    "operationId": "startOrderCheckout",
    "summary": "Iniciar checkout online (Pix ou página do gateway)",
    "description": "Inicia Pix ou checkout hospedado no gateway escolhido no pedido\n\nRequer `payments:initiate`. Disponível para `asaas_pix`, `asaas`, `mercadopago_pix` e `mercadopago` quando o gateway está ativo. Retorna `checkout_url` para abrir ou enviar ao comprador. Cobranças online somente são confirmadas pelo webhook autenticado do provedor.\n\n**Escopo:** `payments:initiate`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "billing": {
          "type": "object",
          "description": "Dados opcionais do pagador para o checkout Asaas"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "URL do checkout e valor cobrado"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "tags": [
     "Pagamentos"
    ],
    "x-escopos": [
     "payments:initiate"
    ]
   }
  },
  "/orders/{order}/checkout/status": {
   "get": {
    "operationId": "getOrderCheckoutStatus",
    "summary": "Consultar situação do checkout online",
    "description": "Consulta confirmação local do pagamento e estado operacional\n\nRequer `payments:read`. `paid` só passa a verdadeiro após confirmação do provedor.\n\n**Escopo:** `payments:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Situação atual do pagamento e pedido"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "tags": [
     "Pagamentos"
    ],
    "x-escopos": [
     "payments:read"
    ]
   }
  },
  "/orders/{order}/transition": {
   "post": {
    "operationId": "transitionOrder",
    "summary": "Mudar a etapa do pedido",
    "description": "Etapas: placed → accepted → preparing → ready → dispatched → completed. cancelled é permitido até preparing; de ready o pedido vai para dispatched ou completed. Transição não permitida responde 422 em error.details.to_state.\n\n**Escopo:** `orders:transition`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "to_state"
        ],
        "properties": {
         "to_state": {
          "type": "string",
          "enum": [
           "placed",
           "accepted",
           "preparing",
           "ready",
           "dispatched",
           "completed",
           "cancelled"
          ],
          "description": "Próxima etapa do pedido"
         },
         "reason_code": {
          "type": "string",
          "maxLength": 80,
          "description": "Motivo operacional, quando a etapa exigir (ex.: cancelamento)"
         }
        }
       },
       "example": {
        "to_state": "accepted"
       },
       "examples": {
        "real": {
         "summary": "Requisição usada na demonstração",
         "value": {
          "to_state": "accepted"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Etapa atualizada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "type": "object",
           "required": [
            "order_id",
            "state",
            "version"
           ],
           "properties": {
            "order_id": {
             "type": "integer"
            },
            "state": {
             "type": "string",
             "enum": [
              "placed",
              "accepted",
              "preparing",
              "ready",
              "dispatched",
              "completed",
              "cancelled"
             ]
            },
            "version": {
             "type": "integer",
             "description": "Versão do estado; incrementa a cada transição"
            }
           }
          }
         }
        },
        "examples": {
         "real": {
          "summary": "Resposta real (dados fictícios da demonstração)",
          "value": {
           "data": {
            "order_id": 6830,
            "state": "accepted",
            "version": 2
           }
          }
         }
        }
       }
      }
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "tags": [
     "Pedidos"
    ],
    "x-escopos": [
     "orders:transition"
    ]
   }
  },
  "/orders/{order}/payment-intents": {
   "get": {
    "operationId": "getOrderPaymentIntent",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Intent financeiro do pedido"
     }
    },
    "summary": "Consultar intenção de pagamento do pedido",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:read`.",
    "x-escopos": [
     "payments:read"
    ]
   },
   "post": {
    "operationId": "createOrderPaymentIntent",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Intent criado ou existente"
     }
    },
    "summary": "Criar intenção de pagamento do pedido",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "payments:write"
    ]
   }
  },
  "/payment-intents/{intent}/allocations": {
   "post": {
    "operationId": "allocatePayment",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "intent",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/PaymentAllocationInput"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Alocação criada"
     }
    },
    "summary": "Alocar pagamento na intenção",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "payments:write"
    ]
   }
  },
  "/payment-allocations/{allocation}/capture": {
   "post": {
    "operationId": "capturePaymentAllocation",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "allocation",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Captura confirmada"
     }
    },
    "summary": "Capturar alocação de pagamento",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "payments:write"
    ]
   }
  },
  "/payment-allocations/{allocation}/cancel": {
   "parameters": [
    {
     "name": "allocation",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "cancelPaymentAllocation",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Alocacao pendente cancelada e saldo liberado"
     }
    },
    "summary": "Cancelar alocação de pagamento",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "payments:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/payment-intents/{intent}/complete": {
   "post": {
    "operationId": "completePaymentIntent",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "intent",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Pedido quitado"
     }
    },
    "summary": "Concluir intenção de pagamento",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "payments:write"
    ]
   }
  },
  "/payment-transactions/{transaction}/refunds": {
   "post": {
    "operationId": "refundPaymentTransaction",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "transaction",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Estorno solicitado ou processado"
     }
    },
    "summary": "Estornar transação de pagamento",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:refund`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "payments:refund"
    ]
   }
  },
  "/cash-sessions": {
   "get": {
    "operationId": "listCashSessions",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Caixas da unidade"
     }
    },
    "summary": "Listar sessões de caixa",
    "tags": [
     "Caixa"
    ],
    "description": "**Escopo:** `cash:read`.",
    "x-escopos": [
     "cash:read"
    ]
   },
   "post": {
    "operationId": "openCashSession",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "responses": {
     "201": {
      "description": "Caixa aberto"
     }
    },
    "summary": "Abrir caixa",
    "tags": [
     "Caixa"
    ],
    "description": "**Escopo:** `cash:manage`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "cash:manage"
    ]
   }
  },
  "/pos/sessions": {
   "post": {
    "operationId": "openPosSession",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "responses": {
     "201": {
      "description": "Sessão de venda aberta"
     }
    },
    "summary": "Abrir venda no PDV",
    "tags": [
     "PDV"
    ],
    "description": "**Escopo:** `pos:use`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "pos:use"
    ]
   }
  },
  "/pos/sessions/{session}/finalize": {
   "post": {
    "operationId": "finalizePosSession",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Venda PDV finalizada"
     }
    },
    "summary": "Finalizar venda do PDV",
    "tags": [
     "PDV"
    ],
    "description": "**Escopo:** `pos:use`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "pos:use"
    ]
   }
  },
  "/table-sessions": {
   "get": {
    "operationId": "listTableSessions",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "open",
        "closed"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Mesas e comandas da unidade"
     }
    },
    "summary": "Listar atendimentos abertos",
    "tags": [
     "Mesas e comandas"
    ],
    "description": "**Escopo:** `tables:read`.",
    "x-escopos": [
     "tables:read"
    ]
   },
   "post": {
    "operationId": "openTableSession",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/TableSessionInput"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Mesa ou comanda aberta ou retomada"
     }
    },
    "summary": "Abrir mesa ou comanda",
    "tags": [
     "Mesas e comandas"
    ],
    "description": "**Escopo:** `tables:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "tables:write"
    ]
   }
  },
  "/table-sessions/{session}": {
   "get": {
    "operationId": "getTableSession",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Atendimento e itens"
     }
    },
    "summary": "Consultar atendimento",
    "tags": [
     "Mesas e comandas"
    ],
    "description": "**Escopo:** `tables:read`.",
    "x-escopos": [
     "tables:read"
    ]
   }
  },
  "/table-sessions/{session}/items": {
   "post": {
    "operationId": "addTableSessionItem",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/TableSessionItemInput"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Item pendente incluído"
     }
    },
    "summary": "Lançar item no atendimento",
    "tags": [
     "Mesas e comandas"
    ],
    "description": "**Escopo:** `tables:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "tables:write"
    ]
   }
  },
  "/table-sessions/{session}/items/{item}": {
   "put": {
    "operationId": "updateTableSessionItem",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     },
     {
      "name": "item",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Item pendente atualizado"
     }
    },
    "summary": "Alterar item pendente",
    "tags": [
     "Mesas e comandas"
    ],
    "description": "**Escopo:** `tables:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "tables:write"
    ]
   },
   "delete": {
    "operationId": "deleteTableSessionItem",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     },
     {
      "name": "item",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Item pendente removido"
     }
    },
    "summary": "Remover item pendente",
    "tags": [
     "Mesas e comandas"
    ],
    "description": "**Escopo:** `tables:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "tables:write"
    ]
   }
  },
  "/table-sessions/{session}/send-to-kitchen": {
   "post": {
    "operationId": "sendTableSessionItemsToKitchen",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Somente os itens pendentes foram materializados e enviados à cozinha"
     }
    },
    "summary": "Enviar itens pendentes para a cozinha",
    "tags": [
     "Mesas e comandas"
    ],
    "description": "**Escopo:** `tables:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "tables:write"
    ]
   }
  },
  "/table-sessions/{session}/transfer-items": {
   "post": {
    "operationId": "transferPendingTableSessionItems",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/TableSessionItemsTransferInput"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Itens pendentes movidos sem duplicação"
     }
    },
    "summary": "Transferir itens pendentes para outro atendimento",
    "tags": [
     "Mesas e comandas"
    ],
    "description": "**Escopo:** `tables:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "tables:write"
    ]
   }
  },
  "/table-sessions/{session}/transfer": {
   "post": {
    "operationId": "transferTableSessionReference",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/TableSessionTransferInput"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Mesa ou comanda transferida"
     }
    },
    "summary": "Transferir atendimento para outra mesa ou comanda",
    "tags": [
     "Mesas e comandas"
    ],
    "description": "**Escopo:** `tables:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "tables:write"
    ]
   }
  },
  "/table-sessions/{session}/merge": {
   "post": {
    "operationId": "mergePendingTableSessions",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/TableSessionMergeInput"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Atendimentos pendentes unidos"
     }
    },
    "summary": "Juntar atendimentos",
    "tags": [
     "Mesas e comandas"
    ],
    "description": "**Escopo:** `tables:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "tables:write"
    ]
   }
  },
  "/table-sessions/{session}/bill": {
   "get": {
    "operationId": "getTableSessionBill",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Conferência do pedido canônico e das partes da conta"
     }
    },
    "summary": "Consultar a conta do atendimento",
    "tags": [
     "Mesas e comandas"
    ],
    "description": "**Escopo:** `tables:read`.",
    "x-escopos": [
     "tables:read"
    ]
   }
  },
  "/table-sessions/{session}/splits": {
   "post": {
    "operationId": "createTableSessionSplits",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/TableSessionSplitsInput"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Partes da conta registradas com a soma exata do pedido"
     }
    },
    "summary": "Dividir a conta",
    "tags": [
     "Mesas e comandas"
    ],
    "description": "**Escopo:** `tables:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "tables:write"
    ]
   }
  },
  "/table-sessions/{session}/close": {
   "post": {
    "operationId": "closeTableSession",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/TableSessionCloseInput"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Atendimento quitado e fechado"
     }
    },
    "summary": "Fechar mesa ou comanda",
    "tags": [
     "Mesas e comandas"
    ],
    "description": "**Escopo:** `tables:close`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "tables:close"
    ]
   }
  },
  "/orders/{order}/receipt": {
   "get": {
    "operationId": "getOrderReceipt",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Dados imutáveis do comprovante"
     }
    },
    "summary": "Consultar recibo do pedido",
    "tags": [
     "Impressão"
    ],
    "description": "**Escopo:** `orders:read`.",
    "x-escopos": [
     "orders:read"
    ]
   }
  },
  "/orders/{order}/reprint": {
   "post": {
    "operationId": "reprintOrderReceipt",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Segunda via enfileirada e auditada"
     }
    },
    "summary": "Reimprimir recibo do pedido",
    "tags": [
     "Impressão"
    ],
    "description": "**Escopo:** `print:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "print:write"
    ]
   }
  },
  "/kitchen-stations": {
   "get": {
    "operationId": "listKitchenStations",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Estações configuradas para a unidade"
     }
    },
    "summary": "Listar estações da cozinha",
    "tags": [
     "Cozinha"
    ],
    "description": "**Escopo:** `kitchen:read`.",
    "x-escopos": [
     "kitchen:read"
    ]
   },
   "post": {
    "operationId": "createKitchenStation",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "responses": {
     "201": {
      "description": "Estação criada"
     }
    },
    "summary": "Criar estação da cozinha",
    "tags": [
     "Cozinha"
    ],
    "description": "**Escopo:** `kitchen:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "kitchen:write"
    ]
   }
  },
  "/kitchen-tickets": {
   "get": {
    "operationId": "listKitchenTickets",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     }
    ],
    "responses": {
     "200": {
      "description": "Fila da cozinha",
      "content": {
       "application/json": {
        "examples": {
         "real": {
          "summary": "Resposta real (dados fictícios da demonstração)",
          "value": {
           "data": [],
           "meta": {
            "total": 0,
            "current_page": 1
           }
          }
         }
        }
       }
      }
     }
    },
    "summary": "Listar tíquetes de produção",
    "tags": [
     "Cozinha"
    ],
    "description": "**Escopo:** `kitchen:read`.",
    "x-escopos": [
     "kitchen:read"
    ]
   }
  },
  "/kitchen-tickets/{ticket}/transition": {
   "post": {
    "operationId": "transitionKitchenTicket",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "ticket",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Ticket atualizado"
     }
    },
    "summary": "Mudar a etapa do tíquete",
    "tags": [
     "Cozinha"
    ],
    "description": "**Escopo:** `kitchen:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "kitchen:write"
    ]
   }
  },
  "/stock/units": {
   "get": {
    "operationId": "listStockUnits",
    "summary": "Listar unidades de medida",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Catálogo de unidades"
     }
    },
    "tags": [
     "Estoque e compras"
    ],
    "description": "Unidades de medida disponíveis para conversão\n\n**Escopo:** `stock:read`.",
    "x-escopos": [
     "stock:read"
    ]
   }
  },
  "/stock/items": {
   "get": {
    "operationId": "listStockItems",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     }
    ],
    "responses": {
     "200": {
      "description": "Insumos, saldos da unidade e conversões"
     }
    },
    "summary": "Listar insumos",
    "tags": [
     "Estoque e compras"
    ],
    "description": "**Escopo:** `stock:read`.",
    "x-escopos": [
     "stock:read"
    ]
   }
  },
  "/stock/items/{item}": {
   "get": {
    "operationId": "getStockItem",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "item",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Insumo com saldo e unidades"
     }
    },
    "summary": "Consultar insumo",
    "tags": [
     "Estoque e compras"
    ],
    "description": "**Escopo:** `stock:read`.",
    "x-escopos": [
     "stock:read"
    ]
   }
  },
  "/stock/items/{item}/units/{unit}": {
   "put": {
    "operationId": "saveStockItemConversion",
    "summary": "Configurar conversão de unidade do insumo",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "item",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "unit",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "factor_to_base"
        ],
        "properties": {
         "factor_to_base": {
          "type": "number",
          "exclusiveMinimum": 0,
          "example": 0.001
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Conversão atualizada"
     },
     "201": {
      "description": "Conversão criada"
     },
     "422": {
      "description": "Unidade incompatível ou fator inválido"
     }
    },
    "tags": [
     "Estoque e compras"
    ],
    "description": "Configura a equivalência da unidade informada para a unidade-base do insumo\n\n**Escopo:** `stock:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "stock:write"
    ]
   }
  },
  "/stock/movements": {
   "get": {
    "operationId": "listStockMovements",
    "summary": "Listar movimentações de estoque",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     }
    ],
    "responses": {
     "200": {
      "description": "Movimentações normalizadas na unidade-base, com unidade de origem"
     }
    },
    "tags": [
     "Estoque e compras"
    ],
    "description": "Extrato imutável de estoque da unidade\n\n**Escopo:** `stock:read`.",
    "x-escopos": [
     "stock:read"
    ]
   }
  },
  "/stock/purchases": {
   "post": {
    "operationId": "createStockPurchase",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "item_id",
         "quantity",
         "unit",
         "unit_cost"
        ],
        "properties": {
         "item_id": {
          "type": "integer"
         },
         "quantity": {
          "type": "number",
          "exclusiveMinimum": 0
         },
         "unit": {
          "type": "string",
          "example": "kg"
         },
         "unit_cost": {
          "type": "number",
          "minimum": 0,
          "description": "Custo por unidade informada"
         },
         "occurred_at": {
          "type": "string",
          "format": "date-time"
         },
         "notes": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Compra lançada no razão de estoque"
     },
     "422": {
      "description": "Unidade não configurada ou payload inválido"
     }
    },
    "summary": "Registrar entrada por compra",
    "tags": [
     "Estoque e compras"
    ],
    "description": "**Escopo:** `stock:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "stock:write"
    ]
   }
  },
  "/stock/losses": {
   "post": {
    "operationId": "createStockLoss",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "item_id",
         "quantity",
         "unit",
         "notes"
        ],
        "properties": {
         "item_id": {
          "type": "integer"
         },
         "quantity": {
          "type": "number",
          "exclusiveMinimum": 0
         },
         "unit": {
          "type": "string",
          "example": "kg"
         },
         "occurred_at": {
          "type": "string",
          "format": "date-time"
         },
         "notes": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Perda lançada no razão de estoque"
     },
     "422": {
      "description": "Saldo, unidade ou payload inválido"
     }
    },
    "summary": "Registrar perda",
    "tags": [
     "Estoque e compras"
    ],
    "description": "**Escopo:** `stock:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "stock:write"
    ]
   }
  },
  "/stock/inventory-counts": {
   "post": {
    "operationId": "startStockInventory",
    "summary": "Abrir contagem de inventário",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "started_at": {
          "type": "string",
          "format": "date-time"
         },
         "notes": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Inventário em rascunho"
     }
    },
    "tags": [
     "Estoque e compras"
    ],
    "description": "Abre inventário físico em rascunho\n\n**Escopo:** `stock:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "stock:write"
    ]
   }
  },
  "/stock/inventory-counts/{count}/items/{item}": {
   "put": {
    "operationId": "setStockInventoryLine",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "count",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "item",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "quantity"
        ],
        "properties": {
         "quantity": {
          "type": "number",
          "minimum": 0
         },
         "unit": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Linha do inventário salva"
     }
    },
    "summary": "Informar quantidade contada",
    "tags": [
     "Estoque e compras"
    ],
    "description": "**Escopo:** `stock:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "stock:write"
    ]
   }
  },
  "/stock/inventory-counts/{count}/close": {
   "post": {
    "operationId": "closeStockInventory",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "count",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Inventário fechado e ajustes lançados"
     },
     "422": {
      "description": "Linhas faltantes ou estado inválido"
     }
    },
    "summary": "Fechar contagem de inventário",
    "tags": [
     "Estoque e compras"
    ],
    "description": "**Escopo:** `stock:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "stock:write"
    ]
   }
  },
  "/stock/suppliers": {
   "get": {
    "operationId": "listStockSuppliers",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     }
    ],
    "responses": {
     "200": {
      "description": "Fornecedores ativos"
     }
    },
    "summary": "Listar fornecedores",
    "tags": [
     "Estoque e compras"
    ],
    "description": "**Escopo:** `stock:read`.",
    "x-escopos": [
     "stock:read"
    ]
   },
   "post": {
    "operationId": "createStockSupplier",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "name"
        ],
        "properties": {
         "name": {
          "type": "string"
         },
         "tax_id": {
          "type": "string"
         },
         "email": {
          "type": "string",
          "format": "email"
         },
         "phone": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Fornecedor criado"
     }
    },
    "summary": "Cadastrar fornecedor",
    "tags": [
     "Estoque e compras"
    ],
    "description": "**Escopo:** `stock:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "stock:write"
    ]
   }
  },
  "/stock/purchase-orders": {
   "get": {
    "operationId": "listStockPurchaseOrders",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     }
    ],
    "responses": {
     "200": {
      "description": "Pedidos de compra da unidade"
     }
    },
    "summary": "Listar pedidos de compra",
    "tags": [
     "Estoque e compras"
    ],
    "description": "**Escopo:** `stock:read`.",
    "x-escopos": [
     "stock:read"
    ]
   },
   "post": {
    "operationId": "createStockPurchaseOrder",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "supplier_id",
         "lines"
        ],
        "properties": {
         "supplier_id": {
          "type": "integer"
         },
         "notes": {
          "type": "string"
         },
         "lines": {
          "type": "array",
          "minItems": 1,
          "items": {
           "type": "object",
           "required": [
            "item_id",
            "quantity",
            "unit",
            "unit_cost"
           ]
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Pedido de compra em rascunho"
     }
    },
    "summary": "Criar pedido de compra",
    "tags": [
     "Estoque e compras"
    ],
    "description": "**Escopo:** `stock:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "stock:write"
    ]
   }
  },
  "/stock/purchase-orders/{purchase}/approve": {
   "post": {
    "operationId": "approveStockPurchaseOrder",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "purchase",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Pedido aprovado"
     }
    },
    "summary": "Aprovar pedido de compra",
    "tags": [
     "Estoque e compras"
    ],
    "description": "**Escopo:** `stock:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "stock:write"
    ]
   }
  },
  "/stock/purchase-orders/{purchase}/receive": {
   "post": {
    "operationId": "receiveStockPurchaseOrder",
    "summary": "Receber pedido de compra",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "purchase",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "quantities"
        ],
        "properties": {
         "quantities": {
          "type": "object",
          "additionalProperties": {
           "type": "number",
           "exclusiveMinimum": 0
          }
         },
         "received_at": {
          "type": "string",
          "format": "date-time"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Recebimento aplicado parcial ou totalmente"
     },
     "422": {
      "description": "Quantidade acima do pedido"
     }
    },
    "tags": [
     "Estoque e compras"
    ],
    "description": "Recebe total ou parte de um pedido e atualiza custo médio\n\n**Escopo:** `stock:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "stock:write"
    ]
   }
  },
  "/stock/purchase-orders/{purchase}/reconcile": {
   "post": {
    "operationId": "reconcileStockPurchaseOrder",
    "summary": "Conciliar pedido de compra com a nota do fornecedor",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "purchase",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "status"
        ],
        "properties": {
         "status": {
          "type": "string",
          "enum": [
           "pending",
           "matched",
           "divergent"
          ]
         },
         "notes": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Situação de conciliação atualizada"
     }
    },
    "tags": [
     "Estoque e compras"
    ],
    "description": "Concilia documento/XML do fornecedor com o pedido\n\n**Escopo:** `stock:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "stock:write"
    ]
   }
  },
  "/finance/categories": {
   "get": {
    "operationId": "listFinanceCategories",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Categorias financeiras"
     }
    },
    "summary": "Listar categorias financeiras",
    "tags": [
     "Financeiro"
    ],
    "description": "**Escopo:** `finance:read`.",
    "x-escopos": [
     "finance:read"
    ]
   },
   "post": {
    "operationId": "createFinanceCategory",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "code",
         "name",
         "kind"
        ],
        "properties": {
         "code": {
          "type": "string"
         },
         "name": {
          "type": "string"
         },
         "kind": {
          "type": "string",
          "enum": [
           "expense",
           "income",
           "transfer"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Categoria criada"
     }
    },
    "summary": "Criar categoria financeira",
    "tags": [
     "Financeiro"
    ],
    "description": "**Escopo:** `finance:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "finance:write"
    ]
   }
  },
  "/finance/accounts": {
   "get": {
    "operationId": "listFinanceAccounts",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Contas financeiras da unidade"
     }
    },
    "summary": "Listar contas financeiras",
    "tags": [
     "Financeiro"
    ],
    "description": "**Escopo:** `finance:read`.",
    "x-escopos": [
     "finance:read"
    ]
   },
   "post": {
    "operationId": "createFinanceAccount",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "name",
         "kind"
        ],
        "properties": {
         "name": {
          "type": "string"
         },
         "kind": {
          "type": "string",
          "enum": [
           "cash",
           "bank",
           "card",
           "other"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Conta criada"
     }
    },
    "summary": "Criar conta financeira",
    "tags": [
     "Financeiro"
    ],
    "description": "**Escopo:** `finance:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "finance:write"
    ]
   }
  },
  "/finance/cost-centers": {
   "get": {
    "operationId": "listFinanceCostCenters",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Centros de custo da unidade"
     }
    },
    "summary": "Listar centros de custo",
    "tags": [
     "Financeiro"
    ],
    "description": "**Escopo:** `finance:read`.",
    "x-escopos": [
     "finance:read"
    ]
   },
   "post": {
    "operationId": "createFinanceCostCenter",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "code",
         "name"
        ],
        "properties": {
         "code": {
          "type": "string"
         },
         "name": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Centro de custo criado"
     }
    },
    "summary": "Criar centro de custo",
    "tags": [
     "Financeiro"
    ],
    "description": "**Escopo:** `finance:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "finance:write"
    ]
   }
  },
  "/finance/titles": {
   "get": {
    "operationId": "listFinanceTitles",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     }
    ],
    "responses": {
     "200": {
      "description": "Títulos e parcelas da unidade"
     }
    },
    "summary": "Listar títulos a pagar e a receber",
    "tags": [
     "Financeiro"
    ],
    "description": "**Escopo:** `finance:read`.",
    "x-escopos": [
     "finance:read"
    ]
   },
   "post": {
    "operationId": "createFinanceTitle",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "description",
         "amount",
         "kind",
         "due_on"
        ],
        "properties": {
         "description": {
          "type": "string"
         },
         "amount": {
          "type": "number"
         },
         "kind": {
          "type": "string",
          "enum": [
           "payable",
           "receivable"
          ]
         },
         "due_on": {
          "type": "string",
          "format": "date"
         },
         "installments": {
          "type": "integer",
          "minimum": 1
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Título criado"
     }
    },
    "summary": "Criar título a pagar ou a receber",
    "tags": [
     "Financeiro"
    ],
    "description": "**Escopo:** `finance:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "finance:write"
    ]
   }
  },
  "/finance/installments/{installment}/settle": {
   "post": {
    "operationId": "settleFinanceInstallment",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "installment",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "account_id",
         "amount"
        ],
        "properties": {
         "account_id": {
          "type": "integer"
         },
         "amount": {
          "type": "number",
          "exclusiveMinimum": 0
         },
         "settled_at": {
          "type": "string",
          "format": "date-time"
         },
         "external_reference": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Liquidação registrada"
     },
     "422": {
      "description": "Valor acima do saldo"
     }
    },
    "summary": "Baixar parcela de título",
    "tags": [
     "Financeiro"
    ],
    "description": "**Escopo:** `finance:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "finance:write"
    ]
   }
  },
  "/finance/cash-flow": {
   "get": {
    "operationId": "getFinanceCashFlow",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "from",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "format": "date"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Fluxo de caixa sintético do período"
     }
    },
    "summary": "Consultar fluxo de caixa",
    "tags": [
     "Financeiro"
    ],
    "description": "**Escopo:** `finance:read`.",
    "x-escopos": [
     "finance:read"
    ]
   }
  },
  "/reports": {
   "get": {
    "operationId": "listReports",
    "summary": "Listar relatórios disponíveis",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Catálogo de relatórios"
     }
    },
    "tags": [
     "Relatórios e DRE"
    ],
    "description": "Read models publicados e suas colunas de exportação\n\n**Escopo:** `reports:read`.",
    "x-escopos": [
     "reports:read"
    ]
   }
  },
  "/reports/dre/rebuild": {
   "post": {
    "operationId": "dreRebuild",
    "summary": "Recalcular a DRE",
    "description": "Recalcular DRE em fila\n\nExige habilidade reports:manage, permissão administrativa e acesso à unidade. Veja docs/RELATORIOS-DRE.md.\n\n**Escopo:** `reports:manage`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "from",
         "to"
        ],
        "properties": {
         "from": {
          "type": "string",
          "format": "date"
         },
         "to": {
          "type": "string",
          "format": "date"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Operação concluída"
     },
     "202": {
      "description": "Apuração enfileirada"
     },
     "403": {
      "description": "Sem permissão para operação ou unidade"
     },
     "409": {
      "description": "Conflito com o estado do período ou chave de idempotência"
     },
     "422": {
      "description": "Dados inválidos ou fechamento não permitido"
     }
    },
    "tags": [
     "Relatórios e DRE"
    ],
    "x-escopos": [
     "reports:manage"
    ]
   }
  },
  "/reports/dre/category": {
   "post": {
    "operationId": "dreCategory",
    "summary": "Classificar categoria na DRE",
    "description": "Classificar categoria global (superusuário)\n\nExige habilidade reports:manage, permissão administrativa e acesso à unidade. Veja docs/RELATORIOS-DRE.md.\n\n**Escopo:** `reports:manage`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "category_id",
         "dre_section",
         "dre_order"
        ],
        "properties": {
         "category_id": {
          "type": "integer"
         },
         "dre_section": {
          "type": "string",
          "enum": [
           "deduction",
           "variable_expense",
           "fixed_expense",
           "other_expense",
           "other_income"
          ]
         },
         "dre_order": {
          "type": "integer",
          "minimum": 0,
          "maximum": 65535
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Operação concluída"
     },
     "202": {
      "description": "Apuração enfileirada"
     },
     "403": {
      "description": "Sem permissão para operação ou unidade"
     },
     "409": {
      "description": "Conflito com o estado do período ou chave de idempotência"
     },
     "422": {
      "description": "Dados inválidos ou fechamento não permitido"
     }
    },
    "tags": [
     "Relatórios e DRE"
    ],
    "x-escopos": [
     "reports:manage"
    ]
   }
  },
  "/reports/dre/title": {
   "post": {
    "operationId": "dreTitle",
    "summary": "Definir competência e categoria de título",
    "description": "Definir competência e categoria do título\n\nExige habilidade reports:manage, permissão administrativa e acesso à unidade. Veja docs/RELATORIOS-DRE.md.\n\n**Escopo:** `reports:manage`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "title_id",
         "category_id",
         "competence_on"
        ],
        "properties": {
         "title_id": {
          "type": "integer"
         },
         "category_id": {
          "type": "integer"
         },
         "competence_on": {
          "type": "string",
          "format": "date"
         },
         "dre_channel": {
          "type": "string",
          "enum": [
           "pdv",
           "delivery_online",
           "retirada_online",
           "online"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Operação concluída"
     },
     "202": {
      "description": "Apuração enfileirada"
     },
     "403": {
      "description": "Sem permissão para operação ou unidade"
     },
     "409": {
      "description": "Conflito com o estado do período ou chave de idempotência"
     },
     "422": {
      "description": "Dados inválidos ou fechamento não permitido"
     }
    },
    "tags": [
     "Relatórios e DRE"
    ],
    "x-escopos": [
     "reports:manage"
    ]
   }
  },
  "/reports/dre/entry": {
   "post": {
    "operationId": "dreEntry",
    "summary": "Registrar lançamento gerencial",
    "description": "Exige habilidade reports:manage, permissão administrativa e acesso à unidade. Veja docs/RELATORIOS-DRE.md.\n\n**Escopo:** `reports:manage`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "description",
         "amount_minor",
         "category_id",
         "occurred_on"
        ],
        "properties": {
         "description": {
          "type": "string"
         },
         "amount_minor": {
          "type": "integer",
          "minimum": 1
         },
         "category_id": {
          "type": "integer"
         },
         "occurred_on": {
          "type": "string",
          "format": "date"
         },
         "channel": {
          "type": "string",
          "enum": [
           "pdv",
           "delivery_online",
           "retirada_online",
           "online"
          ]
         },
         "financial_title_id": {
          "type": "integer"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Operação concluída"
     },
     "202": {
      "description": "Apuração enfileirada"
     },
     "403": {
      "description": "Sem permissão para operação ou unidade"
     },
     "409": {
      "description": "Conflito com o estado do período ou chave de idempotência"
     },
     "422": {
      "description": "Dados inválidos ou fechamento não permitido"
     }
    },
    "tags": [
     "Relatórios e DRE"
    ],
    "x-escopos": [
     "reports:manage"
    ]
   }
  },
  "/reports/dre/budget": {
   "post": {
    "operationId": "dreBudget",
    "summary": "Definir orçamento mensal",
    "description": "Exige habilidade reports:manage, permissão administrativa e acesso à unidade. Veja docs/RELATORIOS-DRE.md.\n\n**Escopo:** `reports:manage`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "month",
         "category_id",
         "amount_minor"
        ],
        "properties": {
         "month": {
          "type": "string",
          "example": "2026-08"
         },
         "category_id": {
          "type": "integer"
         },
         "amount_minor": {
          "type": "integer",
          "minimum": 0
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Operação concluída"
     },
     "202": {
      "description": "Apuração enfileirada"
     },
     "403": {
      "description": "Sem permissão para operação ou unidade"
     },
     "409": {
      "description": "Conflito com o estado do período ou chave de idempotência"
     },
     "422": {
      "description": "Dados inválidos ou fechamento não permitido"
     }
    },
    "tags": [
     "Relatórios e DRE"
    ],
    "x-escopos": [
     "reports:manage"
    ]
   }
  },
  "/reports/dre/marketplaceCost": {
   "post": {
    "operationId": "dreMarketplaceCost",
    "summary": "Classificar custo de marketplace",
    "description": "Exige habilidade reports:manage, permissão administrativa e acesso à unidade. Veja docs/RELATORIOS-DRE.md.\n\n**Escopo:** `reports:manage`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "entry_id",
         "category_id"
        ],
        "properties": {
         "entry_id": {
          "type": "integer"
         },
         "category_id": {
          "type": "integer"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Operação concluída"
     },
     "202": {
      "description": "Apuração enfileirada"
     },
     "403": {
      "description": "Sem permissão para operação ou unidade"
     },
     "409": {
      "description": "Conflito com o estado do período ou chave de idempotência"
     },
     "422": {
      "description": "Dados inválidos ou fechamento não permitido"
     }
    },
    "tags": [
     "Relatórios e DRE"
    ],
    "x-escopos": [
     "reports:manage"
    ]
   }
  },
  "/reports/dre/close": {
   "post": {
    "operationId": "dreClose",
    "summary": "Fechar mês da DRE",
    "description": "Fechar período mensal\n\nExige habilidade reports:close, permissão administrativa e acesso à unidade. Veja docs/RELATORIOS-DRE.md.\n\n**Escopo:** `reports:close`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "month",
         "titles_reviewed",
         "taxes_reviewed",
         "fees_reviewed"
        ],
        "properties": {
         "month": {
          "type": "string",
          "example": "2026-08"
         },
         "titles_reviewed": {
          "type": "boolean"
         },
         "taxes_reviewed": {
          "type": "boolean"
         },
         "fees_reviewed": {
          "type": "boolean"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Operação concluída"
     },
     "202": {
      "description": "Apuração enfileirada"
     },
     "403": {
      "description": "Sem permissão para operação ou unidade"
     },
     "409": {
      "description": "Conflito com o estado do período ou chave de idempotência"
     },
     "422": {
      "description": "Dados inválidos ou fechamento não permitido"
     }
    },
    "tags": [
     "Relatórios e DRE"
    ],
    "x-escopos": [
     "reports:close"
    ]
   }
  },
  "/reports/dre/reopen": {
   "post": {
    "operationId": "dreReopen",
    "summary": "Reabrir mês da DRE",
    "description": "Reabrir período mensal com justificativa\n\nExige habilidade reports:close, permissão administrativa e acesso à unidade. Veja docs/RELATORIOS-DRE.md.\n\n**Escopo:** `reports:close`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "month",
         "reason"
        ],
        "properties": {
         "month": {
          "type": "string",
          "example": "2026-08"
         },
         "reason": {
          "type": "string",
          "minLength": 10,
          "maxLength": 1000
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Operação concluída"
     },
     "202": {
      "description": "Apuração enfileirada"
     },
     "403": {
      "description": "Sem permissão para operação ou unidade"
     },
     "409": {
      "description": "Conflito com o estado do período ou chave de idempotência"
     },
     "422": {
      "description": "Dados inválidos ou fechamento não permitido"
     }
    },
    "tags": [
     "Relatórios e DRE"
    ],
    "x-escopos": [
     "reports:close"
    ]
   }
  },
  "/reports/{report}": {
   "get": {
    "operationId": "getReport",
    "summary": "Consultar relatório no período",
    "description": "Agregados do read model na janela informada\n\nConsulte o catálogo para conhecer os relatórios e suas colunas. Valores com sufixo `_minor` são centavos. A DRE é gerencial, depende de apuração e informa cobertura e avisos; consulte `docs/RELATORIOS-DRE.md`.\n\n**Escopo:** `reports:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "report",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "dre",
        "vendas-horario",
        "vendas-operador",
        "vendas-regiao",
        "performance-produtos",
        "consumo-insumos",
        "posicao-historica",
        "lista-compras",
        "fluxo-de-caixa",
        "rede-consolidado",
        "sales",
        "cash",
        "production",
        "stock",
        "finance",
        "fiscal-apuracao",
        "fiscal-itens",
        "fiscal-recebimentos"
       ]
      }
     },
     {
      "$ref": "#/components/parameters/ReportFrom"
     },
     {
      "$ref": "#/components/parameters/ReportTo"
     },
     {
      "name": "interval",
      "in": "query",
      "description": "Para fluxo-de-caixa; a semana começa na segunda-feira.",
      "schema": {
       "type": "string",
       "enum": [
        "day",
        "week"
       ],
       "default": "day"
      }
     },
     {
      "name": "coverage_days",
      "in": "query",
      "description": "Para lista-compras; cobertura desejada em dias.",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 90,
       "default": 7
      }
     },
     {
      "name": "sla_minutes",
      "in": "query",
      "description": "Apenas para `production`; minutos tolerados entre recebido e pronto.",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 240,
       "default": 15
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Agregados da janela",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Relatório inexistente"
     },
     "422": {
      "description": "Janela inválida; relatórios detalhados admitem até 92 dias e DRE/rede até 366 dias"
     }
    },
    "tags": [
     "Relatórios e DRE"
    ],
    "x-escopos": [
     "reports:read"
    ]
   }
  },
  "/reports/{report}/exports": {
   "post": {
    "operationId": "createReportExport",
    "summary": "Solicitar exportação de relatório",
    "description": "Solicita exportação assíncrona do relatório\n\nResponde 202 imediatamente; o arquivo é gerado por worker e baixado depois.\n\n**Escopo:** `reports:export`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "report",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "dre",
        "vendas-horario",
        "vendas-operador",
        "vendas-regiao",
        "performance-produtos",
        "consumo-insumos",
        "posicao-historica",
        "lista-compras",
        "fluxo-de-caixa",
        "rede-consolidado",
        "sales",
        "cash",
        "production",
        "stock",
        "finance",
        "fiscal-apuracao",
        "fiscal-itens",
        "fiscal-recebimentos"
       ]
      }
     },
     {
      "$ref": "#/components/parameters/ReportFrom"
     },
     {
      "$ref": "#/components/parameters/ReportTo"
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "format": {
          "type": "string",
          "enum": [
           "csv",
           "xlsx",
           "pdf"
          ],
          "default": "csv"
         }
        }
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Exportação enfileirada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/ReportExport"
          }
         }
        }
       }
      }
     },
     "422": {
      "description": "Formato não suportado ou janela inválida"
     }
    },
    "tags": [
     "Relatórios e DRE"
    ],
    "x-escopos": [
     "reports:export"
    ]
   }
  },
  "/reports/exports": {
   "get": {
    "operationId": "listReportExports",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     },
     {
      "name": "report",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "dre",
        "vendas-horario",
        "vendas-operador",
        "vendas-regiao",
        "performance-produtos",
        "consumo-insumos",
        "posicao-historica",
        "lista-compras",
        "fluxo-de-caixa",
        "rede-consolidado",
        "sales",
        "cash",
        "production",
        "stock",
        "finance",
        "fiscal-apuracao",
        "fiscal-itens",
        "fiscal-recebimentos"
       ]
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "queued",
        "processing",
        "completed",
        "failed"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Exportações da unidade"
     }
    },
    "summary": "Listar exportações",
    "tags": [
     "Relatórios e DRE"
    ],
    "description": "**Escopo:** `reports:read`.",
    "x-escopos": [
     "reports:read"
    ]
   }
  },
  "/reports/exports/{export}": {
   "get": {
    "operationId": "getReportExport",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "export",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Situação da exportação",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/ReportExport"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Exportação inexistente na unidade"
     }
    },
    "summary": "Consultar exportação",
    "tags": [
     "Relatórios e DRE"
    ],
    "description": "**Escopo:** `reports:read`.",
    "x-escopos": [
     "reports:read"
    ]
   }
  },
  "/reports/exports/{export}/download": {
   "get": {
    "operationId": "downloadReportExport",
    "summary": "Baixar arquivo exportado",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "export",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Arquivo da exportação",
      "content": {
       "text/csv": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      }
     },
     "409": {
      "description": "Exportação ainda não concluída ou arquivo expirado"
     }
    },
    "tags": [
     "Relatórios e DRE"
    ],
    "description": "Baixa o arquivo gerado\n\n**Escopo:** `reports:export`.",
    "x-escopos": [
     "reports:export"
    ]
   }
  },
  "/print-jobs": {
   "get": {
    "operationId": "listPrintJobs",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     }
    ],
    "responses": {
     "200": {
      "description": "Fila de impressão"
     }
    },
    "summary": "Listar tarefas de impressão",
    "tags": [
     "Impressão"
    ],
    "description": "**Escopo:** `print:read`.",
    "x-escopos": [
     "print:read"
    ]
   }
  },
  "/print-agent/printers": {
   "get": {
    "operationId": "listPrintAgentPrinters",
    "summary": "Listar impressoras do agente local",
    "description": "Lista impressoras disponíveis para vínculo no agente local\n\nRetorna somente impressoras ativas, configuradas para Agente local e pertencentes à unidade informada. É usado pelo assistente instalado no computador para relacionar cada impressora lógica a uma fila do Windows/CUPS ou a um destino TCP direto.\n\n**Escopo:** `print:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Impressoras lógicas disponíveis para o agente",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "required": [
             "id",
             "name",
             "paper_width"
            ],
            "properties": {
             "id": {
              "type": "integer"
             },
             "name": {
              "type": "string"
             },
             "paper_width": {
              "type": "integer",
              "enum": [
               58,
               80
              ]
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "Token sem a habilidade print:read"
     }
    },
    "tags": [
     "Impressão"
    ],
    "x-escopos": [
     "print:read"
    ]
   }
  },
  "/print-jobs/metrics": {
   "get": {
    "operationId": "getPrintMetrics",
    "summary": "Consultar métricas de impressão",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "window_minutes",
      "in": "query",
      "description": "Janela das métricas de volume e latência (5 a 1440 minutos).",
      "schema": {
       "type": "integer",
       "minimum": 5,
       "maximum": 1440,
       "default": 60
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Saúde da fila de impressão da unidade",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/PrintMetrics"
          }
         }
        }
       }
      }
     }
    },
    "tags": [
     "Impressão"
    ],
    "description": "Métricas de entrega, dead-letter e confirmação do agente\n\n**Escopo:** `print:read`.",
    "x-escopos": [
     "print:read"
    ]
   }
  },
  "/print-jobs/claim": {
   "post": {
    "operationId": "claimPrintJobs",
    "summary": "Retirar tarefas para impressão (agente local)",
    "description": "Retirada de tarefas pelo agente local de impressão\n\nCaminho sem CloudPrinter: o agente instalado na loja informa obrigatoriamente as impressoras internas às quais está vinculado e retira somente as tarefas delas. O servidor valida que cada impressora está ativa, usa o transporte Agente local e pertence à unidade do cabeçalho. A retirada trava as linhas e marca cada tarefa como `accepted`, de modo que dois agentes não peguem a mesma tarefa — em impressão isso significaria papel duplicado no balcão. `payload` só é devolvido aqui; a listagem comum expõe apenas metadado. Cada tarefa inclui um `claim_receipt` secreto, que precisa ser mantido no spool local e enviado na confirmação. Depois de imprimir, o agente fecha a tarefa em `POST /print-jobs/{job}/confirm`.\n\n**Escopo:** `print:confirm`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "agent_id",
         "printer_ids"
        ],
        "properties": {
         "agent_id": {
          "type": "string",
          "maxLength": 120,
          "description": "Identificação do computador que está retirando."
         },
         "agent_version": {
          "type": "string",
          "maxLength": 30,
          "description": "Versão do agente para diagnóstico."
         },
         "platform": {
          "type": "string",
          "maxLength": 30,
          "description": "Sistema operacional do agente."
         },
         "printer_ids": {
          "type": "array",
          "minItems": 1,
          "maxItems": 20,
          "uniqueItems": true,
          "items": {
           "type": "integer"
          },
          "description": "IDs internos de impressoras ativas, locais e pertencentes à unidade."
         },
         "max": {
          "type": "integer",
          "minimum": 1,
          "maximum": 20,
          "default": 5
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Tarefas retiradas, com o conteúdo a imprimir",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "allOf": [
             {
              "$ref": "#/components/schemas/PrintJob"
             },
             {
              "type": "object",
              "properties": {
               "payload": {
                "type": "string",
                "description": "Conteúdo em texto puro pronto para a impressora."
               },
               "claim_receipt": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$",
                "description": "Segredo de uso único para confirmar esta retirada; armazenar no spool local e não registrar em logs."
               },
               "paper_width": {
                "type": "integer",
                "description": "Largura do papel em milímetros."
               },
               "copies": {
                "type": "integer",
                "minimum": 1
               },
               "printer_name": {
                "type": "string"
               }
              }
             }
            ]
           }
          },
          "meta": {
           "type": "object",
           "properties": {
            "claimed": {
             "type": "integer"
            },
            "agent_id": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "Token sem a habilidade print:confirm"
     },
     "422": {
      "description": "Impressora ausente, inativa, externa ou pertencente a outra unidade"
     }
    },
    "tags": [
     "Impressão"
    ],
    "x-escopos": [
     "print:confirm"
    ]
   }
  },
  "/print-jobs/{job}/confirm": {
   "post": {
    "operationId": "confirmPrintJob",
    "summary": "Confirmar impressão (agente local)",
    "description": "Confirmação de impressão enviada pelo agente local\n\nO agente informa se o documento saiu no papel. A confirmação exige o mesmo token, agent_reference e claim_receipt recebidos na retirada; o servidor armazena somente o hash do recibo. `printed` é terminal e idempotente; `failed` devolve a tarefa à fila com backoff ou, esgotadas as tentativas, ao dead-letter.\n\n**Escopo:** `print:confirm`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "job",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "status",
         "agent_reference",
         "claim_receipt"
        ],
        "properties": {
         "status": {
          "type": "string",
          "enum": [
           "printed",
           "failed"
          ]
         },
         "agent_reference": {
          "type": "string",
          "maxLength": 120
         },
         "claim_receipt": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
         },
         "message": {
          "type": "string",
          "maxLength": 500
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Estado da tarefa após a confirmação",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/PrintJob"
          }
         }
        }
       }
      }
     },
     "409": {
      "description": "Tarefa em estado terminal ou ainda não enviada"
     },
     "422": {
      "description": "Payload inválido"
     }
    },
    "tags": [
     "Impressão"
    ],
    "x-escopos": [
     "print:confirm"
    ]
   }
  },
  "/print-jobs/{job}/retry": {
   "post": {
    "operationId": "retryPrintJob",
    "summary": "Reenviar tarefa de impressão",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "job",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Tarefa reenfileirada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/PrintJob"
          }
         }
        }
       }
      }
     },
     "422": {
      "description": "Tarefa em estado que não permite reenvio"
     }
    },
    "tags": [
     "Impressão"
    ],
    "description": "Reenfileira tarefa falha, cancelada, em dead-letter ou sem confirmação\n\n**Escopo:** `print:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "print:write"
    ]
   }
  },
  "/audit": {
   "get": {
    "operationId": "listAuditEvents",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Eventos de auditoria da unidade"
     }
    },
    "summary": "Consultar trilha de auditoria",
    "tags": [
     "Governança"
    ],
    "description": "**Escopo:** `audit:read`.",
    "x-escopos": [
     "audit:read"
    ]
   }
  },
  "/reasons": {
   "get": {
    "operationId": "listReasonCodes",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Motivos operacionais disponíveis"
     }
    },
    "summary": "Listar motivos operacionais",
    "tags": [
     "Governança"
    ],
    "description": "**Escopo:** `reasons:manage`.",
    "x-escopos": [
     "reasons:manage"
    ]
   }
  },
  "/approvals": {
   "post": {
    "operationId": "requestSupervisorApproval",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "responses": {
     "201": {
      "description": "Aprovação solicitada"
     }
    },
    "summary": "Solicitar aprovação de supervisor",
    "tags": [
     "Governança"
    ],
    "description": "**Escopo:** `approvals:grant`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "approvals:grant"
    ]
   }
  },
  "/approvals/{approval}/approve": {
   "post": {
    "operationId": "approveSupervisorApproval",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "approval",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Aprovação consumível emitida"
     }
    },
    "summary": "Conceder aprovação de supervisor",
    "tags": [
     "Governança"
    ],
    "description": "**Escopo:** `approvals:grant`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "approvals:grant"
    ]
   }
  },
  "/catalog/menus/{menu}": {
   "get": {
    "operationId": "getMenu",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "menu",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Produto com escolhas disponíveis e preços efetivos por escolha",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/Menu"
          }
         }
        }
       }
      }
     }
    },
    "summary": "Consultar produto",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:read`.",
    "x-escopos": [
     "catalog:read"
    ]
   },
   "put": {
    "operationId": "updateMenu",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "menu",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Produto atualizado"
     }
    },
    "summary": "Alterar produto",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "catalog:write"
    ]
   },
   "delete": {
    "operationId": "deleteMenu",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "menu",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Produto removido"
     }
    },
    "summary": "Excluir produto",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "catalog:write"
    ]
   }
  },
  "/catalog/menus/{menu}/availability": {
   "get": {
    "operationId": "getMenuAvailability",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "menu",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Regras de disponibilidade do produto por canal e horário"
     }
    },
    "summary": "Consultar regras de disponibilidade do produto",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:read`.",
    "x-escopos": [
     "catalog:read"
    ]
   },
   "put": {
    "operationId": "replaceMenuAvailability",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "menu",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "rules"
        ],
        "properties": {
         "rules": {
          "type": "array",
          "maxItems": 100,
          "items": {
           "type": "object",
           "required": [
            "channel",
            "is_available"
           ],
           "properties": {
            "channel": {
             "type": "string",
             "enum": [
              "all",
              "pos",
              "delivery",
              "table",
              "marketplace",
              "kiosk"
             ]
            },
            "weekday": {
             "type": "integer",
             "minimum": 0,
             "maximum": 6,
             "nullable": true
            },
            "starts_at": {
             "type": "string",
             "pattern": "^\\\\d{2}:\\\\d{2}$",
             "nullable": true
            },
            "ends_at": {
             "type": "string",
             "pattern": "^\\\\d{2}:\\\\d{2}$",
             "nullable": true
            },
            "is_available": {
             "type": "boolean"
            },
            "priority": {
             "type": "integer",
             "minimum": 0
            },
            "reason": {
             "type": "string",
             "nullable": true
            }
           }
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Regras substituídas de forma transacional"
     }
    },
    "summary": "Substituir regras de disponibilidade do produto",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "catalog:write"
    ]
   }
  },
  "/catalog/categories/{category}": {
   "put": {
    "operationId": "updateCategory",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "category",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Categoria atualizada"
     }
    },
    "summary": "Alterar categoria",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "catalog:write"
    ]
   },
   "delete": {
    "operationId": "deleteCategory",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "category",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Categoria removida"
     }
    },
    "summary": "Excluir categoria",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "catalog:write"
    ]
   }
  },
  "/catalog/options/{option}": {
   "put": {
    "operationId": "updateMenuOption",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "option",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Grupo de opções atualizado"
     }
    },
    "summary": "Alterar grupo de opções",
    "tags": [
     "Cardápio"
    ],
    "description": "**Escopo:** `catalog:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "catalog:write"
    ]
   }
  },
  "/customers/{customer}": {
   "get": {
    "operationId": "getCustomer",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "customer",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Cliente autorizado"
     }
    },
    "summary": "Consultar cliente",
    "tags": [
     "Clientes"
    ],
    "description": "**Escopo:** `customers:read`.",
    "x-escopos": [
     "customers:read"
    ]
   },
   "put": {
    "operationId": "updateCustomer",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "customer",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Cliente atualizado"
     }
    },
    "summary": "Alterar cliente",
    "tags": [
     "Clientes"
    ],
    "description": "**Escopo:** `customers:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "customers:write"
    ]
   }
  },
  "/customers/{customer}/addresses": {
   "post": {
    "operationId": "createCustomerAddress",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "customer",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "address_1",
         "country_id"
        ],
        "properties": {
         "address_1": {
          "type": "string",
          "description": "Rua e número; inclua o bairro se conhecido"
         },
         "address_2": {
          "type": "string",
          "nullable": true
         },
         "city": {
          "type": "string",
          "nullable": true
         },
         "state": {
          "type": "string",
          "nullable": true
         },
         "postcode": {
          "type": "string",
          "nullable": true
         },
         "country_id": {
          "type": "integer",
          "description": "ID do país válido na instalação"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Endereço criado"
     }
    },
    "summary": "Cadastrar endereço do cliente",
    "tags": [
     "Clientes"
    ],
    "description": "**Escopo:** `customers:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "customers:write"
    ]
   }
  },
  "/customers/{customer}/addresses/{address}": {
   "put": {
    "operationId": "updateCustomerAddress",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "customer",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "address",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "address_1": {
          "type": "string"
         },
         "address_2": {
          "type": "string",
          "nullable": true
         },
         "city": {
          "type": "string",
          "nullable": true
         },
         "state": {
          "type": "string",
          "nullable": true
         },
         "postcode": {
          "type": "string",
          "nullable": true
         },
         "country_id": {
          "type": "integer"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Endereço atualizado"
     }
    },
    "summary": "Alterar endereço do cliente",
    "tags": [
     "Clientes"
    ],
    "description": "**Escopo:** `customers:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "customers:write"
    ]
   }
  },
  "/loyalty/customers/{customer}": {
   "get": {
    "operationId": "getLoyaltyAccount",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "customer",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Saldo de pontos e crédito do cliente na unidade"
     }
    },
    "summary": "Consultar saldo de pontos e crédito do cliente",
    "tags": [
     "Fidelidade e crédito"
    ],
    "description": "**Escopo:** `loyalty:read`.",
    "x-escopos": [
     "loyalty:read"
    ]
   }
  },
  "/loyalty/customers/{customer}/entries": {
   "get": {
    "operationId": "listLoyaltyEntries",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     },
     {
      "name": "customer",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Extrato paginado do ledger"
     }
    },
    "summary": "Listar lançamentos de fidelidade do cliente",
    "tags": [
     "Fidelidade e crédito"
    ],
    "description": "**Escopo:** `loyalty:read`.",
    "x-escopos": [
     "loyalty:read"
    ]
   },
   "post": {
    "operationId": "createLoyaltyEntry",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "customer",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/LoyaltyEntryInput"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Lançamento criado ou repetição idempotente"
     },
     "422": {
      "description": "Saldo insuficiente ou dados inválidos"
     }
    },
    "summary": "Lançar pontos ou crédito para o cliente",
    "tags": [
     "Fidelidade e crédito"
    ],
    "description": "**Escopo:** `loyalty:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "loyalty:write"
    ]
   }
  },
  "/loyalty/entries/{entry}/reverse": {
   "post": {
    "operationId": "reverseLoyaltyEntry",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "entry",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Reversão idempotente criada"
     },
     "404": {
      "description": "Lançamento não encontrado na unidade"
     }
    },
    "summary": "Reverter lançamento de fidelidade",
    "tags": [
     "Fidelidade e crédito"
    ],
    "description": "**Escopo:** `loyalty:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "loyalty:write"
    ]
   }
  },
  "/orders/{order}": {
   "get": {
    "operationId": "getOrder",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Pedido canônico",
      "content": {
       "application/json": {
        "examples": {
         "real": {
          "summary": "Resposta real (dados fictícios da demonstração)",
          "value": {
           "data": {
            "id": 6830,
            "location_id": 1,
            "customer_id": null,
            "state": "placed",
            "state_version": 1,
            "total_minor": 7970,
            "currency": "BRL",
            "payment": "cash",
            "paid": false,
            "total_items": 2,
            "order_type": "collection",
            "created_at": "2026-11-12T19:29:54.000000Z",
            "items": [
             {
              "id": 4868,
              "menu_id": 2,
              "name": "Pizza Calabresa G",
              "quantity": 1,
              "unit_price_minor": 5490,
              "subtotal_minor": 6480,
              "option_values": [
               6
              ]
             },
             {
              "id": 4869,
              "menu_id": 17,
              "name": "Refrigerante Cola 2L",
              "quantity": 1,
              "unit_price_minor": 1490,
              "subtotal_minor": 1490,
              "option_values": []
             }
            ],
            "totals": [
             {
              "code": "subtotal",
              "title": "Subtotal",
              "amount_minor": 7970
             },
             {
              "code": "total",
              "title": "Total do pedido",
              "amount_minor": 7970
             }
            ]
           }
          }
         }
        }
       }
      }
     }
    },
    "summary": "Consultar pedido",
    "tags": [
     "Pedidos"
    ],
    "description": "**Escopo:** `orders:read`.",
    "x-escopos": [
     "orders:read"
    ]
   }
  },
  "/orders/{order}/payment": {
   "put": {
    "operationId": "changeOrderPayment",
    "summary": "Trocar o meio de pagamento do pedido",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "payment"
        ],
        "properties": {
         "payment": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Pedido com novo meio de pagamento"
     }
    },
    "tags": [
     "Pedidos"
    ],
    "description": "Trocar meio de pagamento de pedido ainda sem checkout e sem pagamento\n\n**Escopo:** `orders:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "orders:write"
    ]
   }
  },
  "/orders/{order}/payment-transactions": {
   "get": {
    "operationId": "listOrderPaymentTransactions",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Histórico financeiro do pedido"
     }
    },
    "summary": "Listar transações de pagamento do pedido",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:read`.",
    "x-escopos": [
     "payments:read"
    ]
   }
  },
  "/orders/{order}/cancel": {
   "post": {
    "operationId": "cancelOrder",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "anyOf": [
         {
          "required": [
           "reason_code"
          ]
         },
         {
          "required": [
           "cancellation_code"
          ]
         }
        ],
        "properties": {
         "reason_code": {
          "type": "string",
          "maxLength": 80
         },
         "cancellation_code": {
          "type": "string",
          "maxLength": 10,
          "description": "Obrigatório para pedido iFood; consultar motivos no vínculo de marketplace"
         },
         "approval_challenge": {
          "type": [
           "string",
           "null"
          ],
          "maxLength": 160
         }
        }
       }
      }
     }
    },
    "description": "No canal próprio cria o cancelamento compensatório. Para pedido iFood, exige cancellation_code disponível no parceiro e retorna 202 com solicitação pendente; o pedido só encerra após CANCELLED. Cancelamentos parciais iFood e cancel-unpaid genérico não são permitidos.\n\n**Escopo:** `orders:cancel`.\n\n**Exige** `Idempotency-Key`.",
    "responses": {
     "201": {
      "description": "Cancelamento compensatório criado"
     },
     "202": {
      "description": "Cancelamento iFood solicitado e ainda pendente de confirmação"
     }
    },
    "summary": "Cancelar pedido",
    "tags": [
     "Pedidos"
    ],
    "x-escopos": [
     "orders:cancel"
    ]
   }
  },
  "/orders/{order}/cancel-unpaid": {
   "post": {
    "operationId": "cancelUnpaidOrder",
    "summary": "Cancelar pedido sem pagamento e ainda não iniciado",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "reason_code"
        ],
        "properties": {
         "reason_code": {
          "type": "string",
          "enum": [
           "order.cancel"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Pedido sem pagamento cancelado"
     }
    },
    "tags": [
     "Pedidos"
    ],
    "description": "Cancelar somente pedido sem pagamento e ainda não iniciado\n\n**Escopo:** `orders:cancel`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "orders:cancel"
    ]
   }
  },
  "/orders/{order}/items/{item}/cancel": {
   "post": {
    "operationId": "cancelOrderItem",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "item",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Cancelamento parcial criado"
     }
    },
    "summary": "Cancelar item do pedido",
    "tags": [
     "Pedidos"
    ],
    "description": "**Escopo:** `orders:cancel`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "orders:cancel"
    ]
   }
  },
  "/payment-intents/{intent}": {
   "get": {
    "operationId": "getPaymentIntent",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "intent",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Intent e saldo pendente"
     }
    },
    "summary": "Consultar intenção de pagamento",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:read`.",
    "x-escopos": [
     "payments:read"
    ]
   }
  },
  "/refunds/{refund}": {
   "get": {
    "operationId": "getRefund",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "refund",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Estorno e status"
     }
    },
    "summary": "Consultar estorno",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:read`.",
    "x-escopos": [
     "payments:read"
    ]
   }
  },
  "/payment-methods": {
   "get": {
    "operationId": "listPaymentMethods",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Meios de pagamento por unidade"
     }
    },
    "summary": "Listar meios de pagamento",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:read`.",
    "x-escopos": [
     "payments:read"
    ]
   },
   "post": {
    "operationId": "createPaymentMethod",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "201": {
      "description": "Meio de pagamento criado no catálogo da unidade"
     }
    },
    "summary": "Cadastrar meio de pagamento",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "payments:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/payment-methods/{method}": {
   "parameters": [
    {
     "name": "method",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "put": {
    "operationId": "updatePaymentMethod",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Meio de pagamento atualizado"
     }
    },
    "summary": "Alterar meio de pagamento",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "payments:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/reconciliations": {
   "get": {
    "operationId": "listReconciliations",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Divergências de conciliação"
     }
    },
    "summary": "Listar conciliações de pagamento",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:read`.",
    "x-escopos": [
     "payments:read"
    ]
   }
  },
  "/reconciliations/run": {
   "post": {
    "operationId": "runReconciliation",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "responses": {
     "200": {
      "description": "Conciliação executada"
     }
    },
    "summary": "Executar conciliação de pagamentos",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "payments:write"
    ]
   }
  },
  "/reconciliations/{reconciliation}/resolve": {
   "post": {
    "operationId": "resolveReconciliation",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "reconciliation",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Divergência resolvida e auditada"
     }
    },
    "summary": "Resolver divergência de conciliação",
    "tags": [
     "Pagamentos"
    ],
    "description": "**Escopo:** `payments:refund`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "payments:refund"
    ]
   }
  },
  "/cash-sessions/current": {
   "get": {
    "operationId": "getCurrentCashSession",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Caixa aberto na unidade"
     }
    },
    "summary": "Consultar o caixa aberto",
    "tags": [
     "Caixa"
    ],
    "description": "**Escopo:** `cash:read`.",
    "x-escopos": [
     "cash:read"
    ]
   }
  },
  "/cash-sessions/{session}": {
   "get": {
    "operationId": "getCashSession",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Caixa e movimentos"
     }
    },
    "summary": "Consultar sessão de caixa",
    "tags": [
     "Caixa"
    ],
    "description": "**Escopo:** `cash:read`.",
    "x-escopos": [
     "cash:read"
    ]
   }
  },
  "/cash-sessions/{session}/movements": {
   "post": {
    "operationId": "createCashMovement",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Sangria ou suprimento registrado"
     }
    },
    "summary": "Registrar sangria ou suprimento",
    "tags": [
     "Caixa"
    ],
    "description": "**Escopo:** `cash:manage`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "cash:manage"
    ]
   }
  },
  "/cash-sessions/{session}/close": {
   "post": {
    "operationId": "closeCashSession",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Caixa fechado e conferido"
     }
    },
    "summary": "Fechar caixa",
    "tags": [
     "Caixa"
    ],
    "description": "**Escopo:** `cash:manage`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "cash:manage"
    ]
   }
  },
  "/pos/sessions/{session}": {
   "get": {
    "operationId": "getPosSession",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Sessão e carrinho do PDV"
     }
    },
    "summary": "Consultar venda do PDV",
    "tags": [
     "PDV"
    ],
    "description": "**Escopo:** `pos:use`.",
    "x-escopos": [
     "pos:use"
    ]
   }
  },
  "/pos/sessions/{session}/items": {
   "post": {
    "operationId": "addPosItem",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Item adicionado ao carrinho"
     }
    },
    "summary": "Adicionar item à venda",
    "tags": [
     "PDV"
    ],
    "description": "**Escopo:** `pos:use`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "pos:use"
    ]
   }
  },
  "/pos/sessions/{session}/items/{item}": {
   "put": {
    "operationId": "updatePosItem",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     },
     {
      "name": "item",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Item atualizado"
     }
    },
    "summary": "Alterar item da venda",
    "tags": [
     "PDV"
    ],
    "description": "**Escopo:** `pos:use`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "pos:use"
    ]
   },
   "delete": {
    "operationId": "removePosItem",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     },
     {
      "name": "item",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Item removido"
     }
    },
    "summary": "Remover item da venda",
    "tags": [
     "PDV"
    ],
    "description": "**Escopo:** `pos:use`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "pos:use"
    ]
   }
  },
  "/pos/sessions/{session}/customer": {
   "put": {
    "operationId": "setPosCustomer",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Cliente associado à sessão"
     }
    },
    "summary": "Informar cliente da venda",
    "tags": [
     "PDV"
    ],
    "description": "**Escopo:** `pos:use`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "pos:use"
    ]
   }
  },
  "/pos/sessions/{session}/adjustments": {
   "post": {
    "operationId": "createPosAdjustment",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Desconto ou acréscimo aplicado"
     }
    },
    "summary": "Aplicar desconto ou acréscimo na venda",
    "tags": [
     "PDV"
    ],
    "description": "**Escopo:** `pos:adjust`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "pos:adjust"
    ]
   }
  },
  "/pos/sessions/{session}/hold": {
   "post": {
    "operationId": "holdPosSession",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Venda suspensa"
     }
    },
    "summary": "Colocar venda em espera",
    "tags": [
     "PDV"
    ],
    "description": "**Escopo:** `pos:use`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "pos:use"
    ]
   }
  },
  "/pos/holds": {
   "get": {
    "operationId": "listPosHolds",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Vendas suspensas da unidade"
     }
    },
    "summary": "Listar vendas em espera",
    "tags": [
     "PDV"
    ],
    "description": "**Escopo:** `pos:use`.",
    "x-escopos": [
     "pos:use"
    ]
   }
  },
  "/pos/holds/{session}/resume": {
   "post": {
    "operationId": "resumePosHold",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "session",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Venda retomada"
     }
    },
    "summary": "Retomar venda em espera",
    "tags": [
     "PDV"
    ],
    "description": "**Escopo:** `pos:use`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "pos:use"
    ]
   }
  },
  "/kitchen-stations/{station}": {
   "put": {
    "operationId": "updateKitchenStation",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "station",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Estação atualizada"
     }
    },
    "summary": "Alterar estação da cozinha",
    "tags": [
     "Cozinha"
    ],
    "description": "**Escopo:** `kitchen:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "kitchen:write"
    ]
   }
  },
  "/kitchen-tickets/{ticket}": {
   "get": {
    "operationId": "getKitchenTicket",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "ticket",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Ticket e itens da cozinha"
     }
    },
    "summary": "Consultar tíquete de produção",
    "tags": [
     "Cozinha"
    ],
    "description": "**Escopo:** `kitchen:read`.",
    "x-escopos": [
     "kitchen:read"
    ]
   }
  },
  "/kitchen-ticket-items/{item}/transition": {
   "post": {
    "operationId": "transitionKitchenTicketItem",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "item",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Estado do item atualizado"
     }
    },
    "summary": "Mudar a etapa de um item do tíquete",
    "tags": [
     "Cozinha"
    ],
    "description": "**Escopo:** `kitchen:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "kitchen:write"
    ]
   }
  },
  "/print-jobs/{job}": {
   "get": {
    "operationId": "getPrintJob",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "job",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Job de impressão e tentativas"
     }
    },
    "summary": "Consultar tarefa de impressão",
    "tags": [
     "Impressão"
    ],
    "description": "**Escopo:** `print:read`.",
    "x-escopos": [
     "print:read"
    ]
   }
  },
  "/print-jobs/{job}/cancel": {
   "post": {
    "operationId": "cancelPrintJob",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "job",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Job cancelado"
     }
    },
    "summary": "Cancelar tarefa de impressão",
    "tags": [
     "Impressão"
    ],
    "description": "**Escopo:** `print:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "print:write"
    ]
   }
  },
  "/delivery/drivers": {
   "get": {
    "operationId": "listDeliveryDrivers",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Lista de entregadores"
     }
    },
    "summary": "Listar entregadores",
    "tags": [
     "Entregas"
    ],
    "description": "**Escopo:** `delivery:read`.",
    "x-escopos": [
     "delivery:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   },
   "post": {
    "operationId": "saveDeliveryDriver",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "201": {
      "description": "Entregador salvo"
     }
    },
    "summary": "Cadastrar ou alterar entregador",
    "tags": [
     "Entregas"
    ],
    "description": "**Escopo:** `delivery:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "delivery:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/delivery/queue": {
   "get": {
    "operationId": "getDeliveryQueue",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Fila operacional de entregas"
     }
    },
    "summary": "Consultar fila de entregas",
    "tags": [
     "Entregas"
    ],
    "description": "**Escopo:** `delivery:read`.",
    "x-escopos": [
     "delivery:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/delivery/orders/{order}/assign": {
   "parameters": [
    {
     "name": "order",
     "in": "path",
     "required": true,
     "schema": {
      "type": "integer"
     }
    }
   ],
   "post": {
    "operationId": "assignDeliveryOrder",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "201": {
      "description": "Entrega atribuída"
     }
    },
    "summary": "Atribuir entregador ao pedido",
    "tags": [
     "Entregas"
    ],
    "description": "**Escopo:** `delivery:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "delivery:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/delivery/assignments/{assignment}/check-in": {
   "parameters": [
    {
     "name": "assignment",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "checkInDelivery",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Check-in registrado"
     }
    },
    "summary": "Registrar retirada do pedido pelo entregador",
    "tags": [
     "Entregas"
    ],
    "description": "**Escopo:** `delivery:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "delivery:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/delivery/assignments/{assignment}/dispatch": {
   "parameters": [
    {
     "name": "assignment",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "dispatchDelivery",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Entrega despachada"
     }
    },
    "summary": "Despachar entrega",
    "tags": [
     "Entregas"
    ],
    "description": "**Escopo:** `delivery:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "delivery:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/delivery/assignments/{assignment}/deliver": {
   "parameters": [
    {
     "name": "assignment",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "completeDelivery",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Entrega concluída"
     }
    },
    "summary": "Concluir entrega",
    "tags": [
     "Entregas"
    ],
    "description": "**Escopo:** `delivery:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "delivery:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/delivery/routes": {
   "post": {
    "operationId": "createDeliveryRoute",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "201": {
      "description": "Rota criada"
     }
    },
    "summary": "Criar rota com várias entregas",
    "tags": [
     "Entregas"
    ],
    "description": "**Escopo:** `delivery:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "delivery:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/delivery/routes/{route}/dispatch": {
   "parameters": [
    {
     "name": "route",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "dispatchDeliveryRoute",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Rota despachada"
     }
    },
    "summary": "Despachar rota",
    "tags": [
     "Entregas"
    ],
    "description": "**Escopo:** `delivery:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "delivery:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/delivery/assignments/{assignment}/tracking-token": {
   "parameters": [
    {
     "name": "assignment",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "createDeliveryTrackingToken",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "201": {
      "description": "Token de rastreio criado"
     }
    },
    "summary": "Gerar link de rastreio",
    "tags": [
     "Entregas"
    ],
    "description": "**Escopo:** `delivery:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "delivery:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/delivery/geocode": {
   "post": {
    "operationId": "geocodeDeliveryAddress",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Geocodificação consultada"
     }
    },
    "summary": "Localizar endereço no mapa",
    "tags": [
     "Entregas"
    ],
    "description": "**Escopo:** `delivery:read`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "delivery:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/delivery/tracking/{token}": {
   "parameters": [
    {
     "name": "token",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "operationId": "getPublicDeliveryTracking",
    "responses": {
     "200": {
      "description": "Status público da entrega"
     }
    },
    "summary": "Consultar rastreio público (sem token)",
    "tags": [
     "Entregas"
    ],
    "description": "",
    "security": []
   }
  },
  "/fiscal/profile": {
   "get": {
    "operationId": "getFiscalProfile",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Perfil fiscal da unidade"
     }
    },
    "summary": "Consultar perfil fiscal",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   },
   "put": {
    "operationId": "saveFiscalProfile",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Perfil fiscal atualizado"
     }
    },
    "summary": "Salvar perfil fiscal",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/profile/certificate": {
   "post": {
    "operationId": "uploadFiscalCertificate",
    "description": "Exige HTTPS, perfil fiscal existente e habilidade fiscal:write. A senha é validada e a validade é extraída do certificado; expires_at é aceito por compatibilidade e não substitui a validade do arquivo.\n\n**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "in": "header",
      "name": "X-Location-Id",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "required": [
         "certificate",
         "password"
        ],
        "properties": {
         "certificate": {
          "type": "string",
          "format": "binary",
          "description": "Arquivo PFX ou P12 de até 5 MB"
         },
         "password": {
          "type": "string",
          "format": "password"
         },
         "expires_at": {
          "type": "string",
          "format": "date",
          "deprecated": true
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Certificado A1 armazenado"
     },
     "403": {
      "description": "HTTPS ou permissão necessária"
     },
     "422": {
      "description": "Arquivo ou senha inválidos"
     }
    },
    "summary": "Enviar certificado digital",
    "tags": [
     "Fiscal"
    ],
    "x-escopos": [
     "fiscal:write"
    ]
   }
  },
  "/fiscal/rules": {
   "get": {
    "operationId": "listFiscalRules",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Regras fiscais da unidade"
     }
    },
    "summary": "Listar regras fiscais",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   },
   "post": {
    "operationId": "createFiscalRule",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "201": {
      "description": "Regra fiscal criada"
     }
    },
    "summary": "Criar regra fiscal",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/rules/{rule}": {
   "parameters": [
    {
     "name": "rule",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "put": {
    "operationId": "updateFiscalRule",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Regra fiscal atualizada"
     }
    },
    "summary": "Alterar regra fiscal",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/orders/{order}/fiscal-documents": {
   "parameters": [
    {
     "name": "order",
     "in": "path",
     "required": true,
     "schema": {
      "type": "integer"
     }
    }
   ],
   "get": {
    "operationId": "listOrderFiscalDocuments",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Documentos fiscais do pedido"
     }
    },
    "summary": "Listar documentos fiscais do pedido",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   },
   "post": {
    "operationId": "requestOrderFiscalDocument",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "202": {
      "description": "Emissão fiscal enfileirada"
     }
    },
    "summary": "Solicitar emissão de NFC-e do pedido",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:emit`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:emit"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/documents/{document}": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "operationId": "getFiscalDocument",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Estado do documento fiscal"
     }
    },
    "summary": "Consultar documento fiscal",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/fiscal/documents/{document}/process": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "processFiscalDocument",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Documento processado"
     }
    },
    "summary": "Processar documento fiscal",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:emit`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:emit"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/documents/{document}/retry": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "retryFiscalDocument",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Reprocessamento solicitado"
     }
    },
    "summary": "Tentar de novo a emissão",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:emit`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:emit"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/documents/{document}/query": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "queryFiscalDocument",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Consulta do documento no provedor"
     }
    },
    "summary": "Consultar situação na SEFAZ",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/documents/{document}/attempts": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "operationId": "listFiscalDocumentAttempts",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Histórico de tentativas fiscais"
     }
    },
    "summary": "Listar tentativas de emissão",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/fiscal/documents/{document}/transmit-contingency": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "transmitFiscalContingency",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Transmissão de documento emitido em contingência"
     }
    },
    "summary": "Transmitir nota emitida em contingência",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:emit`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:emit"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/documents/{document}/cancel": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "cancelFiscalDocument",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Documento cancelado"
     }
    },
    "summary": "Cancelar documento fiscal",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:emit`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:emit"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/documents/{document}/xml": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "operationId": "downloadFiscalXml",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "XML autorizado"
     }
    },
    "summary": "Baixar XML do documento fiscal",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/fiscal/documents/{document}/pdf": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "operationId": "downloadFiscalPdf",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "DANFE em PDF"
     }
    },
    "summary": "Baixar DANFE em PDF",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/fiscal/invalidations": {
   "post": {
    "operationId": "invalidateFiscalRange",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "202": {
      "description": "Inutilização solicitada"
     }
    },
    "summary": "Inutilizar faixa de numeração",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:emit`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:emit"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/series": {
   "get": {
    "operationId": "listFiscalSeries",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Séries fiscais da unidade"
     }
    },
    "summary": "Listar séries de numeração",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   },
   "post": {
    "operationId": "createFiscalSeries",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "201": {
      "description": "Série fiscal criada"
     }
    },
    "summary": "Criar série de numeração",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/series/{series}": {
   "parameters": [
    {
     "name": "series",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "put": {
    "operationId": "updateFiscalSeries",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Série fiscal atualizada"
     }
    },
    "summary": "Alterar série de numeração",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/emitters": {
   "get": {
    "operationId": "listFiscalEmitters",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Emissores fiscais da unidade"
     }
    },
    "summary": "Listar emitentes",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   },
   "post": {
    "operationId": "createFiscalEmitter",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "201": {
      "description": "Emissor fiscal criado"
     }
    },
    "summary": "Cadastrar emitente",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/emitters/{emitter}": {
   "parameters": [
    {
     "name": "emitter",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "put": {
    "operationId": "updateFiscalEmitter",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Emissor fiscal atualizado"
     }
    },
    "summary": "Alterar emitente",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/health": {
   "get": {
    "operationId": "fiscalProviderHealth",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Estado do adaptador fiscal"
     }
    },
    "summary": "Verificar o provedor fiscal",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/fiscal/mode": {
   "get": {
    "operationId": "getFiscalMode",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Modo fiscal da unidade e se há transmissão à SEFAZ"
     }
    },
    "summary": "Consultar modo fiscal (produção ou homologação)",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/fiscal/tax-profiles": {
   "get": {
    "operationId": "listFiscalTaxProfiles",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Perfis tributários da unidade"
     }
    },
    "summary": "Listar perfis tributários",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   },
   "post": {
    "operationId": "createFiscalTaxProfile",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "201": {
      "description": "Perfil tributário criado"
     }
    },
    "summary": "Criar perfil tributário",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/tax-profiles/{profile}": {
   "parameters": [
    {
     "name": "profile",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "put": {
    "operationId": "updateFiscalTaxProfile",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Perfil tributário atualizado"
     }
    },
    "summary": "Alterar perfil tributário",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/rule-assignments": {
   "get": {
    "operationId": "listFiscalRuleAssignments",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Vigências que ligam escopo a perfil tributário"
     }
    },
    "summary": "Listar vínculos de regras fiscais",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   },
   "post": {
    "operationId": "createFiscalRuleAssignment",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "201": {
      "description": "Vigência registrada"
     }
    },
    "summary": "Vincular regra fiscal",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/assessments/{document}": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "operationId": "getFiscalAssessment",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Apuração congelada com itens e recebimentos"
     }
    },
    "summary": "Consultar cálculo de tributos",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/orders/{order}/fiscal-assessments": {
   "parameters": [
    {
     "name": "order",
     "in": "path",
     "required": true,
     "schema": {
      "type": "integer"
     }
    }
   ],
   "post": {
    "operationId": "assessOrderTaxes",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "202": {
      "description": "Venda apurada e congelada para a contabilidade"
     }
    },
    "summary": "Calcular tributos do pedido",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/rejections/{code}": {
   "parameters": [
    {
     "name": "code",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "operationId": "diagnoseFiscalRejection",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Orientação operacional para rejeição fiscal"
     }
    },
    "summary": "Explicar código de rejeição da SEFAZ",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/fiscal/incoming-documents": {
   "get": {
    "operationId": "listIncomingFiscalDocuments",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Notas fiscais de entrada importadas"
     }
    },
    "summary": "Listar notas de entrada",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/fiscal/incoming-documents/upload": {
   "post": {
    "operationId": "uploadIncomingFiscalXml",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "201": {
      "description": "XML de entrada importado e analisado"
     }
    },
    "summary": "Enviar XML de nota de entrada",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/fiscal/incoming-documents/{document}": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "operationId": "getIncomingFiscalDocument",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Nota fiscal de entrada e itens"
     }
    },
    "summary": "Consultar nota de entrada",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/fiscal/incoming-documents/{document}/xml": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "operationId": "downloadIncomingFiscalXml",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "XML original da nota de entrada"
     }
    },
    "summary": "Baixar XML da nota de entrada",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/fiscal/incoming-documents/{document}/items/{line}/reconcile": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    },
    {
     "name": "line",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "reconcileIncomingFiscalItem",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Item conciliado com o catálogo"
     }
    },
    "summary": "Vincular item da nota a um insumo",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/incoming-documents/{document}/receive": {
   "parameters": [
    {
     "name": "document",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "receiveIncomingFiscalDocument",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Nota recebida no estoque e financeiro"
     }
    },
    "summary": "Dar entrada da nota no estoque",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/paf/profile": {
   "get": {
    "operationId": "getPafRegionalProfile",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Perfil regional PAF-NFC-e"
     }
    },
    "summary": "Consultar perfil regional do PAF",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   },
   "put": {
    "operationId": "savePafRegionalProfile",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Perfil regional PAF-NFC-e atualizado"
     }
    },
    "summary": "Salvar perfil regional do PAF",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/paf/identify": {
   "get": {
    "operationId": "identifyPaf",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Identificação do PAF-NFC-e"
     }
    },
    "summary": "Identificar o PAF",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/fiscal/paf/exports": {
   "get": {
    "operationId": "listPafExports",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Arquivos PAF-NFC-e gerados"
     }
    },
    "summary": "Listar arquivos do PAF",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   },
   "post": {
    "operationId": "generatePafExport",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "201": {
      "description": "Arquivo PAF-NFC-e gerado"
     }
    },
    "summary": "Gerar arquivo do PAF",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "fiscal:write"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/fiscal/paf/exports/{export}/download": {
   "parameters": [
    {
     "name": "export",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "get": {
    "operationId": "downloadPafExport",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "responses": {
     "200": {
      "description": "Download do arquivo PAF-NFC-e"
     }
    },
    "summary": "Baixar arquivo do PAF",
    "tags": [
     "Fiscal"
    ],
    "description": "**Escopo:** `fiscal:read`.",
    "x-escopos": [
     "fiscal:read"
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ]
   }
  },
  "/webhooks/fiscal/{provider}": {
   "parameters": [
    {
     "name": "provider",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string"
     }
    }
   ],
   "post": {
    "operationId": "receiveFiscalWebhook",
    "security": [],
    "description": "Receptor Chamejar autenticado por segredo exclusivo do provedor e da unidade (FISCAL_WEBHOOK_SECRETS). X-Fiscal-Signature contém o HMAC-SHA256 hexadecimal do corpo bruto usando esse segredo; aceita prefixo sha256=. Limite de 64 KiB. O corpo identifica evento e documento; status e protocolo são obtidos por consulta autenticada ao adaptador fiscal, nunca aceitos do callback. Exige adaptador instalado para provedores reais.\n\nEndereço chamado pelo próprio canal ou provedor. Não chame a partir da sua integração.",
    "parameters": [
     {
      "name": "X-Fiscal-Location-Id",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 1
      }
     },
     {
      "name": "X-Fiscal-Webhook-Token",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "X-Fiscal-Signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "anyOf": [
         {
          "required": [
           "id"
          ]
         },
         {
          "required": [
           "event_id"
          ]
         }
        ],
        "properties": {
         "id": {
          "type": "string",
          "maxLength": 160
         },
         "event_id": {
          "type": "string",
          "maxLength": 160
         },
         "type": {
          "type": "string",
          "maxLength": 60
         },
         "document_id": {
          "type": "string",
          "maxLength": 160
         },
         "provider_document_id": {
          "type": "string",
          "maxLength": 160
         },
         "access_key": {
          "type": "string",
          "maxLength": 44
         }
        }
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Evento fiscal conciliado ou já processado"
     },
     "401": {
      "description": "Unidade ou autenticação inválida"
     },
     "404": {
      "description": "Perfil ou documento não pertence ao provedor e unidade informados"
     },
     "413": {
      "description": "Corpo excessivo"
     },
     "422": {
      "description": "Evento inválido"
     },
     "503": {
      "description": "Consulta fiscal autenticada indisponível ou incompatível"
     }
    },
    "summary": "Receber retorno do provedor fiscal (uso do provedor)",
    "tags": [
     "Webhooks de entrada"
    ],
    "x-uso-interno": true
   }
  },
  "/webhooks/marketplaces/{provider}": {
   "post": {
    "operationId": "receiveMarketplaceWebhook",
    "description": "Recebe um evento do marketplace de forma idempotente (por conexão e identificador externo). Fora do sandbox, exige segredo de pelo menos 32 caracteres, X-Marketplace-Timestamp Unix em segundos e X-Marketplace-Signature hexadecimal HMAC-SHA256 sobre timestamp + ponto + corpo bruto usando o token como chave. Janela de 300 segundos. Conexão inexistente, token inválido ou assinatura inválida retornam 401. Limite de 256 KiB. Payload no formato de evento do iFood (fullCode e orderId) preenche event_type, event_code, external_order_id, occurred_at e source=webhook e entra no mesmo pipeline do polling.\n\nEndereço chamado pelo próprio canal ou provedor. Não chame a partir da sua integração.",
    "parameters": [
     {
      "name": "provider",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "X-Marketplace-Connection",
      "in": "header",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "X-Marketplace-Token",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "X-Marketplace-Timestamp",
      "in": "header",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "X-Marketplace-Signature",
      "in": "header",
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "additionalProperties": true
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Evento recebido de forma idempotente"
     },
     "401": {
      "description": "Segredo da conexão inválido"
     },
     "422": {
      "description": "Evento sem identificador externo"
     }
    },
    "summary": "Receber evento de marketplace (uso dos canais)",
    "tags": [
     "Webhooks de entrada"
    ],
    "x-uso-interno": true,
    "security": []
   }
  },
  "/opendelivery/{merchant}/merchant": {
   "get": {
    "operationId": "getOpenDeliveryMerchant",
    "description": "Retorna dados e cardápio da loja Aiqfome quando a conexão está ativa. Disponível em produção somente com AIQFOME_ENABLED.\n\nEndereço chamado pelo próprio canal ou provedor. Não chame a partir da sua integração.",
    "parameters": [
     {
      "name": "merchant",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "X-API-KEY",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Dados da loja"
     },
     "403": {
      "description": "Chave inválida"
     },
     "503": {
      "description": "Conexão indisponível"
     }
    },
    "summary": "Fornecer dados da loja no padrão Open Delivery (uso do aiqfome)",
    "tags": [
     "Webhooks de entrada"
    ],
    "x-uso-interno": true,
    "security": []
   }
  },
  "/webhooks/aiqfome/events": {
   "post": {
    "operationId": "receiveAiqfomeWebhook",
    "description": "Recebe evento Aiqfome V2 autenticado pelo segredo da conexão. Disponível em produção somente com AIQFOME_ENABLED.\n\nEndereço chamado pelo próprio canal ou provedor. Não chame a partir da sua integração.",
    "parameters": [
     {
      "name": "Authorization",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "additionalProperties": true
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Evento recebido"
     },
     "400": {
      "description": "Evento inválido"
     },
     "401": {
      "description": "Segredo inválido"
     },
     "413": {
      "description": "Corpo excessivo"
     },
     "503": {
      "description": "Falha ao persistir"
     }
    },
    "summary": "Receber evento do aiqfome (uso do aiqfome)",
    "tags": [
     "Webhooks de entrada"
    ],
    "x-uso-interno": true,
    "security": []
   }
  },
  "/webhooks/keeta/events": {
   "post": {
    "operationId": "receiveKeetaWebhook",
    "description": "Evento Open Delivery Keeta autenticado por HMAC-SHA256 Base64 do corpo bruto e roteado pelo merchant externo para uma única conexão ativa. Persiste e deduplica antes de responder 204; limite de 256 KiB, sem throttle API compartilhado. Disponível em produção somente com KEETA_ENABLED. Configurar ordersWebhookURL no onboarding; não executar acknowledgment de polling para webhooks.\n\nEndereço chamado pelo próprio canal ou provedor. Não chame a partir da sua integração.",
    "parameters": [
     {
      "name": "X-App-Id",
      "in": "header",
      "required": true,
      "description": "Identificador da Keeta",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "X-App-MerchantId",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "maxLength": 100
      }
     },
     {
      "name": "X-App-Signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "eventId",
         "eventType",
         "orderId",
         "createdAt"
        ],
        "additionalProperties": true,
        "properties": {
         "eventId": {
          "type": "string"
         },
         "eventType": {
          "type": "string"
         },
         "orderId": {
          "type": "string"
         },
         "createdAt": {
          "type": "string",
          "format": "date-time"
         }
        }
       }
      }
     }
    },
    "responses": {
     "204": {
      "description": "Evento persistido ou duplicata reconhecida"
     },
     "400": {
      "description": "Evento inválido"
     },
     "403": {
      "description": "Assinatura ou vínculo inválido"
     },
     "413": {
      "description": "Corpo excessivo"
     },
     "503": {
      "description": "Integração desativada ou falha de persistência ou fila"
     }
    },
    "summary": "Receber evento da Keeta (uso da Keeta)",
    "tags": [
     "Webhooks de entrada"
    ],
    "x-uso-interno": true,
    "security": []
   }
  },
  "/webhooks/vainabag/events": {
   "post": {
    "operationId": "receiveVainabagWebhook",
    "description": "Recebe evento Vainabag assinado; consulta o estado remoto antes de atualizar a entrega. Disponível em produção somente com VAINABAG_ENABLED.\n\nEndereço chamado pelo próprio canal ou provedor. Não chame a partir da sua integração.",
    "parameters": [
     {
      "name": "X-Vainabag-Signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "additionalProperties": true
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Evento recebido"
     },
     "400": {
      "description": "Evento inválido"
     },
     "401": {
      "description": "Assinatura inválida"
     },
     "413": {
      "description": "Corpo excessivo"
     },
     "503": {
      "description": "Falha ao persistir"
     }
    },
    "summary": "Receber evento da Vainabag (uso da Vainabag)",
    "tags": [
     "Webhooks de entrada"
    ],
    "x-uso-interno": true,
    "security": []
   }
  },
  "/webhooks/vainabag-marketplace/events": {
   "post": {
    "operationId": "receiveVainabagMarketplaceWebhook",
    "description": "Recebe evento assinado do Marketplace da Vainabag (order.created e order.status_changed). É apenas um sinal que antecipa a conferência de pedidos na API da Vainabag; nunca cria pedido por conta própria. A assinatura é sha256= mais HMAC-SHA256 de timestamp, ponto e corpo bruto, com tolerância de 5 minutos no X-Vainabag-Timestamp. Canal desligado por padrão; sem VAINABAG_MARKETPLACE_ENABLED responde 404 em qualquer ambiente.\n\nEndereço chamado pelo próprio canal ou provedor. Não chame a partir da sua integração.",
    "parameters": [
     {
      "name": "X-Vainabag-Signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "X-Vainabag-Timestamp",
      "in": "header",
      "required": true,
      "description": "Segundos Unix do envio",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "X-Vainabag-Event",
      "in": "header",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "order.created",
        "order.status_changed"
       ]
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "additionalProperties": true
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Evento recebido"
     },
     "400": {
      "description": "Evento inválido"
     },
     "401": {
      "description": "Assinatura inválida ou fora da tolerância"
     },
     "404": {
      "description": "Canal desligado"
     },
     "413": {
      "description": "Corpo excessivo"
     }
    },
    "summary": "Receber evento do Marketplace da Vainabag (uso da Vainabag)",
    "tags": [
     "Webhooks de entrada"
    ],
    "x-uso-interno": true,
    "security": []
   }
  },
  "/webhooks/ifood/events": {
   "post": {
    "operationId": "receiveOfficialIfoodWebhook",
    "description": "Webhook oficial exclusivo de aplicação iFood centralizada. Valida X-IFood-Signature com HMAC-SHA256 hexadecimal em maiúsculas ou minúsculas sobre o corpo bruto antes do JSON. Evento é persistido por ID e loja antes do 202; KEEPALIVE exige presença por merchant e responde apenas lojas ativas vinculadas. Exclui o throttle:api herdado; as demais rotas mantêm seus limites. Sem vínculo roteável persiste em quarentena cifrada da aplicação antes do 202, sem atribuir unidade. Recuperação a cada 30 s após vínculo ativo único na mesma aplicação; conteúdo expira em 24 h, sem extensão por replay, e é removido na próxima rotina. Falha de persistência retorna 503. A URL HTTPS é cadastrada no Portal iFood.\n\nEndereço chamado pelo próprio canal ou provedor. Não chame a partir da sua integração.",
    "parameters": [
     {
      "name": "X-IFood-Signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^[a-fA-F0-9]{64}$"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "additionalProperties": true
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Evento persistido na conexão ou quarentena ou heartbeat respondido"
     },
     "401": {
      "description": "Assinatura inválida"
     },
     "503": {
      "description": "Falha de persistência ou aplicação/presença sem configuração central compatível"
     }
    },
    "summary": "Receber evento do iFood (uso do iFood)",
    "tags": [
     "Webhooks de entrada"
    ],
    "x-uso-interno": true,
    "security": []
   }
  },
  "/webhooks/ifood/test/events": {
   "post": {
    "operationId": "receiveOfficialIfoodTestWebhook",
    "description": "Mesmo contrato do webhook oficial, com credenciais, assinatura e quarentena da aplicação de teste. Exige IFOOD_TEST_ENABLED e aplicação de teste centralizada; não compartilha eventos nem vínculos com produção.\n\nEndereço chamado pelo próprio canal ou provedor. Não chame a partir da sua integração.",
    "parameters": [
     {
      "name": "X-IFood-Signature",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^[a-fA-F0-9]{64}$"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "additionalProperties": true
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Evento de teste persistido ou heartbeat respondido"
     },
     "401": {
      "description": "Assinatura inválida"
     },
     "503": {
      "description": "Falha de persistência ou aplicação de teste indisponível"
     }
    },
    "summary": "Receber evento de teste do iFood (uso do iFood)",
    "tags": [
     "Webhooks de entrada"
    ],
    "x-uso-interno": true,
    "security": []
   }
  },
  "/marketplaces/connections": {
   "get": {
    "operationId": "listMarketplaceConnections",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     }
    ],
    "responses": {
     "200": {
      "description": "Conexões da unidade",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/MarketplaceConnection"
           }
          }
         }
        }
       }
      }
     }
    },
    "summary": "Listar conexões",
    "tags": [
     "Marketplaces"
    ],
    "description": "**Escopo:** `marketplaces:read`.",
    "x-escopos": [
     "marketplaces:read"
    ]
   },
   "post": {
    "operationId": "createMarketplaceConnection",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/MarketplaceConnectionInput"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Conexão criada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "$ref": "#/components/schemas/MarketplaceConnection"
          }
         }
        }
       }
      }
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Criar conexão",
    "tags": [
     "Marketplaces"
    ],
    "description": "**Escopo:** `marketplaces:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}": {
   "put": {
    "operationId": "updateMarketplaceConnection",
    "description": "Atualiza a conexão. Provider e ambiente iFood são imutáveis; crie outra conexão para trocar de canal ou passar de homologação a produção. Sem webhook_secret no corpo, o segredo já cadastrado é preservado; credentials é mesclado às credenciais guardadas.\n\n**Escopo:** `marketplaces:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/MarketplaceConnectionInput"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Conexão atualizada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "$ref": "#/components/schemas/MarketplaceConnection"
          }
         }
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Alterar conexão",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/health": {
   "get": {
    "operationId": "marketplaceConnectionHealth",
    "description": "Estado local da conexão (nunca chama o marketplace). No iFood oficial de homologação ou produção devolve status ok, degraded, error ou not_configured, token, polling, pending_catalog, failed_pushes e stuck_events; no sandbox local, sandbox_ready ou configured_not_verified.\n\n**Escopo:** `marketplaces:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Estado do adapter e configuração da conexão",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "$ref": "#/components/schemas/MarketplaceHealth"
          }
         }
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "summary": "Consultar saúde da conexão",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:read"
    ]
   }
  },
  "/marketplaces/connections/{connection}/checklist": {
   "get": {
    "operationId": "marketplaceConnectionChecklist",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Checklist de ativação do parceiro sem expor segredos",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "$ref": "#/components/schemas/MarketplaceChecklist"
          }
         }
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "summary": "Consultar lista de verificação da conexão",
    "tags": [
     "Marketplaces"
    ],
    "description": "**Escopo:** `marketplaces:read`.",
    "x-escopos": [
     "marketplaces:read"
    ]
   }
  },
  "/marketplaces/connections/{connection}/merchant": {
   "get": {
    "operationId": "getIfoodMerchantOperation",
    "description": "Consulta status por operação, pausas e horários publicados diretamente no iFood. CLOSED por horário é estado normal. Exige marketplaces:read e unidade da conexão.\n\n**Escopo:** `marketplaces:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Snapshot da operação iFood"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "summary": "Consultar status, pausas e horários da loja no iFood",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:read"
    ]
   }
  },
  "/marketplaces/connections/{connection}/merchant/interruptions": {
   "post": {
    "operationId": "createIfoodMerchantInterruption",
    "description": "Pausa temporária de 1 minuto a 7 dias. Idempotency-Key é obrigatória e reserva o POST por 24 horas; resultado incerto exige consultar a lista antes de nova chave. Exige marketplaces:write.\n\n**Escopo:** `marketplaces:write`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "description",
         "start",
         "end"
        ],
        "properties": {
         "description": {
          "type": "string",
          "maxLength": 255
         },
         "start": {
          "type": "string",
          "format": "date-time"
         },
         "end": {
          "type": "string",
          "format": "date-time"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Pausa confirmada pelo iFood"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Pausar a loja no iFood",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/merchant/interruptions/{interruption}": {
   "delete": {
    "operationId": "deleteIfoodMerchantInterruption",
    "description": "Confere se a pausa pertence à loja antes de solicitar a remoção. Exige marketplaces:write.\n\n**Escopo:** `marketplaces:write`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "interruption",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Pausa removida"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Remover pausa da loja no iFood",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/merchant/opening-hours": {
   "put": {
    "operationId": "replaceIfoodMerchantOpeningHours",
    "description": "Substitui explicitamente toda a grade semanal do iFood. Dias omitidos são fechados. Não modifica os horários públicos do TastyIgniter. Exige marketplaces:write.\n\n**Escopo:** `marketplaces:write`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "shifts"
        ],
        "properties": {
         "shifts": {
          "type": "array",
          "minItems": 1,
          "maxItems": 28,
          "items": {
           "type": "object",
           "required": [
            "dayOfWeek",
            "start",
            "duration"
           ],
           "properties": {
            "dayOfWeek": {
             "type": "string",
             "enum": [
              "MONDAY",
              "TUESDAY",
              "WEDNESDAY",
              "THURSDAY",
              "FRIDAY",
              "SATURDAY",
              "SUNDAY"
             ]
            },
            "start": {
             "type": "string",
             "example": "18:00:00"
            },
            "duration": {
             "type": "integer",
             "minimum": 1,
             "maximum": 1440
            }
           }
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Grade enviada ao iFood"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Substituir horários da loja no iFood",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/poll": {
   "post": {
    "operationId": "pollMarketplaceConnection",
    "description": "Sincroniza agora, de forma síncrona, os eventos do iFood oficial de homologação ou produção (a mesma rodada do agendador). Não usa Idempotency-Key, pois o polling é naturalmente idempotente (ack e unicidade dos eventos) e o middleware de idempotência executaria o handler dentro de uma transação, deixando chamadas ao iFood, ack e rotação do refresh token sem confirmação no banco. Limitado a 6 chamadas por minuto por usuário. O resultado pode ser locked, backoff, skipped ou error sem que a requisição falhe.\n\n**Escopo:** `marketplaces:write`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Resultado da rodada de polling",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "$ref": "#/components/schemas/MarketplacePollResult"
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "description": "Conexão que não é do iFood oficial"
     },
     "429": {
      "description": "Limite de chamadas excedido"
     }
    },
    "summary": "Sincronizar agora",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/ifood/connect/start": {
   "post": {
    "operationId": "startIfoodConnection",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Código/URL de autorização ou indicação de configuração pendente"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "summary": "Iniciar autorização da loja no iFood",
    "tags": [
     "Marketplaces"
    ],
    "description": "**Escopo:** `marketplaces:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/ifood/connect/central": {
   "post": {
    "operationId": "connectCentralIfoodMerchant",
    "description": "Exige superusuário da plataforma além de marketplaces:write e escopo da unidade. Vincula uma conexão nova à loja já autorizada no Portal para a aplicação centralizada do ambiente da conexão; tokens de loja não podem reivindicar merchants com a credencial global. Requer IFOOD_AUTH_MODE=centralized em produção ou IFOOD_TEST_AUTH_MODE=centralized em homologação e verifica GET merchant antes de ativar. Não usa idempotência transacional por envolver token externo.\n\n**Escopo:** `marketplaces:write`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "merchant_id"
        ],
        "properties": {
         "merchant_id": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Loja verificada e vinculada"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     },
     "503": {
      "description": "Aplicação centralizada não configurada"
     }
    },
    "summary": "Vincular loja ao aplicativo iFood centralizado",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/ifood/connect/complete": {
   "post": {
    "operationId": "completeIfoodConnection",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "state",
         "authorization_code"
        ],
        "properties": {
         "state": {
          "type": "string"
         },
         "authorization_code": {
          "type": "string"
         },
         "authorization_code_verifier": {
          "type": "string"
         },
         "merchant_id": {
          "type": "string",
          "description": "Identificador da loja no iFood; obrigatório para o polling"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Conexão OAuth ativada"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "description": "Estado inválido ou expirado"
     },
     "503": {
      "description": "Credenciais da aplicação ainda não configuradas"
     }
    },
    "summary": "Concluir autorização da loja no iFood",
    "tags": [
     "Marketplaces"
    ],
    "description": "**Escopo:** `marketplaces:write`.\n\n**Exige** `Idempotency-Key`.",
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/mappings": {
   "get": {
    "operationId": "listMarketplaceMappings",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Mapeamentos da conexão",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/MarketplaceMapping"
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "summary": "Listar vínculos de catálogo",
    "tags": [
     "Marketplaces"
    ],
    "description": "**Escopo:** `marketplaces:read`.",
    "x-escopos": [
     "marketplaces:read"
    ]
   },
   "put": {
    "operationId": "replaceMarketplaceMappings",
    "description": "Substitui os vínculos manuais da conexão; vínculos gerenciados pela publicação do catálogo iFood são preservados e não podem ser forjados. entity_type option vincula um código de opção do marketplace a um option_value_id global.\n\n**Escopo:** `marketplaces:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "mappings"
        ],
        "properties": {
         "mappings": {
          "type": "array",
          "maxItems": 1000,
          "items": {
           "type": "object",
           "required": [
            "entity_type",
            "local_id",
            "external_id"
           ],
           "properties": {
            "entity_type": {
             "type": "string",
             "enum": [
              "menu",
              "category",
              "payment",
              "status",
              "option"
             ]
            },
            "local_id": {
             "type": "string",
             "maxLength": 80
            },
            "external_id": {
             "type": "string",
             "maxLength": 160
            },
            "metadata": {
             "type": "object",
             "additionalProperties": true
            },
            "is_active": {
             "type": "boolean"
            }
           }
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Mapeamentos substituídos",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/MarketplaceMapping"
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Substituir vínculos manuais de catálogo",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/catalog/sync": {
   "post": {
    "operationId": "syncMarketplaceCatalog",
    "description": "No iFood de produção, enfileira um produto local selecionado para publicação no Catalog v2.0; não significa que o iFood já o aceitou. Nos adaptadores de teste, registra o pedido no outbox.\n\n**Escopo:** `marketplaces:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "menu_id"
        ],
        "properties": {
         "menu_id": {
          "type": "integer"
         },
         "category_id": {
          "type": "integer"
         },
         "sync_stock": {
          "type": "boolean",
          "description": "Estoque rastreado da unidade; adesão opcional"
         }
        }
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Produto enfileirado ou solicitação registrada no outbox do adaptador de teste"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Sincronizar catálogo com o canal",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/catalog": {
   "get": {
    "operationId": "listIfoodCatalogPublications",
    "description": "Lista produtos locais da unidade com o estado da publicação iFood; não consulta o catálogo remoto.\n\n**Escopo:** `marketplaces:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Produtos e publicações"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "summary": "Listar produtos publicados no iFood",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:read"
    ]
   }
  },
  "/marketplaces/connections/{connection}/catalog/menus/{menu}/preview": {
   "get": {
    "operationId": "previewIfoodCatalogItem",
    "description": "Prévia local de preço, disponibilidade, categorias, adicionais e impedimentos de publicação; não altera o iFood.\n\n**Escopo:** `marketplaces:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "menu",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Prévia e impedimentos"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "summary": "Prever publicação de produto no iFood",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:read"
    ]
   }
  },
  "/marketplaces/connections/{connection}/catalog/menus/{menu}/publish": {
   "post": {
    "operationId": "publishIfoodCatalogItem",
    "description": "Publica ou atualiza um produto explicitamente selecionado. Apenas produtos já publicados são conferidos pelo agendador. Pizzas meio a meio, promoções e regras locais sem tradução fiel são recusadas.\n\n**Escopo:** `marketplaces:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "menu",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "category_id": {
          "type": "integer",
          "description": "Obrigatório quando o produto tem várias categorias"
         },
         "sync_stock": {
          "type": "boolean",
          "description": "Opt-in do estoque rastreado da unidade"
         }
        }
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Publicação enfileirada; consulte o estado até published ou failed"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Publicar produto no iFood",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/catalog/categories/{category}/bind": {
   "post": {
    "operationId": "bindIfoodCatalogCategory",
    "description": "Vincula uma categoria local a uma categoria já conferida na loja iFood após resultado incerto de criação. O ID e o nome são verificados na API autenticada do parceiro.\n\n**Escopo:** `marketplaces:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "category",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "external_id"
        ],
        "properties": {
         "external_id": {
          "type": "string",
          "maxLength": 160
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Categoria vinculada"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Vincular categoria ao iFood",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/orders/{order}/status": {
   "post": {
    "operationId": "syncMarketplaceOrderStatus",
    "description": "Reenvia manualmente ao marketplace o status do pedido, sem alterar o pedido local. Pedidos do iFood importados passam pelo ledger de envios (push_id e action); o pedido local precisa estar no estado pedido ou além. Pedidos sem vínculo (sandbox) apenas registram o pedido de atualização no outbox.\n\n**Escopo:** `marketplaces:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "order",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "status"
        ],
        "properties": {
         "status": {
          "type": "string",
          "enum": [
           "placed",
           "accepted",
           "preparing",
           "ready",
           "dispatched",
           "completed",
           "cancelled"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Atualização de status enfileirada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "$ref": "#/components/schemas/MarketplaceStatusRequestResult"
          }
         }
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Reenviar status do pedido ao canal",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/events": {
   "get": {
    "operationId": "listMarketplaceEvents",
    "description": "Eventos recebidos e seus estados. O pedido completo buscado no marketplace (details) nunca é exposto.\n\n**Escopo:** `marketplaces:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     }
    ],
    "responses": {
     "200": {
      "description": "Eventos recebidos e seus estados",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaginatedMarketplaceEvents"
        }
       }
      }
     }
    },
    "summary": "Listar eventos recebidos dos canais",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:read"
    ]
   }
  },
  "/marketplaces/issues": {
   "get": {
    "operationId": "listMarketplaceIssues",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     }
    ],
    "responses": {
     "200": {
      "description": "Divergências de mapeamento e falhas reprocessáveis",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaginatedMarketplaceEvents"
        }
       }
      }
     }
    },
    "summary": "Listar pendências das integrações",
    "tags": [
     "Marketplaces"
    ],
    "description": "**Escopo:** `marketplaces:read`.",
    "x-escopos": [
     "marketplaces:read"
    ]
   }
  },
  "/marketplaces/events/{event}/replay": {
   "post": {
    "operationId": "replayMarketplaceEvent",
    "description": "Reenfileira um evento com status failed, needs_mapping, received ou deferred. Eventos processed e ignored são finais e não são reabertos. Evento antigo já minimizado por retenção de privacidade também é recusado (422), pois os dados necessários ao processamento já foram removidos.\n\n**Escopo:** `marketplaces:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "event",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Evento reenfileirado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "type": "object",
           "required": [
            "id",
            "status"
           ],
           "properties": {
            "id": {
             "type": "integer"
            },
            "status": {
             "type": "string",
             "const": "received"
            }
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "description": "Evento em estado final ou já minimizado por privacidade"
     }
    },
    "summary": "Reprocessar evento",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/catalog/pending": {
   "get": {
    "operationId": "listMarketplaceCatalogPending",
    "description": "Fila de catálogo pendente da unidade, com as 3 melhores sugestões de vínculo (apenas para itens pending) e o número de pedidos bloqueados. Sugestões só ordenam candidatos; o vínculo é sempre decisão do operador.\n\n**Escopo:** `marketplaces:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "pending",
        "resolved",
        "ignored",
        "all"
       ],
       "default": "pending"
      }
     },
     {
      "name": "connection_id",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Pendências de catálogo",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaginatedMarketplaceCatalogPending"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Listar itens do canal sem vínculo",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:read"
    ]
   }
  },
  "/marketplaces/catalog/pending/{pending}/resolve": {
   "post": {
    "operationId": "resolveMarketplaceCatalogPending",
    "description": "Vincula o item pendente a um produto (ou valor de opção) local e reprocessa os pedidos que ele bloqueava. Repetir com o mesmo local_id não tem efeito; outro local_id para item já vinculado é recusado.\n\n**Escopo:** `marketplaces:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "pending",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "local_id"
        ],
        "properties": {
         "local_id": {
          "type": "string",
          "pattern": "^[0-9]{1,18}$",
          "description": "Identificador numérico do produto ou do valor de opção local"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Pendência vinculada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "$ref": "#/components/schemas/MarketplaceCatalogPendingResolution"
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Vincular item pendente a um produto",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/catalog/pending/{pending}/ignore": {
   "post": {
    "operationId": "ignoreMarketplaceCatalogPending",
    "description": "Ignora uma opção pendente (ela segue como texto no comentário do pedido). Itens do cardápio não podem ser ignorados.\n\n**Escopo:** `marketplaces:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "pending",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": false,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "reason": {
          "type": "string",
          "maxLength": 255,
          "nullable": true
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Pendência ignorada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "$ref": "#/components/schemas/MarketplaceCatalogPending"
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Ignorar item pendente",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  },
  "/marketplaces/orders": {
   "get": {
    "operationId": "listMarketplaceOrders",
    "description": "Pedidos importados do marketplace. Não inclui snapshot nem dados pessoais do cliente.\n\n**Escopo:** `marketplaces:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     },
     {
      "name": "connection_id",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1
      }
     },
     {
      "name": "external_status",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "PLACED",
        "CONFIRMED",
        "READY_TO_PICKUP",
        "DISPATCHED",
        "CONCLUDED",
        "CANCELLED"
       ]
      }
     },
     {
      "name": "needs_attention",
      "in": "query",
      "schema": {
       "type": "boolean"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Pedidos do marketplace",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaginatedMarketplaceOrders"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Listar pedidos importados dos canais",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:read"
    ]
   }
  },
  "/marketplaces/orders/{marketplaceOrder}/financial": {
   "get": {
    "operationId": "getIfoodOrderFinancial",
    "summary": "Consultar financeiro do pedido iFood",
    "description": "Composição financeira e situação fiscal do pedido iFood\n\nExige marketplaces:read e payments:read. Total do cliente difere da venda comercial/fiscal e do repasse. Documento do consumidor não é retornado. not_migrated exige recarga explícita; review_required impede cobrança e nova apuração.\n\n**Escopo:** `marketplaces:read`, `payments:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "marketplaceOrder",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Composição sanitizada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/IfoodOrderFinancial"
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:read",
     "payments:read"
    ]
   }
  },
  "/marketplaces/orders/{marketplaceOrder}/financial/resync": {
   "post": {
    "operationId": "resyncIfoodOrderFinancial",
    "summary": "Recarregar financeiro do pedido iFood",
    "description": "Recarregar valores do iFood e reconhecer pagamento externo\n\nExige marketplaces:write e payments:write. Consulta autenticada fora da transação OAuth. Não altera itens, não cobra gateway, não confirma repasse. Mudança após captura continua em review_required. Pedido minimizado ou itens divergentes exigem tratamento próprio.\n\n**Escopo:** `marketplaces:write`, `payments:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "marketplaceOrder",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Financeiro atualizado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/IfoodOrderFinancial"
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "409": {
      "$ref": "#/components/responses/Conflict"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     },
     "503": {
      "description": "Consulta ou atualização em andamento; respeite Retry-After"
     }
    },
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write",
     "payments:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/financial": {
   "get": {
    "operationId": "listIfoodFinancialEntries",
    "summary": "Listar conciliação e repasses do iFood",
    "description": "Conciliação oficial importada e títulos de repasse\n\nExige marketplaces:read e payments:read. Valores inteiros assinados em centavos. competence filtra lançamentos/resumo; settlements contém até 100 títulos recentes de todas as competências. Apenas impacto_no_repasse SIM compõe expected_net_minor. confirmed significa conferência manual do extrato, sem consulta bancária automática. api_sync_available é false.\n\n**Escopo:** `marketplaces:read`, `payments:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "competence",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}$"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "data paginado de lançamentos, meta, summary de créditos/débitos/líquido e settlements com estado expected/confirmed/divergent"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:read",
     "payments:read"
    ]
   }
  },
  "/marketplaces/connections/{connection}/financial/import": {
   "post": {
    "operationId": "importIfoodReconciliation",
    "summary": "Importar arquivo de conciliação do iFood",
    "description": "Importar arquivo mensal cumulativo oficial de conciliação\n\nExige marketplaces:write e payments:write. CSV/CSV.gz UTF-8, delimitador ponto e vírgula, máximo 10 MB e 20 mil linhas. Loja e competência devem corresponder à conexão. Importação atômica e idempotente; não remove/altera lançamentos já conciliados. Reutilizar chave com outro conteúdo retorna 409. Não confirma repasses nem estorna cliente.\n\n**Escopo:** `marketplaces:write`, `payments:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "required": [
         "competence",
         "file"
        ],
        "properties": {
         "competence": {
          "type": "string",
          "example": "2026-10"
         },
         "file": {
          "type": "string",
          "format": "binary"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Quantidades imported, total_rows e titles"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "409": {
      "$ref": "#/components/responses/Conflict"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write",
     "payments:write"
    ]
   }
  },
  "/marketplaces/connections/{connection}/financial/settlements/{settlement}/confirm": {
   "post": {
    "operationId": "confirmIfoodBankSettlement",
    "summary": "Confirmar repasse do iFood no extrato",
    "description": "Registrar conferência manual de título no extrato bancário\n\nExige marketplaces:write e payments:write. Uso de operador financeiro com comprovante; não dar esta ferramenta ao atendente para confirmar por alegação do cliente. Valor assinado deve ser exatamente o esperado; títulos divergentes ou já confirmados com outros dados são recusados. Título negativo representa saída. Não confirma pagamento de pedido nem processa estorno ao consumidor.\n\n**Escopo:** `marketplaces:write`, `payments:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "connection",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "settlement",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "amount_minor",
         "date",
         "bank_reference"
        ],
        "properties": {
         "amount_minor": {
          "type": "integer",
          "example": 7080
         },
         "date": {
          "type": "string",
          "format": "date",
          "description": "Data ISO não futura da movimentação no extrato"
         },
         "bank_reference": {
          "type": "string",
          "maxLength": 160,
          "minLength": 1
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Título conferido, com confirmation_source manual_bank_statement"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "409": {
      "$ref": "#/components/responses/Conflict"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write",
     "payments:write"
    ]
   }
  },
  "/marketplaces/orders/{marketplaceOrder}/negotiations": {
   "get": {
    "operationId": "listIfoodNegotiations",
    "summary": "Listar negociações e alterações do pedido iFood",
    "description": "Acompanhar disputas Handshake e alterações do pedido\n\nExige marketplaces:read. IDs locais do vínculo e da negociação. Mensagens, fotos e URLs privadas não são expostas. changes informa revisões pendentes, datas e versão canônica para conferência.\n\n**Escopo:** `marketplaces:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     },
     {
      "name": "marketplaceOrder",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Disputas sanitizadas da unidade",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/IfoodNegotiation"
           }
          },
          "meta": {
           "type": "object",
           "additionalProperties": true
          },
          "changes": {
           "type": "object",
           "properties": {
            "version": {
             "type": "integer"
            },
            "items_changed_at": {
             "type": "string",
             "format": "date-time",
             "nullable": true
            },
            "address_changed_at": {
             "type": "string",
             "format": "date-time",
             "nullable": true
            },
            "delivery_estimate_at": {
             "type": "string",
             "format": "date-time",
             "nullable": true
            },
            "review": {
             "type": "object",
             "additionalProperties": true,
             "nullable": true
            }
           }
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:read"
    ]
   }
  },
  "/marketplaces/orders/{marketplaceOrder}/negotiations/{negotiation}/response": {
   "post": {
    "operationId": "respondIfoodNegotiation",
    "summary": "Responder negociação do iFood",
    "description": "Aceitar, recusar ou fazer contraproposta em uma disputa iFood\n\nExige marketplaces:write e orders:cancel. Uma resposta por disputa antes do prazo. 202 é envio, não acordo final nem cancelamento do pedido. Timeout/5xx/422 podem deixar resultado incerto sem reenvio; 429 respeita Retry-After. Aprovação order.cancel é exigida para aceite/oferta financeira quando configurada.\n\n**Escopo:** `marketplaces:write`, `orders:cancel`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "marketplaceOrder",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "negotiation",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "action"
        ],
        "properties": {
         "action": {
          "type": "string",
          "enum": [
           "accept",
           "reject",
           "alternative"
          ]
         },
         "reason": {
          "type": "string",
          "maxLength": 250,
          "description": "Motivo oferecido para aceite ou prazo; justificativa obrigatória para recusa"
         },
         "detail_reason": {
          "type": "string",
          "maxLength": 250
         },
         "alternative_id": {
          "type": "string",
          "maxLength": 180,
          "description": "ID de uma alternativa oferecida nesta disputa"
         },
         "amount_minor": {
          "type": "integer",
          "minimum": 1,
          "description": "Centavos inteiros para REFUND ou BENEFIT, até maxAmount e em BRL"
         },
         "additional_time_minutes": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1440,
          "description": "Minutos entre as opções oferecidas"
         },
         "approval_challenge": {
          "type": "string",
          "maxLength": 160
         }
        }
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Resposta enviada; acompanhar HSS",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/IfoodNegotiation"
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     },
     "503": {
      "description": "Falha temporária ou resultado incerto; consulte a disputa antes de tentar novamente"
     }
    },
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write",
     "orders:cancel"
    ]
   }
  },
  "/marketplaces/orders/{marketplaceOrder}/changes/review": {
   "post": {
    "operationId": "reviewIfoodOrderChanges",
    "summary": "Registrar conferência de alterações do pedido iFood",
    "description": "Registrar conferência operacional de alterações externas\n\nExige marketplaces:write, orders:write e payments:write. Não movimenta estoque ou dinheiro. sync e espera de CANCELLED não são apagáveis por conferência. Versão divergente exige nova leitura.\n\n**Escopo:** `marketplaces:write`, `orders:write`, `payments:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "marketplaceOrder",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "review_keys",
         "expected_version"
        ],
        "properties": {
         "review_keys": {
          "type": "array",
          "minItems": 1,
          "items": {
           "type": "string",
           "enum": [
            "items",
            "address",
            "financial",
            "negotiations"
           ]
          }
         },
         "expected_version": {
          "type": "integer",
          "minimum": 1
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Conferência registrada"
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "409": {
      "description": "O pedido mudou; atualize antes de revisar"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write",
     "orders:write",
     "payments:write"
    ]
   }
  },
  "/marketplaces/orders/{marketplaceOrder}/cancellation-reasons": {
   "get": {
    "operationId": "listIfoodCancellationReasons",
    "summary": "Listar motivos de cancelamento do iFood",
    "description": "Consultar motivos de cancelamento disponíveis no iFood para este pedido\n\nExige marketplaces:read. marketplaceOrder é o id do vínculo retornado por GET /marketplaces/orders, e não o order_id local. Falha transitória do parceiro retorna 503 e Retry-After quando informado.\n\n**Escopo:** `marketplaces:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "marketplaceOrder",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Motivos atuais",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "required": [
             "code",
             "description"
            ],
            "properties": {
             "code": {
              "type": "string"
             },
             "description": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     },
     "503": {
      "description": "iFood indisponível ou com limite de requisições"
     }
    },
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:read"
    ]
   }
  },
  "/marketplaces/orders/{marketplaceOrder}/cancellation": {
   "get": {
    "operationId": "getIfoodCancellation",
    "summary": "Consultar cancelamento do pedido iFood",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "name": "marketplaceOrder",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Situação do cancelamento",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/IfoodCancellationState"
          }
         }
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    },
    "tags": [
     "Marketplaces"
    ],
    "description": "Consultar solicitação e confirmação de cancelamento iFood\n\n**Escopo:** `marketplaces:read`.",
    "x-escopos": [
     "marketplaces:read"
    ]
   },
   "post": {
    "operationId": "requestIfoodCancellation",
    "summary": "Solicitar cancelamento do pedido ao iFood",
    "description": "Solicitar cancelamento sem encerrar o pedido antes da confirmação do iFood\n\nExige marketplaces:write e orders:cancel. O motivo é revalidado no envio. requested e awaiting_confirmation preservam o pedido ativo. Somente CANCELLED confirma o cancelamento. Recusa ou erro não geram estorno nem retorno de estoque.\n\n**Escopo:** `marketplaces:write`, `orders:cancel`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "marketplaceOrder",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "cancellation_code"
        ],
        "properties": {
         "cancellation_code": {
          "type": "string",
          "maxLength": 10,
          "example": "503"
         },
         "reason_code": {
          "type": "string",
          "maxLength": 80,
          "default": "marketplace.restaurant_cancelled"
         },
         "approval_challenge": {
          "type": [
           "string",
           "null"
          ],
          "maxLength": 160
         }
        }
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Solicitação registrada; ainda não é cancelamento confirmado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/IfoodCancellationState"
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     },
     "503": {
      "description": "iFood indisponível ou com limite de requisições"
     }
    },
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write",
     "orders:cancel"
    ]
   }
  },
  "/marketplaces/status-pushes": {
   "get": {
    "operationId": "listMarketplaceStatusPushes",
    "description": "Ledger de envios de status ao marketplace (um por pedido e ação).\n\n**Escopo:** `marketplaces:read`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/PerPage"
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "pending",
        "sending",
        "sent",
        "skipped",
        "failed",
        "dead"
       ]
      }
     },
     {
      "name": "connection_id",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Envios de status",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaginatedMarketplaceStatusPushes"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "$ref": "#/components/responses/ValidationFailed"
     }
    },
    "summary": "Listar envios de status aos canais",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:read"
    ]
   }
  },
  "/marketplaces/status-pushes/{push}/retry": {
   "post": {
    "operationId": "retryMarketplaceStatusPush",
    "description": "Devolve à fila um envio que falhou ou esgotou as tentativas (failed ou dead). O envio segue a ordem do pedido.\n\n**Escopo:** `marketplaces:write`.\n\n**Exige** `Idempotency-Key`.",
    "security": [
     {
      "bearerAuth": []
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/LocationId"
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     },
     {
      "name": "push",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "202": {
      "description": "Reenvio enfileirado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data"
         ],
         "properties": {
          "data": {
           "$ref": "#/components/schemas/MarketplaceStatusPush"
          }
         }
        }
       }
      }
     },
     "403": {
      "$ref": "#/components/responses/Forbidden"
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "422": {
      "description": "Envio que não está em failed nem dead"
     }
    },
    "summary": "Reenviar envio de status com falha",
    "tags": [
     "Marketplaces"
    ],
    "x-escopos": [
     "marketplaces:write"
    ]
   }
  }
 },
 "webhooks": {
  "operationalOrderCreated": {
   "post": {
    "summary": "Pedido criado pela API operacional",
    "description": "Configure o evento `operational_order_created` no painel de webhooks. Use `event_id` para deduplicação e `location_id` para selecionar a unidade.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "event_id",
         "order_id",
         "location_id",
         "total_minor",
         "currency",
         "occurred_at"
        ],
        "properties": {
         "event_id": {
          "type": "string",
          "format": "uuid"
         },
         "order_id": {
          "type": "integer"
         },
         "location_id": {
          "type": "integer"
         },
         "total_minor": {
          "type": "integer",
          "minimum": 0
         },
         "currency": {
          "type": "string",
          "const": "BRL"
         },
         "occurred_at": {
          "type": "string",
          "format": "date-time"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Recebido"
     }
    }
   }
  },
  "operationalOrderTransitioned": {
   "post": {
    "summary": "Etapa operacional alterada",
    "description": "Configure o evento `operational_order`. Inclui aceite sem alteração do status visível.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "event_id",
         "order_id",
         "location_id",
         "from_state",
         "to_state",
         "status_id",
         "occurred_at"
        ],
        "properties": {
         "event_id": {
          "type": "string",
          "format": "uuid"
         },
         "order_id": {
          "type": "integer"
         },
         "location_id": {
          "type": "integer"
         },
         "from_state": {
          "type": "string"
         },
         "to_state": {
          "type": "string"
         },
         "status_id": {
          "type": "integer"
         },
         "occurred_at": {
          "type": "string",
          "format": "date-time"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Recebido"
     }
    }
   }
  },
  "operationalPaymentConfirmed": {
   "post": {
    "summary": "Pagamento integral confirmado",
    "description": "Configure o evento `operational_payment_confirmed`; trate o retorno do navegador apenas como navegação, sem confirmar pagamento por ele.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "event_id",
         "order_id",
         "location_id",
         "amount_minor",
         "currency",
         "paid",
         "occurred_at"
        ],
        "properties": {
         "event_id": {
          "type": "string",
          "format": "uuid"
         },
         "order_id": {
          "type": "integer"
         },
         "location_id": {
          "type": "integer"
         },
         "amount_minor": {
          "type": "integer",
          "minimum": 0
         },
         "currency": {
          "type": "string",
          "const": "BRL"
         },
         "paid": {
          "type": "boolean",
          "const": true
         },
         "occurred_at": {
          "type": "string",
          "format": "date-time"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Recebido"
     }
    }
   }
  },
  "operationalOrderCancelled": {
   "post": {
    "summary": "Pedido ou item cancelado",
    "description": "Configure o evento `operational_order_cancelled`. `status=pending_refund` indica estorno ainda em andamento.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "event_id",
         "kind",
         "order_id",
         "location_id",
         "cancellation_id",
         "amount_minor",
         "status",
         "occurred_at"
        ],
        "properties": {
         "event_id": {
          "type": "string",
          "format": "uuid"
         },
         "kind": {
          "type": "string",
          "enum": [
           "order",
           "item"
          ]
         },
         "order_id": {
          "type": "integer"
         },
         "location_id": {
          "type": "integer"
         },
         "cancellation_id": {
          "type": "string"
         },
         "order_menu_id": {
          "type": [
           "integer",
           "null"
          ]
         },
         "quantity": {
          "type": [
           "integer",
           "null"
          ]
         },
         "amount_minor": {
          "type": "integer",
          "minimum": 0
         },
         "status": {
          "type": "string",
          "enum": [
           "completed",
           "pending_refund"
          ]
         },
         "occurred_at": {
          "type": "string",
          "format": "date-time"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Recebido"
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "token",
    "description": "Token gerado no painel em Configurações → APIs → Gerar meu token."
   }
  },
  "headers": {
   "CorrelationId": {
    "description": "UUID que correlaciona request, logs, eventos e jobs.",
    "schema": {
     "type": "string",
     "format": "uuid"
    }
   },
   "ApiVersion": {
    "schema": {
     "type": "string",
     "const": "v1"
    },
    "description": "Versão da API que respondeu (v1)."
   }
  },
  "parameters": {
   "ReportFrom": {
    "name": "from",
    "in": "query",
    "description": "Início da janela (ISO 8601 ou AAAA-MM-DD). Padrão, início do dia atual.",
    "schema": {
     "type": "string"
    }
   },
   "ReportTo": {
    "name": "to",
    "in": "query",
    "description": "Fim da janela (ISO 8601 ou AAAA-MM-DD, que vale o dia inteiro). Padrão, agora.",
    "schema": {
     "type": "string"
    }
   },
   "LocationId": {
    "name": "X-Location-Id",
    "in": "header",
    "required": true,
    "schema": {
     "type": "integer",
     "minimum": 1
    },
    "description": "Id da unidade em que a operação acontece."
   },
   "PerPage": {
    "name": "per_page",
    "in": "query",
    "schema": {
     "type": "integer",
     "minimum": 1,
     "maximum": 100,
     "default": 25
    },
    "description": "Itens por página."
   },
   "CorrelationId": {
    "name": "X-Correlation-Id",
    "in": "header",
    "required": false,
    "schema": {
     "type": "string",
     "format": "uuid"
    }
   },
   "IdempotencyKey": {
    "name": "Idempotency-Key",
    "in": "header",
    "required": true,
    "description": "Chave única por comando (até 160 caracteres), por exemplo um UUID. Repetir a mesma chave devolve a resposta original; a mesma chave com outro conteúdo devolve 409.",
    "schema": {
     "type": "string",
     "minLength": 1,
     "maxLength": 160
    }
   }
  },
  "responses": {
   "Conflict": {
    "description": "Estado ou revisão divergente; atualize o recurso antes de repetir a operação",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/ErrorResponse"
      }
     }
    }
   },
   "NotFound": {
    "description": "Recurso inexistente ou de outra unidade (a resposta é a mesma nos dois casos)",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/ErrorResponse"
      }
     }
    }
   },
   "Forbidden": {
    "description": "O token não possui a ability necessária",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/ErrorResponse"
      }
     }
    }
   },
   "ValidationFailed": {
    "description": "Dados inválidos; as mensagens de regra de negócio vêm em pt-BR em error.details",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/ErrorResponse"
      }
     }
    }
   }
  },
  "schemas": {
   "IfoodOrderFinancial": {
    "type": "object",
    "properties": {
     "operational_finalized": {
      "type": "boolean"
     },
     "external_status": {
      "type": "string"
     },
     "cancellation_financial_status": {
      "type": "string",
      "nullable": true
     },
     "receipt": {
      "type": "object",
      "nullable": true,
      "description": "Estado do PaymentIntent nativo com saldo atualizado e recebimento reconhecido",
      "additionalProperties": true
     },
     "status": {
      "type": "string",
      "enum": [
       "not_migrated",
       "consistent",
       "review_required"
      ]
     },
     "resync_required": {
      "type": "boolean"
     },
     "revision": {
      "type": "integer"
     },
     "document_status": {
      "type": "string",
      "enum": [
       "not_provided",
       "valid",
       "invalid_or_masked",
       "minimized"
      ]
     },
     "settlement_confirmed": {
      "type": "boolean",
      "description": "Todos os títulos com impacto associados ao pedido foram conferidos manualmente no extrato; sem título ou com lançamentos não titulados retorna false"
     },
     "updated_at": {
      "type": "string",
      "format": "date-time"
     },
     "issues": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "benefits": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "value_minor": {
         "type": "integer"
        },
        "target": {
         "type": "string"
        },
        "target_id": {
         "type": "string",
         "nullable": true
        },
        "sponsors": {
         "type": "object",
         "additionalProperties": {
          "type": "integer"
         }
        }
       }
      }
     },
     "summary": {
      "type": "object",
      "description": "Valores inteiros em centavos. Venda comercial antes das comissões efetivas do canal; não é líquido de repasse. methods são os instrumentos informados pelo iFood, não dados de cartão.",
      "properties": {
       "customer_total_minor": {
        "type": "integer"
       },
       "items_minor": {
        "type": "integer"
       },
       "delivery_minor": {
        "type": "integer"
       },
       "merchant_delivery_minor": {
        "type": "integer"
       },
       "platform_delivery_minor": {
        "type": "integer"
       },
       "platform_fees_minor": {
        "type": "integer"
       },
       "benefits_minor": {
        "type": "integer"
       },
       "merchant_discount_minor": {
        "type": "integer"
       },
       "merchant_items_discount_minor": {
        "type": "integer"
       },
       "merchant_delivery_discount_minor": {
        "type": "integer"
       },
       "ifood_subsidy_minor": {
        "type": "integer"
       },
       "other_subsidy_minor": {
        "type": "integer"
       },
       "merchant_subsidy_minor": {
        "type": "integer"
       },
       "unattributed_benefits_minor": {
        "type": "integer"
       },
       "cart_discount_minor": {
        "type": "integer"
       },
       "item_discounts": {
        "type": "object",
        "additionalProperties": {
         "type": "integer"
        }
       },
       "online_minor": {
        "type": "integer"
       },
       "offline_minor": {
        "type": "integer"
       },
       "commercial_total_minor": {
        "type": "integer"
       },
       "methods": {
        "type": "array",
        "items": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     }
    }
   },
   "ReportExport": {
    "type": "object",
    "required": [
     "id",
     "report",
     "format",
     "status"
    ],
    "properties": {
     "id": {
      "type": "string",
      "format": "uuid"
     },
     "report": {
      "type": "string",
      "enum": [
       "dre",
       "vendas-horario",
       "vendas-operador",
       "vendas-regiao",
       "performance-produtos",
       "consumo-insumos",
       "posicao-historica",
       "lista-compras",
       "fluxo-de-caixa",
       "rede-consolidado",
       "sales",
       "cash",
       "production",
       "stock",
       "finance",
       "fiscal-apuracao",
       "fiscal-itens",
       "fiscal-recebimentos"
      ]
     },
     "format": {
      "type": "string",
      "enum": [
       "csv"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "queued",
       "processing",
       "completed",
       "failed"
      ]
     },
     "filters": {
      "type": "object"
     },
     "row_count": {
      "type": "integer"
     },
     "file_size": {
      "type": "integer"
     },
     "downloadable": {
      "type": "boolean"
     },
     "expired": {
      "type": "boolean"
     },
     "error_message": {
      "type": [
       "string",
       "null"
      ]
     },
     "requested_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "started_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "completed_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "expires_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     }
    }
   },
   "PrintJob": {
    "type": "object",
    "required": [
     "id",
     "status",
     "attempts",
     "max_attempts"
    ],
    "properties": {
     "id": {
      "type": "string",
      "format": "uuid"
     },
     "order_id": {
      "type": [
       "integer",
       "null"
      ]
     },
     "printer_id": {
      "type": "integer"
     },
     "trigger": {
      "type": "string",
      "enum": [
       "order_paid",
       "order_status",
       "pos_sale",
       "manual",
       "kitchen_ticket"
      ]
     },
     "document_name": {
      "type": "string"
     },
     "status": {
      "type": "string",
      "enum": [
       "queued",
       "sending",
       "accepted",
       "printed",
       "failed",
       "dead_letter",
       "cancelled"
      ]
     },
     "attempts": {
      "type": "integer",
      "minimum": 0
     },
     "max_attempts": {
      "type": "integer",
      "minimum": 1
     },
     "external_job_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_status": {
      "type": [
       "string",
       "null"
      ],
      "description": "Último status devolvido pelo CloudPrinter"
     },
     "agent_reference": {
      "type": [
       "string",
       "null"
      ],
      "description": "Identificação do agente local ou do spooler que concluiu a entrega"
     },
     "error_message": {
      "type": [
       "string",
       "null"
      ]
     },
     "awaiting_confirmation": {
      "type": "boolean",
      "description": "Aceito pelo transporte e ainda sem conclusão do spooler ou agente"
     },
     "unconfirmed_seconds": {
      "type": [
       "integer",
       "null"
      ]
     },
     "dispatched_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "next_attempt_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "accepted_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "confirmed_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "dead_lettered_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     }
    }
   },
   "PrintMetrics": {
    "type": "object",
    "required": [
     "status",
     "metrics",
     "alerts",
     "captured_at"
    ],
    "properties": {
     "location_id": {
      "type": "integer"
     },
     "window_minutes": {
      "type": "integer"
     },
     "status": {
      "type": "string",
      "enum": [
       "healthy",
       "warning",
       "critical"
      ]
     },
     "metrics": {
      "type": "object",
      "properties": {
       "queued": {
        "type": "integer"
       },
       "sending": {
        "type": "integer"
       },
       "awaiting_confirmation": {
        "type": "integer"
       },
       "unconfirmed_beyond_timeout": {
        "type": "integer"
       },
       "printed": {
        "type": "integer"
       },
       "failed": {
        "type": "integer"
       },
       "dead_letter": {
        "type": "integer"
       },
       "cancelled": {
        "type": "integer"
       },
       "oldest_pending_age_seconds": {
        "type": "integer"
       },
       "oldest_unconfirmed_age_seconds": {
        "type": "integer"
       },
       "confirmation_timeout_seconds": {
        "type": "integer"
       },
       "max_attempts": {
        "type": "integer"
       },
       "agents_online": {
        "type": "integer"
       },
       "agents_offline": {
        "type": "integer"
       },
       "created_in_window": {
        "type": "integer"
       },
       "printed_in_window": {
        "type": "integer"
       },
       "failed_in_window": {
        "type": "integer"
       },
       "failure_rate_percent": {
        "type": "number"
       },
       "avg_accept_latency_seconds": {
        "type": [
         "integer",
         "null"
        ]
       },
       "avg_confirm_latency_seconds": {
        "type": [
         "integer",
         "null"
        ]
       }
      }
     },
     "printers": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "printer_id": {
         "type": "integer"
        },
        "name": {
         "type": "string"
        },
        "is_enabled": {
         "type": "boolean"
        },
        "pending": {
         "type": "integer"
        },
        "awaiting_confirmation": {
         "type": "integer"
        },
        "unconfirmed_beyond_timeout": {
         "type": "integer"
        },
        "failed": {
         "type": "integer"
        },
        "dead_letter": {
         "type": "integer"
        },
        "last_error": {
         "type": [
          "string",
          "null"
         ]
        }
       }
      }
     },
     "alerts": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "level": {
         "type": "string",
         "enum": [
          "warning",
          "critical"
         ]
        },
        "message": {
         "type": "string"
        }
       }
      }
     },
     "captured_at": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "Money": {
    "type": "object",
    "required": [
     "price_minor",
     "currency"
    ],
    "properties": {
     "price_minor": {
      "type": "integer",
      "minimum": 0,
      "description": "Valor inteiro em centavos"
     },
     "currency": {
      "type": "string",
      "const": "BRL"
     }
    }
   },
   "MenuInput": {
    "type": "object",
    "required": [
     "menu_name",
     "menu_price"
    ],
    "properties": {
     "menu_name": {
      "type": "string"
     },
     "menu_description": {
      "type": "string"
     },
     "menu_price": {
      "type": "number",
      "minimum": 0
     },
     "category_ids": {
      "type": "array",
      "items": {
       "type": "integer"
      }
     }
    }
   },
   "CatalogImportInput": {
    "type": "object",
    "required": [
     "items"
    ],
    "properties": {
     "confirm": {
      "type": "boolean",
      "description": "Obrigatório somente na aplicação do preview"
     },
     "items": {
      "type": "array",
      "minItems": 1,
      "maxItems": 1000,
      "items": {
       "type": "object",
       "required": [
        "menu_name",
        "menu_price"
       ],
       "properties": {
        "id": {
         "type": "integer",
         "nullable": true
        },
        "menu_name": {
         "type": "string",
         "maxLength": 255
        },
        "menu_description": {
         "type": "string",
         "nullable": true
        },
        "menu_price": {
         "type": "number",
         "minimum": 0
        },
        "menu_status": {
         "type": "boolean"
        },
        "menu_priority": {
         "type": "integer",
         "minimum": 0
        },
        "category_ids": {
         "type": "array",
         "items": {
          "type": "integer"
         }
        }
       }
      }
     }
    }
   },
   "Menu": {
    "allOf": [
     {
      "$ref": "#/components/schemas/Money"
     }
    ],
    "type": "object",
    "required": [
     "id",
     "name",
     "available"
    ],
    "properties": {
     "id": {
      "type": "integer"
     },
     "name": {
      "type": "string"
     },
     "available": {
      "type": "boolean"
     },
     "image_url": {
      "type": "string",
      "format": "uri",
      "nullable": true,
      "description": "URL pública HTTPS da foto principal; null quando o produto não tem foto"
     },
     "options": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/MenuOptionAssignment"
      }
     }
    }
   },
   "MenuOptionAssignment": {
    "type": "object",
    "required": [
     "id",
     "option_id",
     "name",
     "display_type",
     "is_required",
     "min_selected",
     "max_selected",
     "values"
    ],
    "properties": {
     "id": {
      "type": "integer",
      "description": "ID da opção vinculada ao produto"
     },
     "option_id": {
      "type": "integer",
      "description": "ID do grupo global de opções"
     },
     "name": {
      "type": "string"
     },
     "display_type": {
      "type": "string"
     },
     "is_required": {
      "type": "boolean"
     },
     "min_selected": {
      "type": "integer",
      "minimum": 0
     },
     "max_selected": {
      "type": "integer",
      "minimum": 0,
      "description": "Zero significa sem limite específico"
     },
     "values": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/MenuOptionChoice"
      }
     }
    }
   },
   "MenuOptionChoice": {
    "type": "object",
    "required": [
     "id",
     "option_value_id",
     "name",
     "price_minor",
     "currency",
     "is_default"
    ],
    "properties": {
     "id": {
      "type": "integer",
      "description": "Envie este menu_option_value_id em items[].option_values ao cotar ou criar um pedido"
     },
     "option_value_id": {
      "type": "integer",
      "description": "ID do valor no grupo global"
     },
     "name": {
      "type": "string"
     },
     "price_minor": {
      "type": "integer",
      "minimum": 0,
      "description": "Acréscimo efetivo neste produto, em centavos"
     },
     "currency": {
      "type": "string",
      "const": "BRL"
     },
     "is_default": {
      "type": "boolean"
     }
    }
   },
   "PaginatedMenus": {
    "type": "object",
    "required": [
     "data",
     "meta"
    ],
    "properties": {
     "data": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Menu"
      }
     },
     "meta": {
      "$ref": "#/components/schemas/Meta"
     }
    }
   },
   "OrderInput": {
    "type": "object",
    "required": [
     "items"
    ],
    "properties": {
     "items": {
      "type": "array",
      "minItems": 1,
      "maxItems": 50,
      "items": {
       "type": "object",
       "required": [
        "menu_id",
        "quantity"
       ],
       "properties": {
        "menu_id": {
         "type": "integer",
         "minimum": 1
        },
        "quantity": {
         "type": "integer",
         "minimum": 1,
         "maximum": 999
        },
        "option_values": {
         "type": "array",
         "maxItems": 50,
         "items": {
          "oneOf": [
           {
            "type": "integer",
            "minimum": 1
           },
           {
            "type": "object",
            "properties": {
             "menu_option_value_id": {
              "type": "integer",
              "minimum": 1
             },
             "id": {
              "type": "integer",
              "minimum": 1
             },
             "quantity": {
              "type": "integer",
              "minimum": 1,
              "maximum": 99
             }
            },
            "anyOf": [
             {
              "required": [
               "menu_option_value_id"
              ]
             },
             {
              "required": [
               "id"
              ]
             }
            ]
           }
          ]
         },
         "description": "IDs de adicionais ou objetos; quantidade acumulada por adicional limitada a 99"
        },
        "comment": {
         "type": "string",
         "maxLength": 500
        }
       }
      }
     },
     "order_type": {
      "type": "string",
      "enum": [
       "collection",
       "delivery"
      ]
     },
     "customer_id": {
      "type": "integer"
     },
     "address_id": {
      "type": "integer",
      "description": "Obrigatório para entrega; endereço do cliente na unidade"
     },
     "coupon_code": {
      "type": "string"
     },
     "expected_total_minor": {
      "type": "integer",
      "minimum": 0,
      "description": "Valor cotado em centavos; usado apenas ao criar o pedido"
     },
     "payment": {
      "type": "string",
      "description": "Código de meio ativo, por exemplo asaas_pix ou mercadopago"
     }
    }
   },
   "PaymentAllocationInput": {
    "type": "object",
    "required": [
     "method",
     "amount_minor"
    ],
    "properties": {
     "method": {
      "type": "string",
      "enum": [
       "cash",
       "pix",
       "card",
       "asaas",
       "pagbank",
       "mercadopago",
       "pagarme"
      ]
     },
     "amount_minor": {
      "type": "integer",
      "minimum": 1
     },
     "tendered_minor": {
      "type": "integer",
      "minimum": 1,
      "description": "Obrigatório para dinheiro quando houver troco"
     },
     "cash_session_id": {
      "type": "integer"
     },
     "provider_reference": {
      "type": "string"
     }
    }
   },
   "TableSessionInput": {
    "type": "object",
    "properties": {
     "kind": {
      "type": "string",
      "enum": [
       "table",
       "tab"
      ],
      "default": "table"
     },
     "dining_table_id": {
      "type": "integer",
      "nullable": true,
      "description": "Obrigatório para atendimento de mesa; referência à mesa cadastrada em Áreas do Salão"
     },
     "reference": {
      "type": "string",
      "maxLength": 80,
      "nullable": true,
      "description": "Obrigatório para comanda; não cria mesa física"
     },
     "customer_id": {
      "type": "integer",
      "nullable": true
     },
     "guests": {
      "type": "integer",
      "minimum": 1,
      "maximum": 999
     },
     "comment": {
      "type": "string",
      "maxLength": 1000
     }
    }
   },
   "TableSessionItemInput": {
    "type": "object",
    "required": [
     "menu_id",
     "quantity"
    ],
    "properties": {
     "menu_id": {
      "type": "integer"
     },
     "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 999
     },
     "option_values": {
      "type": "array",
      "items": {}
     },
     "comment": {
      "type": "string",
      "maxLength": 500
     }
    }
   },
   "TableSessionCloseInput": {
    "type": "object",
    "required": [
     "payments"
    ],
    "properties": {
     "payments": {
      "type": "array",
      "minItems": 1,
      "items": {
       "allOf": [
        {
         "$ref": "#/components/schemas/PaymentAllocationInput"
        }
       ]
      }
     }
    }
   },
   "TableSessionItemsTransferInput": {
    "type": "object",
    "required": [
     "target_session_id",
     "item_ids"
    ],
    "properties": {
     "target_session_id": {
      "type": "string",
      "format": "uuid"
     },
     "item_ids": {
      "type": "array",
      "minItems": 1,
      "items": {
       "type": "string",
       "format": "uuid"
      }
     }
    }
   },
   "TableSessionTransferInput": {
    "type": "object",
    "required": [
     "kind",
     "reference"
    ],
    "properties": {
     "kind": {
      "type": "string",
      "enum": [
       "table",
       "tab"
      ]
     },
     "dining_table_id": {
      "type": "integer",
      "nullable": true,
      "description": "Obrigatório quando o destino for mesa"
     },
     "reference": {
      "type": "string",
      "maxLength": 80,
      "nullable": true,
      "description": "Obrigatório quando o destino for comanda"
     }
    }
   },
   "TableSessionMergeInput": {
    "type": "object",
    "required": [
     "target_session_id"
    ],
    "properties": {
     "target_session_id": {
      "type": "string",
      "format": "uuid"
     }
    }
   },
   "TableSessionSplitsInput": {
    "type": "object",
    "required": [
     "splits"
    ],
    "properties": {
     "splits": {
      "type": "array",
      "minItems": 2,
      "maxItems": 20,
      "items": {
       "type": "object",
       "required": [
        "label",
        "amount_minor"
       ],
       "properties": {
        "label": {
         "type": "string",
         "maxLength": 100
        },
        "amount_minor": {
         "type": "integer",
         "minimum": 1
        }
       }
      }
     }
    }
   },
   "LoyaltyEntryInput": {
    "type": "object",
    "required": [
     "kind",
     "reason"
    ],
    "properties": {
     "kind": {
      "type": "string",
      "enum": [
       "credit",
       "debit",
       "earn",
       "redeem",
       "adjustment"
      ]
     },
     "points_delta": {
      "type": "integer",
      "nullable": true
     },
     "credit_delta_minor": {
      "type": "integer",
      "nullable": true
     },
     "reason": {
      "type": "string",
      "maxLength": 255
     },
     "reference_type": {
      "type": "string",
      "maxLength": 160,
      "nullable": true
     },
     "reference_id": {
      "type": "string",
      "maxLength": 160,
      "nullable": true
     },
     "metadata": {
      "type": "object",
      "additionalProperties": true,
      "nullable": true
     }
    }
   },
   "PaginationMeta": {
    "type": "object",
    "required": [
     "correlation_id",
     "current_page",
     "per_page",
     "total",
     "last_page"
    ],
    "properties": {
     "correlation_id": {
      "type": "string",
      "format": "uuid"
     },
     "current_page": {
      "type": "integer"
     },
     "per_page": {
      "type": "integer"
     },
     "total": {
      "type": "integer"
     },
     "last_page": {
      "type": "integer"
     }
    }
   },
   "MarketplaceConnection": {
    "type": "object",
    "required": [
     "id",
     "location_id",
     "provider",
     "name",
     "environment",
     "status"
    ],
    "description": "Nunca inclui credenciais, tokens nem o segredo do webhook.",
    "properties": {
     "id": {
      "type": "integer"
     },
     "location_id": {
      "type": "integer"
     },
     "provider": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "environment": {
      "type": "string",
      "enum": [
       "sandbox",
       "homologation",
       "production"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "active",
       "inactive",
       "error"
      ]
     },
     "last_sync_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "last_error": {
      "type": [
       "string",
       "null"
      ]
     }
    }
   },
   "IfoodSettings": {
    "type": "object",
    "description": "Opções do iFood na conexão (settings.ifood). Chaves ausentes assumem o padrão.",
    "properties": {
     "auto_confirm": {
      "type": "boolean",
      "default": false,
      "description": "Aceita o pedido localmente (e, portanto, no iFood) assim que ele é importado"
     },
     "price_mode": {
      "type": "string",
      "enum": [
       "external",
       "local"
      ],
      "default": "external"
     },
     "default_cancellation_code": {
      "type": [
       "string",
       "null"
      ],
      "pattern": "^[\\w.\\-]{1,10}$",
      "default": "501"
     },
     "cancellation_code_map": {
      "type": "object",
      "additionalProperties": {
       "type": "string",
       "pattern": "^[\\w.\\-]{1,10}$"
      },
      "description": "Código de cancelamento do iFood por reason_code local"
     },
     "confirm_warning_seconds": {
      "type": "integer",
      "minimum": 30,
      "maximum": 1200,
      "default": 180
     },
     "actor_user_id": {
      "type": [
       "integer",
       "null"
      ],
      "description": "Usuário ativo com acesso à unidade ou superusuário em nome de quem a integração age"
     }
    }
   },
   "MarketplaceConnectionInput": {
    "type": "object",
    "required": [
     "provider",
     "name"
    ],
    "properties": {
     "id": {
      "type": [
       "integer",
       "null"
      ]
     },
     "provider": {
      "type": "string",
      "maxLength": 60
     },
     "name": {
      "type": "string",
      "maxLength": 120
     },
     "environment": {
      "type": "string",
      "enum": [
       "sandbox",
       "homologation",
       "production"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "active",
       "inactive",
       "error"
      ],
      "description": "Ativar iFood oficial em homologação ou produção exige autorização concluída para a loja; sandbox local é simulação."
     },
     "credentials": {
      "type": "object",
      "additionalProperties": true,
      "writeOnly": true,
      "description": "Para iFood, aceita merchant_id, application_client_id e application_client_secret. access_token, refresh_token e dados de sessão são gravados exclusivamente pelo fluxo OAuth."
     },
     "webhook_secret": {
      "type": "string",
      "minLength": 32,
      "maxLength": 255,
      "writeOnly": true
     },
     "settings": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
       "ifood": {
        "$ref": "#/components/schemas/IfoodSettings"
       }
      }
     }
    }
   },
   "MarketplaceMapping": {
    "type": "object",
    "properties": {
     "id": {
      "type": "integer"
     },
     "connection_id": {
      "type": "integer"
     },
     "entity_type": {
      "type": "string",
      "enum": [
       "menu",
       "category",
       "payment",
       "status",
       "option"
      ]
     },
     "local_id": {
      "type": "string"
     },
     "external_id": {
      "type": "string"
     },
     "metadata": {
      "type": [
       "object",
       "null"
      ],
      "additionalProperties": true
     },
     "is_active": {
      "type": "boolean"
     }
    }
   },
   "MarketplaceHealth": {
    "type": "object",
    "required": [
     "provider",
     "status"
    ],
    "properties": {
     "provider": {
      "type": "string"
     },
     "status": {
      "type": "string",
      "enum": [
       "ok",
       "degraded",
       "error",
       "not_configured",
       "sandbox_ready",
       "configured_not_verified"
      ]
     },
     "environment": {
      "type": "string"
     },
     "missing": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "message": {
      "type": "string"
     },
     "token": {
      "type": "object",
      "properties": {
       "valid": {
        "type": "boolean"
       },
       "expires_at": {
        "type": [
         "string",
         "null"
        ],
        "format": "date-time"
       }
      }
     },
     "polling": {
      "type": "object",
      "properties": {
       "last_polled_at": {
        "type": [
         "string",
         "null"
        ],
        "format": "date-time"
       },
       "last_poll_ok_at": {
        "type": [
         "string",
         "null"
        ],
        "format": "date-time"
       },
       "failures": {
        "type": "integer"
       },
       "stale": {
        "type": "boolean",
        "description": "Sem polling bem-sucedido além de stale_after_seconds; 90 s em polling/contingência e 390 s com presença central saudável"
       },
       "next_poll_at": {
        "type": [
         "string",
         "null"
        ],
        "format": "date-time"
       },
       "interval_seconds": {
        "type": "integer",
        "enum": [
         30,
         300
        ]
       },
       "stale_after_seconds": {
        "type": "integer",
        "enum": [
         90,
         390
        ]
       }
      }
     },
     "webhook": {
      "type": "object",
      "properties": {
       "enabled": {
        "type": "boolean"
       },
       "last_event_at": {
        "type": [
         "string",
         "null"
        ],
        "format": "date-time"
       },
       "last_presence_at": {
        "type": [
         "string",
         "null"
        ],
        "format": "date-time"
       },
       "stale": {
        "type": "boolean",
        "description": "Presença central ausente ou recebida há pelo menos 90 segundos"
       },
       "polling_fallback": {
        "type": "boolean",
        "description": "Contingência central por polling a cada 30 segundos"
       }
      }
     },
     "pending_catalog": {
      "type": "integer",
      "description": "Itens bloqueantes aguardando vínculo"
     },
     "failed_pushes": {
      "type": "integer",
      "description": "Envios de status em failed ou dead"
     },
     "stuck_events": {
      "type": "integer",
      "description": "Eventos ainda em received há mais de 1 minuto e sem espera agendada; tornam a conexão degraded e pedem verificação da fila events"
     },
     "failed_events": {
      "type": "integer",
      "description": "Eventos em failed; tornam a conexão degraded até serem resolvidos"
     },
     "attention_orders": {
      "type": "integer",
      "description": "Pedidos que exigem atenção do operador; inclui negociações e divergências operacionais"
     }
    }
   },
   "MarketplaceChecklist": {
    "type": "object",
    "required": [
     "provider",
     "environment",
     "ready_for_activation",
     "missing",
     "next_action",
     "polling",
     "status_push",
     "settings"
    ],
    "properties": {
     "provider": {
      "type": "string"
     },
     "environment": {
      "type": "string"
     },
     "ready_for_activation": {
      "type": "boolean"
     },
     "required_credentials": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "connection_flow": {
      "type": "string"
     },
     "application_credentials_configured": {
      "type": "boolean"
     },
     "missing": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "webhook_path": {
      "type": "string"
     },
     "next_action": {
      "type": "string"
     },
     "webhook": {
      "$ref": "#/components/schemas/MarketplaceHealth/properties/webhook"
     },
     "polling": {
      "type": "object",
      "required": [
       "enabled"
      ],
      "properties": {
       "enabled": {
        "type": "boolean"
       },
       "interval_seconds": {
        "type": "integer"
       },
       "last_polled_at": {
        "type": [
         "string",
         "null"
        ],
        "format": "date-time"
       },
       "last_poll_ok_at": {
        "type": [
         "string",
         "null"
        ],
        "format": "date-time"
       },
       "failures": {
        "type": "integer"
       },
       "stale": {
        "type": "boolean"
       },
       "next_poll_at": {
        "type": [
         "string",
         "null"
        ],
        "format": "date-time"
       }
      }
     },
     "status_push": {
      "type": "object",
      "required": [
       "enabled",
       "pending",
       "failed"
      ],
      "properties": {
       "enabled": {
        "type": "boolean"
       },
       "pending": {
        "type": "integer"
       },
       "failed": {
        "type": "integer"
       }
      }
     },
     "settings": {
      "type": "object",
      "properties": {
       "ifood": {
        "$ref": "#/components/schemas/IfoodSettings"
       }
      }
     }
    }
   },
   "MarketplacePollResult": {
    "type": "object",
    "required": [
     "connection_id",
     "outcome",
     "received",
     "new",
     "acknowledged",
     "ack_failed",
     "message"
    ],
    "properties": {
     "connection_id": {
      "type": "integer"
     },
     "outcome": {
      "type": "string",
      "enum": [
       "polled",
       "skipped",
       "locked",
       "backoff",
       "error"
      ]
     },
     "received": {
      "type": "integer"
     },
     "new": {
      "type": "integer"
     },
     "acknowledged": {
      "type": "integer"
     },
     "ack_failed": {
      "type": "integer"
     },
     "message": {
      "type": [
       "string",
       "null"
      ]
     }
    }
   },
   "MarketplaceStatusRequestResult": {
    "type": "object",
    "required": [
     "event_id",
     "status",
     "external_order_id"
    ],
    "properties": {
     "event_id": {
      "type": "string",
      "description": "UUID do envio (pedidos do iFood) ou id do evento de outbox (sandbox)"
     },
     "status": {
      "type": "string",
      "const": "queued"
     },
     "external_order_id": {
      "type": "string"
     },
     "push_id": {
      "type": "integer",
      "description": "Só em pedidos do iFood"
     },
     "action": {
      "type": "string",
      "enum": [
       "confirm",
       "startPreparation",
       "readyToPickup",
       "dispatch",
       "requestCancellation"
      ],
      "description": "Só em pedidos do iFood"
     }
    }
   },
   "MarketplaceEvent": {
    "type": "object",
    "required": [
     "id",
     "connection_id",
     "external_id",
     "event_type",
     "status",
     "source"
    ],
    "description": "Nunca inclui details (pedido completo com dados pessoais).",
    "properties": {
     "id": {
      "type": "integer"
     },
     "connection_id": {
      "type": "integer"
     },
     "external_id": {
      "type": "string"
     },
     "event_type": {
      "type": "string"
     },
     "event_code": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_order_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "payload": {
      "type": "object",
      "description": "Só as chaves seguras do evento, todas escalares e opcionais: id, code, fullCode, orderId, merchantId, createdAt, salesChannel e, do webhook legado do sandbox, type, event_type e external_id. Todo o resto do que o marketplace enviou (pedido embutido, cliente, endereço, metadados, observações) é omitido por privacidade e nunca é devolvido por esta API, nem antes nem depois da minimização por retenção. Objeto vazio quando nenhuma dessas chaves existe.",
      "additionalProperties": false,
      "properties": {
       "id": {
        "type": "string",
        "description": "Identificador do evento no marketplace"
       },
       "code": {
        "type": "string",
        "description": "Código curto do evento (ex. PLC, CAN)"
       },
       "fullCode": {
        "type": "string",
        "description": "Código completo do evento (ex. PLACED, CANCELLED)"
       },
       "orderId": {
        "type": "string",
        "description": "Identificador do pedido no marketplace"
       },
       "merchantId": {
        "type": "string",
        "description": "Identificador da loja no marketplace"
       },
       "createdAt": {
        "type": "string",
        "description": "Data de criação informada pelo marketplace"
       },
       "salesChannel": {
        "type": "string"
       },
       "type": {
        "type": "string",
        "description": "Só no webhook legado do sandbox"
       },
       "event_type": {
        "type": "string",
        "description": "Só no webhook legado do sandbox"
       },
       "external_id": {
        "type": "string",
        "description": "Só no webhook legado do sandbox"
       }
      }
     },
     "status": {
      "type": "string",
      "enum": [
       "received",
       "processed",
       "ignored",
       "needs_mapping",
       "failed",
       "deferred"
      ]
     },
     "source": {
      "type": "string",
      "enum": [
       "webhook",
       "polling",
       "replay"
      ]
     },
     "attempts": {
      "type": "integer",
      "description": "Execuções da série atual; um replay deliberado ou liberação de dependência inicia outra série. A recuperação automática preserva o contador."
     },
     "order_id": {
      "type": [
       "integer",
       "null"
      ]
     },
     "last_error": {
      "type": [
       "string",
       "null"
      ]
     },
     "occurred_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "received_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "processed_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "next_attempt_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time",
      "description": "Não processar antes deste instante; preserva Retry-After e protege uma execução em andamento."
     },
     "last_dispatched_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time",
      "description": "Última tentativa de enfileiramento feita pelo polling, recuperação ou replay."
     },
     "acknowledged_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "ack_attempts": {
      "type": "integer"
     },
     "ack_error": {
      "type": [
       "string",
       "null"
      ]
     },
     "created_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "updated_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     }
    }
   },
   "PaginatedMarketplaceEvents": {
    "type": "object",
    "required": [
     "data",
     "meta"
    ],
    "properties": {
     "data": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/MarketplaceEvent"
      }
     },
     "meta": {
      "$ref": "#/components/schemas/PaginationMeta"
     }
    }
   },
   "MarketplaceCatalogSuggestion": {
    "type": "object",
    "required": [
     "local_id",
     "name",
     "score"
    ],
    "properties": {
     "local_id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "score": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100
     }
    }
   },
   "MarketplaceCatalogPending": {
    "type": "object",
    "required": [
     "id",
     "connection_id",
     "entity_type",
     "external_id",
     "blocking",
     "status",
     "occurrences",
     "blocked_orders",
     "suggestions"
    ],
    "properties": {
     "id": {
      "type": "integer"
     },
     "connection_id": {
      "type": "integer"
     },
     "entity_type": {
      "type": "string",
      "enum": [
       "menu",
       "option"
      ]
     },
     "external_id": {
      "type": "string"
     },
     "alt_ids": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "name": {
      "type": [
       "string",
       "null"
      ]
     },
     "parent_name": {
      "type": [
       "string",
       "null"
      ],
      "description": "Nome do item pai (opções)"
     },
     "unit_price_minor": {
      "type": [
       "integer",
       "null"
      ]
     },
     "blocking": {
      "type": "boolean",
      "description": "Itens do cardápio bloqueiam o pedido; opções nunca"
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "resolved",
       "ignored"
      ]
     },
     "reason": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "unmapped",
       "inactive_local",
       "mapping_removed",
       null
      ]
     },
     "occurrences": {
      "type": "integer"
     },
     "blocked_orders": {
      "type": "integer",
      "description": "Pedidos aguardando este vínculo"
     },
     "first_seen_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "last_seen_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "resolved_local_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "resolved_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "ignore_reason": {
      "type": [
       "string",
       "null"
      ]
     },
     "suggestions": {
      "type": "array",
      "maxItems": 3,
      "items": {
       "$ref": "#/components/schemas/MarketplaceCatalogSuggestion"
      },
      "description": "Só para itens pending"
     }
    }
   },
   "MarketplaceCatalogPendingResolution": {
    "allOf": [
     {
      "$ref": "#/components/schemas/MarketplaceCatalogPending"
     },
     {
      "type": "object",
      "required": [
       "reprocessed_orders"
      ],
      "properties": {
       "reprocessed_orders": {
        "type": "integer",
        "description": "Pedidos que estavam bloqueados e foram devolvidos ao processamento"
       }
      }
     }
    ]
   },
   "PaginatedMarketplaceCatalogPending": {
    "type": "object",
    "required": [
     "data",
     "meta"
    ],
    "properties": {
     "data": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/MarketplaceCatalogPending"
      }
     },
     "meta": {
      "$ref": "#/components/schemas/PaginationMeta"
     }
    }
   },
   "MarketplaceOrder": {
    "type": "object",
    "required": [
     "id",
     "connection_id",
     "order_id",
     "external_order_id",
     "external_status",
     "needs_attention"
    ],
    "description": "Sem snapshot, nome, telefone, endereço ou observações do cliente.",
    "properties": {
     "id": {
      "type": "integer"
     },
     "connection_id": {
      "type": "integer"
     },
     "order_id": {
      "type": "integer"
     },
     "external_order_id": {
      "type": "string"
     },
     "display_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "external_status": {
      "type": "string",
      "enum": [
       "PLACED",
       "CONFIRMED",
       "READY_TO_PICKUP",
       "DISPATCHED",
       "CONCLUDED",
       "CANCELLED"
      ]
     },
     "external_status_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "local_state": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "placed",
       "accepted",
       "preparing",
       "ready",
       "dispatched",
       "completed",
       "cancelled",
       null
      ]
     },
     "awaiting_acceptance": {
      "type": "boolean",
      "description": "Pedido local ainda placed, sem confirm enviado, além do prazo settings.ifood.confirm_warning_seconds"
     },
     "order_type": {
      "type": "string",
      "enum": [
       "delivery",
       "takeout",
       "indoor"
      ]
     },
     "delivered_by": {
      "type": [
       "string",
       "null"
      ]
     },
     "timing": {
      "type": "string"
     },
     "scheduled_start_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "scheduled_end_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "subtotal_minor": {
      "type": "integer"
     },
     "delivery_fee_minor": {
      "type": "integer"
     },
     "benefits_minor": {
      "type": "integer"
     },
     "additional_fees_minor": {
      "type": "integer"
     },
     "total_minor": {
      "type": "integer"
     },
     "local_total_minor": {
      "type": "integer"
     },
     "total_mismatch": {
      "type": "boolean"
     },
     "prepaid": {
      "type": "boolean"
     },
     "needs_attention": {
      "type": "boolean"
     },
     "attention_reason": {
      "type": [
       "string",
       "null"
      ]
     },
     "cancellation_requested_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "cancellation": {
      "$ref": "#/components/schemas/IfoodCancellationState"
     },
     "last_pushed_action": {
      "type": [
       "string",
       "null"
      ]
     },
     "created_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     }
    }
   },
   "IfoodNegotiation": {
    "type": "object",
    "required": [
     "id",
     "marketplace_order_id",
     "dispute_id",
     "status",
     "can_respond",
     "deadline_elapsed"
    ],
    "properties": {
     "id": {
      "type": "integer"
     },
     "marketplace_order_id": {
      "type": "integer"
     },
     "dispute_id": {
      "type": "string"
     },
     "parent_dispute_id": {
      "type": "string",
      "nullable": true
     },
     "action": {
      "type": "string",
      "nullable": true
     },
     "handshake_type": {
      "type": "string",
      "nullable": true
     },
     "status": {
      "type": "string",
      "enum": [
       "open",
       "sending",
       "uncertain",
       "awaiting_settlement",
       "accepted",
       "rejected",
       "expired",
       "alternative_replied"
      ]
     },
     "can_respond": {
      "type": "boolean"
     },
     "deadline_elapsed": {
      "type": "boolean"
     },
     "expires_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "timeout_action": {
      "type": "string",
      "nullable": true
     },
     "accept_reasons": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "alternatives": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "id": {
         "type": "string"
        },
        "type": {
         "type": "string"
        },
        "metadata": {
         "type": "object",
         "properties": {
          "maxAmount": {
           "type": "object",
           "nullable": true,
           "properties": {
            "value": {
             "type": "string"
            },
            "currency": {
             "type": "string"
            }
           }
          },
          "allowedsAdditionalTimeInMinutes": {
           "type": "array",
           "items": {
            "type": "integer"
           }
          },
          "allowedsAdditionalTimeReasons": {
           "type": "array",
           "items": {
            "type": "string"
           }
          }
         }
        }
       }
      }
     },
     "retry_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "responded_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "settled_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "last_error": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "IfoodCancellationState": {
    "type": "object",
    "required": [
     "marketplace_order_id",
     "order_id",
     "status",
     "pending"
    ],
    "properties": {
     "marketplace_order_id": {
      "type": "integer"
     },
     "request_id": {
      "type": [
       "string",
       "null"
      ],
      "format": "uuid"
     },
     "order_id": {
      "type": "integer"
     },
     "status": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       null,
       "requested",
       "awaiting_confirmation",
       "confirmed",
       "rejected",
       "failed"
      ]
     },
     "pending": {
      "type": "boolean"
     },
     "cancellation_code": {
      "type": [
       "string",
       "null"
      ]
     },
     "requested_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "resolved_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "financial_status": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       null,
       "external_review_required",
       "not_required"
      ]
     },
     "stock_status": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       null,
       "review_required",
       "restored",
       "not_changed"
      ]
     },
     "push_id": {
      "type": "integer",
      "description": "Presente na resposta da solicitação"
     }
    }
   },
   "PaginatedMarketplaceOrders": {
    "type": "object",
    "required": [
     "data",
     "meta"
    ],
    "properties": {
     "data": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/MarketplaceOrder"
      }
     },
     "meta": {
      "$ref": "#/components/schemas/PaginationMeta"
     }
    }
   },
   "MarketplaceStatusPush": {
    "type": "object",
    "required": [
     "id",
     "uuid",
     "connection_id",
     "marketplace_order_id",
     "order_id",
     "action",
     "status",
     "attempts"
    ],
    "properties": {
     "id": {
      "type": "integer"
     },
     "uuid": {
      "type": "string",
      "format": "uuid"
     },
     "connection_id": {
      "type": "integer"
     },
     "marketplace_order_id": {
      "type": "integer"
     },
     "order_id": {
      "type": "integer"
     },
     "external_order_id": {
      "type": "string"
     },
     "sequence": {
      "type": "integer",
      "minimum": 1
     },
     "action": {
      "type": "string",
      "enum": [
       "confirm",
       "startPreparation",
       "readyToPickup",
       "dispatch",
       "requestCancellation"
      ]
     },
     "local_state": {
      "type": "string"
     },
     "trigger": {
      "type": "string",
      "enum": [
       "transition",
       "manual",
       "retry"
      ]
     },
     "cancel_code": {
      "type": [
       "string",
       "null"
      ]
     },
     "cancel_reason": {
      "type": [
       "string",
       "null"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "pending",
       "sending",
       "sent",
       "skipped",
       "failed",
       "dead"
      ]
     },
     "attempts": {
      "type": "integer"
     },
     "http_status": {
      "type": [
       "integer",
       "null"
      ]
     },
     "last_error": {
      "type": [
       "string",
       "null"
      ]
     },
     "next_attempt_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "sent_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "created_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     },
     "updated_at": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time"
     }
    }
   },
   "PaginatedMarketplaceStatusPushes": {
    "type": "object",
    "required": [
     "data",
     "meta"
    ],
    "properties": {
     "data": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/MarketplaceStatusPush"
      }
     },
     "meta": {
      "$ref": "#/components/schemas/PaginationMeta"
     }
    }
   },
   "Meta": {
    "type": "object",
    "required": [
     "correlation_id"
    ],
    "properties": {
     "correlation_id": {
      "type": "string",
      "format": "uuid"
     }
    }
   },
   "HealthResponse": {
    "type": "object",
    "required": [
     "data",
     "meta"
    ],
    "properties": {
     "data": {
      "type": "object",
      "required": [
       "status",
       "service",
       "version",
       "time"
      ],
      "properties": {
       "status": {
        "type": "string",
        "const": "ok"
       },
       "service": {
        "type": "string"
       },
       "version": {
        "type": "string",
        "const": "v1"
       },
       "time": {
        "type": "string",
        "format": "date-time"
       }
      }
     },
     "meta": {
      "$ref": "#/components/schemas/Meta"
     }
    }
   },
   "ReadinessResponse": {
    "type": "object",
    "required": [
     "data",
     "meta"
    ],
    "properties": {
     "data": {
      "type": "object",
      "required": [
       "status",
       "checks"
      ],
      "properties": {
       "status": {
        "type": "string",
        "enum": [
         "ready",
         "not_ready"
        ]
       },
       "checks": {
        "type": "object",
        "required": [
         "database",
         "cache",
         "queue"
        ],
        "additionalProperties": {
         "type": "object"
        }
       }
      }
     },
     "meta": {
      "$ref": "#/components/schemas/Meta"
     }
    }
   },
   "ErrorResponse": {
    "type": "object",
    "required": [
     "error",
     "meta"
    ],
    "properties": {
     "error": {
      "type": "object",
      "required": [
       "code",
       "message"
      ],
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       },
       "details": {
        "type": "object",
        "additionalProperties": true
       }
      }
     },
     "meta": {
      "$ref": "#/components/schemas/Meta"
     }
    }
   }
  }
 },
 "tags": [
  {
   "name": "Plataforma",
   "description": "Saúde do serviço e dados da unidade."
  },
  {
   "name": "Cardápio",
   "description": "Produtos"
  },
  {
   "name": "Clientes",
   "description": "Cadastro de clientes e endereços de entrega."
  },
  {
   "name": "Fidelidade e crédito",
   "description": "Saldo de pontos e crédito em reais por cliente."
  },
  {
   "name": "Pedidos",
   "description": "Cotação"
  },
  {
   "name": "Pagamentos",
   "description": "Checkout online"
  },
  {
   "name": "Caixa",
   "description": "Abertura"
  },
  {
   "name": "PDV",
   "description": "Vendas de balcão com sessões de PDV"
  },
  {
   "name": "Mesas e comandas",
   "description": "Atendimento de salão por mesa ou comanda"
  },
  {
   "name": "Cozinha",
   "description": "Estações e tíquetes de produção."
  },
  {
   "name": "Impressão",
   "description": "Fila de impressão"
  },
  {
   "name": "Entregas",
   "description": "Entregadores"
  },
  {
   "name": "Estoque e compras",
   "description": "Insumos"
  },
  {
   "name": "Financeiro",
   "description": "Contas"
  },
  {
   "name": "Relatórios e DRE",
   "description": "Relatórios operacionais"
  },
  {
   "name": "Fiscal",
   "description": "Perfil fiscal"
  },
  {
   "name": "Marketplaces",
   "description": "Conexões com iFood e aiqfome"
  },
  {
   "name": "Governança",
   "description": "Auditoria"
  },
  {
   "name": "Webhooks de entrada",
   "description": "Endereços chamados pelos próprios canais e provedores. Não são para chamar a partir da sua integração."
  }
 ]
}