Saltar a contenido

Primeros pasos con la API

Todo lo que necesitas para hacer tu primer request: autenticación, convenciones del API y los errores típicos del arranque. Audiencia: desarrolladores que integran un sistema externo (e-commerce, facturador, marketplace) con OpenTPV.

URL base y autenticación

Todas las llamadas van contra la URL base de la API con el token de empresa:

https://api.opentpv.cl
Authorization: Bearer <token de empresa>

El token identifica a la empresa (cada cliente OpenTPV tiene su propia base de datos; el token resuelve cuál). Lo entrega el equipo OpenTPV al habilitar la integración. También se aceptan los headers legacy rut + X-Company-Token en integraciones antiguas; para integraciones nuevas usa siempre Bearer.

Sin token, o con token inválido → 401.

Tu primer request

Listar la configuración por tipo de documento es una llamada segura de solo lectura, ideal para probar la conexión:

curl https://api.opentpv.cl/api/OpcionesGenerales/documentos \
  -H "Authorization: Bearer eyJhbGciOi..."

Si recibes un arreglo JSON con documentos (TPV, E-FACTURA, TICKET, NOTA_VENTA…), la autenticación quedó funcionando.

Conceptos que hay que conocer antes de emitir

Tipos de documento (códigos DTE del SII)

Código Documento
39 Boleta electrónica
41 Boleta exenta electrónica
33 Factura electrónica
34 Factura exenta electrónica
52 Guía de despacho electrónica
61 Nota de crédito electrónica
56 Nota de débito electrónica

Además existen documentos no tributarios internos: ticket, cotización y nota de venta (el "pedido"; ver Pedidos con nota de venta).

Folios CAF y terminal

Cada DTE lleva un folio timbrado por el SII (CAF), asignado por caja. En casi todos los endpoints de emisión indicas codigoTerminal y la API asigna el siguiente folio disponible de esa caja; solo pasas folio explícito si tu sistema administra los CAF por su cuenta. Si la caja no tiene folios cargados, recibirás el error Sin FOLIOS.

Inventario: la API no descuenta stock por defecto

Emitir documentos por API no mueve inventario salvo que la empresa active la opción apiDescuentaInventario (ERP → Opciones → E-Commerce). Es deliberado: las integraciones históricas emitían sin tocar stock. Si tu integración necesita que el stock baje al emitir, coordina la activación con la empresa, y considera el sistema de reservas si además vendes online con stock compartido.

Convenciones legacy

  • Varios campos booleanos viajan como strings "1" / "0" (el backend es compartido con el ERP de escritorio). La referencia indica cuáles.
  • Fechas en formato ISO yyyy-MM-dd o yyyy-MM-ddTHH:mm:ss.
  • Montos en pesos chilenos, sin decimales para totales de DTE.

Errores comunes del arranque

Síntoma Causa típica
401 Token ausente/expirado, o header mal formado (falta Bearer).
400 Sin FOLIOS La caja indicada en codigoTerminal no tiene folios CAF cargados para ese tipo de DTE.
400 Tipo de DTE no admitido Código fuera de la lista soportada por el endpoint.
Emite pero "no descuenta stock" Ver arriba: apiDescuentaInventario está apagado (el default).

Dónde seguir