Facturear Borradores API
Facturas propuestas desde documentos, planillas o datos, para revisar y emitir
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/facture-ar:facture-ar-borradores-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Facturear Borradores API
description: 'API para emitir facturas electrónicas de ARCA (Argentina) desde tu sistema: facturas, notas de crédito y débito, lotes, PDF y XML, envío por email, borradores desde documentos, webhooks y reportes. Autenticación con API Key en el header x-api-key: la key de testing opera en homologación y la de producción emite comprobantes reales.'
version: 1.0.0
contact:
name: Facturear Support
email: support@facture.ar
url: https://facture.ar
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://www.facture.ar/api
description: Servidor de producción
security:
- apiKey: []
tags:
- name: Borradores
description: Facturas propuestas desde documentos, planillas o datos, para revisar y emitir
paths:
/documents:
post:
summary: Proponer facturas desde un documento
description: '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).'
tags:
- Borradores
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
templateId:
type:
- string
- 'null'
description: Plantilla que define CUIT, punto de venta, modo, cliente fijo, precios e instrucciones
mode:
type: string
enum:
- manual
- automatic
description: 'automatic: se emite solo si no hay observaciones'
cuitId:
type:
- string
- 'null'
ptoVta:
type:
- integer
- 'null'
minimum: 1
dedupeKey:
type:
- string
- 'null'
maxLength: 200
description: 'Id estable del documento: repetir el pedido con el mismo valor no duplica el borrador'
sourceRef:
type:
- string
- 'null'
maxLength: 200
description: Referencia que se muestra en el borrador
source:
type: string
enum:
- api
- zapier
- mcp
default: api
fileUrl:
type: string
format: uri
description: URL pública del archivo (PDF, imagen o planilla)
fileName:
type: string
maxLength: 200
mimeType:
type: string
text:
type: string
description: Texto del documento (un pedido, un mensaje)
data:
oneOf:
- $ref: '#/components/schemas/DraftData'
- type: array
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/DraftData'
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: Hasta 25 MB
templateId:
type:
- string
- 'null'
description: Plantilla que define CUIT, punto de venta, modo, cliente fijo, precios e instrucciones
mode:
type: string
enum:
- manual
- automatic
description: 'automatic: se emite solo si no hay observaciones'
cuitId:
type:
- string
- 'null'
ptoVta:
type:
- integer
- 'null'
minimum: 1
dedupeKey:
type:
- string
- 'null'
maxLength: 200
description: 'Id estable del documento: repetir el pedido con el mismo valor no duplica el borrador'
sourceRef:
type:
- string
- 'null'
maxLength: 200
description: Referencia que se muestra en el borrador
source:
type: string
enum:
- api
- zapier
- mcp
default: api
responses:
'202':
description: Borradores creados
headers:
Idempotent-Replayed:
$ref: '#/components/headers/IdempotentReplayed'
content:
application/json:
schema:
type: object
properties:
drafts:
type: array
items:
$ref: '#/components/schemas/Draft'
mapping:
type: object
description: 'Solo planillas: las columnas usadas y si la IA las acaba de proponer'
'400':
description: Falta el documento o los datos son inválidos
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
$ref: '#/components/responses/IdempotencyInProgress'
'422':
$ref: '#/components/responses/IdempotencyKeyReused'
operationId: postDocuments
x-operation-id-source: derived
/documents/drafts:
get:
summary: Listar borradores
description: Los borradores del entorno de la API key, los más nuevos primero.
tags:
- Borradores
parameters:
- name: status
in: query
description: Filtrar por estado. pending = leyéndose, para revisar, con error o en camino a ARCA
required: false
schema:
type: string
enum:
- extracting
- review
- queued
- invoiced
- error
- discarded
- pending
- name: source
in: query
description: Filtrar por origen
required: false
schema:
type: string
enum:
- upload
- google_drive
- zapier
- api
- recurring
- mcp
- whatsapp
- name: limit
in: query
description: Cantidad máxima
required: false
schema:
type: integer
minimum: 1
maximum: 500
default: 200
responses:
'200':
description: Borradores
content:
application/json:
schema:
type: object
properties:
drafts:
type: array
items:
$ref: '#/components/schemas/Draft'
operationId: getDocumentsDrafts
x-operation-id-source: derived
/documents/drafts/{draftId}:
get:
summary: Obtener un borrador
tags:
- Borradores
parameters:
- name: draftId
in: path
description: ID del borrador
required: true
schema:
type: string
responses:
'200':
description: Borrador
content:
application/json:
schema:
type: object
properties:
draft:
$ref: '#/components/schemas/Draft'
'404':
description: El borrador no existe
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: getDocumentsDraftsByDraftId
x-operation-id-source: derived
patch:
summary: Corregir un borrador
description: Cambia los datos, el CUIT o el punto de venta de un borrador que espera revisión. Con una API key, environment solo se acepta si coincide con el de la key.
tags:
- Borradores
parameters:
- name: draftId
in: path
description: ID del borrador
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/DraftData'
cuitId:
type:
- string
- 'null'
ptoVta:
type:
- integer
- 'null'
minimum: 1
environment:
type: string
enum:
- production
- homologation
responses:
'200':
description: Borrador actualizado
content:
application/json:
schema:
type: object
properties:
draft:
$ref: '#/components/schemas/Draft'
'400':
description: Datos inválidos o el borrador ya no se puede editar
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: patchDocumentsDraftsByDraftId
x-operation-id-source: derived
delete:
summary: Descartar un borrador
tags:
- Borradores
parameters:
- name: draftId
in: path
description: ID del borrador
required: true
schema:
type: string
responses:
'200':
description: Borrador descartado
content:
application/json:
schema:
type: object
properties:
discarded:
type: integer
'400':
description: El borrador no se puede descartar
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: deleteDocumentsDraftsByDraftId
x-operation-id-source: derived
/documents/drafts/{draftId}/email:
post:
summary: Enviar la factura de un borrador por email
description: Envía (o reenvía) la factura emitida desde el borrador a una dirección.
tags:
- Borradores
parameters:
- name: draftId
in: path
description: ID del borrador
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
responses:
'200':
description: Resultado del envío
content:
application/json:
schema:
type: object
properties:
status:
type:
- string
- 'null'
description: Estado del envío
'400':
description: Email inválido o el borrador todavía no tiene factura
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: postDocumentsDraftsByDraftIdEmail
x-operation-id-source: derived
/documents/drafts/invoice:
post:
summary: Emitir borradores
description: Emite ante ARCA los borradores indicados. Con la key de producción son comprobantes reales. Con una API key solo se emiten los borradores de su entorno.
tags:
- Borradores
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- ids
properties:
ids:
type: array
minItems: 1
maxItems: 500
items:
type: string
responses:
'200':
description: Resultado
content:
application/json:
schema:
type: object
properties:
queued:
type: integer
description: Borradores enviados a ARCA
batchIds:
type: array
items:
type: string
description: Lotes creados; consultalos en GET /invoices/batches/{batchId}
failed:
type: array
items:
type: object
properties:
draftId:
type: string
error:
type: string
'400':
description: Datos inválidos
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: postDocumentsDraftsInvoice
x-operation-id-source: derived
/documents/drafts/discard:
post:
summary: Descartar borradores
tags:
- Borradores
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- ids
properties:
ids:
type: array
minItems: 1
maxItems: 500
items:
type: string
responses:
'200':
description: Cantidad descartada
content:
application/json:
schema:
type: object
properties:
discarded:
type: integer
'400':
description: Datos inválidos
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: postDocumentsDraftsDiscard
x-operation-id-source: derived
components:
schemas:
DraftData:
type: object
description: Los datos de la factura propuesta
required:
- lines
properties:
receiver:
type: object
properties:
name:
type:
- string
- 'null'
maxLength: 200
docType:
type:
- string
- 'null'
description: CUIT, CUIL o DNI; null = consumidor final sin identificar
docNumber:
type:
- string
- 'null'
description: CUIT, CUIL o DNI, con o sin guiones
condicionIva:
type:
- integer
- 'null'
description: Condición frente al IVA del receptor (código de ARCA). Si falta, se busca en el padrón
email:
type:
- string
- 'null'
format: email
description: Si está, se le manda la factura
address:
type:
- string
- 'null'
maxLength: 300
concepto:
type: integer
enum:
- 1
- 2
- 3
default: 1
description: 1 productos, 2 servicios, 3 productos y servicios
serviceFrom:
type:
- string
- 'null'
format: date
description: AAAA-MM-DD, servicios
serviceTo:
type:
- string
- 'null'
format: date
description: AAAA-MM-DD, servicios
paymentDue:
type:
- string
- 'null'
format: date
description: Vencimiento del pago, AAAA-MM-DD
pricesIncludeIva:
type: boolean
default: true
description: Los precios de las líneas incluyen IVA
lines:
type: array
maxItems: 200
items:
type: object
required:
- description
- unitPrice
properties:
description:
type: string
maxLength: 200
quantity:
type: number
exclusiveMinimum: 0
default: 1
unitPrice:
type:
- number
- 'null'
minimum: 0
description: null si el documento no trae precio
ivaRate:
type: number
enum:
- 0
- 2.5
- 5
- 10.5
- 21
- 27
default: 21
description: Alícuota de IVA en porcentaje
documentTotal:
type:
- number
- 'null'
description: Total impreso en el documento, para controlar las líneas
currency:
type: string
minLength: 3
maxLength: 3
default: ARS
description: Moneda ISO 4217
documentDate:
type:
- string
- 'null'
format: date
description: Fecha del documento, AAAA-MM-DD. La factura se emite con la fecha del día
reference:
type:
- string
- 'null'
maxLength: 100
description: Número de remito, pedido o referencia
description:
type:
- string
- 'null'
maxLength: 500
description: Texto libre que va en la factura
Draft:
type: object
description: Un borrador de factura armado desde un documento, una planilla, datos enviados por API o una plantilla recurrente
properties:
id:
type: string
status:
type: string
enum:
- extracting
- review
- queued
- invoiced
- error
- discarded
description: 'extracting: leyéndose; review: espera revisión; queued: enviado a ARCA; invoiced: facturado; error: no se pudo leer o emitir; discarded: descartado'
mode:
type: string
enum:
- manual
- automatic
description: 'automatic: se emite solo si no hay observaciones'
source:
type: string
enum:
- upload
- google_drive
- zapier
- api
- recurring
- mcp
- whatsapp
sourceRef:
type:
- string
- 'null'
fileName:
type:
- string
- 'null'
mimeType:
type:
- string
- 'null'
hasFile:
type: boolean
templateId:
type:
- string
- 'null'
templateName:
type:
- string
- 'null'
cuitId:
type:
- string
- 'null'
ptoVta:
type:
- integer
- 'null'
environment:
type: string
enum:
- production
- homologation
data:
oneOf:
- $ref: '#/components/schemas/DraftData'
- type: 'null'
total:
type:
- number
- 'null'
description: Total calculado con las líneas; null si falta algún precio
voucherLetter:
type:
- string
- 'null'
enum:
- A
- B
- C
- null
confidence:
type:
- number
- 'null'
description: Confianza de la lectura con IA, de 0 a 1
issues:
type: array
description: Observaciones que hay que revisar
items:
type: object
properties:
code:
type: string
enum:
- 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:
type: string
errorMessage:
type:
- string
- 'null'
invoice:
type:
- object
- 'null'
description: La factura emitida desde el borrador
properties:
id:
type: string
voucherNumber:
type: integer
ptoVta:
type:
- integer
- 'null'
invoiceType:
type:
- integer
- 'null'
status:
type: string
amount:
type: number
emailStatus:
type:
- string
- 'null'
description: Estado del envío de la factura por email
url:
type: string
description: Link al borrador en el dashboard
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
Error:
type: object
description: Error de la API. Los errores de autenticación (401), validación (400), CUIT inexistente (404), conflicto (409) e internos (500) vienen como application/problem+json (RFC 9457) con code, message y resolution. Otros errores vienen como JSON con error y, a veces, details y code. En los dos casos está el campo error.
required:
- error
properties:
error:
type: string
description: Mensaje de error
code:
type: string
description: 'Código estable: unauthorized, invalid_request, cuit_not_found, conflict, internal_error, o códigos propios como SUBSCRIPTION_LIMIT_EXCEEDED'
message:
type: string
description: Qué pasó (problem+json)
resolution:
type: string
description: Qué hacer para resolverlo (problem+json)
type:
type: string
format: uri
description: URI del tipo de problema (problem+json)
title:
type: string
description: Título corto del problema (problem+json)
status:
type: integer
description: Código HTTP (problem+json)
detail:
type: string
description: Igual que message (problem+json)
details:
description: 'Detalle del error: un texto, o la lista de errores de validación'
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: 'Clave que elegís vos (recomendado: un UUID nuevo por cada factura o lote). Si reenviás la misma solicitud con la misma clave —por un timeout, un error de red o un 5xx— recibís la respuesta original (mismo `batchId`, header `Idempotent-Replayed: true`) en vez de una factura nueva. Para una factura distinta, o después de que ARCA rechazó la anterior en forma definitiva, usá una clave nueva. Entre 1 y 255 caracteres ASCII imprimibles; se guarda 7 días. En un lote, el ítem `i` queda identificado como `<clave>:<i>`.'
schema:
type: string
minLength: 1
maxLength: 255
example: 6f1c2b0e-8a43-4c5e-9d2a-3b7f1e0c9a11
responses:
IdempotencyInProgress:
description: 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.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
IdempotencyKeyReused:
description: '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.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
IdempotentReplayed:
description: '`true` cuando la respuesta es la guardada de una solicitud anterior con el mismo `Idempotency-Key`: no se encoló nada nuevo.'
schema:
type: string
enum:
- 'true'
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: 'API Key para autenticación. Formato: test_sk_xxx para testing, prod_sk_xxx para producción.'