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

# Add Document Tags

> Agrega etiquetas a un documento por nombre. Los nombres que no existan en tu compañía se crean automáticamente.

- **Aditivo:** no reemplaza las etiquetas existentes; solo agrega las que el documento aún no tiene.
- **Idempotente por etiqueta:** repetir el mismo nombre no duplica la etiqueta en el documento.
- Las etiquetas también se propagan a los pagos asociados al documento.
- Tras agregar etiquetas, `GET /documents/{reference}` y el listado las reflejan en el campo `tags`.
- Para el tag de sistema `admitido`, preferí `POST /documents/{reference}/acknowledge` si solo necesitás marcar el documento como admitido.



## OpenAPI

````yaml POST /documents/{reference}/tags
openapi: 3.1.0
info:
  title: Payana Accounts Payable API
  description: >-
    API pública para gestionar cuentas por pagar (payments) y beneficiarios
    (beneficiaries) en Payana, incluyendo notificaciones por webhooks cuando se
    procesan pagos.
  version: 1.0.0
servers:
  - url: https://api.prod.payana.cloud/public/api/v1
    description: Production
  - url: https://api.develop.payana.cloud/public/api/v1
    description: Develop
security:
  - apiKeyAuth: []
tags:
  - name: Payments
    description: Crear y listar pagos
  - name: Beneficiaries
    description: Crear, listar y consultar beneficiarios
  - name: Webhooks
    description: Eventos de webhooks enviados por Payana
  - name: Banks
    description: Listar y consultar bancos
  - name: Transactions In
    description: Transacciones entrantes (polling, mismo formato que webhooks)
  - name: Documents
    description: Listar, consultar y operar documentos (cuentas por pagar)
  - name: DIAN Events
    description: >-
      Encolar eventos DIAN (030 Acuse de recibo, 031 Reclamo, 032 Recibo del
      bien, 033 Aceptación expresa, 034 Aceptación tácita) para documentos
      identificados por CUFE. El procesamiento es asíncrono.
  - name: Fiscal Sync
    description: >-
      Disparar y consultar sincronización de documentos fiscales desde el SAT
      (México) o la DIAN (Colombia).
  - name: Workflow Steps
    description: >-
      Resolver el paso en que está parado un documento dentro de su flujo:
      aprobación, clasificación o etiquetado.
paths:
  /documents/{reference}/tags:
    post:
      tags:
        - Documents
      summary: Add tags to a document
      description: >-
        Agrega etiquetas a un documento por nombre. Los nombres que no existan
        en tu compañía se crean automáticamente.


        - **Aditivo:** no reemplaza las etiquetas existentes; solo agrega las
        que el documento aún no tiene.

        - **Idempotente por etiqueta:** repetir el mismo nombre no duplica la
        etiqueta en el documento.

        - Las etiquetas también se propagan a los pagos asociados al documento.

        - Tras agregar etiquetas, `GET /documents/{reference}` y el listado las
        reflejan en el campo `tags`.

        - Para el tag de sistema `admitido`, preferí `POST
        /documents/{reference}/acknowledge` si solo necesitás marcar el
        documento como admitido.
      parameters:
        - name: reference
          in: path
          required: true
          description: >-
            Referencia interna del documento en Payana (UUID, ej.
            `aaea7db4-647c-4d92-9f86-89e34a68e1aa`).
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreDocumentTagsRequest'
            example:
              tags_text:
                - centro-costo-42
                - urgente
      responses:
        '200':
          description: Tags stored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreDocumentTagsResponse'
              example:
                message: Tags stored successfully
        '400':
          description: Bad request / validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Document not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity (ej. `tags_text` vacío)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    StoreDocumentTagsRequest:
      type: object
      required:
        - tags_text
      properties:
        tags_text:
          type: array
          minItems: 1
          description: >-
            Nombres de etiquetas a agregar al documento. Se crean en Payana si
            aún no existen para tu compañía.
          items:
            type: string
    StoreDocumentTagsResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          example: Tags stored successfully
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          $ref: '#/components/schemas/ErrorObject'
      example:
        success: false
        error:
          code: VALIDATION_ERROR
          message: The request contains invalid data
          details:
            amount:
              - Amount must be greater than 0
            beneficiary_id:
              - Beneficiary does not exist
    ErrorObject:
      type: object
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
        details:
          anyOf:
            - $ref: '#/components/schemas/ErrorDetails'
            - type: 'null'
    ErrorCode:
      type: string
      enum:
        - VALIDATION_ERROR
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - CONFLICT
        - RATE_LIMITED
        - INTERNAL_ERROR
    ErrorDetails:
      type: object
      additionalProperties:
        type: array
        items:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: API key provista por Payana.

````