> ## 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.

# Actualizar factura

> Actualiza una factura existente. Cancela el Payment anterior, crea uno nuevo y lo asocia a la factura.

<Warning>
  **Facturas con pagos parciales:** Si la factura tiene un Payment en estado `partially_paid`, actualizarla cancelará ese Payment (y perderá todos los abonos registrados) y creará uno nuevo sin configuración de pagos parciales. Solo actualiza facturas parcialmente pagadas si estás seguro de que quieres reiniciar el proceso de cobro.

  Si el Payment ya está `approved`, la actualización solo modifica los metadatos de la factura sin cancelar ni reemplazar el Payment.
</Warning>

### Path params

<ParamField path="invoice_id" type="string" required placeholder="2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a">
  ID de la factura a actualizar. [Crear factura](/client/invoices/create).
</ParamField>

### Body

<ParamField body="reference" type="string" required placeholder="INV-12345678">
  Referencia única de la factura dentro de tu compañía. Mínimo 5 y máximo 100 caracteres.
</ParamField>

<ParamField body="provider_id" type="string" placeholder="987654">
  Identificador opcional que asocias a tu proveedor externo.
</ParamField>

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

<ParamField body="name" type="string" required placeholder="Internet plan - Actualizado">
  Nombre o concepto de la factura. Mínimo 5 y máximo 100 caracteres.
</ParamField>

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

<ParamField body="phone" type="string" placeholder="+57XXXXXXXXXX">
  Número de teléfono del cliente en formato E.164. Opcional.
</ParamField>

<ParamField body="email" type="string" placeholder="cliente@ejemplo.com">
  Correo electrónico del cliente. Opcional. Máximo 200 caracteres.
</ParamField>

<ParamField body="due_date" type="string" format="date" placeholder="2026-10-31">
  Fecha de vencimiento de la factura en formato `YYYY-MM-DD` (ej. `2026-10-31`). Opcional.
  Si se omite o se envía `null`, se conserva el `due_date` actual de la factura. El valor se propaga al nuevo Payment generado durante la actualización.
</ParamField>

<Note>
  Si no envías `due_date` en la actualización, la factura conserva su fecha de
  vencimiento actual. Solo se modifica cuando envías un valor explícito.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a \
    -X PUT \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "reference": "INV-12345678",
      "amount": 75000,
      "name": "Internet plan - Actualizado",
      "description": "Plan 100MB - facturación octubre",
      "email": "juan@example.com",
      "phone": "+573001234567",
      "provider_id": "987654",
      "due_date": "2026-10-31"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer sk_test_xxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      reference: 'INV-12345678',
      amount: 75000,
      name: 'Internet plan - Actualizado',
      description: 'Plan 100MB - facturación octubre',
      email: 'juan@example.com',
      phone: '+573001234567',
      provider_id: '987654',
      due_date: '2026-10-31'
    })
  });
  const invoice = await response.json();
  console.log(invoice.id); // ID de la factura actualizada
  ```

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

  url = "https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a"
  headers = {
      "Authorization": "Bearer sk_test_xxx",
      "Content-Type": "application/json"
  }
  data = {
      "reference": "INV-12345678",
      "amount": 75000,
      "name": "Internet plan - Actualizado",
      "description": "Plan 100MB - facturación octubre",
      "email": "juan@example.com",
      "phone": "+573001234567",
      "provider_id": "987654",
      "due_date": "2026-10-31"
  }

  response = requests.put(url, headers=headers, json=data)
  invoice = response.json()
  print(invoice["id"])  # ID de la factura actualizada
  ```

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

  curl_setopt_array($ch, [
      CURLOPT_URL => "https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => "PUT",
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer sk_test_xxx",
          "Content-Type: application/json"
      ],
      CURLOPT_POSTFIELDS => json_encode([
          "reference" => "INV-12345678",
          "amount" => 75000,
          "name" => "Internet plan - Actualizado",
          "description" => "Plan 100MB - facturación octubre",
          "email" => "juan@example.com",
          "phone" => "+573001234567",
          "provider_id" => "987654",
          "due_date" => "2026-10-31"
      ])
  ]);

  $response = curl_exec($ch);
  $invoice = json_decode($response, true);

  echo $invoice["id"]; // ID de la factura actualizada

  curl_close($ch);
  ?>
  ```
</RequestExample>

### Response

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a",
    "name": "Internet plan - Actualizado",
    "description": "Factura de internet actualizada para octubre 2025",
    "provider": "biller",
    "provider_id": "987654",
    "reference": "INV-12345678",
    "status": "CREATED",
    "remarks": null,
    "created_at": "2025-10-20T15:06:00Z",
    "updated_at": "2025-10-20T15:06:00Z",
    "metadata": {
      "key": "value"
    },
    "payment": {
      "id": "new-payment-id",
      "title": "Internet plan - Actualizado",
      "description": "Internet plan - Actualizado",
      "currency": "COP",
      "amount": 75000,
      "amount_label": "75.000",
      "phone": "+573167591039",
      "external_id": "987654",
      "allows": { "accounts": true, "cards": true, "card_extra": false, "realtime": false },
      "status": "pending",
      "is_test": false,
      "payment_link": "https://pay.onepay.test/p/new-payment-id",
      "redirect_url": null,
      "created_at": "2025-10-20T15:25:00Z"
    }
  }
  ```

  ```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 404 theme={null}
  {
    "message": "La factura no existe o pertenece a otra compañía"
  }
  ```
</ResponseExample>