API Datamart

API Datamart (1.0.0)

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.

Peticiones y respuestas

La interacción con el 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, y estas últimas se devuelven bajo códigos de estado HTTP. De forma general, 200 indica que la solicitud fue satisfactoria, 4XX errores controlados y 500 cuando ocurre algún error no controlado. Se recomienda incluir el encabezado Content-Type: application/json en todas las solicitudes que envíen contenido en el cuerpo de la misma.

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

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

Errores

Las respuestas no satisfactorias utilizan códigos de estado HTTP para indicar el tipo de error ocurrido. El cuerpo de respuesta JSON puede contener un código de nivel superior y un mensaje con una descripción detallada del problema.
Cada API describe detalladamente 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.

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. Vea la lista de errores de nivel superior para más detalles. (Vea abajo)
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.

Errores de validación
Las respuestas con un código de nivel superior se devuelven cuando es posible corregir un problema específico en la solicitud. La respuesta incluirá un mensaje descriptivo de los problemas detectados y un código para facilitar el tratamiento al problema.
La siguiente lista describe códigos de nivel superior comunes que pueden responder todas las APIs. Cada API describe detalladamente 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.

  •   1 - El cuerpo de la solicitud o alguno de sus parámetros están incorrectos
  • 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

Ejemplo de respuesta para una solicitud con credenciales inválidas:

  {
    "Codigo":"65",
    "Mensaje": "Credenciales inválidas"
  }

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

   /*
    using DMSDK.Core;
    using DMSDK.Core.Model;
    using DMSDK.SII;
    using DMSDK.SII.Model;
    */

    //Identificación del DTE a verificar
    VerificarFactCesionReq factibilidadRequest = new VerificarFactCesionReq()
    {
        RUTEmisor = "1-9",
        TipoDocumento = TipoDocumento.FacturaElectronica,
        FolioDocumento = "1234"
    };

    //Parámetros para consultar la API
    var apiConfig = new ApiConfig()
    {
        IdCliente = "id-cliente",
        ApiKey = "api-key-cliente",
        Ambiente = Ambiente.HOMO
    };

    var respuesta = ServicioDTE.VerificarFactibilidadCesion(factibilidadRequest, apiConfig);

    if (respuesta.Codigo == CodigoRespuesta.OK)
    {
        string mensaje = (respuesta.DocumentoCedible == DTECedible.SI || respuesta.DocumentoCedible == DTECedible.OBS) 
            ? "El documento puede ser cedido" 
            : "El documento no puede ser cedido";
        Console.WriteLine($"{mensaje}: {respuesta.Mensaje}");
    }
    else
    {
        Console.WriteLine($"No se pudo consultar si el DTE puede ser cedido: {respuesta.Mensaje}");
    }

Obtener notificación recibida vía Webhook

  /*
    using DMSDK.Core.Excepciones;
    using DMSDK.Perfiles.CL.Model;
    using DMSDK.SII.Model;
    using System.IO;
    using System.Net;
    using System.Web.Mvc;
    */

    //Verificar autenticidad del POST recibido
    var authToken = Request.Headers.Get("auth-token");
    if (authToken != "mi_token_auth")
        return new HttpStatusCodeResult(HttpStatusCode.Unauthorized);

    EventoDTENotificado dteEvent;
    try
    {
        using (StreamReader reader = new StreamReader(Request.InputStream))
        {
            var payload = reader.ReadToEnd();
            dteEvent = new EventoDTENotificado(payload);
        }
        //TODO: procesar el evento DTE recibido
    }
    catch (NotificacionInvalidaException ex)
    {
        return new HttpStatusCodeResult(HttpStatusCode.BadRequest, ex.Message);
    }

    //Retornar OK como indicador de que se recibió la notificación de manera satisfactoria
    return new HttpStatusCodeResult(HttpStatusCode.OK);

Acceso a las APIs

En Datamart disponemos de dos ambientes de trabajo, un ambiente de homologación sobre el que se pueden probar todas las integraciones a los diferentes servicios, y un ambiente que producción que una vez terminado el desarrollo se puede comenzar a consumir análogo al ambiente productivo. De esta forma el desarrollo de nuevas funcionalidades o integraciones no afecta el ambiente de producción.

