# Contingencia Local Panamá

- **País:** Panamá
- **Versión:** v2.0.0
- **Actualizada el:** 08/10/2026
- **Versión HTML:** `/pa/guias/contingencia-local`

Guía para integradores · Librería NUC_Contingencia v2.0.0

Esta guía explica cómo funciona la emisión en contingencia de documentos fiscales electrónicos de Panamá con la librería local de Digifact: qué hace, cómo se integra en su sistema y qué ocurre con los documentos cuando se restablece la conexión.

## ¿Qué es la Contingencia Local?

Es un componente (DLL para .NET Framework) que se instala junto a su aplicación y le permite seguir facturando aunque no haya conexión con Digifact o con la DGI: sin internet, con la plataforma en mantenimiento o ante cualquier falla de comunicación.

La librería toma el mismo NUC que usted ya envía al API de Digifact y, de forma totalmente local (sin ninguna llamada a internet):

- Transforma el NUC al formato oficial rFE de la DGI.
- Lo firma electrónicamente con el certificado de su empresa.
- Calcula el CUFE y el enlace QR de consulta pública.
- Le devuelve el documento listo para imprimir y entregar el CAFE a su cliente.

El documento sale marcado como operación en contingencia (tipo de emisión `02`), con el motivo y la fecha/hora de inicio de la contingencia — tal como lo exige la normativa de la DGI.

## ¿Cómo funciona? El flujo completo

| Paso | Qué ocurre | Quién lo hace |
|---|---|---|
| 1. Se detecta la falla | Su sistema no logra comunicarse con el API de Digifact (timeout, sin internet, etc.). Su aplicación decide pasar a modo contingencia. | Su sistema |
| 2. Emisión local | Su sistema arma el NUC de la venta (el mismo de siempre) y lo pasa a la librería junto con el motivo de la contingencia. La librería devuelve el rFE firmado, el CUFE y el QR. | Librería Digifact |
| 3. Entrega al cliente | Se imprime/entrega el CAFE con la leyenda de contingencia. La venta no se detiene. | Su sistema |
| 4. Resguardo | Cada documento emitido se conserva en disco (o en su base de datos) para su transmisión posterior. La librería incluye una opción de spool que lo hace por usted. | Su sistema / librería |
| 5. Transmisión a la DGI | Al restablecerse la conexión, los documentos del episodio se envían a certificar a través de la plataforma Digifact, dentro del plazo legal. | Su sistema + Digifact |

> **Plazo legal (DGI):** los documentos emitidos en contingencia deben obtener su Autorización de Uso dentro de las 72 horas siguientes a la emisión. Si el episodio supera las 72 horas, el motivo debe explicar además por qué no se volvió a operación normal. Recomendamos transmitir tan pronto se restablezca la comunicación.

## Requisitos e instalación

No requiere instalador ni recompilar su aplicación: es copiar archivos junto a su ejecutable. Funciona en cualquier Windows con .NET Framework 4.x y carga en procesos de 32 y de 64 bits (AnyCPU).

| Archivo | ¿Cuándo se necesita? |
|---|---|
| `NUC_Contingencia_DigifactSA.dll` | Siempre. Es la librería principal. |
| `pa.digifact.com.FEConstruct.dll` | Siempre. Componente de construcción del rFE. |
| `NUCSchema.xsd` | Solo si usa la ruta XML (`GENERATE_FE`). La ruta JSON usa el esquema embebido. |
| `NUCSchema.json` | Solo si su integración llama a `checkFiles` esperando Código 0. |

Desde la versión 2.0.0 ya no se necesitan el Visual C++ Redistributable ni las librerías Chilkat y Newtonsoft.Json: su aplicación puede usar la versión de Newtonsoft que prefiera, sin conflictos ni binding redirects.

## Archivo de credenciales

La librería firma con el certificado de su empresa. Los datos se indican en un archivo JSON cuya ruta se pasa al constructor:

```json
{
  "Ruc": "155000000-2-2021",
  "FirmaBase64": "<certificado PFX codificado en base64>",
  "Contrasenia": "<contraseña del PFX>",
  "QRKey": "<clave QR provista por Digifact>"
}
```

### Alternativas más seguras (opcionales, v2.0.0)

| Clave | Qué permite |
|---|---|
| `CertThumbprint` | El certificado vive en el almacén de Windows; la clave privada nunca pasa por un archivo. |
| `PfxPath` | El PFX en disco, fuera del JSON, protegido con permisos NTFS. |
| `ContraseniaDPAPI` | La contraseña protegida con DPAPI de Windows en lugar de texto plano. |

