Trifaco API
Prevalidación de notas crédito

Prevalidar nota crédito y saldo contextual

POST/v1/credit-note-validations

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

Alcance: Comprueba estructura, cálculo y contexto del saldo de la factura original sin reservar ni emitir. Los errores semánticos devuelven 200 con valid=false; entrada mal formada devuelve 400 y referencias inaccesibles 404. La emisión de notas solo está disponible en qualification. Conserva exactamente el comprador y hereda las reglas de la factura original; originales v1 siguen pudiendo ajustarse.

No reserva, asigna número, firma ni transmite. 200 valid=false para errores fiscales/contextuales; referencias ajenas o de otro ambiente conservan 404. Un resultado válido no garantiza admisión futura. Errores contextuales usan CREDIT_CONTEXT_INVALID y detalle en message.

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/credit-note-validations" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "document_type": "credit_note",    "external_reference": "TRIF11-CREDIT-TOTAL-001",    "profile_id": "co-referenced-note-cop-v1",    "numbering_range_id": "00000000-0000-4000-8000-000000000011",    "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": "0.5",        "unit_code": "94",        "unit_price": "12000",        "price_base_quantity": "1",        "net_amount": "6000",        "adjustments": [],        "taxes": [          {            "code": "01",            "rate": "19",            "taxable_amount": "6000",            "amount": "1140"          }        ],        "withholdings": [],        "original_line_id": "1"      }    ],    "adjustments": [],    "tax_totals": [      {        "code": "01",        "rate": "19",        "taxable_amount": "6000",        "amount": "1140"      }    ],    "withholding_totals": [],    "totals": {      "line_extension_amount": "6000",      "tax_exclusive_amount": "6000",      "tax_inclusive_amount": "7140",      "allowance_total_amount": "0.00",      "charge_total_amount": "0.00",      "prepaid_amount": "0.00",      "payable_rounding_amount": "0.00",      "payable_amount": "7140"    },    "payment": {      "terms": "cash",      "means_code": "10"    },    "delivery": {      "mode": "trifaco_email",      "recipients": [        "comprador@example.com"      ]    },    "original_document_id": "00000000-0000-4000-8000-000000000020",    "discrepancy_reason": {      "code": "2",      "description": "Caso sintético TRIF-11, devolución de saldo ajustado"    },    "adjustment_scope": "total"  }'
{  "valid": true,  "rules_version": "string",  "errors": [],  "warnings": [],  "calculated_totals": {    "line_extension_amount": "string",    "tax_exclusive_amount": "string",    "tax_inclusive_amount": "string",    "allowance_total_amount": "string",    "charge_total_amount": "string",    "prepaid_amount": "string",    "payable_rounding_amount": "string",    "payable_amount": "string"  }}

Validar entrada sin emitir POST

**Estado:** parcial. **Ambientes:** simulation, qualification. **Permisos:** `documents:write`. **Alcance:** Comprueba estructura e importes del perfil fiscal local sin admitir trabajo ni consumir numeración. No comprueba preparación de rango o certificado ni garantiza aceptación DIAN. Reglas de comprador v2: persona CC/NIT o empresa NIT con dirección; sin consumidor final ni identidad RUT verificada. Correo ausente solo avisa. Perfil optativo co-sale-cop-iva-v1/v3: IVA gravado/exento/excluido solo en simulación sin firma ni notas; habilitación real bloqueada. Errores de negocio se devuelven con 200 y valid=false; malformación del JSON/estructura no interpretable usa 400/422. No asigna número, firma ni saldo.

Consultar saldo ajustable por línea GET

**Estado:** parcial. **Ambientes:** simulation, qualification. **Permisos:** `documents:read`. **Alcance:** Devuelve un saldo informativo de cantidades, base e IVA del original y sus incrementos. Exige factura propia firmada, completada y validada; el uso efectivo con aceptación fiscal corresponde a qualification. Una admisión posterior puede encontrar un saldo diferente. Factura propia validada. Desglosa cantidad física, base/IVA original e incrementos, consumo, reservas y remanente. Bloqueo explícito ante ND pendiente o redondeo no representable.