Borradores y aprobación

Un borrador es un documento que un agente de IA preparó y que una persona aprueba o descarta en el portal. Nada llega a la DIAN y no se toma número hasta la aprobación: así, un borrador descartado no deja huecos en la numeración.

Los borradores son parte del servidor MCP (el canal de los agentes). La API REST emite directamente; no tiene un endpoint de borradores. Si tu integración es REST pura, esta guía es solo para entender lo que verá tu equipo en el portal.

Cuándo se crea un borrador

• Cuando la conexión de agente tiene una política que exige aprobación (requires_approval) para issue_document, resubmit_document o transcribe_paper_invoice: en lugar de emitir, la herramienta guarda un borrador y responde pending_approval. No pide la confirmación de producción: nada tiene efecto fiscal hasta la aprobación.
• Cuando la persona activa “una persona aprueba todo” en la conexión.
• Cuando el agente llama a propósito a prepare_draft (una revisión previa, un documento por encima de su monto máximo, un lote).

Tipos de borrador: issue (un documento nuevo), resubmit (la corrección de un rejected) y transcribe (la transcripción de un papel). Las herramientas, con sus argumentos exactos, están en la referencia del MCP.

Ejemplo: los argumentos de prepare_draft

Esta es la llamada que hace el agente (los argumentos de la herramienta, que viajan por el protocolo MCP, no por un curl a la API REST). document es exactamente el cuerpo de una emisión REST (emitir una factura):

{
  "company_id": "cmp_...",
  "idempotency_key": "mensualidad-noviembre-0007",
  "batch_id": "Mensualidades de noviembre",
  "note": "Cobro mensual del plan; el valor sale de la planilla de octubre.",
  "document": {
    "resolution_id": "18760000000000",
    "type": "invoice",
    "customer": {"identification": {"type": "nit", "number": "900373076"}, "name": "Comercializadora Andina S.A.S."},
    "lines": [{"description": "Mensualidad", "quantity": "1", "unit_price": "120000.00"}]
  }
}

Y la respuesta mientras espera a la persona, sin error:

{"status": "pending_approval", "draft_id": "...", "replayed": false, "document_id": null}

El recorrido

1. El agente prepara. Se valida como la emisión real (resolución y su vigencia, contenido, empresa configurada) sin numerar. Un documento inválido no se guarda: el error es el de la emisión (422 validation_failed, invalid_state…).
2. La persona revisa en el portal (Documentos, Por aprobar). Puede editar el contenido antes de aprobar; se valida de nuevo y queda registrado quién y cuándo lo editó.
3. Aprueba o descarta. Aprobar ejecuta la escritura real: se numera, se firma y se transmite como cualquier documento. Descartarlo no emite nada. Aprobar dos veces devuelve el mismo documento.

El documento que sale lleva como actor al agente, el origen mcp, y la persona y el instante de la aprobación en approved_by y approved_at.

Idempotencia

Para issue_document y prepare_draft, la clave es la idempotency_key: repetir la llamada con la misma clave y el mismo cuerpo devuelve el mismo borrador (replayed: true), en el estado en que esté (pendiente, aprobado con su document_id, o descartado). Con otro cuerpo, idempotency_key_reused. Al aprobarlo, el documento se emite con esa misma clave. Ver idempotencia y reintentos.

Límites de la conexión de agente

• Monto máximo por documento. Un borrador que lo supera no se rechaza: se guarda marcado como amount_over_limit, y una persona puede aprobarlo por separado. El límite acota lo que el agente hace solo, no lo que decide una persona.
• Tope diario de documentos enviados a la DIAN. Se cuenta al aprobar, no al preparar. Si ya no hay cupo, la aprobación responde 409 agent_daily_limit_reached y el borrador sigue pendiente.
• Los borradores descartados se borran a los 90 días.

Consultar un borrador

La herramienta get_draft devuelve su estado: pending_approval, approved (con document_id) o discarded (con su motivo). Solo ve los borradores que preparó la misma clave; otro es draft_not_found, igual que uno inexistente.

Qué no pasa por aprobación

Reintentar un documento (retry_document), reenviar un correo (resend_document) y las contingencias no tienen contenido que revisar: con política de aprobación responden approval_required y la persona las hace desde el portal.

Para el flujo de un agente de código en el sandbox, consulta el manual del agente.