Contactar

Introducción Última actualización: 2022-01-14

Implementa la solución fiscal ideal para cualquier tipo de negocio.

Optimiza tu experiencia de facturación y ofrece documentos tributarios en todas tus aplicaciones.

Empieza por aquí

Ebill utiliza una API RESTful basada en HTTP y bajo SSL. Las peticiones y respuestas de la API se hacen por medio del uso de mensajes formateados en JSON.

Lo primero que debes hacer para conectarte a la API es obtener la autorización para acceder a los recursos de esta. Esta autorización o llave de acceso, identifican tu empresa y el punto de venta que realiza las acciones, según el ambiente de prueba o producción que desea utilizar y son entregadas al momento de contratar nuestros planes.

Ambientes

Para facilitar las integraciones, hemos creado un ambiente para pruebas y otro para producción. Esto permite que nuestros desarrolladores puedan crear documentos y que estos pasen por un flujo identico al productivo utilizando el ambiente de certificación del SII.

Existen una URL para cada ambiente:

  • Desarrollo: https://qaapi.ebill.cl
  • Producción: https://api.ebill.cl

Por seguridad, se debe tener en consideración los límites que ofrece la API para su implementación, actualmente se tiene un límite de peticiones por segundos que se pueden realizar y cuotas mensuales solo si el ambiente es de prueba.

  • límite de consultas por segundos: 100
  • cuota mensual de cantidad de request: 1000
Cuando se alcance alguno de estos límites el sistema reponderá con un código HTTP de error 429

Nota

Recuerda que la cuota mensual es solo para el ambiente de prueba. Además, si para tu integración necesitas aumentar estos límites, no te preocupes, simplemente ponte en contacto con nosotros en soporte@ebill.cl tenemos una solución para todos tus problemas.

Autenticación

Hay dos tipos diferentes de credenciales:

  • Credenciales de prueba. Las credenciales de prueba deben usarse para probar tus integraciones. Se recomienda utilizarlas antes de las credenciales de producción para garantizar que las integraciones funcionen correctamente.
  • Credenciales de producción. Las credenciales de producción se utilizan para entornos reales de emisión de documentos tributarios.

Con estas credenciales puedes comunicarte con nuestra API de forma segura, utilizando tu Api-Key y Access-Token generado por nuestro equipo de soporte para cada punto de venta. Esta información debe ser enviada en todas las llamadas en la sección Headers de la siguiente forma:

 request.AddHeader("X-Api-Key","xxxxxxxxxxxxxxxxxxxx");
 request.AddHeader("X-Access-Token","xxxxxxxxxxxxxxxxxxxx");

Nota

Tienes la opción de renovar tus credenciales por razones de seguridad o por el motivo que necesites. Para renovarlas, simplemente ponte en contacto con nosotros en soporte@ebill.cl

APIs

Encuentra en cada sección todo lo que necesitas saber para generar documentos tributarios o realizar el pedido de información que quieras. En esta sección describimos todos nuestros recursos y como debes utilizarlos, así como la respuesta que debes esperar de cada uno.

Tu empresa

Para poder configurar en los puntos de ventas toda la información de la empresa, podemos solicitar via api esta información para mitigar errores manuales. Esta solicitud se debe realizar mediante una llamada GET como se muestra en el ejemplo:

 var client = new RestClient("https://{Url}/account/{Rut}");
 var request = new RestRequest(Method.GET);
 request.AddHeader("X-Api-Key", "xxxxxxxxxxxxxxxxxxxx");
 request.AddHeader("X-Access-Token", "xxxxxxxxxxxxxxxxxxxx");
 IRestResponse response = client.Execute(request);

  • {URL}: Es la url según el ambiente de pruebas o producción.
  • {Rut}: Identificador de la empresa (Ej: 12345678-9).
Ejemplo de Url: https://{Url}/account/12345678-9

La respuesta de esta llamada tiene un HTTP_STATUS_CODE = 200 y el BODY, es un json con la siguiente estructura:

{
	"Code": 200,
	"Status": "OK",
	"Data": {
		"Rut": "12345678-9",
		"BusinessName": "Nombre de la Empresa",
		"Giro": "Giro de mi empresa",
		"SiiOffice": "SANTIAGO ORIENTE",
		"ResolutionNumber": 80,
		"ResolutionDate": "2016-06-29",
		"Addresses": [
			{
				"Street": "Calle",
				"Number": "13",
				"Office": "101",
				"Commune": "PROVIDENCIA",
				"City": "SANTIAGO"
			}
		],
		"BranchOffices": [
			{
				"Code": "12345",
				"Type": "Sucursal",
				"Address": "Calle 13, Of 101 PROVIDENCIA, SANTIAGO",
				"AddressStruct": {
					"Street": "Calle",
					"Number": "13",
					"Office": "101",
					"Commune": "PROVIDENCIA",
					"City": "SANTIAGO"
				}
			}
		],
		"EconomicActivitys": [
			{
				"Code": "726000",
				"Description": "EMPRESAS DE SERVICIOS INTEGRALES DE INFORMATICA"
			}
		]
	}
}

