> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Recibir mensajes con concesión

> Usa POST porque recibir cambia el estado: concede mensajes, incrementa el recuento y los oculta a otros consumidores. Un GET podría repetirse mediante proxies como una lectura segura. Devuelve una lista vacía, sin error, cuando no hay mensajes.

<Info>
  Requiere la acción IAM **`queue:ReceiveMessage`**. Consulte [QUEUE permisos](/es/queue/permissions) para la lista completa, el alcance de cada acción y un ejemplo de política.
</Info>


## OpenAPI

````yaml /es/api-reference/specs/queue.yaml post /v1/queues/{queue_id}/messages/receive
openapi: 3.0.3
info:
  title: API Basaltic Queue
  version: 1.0.0
  description: >-
    Colas duraderas con entrega al menos una vez. Recibir un mensaje concede una
    reserva temporal: `ReceiveMessage` lo oculta durante el timeout de
    visibilidad y devuelve un recibo. Elimine el mensaje con ese recibo antes de
    que venza para evitar la reentrega. Cada recepción genera un recibo nuevo;
    los recibos vencidos devuelven `QUEUE_RECEIPT_HANDLE_EXPIRED`.


    Las colas estándar tienen orden de mejor esfuerzo. Las colas FIFO terminan
    en `.fifo`, mantienen el orden por `message_group_id` y deduplican
    `message_deduplication_id` durante cinco minutos. Los grupos distintos
    pueden procesarse en paralelo. El tipo es inmutable. `wait_time_seconds`
    permite esperar hasta 20 segundos por mensajes.


    Los cuerpos se cifran en reposo. `kms_key` acepta UUID, nombre en la cuenta
    o CRN completo de una clave simétrica habilitada en la misma cuenta y
    región. Las referencias inválidas devuelven 400; las claves inexistentes
    devuelven 404. Las lecturas de metadatos conservan ID y CRN de una
    vinculación eliminada. La clave de datos permanece en caché durante
    `kms_data_key_reuse_period_seconds`; los envíos y recepciones pueden
    continuar durante esa ventana tras desactivar la clave. Reducirla aumenta
    las llamadas a KMS.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://queue.{region}.basaltic.sh
    description: Punto final de API regional
    variables:
      region:
        default: sa-saopaulo-1
        description: Código de región
security:
  - BearerAuth: []
tags:
  - name: Queues
    description: Ciclo de vida y atributos de las colas
  - name: Messages
    description: Envío, recepción y confirmación de mensajes
paths:
  /v1/queues/{queue_id}/messages/receive:
    parameters:
      - $ref: '#/components/parameters/QueueId'
    post:
      tags:
        - Messages
      summary: Recibir mensajes con concesión
      description: >-
        Usa POST porque recibir cambia el estado: concede mensajes, incrementa
        el recuento y los oculta a otros consumidores. Un GET podría repetirse
        mediante proxies como una lectura segura. Devuelve una lista vacía, sin
        error, cuando no hay mensajes.
      operationId: receiveMessages
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceiveRequest'
      responses:
        '200':
          description: Mensajes concedidos; puede estar vacío.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiveResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: La clave de cifrado de la cola no está disponible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    QueueId:
      name: queue_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
  schemas:
    ReceiveRequest:
      type: object
      properties:
        max_messages:
          type: integer
          minimum: 1
          maximum: 10
          description: >-
            Cantidad de mensajes que se concederán. El resultado puede contener
            menos mensajes aunque haya más disponibles.
          example: 10
        visibility_timeout_seconds:
          type: integer
          minimum: 0
          maximum: 43200
          description: Sustituye el valor predeterminado de la cola solo en esta concesión.
          example: 60
        wait_time_seconds:
          type: integer
          minimum: 0
          maximum: 20
          description: >-
            Tiempo máximo de espera por un mensaje. El valor predeterminado es
            receive_wait_time_seconds de la cola.
          example: 20
    ReceiveResponse:
      type: object
      required:
        - messages
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ReceivedMessage'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Código de error que identifica el tipo de error
              example: INVALID_INPUT
            message:
              type: string
              description: Mensaje de error legible por el ser humano
              example: Invalid request parameters
            params:
              type: object
              additionalProperties: true
              description: >-
                Valores no sensibles opcionales para la interpolación de errores
                localizados, codificados por código de error. Nunca presente por
                errores del servidor.
              example:
                instances: 2
                pools: 0
            request_id:
              type: string
              format: uuid
              description: Solicitar ID para depuración
              example: 550e8400-e29b-41d4-a716-446655440000
    ReceivedMessage:
      type: object
      required:
        - id
        - receipt_handle
        - body
        - receive_count
        - enqueued_at
        - visible_at
      properties:
        id:
          type: string
          format: uuid
          example: 019400aa-bbbb-7ccc-8ddd-eeeeffff0000
        receipt_handle:
          type: string
          description: >-
            Credencial de esta concesión. Necesaria para eliminar el mensaje o
            ampliar la concesión; válida solo hasta su vencimiento.
          example: >-
            019400aabbbb7ccc8dddeeeeffff00003f2a91c4d5e60718293a4b5c6d7e8f9015a6b7c8d9e0f1a2b3c4d5e6f708192a3
        body:
          type: string
          example: '{"order_id":"A-1001"}'
        attributes:
          $ref: '#/components/schemas/MessageAttributes'
        receive_count:
          type: integer
          description: >-
            Número de concesiones de este mensaje, incluida la actual. Compárelo
            con la política de redirección para identificar mensajes
            problemáticos.
          example: 1
        message_group_id:
          type: string
          example: customer-42
        enqueued_at:
          type: string
          format: date-time
          example: '2026-01-18T11:45:00Z'
        visible_at:
          type: string
          format: date-time
          description: Cuándo vence la concesión y el mensaje vuelve a entregarse.
          example: '2026-01-18T11:45:30Z'
    MessageAttributes:
      type: object
      description: >-
        Atributos tipados enviados con el cuerpo. Hasta 20, con valores de hasta
        1024 caracteres. Los valores `Binary` usan base64 estándar. La cola
        valida el tipo declarado sin convertir valores.
      additionalProperties:
        type: object
        required:
          - type
          - value
        properties:
          type:
            type: string
            enum:
              - String
              - Number
              - Binary
            example: String
          value:
            type: string
            example: critical
      example:
        severity:
          type: String
          value: critical
        attempt:
          type: Number
          value: '2'
  responses:
    BadRequest:
      description: Parámetros de solicitud no válidos
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_INPUT
              message: Invalid request parameters
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Unauthorized:
      description: Se requiere autenticación o el token no es válido
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Forbidden:
      description: Permisos insuficientes
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ACCESS_DENIED
              message: You don't have permission to perform this action
              request_id: 550e8400-e29b-41d4-a716-446655440000
    NotFound:
      description: No se encontró el recurso
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Resource not found
              request_id: 550e8400-e29b-41d4-a716-446655440000
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >+
        Un token bearer de OAuth 2.0, enviado como `Authorization: Bearer
        <token>`. Esta es la forma recomendada de autenticación.


        Obtén el token intercambiando el par de claves de acceso de una cuenta
        de servicio en `POST /v1/oauth/token` con
        `grant_type=client_credentials`. Es el flujo estándar de credenciales de
        cliente; las bibliotecas compatibles con OAuth pueden obtener y renovar
        el token por ti.


        ```

        curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
          https://iam.basaltic.sh/v1/oauth/token
        ```


        Los tokens duran una hora por defecto. El mismo par de claves de acceso
        también sirve como credencial AWS SigV4 para el endpoint de objetos
        compatible con S3, que solo acepta ese método de autenticación.


````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.