El presente manual tiene como objetivo dar a conocer el medio de integración desde una aplicación que soporte conexión mediante Servicio Web, con el sistema de Facturación.cl que ofrece la emisión y resguardo de sus Documentos Tributarios Electrónicos.
Para realizar la integración entre aplicaciones, utilizaremos la tecnología conocida como Servicio Web SOAP a fin de acceder a las funcionalidades ofrecidas por nuestra plataforma.
Un servicio Web es un conjunto de protocolos o estándares que permiten intercambiar los datos entre aplicaciones de software, permitiendo que distintos programas, hechos en diferentes lenguajes de programación y ejecutándose en diversas plataformas, puedan interactuar entre sí.
Para la comunicación de datos mediante Servicios Web, éstos utilizan estándares y protocolos globales. Siendo muchos de estos libres, incrementando así la popularidad de SOAP.
El protocolo SOAP permite la comunicación de dos objetos mediante el intercambio de archivos XML.
Gracias a que la tecnología de Servicio Web SOAP está basada en estándares abiertos y regidos por la W3C. Existen diversos clientes disponibles para la mayoría de las plataformas y lenguajes de programación mediante API's que permiten hacer uso de servicios web, dejando a disposición del programador múltiples librerías que permiten el acceso a nuestros servicios.
A continuación, se presenta un listado de solamente algunos de los clientes y librerías existentes que permiten realizar la comunicación con nuestro WebServices
| Plataforma | Lenguaje | Nombre | URL |
|---|---|---|---|
| Multiplataforma | PHP | NuSOAP | http://nusoap.sourceforge.net/ |
| Multiplataforma | PHP 5 | SOAP API | http://cl.php.net/soap |
| Multiplataforma | Java | WS ToolKit | http://java.net/projects/metro |
| Multiplataforma | Perl | SOAP Lite | http://www.soaplite.com/ |
| Microsoft Windows | C#, J#, VB.Net | System.Net | http://msdn.microsoft.com/en-us/library/ms997641.aspx |
| Microsoft Windows | C++ | SOAP ToolKit | http://msdn.microsoft.com/en-us/library/aa286526.aspx |
| Microsoft Windows | Microsoft Office | Office Web Services ToolKit | http://www.microsoft.com/es-es/download/details.aspx?id=2224 |
El primero paso consiste en enviar los parámetros definidos a nuestro Servicio Web, valiéndose de un cliente SOAP permitido por su aplicación, los cuales serán necesarios para obtener la información de los DTE del libro de compra.
Este servicio le permitirá visualizar y dar acuse comercial a los documentos registrados en su Panel DTE Recibidos
Para acceder al WebService tanto en ambiente de pruebas como producción debe utilizar la siguiente URL: http://ws.facturacion.cl/WSDS/wspaneldte.asmx?wsdl
La información 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 recibidos se debe utilizar dicho algoritmo.
Para hacer uso del servicio, es necesario al momento de invocar o consumir el método, indicar la información de autenticación que será proporcionada por nuestra empresa.
Esta información de autenticación es transmitida en una variable de tipo objeto, que contiene la siguiente estructura con los datos de autenticación
| Clase: logininfo | |||
|---|---|---|---|
| Campo | Descripción | Codificado | Obligatorio |
| Usuario | Corresponde al nombre del usuario. | SI | SI |
| Rut | Corresponde al RUT de su empresa. | SI | SI |
| Clave | Es la clave asignada a su empresa. | SI | SI |
El Servicio Web posee varios métodos los cuales es posible consumir mediante cualquier cliente SOAP, por lo que se entrega una breve descripción de los que utilizarán en la integración.
| Método: | Acuse | ||
|---|---|---|---|
| Descripción: | |||
| Permite dar acuse o rechazo a un documento ubicado en el Panel DTE Recibidos. | |||
| Parámetro | Descripción | Codificado | |
| login | Estructura con datos de autenticación del cliente. | - | |
| Folio | Corresponde al número de Folio del Documento. | - | |
| Tipo | Corresponde al Tipo de Documento (Tipo DTE). | - | |
| Rut Proveedor | Corresponde al RUT de la empresa emisora del DTE . | - | |
| Acción | Da el acuse del documento en panel DTE Recibos. a = Aceptar / r = Rechazar | - | |
| Respuesta: | |||
| Retorna un mensaje de éxito o error según corresponda. Dependiendo si se rechazó o acepto el documento. | |||
| Método: | ConsultaPanelDte | ||
|---|---|---|---|
| Descripción: | |||
| Permite consultar los documentos de compras que están pendientes de acuse en el Panel DTE Recibidos. | |||
| Parámetro | Descripción | Codificado | |
| login | Estructura con datos de autenticación del cliente. | - | |
| Folio | Corresponde al número de Folio del Documento. | - | |
| Tipo | Corresponde al Tipo de Documento (Tipo DTE). | - | |
| Rut Proveedor | Corresponde al RUT de la empresa emisora del DTE . | - | |
| Respuesta: | |||
| Retorna las características del documento: Folio, TipoDTE, Rut Proveedor, Fecha Recepción SII, Monto Total y si viene con XML. | |||
En caso de no enviar los parámetros de Folio, Tipo y Rut proveedor retornará todos los documentos de compra ubicados en el Panel DTE Recibidos.
| Método: | ObtenerPanelDte | ||
|---|---|---|---|
| Descripción: | |||
| Permite obtener el XML del documento consultado del Panel DTE Recibidos. | |||
| Parámetro | Descripción | Codificado | Obligatorio |
| login | Estructura con datos de autenticación del cliente. | - | - |
| Rut Emisor | Corresponde al RUT de la empresa emisora del DTE. | NO | SI |
| Folio | Corresponde al número de Folio del Documento. | NO | SI |
| Tipo | Corresponde al Tipo de Documento (Tipo DTE). | NO | SI |
| Respuesta: | |||
|
Como respuesta retorna el archivo XML
|
|||
En el siguiente ejemplo, veremos la manera de procesar el archivo de integración, utilizando PHP4 y valiéndonos de la librería NuSoap.
|
<?php
require_once('lib/nusoap.php');
/* Ruta de acceso al servicio web */
$wsdl = 'http://ws.facturacion.cl/WSDS/wsplano.asmx?wsdl';
/* Creamos una instancia del cliente SOAP */
$client = new soapclient($wsdl,true);
$client->setUseCurl(0);
$err = $client->getError();
if ($err) {
echo '<h2>Error en el constructor</h2><pre>' . $err .
'</pre>'; exit();
}
/* Definimos los parámetros a pasar al servicio */
$params = array(
'login' => array(
'Usuario' => base64_encode("Usuario"),
'Rut' => base64_encode("1-9"),
'Clave' => base64_encode("123456"),
'rutproveedor' => "90635000-9",
'tipoDTE' => "33",
'folio' => "10052")
'acuse' =>"a";
/* Invocamos el Web Service, Metodo: Procesar */
$result = $client->call('Acuse',$params);
/* Verificamos la respuesta, retornada por el servicio*/
if ($client->fault) {
echo '<h2>Fault (Error - La solicitud SOAP es
erronea)</h2><pre>'; print_r($result); echo '</pre>';
} else {
$err = $client-
>getError(); if ($err) {
echo '<h2>Error</h2><pre>' . $err . '</pre>';
} else {
/* Resultado exitoso */
echo $result['ProcesarResult'];
}
}
|
En el ejemplo siguiente, veremos la misma funcionalidad del código anterior utilizando PHP5 y su API SOAP integrada.
|
<?php
/* Ruta de acceso al servicio web */
$wsdl = 'http://ws.facturacion.cl/WSDS/wsplano.asmx?wsdl';
try {
/* Creamos una instancia del cliente SOAP */
$client = new soapclient($wsdl);
/* Definimos los parámetros a pasar al servicio */
$params = array(
'login' => array(
'Usuario' => base64_encode("Usuario"),
'Rut' => base64_encode("1-9"),
'Clave' => base64_encode("123456"),
'rutproveedor' => "90635000-9", 'tipoDTE' => "33",
'folio' => "10052")
'acuse' => "a";
/* Invocamos el Web Service, Metodo: Procesar */
$response = $client->Procesar($params);
/* Respuesta entregada por el servicio web */
print_r($response);
} catch(SoapFault $e){ echo 'Hubo un error';
}
?>
|
El método ConsultaPanelDte retorna mensaje que contendrá la información de los documentos de compra ubicados en el Panel de DTE Recibidos.
|
Ejemplo de proceso exitoso:
<WSPLANO>
<Resultado>True</Resultado>
<Mensaje>Proceso exitoso.</Mensaje>
<Detalle>
<Documento>
"folio":"10052","tipodte":"33","rutproveedor":"90635000-
9",
"recepcionsii":"2019-08-07T17:15:19Z"
</Documento>
</Detalle>
</WSPLANO>
|
Para mayor información, puede consultar los siguientes enlaces:
https://es.wikipedia.org/wiki/Servicio_web
https://es.wikipedia.org/wiki/SOAP
Este servicio le permitirá obtener los documentos que tiene registrados en su Libro de Compras
Para hacer uso del servicio, es necesario al invocar o consumirlo, indicar la información de autenticació que será proporcionada por nuestra empresa.
Esta información de autenticación es transmitida en una variable de tipo objeto, que contiene la siguiente estructura con los datos de autenticación:
| Clase: logininfo | |||
|---|---|---|---|
| Campo | Descripción | Codificado | Obligatorio |
| Rut | Corresponde al RUT de su empresa. | NO | SI |
| Clave | Es la clave asignada a su empresa. | NO | SI |
El Servicio Web posee varios métodos los cuales es posible consumir mediante cualquier cliente SOAP , por lo que se entrega una breve descripción de los que utilizarán en la integración.
| Método: | ObtenerCompra | ||
|---|---|---|---|
| Descripción: | |||
| Permite obtener el archivo XML de los documentos que se encuentran en el libro de compra. | |||
| Parámetro | Descripción | Codificado | Obligatorio |
| login | Estructura con datos de autenticación del cliente. | NO | SI |
| periodo | Corresponde al periodo del libro de compra donde se encuentra el Documento. Formato AAAA-MM | NO | SI |
| rutEmisor | Corresponde al RUT de la empresaque emitió el documento. | NO | NO |
| tipoDTE | Corresponde al Tipo de Documento (Tipo DTE). | NO | NO |
| folio | Corresponde al número de Folio del documento. | NO | NO |
| FormaPago | Corresponde a la forma de pago del documento 1= Al Contado / 2= Al Crédito / 3= Sin Costo. |
NO | NO |
| FechaIngreso | Corresponde a la fecha de ingreso al libro de compras Formato AAAA-MM-DD. | NO | NO |
| Incluyelink | En caso de que se requiera obtener los Links de los PDF de los documentos, se debe agregar este campo indicando como valor '1'. Se retornará el link de representación solo del cedible. | NO | NO |
| ConXML | En caso de que se requiera obtener sólo los documentos en formato XML recibidos por medio de intercambio enviados por su proveedor que figuran en el Libro de Compras, se debe agregar este campo indicando valor '1'. Se retornarán sólo los documentos que cuentan con su formato XML tributario en el Libro de Compras. | NO | NO |
| Respuesta: | SI | ||
| Como respuesta retorna el archivo XML, además de retornar el link para visualizar el PDF, del documento solicitado en formato base64Binary | |||
En caso de no enviar los parámetros de rutEmisor, tipoDTE, folio, FormaPago y FechaIngreso retornará todos los documentos de compra del periodo envíado.
En el siguiente ejemplo, veremos la manera de procesar el archivo de integración, utilizando como lenguaje PHP4 y valiéndonos de la librería NuSoap .
|
<?php
require_once('lib/nusoap.php');
/* Ruta de acceso al servicio web */
$wsdl = 'http://ws.facturacion.cl/WSDS/wsplano.asmx?wsdl';
/* Creamos una instancia del cliente SOAP */
$client = new soapclient($wsdl,true);
$client->setUseCurl(0);
$err = $client->getError();
if ($err) {
echo '<h2>Error en el constructor</h2><pre>' . $err .
'</pre>'; exit();
}
/* Definimos los parametros a pasar al servicio */
$params = array(
'login' => array(
'Rut' => "1-9",
'Clave' => "123456",
'periodo' => "2017-10",
'rutEmisor' => "76815550-K",
'tipoDTE' => "33",
'folio' => "15"));
/* Invocamos el Web Service, Metodo: ObtenerCompra */
$result = $client->call('ObtenerCompra',$params);
/* Verificamos la respuesta, retornada por el servicio*/
if ($client->fault) {
echo '<h2>Fault (Error - La solicitud SOAP es
erronea)</h2><pre>'; print_r($result); echo '</pre>';
} else {
$err = $client-
>getError(); if ($err) {
echo '<h2>Error</h2><pre>' . $err . '</pre>';
} else {
/* Resultado exitoso */
echo $result['ProcesarResult'];
}
}
?>
|
En el ejemplo siguiente, veremos la misma funcionalidad del código anterior utilizando PHP5 y su API SOAP integrada.
|
<?php
/* Ruta de acceso al servicio web */
$wsdl = 'http://ws.facturacion.cl/WSDS/wsplano.asmx?wsdl';
try {
/* Creamos una instancia del cliente SOAP */
$client = new soapclient($wsdl);
/* Definimos los parametros a pasar al servicio */
$params = array(
$params = array(
'login' => array(
'Rut' => "1-9",
'Clave' => "123456",
'periodo' => "2017-10",
'rutEmisor' => "76815550-K",
'tipoDTE' => "33",
'folio' => "15"));
/* Invocamos el Web Service, Metodo: Procesar */
$response = $client->Procesar($params);
/* Respuesta entregada por el servicio web */
print_r($response);
} catch(SoapFault $e){ echo 'Hubo un error';
}
?>
|
El método ObtenerCompra retorna XML que contendrá la información de los documentos de compra, esta información vendrá codificado en Base64 por lo cual deberá ser decodificado.
|
<WSPLANO>
<Resultado>True</Resultado>
<Mensaje>Proceso exitoso.</Mensaje>
<detalle>
<Documento>
PERURSB2ZXJzaW9uPSIxLjAiPg0KCTxEb2N1bWVudG8gSUQ9IkYxVDMzIj4NCgkJPEVuY2FiZ
XphZG8+DQoJCQk8SWREb2M+DQoJCQkJPFRpcG9EVEU+MzM8L1RpcG9EVEU+DQoJCQkJPEZvbG
lvPjA8L0ZvbGlvPg0KCQkJCTxGY2hFbWlzPjIwMDgtMDQtMDk8L0ZjaEVtaXM+DQoJCQk8L0l
kRG9jPg0KCQkJPEVtaXNvcj4NCgkJCQk8UlVURW1pc29yPjEtOTwvUlVURW1pc29yPg0KCQkJ
CTxSem5Tb2M+Um9iZXJ0byBHb21lejwvUnpuU29jPg0KCQkJCTxHaXJvRW1pcz5JbXBvcnRhY
2nDs24gPC9HaXJvRW1pcz4NCgkJCQk8QWN0ZWNvPjUxNTAwOTwvQWN0ZWNvPg0KCQkJCTxEaX
JPcmlnZW4+UGVkcm8gZGUgVmFsZGl2aWEgMjU8L0Rpck9yaWdlbj4NCgkJCQk8Q21uYU9yaWd
lbj5Qcm92aWRlbmNpYTwvQ21uYU9yaWdlbj4NCgkJCQk8Q2l1ZGFkT3JpZ2VuPlNBTlRJQUdP
PC9DaXVkYWRPcmlnZW4+DQoJCQk8L0VtaXNvcj4NCgkJCTxSZWNlcHRvcj4NCgkJCQk8UlVUU
mVjZXA+MTU5MTU5MTUtOTwvUlVUUmVjZXA+DQoJCQkJPENkZ0ludFJlY2VwPjE1OTE1OTE1PC
9DZGdJbnRSZWNlcD4NCgkJCQk8UnpuU29jUmVjZXA+U0VSVklDSU9TIEdSQUZJQ09TPC9Sem5
Tb2NSZWNlcD4NCgkJCQk8R2lyb1JlY2VwPlNFUlZJQ0lPPC9HaXJvUmVjZXA+DQoJCQkJPERp
clJlY2VwPkRFUEFSVEFNRU5UQUwgMjUwPC9EaXJSZWNlcD4NCgkJCQk8Q21uYVJlY2VwPlNBT
iBKT0FRVUlOPC9DbW5hUmVjZXA+DQoJCQkJPENpdWRhZFJlY2VwPlNBTlRJQUdPPC9DaXVkYW
RSZWNlcD4NCgkJCTwvUmVjZXB0b3I+DQoJCQk8VG90YWxlcz4NCgkJCQk8TW50TmV0bz41NTc
yNjI8L01udE5ldG8+DQoJCQkJPFRhc2FJVkE+MTk8L1Rhc2FJVkE+DQoJCQkJPElWQT4xMDU4
ODA8L0lWQT4NCgkJCQk8TW50VG90YWw+NjYzMTQyPC9NbnRUb3RhbD4NCgkJCTwvVG90YWxlc
z4NCgkJPC9FbmNhYmV6YWRvPg0KCQk8RGV0YWxsZT4NCgkJCTxOcm9MaW5EZXQ+MTwvTnJvTG
luRGV0Pg0KCQkJPENkZ0l0ZW0+DQoJCQkJPFRwb0NvZGlnbz5JTlQxPC9UcG9Db2RpZ28+DQo
JCQkJPFZsckNvZGlnbz5DQTwvVmxyQ29kaWdvPg0KCQkJPC9DZGdJdGVtPg0KCQkJPE5tYkl0
ZW0+Q2Fqw7NuIEFGRUNUTzwvTm1iSXRlbT4NCgkJCTxEc2NJdGVtPlRleHRvIGFkaWNpb25hb
CBhbCBwcm9kdWN0bzwvRHNjSXRlbT4NCgkJCTxRdHlJdGVtPjE2NjwvUXR5SXRlbT4NCgkJCT
xVbm1kSXRlbT5VTjwvVW5tZEl0ZW0+DQoJCQk8UHJjSXRlbT4zMzU3PC9QcmNJdGVtPg0KCQk
JPE1vbnRvSXRlbT41NTcyNjI8L01vbnRvSXRlbT4NCgkJPC9EZXRhbGxlPg0KCTwvRG9jdW1l
bnRvPg0KPC9EVEU+
</Documento>
</Detalle>
</WSPLANO>
|
Para mayor información, puede consultar los siguientes enlaces:
https://es.wikipedia.org/wiki/Servicio_web
https://es.wikipedia.org/wiki/SOAP