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

# Crear documento de cobro

> Crea el documento central, su proyección pública y un checkout por el saldo completo. `provider` debe coincidir con el source de la llave. Requiere `public_invoices:write`.



## OpenAPI

````yaml /openapi/invoices-v1.json post /v1/invoices
openapi: 3.1.0
info:
  title: Cobrix API pública de documentos de cobro
  version: 1.0.0
  description: >-
    API de documentos de cobro con montos en unidades mayores de la moneda de
    referencia de la empresa. No admite pagos parciales.
  license:
    name: Propietaria
    url: https://cobrix.co/terms
servers:
  - url: https://api.cobrix.co/api
    description: Producción
  - url: https://sandbox-api.cobrix.co/api
    description: Sandbox
security:
  - bearerAuth: []
tags:
  - name: Documentos públicos
    description: Documentos de cobro públicos y su cobro vigente.
paths:
  /v1/invoices:
    post:
      tags:
        - Documentos públicos
      summary: Crear documento de cobro
      description: >-
        Crea el documento central, su proyección pública y un checkout por el
        saldo completo. `provider` debe coincidir con el source de la llave.
        Requiere `public_invoices:write`.
      operationId: createPublicInvoice
      parameters:
        - $ref: '#/components/parameters/InvoiceIdempotency'
        - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvoiceRequest'
      responses:
        '201':
          description: Documento creado o replay idempotente
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    InvoiceIdempotency:
      name: x-idempotency
      in: header
      required: true
      schema:
        type: string
        minLength: 1
      description: Clave estable por creación.
    RequestId:
      name: X-Request-Id
      in: header
      required: false
      schema:
        type: string
  schemas:
    CreateInvoiceRequest:
      type: object
      additionalProperties: false
      required:
        - reference
        - provider
        - amount
        - name
      properties:
        reference:
          type: string
          minLength: 1
          maxLength: 255
        provider_id:
          type: string
          minLength: 1
          maxLength: 255
        provider:
          type: string
          minLength: 1
          maxLength: 64
          description: Debe coincidir con el source del partner.
        amount:
          type: number
          minimum: 0.01
          maximum: 1000000
          multipleOf: 0.01
          description: Unidades mayores de la moneda de referencia.
        name:
          type: string
          minLength: 5
          maxLength: 100
        description:
          type: string
          minLength: 4
          maxLength: 2000
        phone:
          type: string
          pattern: ^\+[1-9][0-9]{7,14}$
        email:
          type: string
          format: email
          maxLength: 200
        due_date:
          type:
            - string
            - 'null'
          format: date
          description: YYYY-MM-DD.
        document_url:
          type: string
          format: uri
        metadata:
          type: object
          additionalProperties: true
      example:
        reference: INV-EXT-1001
        provider: erp_acme
        provider_id: '1001'
        amount: 20.25
        name: Plan mensual de internet
        description: Servicio correspondiente a julio
        phone: '+584121234567'
        email: cliente@example.com
        due_date: '2026-08-15'
        metadata:
          service_id: svc-1001
    Invoice:
      type: object
      required:
        - id
        - name
        - description
        - amount
        - provider
        - provider_id
        - reference
        - status
        - remarks
        - metadata
        - due_date
        - created_at
        - updated_at
        - payment_id
        - is_test
        - partial_payment_config
        - payment
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        amount:
          type: number
        provider:
          type: string
        provider_id:
          type:
            - string
            - 'null'
        reference:
          type: string
        status:
          $ref: '#/components/schemas/InvoiceStatus'
        remarks:
          type:
            - string
            - 'null'
        metadata:
          type:
            - object
            - 'null'
          additionalProperties: true
        due_date:
          type:
            - string
            - 'null'
          format: date
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        payment_id:
          type:
            - string
            - 'null'
          format: uuid
        is_test:
          type: boolean
        partial_payment_config:
          type: 'null'
          description: Siempre null; esta API exige pago completo.
        payment:
          oneOf:
            - $ref: '#/components/schemas/InvoicePayment'
            - type: 'null'
    InvoiceStatus:
      type: string
      enum:
        - CREATED
        - PAID
        - CONCILIATED
        - PAID_FROM_PROVIDER
        - DELETE_FROM_PROVIDER
        - FAILED
    InvoicePayment:
      type: object
      required:
        - id
        - source
        - currency
        - amount
        - amount_label
        - title
        - description
        - phone
        - expiration_at
        - due_date
        - document_link
        - external_id
        - allows
        - status
        - is_test
        - created_at
        - paid_at
        - payment_link
        - redirect_url
        - provider_id
        - metadata
        - customer
        - method
        - splits
        - company
        - commission
      properties:
        id:
          type: string
          format: uuid
        source:
          type: string
        currency:
          type: string
        amount:
          type: number
        amount_label:
          type: string
        title:
          type: string
        description:
          type: string
        phone:
          type:
            - string
            - 'null'
        expiration_at:
          type:
            - string
            - 'null'
          format: date-time
        due_date:
          type:
            - string
            - 'null'
          format: date
        document_link:
          type:
            - string
            - 'null'
          format: uri
        external_id:
          type:
            - string
            - 'null'
        allows:
          $ref: '#/components/schemas/PaymentAllows'
        status:
          type: string
        is_test:
          type: boolean
        created_at:
          type: string
          format: date-time
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
        payment_link:
          type:
            - string
            - 'null'
          format: uri
        redirect_url:
          type:
            - string
            - 'null'
          format: uri
        provider_id:
          type:
            - string
            - 'null'
        metadata:
          type: 'null'
        customer:
          type: 'null'
        method:
          type: 'null'
        splits:
          type: array
          items:
            type: object
            additionalProperties: true
        company:
          type: 'null'
        commission:
          type: 'null'
    InvoiceError:
      type: object
      required:
        - message
      properties:
        message:
          type: string
        code:
          type: integer
        code_name:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    PaymentAllows:
      type: object
      required:
        - accounts
        - cards
        - card_extra
        - realtime
      properties:
        accounts:
          type: boolean
        cards:
          type: boolean
        card_extra:
          type: boolean
        realtime:
          type: boolean
  headers:
    RateLimitLimit:
      description: Máximo de requests por ventana.
      schema:
        type: integer
        default: 300
    RateLimitRemaining:
      description: Requests disponibles en la ventana.
      schema:
        type: integer
    RateLimitReset:
      description: Timestamp Unix de reinicio.
      schema:
        type: integer
    RetryAfter:
      description: Segundos antes de reintentar.
      schema:
        type: integer
  responses:
    Unauthorized:
      description: Llave ausente o inválida
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvoiceError'
          example:
            message: Unauthenticated.
            code: 10002
            code_name: authentication_error
    Forbidden:
      description: Scope o compañía no habilitada
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvoiceError'
          example:
            message: La llave API no tiene permiso para realizar esta operación.
            code: 10005
            code_name: forbidden
    Conflict:
      description: >-
        Idempotencia, pago aplicado, monto pagado, estado terminal o
        actualización concurrente
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvoiceError'
          examples:
            paymentApplied:
              value:
                message: No se puede actualizar un documento con pagos aplicados.
                code: 10009
                code_name: conflict
                errors:
                  payment:
                    - No se puede actualizar un documento con pagos aplicados.
            paidAmount:
              value:
                message: >-
                  El documento ya fue pagado. Solo pueden actualizarse sus datos
                  informativos.
                code: 10009
                code_name: conflict
                errors:
                  amount:
                    - >-
                      El documento ya fue pagado. Solo pueden actualizarse sus
                      datos informativos.
            idempotency:
              value:
                message: >-
                  La clave de idempotencia ya fue utilizada con un cuerpo
                  diferente.
                code: 10003
                code_name: idempotency_error
    ValidationError:
      description: Campos inválidos o no permitidos
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvoiceError'
          example:
            message: La solicitud contiene errores de validación.
            code: 10001
            code_name: validation_error
            errors:
              amount:
                - El monto debe ser al menos 0.01.
    RateLimited:
      description: Límite distribuido por llave, método y ruta
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvoiceError'
          example:
            message: >-
              Demasiadas solicitudes. Espera el tiempo indicado en Retry-After e
              intenta nuevamente.
            code: 10029
            code_name: rate_limit_error
    InternalError:
      description: Error interno sanitizado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvoiceError'
          example:
            message: Error interno. Comunícate con soporte para resolver el problema.
            code: 10101
            code_name: INTERNAL_ERROR
    ServiceUnavailable:
      description: Configuración financiera temporalmente indisponible
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvoiceError'
          example:
            message: >-
              El servicio financiero no está disponible temporalmente. Intenta
              nuevamente más tarde.
            code: 10103
            code_name: service_unavailable
            errors:
              configuration:
                - La configuración financiera de la compañía no está disponible.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Cobrix API key
      description: Llave cbx_live con scope de documentos públicos.

````