Crear Factura

http

POST /invoicing/lite

Crea una factura electrónica o nota de crédito. Este es el endpoint principal de facturación de Solerba — diseñado para requerir la mínima información posible para emitir un documento fiscal válido.

Autenticación

Requiere header X-SOLERBA-TOKEN. Ver .

Request Body

Campos principales

Campo	Tipo	Requerido	Descripción
`branchId`	`integer`	Sí	ID de la sucursal desde la que se factura
`doctype`	`string`	No	Tipo de documento: `"01"` (factura) o `"04"` (nota de crédito). Default: `"01"`
`datetime`	`string`	No	Fecha y hora de emisión en formato ISO 8601. Default: fecha actual
`externalId`	`string`	No	ID externo para idempotencia (máx. 100 caracteres)
`client`	`object`	No	Datos del receptor. Si se omite, se factura como Consumidor Final
`items`	`array`	Sí	Líneas de la factura (mín. 1, máx. 400)
`payments`	`array`	Sí	Formas de pago (mín. 1)
`discounts`	`array`	No	Descuentos a nivel de documento
`additionalData`	`object`	No	Datos adicionales (requerido para notas de crédito)

Objeto `client`

Campo	Tipo	Requerido	Descripción
`taxReceiverType`	`string`	Sí	Tipo de receptor: `"01"`, `"02"`, `"03"` o `"04"`
`email`	`string`	Condicional	Email del receptor (requerido excepto para Consumidor Final)
`taxName`	`string`	Condicional	Razón social (requerido para tipos 01, 03, 04)
`taxId`	`string`	Condicional	RUC del receptor (requerido para tipos 01, 03, 04)
`taxDv`	`integer`	Condicional	Dígito verificador (requerido para tipos 01, 03, 04)
`taxIdType`	`integer`	Condicional	Tipo de identificación: `1` (natural) o `2` (jurídico). Requerido para tipos 01, 03, 04
`phone`	`string`	No	Teléfono del receptor
`dni`	`string`	No	Cédula (solo para Consumidor Final)
`ignoreCreate`	`boolean`	No	Si es `true`, no crea el cliente en el catálogo

Objeto en `items[]`

Campo	Tipo	Requerido	Descripción
`description`	`string`	Sí	Descripción del producto o servicio
`qty`	`number`	Sí	Cantidad (puede ser decimal)
`price`	`number`	Sí	Precio unitario
`taxes`	`array`	Sí	Impuestos aplicables (mín. 1)
`sku`	`string`	No	Código del producto en tu sistema
`unitMeasure`	`string`	No	Unidad de medida (`"kg"`, `"und"`, `"m"`, `"l"`, etc.)
`codCpbScmp`	`string`	No	Código de compra gubernamental (solo para receptores tipo 03)
`discount`	`number`	No	Descuento por unidad
`additionalData`	`object`	No	Datos adicionales del ítem

Objeto en `items[].taxes[]`

Campo	Tipo	Requerido	Descripción
`code`	`string`	Sí	Código ITBMS: `"00"`, `"01"`, `"02"` o `"03"`
`amount`	`number`	No	Monto del impuesto (se calcula automáticamente si se omite)
`description`	`string`	No	Descripción del impuesto

Objeto en `payments[]`

Campo	Tipo	Requerido	Descripción
`type`	`string`	Sí	Código de forma de pago: `"02"`, `"03"`, `"04"`, `"08"`, `"99"` o `"PLAZO"`
`amount`	`number`	Sí	Monto del pago
`description`	`string`	Condicional	Descripción (requerido para tipo `"99"`, mín. 12 caracteres)

Objeto en `discounts[]`

Campo	Tipo	Requerido	Descripción
`amount`	`number`	Sí	Monto del descuento
`description`	`string`	Sí	Descripción del descuento

Objeto `additionalData`

Campo	Tipo	Requerido	Descripción
`creditNote`	`object`	Condicional	Requerido cuando `doctype` es `"04"`
`creditNote.cufe`	`string`	Sí (en nota de crédito)	CUFE de la factura original a la que se hace referencia