Todos los servicios están disponibles en el ambiente de homologación y con las mismas funcionalidades. Para realizar solicitudes a las diferentes APIs solo se debe modificar el Host y ApiKey según el ambiente en que se desee operar.

Homologación: https://homo.datamart.cl.

Producción: https://api.datamart.cl.

Autorización

Para identificar y autorizar el acceso a las APIs se utiliza autorización por ApiKey e ID del Cliente, cada API especifica explícitamente el método de autenticación que se debe utilizar para realizar solicitudes. Las ApiKeys de acceso pueden ser recuperadas y configuradas desde el Portal de Clientes. Cada ApiKey es configurada para ser utilizada en el ambiente de homologación o producción, para cada ambiente se obtendrá una ApiKey privada para autorizar todas las solicitudes. Debe asegurarse de proteger y nunca compartir los ApiKeys ya que tienen acceso a todos los datos de su cuenta.

ApiKey

ApiKey del cliente para autenticación y autorización en las APIs

Security Scheme Type API Key
Header parameter name: x-api-key

IdCliente

Identificador del cliente para autenticación y autorización en las APIs

Security Scheme Type API Key
Header parameter name: x-dmrt-customer-id

Notificaciones

La mayoría de los servicios envían notificaciones a los clientes sobre los datos que procesan. Estas notificaciones pueden ocurrir vía correo electrónico o webhook, a través del Portal de Clientes los clientes pueden seleccionar las configuraciones sobre cómo desea que ello ocurra y los métodos de seguridad que emplean.

Fogape

Este servicio permite obtener la deuda registrada en Fondo de Garantía para Pequeños Empresarios (FOGAPE) para un beneficiario.

Obtener Deuda

Permite obtener deuda de fogape

Authorizations:
path Parameters
cliente-id
required
any

Identificador del cliente

rut-beneficiario
required
any

Identificador del beneficiario

Responses

200

Retorna la información de la deuda del beneficiario

400

Error de validación

401

No Autorizado

403

ApiKey requerida

429

Cuota excedida

500

Error interno

get/fogape/v1/debts/{cliente-id}/{rut-beneficiario}

Servidor de Homologación

https://homo.datamart.cl/fogape/v1/debts/{cliente-id}/{rut-beneficiario}

Servidor de Producción

https://api.datamart.cl/fogape/v1/debts/{cliente-id}/{rut-beneficiario}

Request samples

Copy
curl --request GET \
  --url 'https://homo.datamart.cl/fogape/v1/debts/{cliente-id}/{rut-beneficiario}' \
  --header 'x-api-key: {API_KEY_CLIENTE}'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Codigo": "0",
  • "Mensaje": "",
  • "DeudaFogape":
    {
    },
  • "DeudaCovid19":
    {
    },
  • "OperacionesVigentes":
    [
    ],
  • "FechaConsulta": "2020-05-30T12:04:25",
  • "SolicitudId": "a7cce77b-f795-4208-91f6-79460ceb91c6"
}

DJ Sync

Servicio que permite sincronizar las declaraciones juradas (DJ) desde el Servicio de Impuestos Internos. Para una empresa suscrita al servicio, periódicamente y de forma automática se notifica vía Webhook o por correo electrónico las declaraciones juradas.

Notificaciones
Este servicio notifica de forma automática, vía Webhook o por correo electrónico, las declaraciones juradas de la empresa, actualizada desde el Servicio de Impuestos Internos.
El siguiente modelo representa los datos enviados en la notificación.

RUT
string

Identificador del subscriptor

Servicio
string

Nombre del servicio

Notificacion
string
Value: "DJ_DESCARGADA"

Tipo de acción realizada sobre la DJ

EnlaceXml
string <uri>

Enlace para la descarga del xml de la DJ

Periodo
string <yyyy>

Año de la DJ

Dj
string

Identificador de la DJ

Copy
Expand all Collapse all