Saltar al contenido principal

Endpoints

Introducción a los Endpoints de la API​

Los endpoints son las URL que se utilizan para acceder a los recursos de la API. Cada endpoint es un punto de acceso a la API que puede devolver datos o realizar operaciones en el servidor.

La API cuenta con dos tipos de endpoints: Públicos y Privados.

Endpoints Públicos​

Los endpoints públicos son aquellos que no requieren autenticación para ser accedidos. Estos endpoints son utilizados para obtener información de la API, como por ejemplo, token de acceso para los endpoints privados. Todas las solicitudes a los endpoints públicos de las tablas referenciadas de la DIAN retornan un objeto de tipo JSON con la siguiente estructura.

{
    "dataRecords": {
        "data": [
            {
                "id": 1,
                "code": 1,
                "environment_name": "Producción"
            },
            {
                "id": 2,
                "code": 2,
                "environment_name": "Pruebas"
            }
        ]
    },
    "success": true
}

Donde dataRecords es el objeto que contiene la información de la tabla referenciada, data es el arreglo de objetos que contiene la información de la tabla referenciada y success es el estado de la petición.

Tablas Referenciadas DIAN. Todas las peticiónes de este tipo de endpoints son GET.​

Documentos electrónicos.​

  • Ambiente de destino de los documentos electrónicos: cbc:ProfileExecutionID y cbc:UUID.@schemeID​

{{url}}/destination-environment

  • Tipo de correcciones aplicables a las notas contables​

{{url}}/correction-notes

  • Códigos de descuentos​

{{url}}/discount-codes

  • Tipos de Documentos: Factura, Nota Crédito, Nota Débito, etc. cbc:InvoiceTypeCode y cbc:CreditnoteTypeCode​

{{url}}/document-type

  • Tipos de operación: Exportación, Nacional, etc. cbc:InvoiceTypeCode y cbc:CreditnoteTypeCode​

{{url}}/operation-type

  • Documentos de identificación​

{{url}}/identity-documents

  • Tributos - Impuestos​

{{url}}/taxes

  • Rango de impuestos​

{{url}}/tax-rates

  • Tipo de organización​

{{url}}/organization-type

  • Régimen Fiscal​

{{url}}/fiscal-regime

  • Régimen contable​

{{url}}/accounting-regime

  • Unidades de cantidad​

{{url}}/quantity-units

  • Tipo de identificación del ITEM de cada línea del documento electrónico.​

{{url}}/type-item-identifications

  • Referencia de precios​

{{url}}/reference-price

  • Métodos de pago​

{{url}}/payment-methods

  • Medios de pago​

{{url}}/payment-means
{{url}}/cities

  • Departamentos​

{{url}}/departments
{{url}}/countries
{{url}}/currencies

Nómina electrónica.​

  • Tipo de ajuste a la nota de ajuste​

{{url}}/ep/adjustment-note-type

  • Tipo de contrato​

{{url}}/ep/contract-type

  • Tipo de discapacidad​

{{url}}/ep/disability-type

  • Horas extras​

{{url}}/ep/extra-hours

  • Periodicidad de la nómina​

{{url}}/ep/payroll-period

  • Tipo de trabajo​

{{url}}/ep/worker-type

  • Subtipo de trabajo​

{{url}}/ep/worker-subtype

Autenticación​

Autenticación de usuario​

  • Iniciar sesión. Tipo de petición: POST​

{{url}}/auth/login

Endpoints Privados​

Los endpoints privados son aquellos que requieren autenticación para ser accedidos. Estos endpoints son utilizados para realizar operaciones en la API, como por ejemplo, realizar el envío de una factura, email u otro tipo de operación.

Autenticación​

Autenticación de usuario​

  • Cerrar sesión. Tipo de petición: GET​

{{url}}/auth/logout

Facturación electrónica​

Este endpoint es utilizado para enviar facturas electrónicas a la DIAN, de tipo POS, Documento soporte, factura nacional y de exportación.

  • Enviar factura. Tipo de petición: POST​

