# Quickstart

> Emite tu primer DTE (factura electrónica chilena) contra la API REST de Simplo — con curl, C#, Java, Python o el SDK TypeScript — y sigue su estado en el SII.

Emite tu primer DTE (Documento Tributario Electrónico — una factura o boleta
electrónica chilena) en pocos minutos. Simplo es una **API REST**: cualquier
lenguaje que hable HTTP + JSON sirve. Aquí el mismo flujo en curl, C#, Java,
Python y el SDK TypeScript.

> **Beta privada:**
> La API de Simplo está en **beta privada**: el acceso con API key a la
> superficie de emisión se habilita cuenta por cuenta, así que este recorrido
> funciona una vez que tu cuenta está en la beta. Para pedir acceso, escribe a
> [hola@simplo.cl](mailto:hola@simplo.cl).

## 1. Configura tus credenciales

Consigue una API key (`sk_simplo_...`) desde tu cuenta de Simplo — ver
[Autenticación](/comienza/autenticacion/) — y expórtala:

```bash
export SIMPLO_API_KEY="sk_simplo_..."
```

Toda petición lleva el header `X-Api-Key` y opera en el contexto de la
empresa asociada a la credencial — no envías el RUT emisor en cada llamada.

## 2. Emite una factura

`POST /api/v1/billing/dte` exige un header `Idempotency-Key` (UUID): un
reintento con la misma key nunca duplica la factura.

#### curl

```bash
curl -X POST https://api.simplo.cl/api/v1/billing/dte \
  -H "X-Api-Key: $SIMPLO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "tipo_dte": 33,
    "receptor": {
      "rut": "76543210-K",
      "razon_social": "Cliente Ejemplo SpA",
      "giro": "Servicios de software",
      "direccion": "Av. Providencia 1234",
      "comuna": "Providencia"
    },
    "detalle": [
      { "nombre": "Servicios de consultoría", "cantidad": 10, "precio": 50000 }
    ]
  }'
```

```json
// 201 Created
{
  "id": "4f9c9c2e-8a49-4f2e-9d5f-0d8f3a1b2c3d",
  "folio": 1042,
  "tipo_dte": 33,
  "estado": "firmado",
  "monto_total": 595000,
  "created_at": "2026-08-01T14:30:00Z"
}
```

#### C#

```csharp
using System.Net.Http.Json;
using System.Text.Json;

var http = new HttpClient { BaseAddress = new Uri("https://api.simplo.cl") };
http.DefaultRequestHeaders.Add("X-Api-Key",
    Environment.GetEnvironmentVariable("SIMPLO_API_KEY"));

var request = new HttpRequestMessage(HttpMethod.Post, "/api/v1/billing/dte")
{
    Content = JsonContent.Create(new
    {
        tipo_dte = 33, // Factura Electrónica
        receptor = new
        {
            rut = "76543210-K",
            razon_social = "Cliente Ejemplo SpA",
            giro = "Servicios de software",
            direccion = "Av. Providencia 1234",
            comuna = "Providencia",
        },
        detalle = new[]
        {
            new { nombre = "Servicios de consultoría", cantidad = 10, precio = 50000 },
        },
    })
};
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode(); // 201

var dte = await response.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine($"folio {dte.GetProperty("folio")} — {dte.GetProperty("estado")}");
// folio 1042 — firmado
```

#### Java

```java
import java.net.URI;
import java.net.http.*;
import java.util.UUID;

var body = """
    {
      "tipo_dte": 33,
      "receptor": {
        "rut": "76543210-K",
        "razon_social": "Cliente Ejemplo SpA",
        "giro": "Servicios de software",
        "direccion": "Av. Providencia 1234",
        "comuna": "Providencia"
      },
      "detalle": [
        { "nombre": "Servicios de consultoría", "cantidad": 10, "precio": 50000 }
      ]
    }""";

HttpClient http = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.simplo.cl/api/v1/billing/dte"))
    .header("X-Api-Key", System.getenv("SIMPLO_API_KEY"))
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", UUID.randomUUID().toString())
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response =
    http.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode()); // 201
System.out.println(response.body());
// {"id":"4f9c…","folio":1042,"estado":"firmado",…}
```

#### Python

```python
import http.client, json, os, uuid

conn = http.client.HTTPSConnection("api.simplo.cl")
conn.request(
    "POST",
    "/api/v1/billing/dte",
    body=json.dumps({
        "tipo_dte": 33,  # Factura Electrónica
        "receptor": {
            "rut": "76543210-K",
            "razon_social": "Cliente Ejemplo SpA",
            "giro": "Servicios de software",
            "direccion": "Av. Providencia 1234",
            "comuna": "Providencia",
        },
        "detalle": [
            {"nombre": "Servicios de consultoría", "cantidad": 10, "precio": 50000}
        ],
    }),
    headers={
        "X-Api-Key": os.environ["SIMPLO_API_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)

dte = json.loads(conn.getresponse().read())
print(dte["folio"], dte["estado"])  # 1042 firmado
```

#### SDK TypeScript

```bash
npm install @simplohq/sdk
```

