Evento de Retorno (18)

POST

/dte/{codigo}/retorno

curl --request POST \
  --url https://openfactura.co/api/v1/dte/example/retorno \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "items": [ { "descripcion": "example", "cantidad": 1, "precioUni": 1, "tipoItem": 1, "codigo": "example", "uniMedida": 1, "descuento": 1, "tipoVenta": "gravada", "seguro": 1, "flete": 1 } ] }'

• Open Factura en la nube

Devolución de bienes, reembolsos o envases sobre una Factura (01), Factura de Exportación (11) o Sujeto Excluido (14) procesados, sin invalidar el documento. precioUni como en el documento original (en Factura, con IVA). Plazo: 3 meses desde la fecha del DTE. La suma de los retornos no puede superar el documento (409 retorno_excedido con details.disponible).

Permiso: dte:emit.

Authorizations

• claveApi
• sesion

Parameters

Path Parameters

codigo

required

string

Código de generación (UUID) o id interno.

Header Parameters

Idempotency-Key

string

<= 200 characters

Hasta 200 caracteres. Repetir con la misma clave y el mismo cuerpo devuelve la respuesta original con Idempotent-Replayed: true, sin emitir dos veces; con otro cuerpo: 409 idempotencia_distinta. Se conservan 24 horas, por ambiente.

Request Body^required

Media typeapplication/json

object

items

required

Array<object>

>= 1 items <= 2000 items

object

descripcion

required

string

>= 1 characters <= 1000 characters

cantidad

required

number

> 0

precioUni

required

number

tipoItem

Any of:

number

number

Allowed value: 1

number

number

Allowed value: 2

number

number

Allowed value: 3

number

number

Allowed value: 4

codigo

Any of:

string

string

<= 25 characters

null

null

uniMedida

integer

>= 1 <= 99

descuento

number

tipoVenta

string

Allowed values: gravada exenta noSujeta

seguro

number

flete

number

Responses

201

Evento procesado.

Media typeapplication/json

object

id

required

string

tipo

required

string

Allowed values: retorno operaciones_especiales

tipoEvento

string

Allowed values: 18 17

codigoGeneracion

required

string

ambiente

required

string

Allowed values: 00 01

estado

required

string

Allowed values: procesado rechazado invalidado

selloRecibido

string | null

documentoId

Documento de un retorno.

string | null

creado

Milisegundos desde 1970.

integer

Example

{
  "tipo": "retorno",
  "tipoEvento": "18",
  "ambiente": "00",
  "estado": "procesado"
}

Headers

RateLimit-Limit

integer

Peticiones permitidas por minuto (sólo con clave de API).

RateLimit-Remaining

integer

Peticiones restantes en la ventana actual (sólo con clave de API).

RateLimit-Reset

integer

Segundos hasta que se reinicia la ventana (sólo con clave de API).

Idempotent-Replayed

string

Allowed values: true

true cuando la respuesta es la guardada de un intento anterior.

400

Cuerpo o parámetros inválidos (details = [{ ruta, mensaje }]), o el DTE no cumple el esquema del MH (details.problemas). Códigos: datos_invalidos, dte_invalido.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: datos_invalidos dte_invalido no_autenticado sin_permiso origen_no_permitido no_encontrado sin_organizacion sin_organizacion_activa nit_bloqueado emisor_no_configurado credenciales_incompletas sin_punto_venta estado_invalido ambiente_distinto retorno_excedido retorno_vigente idempotencia_distinta idempotencia_en_curso cliente_repetido producto_repetido codigo_repetido sin_archivo limite_webhooks simulador_inactivo dte_rechazado invalidacion_rechazada contingencia_rechazada evento_rechazado limite_excedido error_interno mh_credenciales_rechazadas mh_no_disponible emision_fallida emision_incierta

message

required

string

details

Detalle según el código; puede faltar.

Example

{
  "error": {
    "code": "datos_invalidos"
  }
}

401

Falta sesión, o la clave de API no es válida, fue revocada o expiró. Códigos: no_autenticado.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: datos_invalidos dte_invalido no_autenticado sin_permiso origen_no_permitido no_encontrado sin_organizacion sin_organizacion_activa nit_bloqueado emisor_no_configurado credenciales_incompletas sin_punto_venta estado_invalido ambiente_distinto retorno_excedido retorno_vigente idempotencia_distinta idempotencia_en_curso cliente_repetido producto_repetido codigo_repetido sin_archivo limite_webhooks simulador_inactivo dte_rechazado invalidacion_rechazada contingencia_rechazada evento_rechazado limite_excedido error_interno mh_credenciales_rechazadas mh_no_disponible emision_fallida emision_incierta

message

required

string

details

Detalle según el código; puede faltar.

Example

{
  "error": {
    "code": "datos_invalidos"
  }
}

403

Falta un permiso (details.permiso) o el origen de la petición con cookie no está permitido. Códigos: sin_permiso, origen_no_permitido.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: datos_invalidos dte_invalido no_autenticado sin_permiso origen_no_permitido no_encontrado sin_organizacion sin_organizacion_activa nit_bloqueado emisor_no_configurado credenciales_incompletas sin_punto_venta estado_invalido ambiente_distinto retorno_excedido retorno_vigente idempotencia_distinta idempotencia_en_curso cliente_repetido producto_repetido codigo_repetido sin_archivo limite_webhooks simulador_inactivo dte_rechazado invalidacion_rechazada contingencia_rechazada evento_rechazado limite_excedido error_interno mh_credenciales_rechazadas mh_no_disponible emision_fallida emision_incierta

