Herramientas del MCP

Las herramientas llaman a los mismos casos de uso que la API REST y se autentican con la misma clave: el ambiente sale de la clave. Un parámetro marcado como objeto lleva el cuerpo completo de la operación equivalente de la API.

`list_companies`

Empresas de la cuenta

Lista las empresas emisoras que alcanza la clave de API, el ambiente de la clave (sandbox = DIAN simulada por foliios, test = habilitación DIAN, live = producción) y si cada empresa está configurada para emitir en ese ambiente. Úsala primero: da el company_id que piden las demás tools (no es el NIT) y dice si puedes emitir. También trae las resoluciones de numeración de cada empresa en ese ambiente (resolutions[]: resolution_id para el cuerpo del documento, prefijo, rango from-to, vigencia, modo automatic/manual, tipo y alertas como expired o exhausted). No lista documentos.

Efecto: solo lectura, idempotente

Sin parámetros.

`validate_document`

Validar borrador

Valida un borrador de factura, nota crédito o nota débito contra las reglas del dominio y del Anexo 1.9 (tipos y formatos, totales e impuestos, DIVIPOLA y demás catálogos, NIT y dígito de verificación, modo de numeración, rango y vigencia de la resolución, configuración de la empresa) SIN emitirlo ni consumir número. Devuelve valid y, si no, todos los errores a la vez con campo, causa y corrección sugerida; si es válido, el resumen y los totales calculados. Úsala antes de issue_document, sobre todo en producción. El comprador puede ir mínimo (customer con solo identification): el nombre y el correo que falten se completan con la consulta de la DIAN, como en issue_document; lo que envíes siempre gana. No detecta lo que solo la DIAN valida (por ejemplo, que el nombre coincida con el RUT) ni si un número manual ya está usado.

Efecto: solo lectura, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`document`	object	sí	El documento: exactamente el cuerpo de POST /v1/companies/{company_id}/documents. Montos, cantidades y porcentajes como texto decimal (“4000.00”). Campos: foliios://reference/fields o explain_field.

`issue_document`

Emitir documento

Emite ante la DIAN una factura electrónica de venta, nota crédito o nota débito y la deja pending para su transmisión; sigue su estado con get_document. Exige idempotency_key: repetir la llamada con la misma clave y el mismo documento devuelve el mismo documento (nunca duplica). Con clave sk_sandbox_ la DIAN la simula foliios (sin efecto fiscal ni correos reales; los escenarios de list_sandbox_scenarios se piden con sandbox_scenario, una nota [sandbox:<id>] o el número de comprador 999000NNN). Con clave sk_test_ (habilitación) emite sin efecto fiscal. Con clave sk_live_ (producción) es una factura REAL e irreversible: antes de emitir pide confirmación explícita de la persona, por elicitation si el cliente la soporta o devolviendo status: "confirmation_required" con un resumen y un confirmation_token que solo debes reenviar después de que la persona apruebe. Al comprador solo se le pide documento, nombre y correo (Res. 202 de 2025): basta customer.identification; si faltan el nombre o el correo se completan con la consulta de la DIAN (lookup_acquirer) y, si la DIAN no responde, se emite con lo que haya (sin nombre de ninguna fuente: name_required). Valida antes con validate_document. No la uses para corregir un documento rechazado (usa resubmit_document); un reenvío NO conserva este sandbox_scenario, reevalúa desde el contenido corregido salvo que vuelvas a forzarlo con el sandbox_scenario propio de resubmit_document.

Efecto: escribe y no se deshace, idempotente, llama a servicios externos

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`confirmation_token`	string	no	Solo en producción (clave sk_live_) y solo si tu cliente no soporta elicitation: el `confirmation_token` que devolvió una llamada anterior con `status: "confirmation_required"`, después de mostrarle el resumen a la persona y obtener su aprobación explícita. Nunca lo inventes ni lo reenvíes sin preguntar.
`document`	object	sí	El documento: exactamente el cuerpo de POST /v1/companies/{company_id}/documents. Montos, cantidades y porcentajes como texto decimal (“4000.00”). Campos: foliios://reference/fields o explain_field.
`idempotency_key`	string	sí	Clave única por documento (por ejemplo un UUID v4) que hace la emisión idempotente. Genérala una vez por documento y REPÍTELA en cada reintento del mismo documento: si ya se emitió, devuelve el mismo documento en vez de otro. Con otro documento, usa otra clave.
`sandbox_scenario`	string	no	Solo con clave sk_sandbox_: el id de un escenario de list_sandbox_scenarios (por ejemplo rejected_fad06 o dian_unavailable) que fuerza la respuesta de la DIAN simulada. Con otra clave se rechaza.

