openapi: 3.1.0
info:
  title: Integrador Pigz
  version: 1.1.0
  contact:
    email: dev@pigz.com.br
  license:
    name: MIT
    url: https://opensource.org/license/mit/
  description: >
    # O que é o Integrador Pigz


    A API do **Integrador Pigz** permite que sistemas terceiros (como PDVs ou
    plataformas de pedidos) recebam e manipulem pedidos da Pigz.


    Ela foi projetada para integrar pedidos da Pigz em **sistemas de Ponto de
    Venda (PDV)** ou plataformas de captação de pedidos online. 

    Através dela é possível consultar pedidos novos ou cancelados e atualizar o
    status de cada pedido conforme o fluxo de operação da loja.


    ### Exemplo de fluxo

    1. Um cliente realiza um pedido na Pigz.

    2. O sistema PDV parceiro consulta periodicamente os pedidos via `Pooling`.

    3. Assim que o pedido chega ao PDV, ele deve confirmar o recebimento via
    `Change Stage Order` (stage = `conhecido` ou `integrado`).

    4. O PDV atualiza os status seguintes até o pedido ser entregue, retirado ou
    cancelado.


    Essa comunicação garante sincronização entre a Pigz e os sistemas parceiros.
servers:
  - url: https://integrador.pigz.dev
  - url: https://integrador.pigz.com.br
tags:
  - name: Auth
    description: Autenticação e geração de token
  - name: Orders
    description: Consulta e atualização de pedidos
  - name: Merchant
    description: Gerenciamento de abertura/fechamento de lojas
paths:
  /authentication:
    post:
      summary: Gerar token de autenticação
      operationId: authenticate
      description: >
        Gera um token JWT válido por 12 horas.  

        É necessário enviar credenciais via **Basic Auth** (`email:senha` em
        Base64).
      tags:
        - Auth
      security:
        - basicAuth: []
      responses:
        '200':
          description: Token gerado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: Token JWT
                    example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1...
                  expire:
                    type: number
                    description: Timestamp de expiração em segundos
                    example: 959804400
        '400':
          description: Erro ao gerar token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Could not generate a new token
  /pooling:
    get:
      summary: Consultar pedidos
      operationId: getOrders
      description: >
        Retorna os **pedidos novos e cancelados** desde a última consulta.  

        É necessário enviar um **Bearer Token válido**.


        ⚠️ **Atenção**: após receber um pedido, utilize o endpoint `Change Stage
        Order` 

        para marcar como `conhecido` ou `integrado`. Assim o pedido não será
        enviado novamente.
      tags:
        - Orders
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Lista de pedidos retornados
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '204':
          description: Nenhum pedido novo ou cancelado
        '401':
          description: Token inválido ou expirado
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bearer Token invalid or Expired
        '403':
          description: Token ausente ou inválido
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not contain Bearer Token or does not exist
  /pedido/{id}/{stage}:
    put:
      summary: Alterar estágio do pedido
      operationId: updateOrderStage
      description: >
        Atualiza o **status de um pedido**.  

        É necessário enviar um **Bearer Token válido**.


        ### Estágios possíveis:

        - `integrado` ou `conhecido`: pedido recebido pelo PDV

        - `confirmado`: pedido aceito pela loja

        - `despachado`: pedido enviado para entrega

        - `prontoRetirada`: pedido pronto para retirada na loja

        - `entregue`: pedido entregue ao cliente

        - `cancelado`: pedido cancelado


        ⚠️ **Atenção**: não marque o pedido como `entregue` e depois tente
        cancelar.
      tags:
        - Orders
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID do Pedido
          schema:
            type: integer
          example: 3105
        - name: stage
          in: path
          required: true
          description: Novo estágio do pedido
          schema:
            type: string
          example: conhecido
      responses:
        '200':
          description: Estágio atualizado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Altered Stage
                  time:
                    type: number
                    example: 959804400
        '400':
          description: Erro ao salvar dados
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unable to save data or connect to PIGZ
  /merchant/{openOrClose}:
    post:
      summary: Abrir ou fechar loja
      operationId: setMerchantStatus
      description: |
        Define a loja como aberta ou fechada.  
        Somente abrirá se estiver dentro do horário de funcionamento.

        ### Valores aceitos:
        - `abrir` ou `open`
        - `fechar` ou `close`
      tags:
        - Merchant
      security:
        - bearerAuth: []
      parameters:
        - name: openOrClose
          in: path
          required: true
          description: Situação desejada da loja
          schema:
            type: string
          example: open
      responses:
        '200':
          description: Estado da loja alterado
          content:
            application/json:
              schema:
                type: object
                properties:
                  Message:
                    type: string
                    example: Opening state changed to close
        '400':
          description: Erro ao obter informações da loja
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not possible get info on merchant
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Order:
      type: object
      properties:
        codigo:
          type: number
          description: Código do pedido
          example: 1234
        dataHora:
          type: string
          description: Data e hora do pedido (ISO 8601)
          example: '2025-08-26T12:34:56Z'
        cliente:
          type: object
          properties:
            nome:
              type: string
              description: Nome do cliente
              example: João Silva
            telefone:
              type: string
              description: Telefone do cliente
              example: +55 11 91234-5678
        itens:
          type: array
          items:
            type: object
            properties:
              tipo:
                type: string
                description: Tipo do item
                example: Pizza
              nome:
                type: string
                description: Nome do item
                example: Calabresa
              quantidade:
                type: number
                description: Quantidade do item
                example: 2
              preco:
                type: number
                description: Preço unitário do item
                example: 39.9
        pagamento:
          type: object
          properties:
            codigo:
              type: number
              description: Código da forma de pagamento
              example: 1
            tipo:
              type: string
              description: Tipo de pagamento
              example: Cartão de crédito
            preco:
              description: Valor pago
              oneOf:
                - type: number
                  example: 79.8
                - type: string
                  example: '79.80'
            status:
              type: string
              description: Status do pagamento
              example: pago
        status:
          type: string
          description: Status atual do pedido
          example: confirmado
        tipoEntrega:
          type: string
          description: Tipo de entrega do pedido
          example: delivery
