Referencia API

Documentación general de la API externa de Solerba: URL base, formato de respuestas, códigos de error y catálogos de referencia.

URL Base

https://api.solerba.com/external-api

Todas las solicitudes deben usar HTTPS. Las solicitudes HTTP serán rechazadas.

Autenticación

Todas las solicitudes requieren el header:

X-SOLERBA-TOKEN: tu-api-token-aqui

Consulta la para más detalles.

Endpoints disponibles

Método	Ruta	Descripción	Documentación
POST	/invoicing/lite	Crear factura o nota de crédito
POST	/invoicing/lite/cancel	Cancelar una factura emitida
GET	/invoicing/find	Buscar factura por ID o CUFE
GET	/invoicing/ruc/info	Consultar información de un RUC

Formato de respuesta

Respuesta exitosa

{
  "success": true,
  "result": {
    // Datos de la respuesta
  }
}

Respuesta de error

{
  "success": false,
  "error": "Descripción del error"
}

Error de validación

Cuando los datos enviados no cumplen con las validaciones requeridas, la respuesta incluye detalles específicos:

{
  "success": false,
  "error": [
    {
      "code": "too_small",
      "minimum": 1,
      "type": "array",
      "inclusive": true,
      "exact": false,
      "message": "Array must contain at least 1 element(s)",
      "path": ["items"]
    }
  ]
}

Códigos de estado HTTP

Código	Descripción	Uso
200	OK	Solicitud exitosa (GET)
201	Creado	Recurso creado exitosamente (POST de factura)
400	Bad Request	Datos inválidos o faltantes en la solicitud
401	No autorizado	Token ausente, inválido o expirado
403	Prohibido	Sin permisos o empresa inactiva
404	No encontrado	Recurso no encontrado
500	Error interno	Error del servidor — contacta a soporte

Catálogos de referencia

Tipos de documento

Código	Descripción
01	Factura de operaciones internas
04	Nota de crédito por referencia a factura

Códigos de impuesto ITBMS

Código	Tasa	Descripción
00	0%	Exento
01	7%	Tasa general
02	10%	Licores y productos específicos
03	15%	Tabaco y productos específicos

Tipos de receptor

Código	Tipo	Descripción
01	Contribuyente	Persona natural o jurídica con RUC
02	Consumidor Final	Consumidor sin datos fiscales
03	Gobierno	Entidades gubernamentales
04	Extranjero	Persona o empresa no registrada en Panamá

Formas de pago

Código	Forma de pago	Nota
01	Crédito	Forma de pago que acompaña a las cuotas PLAZO en facturas a crédito
02	Tarjeta de crédito/débito
03	Cheque
04	Transferencia bancaria
08	Efectivo
99	Otro	Requiere description de mínimo 12 caracteres
PLAZO	Cuota a plazo	Requiere date (vencimiento) y additionalData.paymentTime 2 o 3. Ver

Otros códigos del catálogo DGI

El API acepta cualquier código de forma de pago de 2 dígitos del catálogo oficial de la DGI. La tabla anterior lista los más comunes.

Tiempo de pago (additionalData.paymentTime)

Valor	Modo	Descripción
1	Contado	Pago inmediato (valor por defecto)
2	Crédito	Pago a plazos: las cuotas PLAZO suman el total de la factura
3	Mixto	Parte de contado + parte a crédito. Aún no disponible — el proveedor de facturación no ha implementado esta función

Tipos de identificación fiscal

Valor	Descripción
1	Persona natural (cédula)
2	Persona jurídica (RUC empresarial)

Unidades de medida comunes

Código	Descripción
und	Unidad
kg	Kilogramo
m	Metro
l	Litro
Hora	Hora
Dia	Día
Mes	Mes
Docena	Docena

Valores sensibles a mayúsculas

El catálogo de unidades distingue mayúsculas (und, kg en minúscula; Hora, Dia, Mes con inicial mayúscula). Un valor fuera del catálogo se rechaza con 400 indicando las opciones válidas.

Siguientes pasos

• — Endpoint principal para emitir facturas
• — Manejo de API Tokens
• — Guía de tipos de documento y flujo de facturación