```ts
import Simplo from '@simplohq/sdk';

const simplo = new Simplo(); // lee SIMPLO_API_KEY

const dte = await simplo.dtes.emit({
  tipo_dte: 33, // Factura Electrónica
  receptor: {
    rut: '76543210-K',
    razon_social: 'Cliente Ejemplo SpA',
    giro: 'Servicios de software',
    direccion: 'Av. Providencia 1234',
    comuna: 'Providencia',
  },
  detalle: [{ nombre: 'Servicios de consultoría', cantidad: 10, precio: 50000 }],
});

console.log(dte.folio, dte.estado); // 1042 "firmado"
```

El SDK genera la `Idempotency-Key` y reintenta con backoff por ti — ver
[SDK TypeScript](/agentes/sdk/).

La respuesta `201` retorna en cuanto el documento queda firmado
(`estado: "firmado"`): folio asignado desde el CAF activo, XML generado,
timbre electrónico (TED) y firma digital listos. El envío al SII (Servicio de
Impuestos Internos) ocurre de forma **asíncrona**.

Los montos son pesos chilenos (CLP) enteros. El IVA (19%) lo calcula la API —
tú envías precios netos.

## 3. Sigue el estado del documento

Por polling sobre `GET /api/v1/billing/dte/{id}`:

#### curl

```bash
curl https://api.simplo.cl/api/v1/billing/dte/4f9c9c2e-8a49-4f2e-9d5f-0d8f3a1b2c3d \
  -H "X-Api-Key: $SIMPLO_API_KEY"
```

```json
// 200 OK (extracto)
{
  "estado": "aceptado",
  "tracking": { "track_id": "1234567890", "estado_envio": "aceptado" }
}
```

#### C#

```csharp
var current = await http.GetFromJsonAsync<JsonElement>(
    $"/api/v1/billing/dte/{dte.GetProperty("id")}");
Console.WriteLine(current.GetProperty("estado"));
// "enviando" | "procesando" | "aceptado" | "rechazado" | "con_reparos"
```

#### Java

```java
HttpRequest poll = HttpRequest.newBuilder()
    .uri(URI.create("https://api.simplo.cl/api/v1/billing/dte/" + dteId))
    .header("X-Api-Key", System.getenv("SIMPLO_API_KEY"))
    .GET()
    .build();
System.out.println(http.send(poll, HttpResponse.BodyHandlers.ofString()).body());
// "estado": "enviando" | "procesando" | "aceptado" | "rechazado" | "con_reparos"
```

#### Python

```python
conn.request(
    "GET",
    f"/api/v1/billing/dte/{dte['id']}",
    headers={"X-Api-Key": os.environ["SIMPLO_API_KEY"]},
)
current = json.loads(conn.getresponse().read())
print(current["estado"])
# "enviando" | "procesando" | "aceptado" | "rechazado" | "con_reparos"
```

#### SDK TypeScript

```ts
const current = await simplo.dtes.retrieve(dte.id);
console.log(current.estado); // "enviando" | "procesando" | "aceptado" | …
console.log(current.tracking?.track_id); // track ID del SII una vez enviado
```

O suscríbete a webhooks — ver [Webhooks](/referencia/webhooks/). El ciclo
completo de estados está documentado en [Estados](/referencia/estados/).

## 4. Descarga el PDF y el XML

```bash
# PDF con timbre electrónico PDF417 (agrega ?cedible=true para factoring)
curl -o factura.pdf \
  "https://api.simplo.cl/api/v1/billing/dte/$DTE_ID/pdf" \
  -H "X-Api-Key: $SIMPLO_API_KEY"

# XML firmado (ISO-8859-1)
curl -o factura.xml \
  "https://api.simplo.cl/api/v1/billing/dte/$DTE_ID/xml" \
  -H "X-Api-Key: $SIMPLO_API_KEY"
```

Con el SDK: `simplo.dtes.pdf(dte.id, { cedible: true })` y
`simplo.dtes.xml(dte.id)`.

## Antes de poder emitir en serio

Dos pasos de configuración, una sola vez por empresa:

1. **Certificado digital** — se sube a través de tu cuenta de Simplo; verifica
   su estado con `GET /api/v1/billing/empresa/certificado`.
2. **Folios (CAF)** — un CAF (Código de Autorización de Folios) es el archivo
   del SII que autoriza un rango de números de documento. Súbelo con
   `POST /api/v1/billing/caf` y monitorea la disponibilidad con
   `GET /api/v1/billing/caf`.

## Siguientes pasos

- [El contrato OpenAPI](/referencia/contrato-openapi/) — descarga la spec y
  genera un cliente C#, Java o TypeScript
- [Referencia por endpoint](/api/) — los 27 endpoints, con ejemplos en curl,
  C#, Java y JavaScript
- [Autenticación](/comienza/autenticacion/) — API keys y auth avanzada
- [Tipos de DTE](/referencia/tipos-de-dte/) — los 12 tipos de documento
- [Errores](/referencia/errores/) — manejo de errores y reintentos
- [Paginación](/referencia/paginacion/) — listados con cursor
- [Webhooks](/referencia/webhooks/) — actualizaciones de estado en tiempo real
- [Multi-empresa](/comienza/multi-empresa/) — operar más de una empresa
- [Agentes](/agentes/conecta-tu-agente/) — punteros para coding agents

---

Versión HTML: https://docs.simplo.cl/comienza/quickstart/ · Índice para agentes: https://docs.simplo.cl/llms.txt