Novedades

Aquí se anotan los cambios de la API que afectan a quien integra. La versión vigente es v1.

Política de versiones

La versión mayor va en la ruta: /v1.
Dentro de v1 solo hay cambios compatibles: campos nuevos en las respuestas, campos opcionales nuevos en las solicitudes, endpoints nuevos, códigos de error nuevos y valores nuevos en enumeraciones de respuesta. Tu cliente debe tolerar campos y valores que no conoce.
Rompería el contrato, y por eso iría a /v2: quitar o renombrar campos, códigos o rutas; volver obligatorio algo opcional; cambiar tipos o formatos (por ejemplo, de los montos); cambiar el significado de un estado.
Un endpoint o campo que se retire se anuncia con las cabeceras Deprecation y Sunset (RFC 8594) y se mantiene al menos 6 meses.

El contrato de cada versión está en la referencia de la API v1, generada desde el código.

v1 (vigente)

Cambios de comportamiento

Cambios que no tocan la forma del contrato (v1 sigue siendo compatible) pero cambian lo que la API hace con los datos existentes.

Cada empresa puede declarar su software y su fabricante. En el portal, en Empresa → Software y fabricante, una empresa escribe quién fabrica su software, el NIT del fabricante si quiere y el nombre del software; una sola configuración para sandbox, habilitación y producción. Es lo que declaran sus documentos en la línea «Software: … · Fabricante: …» del PDF y en print.software. El nombre del software solo se puede declarar junto a un fabricante propio: sin él, los documentos declaran el software y el fabricante de foliios. Un cambio aplica a los documentos que se emitan después: los ya emitidos conservan lo que declararon, también al reenviarlos. La API v1 no cambia. Noviembre de 2026.
La representación gráfica nombra al fabricante del software, no al emisor. Antes, la línea del software del PDF ponía al emisor como fabricante cuando usaba software propio y en todos los documentos del sandbox. Ahora dice «Software: … · Fabricante: …, NIT …» con el software y el fabricante que el documento declara, los mismos de print.software, y agrega «Proveedor tecnológico: NIT …» solo cuando el software está registrado con un NIT distinto al del emisor (nunca en el sandbox). Un documento ya entregado conserva su PDF; al reenviarlo se genera con la redacción nueva. Noviembre de 2026.
La emisión espera el resultado de la DIAN. Antes, POST .../documents respondía siempre 202 con el documento en pending. Ahora la solicitud espera y el código dice cómo terminó: 201 con el documento accepted (o en contingency), 200 si quedó rejected o failed, con el detalle en dian, y 202 con Location y Retry-After si se acabó la espera y sigue en proceso. El parámetro nuevo ?wait=N ajusta la espera en segundos y ?wait=0 no espera; un wait inválido responde 400 invalid_query. Si la DIAN no respondió a tiempo y puede tener el documento, el 202 trae outcome_code: dian_outcome_uncertain: no lo emitas de nuevo con otra Idempotency-Key, consúltalo con GET. resubmit y retry esperan igual, y una repetición con la misma Idempotency-Key responde con el código del estado actual del documento. Si tu cliente exigía 202, acepta también 201 y 200, y usa un tiempo de espera HTTP mayor que wait. Ver emitir una factura. Noviembre de 2026.
Los documentos de habilitación se conservan 7 días. Un documento emitido con una clave sk_test_ no tiene validez fiscal y ahora vence a los 7 días de creado: consultarlo, descargar su XML, su PDF o su AttachedDocument, reintentarlo, reenviarlo o corregirlo responde 410 document_expired, y más tarde 404. Los de producción no cambian. Ver habilitación. Noviembre de 2026.
Una nota que el UBL no puede llevar se rechaza antes de numerar. Una nota crédito o débito con withholdings, o una nota crédito con prepaid_payments, antes se aceptaba, tomaba número y terminaba en failed con rendering_failed. Ahora responde 422 validation_failed con el campo (withholdings_in_note, prepaid_payments_in_credit_note) y no consume número, saldo ni la Idempotency-Key. Además, todo documento se escribe una vez de prueba antes de numerar: si a la configuración de la empresa le falta una pieza (identificador o PIN del software, clave técnica de la resolución, NIT del proveedor del software), la respuesta es 409 environment_not_configured y su detail dice cuál; ante un defecto de la plataforma, 500 internal_error. En ningún caso consume número, saldo ni la Idempotency-Key.
El número de un documento que falló sin firmarse se puede reutilizar (numeración manual). Antes, pedir el número de cualquier documento failed respondía 409 number_already_used y el número quedaba perdido. Ahora, si el documento que lo tiene está failed sin cufe, con invalid_document o rendering_failed, la emisión de un documento nuevo con ese número se acepta de inmediato; lo mismo si está rejected y su número había quedado retenido. Hace falta una Idempotency-Key nueva: la misma clave sigue devolviendo el failed original. Con numeración automática nada cambia: ese número no se reasigna y el cliente no elige números. Ver numeración y series. Noviembre de 2026.
El reenvío ya no conserva el escenario forzado del sandbox. Antes, corregir y reenviar un documento (POST .../resubmit) cuya emisión forzó un escenario con la cabecera Foliios-Sandbox-Scenario mantenía ese mismo escenario. Ahora el reenvío se reevalúa desde el contenido corregido (una nota [sandbox:<id>] o un comprador 999000NNN), igual que una emisión nueva. Para forzar un escenario en ese reenvío en particular, el cuerpo de resubmit acepta el campo opcional sandbox_scenario (nunca la cabecera, que un reenvío no lee). Fecha: sin fecha registrada. Ver rechazos y reenvío.
Una nota ya no acepta el resolution_id de una factura. Antes, una nota crédito o débito con cualquier resolution_id se aceptaba y el campo se ignoraba. Ahora ese campo, en una nota, solo puede faltar o ser el de la serie de la nota (el resolution_id que la API devuelve para ella): cualquier otro responde 422 validation_failed con el campo resolution_id y el código not_allowed, sin consumir número ni atar la Idempotency-Key. Aplica a la emisión por la API y por el MCP, a la validación, a los borradores y a cada fila de una emisión masiva. Una nota emitida antes de que existieran las series propias devuelve el resolution_id de su factura: no lo copies en una nota nueva. Si tu integración lo envía, quítalo de las notas. La regla se revisa antes que la Idempotency-Key: si repites una nota ya emitida con su misma clave y el resolution_id de una factura en el cuerpo, recibes ese 422 y no el documento original; la nota sigue emitida una sola vez y la consultas con GET .../documents/{document_id}. Ver notas crédito y débito. Noviembre de 2026.
El correo de una factura ya no recuerda la aceptación tácita. El correo que recibe el comprador de una factura ya no trae el recordatorio del plazo de reclamo y de la aceptación tácita: la aceptación, los reclamos y su registro en RADIAN son del emisor y del comprador. 2026-11-05.

Cambios compatibles

Evento nuevo document.delivery_complained. Cuando un destinatario marca como spam el correo de un documento, foliios envía este evento con el documento y data.complaint.complained_at. No trae la dirección ni data.delivery, y la entrega no cambia de estado; la dirección queda en GET .../suppressions con reason: complaint. Un endpoint sin lista de eventos lo recibe sin cambiar nada; uno con lista debe agregarlo para recibirlo. Se puede probar en el sandbox con POST /v1/sandbox/events. Ver entrega por correo y webhooks. Noviembre de 2026.
print.software.manufacturer_id puede ser null. El NIT del fabricante del software pasa de texto obligatorio a string | null: la clave está siempre y vale null cuando el documento no declara ninguno. print ya no depende de ese dato. El software y el fabricante de print.software son los mismos que imprime la representación gráfica del documento y quedan fijos cuando se emite. Ver emitir una factura. Noviembre de 2026.
Campo print en el documento. La respuesta de un documento incorpora el campo opcional print, con lo necesario para imprimir uno accepted o en contingency: cufe, qr_text, qr_url, validated_at (null en contingencia), status_label, software y, en facturas, numbering_authorization. Es null en cualquier otro estado y puede venir null también en un documento aceptado: tu cliente debe tolerarlo. Ver emitir una factura. Noviembre de 2026.
Cuota mensual en habilitación. Cada empresa emite hasta 1.000 documentos nuevos por mes con claves sk_test_. Al pasarse, la emisión responde con el código nuevo 429 test_quota_exceeded, con limit y sin Retry-After: el cupo vuelve el día 1, en hora de Colombia. El set de habilitación y las repeticiones con la misma Idempotency-Key no cuentan. Ver límites por empresa. Noviembre de 2026.
Activación de la cuenta para producción. Configurar el ambiente de producción en el portal (crear una clave sk_live_, guardar el software, registrar resoluciones) exige una cuenta activada. Sin activar, el portal responde con el código nuevo 402 activation_required y no cambia nada. La habilitación y el sandbox no lo necesitan. Ver paso a producción. Noviembre de 2026.
number_reusable y quién tiene un número ocupado. Los documentos traen el campo nuevo number_reusable, y el evento document.failed lo trae en data.number_reusable: true cuando el documento está rejected, o failed sin haberse firmado nunca (invalid_document o rendering_failed). Los errores 409 number_already_used y 409 number_in_verification agregan holder_document_id y holder_status, el id y el estado del documento que tiene el número. Ver numeración y series e idempotencia y reintentos. Noviembre de 2026.
Límites por empresa en producción. Cada empresa admite 100 escrituras y 300 lecturas por minuto (REST y MCP juntos), 1.000 documentos en proceso, 5 emisiones síncronas abiertas, 1 lote en admisión y 5 lotes por minuto. Códigos 429 nuevos: in_flight_limited y concurrency_limited; rate_limited suma el miembro limit. Las respuestas traen Retry-After y X-RateLimit-Limit, -Remaining y -Reset. Un lote entra completo o no entra. GET .../acquirers/... cuenta como lectura. Ver límites por empresa. Noviembre de 2026.
Verificación de integración del sandbox. Endpoint nuevo GET /v1/companies/{company_id}/sandbox/integration-check, con la herramienta equivalente get_integration_check en el MCP. Calcula, desde los datos de la empresa, cuatro comprobaciones derivadas y dos declaradas. Solo para claves de sandbox. Ver verificación de integración. Noviembre de 2026.
Campos nuevos en el listado y en el documento. El listado de documentos (GET .../documents) incorpora type, payable_amount, currency, origin, actor y approved_by, y la respuesta de un documento incorpora origin, actor y approved_by. Los cuatro primeros del listado son null en documentos guardados antes de que el listado los llevara. Octubre de 2026.
Series propias de notas crédito y débito. Las notas se numeran con su propia serie (NC y ND) y la API ignora el resolution_id que llegue en ellas: ya no hace falta enviarlo. Si la serie de la empresa no está configurada, la emisión de esa nota responde 409 note_series_not_configured. Ver numeración y series. Fecha: sin fecha registrada.
Catálogo del sandbox versionado. GET /v1/sandbox/scenarios trae su version; la versión vigente del catálogo y de las reglas del sandbox es la del encabezado de la referencia de escenarios.

Documentación

Guía de tirilla para puntos de venta. Página nueva: tirilla en un punto de venta. Explica cómo emitir con ?wait=N desde un punto de venta, con o sin operador, qué imprimir con cada respuesta (201, 200, 202, 429 o sin respuesta), qué va en la tirilla campo por campo desde print y desde tu venta, el QR, el consumidor final, la contingencia y la reimpresión. Trae una receta en Python con pruebas. La API v1 no cambia. Noviembre de 2026.

Sandbox: notificaciones de un documento aceptado

El sandbox devuelve, sin pedir ningún escenario, las notificaciones que la habilitación real de la DIAN dio a documentos aceptados (por ejemplo RUT01), para que un documento aceptado se vea igual en el sandbox y en habilitación. Ver escenarios. Noviembre de 2026.

Cómo enterarte de los cambios

Esta página se actualiza con cada cambio visible de la API.
Las páginas de la referencia generada siempre reflejan el código vigente.
Los agentes pueden leer llms.txt y los .md de cada página, que siempre son la versión actual.