Crea un documento equivalente electrónico tiquete POS

POST/api/v1/documents/pos

Documento equivalente electrónico del tiquete de máquina registradora con sistema P.O.S. (tipo 20, Anexo de documento equivalente 1.0). Mismo cuerpo que la factura más point_of_sale (datos de la caja, obligatorios). Necesita un rango de tipo pos con su resolución. Para consumidor final envía customer con document_number 222222222222. Probado con la DIAN (EPOS1-3 y NAP1-2, 2026-11-12).

Parámetros de consulta

waitinteger
Segundos (máximo 10) que la petición espera el resultado de la DIAN. Si llega, responde 200 con número, CUFE y estado final; si no, 202 y el resultado llega por webhook. mínimo 0, máximo 10.

Cuerpo de la petición application/json

Montos, cantidades y tarifas van como texto decimal: "5000.00", "19".

external_idstring· máx. 128 caracteresobligatorio
Ejemplo: pedido-77
numbering_range_idstring · uuid
Opcional si la cuenta tiene un solo rango activo del tipo de documento
issued_atstring · date-time
Vacío = ahora
currencystring
ISO 4217 (lista TipoMoneda de la DIAN); vacío = COP. En otra moneda los montos se envían en esa moneda y factuROA los convierte a pesos con exchange_rate: el XML va en COP y la moneda original queda en PaymentExchangeRate y en el PDF
Ejemplo: USD
exchange_rateobject
Obligatoria si currency no es COP: pesos por unidad de la moneda y fecha en que se fijó (la TRM o la pactada con el comprador). factuROA no calcula ni consulta la tasa: la informa y responde por ella el emisor
+ Ver 2 campos− Ocultar 2 campos
- ratestringobligatorio
  Ejemplo: 4123.45
- datestring · dateobligatorio
exportboolean
Factura de exportación (tipo 02). Solo factura de venta; cada línea exige brand y model
delivery_termsobject
Condiciones de entrega de la exportación
+ Ver 2 campos− Ocultar 2 campos
- incotermstringobligatorio
  Valores: CFR · CIF · CIP · CPT · DAP · DAT · DDP · EXW · FAS · FCA · FOB
- special_termsstring
  Ejemplo: Portes pagados
customerobjectobligatorio
+ Ver 11 campos− Ocultar 11 campos
- person_typeinteger
  1 jurídica, 2 natural
  Valores: 1 · 2
- document_typestringobligatorio
  13 cédula, 31 NIT, 22 cédula de extranjería, 41 pasaporte...
  Ejemplo: 13
- document_numberstringobligatorio
  Ejemplo: 1020304050
- dvstring
- namestringobligatorio
  Ejemplo: Ana Pérez
- trade_namestring
- emailstring
- phonestring
- addressobject
  + Ver 8 campos− Ocultar 8 campos
  - linestring
    Ejemplo: Cra 7 # 71-21
  - city_codestring
    DIVIPOLA del municipio (5 dígitos)
    Ejemplo: 11001
  - city_namestring
    Ejemplo: Bogotá, D.C.
  - department_codestring
    DIVIPOLA del departamento (2 dígitos)
    Ejemplo: 11
  - department_namestring
    Ejemplo: Bogotá
  - postal_zonestring
  - country_codestring
    ISO 3166-1; vacío = CO
  - country_namestring
- tax_level_codesarray<string>
- tax_schemestring
  Ejemplo: ZZ
paymentobject
+ Ver 3 campos− Ocultar 3 campos
- methodinteger
  1 contado, 2 crédito
  Valores: 1 · 2
- means_codestring
  10 efectivo, 42 consignación, 47 transferencia, 48 tarjeta crédito, 49 tarjeta débito, ZZZ otro
  Ejemplo: 42
- due_datestring · date
  Ejemplo: 2026-11-30
notesarray<string>
linesarray<object>· máx. 500 elementosobligatorio
+ Ver 11 campos− Ocultar 11 campos
- descriptionstringobligatorio
  Ejemplo: Café
- item_codestring
- brandstring
  Marca (opcional; la DIAN la notifica si falta en documento soporte)
- modelstring
  Modelo (opcional)
- quantitystringobligatorio
  Ejemplo: 2
- unit_codestringobligatorio
  Ejemplo: EA
- unit_pricestringobligatorio
  Ejemplo: 5000.00
- price_includes_taxboolean· por defecto false
  unit_price es el precio final con impuestos incluidos (como se cobra en caja). factuROA calcula la base (precio / (1 + suma de tarifas)) y agrega PayableRoundingAmount para que el total sea exactamente la suma de cantidad por precio final (3 × 4990 con IVA 19 % = 14970.00). Solo con impuestos por porcentaje y sin allowances en la línea.