{{url}}/invoice

Nota crédito electrónica​

Este endpoint es utilizado para enviar notas crédito electrónicas a la DIAN, de tipo POS, Documento soporte, factura nacional y de exportación.

  • Enviar nota crédito. Tipo de petición: POST​

{{url}}/notes/credit

Nota débito electrónica​

Este endpoint es utilizado para enviar notas débito electrónicas a la DIAN, de tipo POS, Documento soporte, factura nacional y de exportación.

  • Enviar nota débito. Tipo de petición: POST​

{{url}}/notes/debit

Nómina electrónica​

Este endpoint es utilizado para enviar nóminas electrónicas a la DIAN.

  • Enviar nómina. Tipo de petición: POST​

{{url}}/ep/payroll

Nota de ajuste electrónica de remplazo (Nómina)​

Este endpoint es utilizado para enviar notas de ajuste electrónicas de remplazo a la DIAN.

  • Enviar nota de ajuste. Tipo de petición: POST​

{{url}}/ep/payroll/replace

Nota de ajuste electrónica de eliminación (Nómina)​

Este endpoint es utilizado para enviar notas de ajuste electrónicas de eliminación a la DIAN.

  • Enviar nota de ajuste. Tipo de petición: POST​

{{url}}/ep/payroll/delete

Documento soporte para no obligados a facturar​

Este endpoint es utilizado para enviar documentos soporte para no obligados a facturar a la DIAN. Para residentes y no residentes.

  • Enviar documento soporte. Tipo de petición: POST​

{{url}}/ds/document

Nota de ajuste para el documento soporte​

Este endpoint es utilizado para enviar notas de ajuste para el documento soporte a la DIAN. Para residentes y no residentes.

  • Enviar nota de ajuste. Tipo de petición: POST​

{{url}}/ds/adjustment-note

Documentos​

Búsqueda de documentos electrónicos​

Este endpoint es utilizado para buscar en los documentos generados por la API.

  • Buscar documentos. Tipo de petición: GET​

{{url}}/documents?order_number=251956&query=&limit=1&resolution=&number=&prefix=

Para realizar la búsqueda de documentos se pueden utilizar los siguientes parámetros:

  • Parámetros de búsqueda​

{
    "order_number": "Número de orden",
    "number": "Número de documento",
    "query": "Texto de búsqueda",
    "limit": "Número de registros a traer",
    "resolution": "Resolución de facturación",
    "prefix": "Prefijo de la resolución",
    "startDate": "Fecha de inicio",
    "endDate": "Fecha de fin"
}

Último documento generado​

Este endpoint es utilizado para obtener el último documento generado por la API.

  • Último documento. Tipo de petición: GET​

{{url}}/documents/last?resolution=18764074347312&prefix=LZT

Para obtener el último documento generado se deben enviar los siguientes parámetros:

  • Parámetros de búsqueda​

{
    "resolution": "Resolución de facturación",
    "prefix": "Prefijo de la resolución"
}

Descargar PDF del documento​

Este endpoint es utilizado para descargar el PDF del documento generado por la API.

  • Descargar PDF. Tipo de petición: GET​

{{url}}/documents/pdf/{CUFE/CUDE}

Donde CUFE/CUDE es el código único de factura electrónica o documento soporte. Para descargar el PDF del documento se debe enviar el CUFE/CUDE del documento generado.

  • Parámetros de búsqueda​

{
    "regenerate": "Cuando es 1 le indica al API que debe reescribir representación grafica. Por defecto es 0"
}

Descargar XML del documento​

Este endpoint es utilizado para descargar el XML del documento generado por la API.

  • Descargar XML. Tipo de petición: GET​

{{url}}/documents/xml/{CUFE/CUDE}

Donde CUFE/CUDE es el código único de factura electrónica o documento soporte. Para descargar el XML del documento se debe enviar el CUFE/CUDE del documento generado.

Descargar ATTACHED del documento​