`prepare_draft`

Preparar borrador

Deja una factura, nota crédito o nota débito como BORRADOR para que una persona la apruebe en el portal (Por aprobar): la valida igual que issue_document (completa el comprador con la DIAN si falta su nombre o correo) pero NO la envía a la DIAN ni toma número; el número se asigna cuando la persona la aprueba. Úsala cuando la persona quiera revisar antes de emitir, cuando el documento supere el monto máximo de la conexión o para preparar varios documentos del mismo lote (batch_id, por ejemplo “Mensualidades de noviembre”) que se aprueban juntos. Exige idempotency_key: repetir la llamada con la misma clave devuelve el mismo borrador. Explica en note lo que hiciste (la persona lo lee al aprobar). Después consulta get_draft. No pide confirmación ni en producción: nada tiene efecto fiscal hasta la aprobación.

Efecto: escribe, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`batch_id`	string	no	Opcional: el lote al que pertenece (lo eliges tú; el portal muestra y aprueba el lote junto). 1 a 80 caracteres.
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`document`	object	sí	El documento: exactamente el cuerpo de POST /v1/companies/{company_id}/documents. Montos, cantidades y porcentajes como texto decimal (“4000.00”). Campos: foliios://reference/fields o explain_field.
`idempotency_key`	string	sí	Clave única por documento (por ejemplo un UUID v4) que hace la emisión idempotente. Genérala una vez por documento y REPÍTELA en cada reintento del mismo documento: si ya se emitió, devuelve el mismo documento en vez de otro. Con otro documento, usa otra clave.
`note`	string	no	Opcional: lo que la persona debe saber para aprobarlo (de dónde salió el valor, qué cambió). Máximo 1000 caracteres.

`get_draft`

Consultar borrador

Consulta un borrador que esta conexión preparó (con prepare_draft o con issue_document cuando la emisión requiere aprobación): status pending (esperando a una persona en el portal), approved (con document_id: sigue el documento con get_document) o discarded (una persona lo descartó, con su motivo; no se emitió nada). Muestra también las reglas que lo enviaron a aprobación. No lista borradores ni muestra los de otras conexiones.

Efecto: solo lectura, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`draft_id`	string	sí	Id del borrador (el `draft_id` que devolvió prepare_draft o issue_document).

`get_document`

Consultar documento

Consulta un documento: estado (pending, sending, accepted, rejected, dian_unavailable, contingency, failed), número, CUFE/CUDE, totales, fechas, lo que dijo la DIAN (reglas explicadas) y su entrega al comprador por correo (delivery: pending, sent, failed o not_applicable; reenvíala con resend_document). Úsala después de emitir hasta que el estado sea final (accepted, rejected o failed). Para el detalle de un rechazo, explain_rejection; un failed con links.retry se reintenta con retry_document una vez corregida la causa (dian.failure_code).

Efecto: solo lectura, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`document_id`	string	sí	Id del documento (el `id` que devolvió issue_document o list_documents).

`list_documents`

Listar documentos

Lista documentos de una empresa en el ambiente de la clave, del más nuevo al más viejo, con filtros por estado, rango de fechas de creación y comprador. Paginada: si has_more es true, repite la llamada con los mismos filtros y cursor = next_cursor. Una página filtrada puede traer menos de limit filas y aun así tener más. Para un documento concreto usa get_document.

Efecto: solo lectura, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`created_from`	string	no	Creados desde: fecha YYYY-MM-DD (inicio del día en Colombia) o instante RFC 3339.
`created_to`	string	no	Creados hasta: fecha YYYY-MM-DD (fin del día en Colombia) o instante RFC 3339.
`cursor`	string	no	El `next_cursor` de la página anterior, tal cual.
`customer_id_number`	string	no	Número de identificación del comprador, sin dígito de verificación; va con customer_id_type.
`customer_id_type`	string	no	Tipo de identificación del comprador; va con customer_id_number.
`limit`	integer	no	Filas por página (20 por defecto).
`status`	string	no	Solo documentos en este estado.

