El presente manual tiene como objetivo dar a conocer el medio de integración desde una aplicación que soporte conexión mediante una API REST, con el servicio que ofrece la emisión y consulta de Documentos Tributarios Electrónicos (DTE) a través de Facturación.cl.

Para realizar la integración entre aplicaciones, se utiliza una API basada en el estilo REST, en la que las solicitudes y respuestas se intercambian en formato JSON sobre el protocolo HTTP.

Una API REST permite que distintos programas, desarrollados en diferentes lenguajes de programación y ejecutándose en diversas plataformas, puedan interactuar entre sí mediante solicitudes HTTP estándar (GET, POST) e intercambio de datos en formato JSON.

Al estar basada en estándares abiertos (HTTP y JSON), existen múltiples clientes y librerías disponibles para la mayoría de las plataformas y lenguajes de programación que permiten hacer uso de la API, sin requerir herramientas especializadas.

A continuación, se presenta un listado de algunas de las herramientas y librerías que permiten realizar la integración con el servicio:

Para acceder a la API REST debe utilizar como base la URL rest.facturacion.cl, seguida del recurso correspondiente:

 
https://rest.facturacion.cl/login
https://rest.facturacion.cl/wsds/procesar
https://rest.facturacion.cl/wsds/obtenerlink
https://rest.facturacion.cl/wsds/obtenerpdf
https://rest.facturacion.cl/wsds/getticket
https://rest.facturacion.cl/wsds/version
        

- El primer paso consiste en construir el archivo de Integración, el cual será necesario para la emisión y generación de los Documentos Tributarios Electrónicos.

Actualmente se dispone de dos formatos, para los cuales existe documentación respectiva a fin de crearlos basados en ciertas estructuras de información:

• Archivos de Texto Plano (TXT)
• Archivos en estándar XML

Estos archivos deberán contener la información del documento a generar (Factura Electrónica, Guía de Despacho Electrónica, Nota de Crédito Electrónica, Nota de Débito Electrónica, etc.). Para más información respecto de los formatos de dichos archivos, se pueden consultar los manuales correspondientes de Facturación.cl.

- El segundo paso consiste en enviar dicho archivo al endpoint /wsds/procesar de la API, previa autenticación.

- El tercer paso y final consiste en obtener la representación impresa del documento tributario ya generado, en formato PDF o en los datos requeridos para impresión térmica.

La información sensible o binaria debe ser enviada de manera codificada utilizando el formato de codificación Base64, el cual es un estándar disponible en múltiples lenguajes de programación.

En los casos en que se indique Codificado, tanto en los datos enviados como en los recibidos, se debe utilizar dicho algoritmo.

Para hacer uso del servicio, es necesario autenticarse mediante el endpoint POST /login, indicando las credenciales de acceso entregadas al inicio del proceso de integración, las que variarán dependiendo si se está en ambiente de pruebas o producción.

Como resultado de una autenticación exitosa, se obtiene un token de acceso que debe incluirse en cada petición posterior a los métodos protegidos, dentro de la cabecera Authorization.

POST /login
Content-Type: application/json
{
"usuario": "desisws",
"rut": "11111111-1",
"clave": "123456xx"
}

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....."
}

Uso del token

El token debe incluirse en cada petición a los métodos protegidos, con el siguiente formato de cabecera:

Authorization: <token>

Nota:

El token tiene una vigencia de 24 horas. Transcurrido ese plazo, se debe solicitar uno nuevo mediante /login.

La API posee varios métodos (endpoints) los cuales es posible consumir mediante cualquier cliente HTTP, por lo que se entrega a continuación una breve descripción de los que se utilizarán en la integración.

En el siguiente ejemplo, se muestra la manera de autenticarse y procesar el archivo de integración utilizando cURL desde la línea de comandos.

El método /wsds/procesar retorna como respuesta un JSON con la información del resultado del o los documentos procesados.