- taxesarray<object>
  + Ver 6 campos− Ocultar 6 campos
  - codestringobligatorio
    Por porcentaje: 01 IVA (0, 5, 16, 19), 04 INC (2, 4, 8, 16), 03 ICA, 35 ICUI (10, 15, 20). Por unidad (sin rate, con per_unit_amount): 22 INC bolsas plásticas, 34 IBUA.
    Valores: 01 · 04 · 03 · 35 · 22 · 34
  - ratestring
    Porcentaje con hasta 3 decimales
    Ejemplo: 19
  - per_unit_amountstring
    Ejemplo: 5000.00
  - base_quantitystring
    Cantidad a la que aplica per_unit_amount (IBUA: 100 ml). Vacío = 1
    Ejemplo: 100
  - base_unit_codestring
    Unidad de base_quantity. Vacío = la de la línea
    Ejemplo: MLT
  - taxable_quantitystring
    Cantidad gravada (IBUA: ml totales). Vacío = cantidad de la línea
    Ejemplo: 1200
- allowancesarray<object>
  Descuentos y cargos de la línea; cambian el valor de la línea y la base de los impuestos.
  + Ver 4 campos− Ocultar 4 campos
  - typestringobligatorio
    Valores: discount · charge
  - reasonstringobligatorio
    Ejemplo: Pronto pago
  - reason_codestring
    Solo descuentos del documento: 00 no condicionado, 01 condicionado
    Valores: 00 · 01
  - amountstringobligatorio
    Ejemplo: 5000.00
- purchase_datestring · date
  Ejemplo: 2026-11-30
deliveryobject
Obligatoria cuando el adquiriente no da NIT y la venta es fuera del local (Res. 165 de 2023, art. 11 num. 3).
+ Ver 2 campos− Ocultar 2 campos
- addressobjectobligatorio
  + Ver 8 campos− Ocultar 8 campos
  - linestring
    Ejemplo: Cra 7 # 71-21
  - city_codestring
    DIVIPOLA del municipio (5 dígitos)
    Ejemplo: 11001
  - city_namestring
    Ejemplo: Bogotá, D.C.
  - department_codestring
    DIVIPOLA del departamento (2 dígitos)
    Ejemplo: 11
  - department_namestring
    Ejemplo: Bogotá
  - postal_zonestring
  - country_codestring
    ISO 3166-1; vacío = CO
  - country_namestring
- datestring · date
  Ejemplo: 2026-11-30
allowancesarray<object>
Descuentos y cargos del documento; no cambian la base de los impuestos, sí el total a pagar.
+ Ver 4 campos− Ocultar 4 campos
- typestringobligatorio
  Valores: discount · charge
- reasonstringobligatorio
  Ejemplo: Pronto pago
- reason_codestring
  Solo descuentos del documento: 00 no condicionado, 01 condicionado
  Valores: 00 · 01
- amountstringobligatorio
  Ejemplo: 5000.00
withholdingsarray<object>
Retenciones informativas (solo factura y documento soporte); no se restan del total a pagar.
+ Ver 3 campos− Ocultar 3 campos
- codestringobligatorio
  05 ReteIVA, 06 ReteFuente (renta), 07 ReteICA
  Valores: 05 · 06 · 07
- ratestringobligatorio
  Porcentaje con hasta 3 decimales
  Ejemplo: 19
- basestringobligatorio
  Ejemplo: 5000.00
prepaymentsarray<object>
Anticipos recibidos antes de facturar (solo factura de venta); se restan del total a pagar.
+ Ver 4 campos− Ocultar 4 campos
- idstringobligatorio
  Recibo o transacción del anticipo
  Ejemplo: RC-1001
- amountstringobligatorio
  Ejemplo: 5000.00
- received_datestring · date
  Ejemplo: 2026-11-30
- instructionstring
  Ejemplo: Anticipo recibido
point_of_saleobjectobligatorio
Datos de la caja (extensión InformacionCajaVenta de la DIAN)
+ Ver 5 campos− Ocultar 5 campos
- register_platestringobligatorio
  Placa de inventario de la caja
  Ejemplo: CJ001
- locationstringobligatorio
  Ejemplo: Local 1
- cashierstringobligatorio
  Nombres y apellidos del cajero o vendedor
  Ejemplo: ANA PEREZ
- register_typestringobligatorio
  Ejemplo: Principal
- sale_codestringobligatorio
  Ejemplo: V-77

Respuestas

202Documento en fila (pending). El número, el CUFE y la firma se asignan al enviarlo a la DIAN.

