Astranexo Mensajes receptor API

openapi: 3.2.0
info:
  title: Astranexo Com Mensajes receptor API
  version: '1.0'
  contact:
    name: Soporte de Aster
    url: https://astranexo.com/soporte
    email: app@astranexo.com
  description: 'Operations tagged Mensajes receptor 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: Mensajes receptor
  description: Aceptación, aceptación parcial o rechazo de comprobantes recibidos de proveedores.
paths:
  /receptor-messages:
    post:
      operationId: submitReceptorMessage
      tags:
      - Mensajes receptor
      summary: Aceptar, aceptar parcialmente o rechazar un comprobante recibido
      description: 'Emite el mensaje receptor sobre un comprobante de un proveedor: `1` aceptación

        (documento `05`), `2` aceptación parcial (`06`) y `3` rechazo (`07`). Se firma y se

        envía a Hacienda igual que un comprobante; el veredicto llega por webhook con

        `document_type: "RC"`. La organización debe ser el receptor del comprobante

        (`422 organization_mismatch`). En producción consume 0,5 documentos de la cuota.

        Muchos campos aceptan alias en español (por ejemplo `mensaje`, `cedula_emisor`,

        `fecha_emision`).'
      x-required-ability: invoices:sign
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceptorMessageRequest'
            example:
              clave: '50607102600310198765400100001010000000283112345678'
              message: 1
              issuer_id: '3101987654'
              issuer_id_type: '02'
              receiver_id: '3101123456'
              receiver_id_type: '02'
              issue_date: '2026-10-07T14:30:00-06:00'
              total: 113000
              total_tax: 13000
              activity_code: '620100'
              tax_condition: '01'
              total_tax_credit: 13000
              total_applicable_expense: 100000
              original_doc_type: '01'
      responses:
        '201':
          description: Mensaje receptor firmado y en proceso.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/DocumentSubmitted'
              example:
                success: true
                message: Receptor message submitted for processing.
                data:
                  id: 4190
                  document_key: '50607102600310198765400100001010000000283112345678'
                  consecutive_number: '00100001050000000006'
                  document_type: '05'
                  document_type_name: Aceptación Comprobante
                  status: processing
                  environment: staging
                  signed_xml_path: aster/6f1c2a9e-4b7d-4c3e-9a51-2d8f0e7b1c44/staging/2026/10/recibidos/FE/50607102600310198765400100001010000000283112345678/ConfirmacionAceptacionComprobante_00100001050000000006.xml
                  storage_status: cloud
                  tenant_uuid: 6f1c2a9e-4b7d-4c3e-9a51-2d8f0e7b1c44
                  queued_at: '2026-10-08T16:30:00Z'
                timestamp: '2026-10-08T16:30:00Z'
                api_version: '1.0'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/QuotaExceeded'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '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.