message

required

string

details

Detalle según el código; puede faltar.

Example

{
  "error": {
    "code": "datos_invalidos"
  }
}

404

El recurso no existe en esta organización. Códigos: no_encontrado.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: datos_invalidos dte_invalido no_autenticado sin_permiso origen_no_permitido no_encontrado sin_organizacion sin_organizacion_activa nit_bloqueado emisor_no_configurado credenciales_incompletas sin_punto_venta estado_invalido ambiente_distinto retorno_excedido retorno_vigente idempotencia_distinta idempotencia_en_curso cliente_repetido producto_repetido codigo_repetido sin_archivo limite_webhooks simulador_inactivo dte_rechazado invalidacion_rechazada contingencia_rechazada evento_rechazado limite_excedido error_interno mh_credenciales_rechazadas mh_no_disponible emision_fallida emision_incierta

message

required

string

details

Detalle según el código; puede faltar.

Example

{
  "error": {
    "code": "datos_invalidos"
  }
}

409

Falta configurar algo o hay un conflicto. Códigos: sin_organizacion, sin_organizacion_activa, nit_bloqueado, emisor_no_configurado, credenciales_incompletas, sin_punto_venta, estado_invalido, ambiente_distinto, retorno_excedido, retorno_vigente, idempotencia_distinta, idempotencia_en_curso, cliente_repetido, producto_repetido, codigo_repetido, sin_archivo, limite_webhooks, simulador_inactivo.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: datos_invalidos dte_invalido no_autenticado sin_permiso origen_no_permitido no_encontrado sin_organizacion sin_organizacion_activa nit_bloqueado emisor_no_configurado credenciales_incompletas sin_punto_venta estado_invalido ambiente_distinto retorno_excedido retorno_vigente idempotencia_distinta idempotencia_en_curso cliente_repetido producto_repetido codigo_repetido sin_archivo limite_webhooks simulador_inactivo dte_rechazado invalidacion_rechazada contingencia_rechazada evento_rechazado limite_excedido error_interno mh_credenciales_rechazadas mh_no_disponible emision_fallida emision_incierta

message

required

string

details

Detalle según el código; puede faltar.

Example

{
  "error": {
    "code": "datos_invalidos"
  }
}

422

El MH rechazó el documento o el evento; details.mh = { codigo, mensaje, observaciones[] }. Códigos: dte_rechazado, invalidacion_rechazada, contingencia_rechazada, evento_rechazado.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: datos_invalidos dte_invalido no_autenticado sin_permiso origen_no_permitido no_encontrado sin_organizacion sin_organizacion_activa nit_bloqueado emisor_no_configurado credenciales_incompletas sin_punto_venta estado_invalido ambiente_distinto retorno_excedido retorno_vigente idempotencia_distinta idempotencia_en_curso cliente_repetido producto_repetido codigo_repetido sin_archivo limite_webhooks simulador_inactivo dte_rechazado invalidacion_rechazada contingencia_rechazada evento_rechazado limite_excedido error_interno mh_credenciales_rechazadas mh_no_disponible emision_fallida emision_incierta

message

required

string

details

Detalle según el código; puede faltar.

Example

{
  "error": {
    "code": "datos_invalidos"
  }
}

429

Límite de peticiones excedido; Retry-After indica cuántos segundos esperar. Códigos: limite_excedido.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: datos_invalidos dte_invalido no_autenticado sin_permiso origen_no_permitido no_encontrado sin_organizacion sin_organizacion_activa nit_bloqueado emisor_no_configurado credenciales_incompletas sin_punto_venta estado_invalido ambiente_distinto retorno_excedido retorno_vigente idempotencia_distinta idempotencia_en_curso cliente_repetido producto_repetido codigo_repetido sin_archivo limite_webhooks simulador_inactivo dte_rechazado invalidacion_rechazada contingencia_rechazada evento_rechazado limite_excedido error_interno mh_credenciales_rechazadas mh_no_disponible emision_fallida emision_incierta

message

required

string

details

Detalle según el código; puede faltar.

Example

{
  "error": {
    "code": "datos_invalidos"
  }
}

Headers

Retry-After

integer

Segundos que hay que esperar.

502

Problema hablando con el MH o al firmar. Con emision_incierta consulte details.codigoGeneracion antes de reintentar. Códigos: mh_credenciales_rechazadas, mh_no_disponible, emision_fallida, emision_incierta.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: datos_invalidos dte_invalido no_autenticado sin_permiso origen_no_permitido no_encontrado sin_organizacion sin_organizacion_activa nit_bloqueado emisor_no_configurado credenciales_incompletas sin_punto_venta estado_invalido ambiente_distinto retorno_excedido retorno_vigente idempotencia_distinta idempotencia_en_curso cliente_repetido producto_repetido codigo_repetido sin_archivo limite_webhooks simulador_inactivo dte_rechazado invalidacion_rechazada contingencia_rechazada evento_rechazado limite_excedido error_interno mh_credenciales_rechazadas mh_no_disponible emision_fallida emision_incierta

message

required

string

details

Detalle según el código; puede faltar.

Example

{
  "error": {
    "code": "datos_invalidos"
  }
}