Emitir un DTE

POST

/documents

const url = 'https://api.sudte.com/v1/documents?mode=sync&dry_run=false';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"emitter_id":"emi_01HZY","type":"01","establishment":"M001","point_of_sale":"P001","external_id":"odoo-account.move-1542","receiver":{"name":"Cliente final","email":"cliente@example.com"},"items":[{"description":"Servicio de soporte","quantity":"1","unit_price":"113.00","unit_code":"59","tax":"gravada"}],"payment":{"condition":"1","methods":[{"code":"01","amount":"113.00"}]}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url 'https://api.sudte.com/v1/documents?mode=sync&dry_run=false' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "emitter_id": "emi_01HZY", "type": "01", "establishment": "M001", "point_of_sale": "P001", "external_id": "odoo-account.move-1542", "receiver": { "name": "Cliente final", "email": "cliente@example.com" }, "items": [ { "description": "Servicio de soporte", "quantity": "1", "unit_price": "113.00", "unit_code": "59", "tax": "gravada" } ], "payment": { "condition": "1", "methods": [ { "code": "01", "amount": "113.00" } ] } }'

Sudte calcula, arma el JSON oficial, valida contra el esquema del MH, firma, transmite y devuelve el sello. mode=sync (por defecto) espera hasta 20 s; si MH no responde a tiempo devuelve 202 y notifica por webhook. dry_run=true valida y calcula sin firmar ni transmitir (sin costo).

Autorización

apiKey
session

Parámetros

Cabeceras

Idempotency-Key

obligatorio

string

<= 255 characters

Parámetros de consulta

mode

string

default: sync

Allowed values: sync async

dry_run

boolean

Cuerpo de la solicitud^obligatorio

application/json

object

emitter_id

obligatorio

string

type

obligatorio

CAT-002. Semana 1 implementa 01, 03, 05 y 06.

string

Allowed values: 01 03 04 05 06 07 08 09 11 14 15

establishment

obligatorio

Código MH del establecimiento (4)

string

point_of_sale

obligatorio

Código MH del punto de venta (4)

string

external_id

Id en el sistema del cliente (ej. Odoo)

string

issued_at

Por defecto ahora; holgura máxima 30 min

string format: date-time

receiver

Requerido según tipo. En FE puede omitirse si el total es menor al umbral del Aviso DGII ($25,000).

object

name

string

document_type

CAT-022 (36 NIT, 13 DUI, 37 otro, 03 pasaporte, 02 carnet residente)

string

document_number

string

nrc

string

economic_activity

CAT-019

string

trade_name

string

address

object

department

CAT-012

string

municipality

CAT-013

string

district

CAT-008

string

line

string

email

string format: email

phone

string

country

CAT-020 (exportación)

string

items

obligatorio

Array<object>

>= 1 items <= 2000 items

object

type

CAT-011

string

default: 1

Allowed values: 1 2 3 4

code

string

description

obligatorio

string

<= 1000 characters

quantity

obligatorio

string

/^-?\d+(\.\d{1,8})?$/

unit_code

CAT-014

string

default: 59

unit_price

obligatorio

FE: con IVA. CCF/NC/ND: sin IVA.

string

/^-?\d+(\.\d{1,8})?$/

discount

string

/^-?\d+(\.\d{1,8})?$/

tax

obligatorio

string

Allowed values: gravada exenta no_sujeta

taxes

Tributos CAT-015 adicionales

Array<string>

related_document

CodigoGeneracion relacionado (NC/ND)

string

global_discount

object

gravada

string

/^-?\d+(\.\d{1,8})?$/

exenta

string

/^-?\d+(\.\d{1,8})?$/

no_sujeta

string

/^-?\d+(\.\d{1,8})?$/

withholding

object

iva_1

boolean

renta

string

/^-?\d+(\.\d{1,8})?$/

perception

Percepción IVA 1%

boolean

payment

object

condition

CAT-016

string

Allowed values: 1 2 3

methods

Array<object>

object

code

CAT-017

string

amount

string

/^-?\d+(\.\d{1,8})?$/

reference

string

term

CAT-018

string

period

integer

related_documents

Array<object>

object

type

CAT-002. Semana 1 implementa 01, 03, 05 y 06.

string

Allowed values: 01 03 04 05 06 07 08 09 11 14 15

generation_code

string

issued_on

string format: date

notes

string

appendix

Array<object>

<= 10 items

object

field

string

label

string

value

string

raw

Avanzado. JSON MH ya armado (sin firma); sudte solo valida, firma y transmite.

object

send_email

boolean

default: true

environment

