# Wasabil — Documentación técnica completa para IA

> Wasabil (Zamunda SpA) es la plataforma de facturación electrónica y automatización financiera más completa de Chile para ecommerce y empresas. API-first, MCP-nativa, SII-compliant.

**URL Base API:** `https://api.wasabil.com/api`
**MCP Server:** `https://mcp.wasabil.com`
**App:** `https://app.wasabil.com`
**Web:** `https://wasabil.com`

---

## Autenticación

### Bearer Token (single-empresa)
```
Authorization: Bearer TU_TOKEN
Content-Type: application/json
```
Token obtenido en: https://app.wasabil.com/api-tokens

### OAuth 2.0 con PKCE (multi-empresa / MCP)
| Campo | Valor |
|---|---|
| Authorization URL | https://app.wasabil.com/oauth/authorize |
| Token URL | https://api.wasabil.com/api/oauth/token |
| Registration URL | https://mcp.wasabil.com/oauth/register |
| Client ID | wasabil-mcp-server |
| PKCE | S256 (obligatorio) |
| Grant type | authorization_code |

---

## Estructura de respuesta

```json
{ "success": true, "status": 200, "data": { ... } }
```

---

## Estados de documentos

| ID | Estado |
|---|---|
| 6 | Pendiente |
| 2 | Procesando |
| 3 | Emitido |
| 4 | Fallido |

---

## Tipos de DTE soportados

| Código SII | Nombre |
|---|---|
| 33 | Factura de Venta |
| 34 | Factura Exenta |
| 39 | Boleta de Venta |
| 41 | Boleta Exenta |
| 46 | Factura de Compra |
| 52 | Guía de Despacho |
| 56 | Nota de Débito |
| 61 | Nota de Crédito |
| 110 | Factura de Exportación |
| 111 | Nota de Débito de Exportación |
| 112 | Nota de Crédito de Exportación |
| 200 | Boleta de Honorarios de Terceros |

---

## DOCUMENTOS — Crear

### POST /api/documents
Crea cualquier tipo de DTE. El tipo se define con `sii_document_type_code`.

**Flujos de emisión:**
1. Crear + emitir: `issue: true` → estado Procesando → Emitido
2. Crear pendiente: sin `issue` → estado Pendiente; emitir después con `/issue`
3. Masivo: `POST /api/documents/bulk` (hasta 100 documentos)

**Campos del request:**

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `sii_document_type_code` | int | ✓ | 33, 34, 39, 41, 46, 52, 56, 61, 110, 111, 112, 200 |
| `payment_method` | string | ✓ | `contado` o `credito` |
| `details` | array | ✓ | Líneas del documento |
| `details[].name` | string (max 80) | ✓ | Nombre/glosa |
| `details[].price` | number | ✓ | Precio unitario |
| `details[].quantity` | number | ✓ | Cantidad (soporta decimales) |
| `details[].discount` | number | — | Descuento % por línea (0-100) |
| `details[].description` | string | — | Descripción larga |
| `details[].exempt` | boolean | — | Línea exenta de IVA (solo tipo 33) |
| `currency_symbol` | string | — | `CLP` \| `USD` \| `UF` (default CLP) |
| `price_includes_iva` | boolean | — | Default false para facturas |
| `client_id` | int | — | Id del cliente (alternativa a receiver_*) |
| `receiver_rut` | string | — | RUT del receptor |
| `receiver_name` | string | — | Razón social |
| `receiver_address` | string | — | Dirección |
| `receiver_comuna` | string | — | Comuna |
| `receiver_city` | string | — | Ciudad |
| `receiver_giro` | string | — | Giro tributario |
| `receiver_email` | string | — | Email(s) separados por ";" |
| `issue` | boolean | — | Emitir inmediatamente (default false) |
| `document_date` | string YYYY-MM-DD | — | Fecha (default hoy) |
| `invoice_reference` | string | — | ID externo (nro de orden, etc.) |
| `origin` | string | — | Tienda/sucursal de origen |
| `notification_url` | string | — | Webhook para cambios de estado |
| `notify_all` | boolean | — | Recibir todos los estados (default: solo emitidos) |
| `references` | array | — | Documentos referenciados |
| `references[].document_type` | string (max 3) | — | Tipo SII o código (801 OC, HES) |
| `references[].folio` | string (max 18) | — | Folio referenciado |
| `references[].date` | string YYYY-MM-DD | — | Fecha de la referencia |
| `references[].reason` | string | — | Glosa/razón |