¿Qué significa cada elemento del json?

  • {Rut}: Es el identificador de la empresa (Tax Id).
  • {BusinessName}: Es la razón social de la empresa.
  • {Giro}: Giro de la empresa (va en el campo “GiroEmis” del documento).
  • {SiiOffice}: Es la dirección regional (va en el documento impreso).
  • {ResolutionNumber}: Número de resolución (va en el documento impreso)
  • {ResolutionDate}: Fecha de resolución (va en el documento impreso)
  • {Addresses}: Dirección de la casa matriz.
  • {BranchOffices}: Listado de sucursales (En caso que el POS esté en una sucursal, debe enviar el código en el campo "CdgSIISucur" y la dirección de esta reemplaza la dirección de casa matriz).
  • {EconomicActivitys}: Listado de actividades económicas que tiene habilitada la empresa (Se envía una por documento y solo el código en el campo “Acteco”).


¿Qué otros estados debo esperar al consultar mi empresa?

401 Unauthorized Error con X-Api-Key, X-Access-Token o el Rut no corresponde con la Key y Token proporcionado.
404 NotFound La empresa solicitada no existe.
500 InternalServerError Esto es un error no esperado en las apis de ebill. No debería pasar nunca.

Gestiona Folios

Para poder emitir documentos tributarios, debemos poder asignar un folio y timbrar los documentos. Como en Ebill se maneja de forma centralizada el uso de los CAF, tienes 2 formas de operar, según las complejidades de tu negocio:

  • Nosotros asignamos los folios. No te preocupas por nada, la api de ebill se encarga de asignar los folios de forma eficiente al momento de crear un documento. Este modelo no se recomienda para el uso vía api, ya que pierdes la posibilidad de trabajar en modo offline, dependes 100% de nosotros para poder imprimir el comprobante y puede generar duplicidad en las ventas si no establecemos un código interno para cada transacción.
  • Tú gestionas rangos de folios, los asignas y timbras el documento. Esta es la forma óptima de integrarte, ya que tienes control de la emisión de documentos y no depende de nosotros para imprimir o distribuír vía electrónica. Además al tener rangos de folios reservados, vas a poder trabajar en modo offline en tus puntos de ventas, o sea no se detiene tu venta por problemas de internet u otros.

Si decides tener el control, primero debes solicitar un subrango para cada tipo de documento en cada uno de tus puntos de ventas (POS). Esta solicitud se debe realizar mediante una llamada POST sin body como se muestra en el ejemplo:

 var client = new RestClient("https://{Url}/caf/range/{Rut}/{DocumentType}/{Quantity}");
 var request = new RestRequest(Method.POST);
 request.AddHeader("X-Api-Key", "xxxxxxxxxxxxxxxxxxxx");
 request.AddHeader("X-Access-Token", "xxxxxxxxxxxxxxxxxxxx");
 IRestResponse response = client.Execute(request);

  • {URL}: Es la url según el ambiente de pruebas o producción.
  • {Rut}: Identificador de la empresa (Ej: 12345678-9).
  • {DocumentType}: Tipo de documento (Ej: 39 - para boleta electrónica, 33 - para Factura Electrónica).
  • {Quantity}: Cantidad de folios que solicita (Ej: 100 folios, que representa el promedio de ventas en 15 días de un POS).
Ejemplo de Url: https://{Url}/caf/range/12345678-9/39/100

La respuesta de esta llamada tiene un HTTP_STATUS_CODE = 200 y el BODY, es un json con la siguiente estructura:

 {
	"Code": 200,
	"Status": "OK",
	"Data": {
		"Rut": "12345678-9",
		"DocumentType": 39,
		"FolioFrom": 1,
		"FolioTo": 100,
		"CafFrom": 1,
		"CafTo": 200,
		"AuthorizationDate": "2021-06-02",
		"CafBase64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+CjxBVVRPUklaQUNJT04+C..."
	}
 }

