Clientes

Los clientes en Solerba representan a los receptores de las facturas electrónicas. Cada cliente tiene datos fiscales asociados que determinan cómo se genera la factura ante la DGI.

Tipos de receptor

La DGI de Panamá clasifica a los receptores de facturas en cuatro tipos:

Código	Tipo	Descripción
01	Contribuyente	Persona natural o jurídica registrada ante la DGI con RUC
02	Consumidor Final	Persona que adquiere bienes o servicios para uso personal
03	Gobierno	Entidades gubernamentales
04	Extranjero	Personas o empresas no registradas en Panamá

Datos requeridos por tipo de receptor

Los datos fiscales requeridos varían según el tipo de receptor:

Campo	Contribuyente (01)	Consumidor Final (02)	Gobierno (03)	Extranjero (04)
taxName	Requerido	Opcional	Requerido	Requerido
taxId (RUC)	Requerido	No aplica	Requerido	Opcional (alias de foreignTaxId)
taxDv (DV)	Requerido	No aplica	Requerido	No aplica
taxIdType	Requerido (1 o 2)	No aplica	Requerido	No aplica
foreignTaxId	No aplica	No aplica	No aplica	Requerido (o passport)
passport	No aplica	No aplica	No aplica	Requerido (o foreignTaxId)
country	No aplica	No aplica	No aplica	Requerido con passport
email	Opcional (recomendado)	Opcional	Opcional (recomendado)	Opcional (recomendado — se usa para enviar el PDF)
phone	Opcional	Opcional	Opcional	Opcional
dni	No aplica	Opcional	No aplica	No aplica

Tipo de identificación (taxIdType)

• 1 — Persona natural (cédula)
• 2 — Persona jurídica (RUC empresarial)

País del receptor (country)

Código de país en formato ISO 3166-1 alpha-2 (dos letras: US, CO, ES, MX). Solo aplica al receptor Extranjero (04) y se envía a la DGI en el campo PaisExt, que acompaña al número de pasaporte. Enviarlo en cualquier otro tipo de receptor produce un error 400.

Consumidor Final

El caso más simple de facturación. Cuando no se envía el objeto client en la API, la factura se emite automáticamente como Consumidor Final (tipo 02).

Para Consumidor Final:

• No se requiere RUC ni datos fiscales
• Opcionalmente se puede incluir un dni (cédula) para identificación
• El email es opcional

Contribuyente

Para facturar a un contribuyente, es necesario proporcionar datos fiscales completos:

{
  "client": {
    "taxName": "Empresa ABC S.A.",
    "taxId": "6-123-3123",
    "taxDv": 1,
    "taxIdType": 2,
    "taxReceiverType": "01",
    "email": "[email protected]"
  }
}

Validación de RUC

Puedes validar los datos fiscales de un RUC antes de facturar usando el endpoint .

Extranjero

El receptor Extranjero (04) se usa para personas o empresas que no están registradas ante la DGI de Panamá. A diferencia del contribuyente, no tiene RUC ni dígito verificador: se identifica con su documento de origen.

Identificación

Debes enviar uno de estos dos campos — son excluyentes entre sí:

Campo	Descripción
foreignTaxId	Identificación tributaria del país de origen (por ejemplo, el EIN o VAT del cliente). Entre 3 y 50 caracteres. Se envía a la DGI como NumIdTE
passport	Número de pasaporte del receptor. Entre 3 y 50 caracteres. Se envía a la DGI como NumPasaporte

Enviar ambos produce un error 400. Si no envías ninguno de los dos pero sí taxId, este último se interpreta como foreignTaxId (alias por retrocompatibilidad).

Cuando identificas al receptor por pasaporte, country es obligatorio: la DGI exige el país (PaisExt) junto al número de pasaporte. Con foreignTaxId el país es opcional.

Diferencias con el contribuyente

• Sin dígito verificador — taxDv no aplica y no se envía a la DGI. El DV solo existe para receptores Contribuyente (01) y Gobierno (03)
• Sin tipo de identificación — taxIdType tampoco aplica: el documento fiscal del extranjero no lleva este campo
• El RUC del documento es EXTRANJERO — Solerba emite el documento con el literal "EXTRANJERO" como identificación fiscal del receptor, igual que usa "CF" para el Consumidor Final. La identificación real (foreignTaxId o passport) viaja en su campo específico
• Sin validación ante la DGI — no es posible verificar los datos de un extranjero con , porque ese registro es exclusivo de Panamá. Los datos se envían tal como los proporcionas

Referencia

Este comportamiento sigue la especificación NUC-JSON Panamá V2.0.7 y el ejemplo oficial de Digifact NUC 17 — a extranjero con nombre_dirección.

Ejemplo — identificación tributaria extranjera

{
  "branchId": 1,
  "client": {
    "taxName": "Foreign Corp LLC",
    "taxReceiverType": "04",
    "foreignTaxId": "98-7654321",
    "email": "[email protected]",
    "address": "1209 Orange St, Wilmington, DE"
  },
  "items": [
    { "description": "Servicio de consultoría", "qty": 1, "price": 500, "taxes": [{ "code": "00" }] }
  ],
  "payments": [
    { "type": "04", "amount": 500 }
  ]
}

Ejemplo — pasaporte

country es obligatorio en esta variante:

{
  "branchId": 1,
  "client": {
    "taxName": "John Smith",
    "taxReceiverType": "04",
    "passport": "X1234567",
    "country": "CO",
    "email": "[email protected]"
  },
  "items": [
    { "description": "Servicio de consultoría", "qty": 1, "price": 500, "taxes": [{ "code": "00" }] }
  ],
  "payments": [
    { "type": "04", "amount": 500 }
  ]
}

Clientes en las facturas por API

Los datos del cliente que envías en una factura por API (client) se usan únicamente para emitir el documento fiscal: no crean ni modifican clientes en el catálogo de la empresa. El catálogo se gestiona desde el panel.

Esto significa que no necesitas registrar al cliente en Solerba antes de facturarle — basta con enviar sus datos fiscales completos en cada factura. Ver los campos disponibles en .

Gestión desde el panel

Desde el panel de administración y el panel de facturación puedes:

• Ver el listado de clientes registrados por empresa
• Crear nuevos clientes con sus datos fiscales
• Editar información de clientes existentes

Siguientes pasos

• — Emite facturas a tus clientes
• — Referencia del endpoint con ejemplos por tipo de receptor
• — Valida datos fiscales antes de facturar