POST /v1/documents/credit-notes/partial-refund

Scope: documents:write

Devolución parcial de líneas específicas de una factura autorizada. El servidor resuelve cada línea por índice o por código y construye la nota de crédito.

Campos del body

Campo	Tipo	Obligatorio	Descripción
`originalAccessKey`	string	Sí	Clave de acceso de 49 dígitos de la factura autorizada.
`reason`	string	Sí	Motivo. Máx. 300 chars.
`lines`	array	Sí	Al menos 1 línea a devolver. Cada elemento: `lineIndex` o `mainCode`, y `quantity`.
`issueDate`	string	No	`YYYY-MM-DD`. Si se omite, se usa la fecha del día.

Por cada elemento en lines: usar lineIndex o mainCode (no ambos, no ninguno). quantity es obligatorio y no puede superar la cantidad original de esa línea.

Respuesta y errores

201: Nota de crédito. Modo síncrono por defecto; ?async=true para asíncrono.

HTTP	error.code	Cuándo
422	`ORIGINAL_DOCUMENT_NOT_FOUND`	Factura no encontrada.
422	`ORIGINAL_DOCUMENT_NOT_AUTHORIZED`	Factura no está AUTHORIZED.
422	`INVALID_LINE_REFERENCE`	Línea sin `lineIndex` ni `mainCode`.
422	`INVALID_LINE_INDEX`	`lineIndex` fuera de rango.
422	`LINE_NOT_FOUND`	`mainCode` no existe en la factura original.
422	`QUANTITY_INVALID`	`quantity` ≤ 0.
422	`QUANTITY_EXCEEDS_ORIGINAL`	`quantity` mayor que la cantidad original.
422	`DUPLICATE_LINE_INDEX`	`lineIndex` repetido en `lines`.

Ejemplo por índice de línea

{
  "originalAccessKey": "0703202601099123456000110010010000000024000000011",
  "reason": "Devolución parcial — ítems defectuosos",
  "lines": [
    { "lineIndex": 0, "quantity": 2 },
    { "lineIndex": 2, "quantity": 1 }
  ]
}

Ejemplo por código de producto

{
  "originalAccessKey": "0703202601099123456000110010010000000024000000011",
  "reason": "Devolución por código de producto",
  "lines": [
    { "mainCode": "PROD-001", "quantity": 3 },
    { "mainCode": "SRV-CONS", "quantity": 1 }
  ]
}

Ejemplo en JavaScript

const API_BASE_URL = 'https://live.faktur.com.ec';
const API_KEY = 'sk_...';
const API_SECRET = 'tu-secret';

const body = {
  originalAccessKey: '0703202601099123456000110010010000000024000000011',
  reason: 'Devolución parcial — ítems defectuosos',
  lines: [
    { lineIndex: 0, quantity: 2 },
    { lineIndex: 2, quantity: 1 }
  ]
};

const response = await fetch(`${API_BASE_URL}/v1/documents/credit-notes/partial-refund`, {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'X-API-Secret': API_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
});

const json = await response.json();
if (json.success) {
  console.log('Nota de crédito:', json.data.accessKey, json.data.status);
} else {
  console.error('Error:', json.error?.code, json.error?.message);
}