> **Aviso de vencimiento:** la librería avisa con 30 días de antelación cuando el certificado está por vencer (sin bloquear la emisión) y detiene la emisión si el certificado ya venció — así ningún documento sale con una firma que la DGI rechazaría.

## Integración en su código

La ruta recomendada es la JSON (`GENERATE_FE_WITH_JSON`). Ejemplo mínimo en C#:

```csharp
var gen = new GENERATE_FE_WITH_JSON(
    @"C:\FEL\credenciales.json",               // archivo de credenciales
    @"C:\FEL\NUCSchema.json",                  // esquema (validación informativa)
    "Falla de comunicación con el proveedor",  // motivo (15–250 caracteres)
    DateTime.Now);                             // fecha/hora de inicio de la contingencia

gen.setEnvironment(2);   // 1 = producción · 2 = pruebas
gen.ConfigDecimales(6);

TransformResult r = gen.GET_XML(nucJson);

if (r.EsExitoso) {   // equivale a r.codigo == 1
    string rfeFirmado = r.responseData1;   // XML rFE firmado
    string cufe = r.CUFE;
    string qr = r.linkQR;
} else {
    // r.mensaje, r.descripcion y r.fel_error indican la causa exacta
}
```

También existe la sobrecarga `GET_XML(nuc, motivo, fecha)` para indicar el motivo y la fecha en cada llamada, y la clase `GENERATE_FE` para integraciones que trabajan con el NUC en XML.

### Campos principales de la respuesta (TransformResult)

| Campo | Contenido |
|---|---|
| `codigo` / `EsExitoso` | 1 = éxito, 0 = error. Use `EsExitoso` para evitar confusiones. |
| `responseData1` | El rFE firmado (XML), listo para resguardar y transmitir. |
| `CUFE` / `linkQR` | Identificador único del documento y URL del QR de consulta pública. |
| `mensaje` / `descripcion` | Resultado general y detalle (incluye hallazgos de esquema no bloqueantes). |
| `fel_error` / `fel_infoDetails` | Solo en errores: categoría (ESTRUCTURA, TRANSFORM…) y detalle técnico. |

## Recomendaciones al armar el NUC

- Envíe todos los importes y cantidades como texto con 6 decimales (por ejemplo `"Price": "100.000000"`). Es válido en todas las representaciones y evita hallazgos de esquema.
- El ambiente del documento viaja en `Header.AdditionalIssueType` y debe ser coherente con `setEnvironment`.
- En los impuestos de cada ítem, el código de tasa ITBMS va en el campo `Code` (`00` = exento, `01` = 7%); `Rate` solo se usa con tasa porcentual de ISC.
- Varios campos que los esquemas marcan como opcionales son obligatorios en la práctica (p. ej. el teléfono del emisor). La Guía del NUC mínimo emisible que acompaña al paquete lista cada campo con su referencia de error.
- Desde la v2.0.0, si falta un campo obligatorio el error indica la ruta exacta del campo en lugar de un error genérico.

## Al restablecerse la conexión

Los documentos emitidos localmente deben transmitirse a la DGI para obtener su Autorización de Uso dentro del plazo de 72 horas. La transmisión se realiza a través de la plataforma Digifact; coordine con su ejecutivo o con soporte la habilitación del reenvío de contingencia para su integración. Buenas prácticas:

- Conserve cada rFE firmado tal como lo devolvió la librería (la opción spool de la configuración lo deja en disco automáticamente, listo para el reenvío).
- Transmita apenas se restablezca la comunicación, priorizando los documentos más antiguos.
- Verifique el resultado de cada documento transmitido y conserve el acuse.
- Use el mismo motivo y la misma fecha de inicio para todos los documentos del mismo episodio.

## Configuración opcional

Si se coloca un archivo `NUC_Contingencia.config.json` junto a la DLL se habilitan opciones adicionales; sin él, el comportamiento es el estándar:

| Opción | Para qué sirve |
|---|---|
| `logging` | Bitácora con niveles y rotación. El certificado, la contraseña y la clave QR se redactan siempre: el log se puede compartir con soporte sin riesgo. |
| `spool` | Guarda automáticamente cada documento emitido en disco, para su transmisión posterior. |
| `ambientePorDefecto` | Fija producción o pruebas por instalación, sin tocar su código. |
| `certificado.diasAvisoVencimiento` | Cambia la antelación del aviso de vencimiento (predeterminado: 30 días). |

> ¿Dudas? Contacte a su ejecutivo de cuenta o al equipo de soporte de Digifact. Para pruebas de integración solicite sus credenciales del ambiente de pruebas.
