API Datamart

Introducción

Bienvenido a la documentación de la API de Datamart. Esta API le dará la posibilidad de conectar sus aplicaciones informáticas a diferentes servicios de Datamart para la sincronización de documentos tributarios, cesiones electrónicas, deuda en la tesorería general de la república, carpetas tributarias, entre otros.
La API se encuentra desarrollada tomando en consideración principios y recomendaciones para implementación de APIs REST y documentada siguiendo la especificación OpenAPI.

Subscripciones y credenciales

Para habilitar el modelo de notificación que permite sincronizar la información de un titular de información se requerirá establecer una subscripción de servicio. La subscripción de servicio es la entidad bajo la cual se identifica a las partes involucradas y la información que se comunicará. Esta entidad está conformada por:

Id de subscriptor: variable bajo la cual se identifica al Titular (que acepta compartir su información)
Id de cliente: variable que identifica al Destinatario que recibe la información
Servicio: variable que define la información y las condiciones bajo las cuales se notificará la misma

Los servicios están diseñados en torno al contexto de información que notifican. En caso de que la sincronización de información que acuerde el titular con el destinatario involucre datos de más de un servicio, se deberá orquestar la subscripción de tantos servicios como sea necesario.
En ocasiones, cuando la información asociada al servicio sea privada, se requerirá que los titulares registren sus credenciales de acceso, a fin de establecer las conexiones requeridas para obtener y comunicar dicha información. Las credenciales que provee el titular de la información serán tratadas como secretos, siendo almacenadas de manera encriptada. En este sentido, las credenciales de acceso serán únicas y estarán asociadas a cada titular, con independencia del número de subscripciones que se hayan realizado en el tiempo.
Ante la necesidad de realizar una operación que genere o modifique una subscripción de un servicio, será siempre obligatorio proveer la credencial válida de la fuente de datos. Este requerimiento tiene una finalidad dual, ya que por un lado permite gestionar la conexión a la fuente de datos y, por otro, actúa como mecanismo de seguridad al verificarse que el usuario que realiza la solicitud corresponde a una persona vinculada con el titular.
Ya que la credencial es una entidad única para todas las subscripciones, cualquier actualización que genere el titular sobre esta generará un efecto global en todos los destinatarios que posean subscripciones a servicios en donde dicha credencial sea utilizada para establecer la conexión hacia las fuentes de datos.
Al proveer las credenciales de los titulares de información a Datamart, estas pueden ser cifradas previo su envío usando algoritmos criptográficos estándares como AES o pueden ser enviadas en texto plano, en ambos casos el envío siempre se realizará sobre protocolo seguro HTTPS.

Peticiones y respuestas

Peticiones
La interacción con la API se realiza sobre conexiones seguras utilizando el protocolo HTTPS. Las solicitudes sobre HTTP no serán aceptadas y la respuesta indicará que se debe volver a realizar la misma solicitud sobre HTTPS. Las peticiones y respuestas se envían con formato JSON de acuerdo a los parámetros de cada método.

Ejemplo de petición POST

POST /cte/v1/subscriptions/1-9/1-8
Host: https://homo.datamart.cl
x-api-key: c40e7d1e28b94bdeb2dd16a736f09b16
Content-Type: application/json
{
  "atributo": "valor"
}

Ejemplo de petición GET

GET /subscriptions/v1/check-subscription/1-9/1-8/cte
Host: https://homo.datamart.cl
x-api-key: c40e7d1e28b94bdeb2dd16a736f09b16

Respuestas
Las respuestas utilizan códigos de estado HTTP para devolver el resultado de una petición realizada. De forma general, 200 indica que la solicitud fue satisfactoria, 4XX errores controlados y 500 cuando ocurre algún error no controlado. El cuerpo de respuesta JSON puede contener un código de nivel superior y un mensaje con una descripción detallada de la respuesta.
Cada API describe los posibles códigos de estado HTTP, el formato JSON de la respuesta, así como los diferentes códigos de nivel superior que puede responder.

Códigos comunes
La siguiente lista describe códigos de nivel superior comunes que pueden responder todas las APIs.

1 - El cuerpo de la solicitud o alguno de sus parámetros están incorrectos
13 - Certificado para autenticación requerido
15 - El usuario proporcionado no está autorizado para realizar la acción solicitada
60 - El cliente no está subscrito al servicio solicitado
61 - El cliente ya está subscrito al servicio solicitado
65 - Las credenciales proporcionadas no son correctas
66 - La autenticación con certificado digital no está habilitada
90 - Error no controlado (Internal Server Error)
91 - Tiempo de ejecución superado

Errores

Las respuestas relacionadas con errores de validación incluirán códigos de nivel superior para facilitar la corrección del problema y un mensaje descriptivo de los problemas detectados.

Ejemplo error de validación (HTTP 400)

{ 
  "Codigo":"1"
  "Mensaje": "El email de contacto no es válido"
}

Ejemplo error ApiKey incorrecta (HTTP 403)

{
  "message": "Forbidden"
}

Errores comunes
Los siguientes códigos de respuesta HTTP son comunes a todas las APIs.

HTTP Status	Descripción
400	El cuerpo de la solicitud contiene una sintaxis incorrecta o está incompleta.
400	Errores de validación presentes.
401	No autorizado.
403	ApiKey incorrecta.
403	La URL solicitada está incorrecta.
408	Tiempo de ejecución superado.
429	Cuota exedida.
500	Se produjo un error no controlado en la API.

Adecuaciones especiales

En base a la envergadura y limitaciones de los Clientes, Datamart podrá en ocasiones excepcionales generar desarrollos que puedan afectar el comportamiento de sus API’s, en este sentido, la documentación publicada hará referencia al comportamiento estándar de los servicios. La información relativa al comportamiento específico introducida por estas modificaciones será documentada y compartida con el Cliente en base al procedimiento de Datamart número DTM-PRC-CSTM-03.

Soporte SDK

Datamart ha mantenido oficialmente paquetes de software (SDKs) para facilitar a los desarrolladores comenzar a realizar solicitudes a las APIs de los diferentes servicios, así como también procesar la información que se notifica vía Webhooks.
En esta sección se proporcionan instrucciones básicas sobre cómo instalar y comenzar a utilizar estos paquetes de software.
Los SDKs mantenidos oficialmente están disponibles solamente para Microsoft .NET Framework v4.5 o superior. Los paquetes son de acceso público y se pueden encontrar en Nuget.org: https://www.nuget.org/profiles/Datamart.

C#

Verificar factibilidad de cesión de un DTE
Instalar paquete DMSDK.SII

PM> Install-Package DMSDK.SII