Admitir Invoice
/v1/invoicesEstado: parcial. Ambientes: simulation, qualification. Permisos: documents:write.
Alcance: Admite el perfil restringido COP, IVA 0/5/19, unidad 94, producto 999, pago 10 y BaseQuantity 1. simulation produce resultados ficticios; qualification exige rango, certificado, autorización revisada y configuración vigentes. La respuesta 202 confirma recepción, no 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.
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 Secreto ligado a empresa, actor, permisos y ambiente. No admite cambiar empresa por body/header.
In: header
Header Parameters
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.
^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$1 <= length <= 128Request 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/invoices" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "document_type": "invoice", "external_reference": "DEMO-INVOICE-001", "profile_id": "co-sale-cop-v1", "numbering_range_id": "00000000-0000-4000-8000-000000000010", "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": [] } ], "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" ] } }'{ "operation_id": "00000000-0000-4000-8000-000000000030", "document_id": "00000000-0000-4000-8000-000000000020", "revision": 1, "version": 1, "environment": "simulation", "external_reference": "DEMO-INVOICE-001", "processing_status": "queued", "dian_status": "not_sent", "billing_status": "not_billable", "created_at": "2026-09-10T15:00:00Z", "status_url": "/v1/documents/00000000-0000-4000-8000-000000000020"}Solicitar reenvío al comprador POST
**Estado:** parcial. **Ambientes:** simulation, qualification. **Permisos:** `documents:deliver`. **Alcance:** Entrega de ensayo de una revisión validada. Idempotente, diez solicitudes manuales por documento/revisión/hora, cien destinatarios activos por empresa/ambiente y sin duplicar destinatarios pendientes. Espera el paquete completo. No envía correo real. Solicitar reenvío al comprador
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.