Crear Factura.

Crear una nueva factura de venta teniendo en cuenta que el cliente o tercero ya está creado en la base de datos de Siigo Nube.

Nombre	Tipo	Descripción	Características
document.id	number	Identificador del tipo de comprobante	Campo obligatorio, debe existir en Siigo previamente. Consultar: `/document-types`
date	date	Fecha de comprobante	Campo obligatorio. Para facturas electrónicas NO puede ser anterior a la fecha actual.
number	number	Consecutivo/número del comprobante	Campo opcional. Si se envía, debe ser un consecutivo que no exista en Nube.
customer.identification	string	Número de identificación del cliente	Campo obligatorio. Debe existir y estar activo en Siigo Nube.
customer.branch_office	number	Número de sucursal del cliente	Campo opcional. Por defecto se usa 0 si no se envía.
seller	number	ID del vendedor asociado a la factura	Campo obligatorio. Debe existir en Siigo Nube. Consultar: `/users`
stamp	object	Envío de factura electrónica a la DIAN	Campo opcional. Si se envía como `true`, se envía a la DIAN. Por defecto es `false`.
mail	object	Envío del documento por correo electrónico al cliente	Campo opcional. Si se envía como `true`, se envía por correo. Por defecto es `false`.
observations	string	Observaciones o comentarios de la factura	Campo opcional. Máximo 4.000 caracteres.
retentions	array	IDs de impuestos tipo ReteICA, ReteIVA o Autoretención	Campo opcional. Consultar: `/taxes`
advance_payment	number	Valor de anticipo o copago	Campo opcional. Numérico, máximo 2 decimales. Debe ser positivo y no superar el valor total de la factura.
cost_center	number	ID del centro de costos	Campo opcional. Debe existir y estar activo en Siigo Nube.
currency.code	string	Código de moneda	Campo opcional. Requiere configuración de moneda extranjera. Por defecto se usa la moneda local.
currency.exchange_rate	number	Tasa o valor en moneda extranjera	Campo opcional. Igual que `currency.code`, debe estar configurado en Siigo Nube.
items.code	string	Código único del producto	Campo obligatorio. Debe existir y estar activo en Siigo Nube.
items.description	string	Descripción del producto/servicio	Campo opcional. Comportamiento depende de configuración en Siigo Nube.
items.quantity	number	Cantidad del producto	Campo obligatorio. Numérico, máximo 2 decimales.
items.price	number	Precio unitario del producto	Campo obligatorio. Numérico, máximo 6 decimales.
items.discount	number	Descuento aplicado al producto	Campo opcional. Puede ser por valor o porcentaje.
items.seller	number	ID del vendedor por ítem	Campo obligatorio si se tiene activa esta configuración. Debe existir en Siigo Nube. Consultar: `/users`
items.warehouse	number	ID de la bodega asociada	Campo opcional. Debe existir y estar activa en Siigo Nube si se envía.
items.taxes.id	number	ID del impuesto	Campo opcional. No se permiten dos impuestos del mismo tipo por ítem. Consultar: `/taxes`
items.taxed_price	number	Precio con IVA incluido	Campo opcional. Si se envía, reemplaza `items.price`.
adittional_fields	array	Campos adicionales para orden de compra y entrega	Campo opcional. Alfanumérico, máximo 20 caracteres por campo, permite caracteres especiales.
payments.id	number	ID del medio de pago	Campo obligatorio. Debe existir y estar activo en Siigo Nube. Consultar: `/payment-types`. Solo se permite un medio con vencimiento (`due_date: true`).
payments.value	number	Valor del medio de pago	Campo obligatorio. Numérico, máximo 2 decimales.
payments.due_date	string	Fecha de vencimiento del pago	Campo obligatorio si el medio de pago maneja vencimiento. Formato: `yyyy-MM-dd`.
global_discounts.id	number	ID del descuento global	Campo opcional. Debe existir y estar activo en Siigo Nube.
global_discounts.percentage	number	Porcentaje del descuento global	Campo opcional. Entre 0.01 y 99.99. Máximo 2 decimales.
global_discounts.value	number	Valor del descuento global	Campo opcional. Si se envía junto con el porcentaje, se tomará el porcentaje.

