# MATIAS API UBL 2.1

> API REST de facturación electrónica para Colombia (DIAN, UBL 2.1): factura electrónica, POS electrónico, documento soporte, notas crédito/débito, nómina electrónica, eventos RADIAN y sector salud (Res. 000948 de 2026).

Guía rápida para agentes de IA:

- Base URL: en los ejemplos, `{{url}}` es la base URL de la API. Sandbox (gratuito, sin envío a la DIAN): `https://sandbox-api.matias-api.com/api/ubl2.1`. La de producción se entrega al contratar el servicio.
- Autenticación: header `Authorization: Bearer {token}` (token de acceso personal), además de `Accept: application/json` y `Content-Type: application/json`.
- Casas de Software: agregan `?client_uuid={uuid}` para operar en nombre de una empresa cliente.
- Cada página de este índice está en Markdown plano (`.md`). También se obtiene enviando `Accept: text/markdown` a la URL HTML.
- Especificación OpenAPI 3 de los endpoints públicos: https://docs.matias-api.com/openapi.json

## Inicio

- [Introducción](https://docs.matias-api.com/docs/intro.md): Matias es una plataforma de facturación electrónica que permite a las empresas emitir, enviar y gestionar facturas electrónicas de forma segura y eficiente. Nuestra API RESTful proporciona acceso completo a los…
- [Documentación para agentes de IA](https://docs.matias-api.com/docs/ai-ready.md): Cómo usar la documentación de MATIAS API con ChatGPT, Claude, Cursor, Copilot y otros asistentes de IA (llms.txt, Markdown y OpenAPI).

## Endpoints

- [Introducción y Autenticación](https://docs.matias-api.com/docs/endpoints/intro-auth.md): Autenticación de la API: login, tokens de acceso personal (PAT), verificación de correo, recuperación de contraseña y cierre de sesión.
- [Endpoints Públicos, Tablas DIAN y Funciones Auxiliares](https://docs.matias-api.com/docs/endpoints/public-dian.md): Endpoints públicos sin token: tablas paramétricas DIAN, catálogos (impuestos, unidades, ubicaciones) y funciones auxiliares (dígito de verificación, números a letras).
- [Facturación y Documentos Equivalentes (POS)](https://docs.matias-api.com/docs/endpoints/invoices-pos.md): Emisión de factura electrónica, notas crédito y débito y documento equivalente POS: request, respuestas, advertencias (warnings) y errores de emisión.
- [Documento Soporte](https://docs.matias-api.com/docs/endpoints/support-documents.md): Emisión de documento soporte y nota de ajuste para adquisiciones a no obligados a facturar, incluidos no residentes.
- [Nómina Electrónica](https://docs.matias-api.com/docs/endpoints/payroll.md): Nómina electrónica: emisión, reemplazo y eliminación del documento soporte de pago de nómina ante la DIAN.
- [Búsqueda y Estados de Documentos](https://docs.matias-api.com/docs/endpoints/queries-status.md): Consulta de documentos y estados DIAN: por uuid, por número o trackId, descarga de XML y PDF, reenvío por correo y eliminación de documentos no validados.
- [API de Eventos RADIAN](https://docs.matias-api.com/docs/endpoints/events-radian.md): Recepción de documentos y eventos RADIAN (030, 031, 032, 033): importación, envío individual y en bloque, buzón de recepción y personas de recepción.
- [API de Autoincremento](https://docs.matias-api.com/docs/endpoints/autoincrement.md): Emisión con numeración automática: la plataforma asigna el consecutivo de factura, notas, documento soporte y POS, y permite reenviar por uuid.
- [Gestión de Membresías y Consumo](https://docs.matias-api.com/docs/endpoints/memberships-health.md): Membresías y consumo: resumen del plan, recargas, cuotas para empresas cliente de Casas de Software y estadísticas de almacenamiento y correos.
- [Webhooks](https://docs.matias-api.com/docs/endpoints/webhooks.md): Webhooks salientes: alta y gestión, catálogo de eventos, formato del evento, firma HMAC, reintentos e historial de entregas.
- [Empresa](https://docs.matias-api.com/docs/endpoints/company.md): Datos de la empresa y gestión de clientes y sub-cuentas para Casas de Software: alta, listado, habilitación, estadísticas, logo y configuración.
- [Perfil](https://docs.matias-api.com/docs/endpoints/profile.md): Perfil del usuario autenticado: datos, tipos de usuario, imagen y cambio de correo.
- [Resoluciones DIAN](https://docs.matias-api.com/docs/endpoints/dian-resolutions.md): Resoluciones de numeración DIAN: creación manual, consulta, actualización, eliminación y sincronización con la DIAN.
- [Software DIAN](https://docs.matias-api.com/docs/endpoints/dian-software.md): Software DIAN de la empresa: registro, consulta, actualización y eliminación del identificador y PIN por tipo de documento.
- [Certificado de Firma Digital](https://docs.matias-api.com/docs/endpoints/digital-certificate.md): Certificado de firma digital (.p12/.pfx): carga, renovación, consulta y vencimiento, y cupos de certificado incluidos en el plan.
- [Plantillas de Empresa (Company Templates)](https://docs.matias-api.com/docs/endpoints/company-templates.md): Plantillas de la representación gráfica (PDF): asignación, personalización, vista previa y datos adicionales en el PDF.
- [Gestión de Monedas](https://docs.matias-api.com/docs/endpoints/currencies.md): Monedas y tasas de cambio de la empresa para documentos en moneda extranjera.
- [Configuración de Reportes](https://docs.matias-api.com/docs/endpoints/report-settings.md): Encabezado de reportes y PDF: datos de contacto, logo y configuración por empresa.
- [Registros de Email](https://docs.matias-api.com/docs/endpoints/email-logs.md): Registros de los correos enviados a los adquirentes: estado de entrega, rebotes, aperturas y avisos de correos no entregados.
- [Envío Masivo (Bulk) — Referencia de Endpoints](https://docs.matias-api.com/docs/endpoints/bulk-documents.md): Referencia de endpoints del envío masivo asíncrono: crear lote, consultar lote e items y listar lotes.
- [Marca Blanca de Correos](https://docs.matias-api.com/docs/endpoints/email-branding.md): Marca blanca de los correos que el API envía en nombre de tus empresas: logo, colores, textos y vista previa por tipo de correo.

## Referencia

- [Envío Masivo de Documentos (Bulk)](https://docs.matias-api.com/docs/bulk-documents.md): Guía completa del envío masivo asíncrono de documentos electrónicos (facturas, notas crédito/débito, documentos soporte, notas de ajuste y documentos POS) con estados, errores, idempotencia y webhook.
- [Campos de todos los documentos electrónicos](https://docs.matias-api.com/docs/billing-fields.md): En esta sección se describen todos los campos que se deben considerar para la generación de factura electrónica, nota de crédito y nota de débito, documento soporte y documento equivalente, con sus respectivas notas…
- [Respuestas de la API](https://docs.matias-api.com/docs/response-json.md): Formato de las respuestas y errores de la API: emisión exitosa, rechazo de la DIAN, advertencias (warnings), códigos HTTP y formato de los errores.

## Ejemplos JSON — Facturación

- [Factura](https://docs.matias-api.com/docs/jsons-billing/invoice.md): A continuación se muestra un ejemplo de un JSON que representa una factura. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura a crédito](https://docs.matias-api.com/docs/jsons-billing/credit-invoice.md): A continuación se muestra un ejemplo de un JSON que representa una factura a crédito. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura con consumidor final](https://docs.matias-api.com/docs/jsons-billing/invoice-final-consumer.md): A continuación se muestra un ejemplo de un JSON que representa una factura para consumidor final, Solo se omite el objeto customer.
- [Factura con Impuesto al Consumo de Bolsa Plástica](https://docs.matias-api.com/docs/jsons-billing/invoice-with-box-tax.md): A continuación se muestra un ejemplo de un JSON que representa una factura con regalo. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura con varios impuestos](https://docs.matias-api.com/docs/jsons-billing/invoice-with-taxes.md): A continuación se muestra un ejemplo de un JSON que representa una factura con varios impuestos. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura con Cargos](https://docs.matias-api.com/docs/jsons-billing/invoice-with-charges.md): A continuación se muestra un ejemplo de un JSON que representa una factura con cargos. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura con Descuento](https://docs.matias-api.com/docs/jsons-billing/invoice-with-discount.md): A continuación se muestra un ejemplo de un JSON que representa una factura con cargos. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura con cargos + IVA - descuentos](https://docs.matias-api.com/docs/jsons-billing/invoice-with-taxes-charges-discounts.md): A continuación se muestra un ejemplo de un JSON que representa una factura con cargos + IVA - descuentos. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura con Propina](https://docs.matias-api.com/docs/jsons-billing/invoice-with-tip.md): A continuación se muestra un ejemplo de un JSON que representa una factura con cargos. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura con Propina con IVA](https://docs.matias-api.com/docs/jsons-billing/invoice-with-tip-tax.md): A continuación se muestra un ejemplo de un JSON que representa una factura con cargos. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura con datos extra](https://docs.matias-api.com/docs/jsons-billing/invoice-extra-data.md): A continuación se muestra un ejemplo de un JSON que representa una factura. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura con Retenciones](https://docs.matias-api.com/docs/jsons-billing/invoice-with-retentions-example.md): A continuación se muestra un ejemplo de un JSON que representa una factura con retenciones. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura AIU](https://docs.matias-api.com/docs/jsons-billing/AIU-invoice.md): A continuación se muestra un ejemplo de un JSON que representa una factura AIU. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura partida arancelaria](https://docs.matias-api.com/docs/jsons-billing/invoice-tariff.md): A continuación se muestra un ejemplo de un JSON que representa una factura.
- [Factura con Item de Regalo](https://docs.matias-api.com/docs/jsons-billing/invoice-with-gift.md): A continuación se muestra un ejemplo de un JSON que representa una factura con regalo. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura con Item de Regalo con impuesto](https://docs.matias-api.com/docs/jsons-billing/invoice-with-gift-tax.md): A continuación se muestra un ejemplo de un JSON que representa una factura con regalo. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura en USD](https://docs.matias-api.com/docs/jsons-billing/USD-invoice.md): A continuación se muestra un ejemplo de un JSON que representa una factura en dólares. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura en USD Exportación](https://docs.matias-api.com/docs/jsons-billing/USD-invoice-exportation.md): A continuación se muestra un ejemplo de un JSON que representa una factura en dólares. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura en Euros](https://docs.matias-api.com/docs/jsons-billing/EURO-invoice.md): A continuación se muestra un ejemplo de un JSON que representa una factura en euros. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura de Exportación (USD)](https://docs.matias-api.com/docs/jsons-billing/invoice-exportation.md): Ejemplo de JSON avanzado para una factura de exportación en USD con Incoterms, remisiones, datos de entrega y transportadora.
- [Factura venta de divisas](https://docs.matias-api.com/docs/jsons-billing/currency-sale.md): A continuación se muestra un ejemplo de un JSON que representa una factura. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Factura compra de divisas](https://docs.matias-api.com/docs/jsons-billing/currency-purchase.md): A continuación se muestra un ejemplo de un JSON que representa una factura. Este JSON se puede utilizar para pruebas o para simular una factura real.
- [Nota Crédito](https://docs.matias-api.com/docs/jsons-billing/credit-note.md): A continuación se muestra un ejemplo de un JSON que representa una nota crédito. Este JSON se puede utilizar para pruebas o para simular una nota crédito real.
- [Nota Crédito sin referencia a factura](https://docs.matias-api.com/docs/jsons-billing/credit-note-without-reference-to-invoice.md): A continuación se muestra un ejemplo de un JSON que representa una nota crédito. Este JSON se puede utilizar para pruebas o para simular una nota crédito real.
- [Nota Débito](https://docs.matias-api.com/docs/jsons-billing/debit-note.md): A continuación se muestra un ejemplo de un JSON que representa una nota débito. Este JSON se puede utilizar para pruebas o para simular una nota débito real.
- [Factura de Contingencia Tipo 03 (Talonario o Papel)](https://docs.matias-api.com/docs/jsons-billing/contingency-invoice-type-03.md): Factura electrónica emitida como transmisión digital de una factura física (talonario/papel) previamente entregada al cliente durante un inconveniente tecnológico. Este tipo de factura NO es una factura nueva, sino…
- [Factura de Contingencia Tipo 04 (Manual)](https://docs.matias-api.com/docs/jsons-billing/contingency-invoice-type-04.md): Factura electrónica emitida como respaldo de un documento generado manualmente o mediante proceso manual. Similar a la tipo 03, pero sin la obligatoriedad de additionaldocumentreference.
- [Nota Crédito para Factura de Contingencia Tipo 03](https://docs.matias-api.com/docs/jsons-billing/credit-note-type-03.md): Las notas crédito/débito NO tienen esquema de contingencia. Para generar una nota que afecte a una factura de contingencia Tipo 03, primero debe transmitir la factura Tipo 03 a la DIAN, obtener el CUFE asignado, y…
- [Factura Mandatos](https://docs.matias-api.com/docs/jsons-billing/mandate-invoice.md): Factura que incluye información de mandatarios en los ítems. Los mandatos aplican cuando se venden productos o servicios en nombre de terceros.
- [Factura con Impuesto Nominal](https://docs.matias-api.com/docs/jsons-billing/invoice-with-nominal-tax.md): A continuación se muestra un ejemplo de un JSON que representa una factura con impuesto nominal (valor fijo por unidad). Este tipo de impuesto no se calcula como un porcentaje sobre una base gravable, sino como un…
- [Factura Impuesto Licores - AD VALOREM](https://docs.matias-api.com/docs/jsons-billing/invoice-licores-ad-valorem.md): A continuación se muestra un ejemplo de un JSON que representa una factura con Impuesto al Consumo de Licores bajo la modalidad Ad Valorem (porcentual). A diferencia del impuesto nominal, el Ad Valorem se calcula…
- [Factura Electrónica del Sector Salud](https://docs.matias-api.com/docs/jsons-billing/invoice-health-sector.md): Ejemplo de payload JSON para Factura Electrónica del Sector Salud con soporte RIPS según la Resolución 000948 de 2026 y Documento Técnico 2 del MinSalud.
- [Nota Crédito del Sector Salud](https://docs.matias-api.com/docs/jsons-billing/credit-note-health-sector.md): Ejemplo de payload JSON para Nota Crédito Electrónica del Sector Salud con soporte RIPS según la Resolución 000948 de 2026 y Documento Técnico 2 del MinSalud.

## Ejemplos JSON — POS

- [P.O.S Electrónico](https://docs.matias-api.com/docs/jsons-pos/pos.md): A continuación se muestra un ejemplo de un JSON que representa una factura de P.O.S Electrónico. Este JSON se puede utilizar para pruebas o para simular un punto de venta real.
- [P.O.S consumidor final](https://docs.matias-api.com/docs/jsons-pos/pos-final-consumer.md): A continuación se muestra un ejemplo de un JSON que representa una factura de P.O.S Electrónico para consumidor final. Este JSON se puede utilizar para pruebas o para simular un punto de venta real.
- [P.O.S con descuento](https://docs.matias-api.com/docs/jsons-pos/pos-with-discount.md): A continuación se muestra un ejemplo de un JSON que representa una factura de P.O.S Electrónico para consumidor final. Este JSON se puede utilizar para pruebas o para simular un punto de venta real.
- [Nota Débito P.O.S.](https://docs.matias-api.com/docs/jsons-pos/pos-debit-note.md): A continuación se muestra un ejemplo de un JSON que representa una nota débito P.O.S. Este JSON se puede utilizar para pruebas o para simular una nota débito real.
- [Nota Crédito P.O.S](https://docs.matias-api.com/docs/jsons-pos/pos-credit-note.md): A continuación se muestra un ejemplo de un JSON que representa una nota crédito P.O.S. Este JSON se puede utilizar para pruebas o para simular una nota crédito real.

## Ejemplos JSON — Documento Soporte

- [Documento soporte residente](https://docs.matias-api.com/docs/jsons-support-document/support-document.md): A continuación se muestra un ejemplo de un JSON que representa un documento soporte. Este JSON se puede utilizar para pruebas o para simular un documento soporte real.
- [Documento soporte no residente](https://docs.matias-api.com/docs/jsons-support-document/support-document-non-residents.md): A continuación se muestra un ejemplo de un JSON que representa un documento soporte. Este JSON se puede utilizar para pruebas o para simular un documento soporte real.
- [Notas de ajuste documento soporte residente](https://docs.matias-api.com/docs/jsons-support-document/adjustment-note.md): A continuación se muestra un ejemplo de un JSON que representa un documento soporte de nota de ajuste. Este JSON se puede utilizar para pruebas o para simular un documento soporte real.
- [Notas de ajuste documento soporte no residente](https://docs.matias-api.com/docs/jsons-support-document/adjustment-note-non-residents.md): A continuación se muestra un ejemplo de un JSON que representa un documento soporte de nota de ajuste. Este JSON se puede utilizar para pruebas o para simular un documento soporte real.

## Ejemplos JSON — Nómina

- [Campos de la nómina](https://docs.matias-api.com/docs/payroll/payroll-fields.md): La nómina electrónica es un documento que contiene información detallada de los pagos y deducciones que se le realizan
- [Campos de la nómina de reemplazo](https://docs.matias-api.com/docs/payroll/payroll-replace.md): Los campos de la nómina de reemplazo son los campos que se utilizan para calcular la nómina de un empleado que ha sido reemplazado
- [Nómina de eliminación](https://docs.matias-api.com/docs/payroll/payroll-delete.md)

## Casos de Uso

- [Guía: Factura Electrónica Simple](https://docs.matias-api.com/docs/use-cases/simple-invoice.md): Guía paso a paso para emitir una factura electrónica simple
- [Guía: Factura con Descuentos](https://docs.matias-api.com/docs/use-cases/invoice-with-discounts.md): Guía completa para emitir facturas electrónicas con descuentos comerciales
- [Guía: Exportaciones e Internacionalización](https://docs.matias-api.com/docs/use-cases/export-scenarios.md): Guía completa para emitir facturas de exportación y ventas internacionales
- [Guía: Errores Comunes y Soluciones](https://docs.matias-api.com/docs/use-cases/common-errors.md): Guía para identificar y solucionar errores comunes

## Sandbox

- [Quickstart](https://docs.matias-api.com/docs/sandbox/quickstart.md): Guía rápida para integrar con el sandbox de MATIAS API en 5 minutos.
- [Magic Values](https://docs.matias-api.com/docs/sandbox/magic-values.md): 32 valores de simulación para probar diferentes respuestas de la DIAN en el sandbox.
- [Test Certificate](https://docs.matias-api.com/docs/sandbox/test-cert.md): Certificado de prueba autogenerado para firmar documentos digitalmente en el sandbox.
- [Colección Postman](https://docs.matias-api.com/docs/sandbox/postman.md): Colección de 43 requests listas para usar y probar la integración en el sandbox.

## Recursos

- [Glosario Técnico](https://docs.matias-api.com/docs/glossary.md): Glosario de términos técnicos, normativas y acrónimos de facturación electrónica, DIAN y Sector Salud (Resolución 000948 de 2026)
- [Herramientas Interactivas](https://docs.matias-api.com/docs/interactive-tools.md): Herramientas interactivas para validar y calcular valores de facturas

## Optional

- [Documentación completa en un solo archivo](https://docs.matias-api.com/llms-full.txt): todas las páginas de este índice concatenadas
- [Especificación OpenAPI 3 (JSON)](https://docs.matias-api.com/openapi.json): endpoints públicos, parámetros y esquemas
- [Colección Postman Sandbox Quickstart (JSON)](https://docs.matias-api.com/sandbox-quickstart.postman_collection.json): flujo mínimo de integración contra el sandbox
- [Colección Postman completa (JSON)](https://docs.matias-api.com/postman_collection.json): todos los endpoints con ejemplos; archivo grande (más de 5 MB)
- [Notas de versión](https://docs.matias-api.com/blog): cambios de la API y de la documentación