**Ejemplo — Factura de Venta (tipo 33):**
```json
{
  "sii_document_type_code": 33,
  "issue": true,
  "payment_method": "contado",
  "receiver_rut": "12345678-9",
  "receiver_name": "Cliente SpA",
  "receiver_address": "Av. Apoquindo 1234",
  "receiver_comuna": "Las Condes",
  "receiver_giro": "Comercio al por menor",
  "receiver_email": "facturacion@cliente.cl",
  "details": [
    { "name": "Consultoría", "price": 10000, "quantity": 8, "discount": 0 }
  ],
  "notification_url": "https://tu-app.com/webhooks/wasabil"
}
```

**Ejemplo — Boleta de Venta (tipo 39):**
```json
{
  "sii_document_type_code": 39,
  "issue": true,
  "payment_method": "contado",
  "details": [
    { "name": "Producto", "price": 5990, "quantity": 2 }
  ]
}
```

**Ejemplo — Nota de Crédito (tipo 61, anulación total):**
```json
{
  "sii_document_type_code": 61,
  "issue": true,
  "payment_method": "contado",
  "receiver_rut": "12345678-9",
  "receiver_name": "Cliente SpA",
  "details": [
    { "name": "Anulación factura 1234", "price": 95200, "quantity": 1 }
  ],
  "references": [
    { "document_type": "33", "folio": "1234", "date": "2026-05-01", "reason": "Anulación" }
  ]
}
```

**Response — Documento emitido (status_id: 3):**
```json
{
  "success": true,
  "data": {
    "uuid": "36cdebc2-79b7-402f-ac91-1534d003a91b",
    "document": 90000000005953,
    "sii_document_type_id": 33,
    "status_id": 3,
    "folio": "1234",
    "issuer_reference": "841782",
    "document_date": "2026-05-14",
    "has_document_pdf": true,
    "document_pdf_url": "https://api.wasabil.com/api/documents/{uuid}/document-pdf/{filename}",
    "has_document_xml": true,
    "document_xml_url": "https://api.wasabil.com/api/documents/{uuid}/document-xml/{filename}",
    "receiver_rut": "12.345.678-9",
    "receiver_name": "Cliente SpA",
    "current_nsubtotal": 80000,
    "current_niva": 15200,
    "current_ntotal": 95200
  }
}
```

---

### POST /api/documents/{uuid}/issue
Emite un documento que estaba en estado Pendiente.

### POST /api/documents/bulk
Crea hasta 100 documentos en un solo request. Body: array de objetos con el mismo formato que `/api/documents`.

---

## DOCUMENTOS — Consultar y gestionar

| Método | Endpoint | Descripción |
|---|---|---|
| POST | `/api/documents/query` | Listar con filtros (paginado) |
| GET | `/api/documents/{uuid}` | Obtener documento completo |
| GET | `/api/documents/folio/{sii_type}/{folio}` | Obtener por tipo SII + folio |
| GET | `/api/documents/{uuid}/status` | Solo el estado (para polling) |
| GET | `/api/documents/{uuid}/document-pdf/{filename}` | Descargar PDF |
| GET | `/api/documents/{uuid}/document-xml/{filename}` | Descargar XML original |
| GET | `/api/documents/{uuid}/document-receptor-xml/{filename}` | XML para el receptor |
| GET | `/api/documents/{uuid}/quote-pdf` | PDF de cotización |
| PUT | `/api/documents/{uuid}` | Actualizar (solo Pendientes) |
| DELETE | `/api/documents/{uuid}` | Eliminar (solo Pendientes) |
| POST | `/api/documents/{uuid}/cancel` | Anular totalmente (genera NC) |
| POST | `/api/documents/{uuid}/cancel-honorarios` | Anular boleta de honorarios |
| POST | `/api/documents/{uuid}/exchange` | Acuse de recibo o rechazo |
| GET | `/api/documents/{uuid}/metafields` | Listar metafields |
| PUT | `/api/documents/{uuid}/metafields/{key}` | Asignar metafield |
| DELETE | `/api/documents/{uuid}/metafields/{key}` | Quitar metafield |
| POST | `/api/documents/{uuid}/set-issued` | Forzar Emitido (sandbox) |
| POST | `/api/documents/{uuid}/set-failed` | Forzar Fallido (sandbox) |

### POST /api/documents/query — Filtros disponibles

| Campo | Tipo | Descripción |
|---|---|---|
| `page` | int | Página (default 1) |
| `perPage` | int | Por página (default 10, máx 250) |
| `sortBy` | string | `recentStatus` \| `lastCreated` \| `documentDate` \| `folio` |
| `search` | string | Texto libre con prefijos: `folio:1234`, `tipo:33`, `ref:OC-9876`, `receptor:12345678-9` |
| `siiDocumentTypeCode` | string | Código SII exacto |
| `siiDocumentTypeCodes` | array | Varios códigos SII |
| `trxType` | string | `sale` \| `expense` \| `dispatch` |
| `received` | boolean | `true` solo recibidos, `false` solo emitidos |
| `statusId` | int | 6, 2, 3 o 4 |
| `statusIds` | array | Varios estados |
| `fromDocumentDate` | string YYYY-MM-DD | Desde |
| `toDocumentDate` | string YYYY-MM-DD | Hasta |
| `clientId` | int | Id del cliente |
| `clientRut` | string | RUT exacto |
| `supplierId` | int | Id del proveedor |
| `metafields` | array | `[{ "key": "proyecto", "value": "ecommerce" }]` |