Validaciones especiales

Validación por tipo de receptor

Consumidor Final (02): No requiere taxName, taxId, taxDv ni taxIdType. Permite dni opcional.
Contribuyente (01), Gobierno (03), Extranjero (04): Requieren taxName, taxId, taxDv y taxIdType.
Gobierno (03): Permite el campo codCpbScmp en los ítems para código de compra gubernamental.
Nota de crédito (04): Requiere additionalData.creditNote.cufe con el CUFE de la factura original.

Ejemplos

Factura a Consumidor Final (mínimo)

El caso más simple — sin datos de cliente:

bash

curl -X POST "https://api.solerba.com/external-api/invoicing/lite" \
  -H "X-SOLERBA-TOKEN: tu-api-token-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": 1,
    "items": [
      {
        "description": "Producto de prueba",
        "qty": 1,
        "price": 10,
        "taxes": [{ "code": "00" }]
      }
    ],
    "payments": [
      { "type": "08", "amount": 10 }
    ]
  }'

Ejemplo JS

javascript

const response = await fetch('https://api.solerba.com/external-api/invoicing/lite', {
  method: 'POST',
  headers: {
    'X-SOLERBA-TOKEN': process.env.SOLERBA_TOKEN,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    branchId: 1,
    items: [
      {
        description: 'Producto de prueba',
        qty: 1,
        price: 10,
        taxes: [{ code: '00' }]
      }
    ],
    payments: [
      { type: '08', amount: 10 }
    ]
  })
});

const result = await response.json();
console.log(result.result.cufe);

Ejemplo Py

python

import requests

response = requests.post(
    'https://api.solerba.com/external-api/invoicing/lite',
    headers={
        'X-SOLERBA-TOKEN': 'tu-api-token-aqui',
        'Content-Type': 'application/json'
    },
    json={
        'branchId': 1,
        'items': [
            {
                'description': 'Producto de prueba',
                'qty': 1,
                'price': 10,
                'taxes': [{'code': '00'}]
            }
        ],
        'payments': [
            {'type': '08', 'amount': 10}
        ]
    }
)

result = response.json()
print(result['result']['cufe'])

Factura a Contribuyente

Con datos fiscales completos del receptor:

bash

curl -X POST "https://api.solerba.com/external-api/invoicing/lite" \
  -H "X-SOLERBA-TOKEN: tu-api-token-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": 1,
    "client": {
      "taxName": "Empresa ABC S.A.",
      "taxId": "6-123-3123",
      "taxDv": 1,
      "taxIdType": 2,
      "taxReceiverType": "01",
      "email": "[email protected]"
    },
    "items": [
      {
        "sku": "SRV-001",
        "description": "Servicio de consultoría",
        "qty": 1,
        "price": 500,
        "taxes": [{ "code": "01" }]
      }
    ],
    "payments": [
      { "type": "04", "amount": 535 }
    ]
  }'

Ejemplo JS

javascript

const response = await fetch('https://api.solerba.com/external-api/invoicing/lite', {
  method: 'POST',
  headers: {
    'X-SOLERBA-TOKEN': process.env.SOLERBA_TOKEN,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    branchId: 1,
    client: {
      taxName: 'Empresa ABC S.A.',
      taxId: '6-123-3123',
      taxDv: 1,
      taxIdType: 2,
      taxReceiverType: '01',
      email: '[email protected]'
    },
    items: [
      {
        sku: 'SRV-001',
        description: 'Servicio de consultoría',
        qty: 1,
        price: 500,
        taxes: [{ code: '01' }]
      }
    ],
    payments: [
      { type: '04', amount: 535 }
    ]
  })
});

const result = await response.json();

Ejemplo Py

python

import requests

