Emisión masiva de documentos

Envío de documentos en lote

curl --request POST \
  --url https://api.tupana.ai/v1/documents/batch \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documents": [
    {
      "dte_type": {
        "code": "33"
      },
      "date_issued": "2024-01-15",
      "document_issuer": {
        "rut": "12345678-9",
        "business_name": "Mi Empresa SpA"
      },
      "document_receiver": {
        "rut": "98765432-1",
        "business_name": "Cliente Importante Ltda"
      },
      "details": [
        {
          "item_name": "Servicio de Consultoría",
          "quantity": 1,
          "unit_price": 100000
        }
      ]
    }
  ]
}
'

import requests

url = "https://api.tupana.ai/v1/documents/batch"

payload = { "documents": [
        {
            "dte_type": { "code": "33" },
            "date_issued": "2024-01-15",
            "document_issuer": {
                "rut": "12345678-9",
                "business_name": "Mi Empresa SpA"
            },
            "document_receiver": {
                "rut": "98765432-1",
                "business_name": "Cliente Importante Ltda"
            },
            "details": [
                {
                    "item_name": "Servicio de Consultoría",
                    "quantity": 1,
                    "unit_price": 100000
                }
            ]
        }
    ] }
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    documents: [
      {
        dte_type: {code: '33'},
        date_issued: '2024-01-15',
        document_issuer: {rut: '12345678-9', business_name: 'Mi Empresa SpA'},
        document_receiver: {rut: '98765432-1', business_name: 'Cliente Importante Ltda'},
        details: [{item_name: 'Servicio de Consultoría', quantity: 1, unit_price: 100000}]
      }
    ]
  })
};

