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

# Resoluciones DIAN

> Carga y activa la resolución de facturación de tu empresa.

La resolución es el permiso de la DIAN para emitir documentos con un prefijo y un rango de números. La sacas del portal MUISCA y la cargas acá.

<Warning>
  **Carga una resolución por tipo de documento.** Las facturas y las notas crédito llevan numeración separada: sin una resolución de `credit_note`, no vas a poder anular ni devolver.
</Warning>

## Cargar una resolución

Nace en estado `draft`. Activarla es un paso aparte, después de que validemos los datos: una resolución mal digitada no falla al guardarse, falla al timbrar la primera factura real.

### Body

<ParamField body="number" type="string" required placeholder="18760000001">
  Número de la resolución que asignó la DIAN.
</ParamField>

<ParamField body="document_type" type="string" required placeholder="invoice">
  Tipo de documento que numera: `invoice`, `credit_note` o `debit_note`.
</ParamField>

<ParamField body="from" type="integer" required placeholder="1">
  Primer número del rango autorizado.
</ParamField>

<ParamField body="to" type="integer" required placeholder="5000">
  Último número del rango autorizado.
</ParamField>

<ParamField body="prefix" type="string" placeholder="FE">
  Prefijo autorizado. Acompaña al consecutivo en el número visible del documento (`FE1`, `NC900`).
</ParamField>

<ParamField body="valid_from" type="date" placeholder="2026-01-15">
  Inicio de vigencia.
</ParamField>

<ParamField body="valid_until" type="date" placeholder="2027-01-15">
  Fin de vigencia. Vencida deja de timbrar aunque queden números.
</ParamField>

<ParamField body="issued_at" type="date" placeholder="2026-01-15">
  Fecha en que la DIAN expidió la resolución.
</ParamField>

<ParamField body="technical_key" type="string">
  Clave técnica de la resolución. Entra en el cálculo del CUFE.

  <Note>
    Se guarda encriptada y nunca vuelve en una respuesta de la API.
  </Note>
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.onepay.la/v1/fiscal-resolutions \
    -H "Authorization: Bearer $ONEPAY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "number": "18760000001",
      "prefix": "FE",
      "document_type": "invoice",
      "from": 1,
      "to": 5000,
      "valid_from": "2026-01-15",
      "valid_until": "2027-01-15",
      "technical_key": "fc8eac4227b2b1e8..."
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "res_01J8XK5M2P",
    "number": "18760000001",
    "prefix": "FE",
    "document_type": "invoice",
    "status": "draft",
    "from": 1,
    "to": 5000,
    "current": 0,
    "next_number": 1,
    "remaining": 5000,
    "usage_percentage": 0,
    "valid_until": "2027-01-15",
    "is_expired": false,
    "can_stamp": false
  }
  ```
</ResponseExample>

***

## Activar

`POST /fiscal-resolutions/{resolution}/activate`

Al activar una resolución, la anterior del mismo prefijo y tipo queda fuera de servicio. Dos resoluciones activas a la vez serían dos numeraciones corriendo en paralelo.

```bash theme={null}
curl -X POST https://api.onepay.la/v1/fiscal-resolutions/res_01J8XK5M2P/activate \
  -H "Authorization: Bearer $ONEPAY_API_KEY"
```

Falla con `resolution_not_activatable` si está vencida o ya consumió todo su rango.

***

## Listar

`GET /fiscal-resolutions`

Devuelve todas tus resoluciones con su consumo. Los campos que importan para operar:

| Campo              |                                             |
| ------------------ | ------------------------------------------- |
| `next_number`      | El siguiente consecutivo que se va a usar   |
| `remaining`        | Números que quedan disponibles              |
| `usage_percentage` | Porcentaje del rango consumido              |
| `can_stamp`        | Si esta resolución puede emitir ahora mismo |

<Note>
  OnePay te avisa al 80% y al 95% del rango consumido, y 30 días antes del vencimiento. Conseguir una resolución nueva depende de los tiempos de la DIAN, así que carga la siguiente apenas recibas el primer aviso.
</Note>