response = requests.post(
    'https://api.solerba.com/external-api/invoicing/lite',
    headers={
        'X-SOLERBA-TOKEN': 'tu-api-token-aqui',
        'Content-Type': 'application/json'
    },
    json={
        'branchId': 1,
        'client': {
            'taxName': 'Empresa ABC S.A.',
            'taxId': '6-123-3123',
            'taxDv': 1,
            'taxIdType': 2,
            'taxReceiverType': '01',
            'email': '[email protected]'
        },
        'items': [
            {
                'sku': 'SRV-001',
                'description': 'Servicio de consultoría',
                'qty': 1,
                'price': 500,
                'taxes': [{'code': '01'}]
            }
        ],
        'payments': [
            {'type': '04', 'amount': 535}
        ]
    }
)

result = response.json()

Factura al Gobierno

Con código de compra gubernamental (codCpbScmp):

bash

curl -X POST "https://api.solerba.com/external-api/invoicing/lite" \
  -H "X-SOLERBA-TOKEN: tu-api-token-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": 1,
    "client": {
      "taxName": "Ministerio de Educación",
      "taxId": "4-NT-2-743890",
      "taxDv": 10,
      "taxIdType": 2,
      "taxReceiverType": "03",
      "email": "[email protected]",
      "phone": "5072001234"
    },
    "items": [
      {
        "description": "Equipos de cómputo",
        "qty": 10,
        "price": 1000,
        "codCpbScmp": "1110",
        "taxes": [{ "code": "01" }]
      }
    ],
    "payments": [
      { "type": "04", "amount": 10700 }
    ]
  }'

Ejemplo JS

javascript

const response = await fetch('https://api.solerba.com/external-api/invoicing/lite', {
  method: 'POST',
  headers: {
    'X-SOLERBA-TOKEN': process.env.SOLERBA_TOKEN,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    branchId: 1,
    client: {
      taxName: 'Ministerio de Educación',
      taxId: '4-NT-2-743890',
      taxDv: 10,
      taxIdType: 2,
      taxReceiverType: '03',
      email: '[email protected]',
      phone: '5072001234'
    },
    items: [
      {
        description: 'Equipos de cómputo',
        qty: 10,
        price: 1000,
        codCpbScmp: '1110',
        taxes: [{ code: '01' }]
      }
    ],
    payments: [
      { type: '04', amount: 10700 }
    ]
  })
});

Ejemplo Py

python

import requests

response = requests.post(
    'https://api.solerba.com/external-api/invoicing/lite',
    headers={
        'X-SOLERBA-TOKEN': 'tu-api-token-aqui',
        'Content-Type': 'application/json'
    },
    json={
        'branchId': 1,
        'client': {
            'taxName': 'Ministerio de Educación',
            'taxId': '4-NT-2-743890',
            'taxDv': 10,
            'taxIdType': 2,
            'taxReceiverType': '03',
            'email': '[email protected]',
            'phone': '5072001234'
        },
        'items': [
            {
                'description': 'Equipos de cómputo',
                'qty': 10,
                'price': 1000,
                'codCpbScmp': '1110',
                'taxes': [{'code': '01'}]
            }
        ],
        'payments': [
            {'type': '04', 'amount': 10700}
        ]
    }
)

Nota de Crédito

Referenciando el CUFE de la factura original:

bash

curl -X POST "https://api.solerba.com/external-api/invoicing/lite" \
  -H "X-SOLERBA-TOKEN: tu-api-token-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "doctype": "04",
    "branchId": 1,
    "items": [
      {
        "description": "Devolución de producto",
        "qty": 1,
        "price": 50,
        "taxes": [{ "code": "01" }],
        "unitMeasure": "und"
      }
    ],
    "payments": [
      { "type": "02", "amount": 53.5 }
    ],
    "additionalData": {
      "creditNote": {
        "cufe": "FE0120000155704849-2-2021-3200012026021019600000460010129600000462"
      }
    }
  }'

Ejemplo JS

javascript