components:
  headers:
    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-Remaining:
      description: Solicitudes restantes en la ventana actual.
      schema:
        type: integer
    X-RateLimit-Limit:
      description: Solicitudes permitidas en la ventana actual.
      schema:
        type: integer
  responses:
    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'
    QuotaExceeded:
      description: 'Envío de producción sin cuota disponible: `quota_exceeded` (con `upgrade_url`,

        `pack_url` y `usage`), `plan_required` o `payment_required` (pago fallido hace más

        de 7 días). También `subscription_expired`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QuotaError'
          example:
            success: false
            message: This period's 500 documents are used. Upgrade the plan or add a pack to keep issuing.
            error:
              code: quota_exceeded
              message: This period's 500 documents are used. Upgrade the plan or add a pack to keep issuing.
              upgrade_url: https://aster.astranexo.com/app/billing
              pack_url: https://aster.astranexo.com/app/billing#packs
              usage:
                plan: inicial
                status: active
                period_start: '2026-10-01T00:00:00Z'
                period_end: '2026-11-01T00:00:00Z'
                included_docs: 500
                used: 498.5
                in_flight: 2
                pack_remaining: 0
                remaining: 1.5
                active_organizations: 1
            timestamp: '2026-10-08T16:00:00Z'
            api_version: '1.0'
    Conflict:
      description: 'Conflicto: `idempotency_in_progress`, `duplicate_clave`, `duplicate_consecutive`, `already_voided`, `organization_exists`, `documents_in_progress`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: duplicate_consecutive
              message: El consecutivo 00100001010000000042 ya fue utilizado en el documento 50608102600310112345600100001010000000042112345678 (entorno staging). Hacienda rechazará documentos con consecutivo duplicado.
            timestamp: '2026-10-08T16:00:00Z'
            api_version: '1.0'
    ValidationFailed:
      description: Validación fallida (`validation_error`, con mensajes por campo en `error.errors`) u otra regla de negocio con su propio código.
      content:
        application/json:
          schema:
            anyOf:
            - $ref: '#/components/schemas/ValidationError'
            - $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: validation_error
              message: A valid email is required.
              errors:
                email:
                - A valid email is required.
            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'
    BadRequest:
      description: 'Solicitud mal formada: `invalid_json`, `invalid_request`, `invalid_idempotency_key`, `invalid_body`, `missing_params`, `missing_date`, `invalid_date`, `future_date`, `invalid_currency`, `missing_category`, `missing_param`, `too_many_codes`, etc.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: invalid_json
              message: 'Invalid JSON in request body: unexpected EOF'
            timestamp: '2026-10-08T16:00:00Z'
            api_version: '1.0'
  schemas:
    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
    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'
    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.
    QuotaError:
      type: object
      description: Error 402 de cuota o plan.
      required:
      - success
      - error
      - timestamp
      - api_version
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - quota_exceeded
              - plan_required
              - payment_required
              - subscription_expired
            message:
              type: string
            upgrade_url:
              type: string
              format: uri
              description: Dónde cambiar de plan.
            pack_url:
              type: string
              format: uri
              description: Dónde comprar un paquete de documentos.
            usage:
              $ref: '#/components/schemas/Usage'
        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'
    DocumentSubmitted:
      type: object
      properties:
        id:
          type: integer
          format: int64
        document_key:
          type: string
          description: Clave numérica de 50 caracteres.
        consecutive_number:
          type: string
          description: Consecutivo de 20 dígitos.
        document_type:
          type: string
        document_type_name:
          type: string
        status:
          type: string
          const: processing
        environment:
          $ref: '#/components/schemas/Environment'
        signed_xml_path:
          type: string
          description: Ruta interna del XML firmado (descárguelo con `GET /documents/{key}/xml`).
        storage_status:
          type: string
          enum:
          - cloud
          - local_fallback
        tenant_uuid:
          type: string
          format: uuid
        queued_at:
          type: string
          format: date-time
        simulated:
          type: boolean
          description: Presente y `true` cuando el veredicto será simulado.
    Environment:
      type: string
      enum:
      - staging
      - production
      description: Ambiente de Hacienda. Con claves de Aster lo decide la clave.
    ValidationError:
      description: Error `422 validation_error` con los mensajes por campo.
      allOf:
      - $ref: '#/components/schemas/ErrorEnvelope'
      - type: object
        properties:
          error:
            type: object
            required:
            - code
            - message
            - errors
            properties:
              code:
                type: string
                const: validation_error
              message:
                type: string
                description: Resumen de todos los mensajes, separados por ` | `.
              errors:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
    ReceptorMessageRequest:
      type: object
      required:
      - clave
      - message
      - issuer_id
      - issuer_id_type
      - receiver_id
      - receiver_id_type
      - issue_date
      - total
      properties:
        clave:
          type: string
          pattern: ^[0-9A-Z]{50}$
          description: Clave del comprobante recibido (alias `key`).
        message:
          description: '`1` aceptación, `2` aceptación parcial, `3` rechazo (alias `mensaje`). Acepta número o texto.'
          oneOf:
          - type: integer
            enum:
            - 1
            - 2
            - 3
          - type: string
            enum:
            - '1'
            - '2'
            - '3'
        message_detail:
          type: string
          maxLength: 160
          description: Detalle; obligatorio en la aceptación parcial (alias `detalle_mensaje`, `detail`).
        issuer_id:
          type: string
          pattern: ^[0-9A-Z]+$
          description: Identificación del emisor del comprobante (alias `emisor_id`, `cedula_emisor`).
        issuer_id_type:
          type: string
          description: Tipo de identificación del emisor (alias `emisor_id_type`, `tipo_emisor`).
        receiver_id:
          type: string
          pattern: ^[0-9A-Z]+$
          description: Identificación de la organización receptora (alias `receptor_id`, `cedula_receptor`).
        receiver_id_type:
          type: string
          description: Tipo de identificación del receptor (alias `receptor_id_type`, `tipo_receptor`).
        issue_date:
          type: string
          description: Fecha de emisión del comprobante (alias `fecha_emision`, `date`).
        total:
          type: number
          exclusiveMinimum: 0
          description: Total del comprobante (alias `total_factura`).
        total_tax:
          type: number
          description: Impuesto total del comprobante (alias `total_impuesto`, `monto_total_impuesto`).
        activity_code:
          type: string
          pattern: ^(\d{6}|\d{2,4}\.\d{1,2})$
          description: Actividad económica del receptor (alias `codigo_actividad`).
        tax_condition:
          type: string
          enum:
          - '01'
          - '02'
          - '03'
          - '04'
          - '05'
          description: Condición del impuesto (alias `condicion_impuesto`).
        total_tax_credit:
          type: number
          description: Impuesto a acreditar (alias `monto_total_impuesto_acreditar`).
        total_applicable_expense:
          type: number
          description: Gasto aplicable (alias `monto_total_gasto_aplicable`).
        environment:
          $ref: '#/components/schemas/Environment'
        callback_url:
          type: string
          format: uri
        language:
          type: string
          enum:
          - es
          - en
        original_doc_type:
          type: string
          default: '01'
          description: Tipo del comprobante recibido (alias `tipo_documento_original`).
  parameters:
    IdempotencyKey:
      name: X-Idempotency-Key
      in: header
      required: false
      description: Clave única de la operación (máximo 255 caracteres). Repetirla con el mismo cuerpo devuelve la respuesta guardada durante 24 horas.
      schema:
        type: string
        maxLength: 255
        example: 7f3c1e2a-pedido-1042
  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