`explain_rejection`

Explicar rechazo

Explica en lenguaje claro por qué la DIAN rechazó un documento: cada regla con su código, el mensaje original, qué revisa, el campo del cuerpo afectado, la corrección sugerida y quién la hace (la integración, el portal o un simple reenvío). Úsala cuando get_document diga rejected, antes de resubmit_document. Solo para documentos rechazados.

Efecto: solo lectura, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`document_id`	string	sí	Id del documento (el `id` que devolvió issue_document o list_documents).

`resubmit_document`

Corregir y reenviar

Corrige y reenvía a la DIAN un documento rejected, con el mismo número y resolución; vuelve a pending. Envía el contenido completo corregido (no un parche). Solo funciona sobre documentos rechazados (otro estado: invalid_state), así que un reintento no reenvía dos veces. En producción (sk_live_) pide la misma confirmación explícita que issue_document. Con clave sk_sandbox_, el reenvío LIMPIA por defecto cualquier escenario forzado de la emisión anterior y lo reevalúa desde el contenido corregido (una nota [sandbox:<id>] o el número de comprador 999000NNN); para forzar uno en este reenvío usa el argumento sandbox_scenario (NO va dentro de document: se rechaza con unknown_field). No la uses para emitir un documento nuevo.

Efecto: escribe y no se deshace, llama a servicios externos

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`confirmation_token`	string	no	Solo en producción (clave sk_live_) y solo si tu cliente no soporta elicitation: el `confirmation_token` que devolvió una llamada anterior con `status: "confirmation_required"`, después de mostrarle el resumen a la persona y obtener su aprobación explícita. Nunca lo inventes ni lo reenvíes sin preguntar.
`document`	object	sí	El contenido corregido: el mismo cuerpo de emisión sin `resolution_id` ni `number` (el documento conserva los suyos).
`document_id`	string	sí	Id del documento (el `id` que devolvió issue_document o list_documents).
`sandbox_scenario`	string	no	Solo con clave sk_sandbox_: el id de un escenario de list_sandbox_scenarios que fuerza la respuesta de la DIAN simulada para este reenvío. Sin él, el reenvío reevalúa el escenario desde el contenido corregido (nunca conserva el de la emisión anterior). Con otra clave se rechaza.

`retry_document`

Reintentar documento fallido

Reintenta un documento failed cuando ya se corrigió la causa del fallo: la configuración de la empresa en el portal (ambiente, datos del emisor, resolución con su vigencia o rango, certificado) o un SOAP Fault del emisor que soporte confirmó corregido. Antes de nada vuelve a validar la configuración actual: si sigue mal responde configuration_still_invalid con el failure_code en que terminaría y no cambia el documento. Conserva el número y, si el documento venía de contingencia, su fecha de emisión, CUFE y plazo de 48 h. Un duplicate_unverified (la DIAN dijo que ya procesó el documento y en 24 h no se pudo confirmar su estado) no se reenvía: el reintento vuelve a consultar a la DIAN y deja el documento sending, después accepted, rejected (si la DIAN lo rechazó por reglas distintas de la 90, lo único que libera el número) o otra vez duplicate_unverified; no revisa la configuración. No sirve para los fallos invalid_document, rendering_failed, not_sent ni unclassified (failure_not_retryable); mira links.retry en get_document. Idempotente: si el documento ya está pending o en transmisión lo devuelve sin hacer nada. En producción (sk_live_) pide la misma confirmación explícita que issue_document. Para un documento rejected usa resubmit_document.

Efecto: escribe y no se deshace, idempotente, llama a servicios externos

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`confirmation_token`	string	no	Solo en producción (clave sk_live_) y solo si tu cliente no soporta elicitation: el `confirmation_token` que devolvió una llamada anterior con `status: "confirmation_required"`, después de mostrarle el resumen a la persona y obtener su aprobación explícita. Nunca lo inventes ni lo reenvíes sin preguntar.
`document_id`	string	sí	Id del documento (el `id` que devolvió issue_document o list_documents).

`resend_document`

Reenviar al comprador

