Crear una factura

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

Detalles Técnicos

HTTP Method: POST
URL: https://api.facturallama.com/dte/fc
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.
`paymentType`	Enum	Opcional. Default: `CONTADO`	Tipo de pago. Valores: `CONTADO`, `CREDITO`, `OTRO`
`branchOffice`	Object	Opcional. Ver detalles.	Datos de la sucursal y punto de venta.
`recipient`	Object	Opcional. Ver detalles.	Información del destinatario.
`thirdPartySale`	Object	Opcional. Ver detalles.	Información de venta a terceros.
`relatedTaxDocuments`	Array	Opcional. Máximo de 50 objetos. Ver detalles.	Lista de documentos fiscales relacionados.
`attachments`	Array	Opcional. Máximo de 10 objetos. Ver detalles.	Lista de adjuntos.
`items`	Array	Obligatorio. Ver detalles.	Lista de ítems.
`itemsNoGrav`	Array	Opcional. Ver detalles.	Lista de ítems no gravados.
`discountNoSuj`	Number	Opcional. Debe ser un número decimal positivo.	Descuento no sujeto.
`discountExe`	Number	Opcional. Debe ser un número decimal positivo.	Descuento exento.
`discountGrav`	Number	Opcional. Debe ser un número decimal positivo.	Descuento gravado.
`retentionIva`	Number	Opcional. Puede ser 0 ó un número decimal positivo.	Retención IVA.
`retentionRenta`	Number	Opcional. Puede ser 0 ó un número decimal positivo.	Retención Renta.

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`	String	Opcional. Obligatorio cuando se proporciona nrc. Debe coincidir con códigos de CAT-019.	Código de actividad económica.
`contributorSize`	Enum	Opcional.	Tipo de pago. Valores: `GRANDE`, `MEDIANO`, `OTROS`
`contributorType`	Enum	Opcional.	Tipo de pago. Valores: `NATURAL`, `JURIDICA`
`nrc`	String	Opcional. La longitud del string debe ser de entre 2 y 8 caracteres. Cuando identificationDocument.type no es "NIT", el nrc debe ser nulo.	Número de Registro de Contribuyente. Formato: ########
`name`	String	Obligatorio. Máximo: 150 caracteres.	Nombre del destinatario.
`email`	String	Opcional. Máximo: 100 caracteres. Debe ser un correo electrónico válido.	Correo electrónico del destinatario.
`phone`	String	Opcional. Debe ser un string de exactamente 8 números.	Número de teléfono del destinatario. Formato: ########
`address`	Object	Opcional. Ver detalles.	Dirección del destinatario.
`identificationDocument`	Object	Opcional. Ver detalles.	Documento de identificación del destinatario.

`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.

`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: ##############

`thirdPartySale`

Propiedad	Tipo	Validación	Descripción
`name`	String	Obligatorio. Máximo: 150 caracteres.	Nombre de la tercera parte.
`identificationDocument`	Object	Obligatorio. Ver detalles.	Documento de identificación de la tercera parte.

`thirdPartySale.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: ##############

`relatedTaxDocuments`

Propiedad	Tipo	Validación	Descripción
`id`	UUID	Obligatorio.	Identificador único del documento relacionado.

`attachments`

Propiedad	Tipo	Validación	Descripción
`code`	Enum	Obligatorio.	Código del adjunto. Valores: `EMISOR`, `RECEPTOR`, `DOCTOR`
`details`	String	Opcional. Obligatorio cuando code es EMISOR o RECEPTOR. Máximo: 300 caracteres.	Detalles o descripción del adjunto.
`doctor`	Object	Opcional. Ver detalles.	Información sobre el doctor en caso de que el adjunto se refiera a un servicio médico.

`attachments[n].doctor`

Propiedad	Tipo	Validación	Descripción
`name`	String	Obligatorio, Máximo: 100 caracteres.	Nombre del doctor.
`identificationDocument`	Object	Obligatorio. Ver detallles.	Documento de identificación del doctor.
`service`	Enum	Opcional.	Servicio médico proporcionado. Valores: `CIRUGIA`, `OPERACION`, `TRATAMIENTO_MEDICO`, `CIRUGIA_ISBM`, `OPERACION_ISBM`, `TRATAMIENTO_MEDICO_ISBM`.

