Cufy API
Prevalidación de facturas

Validar entrada sin emitir

POST/v1/invoice-validations

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, empresa NIT con dirección o consumidor final (222222222222, tipo 13, R-99-PN, tributo ZZ); sin 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. 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.

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. Con customer_id valida los datos actuales del cliente guardado: uno archivado da valid=false con CUSTOMER_ARCHIVED; uno inexistente o ajeno, 404 CUSTOMER_NOT_FOUND.

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 (InvoiceRequest) o customer_id de un cliente guardado activo (CustomerInvoiceRequest), nunca los dos (BUYER_SOURCE_CONFLICT) ni ninguno (VALIDATION_ERROR con BUYER_REQUIRED en /buyer).

Emisión normal nacional COP. No acepta emisor libre, número, firma, CUFE ni estado DIAN. issued_at conserva fecha y zona explícitas.

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/invoice-validations" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "document_type": "invoice",    "external_reference": "string",    "profile_id": "co-sale-cop-v1",    "numbering_range_id": "d065a90b-5366-48c7-8bff-81d217b766c5",    "issued_at": "2019-08-24T14:15:22Z",    "currency": "COP",    "buyer": {      "party_type": "company",      "identification": {        "type_code": "10",        "number": "string"      },      "name": "string",      "tax_registration": {        "responsibility_codes": [          "string"        ],        "tax_scheme_codes": [          "string"        ]      }    },    "lines": [      {        "id": "string",        "description": "string",        "product_identification": {          "scheme_code": "001",          "value": "string"        },        "quantity": "string",        "unit_code": "string",        "unit_price": "string",        "price_base_quantity": "string",        "net_amount": "string",        "adjustments": [],        "taxes": [],        "withholdings": []      }    ],    "adjustments": [],    "tax_totals": [],    "withholding_totals": [],    "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"    },    "payment": {      "terms": "cash"    }  }'
{  "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"  }}

Consultar salud de servicio y dependencias GET

**Estado:** implementada. **Ambientes:** simulation, qualification. **Permisos:** `company:read`. **Alcance:** Estado autenticado y saneado del último muestreo por ambiente; ausencia/caducidad implica unknown. Incidentes estables de atraso, incertidumbre y recursos, sin conteos de otras empresas. Entrega y cobro comercial permanecen sin soporte. Una respuesta reciente no es una declaración oficial de disponibilidad DIAN. Consultar salud de servicio y dependencias

Prevalidar nota crédito y saldo contextual POST

**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 admite customer_id (422 CUSTOMER_ID_NOT_SUPPORTED): el comprador debe repetir el del original. 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.