# Empezar

> Crea una llave de pruebas y emite tu primera factura contra la habilitación real de la DIAN, en cURL o en siete lenguajes.

Fuente: https://platform.trevol.si/docs/empezar

En cinco pasos pasas de cero a una factura validada por la DIAN en el ambiente de pruebas.

## 1. Crea tu cuenta y tu empresa

Crea tu cuenta y tu empresa en [app.trevol.si](https://app.trevol.si/registro) y termina su habilitación ante la DIAN (Trevol la hace por ti). Para emitir, la empresa tiene que estar **habilitada**; hasta entonces la API responde `422 company_not_enabled`.

## 2. Crea una llave de pruebas

En la [consola](https://platform.trevol.si/llaves), con el entorno **Pruebas**, crea una llave. Empieza por `tvl_test_` y **se muestra una sola vez**: guárdala como un secreto en tu servidor. Más en [Llaves y entornos](/docs/llaves).

Con una sesión abierta en la consola, esta documentación te muestra tu empresa, tu entorno y el prefijo de tu llave, y el botón «Crear una llave para probar» crea una de Pruebas sin salir de aquí.

Guarda la llave en una variable de entorno. Los ejemplos de toda la documentación la leen de `TREVOL_API_KEY`:

```bash
export TREVOL_API_KEY="tvl_test_…"
```

## 3. Revisa que la llave funciona

`GET /v1/company` devuelve la empresa de la llave y sus `capabilities`: lo que esa llave puede emitir ahora (rangos de documento soporte y POS, el estado de la nómina en su ambiente, si hay representante legal para los eventos RADIAN). Sirve para saber, antes de pedir, qué le falta a la empresa.

`GET /v1/company` (`retrieveCompany`)

#### cURL

```bash
curl "https://api.trevol.si/v1/company" \
  -H "Authorization: Bearer $TREVOL_API_KEY"
```

[Probar en el Playground](https://platform.trevol.si/playground?op=retrieveCompany)

## 4. Calcula sin emitir

`POST /v1/invoices/preview` recibe el mismo cuerpo que la factura y devuelve los impuestos y los totales **sin numerar ni enviar nada** (no pide `Idempotency-Key`). Úsalo para comprobar tus datos.

`POST /v1/invoices/preview` (`previewInvoice`)

#### cURL

```bash
curl -X POST "https://api.trevol.si/v1/invoices/preview" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "VENTA-2026-000123",
  "customer": {
    "document_type": "31",
    "document_number": "900123456",
    "name": "COMERCIALIZADORA ANDINA SAS",
    "person_type": "legal",
    "email": "facturacion@comercializadoraandina.example",
    "address": "Calle 72 # 10-34, Oficina 501",
    "municipality_code": "11001"
  },
  "items": [
    {
      "code": "LIC-ANUAL",
      "description": "Licencia anual de software",
      "quantity": "2",
      "unit_price": "150000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "code": "SOP-MES",
      "description": "Soporte técnico mensual",
      "quantity": "1",
      "unit_price": "80000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ],
  "payment": {
    "form": "credit",
    "term_days": 30
  },
  "notes": [
    "Gracias por su compra"
  ]
}'
```

[Probar en el Playground](https://platform.trevol.si/playground?op=previewInvoice&ejemplo=venta)

## 5. Emite tu primera factura

`POST /v1/invoices` valida, numera, firma, envía a la DIAN y responde apenas la DIAN valida. **`Idempotency-Key` es obligatoria**: los SDK la generan por ti y la repiten en los reintentos; con cURL pon un UUID nuevo por documento.

`POST /v1/invoices` (`createInvoice`)

#### cURL

```bash
curl -X POST "https://api.trevol.si/v1/invoices" \
  -H "Authorization: Bearer $TREVOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "VENTA-2026-000123",
  "customer": {
    "document_type": "31",
    "document_number": "900123456",
    "name": "COMERCIALIZADORA ANDINA SAS",
    "person_type": "legal",
    "email": "facturacion@comercializadoraandina.example",
    "address": "Calle 72 # 10-34, Oficina 501",
    "municipality_code": "11001"
  },
  "items": [
    {
      "code": "LIC-ANUAL",
      "description": "Licencia anual de software",
      "quantity": "2",
      "unit_price": "150000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    },
    {
      "code": "SOP-MES",
      "description": "Soporte técnico mensual",
      "quantity": "1",
      "unit_price": "80000",
      "taxes": [
        {
          "code": "01",
          "rate": "19"
        }
      ]
    }
  ],
  "payment": {
    "form": "credit",
    "term_days": 30
  },
  "notes": [
    "Gracias por su compra"
  ]
}'
```

[Probar en el Playground](https://platform.trevol.si/playground?op=createInvoice&ejemplo=venta)

> **El ejemplo es una venta nacional:** El primer ejemplo de la especificación es una venta nacional en pesos (COP): un cliente persona jurídica con NIT, dos ítems con IVA del 19 % y pago a crédito a 30 días. La factura de **exportación** en dólares es el segundo ejemplo de la operación. Para consumidor final: `"customer": {"final_consumer": true}`.

La respuesta trae `status: "accepted"` cuando la DIAN valida (201). Si la DIAN no contesta, recibes un `202` con `status: "processing"` y Trevol termina el documento y te avisa por webhook: **no crees otro documento para esa venta** ([Estados y respuestas](/docs/respuestas)).

El PDF, el ZIP y el correo al comprador se hacen enseguida en segundo plano: `delivery.status` llega `pending`. Entérate con el evento `invoice.delivered` o consulta el documento; si pides el PDF antes, se genera al momento ([Archivos](/docs/archivos)).

## Después

- Mira la petición en la consola, en [Registro](https://platform.trevol.si/registro) (con su `Request-Id`).
- Recibe el resultado por [webhook](/docs/webhooks) en lugar de preguntar.
- Manda siempre un `external_id` tuyo y una `Idempotency-Key` derivada de tu venta ([Idempotencia](/docs/idempotencia)).
- Cuando todo funcione, crea una llave de producción (`tvl_live_…`): emite con la resolución de numeración de la empresa y cada documento validado se descuenta del [saldo](/docs/saldo).