¿Como crear facturas no electrónicas en Siigo Nube?

Creación de un cliente desde la factura de venta:

Para facilitar el proceso de facturación, se puede crear el cliente desde la misma petición de la factura de venta.

Nombre	Tipo	Descripción	Características
`person_type`	`String`, required	Identifica si el tercero es "person" o "company".	Campo obligatorio, solo se puede enviar `"person"` o `"company"`.
`id_type`	`string`, required	Código del tipo de documento.	Campo obligatorio, las opciones se encuentran en el listado siguiente a este apartado. Ejemplo: `13` para cédula, `31` para NIT.
`identification`	`String`	Número de identificación del cliente.	Campo obligatorio, no permite carácteres especiales, máximo 50 carácteres, solo permite un número de identificación existente en Nube si es un nuevo número de sucursal.
`branch_office`	`number`	Sucursal, valor por default `0`.	Campo opcional, solo recibe números enteros del `0` al `999`.
`name`	`String`, required	Razón social o nombres y apellidos del cliente.	Campo obligatorio, no permite carácteres especiales. `Company` es un solo campo, en el array de `Person` son 2 campos. Máximo 100 carácteres por campo.
`address.address`	`string`, required	Dirección del cliente.	Campo obligatorio, alfanumérico, permite espacios, máximo 256 carácteres.
`address.city.country_code`	`string`, required	Código del país.	Se debe consultar en Siigo Nube: Reportes > Carteras/Proveedores > Reportes de sistema > Países-Departamentos-Ciudades. Ejemplo: `"CO"` para Colombia.
`address.city.state_code`	`string`, required	Código del departamento/estado.	Se consulta en la misma ruta que `country_code`. Ejemplo: `"11"` para Bogotá D.C. (Colombia).
`address.city.city_code`	`string`, required	Código de la ciudad.	Se consulta en la misma ruta. Ejemplo: `"11001"` para Bogotá (Colombia).
`phones.indicative`	`string`	Indicativo del número de contacto.	Campo opcional, numérico, no permite espacios ni carácteres especiales, máximo 10 carácteres.
`phones.number`	`string`	Número de contacto.	Campo opcional, numérico, no permite espacios ni carácteres especiales, máximo 10 carácteres.
`phones.extension`	`string`	Extensión del número de contacto.	Campo opcional, numérico, no permite espacios ni carácteres especiales, máximo 10 carácteres.
`contacts.first_name`	`string`, required	Nombres del contacto.	Campo obligatorio, permite espacios y carácteres especiales, alfanumérico, máximo 50 carácteres.
`contacts.last_name`	`string`	Apellidos del contacto.	Campo opcional, permite espacios y carácteres especiales, alfanumérico, máximo 50 carácteres.
`contacts.email`	`string`	Correo del contacto.	Campo opcional, NO permite espacios ni carácteres especiales, alfanumérico, máximo 100 carácteres.

Json del objeto de customer para su creación desde la factura de venta:

{
	"customer": {
		"person_type": "Person",
		"id_type": "13",
		"identification": "209048401",
		"branch_office": "0",
		"name": ["Manuel", "Camacho"],
		"address": {
			"address": "Cra. 18 #79A - 42",
			"city": {
				"country_code": "Co",
				"state_code": "11",
				"city_code": "11001"
			}
		},
		"phones": [
			{
				"number": "3006003344"
			}
		],
		"contacts": [
			{
				"first_name": "Manuel",
				"last_name": "Camacho",
				"email": "[email protected]"
			}
		]
	}
}

Campos adicionales (adittional_fields)

Permite enviar los campos orden de compra y orden de entrega.