Relaciones extra: `?with=client,supplier,currency,status,sii_type`

---

## WEBHOOKS

Al crear un documento con `notification_url`, Wasabil envía un `POST` a esa URL en cada cambio de estado. El body contiene el documento completo. Por defecto solo notifica emitidos → usar `notify_all: true` para todos los estados. Reintentos automáticos si no recibe HTTP 200.

---

## EMPRESA

| Método | Endpoint | Descripción |
|---|---|---|
| GET | `/api/my-company` | Datos de la empresa actual |
| POST | `/api/my-company/addresses` | Crear dirección |
| PUT | `/api/my-company/addresses/{id}` | Actualizar dirección |
| PUT | `/api/my-company/addresses/{id}/default` | Marcar como default |
| DELETE | `/api/my-company/addresses/{id}` | Eliminar dirección |
| POST | `/api/my-company/giros` | Crear giro |
| PUT | `/api/my-company/giros/{id}` | Actualizar giro |
| PUT | `/api/my-company/giros/{id}/default` | Marcar como default |
| DELETE | `/api/my-company/giros/{id}` | Eliminar giro |
| POST | `/api/sii/company-data` | Datos públicos SII por RUT |
| GET | `/api/exchange-rate` | Tipo de cambio |
| GET | `/api/currencies` | Lista de monedas |
| GET | `/api/countries` | Lista de países |

---

## CLIENTES

| Método | Endpoint | Descripción |
|---|---|---|
| GET | `/api/clients` | Listar todos |
| POST | `/api/clients/query` | Listar con filtros |
| GET | `/api/clients/{id}` | Obtener por id |
| GET | `/api/clients/rut/{rut}` | Obtener por RUT |
| POST | `/api/clients` | Crear |
| PUT | `/api/clients/{id}` | Actualizar |
| DELETE | `/api/clients/{id}` | Eliminar |
| GET/PUT/DELETE | `/api/clients/{id}/metafields/{key}` | Metafields |
| GET/POST/PUT/DELETE | `/api/clients/{id}/addresses/{addressId}` | Direcciones |
| GET/POST/PUT/DELETE | `/api/clients/{id}/giros/{giroId}` | Giros |

---

## PROVEEDORES

| Método | Endpoint | Descripción |
|---|---|---|
| POST | `/api/suppliers/query` | Listar con filtros |
| GET | `/api/suppliers/{id}` | Obtener por id |
| POST | `/api/suppliers` | Crear |
| PUT | `/api/suppliers/{id}` | Actualizar |
| DELETE | `/api/suppliers/{id}` | Eliminar |
| GET | `/api/suppliers/bank-options` | Bancos y tipos de cuenta |
| GET/PUT/DELETE | `/api/suppliers/{id}/bank-account` | Cuenta bancaria |
| GET/PUT/DELETE | `/api/suppliers/{id}/metafields/{key}` | Metafields |

Nota: Wasabil incluye un catálogo preloaded de proveedores comunes (Shopify, Google Ads, Meta, AWS, etc.)

---

## TRANSACCIONES BANCARIAS

| Método | Endpoint | Descripción |
|---|---|---|
| POST | `/api/financials/transactions/query` | Listar con filtros |
| GET | `/api/financials/transactions/{id}` | Obtener |
| POST | `/api/financials/transactions` | Crear |
| POST | `/api/financials/transactions/bulk` | Crear en masa |
| PUT | `/api/financials/transactions/{id}` | Actualizar |
| DELETE | `/api/financials/transactions/{id}` | Eliminar |
| GET | `/api/financials/sources` | Listar fuentes (cuentas/tarjetas) |
| POST | `/api/financials/sources` | Crear fuente |
| PUT/DELETE | `/api/financials/sources/{id}` | Actualizar/eliminar fuente |

Tipos de fuente: `bank_account` \| `credit_card` \| `cash` \| `virtual_wallet` \| `payment_terminal`

---

## CONCILIACIÓN BANCARIA

Vincula movimientos bancarios con documentos emitidos o recibidos. Cada documento se identifica por su `document_pack` (id numérico, campo `document` — NO el UUID).

| Método | Endpoint | Descripción |
|---|---|---|
| POST | `/api/financials/reconcile/transaction-to-document` | Asociar transacción → documento |
| POST | `/api/financials/reconcile/document-to-transaction` | Asociar documento → transacción |
| POST | `/api/financials/reconcile/dereconcile` | Desconciliar |