fetch('https://api.tupana.ai/v1/documents/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tupana.ai/v1/documents/batch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'documents' => [
        [
                'dte_type' => [
                                'code' => '33'
                ],
                'date_issued' => '2024-01-15',
                'document_issuer' => [
                                'rut' => '12345678-9',
                                'business_name' => 'Mi Empresa SpA'
                ],
                'document_receiver' => [
                                'rut' => '98765432-1',
                                'business_name' => 'Cliente Importante Ltda'
                ],
                'details' => [
                                [
                                                                'item_name' => 'Servicio de Consultoría',
                                                                'quantity' => 1,
                                                                'unit_price' => 100000
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tupana.ai/v1/documents/batch"

	payload := strings.NewReader("{\n  \"documents\": [\n    {\n      \"dte_type\": {\n        \"code\": \"33\"\n      },\n      \"date_issued\": \"2024-01-15\",\n      \"document_issuer\": {\n        \"rut\": \"12345678-9\",\n        \"business_name\": \"Mi Empresa SpA\"\n      },\n      \"document_receiver\": {\n        \"rut\": \"98765432-1\",\n        \"business_name\": \"Cliente Importante Ltda\"\n      },\n      \"details\": [\n        {\n          \"item_name\": \"Servicio de Consultoría\",\n          \"quantity\": 1,\n          \"unit_price\": 100000\n        }\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tupana.ai/v1/documents/batch")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"documents\": [\n    {\n      \"dte_type\": {\n        \"code\": \"33\"\n      },\n      \"date_issued\": \"2024-01-15\",\n      \"document_issuer\": {\n        \"rut\": \"12345678-9\",\n        \"business_name\": \"Mi Empresa SpA\"\n      },\n      \"document_receiver\": {\n        \"rut\": \"98765432-1\",\n        \"business_name\": \"Cliente Importante Ltda\"\n      },\n      \"details\": [\n        {\n          \"item_name\": \"Servicio de Consultoría\",\n          \"quantity\": 1,\n          \"unit_price\": 100000\n        }\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tupana.ai/v1/documents/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"documents\": [\n    {\n      \"dte_type\": {\n        \"code\": \"33\"\n      },\n      \"date_issued\": \"2024-01-15\",\n      \"document_issuer\": {\n        \"rut\": \"12345678-9\",\n        \"business_name\": \"Mi Empresa SpA\"\n      },\n      \"document_receiver\": {\n        \"rut\": \"98765432-1\",\n        \"business_name\": \"Cliente Importante Ltda\"\n      },\n      \"details\": [\n        {\n          \"item_name\": \"Servicio de Consultoría\",\n          \"quantity\": 1,\n          \"unit_price\": 100000\n        }\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "created_at": "2024-01-15T10:30:00Z",
  "documents": [
    {
      "index": 0,
      "status": "created",
      "document": {
        "id": 12345,
        "folio": "1",
        "date_issued": "2024-01-15",
        "amount_with_iva": 119000,
        "receiver_id": 456,
        "is_draft": false,
        "can_be_issued": true,
        "dte_type": {
          "code": "33",
          "description": "Factura Electrónica"
        },
        "sender": {
          "id": 123,
          "name": "Mi Empresa SpA",
          "tax_id": "12345678-9"
        },
        "receiver": {
          "id": 456,
          "name": "Cliente Importante Ltda",
          "tax_id": "98765432-1"
        },
        "items": [
          {
            "item_name": "Servicio de Consultoría",
            "item_description": null,
            "quantity": 1,
            "unit_price": 100000,
            "unit": "UN",
            "item_code": null,
            "item_type_code": null,
            "discount_percent": null,
            "other_tax": null
          }
        ],
        "document_total": {
          "net_amount": 100000,
          "iva_rate": 19,
          "iva_amount": 19000,
          "total_amount": 119000
        },
        "pdf_url": "https://s3.amazonaws.com/bucket/documento_12345.pdf?signature=...",
        "pdf_download_url": "/api/master-entities/123/documents/12345/file/"
      }
    }
  ]
}

{
  "error": "Esta entidad no tiene credenciales SII válidas configuradas"
}

{
  "error": "VALIDATION_ERROR",
  "message": "<string>"
}

{
  "error": "VALIDATION_ERROR",
  "message": "<string>"
}

POST

documents

batch

Envío de documentos en lote

curl --request POST \
  --url https://api.tupana.ai/v1/documents/batch \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documents": [
    {
      "dte_type": {
        "code": "33"
      },
      "date_issued": "2024-01-15",
      "document_issuer": {
        "rut": "12345678-9",
        "business_name": "Mi Empresa SpA"
      },
      "document_receiver": {
        "rut": "98765432-1",
        "business_name": "Cliente Importante Ltda"
      },
      "details": [
        {
          "item_name": "Servicio de Consultoría",
          "quantity": 1,
          "unit_price": 100000
        }
      ]
    }
  ]
}
'

import requests

url = "https://api.tupana.ai/v1/documents/batch"

payload = { "documents": [
        {
            "dte_type": { "code": "33" },
            "date_issued": "2024-01-15",
            "document_issuer": {
                "rut": "12345678-9",
                "business_name": "Mi Empresa SpA"
            },
            "document_receiver": {
                "rut": "98765432-1",
                "business_name": "Cliente Importante Ltda"
            },
            "details": [
                {
                    "item_name": "Servicio de Consultoría",
                    "quantity": 1,
                    "unit_price": 100000
                }
            ]
        }
    ] }
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    documents: [
      {
        dte_type: {code: '33'},
        date_issued: '2024-01-15',
        document_issuer: {rut: '12345678-9', business_name: 'Mi Empresa SpA'},
        document_receiver: {rut: '98765432-1', business_name: 'Cliente Importante Ltda'},
        details: [{item_name: 'Servicio de Consultoría', quantity: 1, unit_price: 100000}]
      }
    ]
  })
};

