openapi: 3.0.3
info:
  title: OpenMercantil Public Billing API
  version: 1.4.0
  description: 'Public JSON API for Spanish company information derived from BORME and other

    public sources. OpenMercantil is independent and informational; it is not

    the BOE, BORME or Registro Mercantil and does not replace official

    certificates or registry extracts. The API is free and public, requires no

    API key, and is rate-limited per IP. Versions v1.0 through v1.4 are

    available and documented at https://openmercantil.es/api/documentacion.

    '
  termsOfService: https://openmercantil.es/terminos-de-uso
  contact:
    name: OpenMercantil
    url: https://openmercantil.es/soporte
    email: social@openmercantil.es
  license:
    name: CC BY 4.0 For Derived Public-Data Outputs
    url: https://creativecommons.org/licenses/by/4.0/
servers:
- url: https://openmercantil.es
  description: Production
tags:
- name: Billing
  description: Stripe checkout and donation endpoints
paths:
  /api/v1/checkout:
    post:
      tags:
      - Billing
      summary: Create Stripe Checkout Session
      operationId: createCheckoutSession
      description: Create a Stripe Checkout session for a Pro / Business / Agency subscription. Authentication required.
      security:
      - sessionCookie: []
      responses:
        '200':
          description: Stripe checkout session created
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/donation:
    post:
      tags:
      - Billing
      summary: Create Stripe One-Time Donation Session
      operationId: createDonationSession
      description: Create a Stripe one-time payment session for a donation. Anonymous donations are allowed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount_cents:
                  type: integer
                  minimum: 500
                  maximum: 100000
                  description: Donation amount in EUR cents (500 - 100000).
              required:
              - amount_cents
      responses:
        '200':
          description: Donation session created
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Maximum requests per window (60 per minute by IP on the public anonymous tier).
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Remaining requests in the current window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix timestamp when the rate-limit counter resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      additionalProperties: true
  securitySchemes:
    sessionCookie:
      type: apiKey
      in: cookie
      name: session
      description: Session cookie issued after web sign-in, required only for billing endpoints.