Inicio rápido

En esta guía emitirás una factura (DTE 01) en el ambiente de pruebas del Ministerio de Hacienda, revisarás el resultado y descargarás el PDF.

1. Crea tu cuenta y una API key de pruebas

   Regístrate en app.sudte.com. En Desarrolladores, crea una API key del ambiente de pruebas: empieza con sk_test_ y solo se muestra una vez. Guárdala en una variable de entorno:

   export SUDTE_API_KEY="sk_test_..."

2. Registra tu emisor

   En el panel, en Emisores, registra tu empresa con NIT, NRC, actividad económica, dirección y al menos un establecimiento con su punto de venta (por ejemplo M001 y P001). Después carga tus credenciales de pruebas del MH: el certificado .crt, la clave de la llave privada y la contraseña de la API. Copia el identificador del emisor (emi_…).

   Nota

   También puedes hacerlo por API con POST /v1/emitters y PUT /v1/emitters/{id}/credentials. Si aún no tienes credenciales de pruebas del MH, revisa la sección «Cómo obtener tus credenciales de pruebas» del sandbox.

3. Valida sin emitir con dry_run

   Envía la factura con dry_run=true: sudte calcula y valida contra el esquema oficial, pero no firma, no transmite ni consume número de control.

   curl "https://api.sudte.com/v1/documents?dry_run=true" \
     -H "Authorization: Bearer $SUDTE_API_KEY" \
     -H "Idempotency-Key: prueba-dry-run-1" \
     -H "Content-Type: application/json" \
     -d '{
       "emitter_id": "emi_...",
       "type": "01",
       "establishment": "M001",
       "point_of_sale": "P001",
       "items": [
         { "description": "Café molido 1 lb", "quantity": "2", "unit_price": "8.50", "tax": "gravada" }
       ],
       "payment": { "condition": "1", "methods": [{ "code": "01", "amount": "17.00" }] }
     }'

   La respuesta 200 trae los totales calculados. Si falta algo, recibes 422 con la lista de campos a corregir.

4. Emite la factura

   Repite la llamada sin dry_run y con una Idempotency-Key nueva. En modo síncrono, la respuesta llega cuando el MH otorga el sello:

   cURL

   curl https://api.sudte.com/v1/documents \
     -H "Authorization: Bearer $SUDTE_API_KEY" \
     -H "Idempotency-Key: venta-000123" \
     -H "Content-Type: application/json" \
     -d @factura.json

   Node.js

   const res = await fetch('https://api.sudte.com/v1/documents', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.SUDTE_API_KEY}`,
       'Idempotency-Key': 'venta-000123',
       'Content-Type': 'application/json',
     },
     body: JSON.stringify(factura),
   });
   const dte = await res.json();

   Python

   r = requests.post(
       "https://api.sudte.com/v1/documents",
       headers={"Authorization": f"Bearer {api_key}", "Idempotency-Key": "venta-000123"},
       json=factura,
       timeout=30,
   )
   dte = r.json()

   201 Created

   {
     "id": "doc_01JA2M7R5N3P8Q4S6T0V2W4X6Y",
     "object": "document",
     "type": "01",
     "environment": "00",
     "status": "processed",
     "control_number": "DTE-01-M001P001-000000000000001",
     "generation_code": "8C1F7E2A-4B6D-4E3A-9F1C-2D5B7A9E0C34",
     "reception_stamp": "2026A3F9C1D47E8B4F2A9C0D6E1B5A7C3F8D2E4B",
     "totals": { "subtotal": "17.00", "iva": "1.96", "total": "17.00", "total_in_words": "DIECISIETE 00/100 DÓLARES" },
     "pdf_url": "https://api.sudte.com/v1/documents/doc_01JA2M7R5N3P8Q4S6T0V2W4X6Y/pdf",
     "json_url": "https://api.sudte.com/v1/documents/doc_01JA2M7R5N3P8Q4S6T0V2W4X6Y/json"
   }

   Si el MH tarda más de 20 segundos, recibes 202 Accepted con status: "sending" y el resultado llega por webhook.

5. Descarga el PDF y el JSON firmado

   curl -o factura.pdf https://api.sudte.com/v1/documents/doc_.../pdf \
     -H "Authorization: Bearer $SUDTE_API_KEY"
   curl -o factura.json https://api.sudte.com/v1/documents/doc_.../json \
     -H "Authorization: Bearer $SUDTE_API_KEY"

   El PDF del ambiente de pruebas lleva la leyenda «sin valor legal». Puedes verificar el documento en la consulta pública del MH con el enlace public_url (el mismo del QR).

¿Y ahora?

• Configura un webhook para enterarte de sellos, rechazos e invalidaciones sin consultar.
• Lee las particularidades de cada tipo: factura, crédito fiscal, nota de crédito y nota de débito.
• Cuando el MH autorice a tu emisor, carga las credenciales de producción y cambia a una key sk_live_.