# Chamejar — API de integração v1 (OpenAPI 3.1). Gerado por site/ferramentas/api/gerar-docs-api.py. 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. - **Autenticação:** `Authorization: Bearer `. Gere o token no painel em Configurações → APIs → Gerar meu token. - **Unidade:** quase todas as rotas exigem o cabeçalho `X-Location-Id` com o id da unidade. - **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. - **Valores:** campos terminados em `_minor` estão em centavos (BRL). - **Erros:** `{"error": {"code", "message", "details"}, "meta": {"correlation_id"}}`. - **Limite:** 60 requisições por minuto por usuário do painel (os tokens do mesmo usuário somam). Documentaçã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 Exige `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. **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`. **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`. **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`. **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`. **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`. **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 Aceita 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. **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`. **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 Requer `payments:read`. Os códigos retornados podem ser usados em `payment` ao criar o pedido. **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 Requer `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. **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 Requer `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. **Escopo:** `payments:initiate`. **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 Requer `payments:read`. `paid` só passa a verdadeiro após confirmação do provedor. **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. **Escopo:** `orders:transition`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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 **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 **Escopo:** `stock:write`. **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 **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`. **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`. **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 **Escopo:** `stock:write`. **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`. **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`. **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`. **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`. **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`. **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 **Escopo:** `stock:write`. **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 **Escopo:** `stock:write`. **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`. **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`. **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`. **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`. **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`. **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 **Escopo:** `reports:read`.' x-escopos: - reports:read /reports/dre/rebuild: post: operationId: dreRebuild summary: Recalcular a DRE description: 'Recalcular DRE em fila Exige habilidade reports:manage, permissão administrativa e acesso à unidade. Veja docs/RELATORIOS-DRE.md. **Escopo:** `reports:manage`. **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) Exige habilidade reports:manage, permissão administrativa e acesso à unidade. Veja docs/RELATORIOS-DRE.md. **Escopo:** `reports:manage`. **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 Exige habilidade reports:manage, permissão administrativa e acesso à unidade. Veja docs/RELATORIOS-DRE.md. **Escopo:** `reports:manage`. **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. **Escopo:** `reports:manage`. **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. **Escopo:** `reports:manage`. **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. **Escopo:** `reports:manage`. **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 Exige habilidade reports:close, permissão administrativa e acesso à unidade. Veja docs/RELATORIOS-DRE.md. **Escopo:** `reports:close`. **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 Exige habilidade reports:close, permissão administrativa e acesso à unidade. Veja docs/RELATORIOS-DRE.md. **Escopo:** `reports:close`. **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 Consulte 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`. **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 Responde 202 imediatamente; o arquivo é gerado por worker e baixado depois. **Escopo:** `reports:export`. **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 **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 Retorna 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. **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 **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 Caminho 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`. **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 O 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. **Escopo:** `print:confirm`. **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 **Escopo:** `print:write`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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 **Escopo:** `orders:write`. **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. **Escopo:** `orders:cancel`. **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 **Escopo:** `orders:cancel`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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. **Escopo:** `fiscal:write`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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`. **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. Endereç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. Endereç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. Endereç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. Endereç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. Endereç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. Endereç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. Endereç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. Endereç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. Endereç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`. **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. **Escopo:** `marketplaces:write`. **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. **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. **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. **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. **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. **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. **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`. **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. **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`. **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. **Escopo:** `marketplaces:write`. **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. **Escopo:** `marketplaces:write`. **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. **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. **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. **Escopo:** `marketplaces:write`. **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. **Escopo:** `marketplaces:write`. **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. **Escopo:** `marketplaces:write`. **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. **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. **Escopo:** `marketplaces:write`. **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. **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. **Escopo:** `marketplaces:write`. **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. **Escopo:** `marketplaces:write`. **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. **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 Exige 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. **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 Exige 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. **Escopo:** `marketplaces:write`, `payments:write`. **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 Exige 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. **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 Exige 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. **Escopo:** `marketplaces:write`, `payments:write`. **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 Exige 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. **Escopo:** `marketplaces:write`, `payments:write`. **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 Exige 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. **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 Exige 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. **Escopo:** `marketplaces:write`, `orders:cancel`. **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 Exige 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. **Escopo:** `marketplaces:write`, `orders:write`, `payments:write`. **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 Exige 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. **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 **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 Exige 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. **Escopo:** `marketplaces:write`, `orders:cancel`. **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). **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. **Escopo:** `marketplaces:write`. **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.