Envía otra vez al comprador, por correo, un documento ya validado por la DIAN (accepted) o emitido en contingencia DIAN (tipo 04): un ZIP con el AttachedDocument (el XML firmado con la validación de la DIAN) y la representación gráfica en PDF. Sin email va a los correos del comprador en el documento; con email, a esa dirección. El envío es asíncrono: la respuesta trae el documento con delivery.status: pending; sigue la entrega con get_document (delivery). Cada llamada es un correo más (no es idempotente). En producción (sk_live_), si email no es un correo del comprador, pide confirmación explícita de la persona antes de enviar (los datos del comprador irían a otra dirección). No sirve para documentos pending, rejected ni failed (document_not_deliverable); si el comprador no tiene correo, pasa email (delivery_recipient_required).

Efecto: escribe, llama a servicios externos

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`confirmation_token`	string	no	Solo en producción (clave sk_live_) y solo si tu cliente no soporta elicitation: el `confirmation_token` que devolvió una llamada anterior con `status: "confirmation_required"`, después de mostrarle el resumen a la persona y obtener su aprobación explícita. Nunca lo inventes ni lo reenvíes sin preguntar.
`document_id`	string	sí	Id del documento (el `id` que devolvió issue_document o list_documents).
`email`	string	no	Opcional: otra dirección a la que enviar el documento. Sin ella, los correos del comprador en el documento.

`lookup_acquirer`

Consultar comprador en la DIAN

Consulta en la DIAN (GetAcquirer, Res. 202 de 2025) el nombre y el correo de un comprador por su tipo y número de documento, para llenar customer en el momento de la venta. Devuelve found: true con name y suggested_email (una sugerencia: confírmala con la persona, puede ser el correo de la última factura que recibió) o found: false. Es opcional: issue_document completa solo un customer mínimo. Úsala una vez por comprador y solo para emitir: la empresa tiene un límite de consultas por minuto (rate_limited), cada consulta queda auditada y está prohibido el uso masivo (no la uses para enriquecer bases de clientes). Si falla (acquirer_lookup_unavailable), pide los datos a la persona. Exige el permiso documents:write.

Efecto: solo lectura, idempotente, llama a servicios externos

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`id_type`	string	sí	Tipo de documento del comprador (el mismo valor de customer.identification.type).
`number`	string	sí	Número del documento, sin dígito de verificación.

`explain_field`

Explicar campo

Explica un campo del cuerpo de emisión sin que tengas que leer UBL ni el Anexo 1.9: qué es, de dónde sale el valor, reglas y valores por defecto, ejemplos y el nodo UBL. Para campos con catálogo de la DIAN (municipio DIVIPOLA, país, unidad, medio de pago, moneda) verifica un código con value. Úsala cuando no sepas qué poner o cuando un error señale un campo.

Efecto: solo lectura, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`field`	string	sí	Ruta del campo en el cuerpo, con o sin índices: `customer.address.municipality_code`, `lines[0].unit` o `document.payment.means`.
`value`	string	no	Opcional: un valor para verificar en el catálogo del campo, por ejemplo `11001`.

`report_missing_tool`

Informar tool faltante

Informa al equipo de producto qué necesitabas y ninguna tool ofrece (por ejemplo descargar el PDF, anular una factura, registrar una resolución). Úsala cuando te falte una capacidad, no para errores de una tool que sí existe. No emite ni cambia nada; no incluyas datos personales del comprador.

Efecto: escribe

Parámetro	Tipo	Obligatorio	Descripción
`attempted_tools`	array	no	Tools que intentaste antes (opcional).
`context`	string	no	Para qué o en qué flujo (opcional).
`need`	string	sí	Qué necesitabas hacer, en una frase.

`declare_contingency`

Declarar contingencia del facturador

Declara una contingencia del facturador (tipo 03, anexo 1.9 numeral 12.1): el período en que la empresa no puede facturar electrónicamente y expide facturas de talonario o papel con su numeración de papel, autorizada antes por la DIAN. Una sola contingencia abierta por empresa; una nueva empieza cuando terminó la anterior o después. NO es la contingencia de la DIAN (tipo 04): esa la maneja foliios sola en cada documento. foliios no avisa a la DIAN: la carta la firma el representante legal y la envía la empresa (get_contingency_letter). Exige documents:write.

Efecto: escribe

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`reason`	string	sí	Motivo del inconveniente tecnológico (va en la carta a la DIAN).
`started_at`	string	no	Opcional: cuándo empezó el problema, RFC 3339 (por ejemplo 2026-10-01T08:00:00-05:00); no puede ser futuro. Por defecto, ahora.

`close_contingency`

Cerrar contingencia del facturador

Cierra una contingencia del facturador con la fecha y hora en que se superó el problema (ended_at, por defecto ahora). Desde ese momento la empresa tiene 48 horas para transmitir la transcripción de cada factura de papel del período (anexo 1.9, 12.1); foliios avisa por webhook (document.contingency_deadline_approaching) cuando el plazo se acerca con transcripciones pendientes. Devuelve la contingencia con su plazo. Una contingencia cerrada no se reabre (contingency_already_closed). Exige documents:write.

Efecto: escribe

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`contingency_id`	string	sí	Id de la contingencia (el `id` que devolvió declare_contingency o list_contingencies).
`ended_at`	string	no	Opcional: cuándo se superó el problema, RFC 3339; no futuro ni anterior al inicio. Por defecto, ahora.

`change_note_prefix`

Cambiar prefijo de notas

Cambia el prefijo de la serie de notas crédito o débito de la empresa (por defecto NC/ND), ya configurada: la crea automáticamente el alta del emisor. Aplica solo a las notas que se emitan desde ahora; las ya emitidas conservan su prefijo y número. Rechaza un prefijo igual o que choque con el de otra resolución o serie de la empresa (note_prefix_conflict). Exige documents:write.

Efecto: escribe, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`note_kind`	string	sí	Serie a editar: `credit` (notas crédito, NC por defecto) o `debit` (notas débito, ND por defecto).
`prefix`	string	sí	Nuevo prefijo: hasta 4 letras o dígitos, debe terminar en letra.

`transcribe_paper_invoice`

Transcribir factura de papel

Transcribe una factura de talonario o papel expedida durante una contingencia del facturador a su documento electrónico de transmisión (tipo 03) y la deja pending para transmitirla a la DIAN; sigue su estado con get_document. Conserva el número del papel (dentro de su resolución de talonario o papel), lleva la referencia al papel (número, fecha, tipo) y se emite con la fecha del día en que se firma; la fecha del papel debe estar dentro de la contingencia. Solo facturas: las notas no tienen contingencia. Idempotente por papel: el mismo papel con el mismo contenido devuelve la misma transcripción; con otro contenido, paper_already_transcribed. Con clave sk_live_ (producción) es un documento REAL e irreversible: pide confirmación explícita de la persona, por elicitation o con status: "confirmation_required" y un confirmation_token, como issue_document. Exige documents:write.

Efecto: escribe y no se deshace, idempotente, llama a servicios externos

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`confirmation_token`	string	no	Solo en producción (clave sk_live_) y solo si tu cliente no soporta elicitation: el `confirmation_token` que devolvió una llamada anterior con `status: "confirmation_required"`, después de mostrarle el resumen a la persona y obtener su aprobación explícita. Nunca lo inventes ni lo reenvíes sin preguntar.
`contingency_id`	string	sí	Id de la contingencia (el `id` que devolvió declare_contingency o list_contingencies).
`document`	object	sí	La factura de papel: exactamente el cuerpo de POST /v1/companies/{company_id}/contingencies/{contingency_id}/transcriptions (`paper` con resolución de talonario o papel, número y fecha impresos, más el contenido tal como se expidió). Montos como texto decimal.

`get_contingency`

Consultar contingencia

Consulta una contingencia del facturador: estado (open o closed), fechas, motivo, plazo de transmisión (48 horas desde el fin), si venció con pendientes (overdue) y cada transcripción con el estado de su documento; pending_transcriptions cuenta las que la DIAN aún no acepta. Úsala para vigilar el plazo después de close_contingency. No sabe de facturas de papel que no se hayan transcrito.

Efecto: solo lectura, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`contingency_id`	string	sí	Id de la contingencia (el `id` que devolvió declare_contingency o list_contingencies).

`list_contingencies`

Listar contingencias

Lista las contingencias del facturador de una empresa en el ambiente de la clave, de la más reciente a la más antigua (máximo 50), sin sus transcripciones. Para el detalle y las pendientes usa get_contingency.

Efecto: solo lectura, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.

`list_suppressed_recipients`

Listar direcciones suprimidas