purchase_order: Campo de orden de compra.
delivery_order: Campo de orden de entrega.

    "additional_fields": {
          "purchase_order": {
              "prefix": "OC",
              "number": "23"
          },
          "delivery_order": {
              "prefix": "OE",
              "number": "23",
              "date": "2021-05-19"
          }
      }

Ingresos para terceros (items.customer)

Para manejar terceros por item en facturas de venta, primero se debe tener activa la marcación en el tipo de documento que se puede consultar en: /document-types FV.

Para recibir el campo se debe tener en el tipo de documento el campo "customer_by_item": true Se debe añadir un objeto en el array de items donde incluya la identificación del tercero que se quiere relacionar a este ítem:

Campos para Terceros por Ítem

Nombre	Tipo	Descripción
`items.customer.identification`	`string`	Opcional. Número de identificación del tercero del ítem. Si no se envía, se usa el `customer` principal de la factura. No es modificable y el tercero debe estar activo.
`items.customer.branch_office`	`number`	Opcional. Número de sucursal del tercero (valor por defecto: `0`). Solo acepta números enteros entre 0 y 999.

Json de ejemplo de un item con ingresos para terceros

{
	"customer": {
		"person_type": "Person",
		"id_type": "13",
		"identification": "209048401",
		"branch_office": "0",
		"name": ["Manuel", "Camacho"],
		"address": {
			"address": "Cra. 18 #79A - 42",
			"city": {
				"country_code": "Co",
				"state_code": "11",
				"city_code": "11001"
			}
		},
		"phones": [
			{
				"number": "3006003344"
			}
		],
		"contacts": [
			{
				"first_name": "Manuel",
				"last_name": "Camacho",
				"email": "[email protected]"
			}
		]
	}
}

Facturar productos de obsequio

Para facturar items con valor en 0, se debe aclarar ante la DIAN cual es el valor real del item y quien asume el IVA de este producto si al empresa o el cliente.

Para esto se agregaron los siguientes campos:

Nombre	Tipo	Descripción	Características
items.tax_base	number	Precio base para el cálculo del IVA	Campo obligatorio si se envía el campo `items.price` en 0. El valor debe ser mayor a 0, con máximo 11 enteros y 2 decimales.
items.taxpayer	string	Indica quién asume el IVA del producto facturado en 0	Campo obligatorio si se envía el campo `items.price` en 0. Solo admite los valores `"Customer"` o `"Company"`.

Json de ejemplo de un item con valor en 0 de obsequio:

{
	"items": [
		{
			"code": "1",
			"description": "Alquiler",
			"quantity": 2,
			"price": 0,
			"tax_base": 1000,
			"taxpayer": "Company",
			"taxes": [
				{
					"id": 31779
				}
			]
		}
	]
}

Campos para empresas de transporte (transport)

Permite enviar los campos requeridos en facturación electronica para empresas de transporte, detalle de los campos:

Nombre	Tipo	Descripción	Características
items.transport.file_number	number	Número de radicado	Campo opcional (aplica para empresas de transporte de carga). Debe ser numérico entre 1 y 100.000.000.000.
items.transport.shipment_number	string	Número de remesa	Campo opcional (aplica para empresas de transporte de carga). Alfanumérico. Permite espacios, guion medio (-), guion bajo (_), slash (/), y coma (,). Máximo 15 caracteres.
items.transport.transported_quantity	number	Cantidad transportada	Campo opcional (aplica para empresas de transporte de carga). Numérico, sin decimales. Límite de 8 caracteres.
items.transport.measurement_unit	string	Unidad de medida	Campo opcional (aplica para empresas de transporte de carga). Solo permite los valores: `"GLL"` (Galón) y `"KGM"` (Kilogramo).
items.transport.freight_value	number	Valor Flete	Campo opcional (aplica para empresas de transporte de carga). Numérico, sin decimales. Límite de 12 caracteres.
items.transport.purchase_order	string	Orden de compra	Campo opcional (aplica para empresas de transporte de carga). Alfanumérico. Límite de 50 caracteres.
items.transport.service_type	string	Tipo de servicio	Campo opcional (aplica para empresas de transporte de carga). Puede tomar dos valores: `"AdditionalService"` (servicio adicional) y `"Shipment"` (remesa de transporte en el RNDC).

Json de ejemplo de un item con campos de transporte:

{
	"items": [
		{
			"code": "Item-1",
			"quantity": 1,
			"price": 1069.77,
			"taxes": [
				{
					"id": 13156
				}
			],
			"transport": {
				"file_number": 536,
				"shipment_number": "RM-145",
				"transported_quantity": 120,
				"measurement_unit": "KGM",
				"freight_value": 220000,
				"purchase_order": "OC-236",
				"service_type": "AdditionalService"
			}
		}
	]
}

Campos para empresas del sector salud (healthcare_company)

Permite enviar los campos requeridos en facturación electronica para empresas del sector salud, detalle de los campos:

Nombre	Tipo	Descripción	Características
healthcare_company.period_start	date	Periodo de facturación inicio	Campo opcional. Debe ir en formato `AAAA-MM-DD`.
healthcare_company.period_end	date	Periodo de facturación final	Campo opcional. Debe ir en formato `AAAA-MM-DD`.
healthcare_company.payment_method	number	Modalidad de pago	Campo opcional. Debe enviar el ID válido del listado de valores que se encuentra en la parte inferior.
healthcare_company.service_plan	number	Cobertura - Plan servicios	Campo opcional. Debe enviar el ID válido del listado de valores que se encuentra en la parte inferior.
healthcare_company.policy_number	string	Número de póliza	Campo opcional. Alfanumérico, de máximo 50 caracteres.
healthcare_company.contract_number	string	Número de contrato	Campo opcional. Alfanumérico, de máximo 50 caracteres.
healthcare_company.copayment	number	Copago	Campo opcional. Campo numérico de 12 dígitos: 10 enteros y 2 decimales. Debe ser un valor positivo, sin símbolos ni separadores de miles, usando punto como separador decimal.
healthcare_company.coinsurance	number	Cuota moderadora	Campo opcional. Campo numérico de 12 dígitos: 10 enteros y 2 decimales. Debe ser un valor positivo, sin símbolos ni separadores de miles, usando punto como separador decimal.
healthcare_company.cost_sharing	number	Pagos compartidos	Campo opcional. Campo numérico de 12 dígitos: 10 enteros y 2 decimales. Debe ser un valor positivo, sin símbolos ni separadores de miles, usando punto como separador decimal.
healthcare_company.recovery_charge	number	Cuota de recuperación	Campo opcional. Campo numérico de 12 dígitos: 10 enteros y 2 decimales. Debe ser un valor positivo, sin símbolos ni separadores de miles, usando punto como separador decimal.

Listado de valores del campo "payment_method":

Número	Descripción
01	Pago individual por caso, conjunto integral de atenciones, paquete o canasta.
02	Pago global prospectivo.
03	Pago por capitación.
04	Pago por evento.
05	Otra modalidad (específica).

Listado de valores del campo "service_plan":

Número	Descripción
01	Plan de beneficios en salud financiado con UPC
02	Presupuesto máximo
03	Prima EPS / EOC, no asegurados SOAT
04	Cobertura Póliza SOAT
05	Cobertura ARL
06	Cobertura ADRES
07	Cobertura Salud Pública
08	Cobertura entidad territorial, recursos de oferta
09	Urgencias población migrante
10	Plan complementario en salud
11	Plan medicina prepagada
12	Otras pólizas en salud
13	Cobertura Régimen Especial o Excepción
14	Cobertura Fondo Nacional de Salud de las Personas Privadas de la Libertad
15	Particular

Json de ejemplo de campos del sector salud

{
	"healthcare_company": {
		"period_start": "2024-02-14",
		"period_end": "2024-03-16",
		"payment_method": "04",
		"service_plan": "01",
		"policy_number": "ZAS321456677",
		"contract_number": "CON1245636",
		"copayment": 22505.2,
		"coinsurance": 10805.2,
		"cost_sharing": 10500.0,
		"recovery_charge": 85236.43
	}
}

Parámetros

Código	Moneda
COP	Peso colombiano
EUR	Euro
USD	Dólar estadounidense
ANG	Florín antillano neerlandés
ARS	Peso argentino
AUD	Dólar australiano
BOB	Boliviano
BRL	Real brasileño
CAD	Dólar canadiense
CHF	Franco suizo
CLP	Peso chileno
CRC	Colón costarricense
GBP	Libra esterlina
GTQ	Quetzal guatemalteco
HNL	Lempira hondureño
JPY	Yen japonés
MXN	Peso mexicano
NZD	Dólar neozelandés
PAB	Balboa panameño
PEN	Nuevo sol peruano
SGD	Dólar de Singapur
UYU	Peso uruguayo

Estados en Factura Electrónica:

Estado	Recibido por la DIAN	Descripción
Draft	NO	En este estado una factura de tipo electrónico fue guardada satisfactoriamente en Siigo Nube pero no se ha enviado a la DIAN (No tiene CUFE).
Accepted	SÍ	En este estado la factura fue enviada y aceptada por la DIAN.
Rejected	NO	En este estado la factura fue enviada a la DIAN con errores y fue rechazada, se debe corregir y enviar nuevamente desde Siigo Nube.

Authorization

Authorization<token>

In: header

Partner-Id<token>

In: header

Request Body

application/jsonOptional

Represents the request with the invoice information.

documentobject

numberinteger

Represents the sequential number of the document, this number is required depending of document type.

Format: "int64"

namestring

Contains information about document type, document type Id, and the sequential number of the document. For example, 'FV-2-22' indicates that its document type is an 'invoice', its document type id is '2' and its sequential number is '22'.

datestring

Represents the date of the document. This format must be 'yyyy-MM-dd'. For example, '2021-10-31' to indicate the date 'October 31st, 2021'.

customerobject

cost_centerinteger

Represents the id of the cost center, the value of this field must be an integer number that represents the unique id of the cost center.

Format: "int64"

currencyobject

sellerinteger

Represents the Id of the seller associated with the invoice. For example, the id '629' can represent a seller called 'Mike'.

Format: "int64"

retentionsarray<object>

Contains a list information about every Retention associated to invoice.

advance_paymentnumber

Represent the Advance Payment. For example, an advance payment of 33.3 dollars for a product of 40 dollars.

Format: "double"

observationsstring

Represent additional comments in document.

itemsarray<object>

Contains a list of items associated with the invoice.

paymentsarray<object>

Contains a list with payments types associated to invoice.

additional_fieldsobject

stampobject

mailobject

global_chargesarray<object>

Contains information about the global taxes charges associated to document type.

global_discountsarray<object>

Contains information about the global taxes discounts associated to document type.

curl -X POST "https://api.siigo.com/v1/invoices" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {
      "id": 22
    },
    "number": 25,
    "name": "FV-2-22",
    "date": "2021-10-15",
    "customer": {
      "person_type": "\'Person\'",
      "id_type": "13",
      "identification": "13832081",
      "check_digit": "4",
      "name": [
        "string"
      ],
      "commercial_name": "string",
      "branch_office": 0,
      "active": true,
      "vat_responsible": true,
      "fiscal_responsibilities": [
        {
          "code": "R-99-PN",
          "name": "Not responsible"
        }
      ],
      "address": {
        "address": "Cra. 18 #79A - 42",
        "city": {
          "country_code": "Co",
          "state_code": "19",
          "city_code": "19001"
        },
        "postal_code": "110911"
      },
      "phones": [
        {
          "indicative": "57",
          "number": "3006003345",
          "extension": "132"
        }
      ],
      "contacts": [
        {
          "first_name": "Marcos",
          "last_name": "Castillo",
          "email": "[email protected]",
          "phone": {
            "indicative": "57",
            "number": "3006003345",
            "extension": "132"
          }
        }
      ],
      "comments": "This is an additional comment",
      "related_users": {
        "seller_id": 625,
        "collector_id": 625
      },
      "custom_fields": [
        {
          "key": "YearsOld",
          "value": "29"
        }
      ],
      "type": "string"
    },
    "cost_center": 235,
    "currency": {
      "code": "USD",
      "exchange_rate": 3825.03
    },
    "seller": 629,
    "retentions": [
      {
        "id": 13156
      }
    ],
    "advance_payment": 33.3,
    "observations": "This is an observation",
    "items": [
      {
        "code": "Item-1",
        "description": "This is a description",
        "warehouse": 15,
        "quantity": 2,
        "price": 50,
        "taxed_price": 60,
        "total_price": 60,
        "discount": 13,
        "seller": 629,
        "vat_excluded": false,
        "taxes": [
          {
            "id": 13156
          }
        ]
      }
    ],
    "payments": [
      {
        "id": 5636,
        "value": 1273.03,
        "due_date": "2021-03-19"
      }
    ],
    "additional_fields": {
      "purchase_order": {
        "prefix": "OC",
        "number": "27"
      },
      "delivery_order": {
        "prefix": "OC",
        "number": "27",
        "date": "2021-05-19"
      }
    },
    "stamp": {
      "send": true
    },
    "mail": {
      "send": true
    },
    "global_charges": [
      {
        "id": 13156,
        "percentage": 0
      }
    ],
    "global_discounts": [
      {
        "id": 13156,
        "percentage": 0
      }
    ]
  }'

Success

{
  "id": "63f918c2-ca65-4edc-a7db-66bcdd5159fb",
  "document": {
    "id": 22
  },
  "prefix": "FV",
  "number": 25,
  "name": "FV-2-22",
  "date": "2021-10-10",
  "customer": {
    "id": "302580df-838b-4531-b8bf-dd3c98b34059",
    "identification": "13832081",
    "branch_office": 0
  },
  "cost_center": 235,
  "currency": {
    "code": "USD",
    "exchange_rate": 3825.03
  },
  "seller": 629,
  "retentions": [
    {
      "id": 13156,
      "name": "VAT 19%",
      "type": "Retefuente",
      "percentage": 19,
      "value": 5
    }
  ],
  "advance_payment": 33.3,
  "total": 25.5,
  "balance": 30302.24,
  "observations": "This is an observation",
  "items": [
    {
      "id": "63f918c2-ca65-4edc-a7db-66bcdd5159fb",
      "code": "Item-1",
      "quantity": 2,
      "price": 50,
      "seller": 629,
      "description": "This is a description",
      "discount": {
        "percentage": 13,
        "value": 130
      },
      "taxes": [
        {
          "id": 13156,
          "name": "VAT 19%",
          "type": "IVA",
          "percentage": 19,
          "value": 5,
          "base_value": 2000
        }
      ],
      "warehouse": {
        "id": 15,
        "name": "Main Warehouse"
      },
      "total": 119000
    }
  ],
  "global_charges": [
    {
      "id": 0,
      "name": "string",
      "percentage": 0,
      "value": 0
    }
  ],
  "global_discounts": [
    {
      "id": 0,
      "name": "string",
      "percentage": 0,
      "value": 0
    }
  ],
  "payments": [
    {
      "id": 5636,
      "name": "Credit",
      "value": 1273.03,
      "due_date": "2021-03-19"
    }
  ],
  "additional_fields": {
    "purchase_order": {
      "prefix": "OC",
      "number": "27"
    },
    "delivery_order": {
      "prefix": "OE",
      "number": "27",
      "date": "2021-05-19"
    }
  },
  "stamp": {
    "status": "string",
    "cufe": "string",
    "cude": "string",
    "observations": "string",
    "errors": "string"
  },
  "mail": {
    "status": "string",
    "observations": "string"
  },
  "metadata": {
    "created": "string",
    "last_updated": "string",
    "stock_updated": "string"
  },
  "annulled": true
}

Crear Factura.

Response

TypeScript