`attachments[n].doctor.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
`type`	Enum	Obligatorio.	Tipo de ítem. Valores: `BIENES`, `SERVICIOS`, `BIENES_Y_SERVICIOS`, `OTROS`.
`internalCode`	String	Opcional, Máximo: 25 caracteres.	Código interno del ítem.
`description`	String	Obligatorio. Máximo: 1000 caracteres.	Descripción del ítem.
`quantity`	Number	Obligatorio. Debe ser un número entero positivo.	Cantidad del ítem.
`unitMeasure`	Enum	Opcional. Default: `OTRA`	Unidad de medida del ítem. Contiene diversas opciones, como `METRO`, `YARDA`, `PIE`, `KILOGRAMO`, etc.
`unitPrice`	Number	Obligatorio. Debe ser un número decimal positivo.	Precio unitario del ítem.
`discountAmount`	Number	Opcional. Debe ser un número decimal positivo.	Monto de descuento aplicado al ítem.
`saleType`	Enum	Obligatorio.	Tipo de venta del ítem. Valores: `NO_SUJETA`, `GRAVADA`, `EXENTA`.
`psv`	Number	Opcional. Debe ser un número decimal positivo.	Valor específico por ítem (si aplica).
`documentNumber`	UUID	Opcional.	Número de documento relacionado con el ítem. Este número debe estar presente en el arreglo de `relatedTaxDocuments`.

`itemsNoGrav`

Propiedad	Tipo	Validación	Descripción
`type`	Enum	Obligatorio.	Tipo de ítem. Valores: `BIENES`, `SERVICIOS`, `BIENES_Y_SERVICIOS`, `OTROS`.
`internalCode`	String	Opcional. Máximo: 25 caracteres.	Código interno del ítem.
`description`	String	Obligatorio. Máximo: 1000 caracteres.	Descripción del ítem.
`amount`	Number	Obligatorio. Debe ser un número decimal positivo.	Monto del ítem que no está gravado.

Response Body

Una vez procesada tu solicitud, el servidor responderá con un conjunto de datos que confirmarán la creación de la factura electrónica 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. `FC`.
`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 --location 'https://api.facturallama.com/dte/fc' \
--header 'X-API-Version: 1' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <API Key>' \
--data '{
    "id": "<UUID>",
    "recipient": {
        "name": "Fulano Detal"
    },
    "items": [
        {
            "type": "BIENES",
            "description": "Producto 1",
            "quantity": 1,
            "unitPrice": 17.97,
            "saleType": "GRAVADA"
        }
    ]
}'

wget --no-check-certificate --quiet \
     --method=POST \
     --header='X-API-Key: <API Key>' \
     --header='X-API-Version: 1' \
     --header='Content-Type: application/json' \
     --body-data='{
        "internalId": "<UUID>",
        "recipient": {
            "name": "Fulano Detal"
        },
        "items": [
            {
                "type": "BIENES",
                "description": "Producto 1",
                "quantity": 1,
                "unitPrice": 17.97,
                "saleType": "GRAVADA"
            }
        ]
     }' \
     --output-document=- \
     https://api.facturallama.com/dte/fc

const axios = require("axios");

let data = JSON.stringify({
  internalId: "<UUID>",
  recipient: {
    name: "Fulano Detal",
  },
  items: [
    {
      type: "BIENES",
      description: "Producto 1",
      quantity: 1,
      unitPrice: 17.97,
      saleType: "GRAVADA",
    },
  ],
});

let config = {
  method: "post",
  maxBodyLength: Infinity,
  url: "https://api.facturallama.com/dte/fc",
  headers: {
    "X-API-Version": "1",
    "Content-Type": "application/json",
    "X-API-Key": "<API Key>",
  },
  data: data,
};

axios
  .request(config)
  .then((response) => {
    console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
    console.log(error);
  });

<?php
$client = new Client();
$headers = [
  'X-API-Version' => '1',
  'Content-Type' => 'application/json',
  'X-API-Key' => '<API Key>'
];
$body = '{
  "internalId": "<UUID>",
  "recipient": {
    "name": "Fulano Detal"
  },
  "items": [
    {
      "type": "BIENES",
      "description": "Producto 1",
      "quantity": 1,
      "unitPrice": 17.97,
      "saleType": "GRAVADA"
    }
  ]
}';
$request = new Request('POST', 'https://api.facturallama.com/dte/fc', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.facturallama.com/dte/fc");
request.Headers.Add("X-API-Version", "1");
request.Headers.Add("X-API-Key", "<API Key>");
var content = new StringContent("{\n"internalId": "<UUID>",\n\"recipient\": {\n        \"name\": \"Fulano Detal\"\n    },\n    \"items\": [\n        {\n            \"type\": \"BIENES\",\n            \"description\": \"Producto 1\",\n            \"quantity\": 1,\n            \"unitPrice\": 17.97,\n            \"saleType\": \"GRAVADA\"\n        }\n    ]\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"recipient\": {\n        \"name\": \"Fulano Detal\"\n    },\n    \"items\": [\n        {\n            \"type\": \"BIENES\",\n            \"description\": \"Producto 1\",\n            \"quantity\": 1,\n            \"unitPrice\": 17.97,\n            \"saleType\": \"GRAVADA\"\n        }\n    ]\n}");
Request request = new Request.Builder()
  .url("https://api.facturallama.com/dte/fc")
  .method("POST", body)
  .addHeader("X-API-Version", "1")
  .addHeader("Content-Type", "application/json")
  .addHeader("X-API-Key", "<API Key>")
  .build();
Response response = client.newCall(request).execute();

Crear una factura

Detalles Técnicos​

Request Body​

Propiedades Principales​

Propiedades Anidadas​

branchOffice​

recipient​

recipient.address​

recipient.identificationDocument​

thirdPartySale​

thirdPartySale.identificationDocument​

relatedTaxDocuments​

attachments​

attachments[n].doctor​

attachments[n].doctor.identificationDocument​

items​

itemsNoGrav​

Response Body​

Ejemplo​