Solo con sesión del panel (por defecto 00). Con API key el ambiente lo determina la key y este campo se ignora

string

Allowed values: 00 01

Ejemplos

factura

Factura (01) a consumidor final

{
  "emitter_id": "emi_01HZY",
  "type": "01",
  "establishment": "M001",
  "point_of_sale": "P001",
  "external_id": "odoo-account.move-1542",
  "receiver": {
    "name": "Cliente final",
    "email": "cliente@example.com"
  },
  "items": [
    {
      "description": "Servicio de soporte",
      "quantity": "1",
      "unit_price": "113.00",
      "unit_code": "59",
      "tax": "gravada"
    }
  ],
  "payment": {
    "condition": "1",
    "methods": [
      {
        "code": "01",
        "amount": "113.00"
      }
    ]
  }
}

Respuestas

200

Resultado de dry_run (sin firmar ni transmitir)

application/json

object

string

object

Allowed value: document

emitter_id

string

environment

00 pruebas, 01 producción (CAT-001)

string

Allowed values: 00 01

type

CAT-002. Semana 1 implementa 01, 03, 05 y 06.

string

Allowed values: 01 03 04 05 06 07 08 09 11 14 15

status

string

Allowed values: draft validated signed sending processed rejected contingency voided error

external_id

string

generation_code

CodigoGeneracion

string

control_number

NumeroControl

string

reception_stamp

SelloRecibido

string

processed_at

string format: date-time

issued_at

string format: date-time

totals

object

subtotal

string

/^-?\d+(\.\d{1,8})?$/

iva

string

/^-?\d+(\.\d{1,8})?$/

total

string

/^-?\d+(\.\d{1,8})?$/

total_in_words

string

mh_response

object

code

string

message

string

observations

Array<string>

public_url

Consulta pública MH (QR)

string format: uri

pdf_url

string format: uri

json_url

string format: uri

created_at

string format: date-time

emitter_name

string

establishment

Código MH del establecimiento

string

point_of_sale

Código MH del punto de venta

string

receiver

Resumen del receptor para listados

object

name

string

document_type

string

document_number

string

nrc

string

email

string

related_documents

Array<object>

object

string

type

CAT-002. Semana 1 implementa 01, 03, 05 y 06.

string

Allowed values: 01 03 04 05 06 07 08 09 11 14 15

generation_code

string

voided_at

string format: date-time

void

Datos de la invalidación si status=voided

object

reason_type

string

reason

string

replacement_document_id

string

reception_stamp

string

warnings

Advertencias no bloqueantes (p. ej. retención no aplicada por monto menor a $100)

Array<object>

object

code

string

message

string

events

Historial (creado, firmado, transmitido, reintento, sellado, rechazado, correo enviado, invalidado)

Array<object>

object

type

string

string format: date-time

message

string

Example

{
  "object": "document",
  "environment": "00",
  "type": "01",
  "status": "draft",
  "totals": {
    "subtotal": "113.00",
    "iva": "113.00",
    "total": "113.00"
  },
  "related_documents": [
    {
      "type": "01"
    }
  ]
}

201

Documento procesado por MH

application/json

object

string

object

Allowed value: document

emitter_id

string

environment

00 pruebas, 01 producción (CAT-001)

string

Allowed values: 00 01

type

CAT-002. Semana 1 implementa 01, 03, 05 y 06.

string

Allowed values: 01 03 04 05 06 07 08 09 11 14 15

status

string

Allowed values: draft validated signed sending processed rejected contingency voided error

external_id

string

generation_code

CodigoGeneracion

string

control_number

NumeroControl

string

reception_stamp

SelloRecibido

string

processed_at

string format: date-time

issued_at

string format: date-time

totals

object

subtotal

string

/^-?\d+(\.\d{1,8})?$/

iva

string

/^-?\d+(\.\d{1,8})?$/

total

string

/^-?\d+(\.\d{1,8})?$/

total_in_words

string

mh_response

object

code

string

message

string

observations

Array<string>

public_url

Consulta pública MH (QR)

string format: uri

pdf_url

string format: uri

json_url

string format: uri

created_at

string format: date-time

emitter_name

string

establishment

Código MH del establecimiento

string

point_of_sale

Código MH del punto de venta

string

receiver

Resumen del receptor para listados

object

name

string

document_type

string

document_number

string

nrc

string

email

string

related_documents

Array<object>

object

string

type

CAT-002. Semana 1 implementa 01, 03, 05 y 06.

string

Allowed values: 01 03 04 05 06 07 08 09 11 14 15

generation_code

string

voided_at

string format: date-time

void