Lista las direcciones suprimidas de la empresa: por un rebote permanente, una queja, o porque ya estaban en la lista de supresión de la cuenta (nunca de otra empresa). Un reenvío a una de estas direcciones falla con 409 recipient_suppressed; soporte las quita con ops suppression-remove.

Efecto: solo lectura, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.

`get_contingency_letter`

Borrador de la carta a la DIAN

Devuelve el borrador de la carta a la DIAN de una contingencia del facturador: declara el inconveniente (contingencia abierta) o su superación (cerrada), con el asunto que pide el anexo 1.9 (NIT-DV; Razón social) y el correo contingencia.facturadorvp@dian.gov.co. foliios NO la envía: muéstrasela a la persona; la firma el representante legal (o quien haga sus veces) y la empresa la envía en PDF, con nombres y teléfono de contacto en el cuerpo del correo.

Efecto: solo lectura, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`contingency_id`	string	sí	Id de la contingencia (el `id` que devolvió declare_contingency o list_contingencies).

`list_sandbox_scenarios`

Escenarios del sandbox

Devuelve el catálogo del sandbox (claves sk_sandbox_, DIAN simulada por foliios, sin efecto fiscal): cada escenario con su id, el resultado (aceptado, rechazado con una regla real del Anexo 1.9 como FAD06 o FAJ43b, aceptado con notificaciones, DIAN caída con contingencia, timeout, demora, duplicado tras timeout) y cómo pedirlo desde los datos del documento: la nota [sandbox:<id>] en notes o el número de comprador 999000NNN, o el argumento sandbox_scenario de issue_document (o, en un reenvío, el mismo argumento de resubmit_document). Cada escenario dice a qué aplica (applies_to): document (cualquier documento), note (solo notas crédito y débito) o test_set (el ensayo del set de habilitación del portal: no se piden al emitir). Incluye las reglas que el sandbox valida siempre, las que no puede reproducir y sus límites. Sirve con cualquier clave.

Efecto: solo lectura, idempotente

Sin parámetros.

`list_sandbox_inbox`

Buzón de pruebas

Lista el buzón de pruebas del sandbox de una empresa: los correos que habría recibido el comprador de cada documento sandbox (el sandbox nunca los envía), del más nuevo al más viejo, con asunto, destinatarios, documento y el ZIP (AttachedDocument y PDF). Solo con clave sk_sandbox_.

Efecto: solo lectura, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`limit`	integer	no	Cuántos correos (por defecto 10).

`trigger_sandbox_event`

Disparar evento de prueba

Envía un webhook de prueba del tipo elegido (document.accepted, document.rejected, document.failed, document.contingency, document.contingency_deadline_approaching, document.delivered, document.delivery_failed, document.delivery_not_applicable) al endpoint del sandbox de la empresa, firmado y con reintentos como cualquier evento; su documento es doc_test_.... Sirve para probar el receptor de webhooks. Solo con clave sk_sandbox_; sin efecto fiscal.

Efecto: escribe, llama a servicios externos

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.
`event`	string	sí	Nombre del evento.

`get_integration_check`

Verificación de integración

Verifica qué hizo una empresa en su sandbox, calculado desde sus datos y no desde lo que alguien diga (solo con clave sk_sandbox_; solo lectura, no escribe nada ni gasta cuota). derived[] trae 4 comprobaciones: invoice_accepted, credit_and_debit_note (una nota crédito y una débito aceptadas que referencian una factura aceptada de la empresa), contingency (un documento de la empresa que pasó por contingencia, con la DIAN no disponible —en el sandbox, el escenario dian_unavailable— y terminó aceptado) y webhook_delivered; cada una es passed (con evidence {document_id, number, at} y evidence_expires_at), pending o not_applicable (el webhook, si la empresa no tiene endpoint). La evidencia vale 30 días desde at y se pierde con un reset del sandbox. declared[] son 2 comprobaciones que nadie puede verificar (rejection_corrected, idempotency_replayed): vienen declared, nunca cuentan en complete y debes informarlas a la persona como no verificadas. complete es true solo cuando todas las derived aplicables están passed: no des la integración por terminada antes. window.truncated avisa que el historial era largo y una comprobación pending puede deberse a eso.

Efecto: solo lectura, idempotente

Parámetro	Tipo	Obligatorio	Descripción
`company_id`	string	sí	Id de la empresa emisora dentro de la plataforma (no su NIT). Sale de list_companies.