Este endpoint es utilizado para descargar el attachment del documento generado por la API.

  • Descargar ATTACHED. Tipo de petición: POST​

{{url}}/documents/attached/{CUFE/CUDE}

Donde CUFE/CUDE es el código único de factura electrónica o documento soporte. Para descargar el PDF del documento se debe enviar el CUFE/CUDE del documento generado.

  • Parámetros de búsqueda​

{
    "regenerate": "Cuando es 1 le indica al API que debe reescribir representación grafica. Por defecto es 0"
}

Eventos - Acuses​

Mostrar en lista los eventos generados​

Este endpoint es utilizado para mostrar en lista los eventos generados por la API.

  • Mostrar eventos. Tipo de petición: GET​

{{url}}/events/document-receptions?startDate=&endDate=&trackId=&query&limit=20

Para mostrar los eventos generados se pueden utilizar los siguientes parámetros (opcionales) de búsqueda:

  • Parámetros de búsqueda​

{
    "startDate": "Fecha de inicio (En la que se generó el evento en el API)",
    "endDate": "Fecha de fin (En la que se generó el evento en el API)",
    "trackId": "CUFE/CUDE del documento",
    "query": "Texto de búsqueda (NIT, nombre del proveedor.)",
    "limit": "Número de registros a traer, por defecto es 20 y máximo 50 registros"
}

Estado del documento en la DIAN​

Este endpoint es utilizado para obtener el documento en la DIAN y sus eventos, si tiene eventos generados.

  • Estado del documento. Tipo de petición: GET​

{{url}}/events/status/{{trackId}}

Donde trackId es el CUFE/CUDE del documento.

Importar documentos de la DIAN a la API para generar los eventos(ACUSES)​

Estos endpoints son utilizados para importar los documentos de la DIAN a la API para generar los eventos(ACUSES).

  • Importar documento usando CUFE/CUDE. Tipo de petición: POST​

{{url}}/events/import-track-id

En el body de la petición se debe enviar la propiedad {{trackId}} que debe contener el valor del CUFE/CUDE del documento.

  • Importar documento usando CUFE/CUDE. Tipo de petición: POST​

{{url}}/events/{{trackId}}/import

Donde trackId es el CUFE/CUDE del documento.

  • Importar usando archivo excel. Tipo de petición: POST​

Para importar un archivo, este debe ser en formato EXCEL y debe contener los campos necesarios para la importación. De lo contrario, la importación no se realizará correctamente. Estos campos son: Tipo de documento, CUFE/CUDE, Folio, Prefijo, Fecha Emisión, Fecha Recepción, NIT Emisor, Nombre Emisor, NIT Receptor, Nombre Receptor, IVA, ICA, IPC, Total, Estado, Grupo. El archivo debe contener una fila de encabezado con los nombres de los campos. Acorde a documento excel que se baja de la plataforma de la DIAN.

{{url}}/events/import-excel

Este listado lo puede bajar desde el portal de facturación de la DIAN. Nota: El archivo no debe contener más de 100 registros.

  • Importar usando el tipo de evento. Tipo de petición: POST​

Este endpoint es utilizado para importar los documentos de la DIAN a la API para generar los eventos(ACUSES) por tipo de evento.

{{url}}/events/send/{{trackId}}

Donde trackId es el CUFE/CUDE del documento.

  • Parámetros del body​

{
    "code": "Código del evento(030, 031, 032, 033)",
    "notes": "Notas del evento"
}

  • Ejemplo de body Acuse de recibo​

{
    "code": "030",
    "notes": "Acuso recibido de factura."
}

  • Ejemplo de body Reclamo de la factura​

{
    "code": "031",
    "notes": "Reclamo de factura."
}

  • Ejemplo de body Recibo de la factura​

{
    "code": "032",
    "notes": "Recibo del bien y/o prestación del servicio."
}

  • Ejemplo de body Aceptación expresa​

{
    "code": "033",
    "notes": "Aceptación expresa."
}