idstring · uuid
account_idstring · uuid
Cuenta emisora; una casa de software la usa para saber de qué cliente es el aviso
document_typestring
Valores: invoice · credit_note · debit_note · support_document · support_document_adjustment · payroll · payroll_adjustment · pos · pos_adjustment · pos_debit_adjustment
external_idstring
reference_document_idstring · uuid
prefixstring
numberinteger
null hasta que se envía a la DIAN; un rechazo lo libera
full_numberstring
Ejemplo: SETP990000001
document_keystring
CUFE, CUDE, CUDS o CUNE según el tipo
Ejemplo: a3f1c9...e2
environmentinteger
1 producción, 2 habilitación
Valores: 1 · 2
stagingboolean
Documento de prueba (cuenta en staging): no fue a la DIAN y no tiene validez fiscal
issued_atstring · date-time
customer_idstring
Contraparte: adquirente, vendedor (documento soporte) o trabajador (nómina)
customer_namestring
Ejemplo: PÉREZ GÓMEZ ANA
currencystring
Siempre COP: el XML y los montos van en pesos (regla FAD15 del Anexo 1.9)
Ejemplo: COP
payable_amountstring
Ejemplo: 5000.00
foreignobject
Solo si se facturó en otra moneda: moneda, tasa usada y total en esa moneda
+ Ver 3 campos− Ocultar 3 campos
- currencystring
  Ejemplo: USD
- exchange_ratestring
  Ejemplo: 4123.45
- payable_amountstring
  Ejemplo: 5000.00
statusstring
pending esperando al worker, submitted enviado y esperando a la DIAN, accepted, rejected (por la DIAN, final) y failed (se agotaron los reintentos).
Valores: pending · submitted · accepted · rejected · failed
dianobject
+ Ver 5 campos− Ocultar 5 campos
- track_idstring
- status_codestring
  Ejemplo: 00
- status_descriptionstring
- errorsarray<string>
- rulesarray<object>
  errors separados: regla, tipo (rejection rechaza el documento; notification no impide la aceptación), mensaje de la DIAN y, si factuROA la conoce, cómo corregirla
  + Ver 4 campos− Ocultar 4 campos
  - rulestring
    Ejemplo: FAJ44b
  - typestring
    Valores: rejection · notification
  - messagestring
  - hintstring
    Ejemplo: Emisor persona natural: usa document_type 13 (cédula) en vez de 31.
attemptsinteger
errorobject
Solo si factuROA rechazó el documento sin enviarlo a la DIAN (p. ej. error.plan.no_documents: se quedó en fila cuando el plan se agotó o venció con la renovación cancelada)
+ Ver 2 campos− Ocultar 2 campos
- codestring
  Ejemplo: error.plan.no_documents
- messagestring
emailobject
Correo al adquiriente con el AttachedDocument y el PDF (solo facturas y notas aceptadas, con FACTUROA_EMAIL_FROM configurado).
+ Ver 6 campos− Ocultar 6 campos
- statusstring
  abandoned: sin correo válido del adquiriente o intentos agotados (ver last_error)
  Valores: pending · sent · abandoned
- attemptsinteger
- sent_atstring · date-time
- last_errorstring
- recipientstring
  Dirección del último reenvío (si se pidió otra)
- resendsinteger
  Reenvíos pedidos (máximo 5)
created_atstring · date-time
updated_atstring · date-time

200Ya existía un documento con ese external_id; se devuelve sin crear otro.

idstring · uuid
account_idstring · uuid
Cuenta emisora; una casa de software la usa para saber de qué cliente es el aviso
document_typestring
Valores: invoice · credit_note · debit_note · support_document · support_document_adjustment · payroll · payroll_adjustment · pos · pos_adjustment · pos_debit_adjustment
external_idstring
reference_document_idstring · uuid
prefixstring
numberinteger
null hasta que se envía a la DIAN; un rechazo lo libera
full_numberstring
Ejemplo: SETP990000001
document_keystring
CUFE, CUDE, CUDS o CUNE según el tipo
Ejemplo: a3f1c9...e2
environmentinteger
1 producción, 2 habilitación
Valores: 1 · 2
stagingboolean
Documento de prueba (cuenta en staging): no fue a la DIAN y no tiene validez fiscal
issued_atstring · date-time
customer_idstring
Contraparte: adquirente, vendedor (documento soporte) o trabajador (nómina)
customer_namestring
Ejemplo: PÉREZ GÓMEZ ANA
currencystring
Siempre COP: el XML y los montos van en pesos (regla FAD15 del Anexo 1.9)
Ejemplo: COP
payable_amountstring
Ejemplo: 5000.00
foreignobject
Solo si se facturó en otra moneda: moneda, tasa usada y total en esa moneda
+ Ver 3 campos− Ocultar 3 campos
- currencystring
  Ejemplo: USD
- exchange_ratestring
  Ejemplo: 4123.45
- payable_amountstring
  Ejemplo: 5000.00
statusstring
pending esperando al worker, submitted enviado y esperando a la DIAN, accepted, rejected (por la DIAN, final) y failed (se agotaron los reintentos).
Valores: pending · submitted · accepted · rejected · failed
dianobject
+ Ver 5 campos− Ocultar 5 campos
- track_idstring
- status_codestring
  Ejemplo: 00
