Inicio Rápido: API REST

Introducción

El Servicio REST de Timbrado de CFDI de NTLink permite a los emisores de comprobantes fiscales digitales automatizar el proceso de validación y certificación (timbrado) de sus documentos. Este servicio expone un endpoint que recibe un CFDI en formato JSON sin timbrar y devuelve el Timbre Fiscal Digital del comprobante.

Esta documentación está destinada a orientar a desarrolladores en la correcta integración del servicio REST en sus aplicaciones de facturación electrónica.

Características del Servicio

• Integración Sencilla: Se implementa sobre el protocolo HTTP utilizando el estándar REST, facilitando su integración.
• Seguridad: Toda la comunicación se realiza a través de HTTPS y se requiere autenticación (usuario y contraseña) para garantizar un acceso seguro y controlado.
• Compatibilidad: El servicio cumple con la versión 4.0 del CFDI, asegurando que los documentos emitidos estén en conformidad con las disposiciones vigentes del SAT.
• Automatización del Proceso: Permite enviar lotes o peticiones individuales para timbrar CFDI, lo que optimiza la eficiencia operativa de los sistemas de facturación.

Requisitos previos ⚠️

Para ejecutar esta guía de inicio rápido, necesitas cumplir con los siguientes requisitos:

1. Descargar e instalar Postman: Puedes descargarlo aquí.
2. Conocer la estructura del CFDI versión 4.0: Puedes consultarla en la sección Conoce la estructura CFDI 4.0 💭.
3. Contar con credenciales de acceso al sandbox de pruebas: Para obtener tus credenciales de prueba, completa tu registro aquí y recibirás un correo con tu contraseña.

Paso a paso para generar tu primer CFDI timbrado

1. Configuración del entorno

Descarga e instala Postman. Haz clic aquí para descargarlo.

2. Crea una petición POST a la API de timbrado

Crea una petición POST al siguiente endpoint:

POST http://dev-cfdi4.ntlink.com.mx/api/v1/cfdis/timbraSinSello
Authorization: Basic VVJFMTgwNDI5VE02QG50bGluay5jb20ubXg6TlRQcnVlYmFzLjIwMjEqPw==

El servicio de NTLink utiliza autenticación básica (Basic Auth). Si estás usando Postman, selecciona la opción Basic Auth en la pestaña Authorization y coloca tus datos de acceso. En caso de que necesites calcular manualmente la cabecera de autenticación, sigue estos pasos:

Dados los siguientes accesos de prueba:

Usuario: URE180429TM6@ntlink.com.mx
Contraseña: NTPruebas.2021*?

Paso 1: Concatena el usuario y la contraseña con dos puntos (<usuario>:<contraseña>):
URE180429TM6@ntlink.com.mx:NTPruebas.2021*?

Paso 2: Convierte la cadena anterior a formato Base64. El resultado debe ser:
VVJFMTgwNDI5VE02QG50bGluay5jb20ubXg6TlRQcnVlYmFzLjIwMjEqPw==

Paso 3: Agrega la cabecera (header) de autorización en tu petición de la siguiente manera:
Authorization: Basic VVJFMTgwNDI5VE02QG50bGluay5jb20ubXg6TlRQcnVlYmFzLjIwMjEqPw==

También puedes usar este generador de autenticación básica de DebugBear si te resulta más sencillo.

3. Configuración de la solicitud

Utiliza las credenciales proporcionadas anteriormente para autenticar tus peticiones en el ambiente de pruebas. Prepara el CFDI en formato JSON según los lineamientos de la versión 4.0. Puedes encontrar ejemplos detallados en la sección Ejemplos JSON de CFDI 4.0 y Complementos.

Coloca la URL del servicio a utilizar y selecciona el método POST:

El archivo JSON debe colocarse dentro de la pestaña Body de la solicitud, seleccionando el formato JSON (raw):