¿Qué significa cada elemento del json?

  • {Rut}: Es el identificador de la empresa (Tax Id).
  • {DocumentType}: Es el identificador del tipo de documento definido por el SII.
  • {FolioFrom}: Folio inicial del rango entregado.
  • {FolioTo}: Folio final del rango entregado.
  • {CafFrom}: Folio inicial del CAF. (Informativo)
  • {CafTo}: Folio final del CAF. (Informativo)
  • {AuthorizationDate}: Fecha de autorización del CAF. (Esta fecha se debe guardar, según la definición actual del SII, los CAF expiran 6 meses desde su autorización. Al pasar esto, ya no se puede seguir asignado folios, ni timbrando con este CAF).
  • {CafBase64}: Es el XML CAF que entrega la entidad tributaria y que el contribuyente debe utilizar al crear cada documento. Este XML debe ser almacenado para la generación del Timbre. Al decodificar en base64, se debe utilizar "ISO-8859-1", ejemplo: 
    Encoding.GetEncoding("ISO-8859-1").GetString(Convert.FromBase64String(CafBase64));

    Ejemplo del XML de un CAF: 

     <?xml version="1.0"?>
 <AUTORIZACION>
	<CAF version="1.0">
		<DA>
			<RE>12345678-9</RE>
			<RS>Empresa de Ejemplo</RS>
			<TD>39</TD>
			<RNG>
				<D>1</D>
				<H>200</H>
			</RNG>
			<FA>2021-06-01</FA>
			<RSAPK>
				<M>tmWvGhF8LFa3yb5m5S+AqoVkYEtuRpsuIZh6...</M>
				<E>Aw==</E>
			</RSAPK>
			<IDK>100</IDK>
		</DA>
		<FRMA algoritmo="SHA1withRSA">LzM0q3/F05hlOq2yYGlGo6mta6DCk1fSNAx...</FRMA>
	</CAF>
	<RSASK>-----BEGIN RSA PRIVATE KEY-----
	MIIBOQIBAAJBALZlkgAhwgJ3tZX94eAbxoRfCxWt8m+ZuUo5pt1hDAWu15m13K4G
	QR+BamfgKqFZGBLbkabLiGYeg50e+H6V72UCAQMCQHmZDAAWgVb6eQ6pQUAShFg/
	gVJzXy74GisCIQCJhUcJHSf3wtYejSv15E5SdJK/1U6M7IoB4PURZXmswwIgEeW6
	09GIpdcvegpaSk1WXlnf4dQAW7TO3XlUrlS3a6k=
	-----END RSA PRIVATE KEY-----
	</RSASK>

	<RSAPUBK>-----BEGIN PUBLIC KEY-----
	MFowDQYJKoZIhvcNAQEBBQADSQAwRgJBALZlkgAhwgJ3tZX94eAbxoRfCxWt8m+Z
	uUo5pt1hDAWu15m13K4GQR+BamfgKqFZGBLbkabLiGYeg50e+H6V72UCAQM=
	-----END PUBLIC KEY-----
	</RSAPUBK>
 </AUTORIZACION>


¿Qué otros estados debo esperar al solicitar un rango?

401 Unauthorized Error con X-Api-Key, X-Access-Token o el Rut no corresponde con la Key y Token proporcionado.
404 NotFound 1- No hay un CAF cargado en ebill para ese rut y tipo de documento.
2- Existe un CAF en ebill, pero no tiene rangos disponibles.
500 InternalServerError Esto es un error no esperado en las apis de ebill. No debería pasar nunca.

Crear un documento

Para crear documentos tributarios o registrar ventas, debes ser capáz de generar la información de venta en formato json, como el siguiente ejemplo:

 {
	"TipoDTE":"39",
	"Folio":10,
	"FchEmis":"2021-06-02",
	"FchVenc":"2021-06-02",
	"IndServicio":3,
	"FmaPago":1,
	"RUTEmisor":"12345678-9",
	"RznSocEmisor":"Ebill Company",
	"GiroEmis":"Servicios y Consultoria en Informatica",
	"Telefono":"223572222",
	"CorreoEmisor":"info@ebill.cl",
	"Acteco":"726000",
	"DirOrigen":"Calle 13",
	"CmnaOrigen":"SANTIAGO",
	"CiudadOrigen":"SANTIAGO",
	"RUTRecep":"66666666-6",
	"RznSocRecep":"Cliente",
	"MntNeto":810,
	"IVA":190,
	"TasaIVA":19,
	"MntTotal":1000,
	"Detalles":[
		{
			"NroLinDet":1,
			"NmbItem":"Producto 1",
			"DscItem":"Este es un buen producto 1",
			"QtyItem":1,
			"UnmdItem":"UNID",
			"PrcItem":1000,
			"MontoItem":1000,
			"CdgItems":[
				{
				"TpoCodigo":"INT1",
				"VlrCodigo":"123"
				}
			]
		}
	],
	"TedXML": "<TED><RE>12345678-9</RE><TD>39</TD><F>10</F>...</TED>",
	"Extensiones":{
		"Key":"Value",
		"Key2":"Value2"
	}
 }

Nota

