openapi: 3.1.0
info:
  title: Pigz Integrator
  version: 1.1.0
  contact:
    email: dev@pigz.com.br
  license:
    name: MIT
    url: https://opensource.org/license/mit/
  description: >
    # What is the Pigz Integrator


    The **Pigz Integrator API** allows third-party systems (such as POS systems
    or order platforms) to receive and manage orders from Pigz.


    It is designed to integrate Pigz orders into **Point of Sale (POS)** systems
    or online ordering platforms.  

    Through this API, you can query new or canceled orders and update each
    order’s status according to the store’s operational flow.


    ### Example Workflow

    1. A customer places an order on Pigz.

    2. The partner POS system periodically fetches orders via the `Pooling`
    endpoint.

    3. Once the order reaches the POS, it should confirm receipt using the
    `Change Stage Order` endpoint (stage = `known` or `integrated`).

    4. The POS then updates the order status through its lifecycle until it is
    delivered, picked up, or canceled.


    This communication ensures synchronization between Pigz and partner systems.
servers:
  - url: https://integrador.pigz.dev
  - url: https://integrador.pigz.com.br
tags:
  - name: Auth
    description: Authentication and token generation
  - name: Orders
    description: Order retrieval and status updates
  - name: Merchant
    description: Store open/close management
paths:
  /authentication:
    post:
      summary: Generate authentication token
      operationId: authenticate
      description: >
        Generates a valid JWT token (expires in 12 hours).  

        Credentials must be sent via **Basic Auth** (`email:password` encoded in
        Base64).
      tags:
        - Auth
      security:
        - basicAuth: []
      responses:
        '200':
          description: Token successfully generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: JWT token
                    example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1...
                  expire:
                    type: number
                    description: Expiration timestamp (in seconds)
                    example: 959804400
        '400':
          description: Failed to generate token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Could not generate a new token
  /pooling:
    get:
      summary: Retrieve orders
      operationId: getOrders
      description: >
        Returns **new and canceled orders** since the last request.  

        A valid **Bearer Token** must be provided.


        ⚠️ **Important:** After receiving an order, use the `Change Stage Order`
        endpoint  

        to mark it as `known` or `integrated`. Orders not marked will be sent
        again in future queries.
      tags:
        - Orders
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '204':
          description: No new or canceled orders available
        '401':
          description: Invalid or expired token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bearer Token invalid or expired
        '403':
          description: Missing or invalid token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bearer Token missing or does not exist
  /order/{id}/{stage}:
    put:
      summary: Update order stage
      operationId: updateOrderStage
      description: >
        Updates the **status of an order**.  

        Requires a valid **Bearer Token**.


        ### Available stages:

        - `integrado` or `conhecido`: order received by the POS

        - `confirmado`: order accepted by the store

        - `despachado`: order sent out for delivery

        - `prontoRetirada`: order ready for in-store pickup

        - `entregue`: order delivered to the customer

        - `cancelado`: order canceled


        ⚠️ **Important:** Do not mark an order as `delivered` and then attempt
        to cancel it afterward.
      tags:
        - Orders
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Order ID
          schema:
            type: integer
          example: 3105
        - name: stage
          in: path
          required: true
          description: New order stage
          schema:
            type: string
          example: conhecido
      responses:
        '200':
          description: Stage successfully updated
          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: Open or close store
      operationId: setMerchantStatus
      description: |
        Sets the store as open or closed.  
        The store will only open if it is within the configured business hours.

        ### Accepted values:
        - `open`
        - `close`
      tags:
        - Merchant
      security:
        - bearerAuth: []
      parameters:
        - name: openOrClose
          in: path
          required: true
          description: Desired store status
          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: Unable to get merchant information
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Order:
      type: object
      properties:
        codigo:
          type: number
          description: Order code
          example: 1234
        dataHora:
          type: string
          description: Order date and time (ISO 8601)
          example: '2025-08-26T12:34:56Z'
        cliente:
          type: object
          properties:
            nome:
              type: string
              description: Customer name
              example: Vitor Rocha
            telefone:
              type: string
              description: Customer phone number
              example: +55 95 91234-5678
        itens:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                description: Item ID
                example: 123
              productId:
                type: integer
                description: Product ID
                example: 123
              tipo:
                type: string
                description: Item type
                example: Pizza
              nome:
                type: string
                description: Item name
                example: Calabresa
              quantidade:
                type: number
                description: Quantity of the item
                example: 2
              preco:
                type: number
                description: Unit price of the item
                example: 39.9
        pagamentos:
          type: array
          items:
            type: object
            properties:
              codigo:
                type: number
                description: Payment method code
                example: 1
              tipo:
                type: string
                description: Payment type
                example: Credit card
              preco:
                description: Payment amount
                oneOf:
                  - type: number
                    example: 79.8
                  - type: string
                    example: '79.80'
              status:
                type: string
                description: Payment status
                example: PAID
        pagamento:
          type: object
          properties:
            codigo:
              type: number
              description: Payment method code
              example: 1
            tipo:
              type: string
              description: Payment type
              example: CASH
            preco:
              description: Payment amount
              oneOf:
                - type: number
                  example: 79.8
                - type: string
                  example: '79.80'
            status:
              type: string
              description: Payment status
              example: PAID
        status:
          type: string
          description: Current order status
          example: confirmed
        tipoEntrega:
          type: string
          description: Shipping type
          example: delivery