{
    "WSPLANO": {
        "Resultado": "True",
        "Mensaje": "Proceso exitoso.",
        "Detalle": {
            "Documento": {
                "Folio": "126",
                "TipoDte": "33",
                "Operacion": "VENTA",
                "Fecha": "2008-09-12T15:55:09",
                "Resultado": "True",
                "urlOriginal": "<base64>",
                "urlCedible": "<base64>"
            }
        }
    }
}

{
    "WSPLANO": {
        "Resultado": "True",
        "Mensaje": "Proceso exitoso.",
        "Detalle": {
            "Documento": {
                "Folio": "126",
                "TipoDte": "33",
                "Operacion": "VENTA",
                "Fecha": "2008-09-12T15:55:09",
                "Resultado": "False",
                "Error": "ERROR: Ya existe el Documento del TipoDTE = 33 con Folio = 126"
            }
        }
    }
}

Al consumir el método /wsds/obtenerlink, se retornará como respuesta un JSON que contendrá el link de descarga del documento electrónico en formato PDF, codificado en Base64, por lo cual deberá ser decodificado.

{
    "WSPLANO": {
        "Mensaje": "aHR0cDovL3d3dy5kb21pbmlvLmNvbS9zaXN0ZW1hL2Rlc2Nhcmdhci5waHA/cDE9YzI1YzBmYzllYiZwMj1HREkmbT1WJmk9JmM9ZmFsc2U="
    }
}

Una vez decodificado, se obtendrá un link similar al siguiente:

https://www.facturacion.cl/sistema/descargar.php?p1=c25c0fc9eb&p2=GDI&m=V&i&c=false

Desde dicho link, el cliente podrá descargar el archivo PDF del documento electrónico.

Al consumir el método /wsds/version, puede verificar que el servicio se encuentra disponible.

Ejemplo de resultado Versión:

{ "version": "x.x.x.x" }

Consiste en un formato ticket de documento electrónico, desarrollado sin incluir logotipo, siendo la mejor alternativa en velocidad y bajo consumo de insumos de impresión, el cual requiere de una impresora térmica con capacidades gráficas con cabezal de entre 3 y 4 pulgadas.

Para acceder a este formato, la empresa debe contar con los módulos de ticket térmico (FETICKET y BETICKET) correspondientes a factura y boleta térmica contratados en Facturación.cl.

Con la impresión térmica puede integrar y controlar el proceso de impresión enviando los datos directamente a una impresora compatible con el lenguaje de impresión POS/ESC, consumiendo el método /wsds/getticket, indicando el folio y tipo de documento de la boleta o factura que desea imprimir.

Ej: Boleta Electrónica Afecta, Folio 100 ? parámetros tipo=39, folio=100.

Al ejecutar la llamada, retornará un JSON con los datos del ticket a imprimir de la siguiente forma:

{
    "WSPLANO": {
        "Head": "GyEBHSEBUkFaT04gU09DSUFMIFB08gUy....",
        "Foot": "DQpUSU1CUkUgRUxFQ1RST05JQ08gUy5J...",
        "TED": "PFRFRCB2ZXJzaW9uPSIxLjAiPjxERD48U..."
    }
}

Las tres variables retornadas (Head, Foot y TED) contienen su data codificada en Base64. Tras ser decodificadas, cada una contiene la siguiente información:

Las siguientes modalidades de impresión, provistas por Facturación.cl, permiten incorporar la impresión de ticket utilizando un componente preconstruido, minimizando el desarrollo a realizar por el consumidor de la API.

Debe consumir el endpoint /wsds/getticket y obtener los datos de la boleta. Luego, desde su aplicación, realice una llamada por línea de comando a la librería de impresión provista por Facturación.cl, pasando como parámetros el nombre de la impresora local y las variables Head, Foot y TED tal como se reciben en la respuesta, sin decodificar.

Si su aplicación es una página web y desea incorporar la impresión térmica en ella, debe realizarlo mediante la llamada a una página que incrustará en su sitio el componente de impresión provisto por Facturación.cl, indicando los siguientes parámetros:

La forma recomendada de incorporar este componente es mediante un iframe cuyo src se asocia dinámicamente a la URL del componente de impresión.