Cufy API
Documento equivalente POS

Admitir PosReceipt

POST/v1/pos-receipts

Estado: parcial. Ambientes: qualification. Permisos: documents:write.

Alcance: Solo qualification (habilitación DIAN). Tiquete P.O.S. con CUDE sembrado con el PIN del software, pago de contado, adquiriente sin dirección y rango propio autorizado por la DIAN (tipo pos_equivalent, clase authorized_invoice). point_of_sale es obligatorio: sale en la extensión InformacionCajaVenta. La configuración DIAN del rango debe declarar provider_name y software_name (extensión FabricanteSoftware) y la autorización de firma debe incluir pos_equivalent. Alternativa AG-041: customer_id de un cliente guardado activo en lugar de buyer (nunca los dos: BUYER_SOURCE_CONFLICT; ninguno: VALIDATION_ERROR con BUYER_REQUIRED); el documento conserva la copia del comprador al admitirlo y un reintento recupera el mismo documento aunque el cliente cambie.

202 admite una revisión de forma durable y reserva saldo. La DIAN responde después. Mismo Idempotency-Key o referencia equivalente recupera la admisión original sin nueva reserva, aunque el cliente guardado haya cambiado o se haya archivado después. No transmitir si la capability no está habilitada. Acepta buyer completo o customer_id de un cliente guardado activo (nunca los dos): el documento conserva la copia del comprador al admitirlo. customer_id ajeno o inexistente: 404 CUSTOMER_NOT_FOUND; archivado: 409 CUSTOMER_ARCHIVED.

Authorization

ClientApiKey
X-API-Key<token>

Secreto ligado a empresa, actor, permisos y ambiente. No admite cambiar empresa por body/header.

In: header

Header Parameters

Idempotency-Key*string

Obligatoria en mutaciones. Alcance: empresa/ambiente/operación/recurso destino. Retención mínima 90 días y mientras haya trabajo pendiente. Mismo contenido recupera resultado; contenido diferente produce 409.

Match^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$
Length1 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

buyer completo (PosReceiptRequest) o customer_id de un cliente guardado activo (CustomerPosReceiptRequest), nunca los dos ni ninguno.

Documento equivalente electrónico tiquete de máquina registradora con sistema P.O.S. Se identifica con CUDE, no con CUFE. Exige pago de contado. El adquiriente no lleva dirección. Requiere su propia autorización de numeración y los datos de la caja que lo expide.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/pos-receipts" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "document_type": "pos_equivalent",    "external_reference": "DEMO-POS-001",    "profile_id": "co-pos-equivalent-cop-v1",    "numbering_range_id": "00000000-0000-4000-8000-000000000013",    "issued_at": "2026-09-10T13:30:00-05:00",    "currency": "COP",    "buyer": {      "party_type": "person",      "identification": {        "type_code": "13",        "number": "1000000000"      },      "name": "Comprador de ejemplo",      "email": "comprador@example.com",      "tax_registration": {        "responsibility_codes": [          "R-99-PN"        ],        "tax_scheme_codes": [          "01"        ]      }    },    "lines": [      {        "id": "1",        "description": "Bandeja paisa, datos ficticios",        "product_identification": {          "scheme_code": "999",          "value": "DEMO-POS-001"        },        "quantity": "2",        "unit_code": "94",        "unit_price": "32000.00",        "price_base_quantity": "1",        "net_amount": "64000.00",        "adjustments": [],        "taxes": [          {            "code": "01",            "rate": "19",            "taxable_amount": "64000.00",            "amount": "12160.00"          }        ],        "withholdings": []      },      {        "id": "2",        "description": "Limonada de coco, datos ficticios",        "product_identification": {          "scheme_code": "999",          "value": "DEMO-POS-002"        },        "quantity": "2",        "unit_code": "94",        "unit_price": "9000.00",        "price_base_quantity": "1",        "net_amount": "18000.00",        "adjustments": [],        "taxes": [          {            "code": "01",            "rate": "19",            "taxable_amount": "18000.00",            "amount": "3420.00"          }        ],        "withholdings": []      }    ],    "adjustments": [],    "tax_totals": [      {        "code": "01",        "rate": "19",        "taxable_amount": "82000.00",        "amount": "15580.00"      }    ],    "withholding_totals": [],    "totals": {      "line_extension_amount": "82000.00",      "tax_exclusive_amount": "82000.00",      "tax_inclusive_amount": "97580.00",      "allowance_total_amount": "0.00",      "charge_total_amount": "0.00",      "prepaid_amount": "0.00",      "payable_rounding_amount": "0.00",      "payable_amount": "97580.00"    },    "payment": {      "terms": "cash",      "means_code": "10"    },    "delivery": {      "mode": "cufy_email",      "recipients": [        "comprador@example.com"      ]    },    "point_of_sale": {      "register_id": "CAJA-01",      "location": "Salón principal",      "cashier": "Cajero de ejemplo",      "register_type": "Caja principal",      "sale_code": "VENTA-000123"    }  }'
{  "operation_id": "cb4ede3c-a5d1-45e3-a9d2-fe83accbce52",  "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",  "revision": 1,  "version": 1,  "environment": "simulation",  "external_reference": "string",  "processing_status": "queued",  "dian_status": "not_sent",  "billing_status": "not_reserved",  "created_at": "2019-08-24T14:15:22Z",  "status_url": "../dictionary"}

Admitir DebitNote POST

**Estado:** parcial. **Ambientes:** qualification. **Permisos:** `documents:write`. **Alcance:** Solo qualification, motivo 3 de aumento de valor, sin aumentar cantidad física. No admite NC activa ni más de una ND sin resolver por factura; exige precio, base e IVA compatibles con seis decimales. Conserva exactamente el comprador y hereda las reglas de la factura original; originales v1 siguen pudiendo ajustarse. No admite customer_id (422 CUSTOMER_ID_NOT_SUPPORTED): el comprador debe repetir el del original. 202 admite una revisión de forma durable y reserva saldo. La DIAN responde después. Mismo Idempotency-Key o referencia equivalente recupera la admisión original sin nueva reserva, aunque el cliente guardado haya cambiado o se haya archivado después. No transmitir si la capability no está habilitada. Solo buyer completo: customer_id responde 422 CUSTOMER_ID_NOT_SUPPORTED porque el comprador debe coincidir con el del original.

Admitir PosCreditNote POST

**Estado:** parcial. **Ambientes:** qualification. **Permisos:** `documents:write`. **Alcance:** Solo qualification, sobre un tiquete P.O.S. propio validado. Consecutivo interno del emisor (tipo pos_credit_note, clase note_sequence) con configuración SendBillSync. Referencia al tiquete por su CUDE con DocumentTypeCode 20; motivos del anexo 1 a 5. Conserva exactamente el comprador del tiquete. No admite customer_id (422 CUSTOMER_ID_NOT_SUPPORTED): el comprador debe repetir el del original. 202 admite una revisión de forma durable y reserva saldo. La DIAN responde después. Mismo Idempotency-Key o referencia equivalente recupera la admisión original sin nueva reserva, aunque el cliente guardado haya cambiado o se haya archivado después. No transmitir si la capability no está habilitada. Solo buyer completo: customer_id responde 422 CUSTOMER_ID_NOT_SUPPORTED porque el comprador debe coincidir con el del original.