Evento de Retorno (DTE 18)

El Evento de Retorno (DTE tipo 18) se utiliza para registrar devoluciones, retornos o reversiones parciales o totales de bienes o servicios asociados a documentos previamente emitidos y procesados.

Restricciones Importantes

Tipos de Documento Permitidos: Únicamente se puede aplicar un Evento de Retorno sobre Facturas de Consumidor Final (DTE-01) y Facturas de Sujeto Excluido (DTE-14).
Estado del Documento: El DTE original de origen debe encontrarse en estado PROCESSED (aceptado por el Ministerio de Hacienda).
Control de Cantidades (Sobre-retorno): El sistema valida que la cantidad a devolver, sumada a cualquier devolución previa del mismo ítem, no supere la cantidad original registrada en el DTE de origen.

Endpoint

POST /dte/retorno

(Consulta la guía de Endpoints y Entornos para obtener la URL base según el ambiente).

Estructura del Payload (JSON)

Para realizar una solicitud de Evento de Retorno, debes enviar la identificación del documento de origen, los ítems a devolver con sus cantidades correspondientes y el motivo de la devolución.

Ejemplo de Payload

{
  "documentoOrigen": "0F0169B1-2813-4A0E-9E9D-FADBE39F641F",
  "items": [
    {
      "numItem": 1,
      "cantidadRetorno": 1
    }
  ],
  "motivo": "Devolución parcial de corte de cabello",
  "apendice": null
}

Campos del Payload

Campo	Tipo	Requerido	Descripción
`documentoOrigen`	string	Sí	Código de Generación (UUID) del DTE original (DTE-01 o DTE-14) que se va a afectar.
`items`	array	Sí	Lista de ítems que se están retornando. Debe contener al menos un elemento.
`items[].numItem`	number	Sí	Número correlativo del ítem (`numItem`) tal y como aparece en el cuerpo del DTE original.
`items[].cantidadRetorno`	number	Sí	Cantidad de unidades a retornar (debe ser mayor a `0` y menor o igual a la cantidad disponible).
`motivo`	string	Sí	Descripción o justificación de la devolución o retorno.
`apendice`	array	No	Datos o metadatos adicionales opcionales adjuntos al DTE.

Respuestas de la API

El endpoint retorna el detalle completo del documento de retorno creado y firmado junto con el resultado del Ministerio de Hacienda.

Respuesta Exitosa (201 Created)

{
  "status": "success",
  "data": {
    "id": 1007,
    "tipo": "RETORNO",
    "codigoGeneracion": "E7B2C3D4-E5F6-7A8B-9C0D-1E2F3A4B5C6D",
    "numeroControl": "DTE-18-M001P001-000000000000030",
    "estado": "PROCESSED",
    "ambiente": "TEST",
    "total": "20.00",
    "dteJson": {
      // Estructura interna del DTE de retorno enviado a Hacienda
    },
    "dteFirmado": "eyJhbGciOiJSUzUxMiJ9.eyJpZGVudGlmaWNhY2lvbiI6ey...",
    "selloRecibido": "20261A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P",
    "respuestaMh": {
      "estado": "PROCESSED",
      "version": 2,
      "ambiente": "00",
      "codigoMsg": "001",
      "versionApp": 2,
      "clasificaMsg": "10",
      "observaciones": [],
      "selloRecibido": "20261A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P",
      "descripcionMsg": "RECIBIDO",
      "fhProcesamiento": "08/06/2026 23:05:12",
      "codigoGeneracion": "E7B2C3D4-E5F6-7A8B-9C0D-1E2F3A4B5C6D"
    },
    "dteJsonUrl": "emisores/empresa-pruebas/DTES/TEST/2026/06/08/DTE18/json/E7B2C3D4-E5F6-7A8B-9C0D-1E2F3A4B5C6D.json",
    "dtePdfUrl": "emisores/empresa-pruebas/DTES/TEST/2026/06/08/DTE18/pdf/E7B2C3D4-E5F6-7A8B-9C0D-1E2F3A4B5C6D.pdf",
    "sequenceNumber": "30",
    "sequenceId": 45,
    "serie": "P001",
    "emisorId": 2,
    "branchId": 3,
    "pointOfSaleId": 10,
    "tokenId": 22,
    "errorTecnico": null,
    "createdAt": "2026-06-08T23:05:11.000Z",
    "analisisHacienda": {
      "estadoDocumento": "PROCESSED",
      "aceptadoPorMH": true,
      "tieneObservaciones": false,
      "observaciones": [],
      "erroresValidacion": [],
      "mensaje": "Documento procesado exitosamente"
    }
  }
}

Errores Comunes de Validación

Código de Error (type)	HTTP Status	Causa Común
`VALIDATION_ERROR`	`400`	Campos faltantes en el payload (`documentoOrigen`, `items`, `motivo`) o tipo de datos incorrecto.
`DOCUMENT_NOT_FOUND`	`404`	El `documentoOrigen` especificado no existe en la base de datos local.
`INVALID_ORIGIN_TYPE`	`400`	El DTE original no es del tipo `FACTURA_CONSUMIDOR_FINAL` ni `SUJETO_EXCLUIDO`.
`INVALID_ORIGIN_STATUS`	`400`	El DTE original no está en estado `PROCESSED`.
`PERMISSION_DENIED`	`403`	El token del emisor no posee permisos para operar sobre este tipo de documento.
`ITEM_NOT_FOUND`	`400`	Uno de los valores de `numItem` provistos en el arreglo `items` no existe en el DTE original.
`OVER_RETURN_ERROR`	`400`	La cantidad solicitada a retornar excede la cantidad total disponible del ítem original (restando devoluciones previas).