Si decides generar el timbre del documento, para tener mayor control de las ventas, necesitas generar el contenido del campo "TedXML", para esto en la sección de recursos, te explicamos como hacerlo utilizando nuestras librerías. En caso que sigas con dudas, podemos ayudarte, simplemente ponte en contacto con nosotros en soporte@ebill.cl


Luego, solo debes enviarnos esta información. Esta solicitud se debe realizar mediante una llamada POST donde el BODY contiene el json de la venta como se muestra en el ejemplo:

 var client = new RestClient("https://{Url}/document");
 var request = new RestRequest(Method.POST);
 request.AddHeader("X-Api-Key", "xxxxxxxxxxxxxxxxxxxx");
 request.AddHeader("X-Access-Token", "xxxxxxxxxxxxxxxxxxxx");
 request.AddHeader("Content-Type", "application/json");
 request.AddParameter("application/json", "{\"TipoDTE\": \"39\", \"RUTEmisor\": \"12345678-9\", \"RUTRecep\": \"66666666-6\", \"RznSocEmisor\": \"EBILL COMPANY\", \"RznSocRecep\": \"Cliente\", \"Detalles\": [{\"DscItem\": \"Item 1\", \"MontoItem\": 840, \"NmbItem\": \"Item 1\", \"NroLinDet\": 1, \"PrcItem\": 840, \"QtyItem\": 1, \"UnmdItem\": \"UNID\"}], \"DirOrigen\": \"AV LUIS THAYER OJEDA 183, Of. 304\"...}",  ParameterType.RequestBody);
 IRestResponse response = client.Execute(request);

Ejemplo de Url: https://{Url}/document

La respuesta de esta llamada tiene un HTTP_STATUS_CODE = 200 y el BODY, es un json con la siguiente estructura:

 {
	"Code": 200,
	"Status": "OK",
	"Message": "Document with id 12345678 type 39 and folio 10 was created",
	"Data": {
		"Id": "12345678",
		"TipoDTE": "39",
		"Folio": 10
	}
 }

¿Qué otros estados debo esperar al realizar la solicitud?

401 Unauthorized Error con X-Api-Key, X-Access-Token o el Rut no corresponde con la Key y Token proporcionado.
400 BadRequest 1- La información del documento es inválida, no pudimos entender el json o tiene algún problema. Ver detalle en campo "Message".
2-Existe error en uno o más campos del json. Cuando pasa esto se agrega un nuevo campo “Errores” que tiene el formato Key:Value con el detalle del campo y su error.
409 Conflict El documento con ese Rut, tipo y folio, ya existe en ebill.
500 InternalServerError Esto es un error no esperado en las apis de ebill. No debería pasar nunca.

Resources

En esta sección podrás encontrar documentación y librerías adicionales para hacer tu integración más fácil y en menos tiempo. Con el paso del tiempo, tendremos los recursos en otros lenguajes y plataformas, nuestro objetivo es poder cubrir los requerimientos de la mayor cantidad de empresas que se decidan integrar.

Genera un Timbre

El timbre o ted, es una sección del XML tributario del SII que entre otras cosas, valida la integridad del uso de folio asignado por la entidad tributaria, además es el STRING que se debe utilizar para crear el código en formato PDF417 que va en el comprobante impreso de los documentos electrónicos Ej:

Para generar el Ted utilizando la librería "Ebill.LibCore.dll" solo se debe instanciar ciertas clases y pasarle los datos necesarios para generar la firma:

 var base64EncodedData = "PD94bWVVRPUklaQUNDQUYgdm2lvbj0iMS4wIj4KPERBPgo8=";

 //Read CAF from base64 string
 var caf = new Ebill.LibCore.CAF(base64EncodedData);

 //Build object Timbre with CAF
 var timbre = new Ebill.LibCore.TimbreElectronico(caf)
 {
	RUTEmisor = "12345678-9",
	TipoDTE = 39,
	Folio = 10,
	FechaEmision = DateTime.Parse("2021-06-02"),
	RUTRecep = "66666666-6",
	RazonSocialReceptor = "Cliente",
	MontoTotal = 1000,
	PrimerItemDetalle = "Producto 1"
 };

 timbre.Firmar();
 var tedXml = timbre.GetCleanXml();

El TED generado queda guardado en formato string en tedXml y debe ser enviado en el campo TedXML del json del documento.

Nota

Cuando se genera el timbre, se utiliza DateTime.Now para determinar la fecha en que se timbra el documento, esta hora y fecha, debe estar en time zone de Santiago Chile (Pacific SA Standard Time para windows y America/Santiago para sistemas unix) por lo que el POS o servidor debe tener esta configuración. Otra alternativa es pasando por parámetro esta hora y fecha al momento de firmar de la siguiente forma: timbre.Firmar(DateTime.Parse("2021-06-13T11:53:11"));