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

# Crear factura

> Crea una nueva factura y su Payment asociado.

### Headers

<ParamField header="x-idempotency" type="string" required placeholder="Token único para garantizar la idempotencia de la petición">
  Token único para garantizar la idempotencia de la petición
</ParamField>

### Body

<ParamField body="reference" type="string" required placeholder="1060500333">
  Valor con el que el usuario podrá consultar su deuda y realizar el pago en el portal de pagos. Se recomienda utilizar el documento de identidad del titular del servicio. El uso del número de contrato es posible, pero no es la opción más recomendada.
</ParamField>

<ParamField body="provider_id" type="string" placeholder="987654">
  Identificador único de cada factura utilizado internamente en su sistema. Usualmente corresponde al número de factura, número de contrato o UUID de identificación único.
</ParamField>

<ParamField body="provider" type="string" placeholder="biller" required>
  Proveedor del sistema que se está integrando. Para solicitar la asignación de un proveedor, contacte al equipo de soporte a través de la burbuja de chat ubicada en la esquina inferior derecha del [panel de administración](https://admin.onepay.la).
</ParamField>

<ParamField body="amount" type="number" placeholder="50000" required>
  Monto de la factura en pesos (COP). Debe estar entre 5.000 y 100.000.000.
</ParamField>

<ParamField body="name" type="string" placeholder="Factura #12345 - Febrero 2024" required>
  Título con el que se le cobrará al usuario. Debe tener entre 5 y 100 caracteres.

  **Ejemplos sugeridos:**

  * `Factura #12314235 de Febrero del 2024`
  * `Factura #2432543 | Mensualidad Internet`
</ParamField>

<ParamField body="description" type="string" placeholder="Factura de internet correspondiente al mes de octubre 2025">
  Descripción detallada de la factura. Se propaga al Payment asociado. Mínimo 4 y máximo 2000 caracteres.
</ParamField>

<ParamField body="phone" type="string" placeholder="+57XXXXXXXXXX">
  Número de WhatsApp del usuario al que desea cobrar, en formato E.164. Si no se incluye este valor, el usuario no será notificado por medio de WhatsApp.
</ParamField>

<ParamField body="email" type="string" placeholder="cliente@ejemplo.com">
  Correo electrónico del usuario al que desea cobrar. Si no se incluye este valor, el usuario no será notificado por medio de correo electrónico.
</ParamField>

<ParamField body="due_date" type="date" placeholder="2025-10-20">
  Fecha de pago oportuno en la que el usuario debe realizar el pago de la factura. Este valor se utilizará para crear reglas de cobranza a partir de esta fecha específica para esta factura en concreto.
</ParamField>

<ParamField body="document_url" type="string" placeholder="https://example.com/document.pdf">
  URL pública del documento PDF de la factura, en caso de tenerla.
</ParamField>

<ParamField body="metadata" type="object" placeholder="{}">
  Datos adicionales que desea persistir o guardar en la factura dentro de OnePay.
</ParamField>

<ParamField body="partial_payment" type="object">
  Configuración para pagos parciales. Permite que la factura sea pagada en múltiples transacciones.

  <Note>
    Requiere que el feature **Pagos Parciales** esté habilitado en tu cuenta. Contacta a soporte para activarlo.
  </Note>

  <Expandable title="Propiedades">
    <ParamField body="min_amount" type="number" required>
      Monto mínimo por pago parcial en la moneda de la factura (ej: pesos). Mínimo: 1.
    </ParamField>

    <ParamField body="max_amount" type="number">
      Monto máximo por pago parcial. Debe ser mayor que `min_amount`. Si no se envía, el máximo es el saldo restante.
    </ParamField>

    <ParamField body="max_payments" type="integer">
      Número máximo de pagos parciales permitidos. Mínimo: 2, Máximo: 10. Por defecto: 3.
    </ParamField>

    <ParamField body="timeout_hours" type="integer">
      Horas antes de que expire la ventana de pago parcial después del primer abono. Mínimo: 1, Máximo: 720. Por defecto: 24.
    </ParamField>
  </Expandable>
</ParamField>

<Info>
  Al crear una factura, la respuesta incluye el campo `id` — este es el **identificador único de la factura en OnePay**.
  Guárdalo en tu sistema ya que lo necesitarás para [actualizar](/client/invoices/update) o [eliminar](/client/invoices/delete) la factura posteriormente.

  **Recomendación:** Almacena este valor como `external_id` (o equivalente) en tu sistema de gestión para asociar fácilmente tus registros con OnePay.
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.onepay.la/v1/invoices \
    -X POST \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -H "x-idempotency: invoice-001" \
    -d '{
      "reference": "1060500333",
      "provider_id": "987654",
      "provider": "biller",
      "amount": 50000,
      "name": "Internet plan - Octubre",
      "description": "Factura de internet correspondiente al mes de octubre 2025",
      "phone": "+573167591030",
      "email": "cliente@ejemplo.com",
      "due_date": "2025-10-20",
      "document_url": "https://example.com/document.pdf",
      "metadata": {
        "key": "value"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.onepay.la/v1/invoices', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_xxx',
      'Content-Type': 'application/json',
      'x-idempotency': 'invoice-001'
    },
    body: JSON.stringify({
      reference: '1060500333',
      provider_id: '987654',
      provider: 'biller',
      amount: 50000,
      name: 'Internet plan - Octubre',
      description: 'Factura de internet correspondiente al mes de octubre 2025',
      phone: '+573167591030',
      email: 'cliente@ejemplo.com',
      due_date: '2025-10-20',
      document_url: 'https://example.com/document.pdf',
      metadata: {
        key: 'value'
      }
    })
  });

  const invoice = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.onepay.la/v1/invoices',
      headers={
          'Authorization': 'Bearer sk_test_xxx',
          'Content-Type': 'application/json',
          'x-idempotency': 'invoice-001'
      },
      json={
          'reference': '1060500333',
          'provider_id': '987654',
          'provider': 'biller',
          'amount': 50000,
          'name': 'Internet plan - Octubre',
          'description': 'Factura de internet correspondiente al mes de octubre 2025',
          'phone': '+573167591030',
          'email': 'cliente@ejemplo.com',
          'due_date': '2025-10-20',
          'document_url': 'https://example.com/document.pdf',
          'metadata': {
              'key': 'value'
          }
      }
  )

  invoice = response.json()
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.onepay.la/v1/invoices",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer sk_test_xxx",
      "Content-Type: application/json",
      "x-idempotency: invoice-001"
    ],
    CURLOPT_POSTFIELDS => json_encode([
      "reference" => "1060500333",
      "provider_id" => "987654",
      "provider" => "biller",
      "amount" => 50000,
      "name" => "Internet plan - Octubre",
      "description" => "Factura de internet correspondiente al mes de octubre 2025",
      "phone" => "+573167591030",
      "email" => "cliente@ejemplo.com",
      "due_date" => "2025-10-20",
      "document_url" => "https://example.com/document.pdf",
      "metadata" => [
        "key" => "value"
      ]
    ])
  ]);

  $response = curl_exec($curl);
  $invoice = json_decode($response, true);
  ?>
  ```
</RequestExample>

### Response

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "9da58912-101d-46f8-86c9-20a52119c0bf",
    "name": "Internet plan - Octubre",
    "description": "Factura de internet correspondiente al mes de octubre 2025",
    "amount": 50000,
    "provider": "biller",
    "provider_id": "987654",
    "reference": "1060500333",
    "status": "CREATED",
    "remarks": null,
    "metadata": { "key": "value" },
    "due_date": null,
    "created_at": "2025-10-20T15:06:00.000000Z",
    "updated_at": "2025-10-20T15:06:00.000000Z",
    "payment_id": "c1f4b0aa-6a12-4471-8a3d-1a2b3c4d5e6f",
    "is_test": false,
    "partial_payment_config": null,
    "payment": {
      "id": "c1f4b0aa-6a12-4471-8a3d-1a2b3c4d5e6f",
      "source": "Internet plan - Octubre",
      "currency": "COP",
      "amount": 50000,
      "amount_label": "$ 50.000",
      "title": "Internet plan - Octubre",
      "description": "Internet plan - Octubre",
      "phone": "+573167591030",
      "expiration_at": null,
      "due_date": null,
      "document_link": "https://example.com/document.pdf",
      "external_id": "987654",
      "allows": { "accounts": true, "cards": true, "card_extra": false, "realtime": false },
      "status": "pending",
      "is_test": false,
      "created_at": "2025-10-20T15:06:00.000000Z",
      "paid_at": null,
      "payment_link": "https://pagos.onepay.la/payment/c1f4b0aa-6a12-4471-8a3d-1a2b3c4d5e6f",
      "redirect_url": null,
      "provider_id": null,
      "metadata": null,
      "customer": null,
      "method": null,
      "splits": [],
      "company": null,
      "commission": null
    }
  }
  ```

  ```json 201 Con pagos parciales theme={null}
  {
    "id": "9da58912-101d-46f8-86c9-20a52119c0bf",
    "name": "Internet plan - Octubre",
    "amount": 50000,
    "provider": "biller",
    "provider_id": "987654",
    "reference": "1060500333",
    "status": "CREATED",
    "remarks": null,
    "metadata": { "key": "value" },
    "due_date": null,
    "created_at": "2025-10-20T15:06:00.000000Z",
    "updated_at": "2025-10-20T15:06:00.000000Z",
    "payment_id": "c1f4b0aa-6a12-4471-8a3d-1a2b3c4d5e6f",
    "is_test": false,
    "partial_payment_config": {
      "min_amount_in_cents": 1000000,
      "max_amount_in_cents": null,
      "max_payment_methods": 3,
      "timeout_hours": 24
    },
    "payment": {
      "id": "c1f4b0aa-6a12-4471-8a3d-1a2b3c4d5e6f",
      "source": "Internet plan - Octubre",
      "currency": "COP",
      "amount": 50000,
      "amount_label": "$ 50.000",
      "title": "Internet plan - Octubre",
      "description": "Internet plan - Octubre",
      "phone": "+573167591030",
      "expiration_at": null,
      "due_date": null,
      "document_link": "https://example.com/document.pdf",
      "external_id": "987654",
      "allows": { "accounts": true, "cards": true, "card_extra": false, "realtime": false },
      "status": "pending",
      "is_test": false,
      "created_at": "2025-10-20T15:06:00.000000Z",
      "paid_at": null,
      "payment_link": "https://pagos.onepay.la/payment/c1f4b0aa-6a12-4471-8a3d-1a2b3c4d5e6f",
      "redirect_url": null,
      "provider_id": null,
      "metadata": null,
      "customer": null,
      "method": null,
      "splits": [],
      "company": null,
      "commission": null,
      "partial_payment": {
        "total_paid_in_cents": 0,
        "total_paid_label": "$ 0",
        "remaining_amount_in_cents": 5000000,
        "remaining_label": "$ 50.000",
        "progress_percentage": 0,
        "is_fully_paid": false,
        "min_amount_in_cents": 1000000,
        "max_amount_in_cents": null,
        "max_payment_methods": 3,
        "timeout_hours": 24,
        "partial_expires_at": null,
        "charges": []
      }
    }
  }
  ```

  ```json 422 theme={null}
  {
    "message":"La solicitud contiene errores de validación.",
    "code":10001,
    "code_name":"validation_error",
    "errors":{
      "reference":["El campo referencia es obligatorio."],
      "amount":["El monto debe ser al menos 5000."],
      "name":["El nombre debe tener al menos 5 caracteres."],
      "phone":["El teléfono debe estar en formato E.164."],
      "email":["El correo electrónico no es válido."]
    }
  }
  ```

  ```json 409 theme={null}
  {
    "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
    "code": 10003,
    "code_name": "idempotency_error"
  }
  ```
</ResponseExample>