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

# Tu primera llamada a la API de facturación electrónica en 2 minutos

> Crea una API key de sandbox gratis en developers.tupana.ai, haz tu primera llamada a la API de Tupana y emite una factura electrónica de prueba (DTE 33) sin tocar el SII.

En dos minutos vas a tener una API key de sandbox, una respuesta real de la API de Tupana y una factura electrónica de prueba creada. Sandbox es gratis y **nunca envía nada al SII**.

<Info>
  Todo lo que necesitas es un correo. No hace falta tarjeta, certificado digital ni la clave del SII de ninguna empresa para esta guía.
</Info>

## 1. Crea tu API key de sandbox

1. Entra a [developers.tupana.ai/console](https://developers.tupana.ai/console) e inicia sesión con tu correo.
2. Abre **API Keys** y crea una key. Las keys nuevas **nacen en modo sandbox**: no emiten documentos reales hasta que tú lo decidas.
3. Cópiala y guárdala en una variable de entorno. Se muestra una sola vez.

```bash theme={null}
export TUPANA_API_KEY="pega_aqui_tu_api_key"
```

<Warning>
  La API key va en tu backend, nunca en el navegador ni en un repositorio público.
</Warning>

## 2. Haz tu primera llamada

Consulta la [nómina pública de empresas del SII](/api-reference/v2/free-databases/companies-search). Es una base gratuita: funciona con cualquier key, de sandbox o de producción, y no consume cupo.

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.tupana.ai/v2/sii-companies/?size=mediana&district=LAS%20CONDES&page_size=3" \
    -H "Authorization: Api-Key $TUPANA_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    "https://api.tupana.ai/v2/sii-companies/?size=mediana&district=LAS%20CONDES&page_size=3",
    { headers: { Authorization: `Api-Key ${process.env.TUPANA_API_KEY}` } }
  );
  console.log(await res.json());
  ```

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

  res = requests.get(
      "https://api.tupana.ai/v2/sii-companies/",
      params={"size": "mediana", "district": "LAS CONDES", "page_size": 3},
      headers={"Authorization": f"Api-Key {os.environ['TUPANA_API_KEY']}"},
  )
  print(res.json())
  ```
</CodeGroup>

La respuesta trae empresas reales con su tramo de ventas, rubro y comuna:

```json theme={null}
{
  "year": 2024,
  "count": 1284,
  "page": 1,
  "page_size": 3,
  "results": [
    {
      "tax_id": "76543210-3",
      "name": "CONSTRUCTORA VEGA SPA",
      "size": "mediana",
      "employees": 40,
      "sector": "CONSTRUCCION",
      "district": "LAS CONDES"
    }
  ]
}
```

Si recibes `401`, revisa que el header sea exactamente `Authorization: Api-Key <tu_key>` (con `Api-Key`, no `Bearer`). Más detalle en [Autenticación](/user-guide/authentication).

## 3. Emite una factura de prueba

Con una key de sandbox, `POST /v2/documents/batch/` **simula** la emisión: el documento se crea y se puede consultar, pero no va al SII y su folio tiene la forma `SANDBOX-{n}`. En sandbox no se exige la clave del SII de la empresa emisora.

Usa como emisor (`document_issuer.rut`) el RUT de una empresa que tengas conectada en tu cuenta. Para conectar una, mira [Tupana Link](/api-reference/v2/connect/tupana-link) (en sandbox, la conexión también es de prueba).

```bash theme={null}
curl -X POST https://api.tupana.ai/v2/documents/batch/ \
  -H "Authorization: Api-Key $TUPANA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: primera-factura-001" \
  -H "X-Use-Defaults: true" \
  -d '{
    "documents": [
      {
        "dte_type": { "code": "33" },
        "document_issuer": { "rut": "RUT_DE_TU_EMPRESA" },
        "document_receiver": { "rut": "98765432-1", "business_name": "Cliente Importante Ltda" },
        "details": [
          { "item_name": "Servicio de consultoría", "quantity": 1, "unit_price": 100000 }
        ]
      }
    ]
  }'
```

* `X-Use-Defaults: true` completa la fecha, la actividad y la dirección con los datos por defecto de cada empresa.
* `Idempotency-Key` evita duplicados: si repites la llamada con la misma clave, recibes el mismo lote sin volver a emitir.

La respuesta es `202` con un `batch_id` y el resultado de cada documento. El estado final también llega por [webhook](/guias/webhooks).

## Siguientes pasos

<CardGroup cols={2}>
  <Card title="Emitir facturas en lote" icon="layer-group" href="/guias/emision-masiva">
    Hasta 200 documentos por llamada, con idempotencia y resultados por webhook.
  </Card>

  <Card title="Recibir avisos de estado" icon="bell" href="/guias/webhooks">
    Configura webhooks y verifica la firma HMAC.
  </Card>

  <Card title="Construir un agente de IA" icon="robot" href="/agentes/introduccion">
    Usa el servidor MCP o tool calling sobre la API REST.
  </Card>

  <Card title="Pasar a producción" icon="rocket" href="/precios">
    Precios en UF por empresa y qué cambia al salir de sandbox.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.