const response = await fetch('https://api.solerba.com/external-api/invoicing/lite', {
  method: 'POST',
  headers: {
    'X-SOLERBA-TOKEN': process.env.SOLERBA_TOKEN,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    doctype: '04',
    branchId: 1,
    items: [
      {
        description: 'Devolución de producto',
        qty: 1,
        price: 50,
        taxes: [{ code: '01' }],
        unitMeasure: 'und'
      }
    ],
    payments: [
      { type: '02', amount: 53.5 }
    ],
    additionalData: {
      creditNote: {
        cufe: 'FE0120000155704849-2-2021-3200012026021019600000460010129600000462'
      }
    }
  })
});

Ejemplo Py

python

import requests

response = requests.post(
    'https://api.solerba.com/external-api/invoicing/lite',
    headers={
        'X-SOLERBA-TOKEN': 'tu-api-token-aqui',
        'Content-Type': 'application/json'
    },
    json={
        'doctype': '04',
        'branchId': 1,
        'items': [
            {
                'description': 'Devolución de producto',
                'qty': 1,
                'price': 50,
                'taxes': [{'code': '01'}],
                'unitMeasure': 'und'
            }
        ],
        'payments': [
            {'type': '02', 'amount': 53.5}
        ],
        'additionalData': {
            'creditNote': {
                'cufe': 'FE0120000155704849-2-2021-3200012026021019600000460010129600000462'
            }
        }
    }
)

Respuesta exitosa

HTTP 201 Created

json

{
  "success": true,
  "result": {
    "id": 18874,
    "cufe": "FE0120000155704849-2-2021-3200012026021019600000460010129600000462",
    "urlPdf": "https://storage.solerba.com/invoices/18874.pdf",
    "datetime": "2026-03-20T15:30:00.000Z"
  }
}

Campo	Tipo	Descripción
`id`	`integer`	Identificador único de la factura en Solerba
`cufe`	`string`	Código Único de Factura Electrónica asignado por la DGI
`urlPdf`	`string`	URL para descargar el PDF de la factura
`datetime`	`string`	Fecha y hora de emisión en formato ISO 8601

Problemas comunes

Error	Causa	Solución
`401 Unauthorized`	Token inválido o expirado	Verifica tu API Token
`400` — items requerido	No se enviaron ítems	Incluye al menos 1 ítem en el array `items`
`400` — payments requerido	No se enviaron pagos	Incluye al menos 1 pago en el array `payments`
`400` — branchId requerido	Falta el ID de sucursal	Envía un `branchId` válido
`400` — CUFE requerido	Nota de crédito sin CUFE	Para `doctype: "04"`, incluye `additionalData.creditNote.cufe`
`400` — description requerida	Pago tipo "99" sin descripción	Agrega `description` con mínimo 12 caracteres
Sin folios disponibles	El paquete no tiene folios	Contacta al administrador para asignar un nuevo paquete
`400` — taxName/taxId requerido	Contribuyente sin datos fiscales	Incluye `taxName`, `taxId`, `taxDv` y `taxIdType` para receptores tipo 01, 03 o 04

Siguientes pasos

— Cancela una factura emitida
— Consulta una factura por ID o CUFE
— Guía completa sobre tipos de documento e impuestos

Crear Factura ​

Autenticación ​

Request Body ​

Campos principales ​

Objeto client ​

Objeto en items[] ​

Objeto en items[].taxes[] ​

Objeto en payments[] ​

Objeto en discounts[] ​

Objeto additionalData ​

Validaciones especiales ​

Ejemplos ​

Factura a Consumidor Final (mínimo) ​

Factura a Contribuyente ​

Factura al Gobierno ​

Nota de Crédito ​

Respuesta exitosa ​

Problemas comunes ​

Siguientes pasos ​

Crear Factura

Autenticación

Request Body

Campos principales

Objeto `client`

Objeto en `items[]`

Objeto en `items[].taxes[]`

Objeto en `payments[]`

Objeto en `discounts[]`

Objeto `additionalData`

Validaciones especiales

Ejemplos

Factura a Consumidor Final (mínimo)

Factura a Contribuyente

Factura al Gobierno

Nota de Crédito

Respuesta exitosa

Problemas comunes

Siguientes pasos