Datos de la invalidación si status=voided

object

reason_type

string

reason

string

replacement_document_id

string

reception_stamp

string

warnings

Advertencias no bloqueantes (p. ej. retención no aplicada por monto menor a $100)

Array<object>

object

code

string

message

string

events

Historial (creado, firmado, transmitido, reintento, sellado, rechazado, correo enviado, invalidado)

Array<object>

object

type

string

string format: date-time

message

string

Example

{
  "object": "document",
  "environment": "00",
  "type": "01",
  "status": "draft",
  "totals": {
    "subtotal": "113.00",
    "iva": "113.00",
    "total": "113.00"
  },
  "related_documents": [
    {
      "type": "01"
    }
  ]
}

202

Aceptado; en proceso o en contingencia. Se notificará por webhook

application/json

object

string

object

Allowed value: document

emitter_id

string

environment

00 pruebas, 01 producción (CAT-001)

string

Allowed values: 00 01

type

CAT-002. Semana 1 implementa 01, 03, 05 y 06.

string

Allowed values: 01 03 04 05 06 07 08 09 11 14 15

status

string

Allowed values: draft validated signed sending processed rejected contingency voided error

external_id

string

generation_code

CodigoGeneracion

string

control_number

NumeroControl

string

reception_stamp

SelloRecibido

string

processed_at

string format: date-time

issued_at

string format: date-time

totals

object

subtotal

string

/^-?\d+(\.\d{1,8})?$/

iva

string

/^-?\d+(\.\d{1,8})?$/

total

string

/^-?\d+(\.\d{1,8})?$/

total_in_words

string

mh_response

object

code

string

message

string

observations

Array<string>

public_url

Consulta pública MH (QR)

string format: uri

pdf_url

string format: uri

json_url

string format: uri

created_at

string format: date-time

emitter_name

string

establishment

Código MH del establecimiento

string

point_of_sale

Código MH del punto de venta

string

receiver

Resumen del receptor para listados

object

name

string

document_type

string

document_number

string

nrc

string

email

string

related_documents

Array<object>

object

string

type

CAT-002. Semana 1 implementa 01, 03, 05 y 06.

string

Allowed values: 01 03 04 05 06 07 08 09 11 14 15

generation_code

string

voided_at

string format: date-time

void

Datos de la invalidación si status=voided

object

reason_type

string

reason

string

replacement_document_id

string

reception_stamp

string

warnings

Advertencias no bloqueantes (p. ej. retención no aplicada por monto menor a $100)

Array<object>

object

code

string

message

string

events

Historial (creado, firmado, transmitido, reintento, sellado, rechazado, correo enviado, invalidado)

Array<object>

object

type

string

string format: date-time

message

string

Example

{
  "object": "document",
  "environment": "00",
  "type": "01",
  "status": "draft",
  "totals": {
    "subtotal": "113.00",
    "iva": "113.00",
    "total": "113.00"
  },
  "related_documents": [
    {
      "type": "01"
    }
  ]
}

409

Error (RFC 9457)

application/problem+json

object

type

string format: uri

title

string

status

integer

detail

string

instance

string

request_id

string

errors

Array<object>

object

path

string

message

string

object

codigoMsg

string

descripcionMsg

string

observaciones

Array<string>

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ],
  "mh": {
    "codigoMsg": "example",
    "descripcionMsg": "example",
    "observaciones": [
      "example"
    ]
  }
}

422

Error (RFC 9457)

application/problem+json

object

type

string format: uri

title

string

status

integer

detail

string

instance

string

request_id

string

errors

Array<object>

object

path

string

message

string

object

codigoMsg

string

descripcionMsg

string

observaciones

Array<string>

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ],
  "mh": {
    "codigoMsg": "example",
    "descripcionMsg": "example",
    "observaciones": [
      "example"
    ]
  }
}

default

Error (RFC 9457)

application/problem+json

object

type

string format: uri

title

string

status

integer

detail

string

instance

string

request_id

string

errors

Array<object>

object

path

string

message

string

object

codigoMsg

string

descripcionMsg

string

observaciones

Array<string>

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ],
  "mh": {
    "codigoMsg": "example",
    "descripcionMsg": "example",
    "observaciones": [
      "example"
    ]
  }
}

Emitir un DTE

Autorización

Parámetros

Cabeceras

Parámetros de consulta

Cuerpo de la solicitudobligatorio

Ejemplos

Respuestas

200

Example

201

Example

202

Example

409

Example generated

422

Example generated

default

Example generated

Cuerpo de la solicitud^obligatorio

Example ^generated

Example ^generated

Example ^generated