A nivel de arquitectura de datos, los nodos principales del CFDI 4.0 se representan en JSON como un objeto raíz con subobjetos estructurados. A continuación, se presenta la estructura estándar, alineada con las mejores prácticas de integración y diseñada para mapearse fácilmente contra el XML (Anexo 20):

{
    "version": "4.0",
    "folio": "202601060559062048",
    "fecha": "2026-01-25T19:23:27",
    "formaPago": "03",
    "metodoPago": "PUE",
    "subtotal": 250456.00,
    "total": 290528.96,
    "moneda": "MXN",
    "tipoCambio": 1,
    "tipoDeComprobante": "I",
    "exportacion": "01",
    "lugarExpedicion": "06370",
    "emisor": {
        "rfc": "URE180429TM6",
        "nombre": "UNIVERSIDAD ROBOTICA ESPAÑOLA SA DE CV",
        "regimenFiscal": "601"
    },
    "receptor": {
        "rfc": "SME170525C62",
        "nombre": "SURETE MEXICO",
        "domicilioFiscalReceptor": "01000",
        "regimenFiscalReceptor": "601",
        "usoCfdi": "G03"
    },
    "conceptos": [
        {
            "claveProdServ": "26101101",
            "cantidad": 1,
            "claveUnidad": "H87",
            "unidad": "Pieza",
            "descripcion": "Motor electrico tesla",
            "valorUnitario": 250456,
            "importe": 250456,
            "objetoImp": "02",
            "impuestos": {
                "traslados": [
                    {
                        "base": 250456.000000,
                        "impuesto": "002",
                        "tipoFactor": "Tasa",
                        "tasaOCuota": 0.160000,
                        "importe": 40072.960000
                    }
                ]
            }
        }
    ],
    "impuestos": {
        "traslados": [
            {
                "base": 250456.00,
                "impuesto": "002",
                "tipoFactor": "Tasa",
                "tasaOCuota": 0.160000,
                "importe": 40072.96
            }
        ],
        "totalImpuestosTrasladados": 40072.96,
        "totalImpuestosRetenidos": 0.00
    },
    "complemento": {}
}

Este JSON debe cumplir con el estándar del CFDI 4.0 y validarse correctamente para su uso fiscal. Puedes consultar el esquema XSD en el siguiente enlace:

• 📚 Documentación Técnica CFDI (XSD)

Del mismo modo, puedes consultar los catálogos establecidos por el SAT en el siguiente enlace:

• 📓 Catálogos SAT

Para conocer a detalle la información de cada atributo, haz clic en la sección:

• Conoce la estructura CFDI 4.0 💭

Si necesitas ejemplos específicos del CFDI y sus complementos, consulta el siguiente enlace:

• Ejemplos CFDI 4.0 y Complementos 📂

4. Realiza la prueba de timbrado

1. Una vez configurados los parámetros de autenticación y el cuerpo de la solicitud (body), haz clic en el botón Send (Enviar).
2. Se procesará la solicitud y el servicio devolverá la respuesta.

Si el timbrado es exitoso, se devolverá el CFDI completamente timbrado en formato JSON:

Si la solicitud contiene errores, la respuesta mostrará el código de error y el detalle correspondiente:

¡Felicidades! Has realizado tu primer timbrado de CFDI.

Si necesitas apoyo o tienes dudas adicionales, no dudes en ponerte en contacto con nuestro equipo de soporte haciendo clic aquí. Menciona que nos consultas desde la wiki de desarrolladores de NTLink y un asesor especializado te atenderá de inmediato.

Si deseas integrarte de manera programática, te recomendamos visitar la sección de Ejemplos de código.

5. Solicita tus accesos al entorno de producción

Para darte de alta en nuestro servicio y obtener tus accesos de producción, contáctanos a través de cualquiera de nuestros canales oficiales. Menciona que eres desarrollador y que nos consultas desde la wiki de soporte, y un especialista te atenderá a la brevedad.