- status_descriptionstring
- errorsarray<string>
- rulesarray<object>
  errors separados: regla, tipo (rejection rechaza el documento; notification no impide la aceptación), mensaje de la DIAN y, si factuROA la conoce, cómo corregirla
  + Ver 4 campos− Ocultar 4 campos
  - rulestring
    Ejemplo: FAJ44b
  - typestring
    Valores: rejection · notification
  - messagestring
  - hintstring
    Ejemplo: Emisor persona natural: usa document_type 13 (cédula) en vez de 31.
attemptsinteger
errorobject
Solo si factuROA rechazó el documento sin enviarlo a la DIAN (p. ej. error.plan.no_documents: se quedó en fila cuando el plan se agotó o venció con la renovación cancelada)
+ Ver 2 campos− Ocultar 2 campos
- codestring
  Ejemplo: error.plan.no_documents
- messagestring
emailobject
Correo al adquiriente con el AttachedDocument y el PDF (solo facturas y notas aceptadas, con FACTUROA_EMAIL_FROM configurado).
+ Ver 6 campos− Ocultar 6 campos
- statusstring
  abandoned: sin correo válido del adquiriente o intentos agotados (ver last_error)
  Valores: pending · sent · abandoned
- attemptsinteger
- sent_atstring · date-time
- last_errorstring
- recipientstring
  Dirección del último reenvío (si se pidió otra)
- resendsinteger
  Reenvíos pedidos (máximo 5)
created_atstring · date-time
updated_atstring · date-time

402En producción la cuenta (o su casa de software) no tiene un plan activo: error.plan.inactive. No se crea el documento

codestring
Ejemplo: error.document.invalid
messagestring
errorsarray<object>
Solo en 400: cada campo inválido con su explicación (en español, o en inglés con Accept-Language: en)
+ Ver 2 campos− Ocultar 2 campos
- fieldstring
  Ruta del campo en el JSON enviado
  Ejemplo: lines[0].quantity
- messagestring
  Ejemplo: Cantidad inválida: debe ser mayor que cero.
detailsarray<string>
Rutas de los campos inválidos (compatibilidad; usa errors)
request_idstring

400Datos inválidos (details trae los campos)

codestring
Ejemplo: error.document.invalid
messagestring
errorsarray<object>
Solo en 400: cada campo inválido con su explicación (en español, o en inglés con Accept-Language: en)
+ Ver 2 campos− Ocultar 2 campos
- fieldstring
  Ruta del campo en el JSON enviado
  Ejemplo: lines[0].quantity
- messagestring
  Ejemplo: Cantidad inválida: debe ser mayor que cero.
detailsarray<string>
Rutas de los campos inválidos (compatibilidad; usa errors)
request_idstring

401Falta la key o es inválida, está deshabilitada, vencida o revocada (error.missing_api_key, error.invalid_api_key, error.api_key.disabled, error.api_key.expired, error.api_key.revoked)

codestring
Ejemplo: error.document.invalid
messagestring
errorsarray<object>
Solo en 400: cada campo inválido con su explicación (en español, o en inglés con Accept-Language: en)
+ Ver 2 campos− Ocultar 2 campos
- fieldstring
  Ruta del campo en el JSON enviado
  Ejemplo: lines[0].quantity
- messagestring
  Ejemplo: Cantidad inválida: debe ser mayor que cero.
detailsarray<string>
Rutas de los campos inválidos (compatibilidad; usa errors)
request_idstring

409Conflicto con el estado actual (p. ej. documento referenciado no aceptado, rango agotado)

codestring
Ejemplo: error.document.invalid
messagestring
errorsarray<object>
Solo en 400: cada campo inválido con su explicación (en español, o en inglés con Accept-Language: en)
+ Ver 2 campos− Ocultar 2 campos
- fieldstring
  Ruta del campo en el JSON enviado
  Ejemplo: lines[0].quantity
- messagestring
  Ejemplo: Cantidad inválida: debe ser mayor que cero.
detailsarray<string>
Rutas de los campos inválidos (compatibilidad; usa errors)
request_idstring

422Faltan datos para generar el XML (error.document.incomplete, campos en details)

codestring
Ejemplo: error.document.invalid
messagestring
errorsarray<object>
Solo en 400: cada campo inválido con su explicación (en español, o en inglés con Accept-Language: en)
+ Ver 2 campos− Ocultar 2 campos
- fieldstring
  Ruta del campo en el JSON enviado
  Ejemplo: lines[0].quantity
- messagestring
  Ejemplo: Cantidad inválida: debe ser mayor que cero.
detailsarray<string>
Rutas de los campos inválidos (compatibilidad; usa errors)
request_idstring