Cufy API
Notas débito

Admitir DebitNote

POST/v1/debit-notes

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.

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.

Nota sobre factura validada propia; empresa, comprador, moneda, referencias y saldo ajustable se contrastan con el original. No se aceptan facturas externas en este perfil.

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/debit-notes" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "document_type": "debit_note",    "external_reference": "DEMO-DEBIT-001",    "profile_id": "co-referenced-note-cop-v1",    "numbering_range_id": "00000000-0000-4000-8000-000000000012",    "issued_at": "2026-09-10T10:00: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": "Servicio de ejemplo, datos ficticios",        "product_identification": {          "scheme_code": "999",          "value": "DEMO-001"        },        "quantity": "1",        "unit_code": "94",        "unit_price": "10000.00",        "price_base_quantity": "1",        "net_amount": "10000.00",        "adjustments": [],        "taxes": [          {            "code": "01",            "rate": "19",            "taxable_amount": "10000.00",            "amount": "1900.00"          }        ],        "withholdings": [],        "original_line_id": "1"      }    ],    "adjustments": [],    "tax_totals": [      {        "code": "01",        "rate": "19",        "taxable_amount": "10000.00",        "amount": "1900.00"      }    ],    "withholding_totals": [],    "totals": {      "line_extension_amount": "10000.00",      "tax_exclusive_amount": "10000.00",      "tax_inclusive_amount": "11900.00",      "allowance_total_amount": "0.00",      "charge_total_amount": "0.00",      "prepaid_amount": "0.00",      "payable_rounding_amount": "0.00",      "payable_amount": "11900.00"    },    "payment": {      "terms": "cash",      "means_code": "10"    },    "delivery": {      "mode": "cufy_email",      "recipients": [        "comprador@example.com"      ]    },    "original_document_id": "00000000-0000-4000-8000-000000000020",    "discrepancy_reason": {      "code": "3",      "description": "Cambio de valor de ejemplo",      "reference_id": "1"    },    "adjustment_scope": "partial"  }'
{  "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 CreditNote POST

**Estado:** parcial. **Ambientes:** qualification. **Permisos:** `documents:write`. **Alcance:** Solo qualification, sobre factura propia aceptada, motivos 1/2 y sin anticipos ni retenciones. Permite ND aceptadas anteriores con las reglas de precisión implementadas; las notas pendientes o inciertas reservan saldo. 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 PosReceipt POST

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