Central Fox Tecnologia LTDA Billing API

openapi: 3.2.0
info:
  title: FOX NF-e Billing API
  version: '1.20260923'
  description: Contrato derivado das rotas, regras Laravel e respostas estáticas. Condições de validação são descritas nos campos. x-source identifica a evidência. Valores dinâmicos sem tipo comprovado não recebem tipos inventados.
servers:
- url: https://www.foxnfe.com.br
tags:
- name: Billing
paths:
  /api/v1/billing/subscription:
    get:
      operationId: get_api_v1_billing_subscription
      tags:
      - Billing
      summary: Billing subscription
      x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:102
      x-middleware:
      - api
      - auth:sanctum
      - agent.provider
      - tenant.identify
      - tenant.status
      responses:
        '200':
          description: Resposta implementada pelo controlador.
          content:
            application/json:
              schema:
                anyOf:
                - type: object
                  properties:
                    data:
                      type: 'null'
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        id:
                          description: Valor calculado pelo servidor; o tipo não é restringido sem evidência estática.
                          x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:123
                        status:
                          type: string
                          enum:
                          - draft
                          - pending
                          - processing
                          - authorized
                          - rejected
                          - denied
                          - canceled
                          - contingency
                          x-source: app/app/Modules/Fiscal/Nfe/Enums/NfeStatus.php
                        billing_cycle:
                          description: Valor calculado pelo servidor; o tipo não é restringido sem evidência estática.
                          x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:125
                        current_period_start:
                          type:
                          - string
                          - 'null'
                        current_period_end:
                          type:
                          - string
                          - 'null'
                        plan:
                          type: object
                          properties:
                            code:
                              description: Valor calculado pelo servidor; o tipo não é restringido sem evidência estática.
                              x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:129
                            name:
                              description: Valor calculado pelo servidor; o tipo não é restringido sem evidência estática.
                              x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:130
                            price_brl_cents:
                              description: Valor calculado pelo servidor; o tipo não é restringido sem evidência estática.
                              x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:131
              examples:
                estrutura_ficticia:
                  summary: Exemplo estrutural fictício; não é recibo de execução.
                  description: Dados sintéticos para explicar o formato. Identificadores, cadastros fiscais, arquivos e regras de domínio devem ser substituídos por valores válidos do ambiente de homologação. Este exemplo não comprova aceitação fiscal.
                  value:
                    data: null
          x-source:
          - app/app/Modules/Billing/Http/Controllers/BillingController.php:118
          - app/app/Modules/Billing/Http/Controllers/BillingController.php:121
      security:
      - bearerAuth: []
  /api/v1/billing/subscribe:
    post:
      operationId: post_api_v1_billing_subscribe
      tags:
      - Billing
      summary: Billing subscribe
      x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:27
      x-middleware:
      - api
      - auth:sanctum
      - agent.provider
      - tenant.identify
      - tenant.status
      - throttle:5,60
      responses:
        '409':
          description: Resposta implementada pelo controlador.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              examples:
                estrutura_ficticia:
                  summary: Exemplo estrutural fictício; não é recibo de execução.
                  description: Dados sintéticos para explicar o formato. Identificadores, cadastros fiscais, arquivos e regras de domínio devem ser substituídos por valores válidos do ambiente de homologação. Este exemplo não comprova aceitação fiscal.
                  value:
                    error: EXEMPLO_FICTICIO
          x-source:
          - app/app/Modules/Billing/Http/Controllers/BillingController.php:40
        '201':
          description: Resposta implementada pelo controlador.
          content:
            application/json:
              schema:
                type: object
                properties:
                  external_id:
                    description: Valor calculado pelo servidor; o tipo não é restringido sem evidência estática.
                    x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:44
                  pix_code:
                    description: Valor calculado pelo servidor; o tipo não é restringido sem evidência estática.
                    x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:45
                  checkout_url:
                    description: Valor calculado pelo servidor; o tipo não é restringido sem evidência estática.
                    x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:46
              examples:
                estrutura_ficticia:
                  summary: Exemplo estrutural fictício; não é recibo de execução.
                  description: Dados sintéticos para explicar o formato. Identificadores, cadastros fiscais, arquivos e regras de domínio devem ser substituídos por valores válidos do ambiente de homologação. Este exemplo não comprova aceitação fiscal.
                  value:
                    external_id: null
                    pix_code: null
                    checkout_url: null
          x-source:
          - app/app/Modules/Billing/Http/Controllers/BillingController.php:43
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/post_api_v1_billing_subscribeRequest'
            examples:
              estrutura_ficticia:
                summary: Exemplo estrutural fictício; não é recibo de execução.
                description: Dados sintéticos para explicar o formato. Identificadores, cadastros fiscais, arquivos e regras de domínio devem ser substituídos por valores válidos do ambiente de homologação. Este exemplo não comprova aceitação fiscal.
                value:
                  plan_code: starter
                  gateway: stripe
  /api/v1/billing/change-plan:
    post:
      operationId: post_api_v1_billing_change_plan
      tags:
      - Billing
      summary: Billing changePlan
      x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:50
      x-middleware:
      - api
      - auth:sanctum
      - agent.provider
      - tenant.identify
      - tenant.status
      - throttle:5,60
      responses:
        '422':
          description: Resposta implementada pelo controlador.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              examples:
                estrutura_ficticia:
                  summary: Exemplo estrutural fictício; não é recibo de execução.
                  description: Dados sintéticos para explicar o formato. Identificadores, cadastros fiscais, arquivos e regras de domínio devem ser substituídos por valores válidos do ambiente de homologação. Este exemplo não comprova aceitação fiscal.
                  value:
                    error: EXEMPLO_FICTICIO
          x-source:
          - app/app/Modules/Billing/Http/Controllers/BillingController.php:60
        '200':
          description: Resposta implementada pelo controlador.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Plan changed successfully
              examples:
                estrutura_ficticia:
                  summary: Exemplo estrutural fictício; não é recibo de execução.
                  description: Dados sintéticos para explicar o formato. Identificadores, cadastros fiscais, arquivos e regras de domínio devem ser substituídos por valores válidos do ambiente de homologação. Este exemplo não comprova aceitação fiscal.
                  value:
                    message: Plan changed successfully
          x-source:
          - app/app/Modules/Billing/Http/Controllers/BillingController.php:69
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/post_api_v1_billing_change_planRequest'
            examples:
              estrutura_ficticia:
                summary: Exemplo estrutural fictício; não é recibo de execução.
                description: Dados sintéticos para explicar o formato. Identificadores, cadastros fiscais, arquivos e regras de domínio devem ser substituídos por valores válidos do ambiente de homologação. Este exemplo não comprova aceitação fiscal.
                value:
                  plan_code: free
  /api/v1/billing/cancel:
    post:
      operationId: post_api_v1_billing_cancel
      tags:
      - Billing
      summary: Billing cancel
      x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:72
      x-middleware:
      - api
      - auth:sanctum
      - agent.provider
      - tenant.identify
      - tenant.status
      responses:
        '200':
          description: Resposta implementada pelo controlador.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Subscription canceled
              examples:
                estrutura_ficticia:
                  summary: Exemplo estrutural fictício; não é recibo de execução.
                  description: Dados sintéticos para explicar o formato. Identificadores, cadastros fiscais, arquivos e regras de domínio devem ser substituídos por valores válidos do ambiente de homologação. Este exemplo não comprova aceitação fiscal.
                  value:
                    message: Subscription canceled
          x-source:
          - app/app/Modules/Billing/Http/Controllers/BillingController.php:81
      security:
      - bearerAuth: []
  /api/v1/billing/invoices:
    get:
      operationId: get_api_v1_billing_invoices
      tags:
      - Billing
      summary: Billing invoices
      x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:84
      x-middleware:
      - api
      - auth:sanctum
      - agent.provider
      - tenant.identify
      - tenant.status
      responses:
        '200':
          description: Resposta implementada pelo controlador.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Valor calculado pelo servidor; o tipo não é restringido sem evidência estática.
                    x-source: app/app/Modules/Billing/Http/Controllers/BillingController.php:91
              examples:
                estrutura_ficticia:
                  summary: Exemplo estrutural fictício; não é recibo de execução.
                  description: Dados sintéticos para explicar o formato. Identificadores, cadastros fiscais, arquivos e regras de domínio devem ser substituídos por valores válidos do ambiente de homologação. Este exemplo não comprova aceitação fiscal.
                  value:
                    data: null
          x-source:
          - app/app/Modules/Billing/Http/Controllers/BillingController.php:99
      security:
      - bearerAuth: []
  /api/v1/billing/payment-methods:
    get:
      operationId: get_api_v1_billing_payment_methods
      tags:
      - Billing
      summary: PaymentMethod index
      x-source: app/app/Modules/Billing/Http/Controllers/PaymentMethodController.php:20
      x-middleware:
      - api
      - auth:sanctum
      - agent.provider
      - tenant.identify
      - tenant.status
      responses:
        '200':
          description: Resposta implementada pelo controlador.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Valor calculado pelo servidor; o tipo não é restringido sem evidência estática.
                    x-source: app/app/Modules/Billing/Http/Controllers/PaymentMethodController.php:27
              examples:
                estrutura_ficticia:
                  summary: Exemplo estrutural fictício; não é recibo de execução.
                  description: Dados sintéticos para explicar o formato. Identificadores, cadastros fiscais, arquivos e regras de domínio devem ser substituídos por valores válidos do ambiente de homologação. Este exemplo não comprova aceitação fiscal.
                  value:
                    data: null
          x-source:
          - app/app/Modules/Billing/Http/Controllers/PaymentMethodController.php:35
      security:
      - bearerAuth: []
    post:
      operationId: post_api_v1_billing_payment_methods
      tags:
      - Billing
      summary: PaymentMethod store
      x-source: app/app/Modules/Billing/Http/Controllers/PaymentMethodController.php:41
      x-middleware:
      - api
      - auth:sanctum
      - agent.provider
      - tenant.identify
      - tenant.status
      - throttle:10,60
      responses:
        '201':
          description: Resposta implementada pelo controlador.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Valor calculado pelo servidor; o tipo não é restringido sem evidência estática.
                    x-source: app/app/Modules/Billing/Http/Controllers/PaymentMethodController.php:64
              examples:
                estrutura_ficticia:
                  summary: Exemplo estrutural fictício; não é recibo de execução.
                  description: Dados sintéticos para explicar o formato. Identificadores, cadastros fiscais, arquivos e regras de domínio devem ser substituídos por valores válidos do ambiente de homologação. Este exemplo não comprova aceitação fiscal.
                  value:
                    data: null
          x-source:
          - app/app/Modules/Billing/Http/Controllers/PaymentMethodController.php:71
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/post_api_v1_billing_payment_methodsRequest'
            examples:
              estrutura_ficticia:
                summary: Exemplo estrutural fictício; não é recibo de execução.
                description: Dados sintéticos para explicar o formato. Identificadores, cadastros fiscais, arquivos e regras de domínio devem ser substituídos por valores válidos do ambiente de homologação. Este exemplo não comprova aceitação fiscal.
                value:
                  gateway: null
                  type: card
                  external_id: EXEMPLO_FICTICIO
  /api/v1/billing/payment-methods/{id}:
    delete:
      operationId: delete_api_v1_billing_payment_methods__id_
      tags:
      - Billing
      summary: PaymentMethod destroy
      x-source: app/app/Modules/Billing/Http/Controllers/PaymentMethodController.php:77
      x-middleware:
      - api
      - auth:sanctum
      - agent.provider
      - tenant.identify
      - tenant.status
      responses:
        '204':
          description: Resposta implementada pelo controlador.
          content:
            application/json:
              schema:
                type: 'null'
              examples:
                estrutura_ficticia:
                  summary: Exemplo estrutural fictício; não é recibo de execução.
                  description: Dados sintéticos para explicar o formato. Identificadores, cadastros fiscais, arquivos e regras de domínio devem ser substituídos por valores válidos do ambiente de homologação. Este exemplo não comprova aceitação fiscal.
                  value: null
          x-source:
          - app/app/Modules/Billing/Http/Controllers/PaymentMethodController.php:92
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
components:
  schemas:
    post_api_v1_billing_subscribeRequest:
      type: object
      properties:
        plan_code:
          x-laravel-rules:
          - required
          - string
          - in:starter,growth,pro,scale,enterprise
          type: string
          enum:
          - starter
          - growth
          - pro
          - scale
          - enterprise
        gateway:
          x-laravel-rules:
          - required
          - string
          - in:stripe
          type: string
          enum:
          - stripe
        billing_cycle:
          x-laravel-rules:
          - sometimes
          - string
          - in:monthly,annual
          type: string
          enum:
          - monthly
          - annual
      required:
      - plan_code
      - gateway
      x-source:
      - app/app/Modules/Billing/Http/Requests/CreateSubscriptionRequest.php:17
    post_api_v1_billing_change_planRequest:
      type: object
      properties:
        plan_code:
          x-laravel-rules:
          - required
          - string
          - in:free,starter,growth,pro,scale,enterprise
          type: string
          enum:
          - free
          - starter
          - growth
          - pro
          - scale
          - enterprise
      required:
      - plan_code
      x-source:
      - app/app/Modules/Billing/Http/Requests/ChangePlanRequest.php:17
    post_api_v1_billing_payment_methodsRequest:
      type: object
      properties:
        gateway:
          x-laravel-rules:
          - required
          x-laravel-custom-validation: true
          description: Validação adicional de domínio é aplicada pelo servidor (por exemplo dígitos verificadores e autorização).
        type:
          x-laravel-rules:
          - required
          - string
          - in:card,pix,boleto
          type: string
          enum:
          - card
          - pix
          - boleto
        external_id:
          x-laravel-rules:
          - required
          - string
          - max:200
          type: string
          maxLength: 200
        last_four:
          x-laravel-rules:
          - nullable
          - string
          - size:4
          type:
          - string
          - 'null'
          minLength: 4
          maxLength: 4
        brand:
          x-laravel-rules:
          - nullable
          - string
          - max:30
          type:
          - string
          - 'null'
          maxLength: 30
        is_default:
          x-laravel-rules:
          - boolean
          type: boolean
        metadata:
          x-laravel-rules:
          - nullable
          - array
          type:
          - array
          - object
          - 'null'
          items: {}
          additionalProperties: true
      required:
      - gateway
      - type
      - external_id
      x-source:
      - app/app/Modules/Billing/Http/Controllers/PaymentMethodController.php:46
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer