---
title: "Proponer facturas desde un documento"
method: POST
path: "/documents"
tags: ["Borradores"]
---

# Proponer facturas desde un documento

`POST /documents`

## Request

- Base URL: `https://www.facture.ar/api`
- URL: `https://www.facture.ar/api/documents`
- Auth: API key in header `x-api-key`

Arma borradores de factura a partir de un archivo (fileUrl, o multipart con el campo file), un texto (text) o los datos ya estructurados (data, uno o hasta 100). Los archivos y textos se leen con IA en segundo plano: los borradores vuelven con status extracting; consultalos con GET /documents/drafts. El entorno lo fija la API key. Las solicitudes JSON aceptan `Idempotency-Key`: un reenvío devuelve los mismos borradores en vez de crear otros (ni, en modo automático, emitir otra factura).

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `templateId` string, nullable: Plantilla que define CUIT, punto de venta, modo, cliente fijo, precios e instrucciones
  - `mode` 'manual' | 'automatic': automatic: se emite solo si no hay observaciones
  - `cuitId` string, nullable
  - `ptoVta` integer, nullable
  - `dedupeKey` string, nullable: Id estable del documento: repetir el pedido con el mismo valor no duplica el borrador
  - `sourceRef` string, nullable: Referencia que se muestra en el borrador
  - `source` 'api' | 'zapier' | 'mcp'
  - `fileUrl` string, uri: URL pública del archivo (PDF, imagen o planilla)
  - `fileName` string
  - `mimeType` string
  - `text` string: Texto del documento (un pedido, un mensaje)
  - `data` union
    - DraftData: Los datos de la factura propuesta
      - `receiver` object
        - `name` string, nullable
        - `docType` string, nullable: CUIT, CUIL o DNI; null = consumidor final sin identificar
        - `docNumber` string, nullable: CUIT, CUIL o DNI, con o sin guiones
        - `condicionIva` integer, nullable: Condición frente al IVA del receptor (código de ARCA). Si falta, se busca en el padrón
        - `email` string, email, nullable: Si está, se le manda la factura
        - `address` string, nullable
      - `concepto` 1 | 2 | 3: 1 productos, 2 servicios, 3 productos y servicios
      - `serviceFrom` string, date, nullable: AAAA-MM-DD, servicios
      - `serviceTo` string, date, nullable: AAAA-MM-DD, servicios
      - `paymentDue` string, date, nullable: Vencimiento del pago, AAAA-MM-DD
      - `pricesIncludeIva` boolean: Los precios de las líneas incluyen IVA
      - `lines` object[], required
        - `description` string, required
        - `quantity` number
        - `unitPrice` number, nullable, required: null si el documento no trae precio
        - `ivaRate` 0 | 2.5 | 5 | 10.5 | 21 | 27: Alícuota de IVA en porcentaje
      - `documentTotal` number, nullable: Total impreso en el documento, para controlar las líneas
      - `currency` string: Moneda ISO 4217
      - `documentDate` string, date, nullable: Fecha del documento, AAAA-MM-DD. La factura se emite con la fecha del día
      - `reference` string, nullable: Número de remito, pedido o referencia
      - `description` string, nullable: Texto libre que va en la factura
    - DraftData[]
      - `receiver` object
        - `name` string, nullable
        - `docType` string, nullable: CUIT, CUIL o DNI; null = consumidor final sin identificar
        - `docNumber` string, nullable: CUIT, CUIL o DNI, con o sin guiones
        - `condicionIva` integer, nullable: Condición frente al IVA del receptor (código de ARCA). Si falta, se busca en el padrón
        - `email` string, email, nullable: Si está, se le manda la factura
        - `address` string, nullable
      - `concepto` 1 | 2 | 3: 1 productos, 2 servicios, 3 productos y servicios
      - `serviceFrom` string, date, nullable: AAAA-MM-DD, servicios
      - `serviceTo` string, date, nullable: AAAA-MM-DD, servicios
      - `paymentDue` string, date, nullable: Vencimiento del pago, AAAA-MM-DD
      - `pricesIncludeIva` boolean: Los precios de las líneas incluyen IVA
      - `lines` object[], required
        - `description` string, required
        - `quantity` number
        - `unitPrice` number, nullable, required: null si el documento no trae precio
        - `ivaRate` 0 | 2.5 | 5 | 10.5 | 21 | 27: Alícuota de IVA en porcentaje
      - `documentTotal` number, nullable: Total impreso en el documento, para controlar las líneas
      - `currency` string: Moneda ISO 4217
      - `documentDate` string, date, nullable: Fecha del documento, AAAA-MM-DD. La factura se emite con la fecha del día
      - `reference` string, nullable: Número de remito, pedido o referencia
      - `description` string, nullable: Texto libre que va en la factura

## Response `202`

Borradores creados

- object
  - `drafts` Draft[]
    - `id` string
    - `status` 'extracting' | 'review' | 'queued' | 'invoiced' | 'error' | 'discarded': extracting: leyéndose; review: espera revisión; queued: enviado a ARCA; invoiced: facturado; error: no se pudo leer o emitir; discarded: descartado
    - `mode` 'manual' | 'automatic': automatic: se emite solo si no hay observaciones
    - `source` 'upload' | 'google_drive' | 'zapier' | 'api' | 'recurring' | 'mcp' | 'whatsapp'
    - `sourceRef` string, nullable
    - `fileName` string, nullable
    - `mimeType` string, nullable
    - `hasFile` boolean
    - `templateId` string, nullable
    - `templateName` string, nullable
    - `cuitId` string, nullable
    - `ptoVta` integer, nullable
    - `environment` 'production' | 'homologation'
    - `data` DraftData: Los datos de la factura propuesta
      - `receiver` object
        - `name` string, nullable
        - `docType` string, nullable: CUIT, CUIL o DNI; null = consumidor final sin identificar
        - `docNumber` string, nullable: CUIT, CUIL o DNI, con o sin guiones
        - `condicionIva` integer, nullable: Condición frente al IVA del receptor (código de ARCA). Si falta, se busca en el padrón
        - `email` string, email, nullable: Si está, se le manda la factura
        - `address` string, nullable
      - `concepto` 1 | 2 | 3: 1 productos, 2 servicios, 3 productos y servicios
      - `serviceFrom` string, date, nullable: AAAA-MM-DD, servicios
      - `serviceTo` string, date, nullable: AAAA-MM-DD, servicios
      - `paymentDue` string, date, nullable: Vencimiento del pago, AAAA-MM-DD
      - `pricesIncludeIva` boolean: Los precios de las líneas incluyen IVA
      - `lines` object[], required
        - `description` string, required
        - `quantity` number
        - `unitPrice` number, nullable, required: null si el documento no trae precio
        - `ivaRate` 0 | 2.5 | 5 | 10.5 | 21 | 27: Alícuota de IVA en porcentaje
      - `documentTotal` number, nullable: Total impreso en el documento, para controlar las líneas
      - `currency` string: Moneda ISO 4217
      - `documentDate` string, date, nullable: Fecha del documento, AAAA-MM-DD. La factura se emite con la fecha del día
      - `reference` string, nullable: Número de remito, pedido o referencia
      - `description` string, nullable: Texto libre que va en la factura
    - `total` number, nullable: Total calculado con las líneas; null si falta algún precio
    - `voucherLetter` 'A' | 'B' | 'C' | 'null', nullable
    - `confidence` number, nullable: Confianza de la lectura con IA, de 0 a 1
    - `issues` object[]: Observaciones que hay que revisar
      - `code` 'no_cuit' | 'no_lines' | 'missing_price' | 'invalid_amount' | 'total_mismatch' | 'invalid_document' | 'unidentified_receiver' | 'foreign_currency' | 'low_confidence' | 'possible_duplicate' | 'ai_note' | 'ai_info'
      - `message` string
    - `errorMessage` string, nullable
    - `invoice` object, nullable: La factura emitida desde el borrador
      - `id` string
      - `voucherNumber` integer
      - `ptoVta` integer, nullable
      - `invoiceType` integer, nullable
      - `status` string
      - `amount` number
    - `emailStatus` string, nullable: Estado del envío de la factura por email
    - `url` string: Link al borrador en el dashboard
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
  - `mapping` object: Solo planillas: las columnas usadas y si la IA las acaba de proponer

## Other responses

- `400`: Falta el documento o los datos son inválidos
- `409`: Ya hay una solicitud en curso con este `Idempotency-Key` (code `IDEMPOTENCY_KEY_IN_PROGRESS`). Esperá unos segundos y reintentá con la misma clave para recibir su resultado.
- `422`: Este `Idempotency-Key` ya se usó con otra solicitud: otro cuerpo u otro endpoint (code `IDEMPOTENCY_KEY_REUSED`). Usá una clave nueva para una factura distinta.

---

[API](https://skmtc.dev/facture/apis/facturear-api.md) · [All operations](https://skmtc.dev/facture/apis/facturear-api/llms.txt) · [OpenAPI document](https://skmtc.dev/facture/apis/facturear-api/revisions/b572c5908978?raw)