fetch('https://api.tupana.ai/v1/documents/batch', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tupana.ai/v1/documents/batch",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'documents' => [
        [
                'dte_type' => [
                                'code' => '33'
                ],
                'date_issued' => '2024-01-15',
                'document_issuer' => [
                                'rut' => '12345678-9',
                                'business_name' => 'Mi Empresa SpA'
                ],
                'document_receiver' => [
                                'rut' => '98765432-1',
                                'business_name' => 'Cliente Importante Ltda'
                ],
                'details' => [
                                [
                                                                'item_name' => 'Servicio de Consultoría',
                                                                'quantity' => 1,
                                                                'unit_price' => 100000
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tupana.ai/v1/documents/batch"

	payload := strings.NewReader("{\n  \"documents\": [\n    {\n      \"dte_type\": {\n        \"code\": \"33\"\n      },\n      \"date_issued\": \"2024-01-15\",\n      \"document_issuer\": {\n        \"rut\": \"12345678-9\",\n        \"business_name\": \"Mi Empresa SpA\"\n      },\n      \"document_receiver\": {\n        \"rut\": \"98765432-1\",\n        \"business_name\": \"Cliente Importante Ltda\"\n      },\n      \"details\": [\n        {\n          \"item_name\": \"Servicio de Consultoría\",\n          \"quantity\": 1,\n          \"unit_price\": 100000\n        }\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tupana.ai/v1/documents/batch")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"documents\": [\n    {\n      \"dte_type\": {\n        \"code\": \"33\"\n      },\n      \"date_issued\": \"2024-01-15\",\n      \"document_issuer\": {\n        \"rut\": \"12345678-9\",\n        \"business_name\": \"Mi Empresa SpA\"\n      },\n      \"document_receiver\": {\n        \"rut\": \"98765432-1\",\n        \"business_name\": \"Cliente Importante Ltda\"\n      },\n      \"details\": [\n        {\n          \"item_name\": \"Servicio de Consultoría\",\n          \"quantity\": 1,\n          \"unit_price\": 100000\n        }\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tupana.ai/v1/documents/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"documents\": [\n    {\n      \"dte_type\": {\n        \"code\": \"33\"\n      },\n      \"date_issued\": \"2024-01-15\",\n      \"document_issuer\": {\n        \"rut\": \"12345678-9\",\n        \"business_name\": \"Mi Empresa SpA\"\n      },\n      \"document_receiver\": {\n        \"rut\": \"98765432-1\",\n        \"business_name\": \"Cliente Importante Ltda\"\n      },\n      \"details\": [\n        {\n          \"item_name\": \"Servicio de Consultoría\",\n          \"quantity\": 1,\n          \"unit_price\": 100000\n        }\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "created_at": "2024-01-15T10:30:00Z",
  "documents": [
    {
      "index": 0,
      "status": "created",
      "document": {
        "id": 12345,
        "folio": "1",
        "date_issued": "2024-01-15",
        "amount_with_iva": 119000,
        "receiver_id": 456,
        "is_draft": false,
        "can_be_issued": true,
        "dte_type": {
          "code": "33",
          "description": "Factura Electrónica"
        },
        "sender": {
          "id": 123,
          "name": "Mi Empresa SpA",
          "tax_id": "12345678-9"
        },
        "receiver": {
          "id": 456,
          "name": "Cliente Importante Ltda",
          "tax_id": "98765432-1"
        },
        "items": [
          {
            "item_name": "Servicio de Consultoría",
            "item_description": null,
            "quantity": 1,
            "unit_price": 100000,
            "unit": "UN",
            "item_code": null,
            "item_type_code": null,
            "discount_percent": null,
            "other_tax": null
          }
        ],
        "document_total": {
          "net_amount": 100000,
          "iva_rate": 19,
          "iva_amount": 19000,
          "total_amount": 119000
        },
        "pdf_url": "https://s3.amazonaws.com/bucket/documento_12345.pdf?signature=...",
        "pdf_download_url": "/api/master-entities/123/documents/12345/file/"
      }
    }
  ]
}

{
  "error": "Esta entidad no tiene credenciales SII válidas configuradas"
}

{
  "error": "VALIDATION_ERROR",
  "message": "<string>"
}

{
  "error": "VALIDATION_ERROR",
  "message": "<string>"
}

Crea hasta 200 documentos tributarios electrónicos en una sola llamada. La respuesta con el PDF y los detalles completos se entrega a través del webhook configurado.

Headers

Idempotency-Key (Opcional)

Tipo: String
Descripción: Header opcional que previene la creación de lotes duplicados
Restricciones: Máximo 256 caracteres, expira después de 24 horas
Ejemplo: "batch_2024_01_15_001"

X-Use-Defaults (Opcional)

⚠️ IMPORTANTE: Se recomienda encarecidamente usar el header X-Use-Defaults: true en todas tus solicitudes de emisión masiva de documentos. Este header simplifica significativamente la creación de documentos al hacer opcionales muchos campos y completar automáticamente los datos faltantes según tu configuración en Tupana.

Tipo: String
Valores permitidos: "true", "false"
Por defecto: "false"
Descripción: Si se establece como "true", el sistema usará valores por defecto para campos no proporcionados, reduciendo la complejidad y cantidad de datos que necesitas enviar

Campos que se vuelven opcionales o se completan automáticamente

A nivel del documento:

date_issued: Si no se proporciona, se usa la fecha actual (en zona horaria de Chile)
folio: Si no se proporciona, se genera automáticamente por el sistema
dte_type.code: Si no se proporciona, se usa "33" (Factura Electrónica) por defecto
header.payment_method: Si no se proporciona, se establece como "2" (crédito)

En document_issuer (solo con RUT): Con X-Use-Defaults: true, solo necesitas proporcionar el rut del emisor. El sistema completa automáticamente todos los demás campos desde tu configuración:

business_name: Razón social del emisor
business_activity: Giro o actividad económica
address: Dirección del emisor
district: Comuna
city: Ciudad
email: Email de contacto
phone_number: Teléfono
activity_code: Código de actividad económica

En document_receiver (solo con RUT): Con X-Use-Defaults: true, solo necesitas proporcionar el rut del receptor. El sistema completa automáticamente todos los demás campos desde la configuración del cliente o datos disponibles:

business_name: Razón social del receptor ✅ Opcional
contact: Contacto del receptor ✅ Opcional
business_activity: Giro o actividad económica ✅ Opcional (no se valida si está vacío)
address: Dirección del receptor ✅ Opcional (no se valida si está vacío)
district: Comuna ✅ Opcional (no se valida si está vacío)
city: Ciudad ✅ Opcional (no se valida si está vacío)

Request Body

documents (Obligatorio)

Tipo: Array
Descripción: Lista de documentos a crear en el lote
Restricciones: Máximo 200 documentos por lote

Estructura de cada documento

Campos base (aplican a todos los tipos de documentos)

dte_type (Obligatorio)

Tipo: Object
Campos:
- code (String): Código del tipo de documento

date_issued (Condicional)

Tipo: String (formato YYYY-MM-DD)
Descripción: Fecha de emisión del documento
Obligatorio: Sí, excepto si se usa X-Use-Defaults: true (usa fecha actual)

folio (Opcional)

Tipo: Integer
Descripción: Número de folio del documento
Comportamiento: Si no se proporciona, se genera automáticamente

Tipos de Documentos Soportados

Respuesta

Respuesta Inmediata de la API

201 - Documentos creados exitosamente

Tipo: Object
Campos:
- batch_id (String): Identificador único del lote
- status (String): Estado del procesamiento ("processing")
- total_documents (Integer): Número total de documentos en el lote
- message (String): Mensaje descriptivo del estado

413 - Límite excedido

Descripción: Más de 200 documentos en el array
Campos:
- error (String): Descripción del error
- code (String): Código de error

400 - Credenciales no activas

Descripción: La empresa emisora no tiene credenciales SII activas configuradas
Campos:
- error (String): Mensaje descriptivo indicando que no hay credenciales activas para el RUT especificado

422 - Error de validación

Descripción: Cuerpo malformado o fallo de validación
Campos:
- error (String): Descripción del error
- details (Array): Detalles específicos de los errores de validación

Respuesta del Webhook

Cuando un documento se emite exitosamente, Tupana envía un webhook con la siguiente estructura: event (Obligatorio)

Tipo: String
Valor: "document.issued"
Descripción: Tipo de evento del webhook

created_at (Obligatorio)

Tipo: String (ISO 8601)
Descripción: Timestamp de cuando se generó el webhook

data (Obligatorio)

Tipo: Object
Descripción: Datos completos del documento emitido

Campos del objeto data

Información básica del documento:

id (Integer): ID único del documento en Tupana
folio (String): Folio asignado por el SII
date_issued (String): Fecha de emisión (formato YYYY-MM-DD)
amount_with_iva (Number): Monto total con IVA incluido
is_sandbox (Boolean): Indica si es un documento de prueba

dte_type (Object):

code (String): Código del tipo de documento
description (String): Descripción del tipo de documento

sender (Object):

id (Integer): ID del emisor en Tupana
name (String): Nombre/razón social del emisor
tax_id (String): RUT del emisor (formato con puntos y guión)
email (String): Email del emisor

receiver (Object):

id (Integer): ID del receptor en Tupana
name (String): Nombre/razón social del receptor
tax_id (String): RUT del receptor (formato con puntos y guión)
email (String): Email del receptor

header (Object):

purchase_transaction_type (Integer): Tipo de transacción de compra
sale_transaction_type (Integer): Tipo de transacción de venta
payment_method (String): Método de pago
due_date (String): Fecha de vencimiento (formato YYYY-MM-DD)
retention_type (String): Tipo de retención (solo para boletas de honorarios)

document_issuer (Object):

rut (String): RUT del emisor
business_name (String): Razón social
business_activity (String): Giro o actividad económica
phone_number (String): Teléfono
email (String): Email
activity_code (Integer): Código de actividad económica
sii_branch_code (String): Código de sucursal SII
address (String): Dirección
district (String): Comuna
city (String): Ciudad

document_receiver (Object):

rut (String): RUT del receptor
business_name (String): Razón social
business_activity (String): Giro o actividad económica
contact (String): Contacto
address (String): Dirección
district (String): Comuna
city (String): Ciudad

document_total (Object):

net_amount (Number): Monto neto (sin IVA)
iva_rate (Number): Tasa de IVA aplicada
iva_amount (Number): Monto del IVA
total_amount (Number): Monto total

details (Array): Lista de productos/servicios del documento. Cada elemento contiene:

item_name (String): Nombre del producto/servicio
item_description (String): Descripción del producto/servicio
quantity (Number): Cantidad
unit_price (Number): Precio unitario neto, sin IVA. Si el documento se emitió en bruto (boletas 39/41 con gross_unit_price), este campo refleja el monto bruto de la línea — gross_unit_price es solo de entrada y no se retorna en la respuesta.
item_code (String): Código del producto/servicio
item_type_code (String): Código del tipo de ítem
unit (String): Unidad de medida
discount_percent (Number): Porcentaje de descuento
other_tax (Number): Otros impuestos

references (Array): Referencias a otros documentos (solo para notas de crédito). Cada elemento contiene:

dte_type_code (String): Código del tipo de DTE de referencia
reference_folio (String): Folio del documento referenciado
reference_date (String): Fecha del documento referenciado
reference_reason (String): Razón de la referencia

Archivos generados:

pdf_file (String): URL temporal para descargar el PDF del documento
xml_file (String): URL temporal para descargar el XML del documento

json_param (Object):

Descripción: Campos personalizados adicionales que se pueden incluir en el documento
Estructura: Objeto flexible que puede contener cualquier información adicional

Consideraciones Especiales por Tipo de Documento

Ejemplos de Uso por Tipo de Documento

Factura Electrónica (DTE 33)

{
  "documents": [
    {
      "dte_type": {
        "code": "33"
      },
      "date_issued": "2024-01-15",
      "document_issuer": {
        "rut": "12345678-9",
        "business_name": "Mi Empresa SpA"
      },
      "document_receiver": {
        "rut": "98765432-1",
        "business_name": "Cliente Importante Ltda"
      },
      "details": [
        {
          "item_name": "Servicio de Consultoría",
          "quantity": 1,
          "unit_price": 100000
        }
      ]
    }
  ]
}

Factura de Compra (DTE 46)

{
  "documents": [
    {
      "dte_type": {
        "code": "46"
      },
      "date_issued": "2024-01-15",
      "document_issuer": {
        "rut": "98765432-1",
        "business_name": "Proveedor SpA"
      },
      "document_receiver": {
        "rut": "12345678-9",
        "business_name": "Mi Empresa SpA"
      },
      "header": {
        "purchase_transaction_type": 1,
        "payment_method": "2"
      },
      "details": [
        {
          "item_name": "Equipo de Oficina",
          "quantity": 2,
          "unit_price": 50000
        }
      ]
    }
  ]
}

Factura de Exportación (DTE 110)

{
  "documents": [
    {
      "dte_type": {
        "code": "110"
      },
      "date_issued": "2024-01-15",
      "document_issuer": {
        "rut": "12345678-9",
        "business_name": "Exportadora SpA"
      },
      "document_receiver": {
        "rut": "99999999-9",
        "business_name": "Importador Internacional Inc",
        "address": "123 Main Street",
        "city": "New York",
        "country": "USA"
      },
      "header": {
        "sale_transaction_type": 1,
        "currency": "USD"
      },
      "export_data": {
        "transport_mode": "2",
        "destination_country": "US",
        "destination_port": "JFK",
        "origin_port": "SCL",
        "sale_mode_code": "1"
      },
      "details": [
        {
          "item_name": "Producto Exportado",
          "quantity": 100,
          "unit_price": 50
        }
      ]
    }
  ]
}

Nota de Crédito (DTE 61)

{
  "documents": [
    {
      "dte_type": {
        "code": "61"
      },
      "date_issued": "2024-01-16",
      "document_issuer": {
        "rut": "12345678-9",
        "business_name": "Mi Empresa SpA"
      },
      "document_receiver": {
        "rut": "98765432-1",
        "business_name": "Cliente Importante Ltda"
      },
      "references": [
        {
          "dte_type_code": "33",
          "reference_folio": 12345,
          "reference_date": "2024-01-15",
          "reference_reason": "Corrección de precio"
        }
      ],
      "details": [
        {
          "item_name": "Ajuste por Corrección",
          "quantity": -1,
          "unit_price": 5000
        }
      ]
    }
  ]
}

Boleta de Honorarios por usuario autorizado (DTE 80)

El emisor de la boleta es document_issuer.rut, pero la emite un usuario autorizado por el SII (dueño de una credencial sii_company). header.authorized_user_rut indica cuál credencial usar cuando hay varias accesibles.

{
  "documents": [
    {
      "dte_type": {
        "code": "80"
      },
      "document_issuer": {
        "rut": "76543210-3"
      },
      "document_receiver": {
        "rut": "12345678-9"
      },
      "header": {
        "retention_type": "RETRECEPTOR",
        "authorized_user_rut": "19615893-6"
      },
      "details": [
        {
          "item_name": "Asesoría profesional",
          "quantity": 1,
          "unit_price": 50000
        }
      ]
    }
  ]
}

Boleta de Honorarios de Terceros (DTE 90)

Ejemplo mínimo con header X-Use-Defaults: true: con solo RUT en emisor y receptor el backend completa business_name y el resto si existen en Tupana; usa fecha actual si se omite date_issued.

{
  "documents": [
    {
      "dte_type": {
        "code": "90"
      },
      "document_issuer": {
        "rut": "76543210-3"
      },
      "document_receiver": {
        "rut": "12345678-9"
      },
      "header": {
        "retention_type": "RETRECEPTOR"
      },
      "details": [
        {
          "item_name": "Servicio de reparto de pedidos",
          "quantity": 1,
          "unit_price": 15000
        }
      ]
    }
  ]
}

🧾 Factura de Compra (DTE 46)

Campos específicos del header:

purchase_transaction_type (Integer, Obligatorio):
- 1: Compras del giro - Productos/servicios relacionados con tu actividad principal
- 2: Compras fuera del giro - Productos/servicios no relacionados con tu actividad principal
- 3: Activo fijo - Bienes que se incorporan al patrimonio de la empresa (maquinaria, muebles, etc.)
payment_method (String, Opcional):
- "1": Contado - Pago inmediato
- "2": Crédito - Pago diferido
- "3": Sin costo - Producto/servicio recibido gratuitamente

Validaciones importantes:

Registro contable: Este documento genera asiento automático en tu contabilidad
IVA recuperable: El IVA pagado puede ser recuperado según el tipo de compra
Proveedor extranjero: Si el proveedor es extranjero, usar RUT genérico 55555555-5
Fecha límite: Las compras deben registrarse dentro del mes siguiente a la recepción

Casos de uso comunes:

Registro de compras a proveedores locales
Incorporación de activos fijos
Servicios profesionales recibidos
Compras de materias primas o insumos

✈️ Factura de Exportación (DTE 110)

Campos requeridos en export_data:

transport_mode (String, Obligatorio):
- "1": Marítimo - Envío por barco
- "2": Aéreo - Envío por avión
- "3": Terrestre - Envío por tierra (camión, tren)
- "4": Multimodal - Combinación de modos de transporte
destination_country (String, Obligatorio):
- No es código ISO 3166-1. Es el código de país del SII (ej: "225" = U.S.A., "220" = Brasil, "224" = Argentina). Ver Países de exportación para la tabla completa.
- Debe coincidir con el país del receptor
destination_port (String, Obligatorio):
- Nombre del puerto/aeropuerto/ciudad de destino
- Ejemplos: "JFK", "Santos", "Buenos Aires"
origin_port (String, Obligatorio):
- Nombre del puerto/aeropuerto/ciudad de origen en Chile
- Ejemplos: "SCL", "IQQ", "ANF"
sale_mode_code (String, Obligatorio):
- Código de modalidad de venta del SII (no una cláusula Incoterm). Ver Modalidades de venta de exportación para la tabla completa.

Campos específicos del header:

sale_transaction_type (Integer, Obligatorio):
- 1: Operación constituye venta - Venta normal
- 2: Ventas por acto o contrato - Contratos especiales
- 3: Boleto de pasaje - Para agencias de viajes
currency (String, Obligatorio):
- "USD": Dólares americanos
- "EUR": Euros
- "CLP": Pesos chilenos
- "UF": Unidades de Fomento

Información del receptor extranjero:

RUT: Puede usar identificadores especiales como 99999999-9 para extranjeros
Dirección: Dirección completa en el extranjero
País: País de destino (debe coincidir con destination_country)

Precios y cálculos:

FOB (Free on Board): Los precios deben incluir costos hasta la entrega al transportista
Moneda: Debe coincidir con header.currency
Sin IVA: Las exportaciones están exentas de IVA chileno

Requisitos legales:

Registro de exportación: Debe estar registrado en el sistema aduanero
Certificado de origen: Puede requerirse según acuerdos comerciales
Documentos aduaneros: Factura comercial, certificado de origen, etc.

💼 Boletas de Honorarios (DTE 80, 90)

Campos específicos del header:

retention_type (String, Obligatorio):
- "RETRECEPTOR": La retención la realiza el receptor (99% de los casos)
- "RETCONTRIBUYENTE": La retención la realiza el contribuyente emisor (casos excepcionales)
authorized_user_rut (String, Opcional): RUT del usuario autorizado por el SII (dueño de la credencial sii_company) que emite en representación del emisor. Selecciona determinísticamente la credencial cuando hay varias accesibles. Solo válido para DTE 80 y 90.

Retención automática del 14.5%:

Cálculo: Se aplica sobre el monto bruto antes de IVA
Responsable: Normalmente el pagador retiene y declara el impuesto
Pago al profesional: Se paga el 85.5% restante (bruto menos retención)

Información del receptor (profesional):

Campos opcionales: A diferencia de facturas, no todos los datos son obligatorios
RUT obligatorio: Siempre se requiere el RUT del profesional
Actividad económica: Debe corresponder a servicios profesionales

Diferencias entre DTE 80 y 90:

DTE 80 - Boleta de Honorarios:

Emisión directa por el pagador al profesional
Relación directa pagador-profesional
document_issuer: Quien paga (empresa o persona que contrata)

DTE 90 - Boleta de Honorarios de Terceros:

Emisión por intermediario (plataformas, marketplaces)
document_issuer: Contribuyente real (quien paga — restaurante, empresa cliente)
document_receiver: Profesional que recibe (repartidor, freelancer, instructor)
Requiere enrolamiento de usuarios autorizados para emisión por terceros
Misma estructura de request que DTE 80; solo cambia dte_type.code: "90"

Validaciones específicas:

Tope mensual: Límite de emisión sin retención ampliada
Tipo de servicio: Debe corresponder a honorarios profesionales
Declaración: El retenedor debe declarar y pagar el impuesto retenido

Casos de uso:

DTE 80: Honorarios de abogados, contadores, médicos; servicios de consultoría; pagos directos a freelancers
DTE 90: Apps de delivery (Rappi, Uber Eats); plataformas freelance; marketplaces de servicios; plataformas educativas

🔒 Seguridad y URLs temporales

URLs de archivos temporales:

PDF y XML: URLs válidas por 1 hora aproximadamente
Autenticación: Incluyen tokens de acceso automático
Recomendación: Descargar inmediatamente al recibir el webhook

Medidas de seguridad:

Encriptación: Archivos transmitidos de forma segura
Validación: Solo el emisor puede acceder a sus documentos
Auditoría: Todas las descargas quedan registradas

Authorizations

Authorization

string

header

required

API Key para autenticación. Debe proporcionarse en el header Authorization con el formato: 'Api-Key YOUR-API-KEY' (incluye el prefijo 'Api-Key ' seguido de tu API key)

Headers

Idempotency-Key

string

Previene lotes duplicados (≤ 256 caracteres, expira después de 24 h)

X-Use-Defaults

boolean

default:false

Si se establece como true, el sistema usará valores por defecto para campos no proporcionados:

Fecha actual para date_issued
Datos del emisor según configuración de la plataforma o primera actividad/dirección disponible
Datos del receptor según configuración del cliente o primera actividad/dirección disponible
Payment method = '2' (crédito) en el header del documento

Body

application/json

Lote de documentos a crear

documents

object[]

required

Array de documentos a crear (máximo 200)

Show child attributes

Response

Solicitud de creación de documentos aceptada. Los resultados se enviarán por webhook.

batch_id

string<uuid>

Identificador único del lote

status

enum<string>

Estado del batch

Available options:

created,

processing,

completed,

failed

Example:

"processing"

created_at

string<date-time>

Fecha y hora de creación del batch

documents

object[]

Array de documentos procesados en el batch

Show child attributes

​Headers

​Idempotency-Key (Opcional)

​X-Use-Defaults (Opcional)

​Campos que se vuelven opcionales o se completan automáticamente

​Request Body

​documents (Obligatorio)

​Estructura de cada documento

​Campos base (aplican a todos los tipos de documentos)

​Tipos de Documentos Soportados

​Respuesta

​Respuesta Inmediata de la API

​201 - Documentos creados exitosamente

​413 - Límite excedido

​400 - Credenciales no activas

​422 - Error de validación

​Respuesta del Webhook

​Campos del objeto data

​Consideraciones Especiales por Tipo de Documento

​Ejemplos de Uso por Tipo de Documento

​Factura Electrónica (DTE 33)

​Factura de Compra (DTE 46)

​Factura de Exportación (DTE 110)

​Nota de Crédito (DTE 61)

​Boleta de Honorarios por usuario autorizado (DTE 80)

​Boleta de Honorarios de Terceros (DTE 90)

​🧾 Factura de Compra (DTE 46)

​Campos específicos del header:

​Validaciones importantes:

​Casos de uso comunes:

​✈️ Factura de Exportación (DTE 110)

​Campos requeridos en export_data:

​Campos específicos del header:

​Información del receptor extranjero:

​Precios y cálculos:

​Requisitos legales:

​💼 Boletas de Honorarios (DTE 80, 90)

​Campos específicos del header:

​Retención automática del 14.5%:

​Información del receptor (profesional):

​Diferencias entre DTE 80 y 90:

​Validaciones específicas:

​Casos de uso:

​🔒 Seguridad y URLs temporales

​URLs de archivos temporales:

​Medidas de seguridad:

Authorizations

Headers

Body

Response

Headers

Idempotency-Key (Opcional)

X-Use-Defaults (Opcional)

Campos que se vuelven opcionales o se completan automáticamente

Request Body

documents (Obligatorio)

Estructura de cada documento

Campos base (aplican a todos los tipos de documentos)

Tipos de Documentos Soportados

Respuesta

Respuesta Inmediata de la API

201 - Documentos creados exitosamente

413 - Límite excedido

400 - Credenciales no activas

422 - Error de validación

Respuesta del Webhook

Campos del objeto data

Consideraciones Especiales por Tipo de Documento

Ejemplos de Uso por Tipo de Documento

Factura Electrónica (DTE 33)

Factura de Compra (DTE 46)

Factura de Exportación (DTE 110)

Nota de Crédito (DTE 61)

Boleta de Honorarios por usuario autorizado (DTE 80)

Boleta de Honorarios de Terceros (DTE 90)

🧾 Factura de Compra (DTE 46)

Campos específicos del header:

Validaciones importantes:

Casos de uso comunes:

✈️ Factura de Exportación (DTE 110)

Campos requeridos en export_data:

Campos específicos del header:

Información del receptor extranjero:

Precios y cálculos:

Requisitos legales:

💼 Boletas de Honorarios (DTE 80, 90)

Campos específicos del header:

Retención automática del 14.5%:

Información del receptor (profesional):

Diferencias entre DTE 80 y 90:

Validaciones específicas:

Casos de uso:

🔒 Seguridad y URLs temporales

URLs de archivos temporales:

Medidas de seguridad: