Guía

Emitir facturas

Con una llamada a POST /facturas, Conta360 emite la factura electrónica, la valida ante la DIAN, la contabiliza y mueve el inventario.

Ejemplo completo#

bash

curl -X POST https://app.conta360.co/api/v1/facturas \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-00184" \
  -d '{
    "pedido": "Mesa 7 · 184",
    "cliente": { "tipo_documento": "13", "identificacion": "1098765432", "nombres": "Ana Gómez", "correo": "ana@correo.com" },
    "items": [
      { "codigo": "P-0001", "cantidad": 2 },
      { "codigo": "P-0002", "cantidad": 1, "nota": "sin cebolla" }
    ],
    "pagos": [{ "forma": "1", "metodo": "49" }]
  }'

Respuesta 201:

json

{
  "data": {
    "id": "9a7e…",
    "estado": "validated",
    "estado_nombre": "Validada DIAN",
    "validado": true,
    "numero": "SETP990000001",
    "cufe": "a1b2…",
    "total": "116640.00",
    "total_formato": "$ 116.640",
    "qr": "https://…",
    "url_publica": "https://…"
  },
  "cupo": { "mes": "2026-10", "limite": 450, "usados": 138, "disponibles": 312 }
}

El cliente#

Si ya lo tienes en Conta360, manda cliente_id.
Si no, manda el objeto cliente con su identificación: se busca y, si no existe, se crea.
Sin cliente, la venta sale a nombre de consumidor final (222222222222).

Los tipos de documento más usados son 13 cédula, 31 NIT, 22 cédula de extranjería y 41 pasaporte. Los demás valores los traes con GET /catalogos, junto con las formas y métodos de pago, las unidades y los municipios.

Los ítems#

Cada ítem lleva cantidad y el producto, con producto_id o con su codigo. Puedes agregar una nota (por ejemplo, “sin cebolla”).

El conteo solo hace falta cuando el producto se controla por conteo de inventario (por ejemplo, cabezas de ganado). Si el producto se factura por unidad (94), puedes omitirlo: se toma la cantidad.

El precio y el impuesto salen del catálogo de Conta360. Solo con el alcance facturas.precio puedes mandar precio, descuento o líneas fuera del catálogo con nombre.

Los pagos#

Campo	Valores
`forma`	`1` contado (por defecto), `2` crédito
`metodo`	`10` efectivo (por defecto), `47` transferencia, `48` tarjeta crédito, `49` tarjeta débito
`monto`	Valor pagado con ese método
`vence`	Fecha de vencimiento. Obligatoria si la forma es crédito

Si omites pagos, se asume un pago de contado en efectivo por el total.

Probar sin emitir#

Con "borrador": true el documento se guarda en Conta360 sin enviarlo a la DIAN.

Para probar el flujo completo, con validación de la DIAN pero sin validez fiscal, usa el ambiente de pruebas.

Enviar al cliente#

Con qr y url_publica puedes imprimir la tirilla o mandarle el enlace al cliente.
El PDF y el XML están en GET /facturas/{id}/pdf y GET /facturas/{id}/xml. Aquí el id es el de Conta360 (UUID), no el número DIAN.
Con "enviar_email": true Conta360 se lo envía al correo del cliente.

Numeración#

Con rango_numeracion_id eliges el rango de numeración de la factura.

Si no recibiste respuesta#

Consulta el estado con GET /facturas/{id}. Este acepta el id de Conta360, el número DIAN o el código de referencia. No emitas la factura otra vez: mira Errores y estados.

Todos los campos#

Campos de FacturaNueva, tomados de openapi.yaml:

Campo	Tipo	Descripción
`cliente_id`	string	—
`cliente`	ClienteNuevo	Se busca por identificación y se crea si no existe. Sin cliente_id ni cliente, la venta sale a nombre de consumidor final (222222222222).
`pedido`	string	Referencia del pedido en tu sistema; queda en la observación
`observacion`	string	—
`enviar_email`	boolean	Envía el documento al correo del cliente Por defecto `false`.
`rango_numeracion_id`	integer	—
`items` Obligatorio	ItemFactura[]	—
`pagos`	PagoFactura[]	—
`borrador`	boolean	Guarda el documento sin enviarlo a la DIAN Por defecto `false`.
`electronica`	boolean	false = venta sin factura electrónica (por ejemplo, el cajero quitó "Facturar"). Queda como documento interno (número CC-…), se contabiliza y mueve inventario, pero no se envía a la DIAN ni consume el cupo. Por defecto `true`.