Astranexo Cuenta y uso API

openapi: 3.2.0
info:
  title: Astranexo Com Cuenta y uso API
  version: '1.0'
  contact:
    name: Soporte de Aster
    url: https://astranexo.com/soporte
    email: app@astranexo.com
  description: 'Operations tagged Cuenta y uso across 2 of this provider''s published API definitions: aster-openapi.yaml, fe-api-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://aster.astranexo.com/api/v1
  description: Producción. La misma URL atiende claves de prueba y de producción; la clave decide el ambiente de Hacienda.
security:
- ApiKey: []
tags:
- name: Cuenta y uso
  description: Cuenta, plan, consumo del período y lista pública de precios.
paths:
  /plans:
    get:
      operationId: listPlans
      tags:
      - Cuenta y uso
      summary: Planes y paquetes
      description: Lista pública de planes y paquetes de documentos, con precios en centavos de USD. A cada cargo se le suma el IVA (13 %). Limitado a 120 solicitudes por minuto por IP.
      security: []
      responses:
        '200':
          description: Planes y paquetes.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/PriceList'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    servers:
    - url: https://aster.astranexo.com/api/v1
      description: Producción. La misma URL atiende claves de prueba y de producción; la clave decide el ambiente de Hacienda.
  /account:
    get:
      operationId: getAccount
      tags:
      - Cuenta y uso
      summary: Ver la cuenta
      description: Cuenta, plan y estado de facturación. Requiere una clave de cuenta.
      x-required-ability: account:manage
      responses:
        '200':
          description: La cuenta.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountForbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    servers:
    - url: https://aster.astranexo.com/api/v1
      description: Producción. La misma URL atiende claves de prueba y de producción; la clave decide el ambiente de Hacienda.
  /account/usage:
    get:
      operationId: getAccountUsage
      tags:
      - Cuenta y uso
      summary: Consumo del período
      description: 'Período de facturación actual, documentos incluidos, consumidos (1 por documento de

        producción con veredicto de Hacienda, 0,5 por mensaje receptor), documentos en espera

        de Hacienda, saldo de paquetes, documentos restantes y organizaciones con documentos

        de producción en el período. Los documentos de prueba son gratuitos.'
      x-required-ability: account:manage
      responses:
        '200':
          description: Consumo del período.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/Usage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccountForbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    servers:
    - url: https://aster.astranexo.com/api/v1
      description: Producción. La misma URL atiende claves de prueba y de producción; la clave decide el ambiente de Hacienda.
  /account/archive:
    post:
      operationId: setAccountArchive
      tags:
      - Cuenta y uso
      summary: Activar o desactivar Archeion
      description: 'Agrega o quita el complemento Archeion (US$5 por organización al mes) de la suscripción.

        Requiere una llave de cuenta live y un plan pagado. Escala y Plataforma ya lo incluyen

        (`422 archive_included`). Al desactivarlo, los archivos se conservan 90 días más para

        exportarlos.'
      x-required-ability: account:manage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - enabled
              properties:
                enabled:
                  type: boolean
            example:
              enabled: true
      responses:
        '200':
          description: Cambio solicitado; se refleja cuando se confirma en la suscripción.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
    servers:
    - url: https://aster.astranexo.com/api/v1
      description: Producción. La misma URL atiende claves de prueba y de producción; la clave decide el ambiente de Hacienda.
