Crear un comprobante de retención

Este endpoint está diseñado para facilitar la generación y emisión de comprobantes de retención. Para utilizarlo, necesitas realizar un POST request a `/dte/cr``, incluyendo la información necesaria en el cuerpo de la solicitud.

Detalles Técnicos

• HTTP Method: POST
• URL: https://api.facturallama.com/dte/cr
• Headers:
  • X-API-Key: Tu API key.
  • X-API-Version: La versión de la API que estás utilizando.
  • Content-Type: application/json

Request Body

A continuación se presenta una descripción detallada de las propiedades que puedes incluir en el cuerpo de tu solicitud, así como las validaciones y formatos que debes tener en cuenta.

Propiedades Principales

Propiedad	Tipo	Validación	Descripción
id	UUID	Obligatorio.	Identificador del DTE (este valor se convertira en el código de generación para el Ministerio de Hacienda).
generatedAt	Date	Opcional.	Fecha de generación del DTE. Formato: yyyy-MM-dd
branchOffice	Object	Opcional. Ver detalles.	Datos de la sucursal y punto de venta.
recipient	Object	Obligatorio. Ver detalles.	Información del receptor.
items	Array	Obligatorio. Ver detalles.	Lista de ítems.

Propiedades Anidadas

branchOffice

Propiedad	Tipo	Validación	Descripción
mhCode	String	Obligatorio. Debe ser un string de exactamente 4 caracteres.	Identificador de la sucursal.
posNumber	Number	Obligatorio. Debe ser un número positivo. El valor no puede ser mayor a 999.	Identificador del punto de venta.

recipient

Propiedad	Tipo	Validación	Descripción
economicActivity	Enum	Obligatorio. Debe coincidir con códigos de CAT-019.	Código de actividad económica.
contributorType	Enum	Opcional.	Tipo de Contribuyente. Valores: NATURAL, JURIDICA
contributorSize	Enum	Opcional.	Tamaño de Contribuyente. Valores: GRANDE, MEDIANO, OTROS
nrc	String	Opcional. La longitud del string debe ser de entre 1 y 8 números. Si el identificationDocument.type es NIT, este campo es obligatorio.	Número de Registro de Contribuyente.
name	String	Obligatorio. Máximo: 250 caracteres.	Nombre del receptor.
phone	String	Opcional. Debe ser un string de exactamente 8 números.	Número de teléfono del receptor. Formato: ########
commercialName	String	Opcional. Máximo: 150 caracteres.	Nombre comercial del receptor.
email	String	Obligatorio. Máximo: 100 caracteres. Debe ser un correo electrónico válido.	Correo electrónico del receptor.
address	Object	Obligatorio. Ver detalles.	Dirección del receptor.
identificationDocument	Object	Obligatorio. Ver detalles.	Documento de identificación del receptor.

recipient.address

Propiedad	Tipo	Validación	Descripción
department	String	Obligatorio.	Departamento. Debe coincidir con códigos de CAT-012.
municipality	String	Obligatorio.	Municipio. Debe coincidir con códigos de CAT-013.
complement	String	Obligatorio.	Información adicional de dirección. Máximo: 200 caracteres.

recipient.identificationDocument

Propiedad	Tipo	Validación	Descripción
type	Enum	Obligatorio	Tipo de documento. Valores: NIT, DUI, PASAPORTE, CARNET_RESIDENTE, OTRO.
number	String	Obligatorio	Número del documento de identificación. DUI: #########; NIT: ##############

items

Propiedad	Tipo	Validación	Descripción
documentType	Enum	Obligatorio.	Tipo de documento relacionado con el ítem. Valores: FISICO, DIGITAL.
taxDocumentType	Enum	Obligatorio.	Tipo de DTE relacionado con el ítem. Valores: FC, CCF, FSE.
taxDocumentNumber	String	Obligatorio.	Número de documento relacionado con el ítem. Si el documentType es FISICO se permite un String de máximo 20 caracteres, si es DIGITAL debe escribirse el código de generación del DTE.
taxDocumentGeneratedAt	Date	Obligatorio.	Fecha de emision del documento relacionado con el ítem. Formato: yyyy-MM-dd.
description	String	Obligatorio. Máximo: 1000 caracteres.	Descripción del ítem.
amountSubject	Number	Obligatorio. Debe ser un número decimal positivo.	Monto sujeto a retención del ítem.
ivaRetained	Number	Obligatorio. Debe ser un número decimal positivo.	Iva retenido del ítem.
retentionCode	Enum	Obligatorio	Código de retención MH. Valores: RETENCION_IVA_1, RETENCION_IVA_13, OTRAS_RETENCIONES_IVA_CASOS_ESPECIALES.

Response Body

Una vez procesada tu solicitud, el servidor responderá con un conjunto de datos que confirmarán la creación del comprobante de crédito fiscal o, en caso de error, proporcionarán detalles sobre lo que salió mal.

Propiedad	Tipo	Descripción
id	UUID	Identificador único del DTE.
companyId	UUID	Identificador único de la empresa.
controlNumber	String	Este número es utilizado para identificar el DTE ante el Ministerio de Hacienda (MH).
environment	Enum	Ambiente. Valores: TEST, LIVE.
type	Enum	Tipo de documento fiscal. CR.
version	Integer	Versión del DTE.
status	Enum	Estado del DTE. Valores: CREATED, PROCESSING, APPROVED, REJECTED, INVALIDATED.
mhResponse	Object	Respuesta del API del Ministerio de Hacienda.
generatedAt	Timestamp	Fecha y hora de creación del DTE asignado manualmente.
createdAt	Timestamp	Fecha y hora de creación del DTE.

Ejemplo

Copia y pega el código en una terminal o en tu editor de código favorito. Reemplaza <Tu API Key> con la API key que generaste en el paso anterior.

cURL

curl --location 'https://api.facturallama.com/dte/cr' \
--header 'X-API-Version: 1' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <API Key>' \
--data-raw '{
  "id": "<UUID>",
  "recipient": {
      "contributorType": "NATURAL",
      "contributorSize": "OTROS",
      "economicActivity": "62020",
      "nrc": "12345678",
      "name": "John Doe",
      "email": "johndoe@gmail.com",
      "identificationDocument": {
        "type": "DUI",
        "number": "123456789"
      },
      "address": {
        "department": "06",
        "municipality": "14",
        "complement": "Somewhere beyond the rainbow"
      }
  },
  "items": [
       {
        "documentType": "FISICO",
        "taxDocumentType": "FC",
        "taxDocumentNumber": "34343434",
        "taxDocumentGeneratedAt": "2024-04-22",
        "description": "Retención",
        "ivaRetained": 0.85,
        "amountSubject": 88.5,
        "retentionCode": "RETENCION_IVA_1"
      }
  ]
}'