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 https://api.opentpv.cl. Cada cliente OpenTPV tiene su propia base de datos, y la autenticación es lo que le dice a la API de qué empresa se trata. Hay dos formas de identificarse:

Sesión de usuario Token fijo de empresa
Qué envías Authorization: Bearer <token de sesión> Headers rut y token
Cómo se obtiene Iniciando sesión con un usuario del ERP (abajo) Lo entrega el equipo OpenTPV al habilitar la integración
Cuánto dura 1 hora; se renueva sin volver a iniciar sesión No vence
A nombre de quién queda lo que haces Del usuario que inició sesión De API, sin una persona detrás
Dónde sirve En toda la API En casi toda la API. Algunos módulos, como la recepción de mercadería, exigen sesión de usuario

Los ejemplos de estas guías usan Authorization: Bearer. Con el token fijo, reemplaza ese header por estos dos:

rut: 76543210-K
token: <token fijo de la empresa>

Iniciar sesión

curl -X POST https://api.opentpv.cl/usuarios/login \
  -H "Content-Type: application/json" \
  -d '{ "rut": "76543210-K", "nombreUsuario": "integracion", "clave": "********",
        "tipoAplicacion": "API" }'

{
  "exitoso": true,
  "token": "eyJhbGciOi...",
  "refreshToken": "rt_8f7e6d5c...",
  "usuario": { "idUsuario": 12, "nombreUsuario": "integracion" }
}

token es el que va en Authorization: Bearer. Dura 1 hora. Antes de que venza, pide uno nuevo con el refreshToken, sin enviar de nuevo la clave:

curl -X POST https://api.opentpv.cl/usuarios/refresh \
  -H "Content-Type: application/json" \
  -d '{ "token": "eyJhbGciOi...", "refreshToken": "rt_8f7e6d5c..." }'

La respuesta trae un token y un refreshToken nuevos. Cada refreshToken sirve una sola vez y dura 2 horas: si pasa ese tiempo sin renovar, hay que iniciar sesión otra vez. La sesión también deja de renovarse si a ese usuario le cambian la clave, lo eliminan, o si la empresa queda suspendida.

La forma más simple y robusta de manejarlo: si un llamado responde 401, inicia sesión de nuevo y repite el llamado. Eso cubre el vencimiento normal y también el caso en que la renovación falla, por ejemplo después de una actualización de la API. Un sistema que trabaja por lotes (una vez al día, por ejemplo) puede simplemente iniciar sesión al comenzar cada lote.

Usa un usuario propio para la integración

Pídele a la empresa que cree en el ERP un usuario solo para tu sistema (por ejemplo TIENDA-WEB). Todo lo que haga la integración quedará a su nombre en los registros del ERP, y se distingue de lo que hacen las personas.

Sin credenciales, o con credenciales inválidas → 401.

Ambiente de pruebas

No hay un ambiente de pruebas público. Se habilita uno para cada integrador que lo pide: escribe a soporte@opentpv.cl contando qué vas a integrar (tienda online, facturador, tótem, otro) y recibirás los datos de acceso de una empresa de prueba.

Haz ahí todas tus pruebas. Los documentos que emitas contra una empresa real son documentos tributarios válidos ante el SII y solo se revierten con nota de crédito.

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