components:
  responses:
    PaymentRequired:
      description: 'Se requiere un plan pagado: `plan_required` (claves de producción sin plan activo) o `subscription_expired`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    AccountForbidden:
      description: 'Sin permiso: `account_key_required` (se usó una clave de organización), `forbidden`, `live_key_required`, `organization_limit_reached`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            message: 'This endpoint manages an account: use an account API key.'
            error:
              code: account_key_required
              message: 'This endpoint manages an account: use an account API key.'
            timestamp: '2026-10-08T16:00:00Z'
            api_version: '1.0'
    Forbidden:
      description: 'Sin permiso: `forbidden` (falta la habilidad), `organization_key_required`, `live_key_required`, `no_tenant`, `tenant_inactive`, `tenant_deleted`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            message: This action is unauthorized.
            error:
              code: forbidden
              message: This action is unauthorized.
            timestamp: '2026-10-08T16:00:00Z'
            api_version: '1.0'
    TooManyRequests:
      description: Límite de solicitudes alcanzado (`rate_limited`).
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            message: Rate limit exceeded. Try again in 12 seconds.
            error:
              code: rate_limited
              message: Rate limit exceeded. Try again in 12 seconds.
            timestamp: '2026-10-08T16:00:00Z'
            api_version: '1.0'
    Unauthorized:
      description: 'Clave ausente, desconocida, vencida o revocada: `unauthenticated`, `token_expired`, `key_revoked`, `tenant_unresolved`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            message: Unauthenticated.
            error:
              code: unauthenticated
              message: Unauthenticated.
            timestamp: '2026-10-08T16:00:00Z'
            api_version: '1.0'
    ServiceUnavailable:
      description: 'Servicio no disponible temporalmente: `billing_unavailable`, `service_unavailable`, `auth_unavailable`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  headers:
    X-RateLimit-Remaining:
      description: Solicitudes restantes en la ventana actual.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Fin de la ventana actual (segundos Unix).
      schema:
        type: integer
        format: int64
    Retry-After:
      description: Segundos que faltan para poder reintentar.
      schema:
        type: integer
    X-RateLimit-Limit:
      description: Solicitudes permitidas en la ventana actual.
      schema:
        type: integer
  schemas:
    Usage:
      type: object
      properties:
        plan:
          type: string
        status:
          type: string
          enum:
          - sandbox
          - active
          - past_due
          - canceled
        period_start:
          type: string
          format: date-time
        period_end:
          type: string
          format: date-time
        included_docs:
          type: integer
        used:
          type: number
          description: Documentos consumidos (1 por documento, 0,5 por mensaje receptor).
        in_flight:
          type: integer
          description: Documentos de producción esperando el veredicto de Hacienda (cuentan contra la cuota).
        pack_remaining:
          type: number
          description: Documentos restantes de paquetes.
        remaining:
          type: number
          description: Documentos que aún pueden enviarse en el período (plan + paquetes).
        active_organizations:
          type: integer
          description: Organizaciones con al menos un documento de producción en el período.
    PriceList:
      type: object
      properties:
        plans:
          type: array
          items:
            $ref: '#/components/schemas/Plan'
        packs:
          type: array
          items:
            $ref: '#/components/schemas/Pack'
        currency:
          type: string
          const: USD
        iva_rate:
          type: number
          example: 0.13
    Account:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        billing_email:
          type: string
          format: email
        plan:
          type: string
          example: inicial
        status:
          type: string
          enum:
          - sandbox
          - active
          - past_due
          - canceled
          description: '`sandbox`: sin plan pagado (solo claves de prueba).'
        created_at:
          type: string
          format: date-time
    ErrorPayload:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Código estable del error, para usar en el código del cliente.
          example: validation_error
        message:
          type: string
          description: Descripción legible.
        errors:
          type: object
          description: Mensajes por campo (ruta con puntos, por ejemplo `items.0.cabys_code`).
          additionalProperties:
            type: array
            items:
              type: string
    Plan:
      type: object
      properties:
        code:
          type: string
          example: crecimiento
        name:
          type: string
          example: Crecimiento
        monthly_price_cents:
          type: integer
          description: Precio mensual en centavos de USD, sin IVA.
          example: 4900
        yearly_price_cents:
          type: integer
          description: Precio anual en centavos de USD, sin IVA.
          example: 49000
        included_docs:
          type: integer
          description: Documentos incluidos por período.
          example: 3000
        max_organizations:
          type: integer
          description: Organizaciones permitidas (0 = sin límite).
          example: 10
        active_org_cents:
          type: integer
          description: Cargo por organización activa en el período, en centavos de USD.
        archive_included:
          type: boolean
          description: Si el plan incluye Archeion (Escala y Plataforma).
        live_allowed:
          type: boolean
          description: Si el plan permite documentos de producción.
    Envelope:
      type: object
      description: Envoltura de las respuestas exitosas.
      required:
      - success
      - timestamp
      - api_version
      properties:
        success:
          type: boolean
          const: true
        message:
          type: string
          description: Mensaje legible (en inglés) de algunas operaciones.
        data:
          description: Contenido de la respuesta.
        timestamp:
          type: string
          format: date-time
        api_version:
          type: string
          example: '1.0'
    ErrorEnvelope:
      type: object
      description: Envoltura de los errores.
      required:
      - success
      - error
      - timestamp
      - api_version
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
          description: Repite `error.message` en los errores de autenticación, permisos, límites, idempotencia y cuota.
        error:
          $ref: '#/components/schemas/ErrorPayload'
        timestamp:
          type: string
          format: date-time
        api_version:
          type: string
          example: '1.0'
    Pack:
      type: object
      properties:
        code:
          type: string
          example: pack_500
        docs:
          type: integer
          example: 500
        price_cents:
          type: integer
          description: Precio en centavos de USD, sin IVA.
          example: 2000
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: 'Tu llave de API en el encabezado `Authorization: Bearer <llave>`: `aster_test_…` (pruebas) o `aster_live_…` (producción).'
x-refined-from:
- aster-openapi.yaml
- fe-api-openapi.yaml