Emitir comprobante

POST /api/v1/facturas

Emite un comprobante electrónico (FE, TE, NC o ND) y lo encola para envío a Hacienda. La respuesta es inmediata con estado procesando; el estado final llega después vía webhook o mediante polling a GET /facturas/{clave}.

Autenticación y permisos

Atributo	Valor
Esquema	API key (`X-Api-Key`)
Scope requerido	`facturas:write` para `tipo` FE/TE — `notas:write` para `tipo` NC/ND. Ver Scopes.
Idempotente	Sí (con header `Idempotency-Key`)
Rate limit	120 req/min por API key

Headers


POST /api/v1/facturas HTTP/1.1
Host: api.pos.lxsyscr.com
X-Api-Key: lxs_live_a1b2c3d4_001122...
Content-Type: application/json
Idempotency-Key: 4f1c8a8a-2c4f-4b5e-9c2a-1234567890ab
Accept: application/json

Request body

Ver FacturaApiRequestDto para el schema completo.

Ejemplo mínimo (FE):


{
  "tipo": "FacturaElectronica",
  "idUsuario": 7,
  "cliente": { "idCliente": 42 },
  "condicionVenta": "01",
  "medioPago": "01",
  "moneda": "CRC",
  "lineas": [
    { "idProducto": 100, "cantidad": 2 }
  ]
}

Ejemplo completo (FE con descuento, exoneración, USD):


{
  "tipo": "FacturaElectronica",
  "idUsuario": 7,
  "cliente": { "idCliente": 42 },
  "condicionVenta": "02",
  "plazoCredito": 30,
  "medioPago": "04",
  "moneda": "USD",
  "tipoCambio": 670.50,
  "codigoActividad": "722002",
  "comentario": "Pedido #1234 — Cliente VIP",
  "lineas": [
    {
      "idProducto": 100,
      "cantidad": 3,
      "precioUnitario": 50.00,
      "montoDescuento": 5.00,
      "naturalezaDescuento": "Volumen >= 3 unidades"
    },
    {
      "idProducto": 101,
      "cantidad": 1,
      "idExoneracion": 7
    }
  ],
  "referencias": []
}

La línea con idExoneracion no manda ningún monto: el servidor calcula cuánto se exonera a partir de la exoneración del cliente y la tarifa de IVA del producto. El 7 se obtiene del arreglo exoneraciones de GET /clientes/{identificacion}. El campo montoExoneracion sigue existiendo en el contrato pero está ignorado — ver Exoneraciones.

Respuestas

`201 Created`


HTTP/1.1 201 Created
Location: /api/v1/facturas/50615012600310112345600100001010000000123456789012
Content-Type: application/json


{
  "clave": "50615012600310112345600100001010000000123456789012",
  "numeroConsecutivo": "00100001010000000123",
  "tipoDocumento": "01",
  "estadoHacienda": "procesando",
  "totalComprobante": 169.50,
  "moneda": "USD",
  "fechaEmision": "2026-05-15T15:32:11Z"
}

`400 Bad Request`

Validación falló. Ejemplos:


{ "error": "Debe incluir al menos una línea." }


{ "error": "Producto 999 no encontrado." }


{ "error": "Cliente 42 no encontrado." }


{ "error": "Factura electrónica requiere cliente." }

Si una línea envía idExoneracion y la exoneración no es válida para ese cliente, la emisión se rechaza en vez de facturar con IVA completo en silencio — ver Exoneraciones:


{ "error": "Línea 1: la exoneración 7 no existe o no pertenece al cliente 42." }


{ "error": "Línea 1: la exoneración 7 está inactiva." }


{ "error": "Línea 1: la exoneración 7 venció el 10/01/2026." }


{ "error": "Línea 1: se indicó 'idExoneracion' 7 pero el documento no tiene cliente. La exoneración pertenece a un cliente registrado; envíe 'cliente.idCliente' o 'cliente.identificacion'." }

Al emitir una NC o ND, el motivo de la referencia debe ser un código del catálogo, enviado en referencias[0].codigo o en referencias[0].razon. Solo texto libre no emite:


{ "error": "La razón de la referencia no es un código válido (razon='Cargo por interés moratorio'). Envíe el código de 2 dígitos en 'codigo' o en 'razon', tomado del catálogo: 01 (Anula documento de referencia), 02 (Corrige texto de documento de referencia), 04 (Referencia a otro documento), … " }

`401 Unauthorized`

API key faltante, malformada o revocada.


{ "error": "API key ausente, inválida o revocada." }

`403 Forbidden`

API key válida pero sin el scope que corresponde al tipo emitido.


{ "error": "La API key no tiene el scope 'facturas:write', requerido para emitir este tipo de comprobante." }


{ "error": "La API key no tiene el scope 'notas:write', requerido para emitir este tipo de comprobante." }

Importante: Una key con facturas:write pero sin notas:write puede emitir FE y TE, pero recibe 403 al intentar tipo: "NotaCredito" o "NotaDebito". Ver Scopes.

`409 Conflict`

Idempotency-Key reutilizada con un body distinto. Ver Idempotencia.


{ "error": "Idempotency-Key reutilizada con body distinto." }

`413 Payload Too Large`

Body excede 256 KB.

`429 Too Many Requests`


HTTP/1.1 429 Too Many Requests
Retry-After: 38


{ "error": "Rate limit excedido. Reintenta en 38 segundos." }

`500 Internal Server Error`


{ "error": "Error interno emitiendo el comprobante." }

`501 Not Implemented`

Tipo de comprobante aún no soportado (caso histórico, ya no aplica).


{ "error": "Funcionalidad no disponible en esta versión." }

Notas operativas

La emisión es asíncrona respecto al envío a Hacienda. Un 201 significa “encolado para envío”, no “aceptado por Hacienda”.
El PDF y el XML quedan disponibles tras la emisión local, sin esperar la respuesta de Hacienda.
Si no se configuró un webhook, debe hacerse polling a GET /facturas/{clave} para conocer el estado final.