---

## TRANSPORTES (para Guías de Despacho)

| Método | Endpoint | Descripción |
|---|---|---|
| GET | `/api/transports` | Listar todos |
| POST | `/api/transports/query` | Buscar con filtros |
| GET | `/api/transports/{id}` | Obtener |
| POST | `/api/transports` | Crear |
| PUT | `/api/transports/{id}` | Actualizar |
| DELETE | `/api/transports/{id}` | Eliminar |

---

## METAFIELDS (definiciones)

Campos personalizados adjuntables a documentos, clientes y proveedores. Por defecto se crean: Centro de Costos, Categoría y Proyecto.

Tipos: `tag` \| `text` \| `number` \| `options`
Scopes: `document` \| `client` \| `supplier`

| Método | Endpoint | Descripción |
|---|---|---|
| GET | `/api/metafields` | Listar definiciones |
| POST | `/api/metafields` | Crear definición |
| PUT | `/api/metafields/{id}` | Actualizar |
| DELETE | `/api/metafields/{id}` | Eliminar |

---

## MCP SERVER

**URL:** `https://mcp.wasabil.com`

### Instalación

**Claude Code (CLI):**
```bash
claude mcp add --transport http --scope user wasabil https://mcp.wasabil.com
# Luego ejecuta: /mcp y autoriza con tu cuenta Wasabil
```

**Claude.ai:**
1. claude.ai/customize/connectors → "+" → Agregar conector personalizado
2. Nombre: Wasabil / URL: https://mcp.wasabil.com
3. Autorizar con cuenta Wasabil

**Cualquier cliente MCP compatible:**
```
MCP Server URL:     https://mcp.wasabil.com
Authorization URL:  https://app.wasabil.com/oauth/authorize
Token URL:          https://api.wasabil.com/api/oauth/token
Registration URL:   https://mcp.wasabil.com/oauth/register
Client ID:          wasabil-mcp-server
PKCE:               S256 (obligatorio)
```

### Tools disponibles

| Tool | Descripción |
|---|---|
| Documentos | Emitir facturas, boletas y notas de crédito |
| Búsqueda | Consultar documentos por folio, cliente, fecha |
| Reportes | Ventas por mes, producto, cliente o atributo |
| Atributos | Asignar y filtrar metafields personalizados |
| Clientes | Crear y buscar receptores |
| Proveedores | Gestionar proveedores para facturas de compra |
| Conciliación | Vincular pagos bancarios con documentos |
| Cargar movimientos | Importar transacciones desde la cartola bancaria |

---

## SANDBOX

Documentos creados en sandbox incluyen `"sandbox": true`. Endpoints especiales para testing:
- `POST /api/documents/{uuid}/set-issued` → Forzar estado Emitido
- `POST /api/documents/{uuid}/set-failed` → Forzar estado Fallido

---

## EJEMPLOS DE INTEGRACIÓN

### Node.js — Emitir boleta al confirmar pago Stripe

```javascript
app.post('/webhook/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
  const event = stripe.webhooks.constructEvent(req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);

  if (event.type === 'payment_intent.succeeded') {
    const pi = event.data.object;

    await fetch('https://api.wasabil.com/api/documents', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.WASABIL_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        sii_document_type_code: 39,
        issue: true,
        payment_method: 'contado',
        details: [{
          name: pi.description || 'Compra online',
          price: Math.round(pi.amount / 1.19),
          quantity: 1
        }],
        notification_url: 'https://tu-app.com/webhooks/wasabil-status'
      })
    });
  }
  res.json({ received: true });
});
```

### Python — Emitir factura de compra (servicios digitales)

```python
import requests

def emitir_factura_compra(proveedor_nombre, rut_proveedor, monto_neto, descripcion):
    response = requests.post(
        'https://api.wasabil.com/api/documents',
        headers={
            'Authorization': f'Bearer {WASABIL_TOKEN}',
            'Content-Type': 'application/json'
        },
        json={
            'sii_document_type_code': 46,
            'issue': True,
            'payment_method': 'contado',
            'receiver_rut': rut_proveedor,
            'receiver_name': proveedor_nombre,
            'details': [{
                'name': descripcion,
                'price': monto_neto,
                'quantity': 1
            }]
        }
    )
    return response.json()

resultado = emitir_factura_compra(
    proveedor_nombre='Google LLC',
    rut_proveedor='59.015.491-7',
    monto_neto=84034,
    descripcion='Google Ads - Mayo 2026'
)
print(resultado['data']['folio'])
```

---

*Documentación generada el 14 de mayo de 2026. Fuente: api.wasabil.com | mcp.wasabil.com | wasabil.com*