API de N1

Documentos y causación

Recursos disponibles en la API y cómo leer el estado de causación de cada documento.

Recursos

RecursoQué ofreceScopes
Empresas (/companies)Lista y detalle de las empresas a las que la clave tiene acceso (todas las del usuario o la lista restringida), creación de empresas e invitaciones.companies:read, companies:write
Documentos (/companies/{id}/invoices, /credit-notes, /contractor-invoices, /international-invoices)Facturas electrónicas (compra y venta), notas crédito, cuentas de cobro y facturas del exterior con sus líneas, impuestos y retenciones. Cada documento trae su estado de causación (synced, export con integración, número de comprobante y fecha; en el detalle, exports con el último intento por integración) e indica en files qué archivos tiene, que se descargan con /{id}/original y /{id}/pdf. Solo lectura.documents:read
Contactos (/companies/{id}/contacts)Clientes y proveedores (terceros) con identificación, datos fiscales y de contacto; se pueden crear y actualizar.contacts:read, contacts:write
Carga de documentos (/companies/{id}/files, /dian-imports)Subida de archivos (XML, ZIP o PDF, hasta 25 MB) para que N1 los procese, e importaciones desde la DIAN por rango de fechas; permite seguir el estado de cada carga y descargar el archivo recibido con /files/{id}/content. Las importaciones desde Excel solo están disponibles en la interfaz web.imports:read, imports:write
Causación (/companies/{id}/exports, .../readiness)Verifica si un documento está listo para causarse en el software contable conectado (Siigo, Alegra, World Office, Odoo…), lo envía y consulta el resultado.exports:read, exports:write
Eventos DIAN (/companies/{id}/dian-events)Envío de acuse de recibo, recibo del bien y aceptación expresa de facturas electrónicas, con el estado de cada evento.dian_events:read, dian_events:write
Webhooks (/companies/{id}/webhooks)Endpoints HTTPS por empresa, suscripciones a eventos e historial de entregas.webhooks:manage

Estado de causación

Cada documento indica si ya está causado en el software contable conectado:

  • synced y synced_at: si está causado y desde cuándo.
  • export: cuando synced es true, la integración (siigo, siigo_contador, alegra, odoo, world_office…), el external_id, el external_number (número del comprobante) y el external_name en el software contable, la fecha exported_at y marked_manually (true si un usuario lo marcó como causado desde el panel sin enviarlo desde N1; en ese caso no hay número de comprobante). Es null mientras no esté causado.
  • exports (solo en el detalle del documento): el último intento por integración, con status (queued, running, succeeded, failed, cancelled), número y nombre del comprobante, started_at, finished_at y error cuando falló. Sirve para saber si hay una causación en curso o fallida aunque synced siga en false.

Para filtrar por estado usa synced=true|false en las listas; para el historial completo, GET /companies/{id}/exports.

AnteriorEmpresas y permisosSiguienteArchivos de los documentos