En desarrollo. La API todavía no emite facturas reales: ninguna empresa tiene clave de producción. Solo funciona el ambiente de pruebas de la DGI.
Cómo funciona
Los sistemas nunca hablan con efacturapty ni con la base de Sage: todo pasa por la API. Las claves fiscales viven solo en el servidor.
Una emisión, paso a paso
POST /v1/facturas. Si algo falta, se dice antes de gastar número. Si el PAC no contesta, se reintenta con el mismo número.
1002 Documento duplicado. En prueba, la API salta al siguiente número sola. En producción devuelve rechazada: ese número ya quedó emitido, quizá en un intento anterior. Revísalo en la DGI antes de reenviar.
Rutas
Todas piden Authorization: Bearer <token de la empresa>, menos / y /salud. El token decide qué empresa emite.
| Ruta | Qué hace |
|---|---|
GET /salud | { ok: true } |
GET /v1/estado | Datos de la empresa del token: empresa, nombre, ruc, dv, sucursal, punto, produccion, prueba, maximoPrueba. |
GET /v1/siguiente?tipo=01&prueba=1 | El número que tocaría ahora, sin reservarlo. |
POST /v1/facturas | Emite. Cuerpo { borrador }. 400 con mensajes si falta algo. |
POST /v1/facturas/anular | Cuerpo { cufe, motivo, prueba }. Motivo de 15 caracteres o más. |
GET /v1/facturas/pdf?cufe=…&prueba=1 | El PDF de la factura (CAFE). |
GET /v1/ruc/:ruc | Consulta del RUC en la DGI. |
El borrador
Lo que manda el sistema. El emisor no va: sale de la empresa del token. Los totales tampoco: los calcula la API.
{
"prueba": true, // ambiente de pruebas
"tipoDocumento": "01", // 01 factura, 06 nota de crédito genérica, 04 / 05 notas referidas
"numero": 15, // solo al reenviar una rechazada
"fecha": 1794100000000, // milisegundos; sale con la hora de Panamá
"receptor": {
"tipo": "01", // 01 contribuyente, 02 consumidor final, 03 gobierno, 04 extranjero
"tipoContribuyente": 2, // 1 natural, 2 jurídica
"ruc": "155-1-2023", "dv": "45",
"nombre": "Empresa S.A.", "direccion": "", "correo": "cliente@empresa.pa", "telefono": "",
"pasaporte": "", "pais": "PA",
"codigoUbicacion": "", "provincia": "", "distrito": "", "corregimiento": ""
},
"items": [
{ "descripcion": "Cambio de aceite", "codigo": "", "cantidad": 1, "precio": 40,
"descuento": 0, "tasaItbms": "01" } // precio por unidad sin ITBMS; tasa 00 o 01
],
"pagos": [{ "forma": "02", "descripcion": "", "monto": 42.80 }],
"informacion": "", // sale impresa en la factura
"cufeReferenciado": "" // factura que corrige una nota 04 / 05
}
Formas de pago
01 crédito · 02 efectivo · 03 tarjeta de crédito · 04 tarjeta de débito · 05 fidelización · 06 vale · 07 tarjeta de regalo · 08 transferencia · 09 cheque · 10 punto de pago · 99 otro
ITBMS
00 exento · 01 7 %. Las tasas de 10 % y 15 % se rechazan: Sage no las registra.
La respuesta
{
"empresa": "SPEEDCAR", "tipoDocumento": "01", "numero": 3994, "prueba": false,
"estado": "autorizada", // o "rechazada"
"cufe": "FE0120000155650257-2-2017-…", "protocolo": "…", "fechaAutorizacion": "…",
"qr": "https://dgi-fep.mef.gob.pa/Consultas/…",
"mensajes": ["0260 Autorizado el uso de la FE"],
"solicitud": { "DatosGenerales": { … }, "ListaItems": [ … ], "Totales": { … } } // el JSON exacto enviado
}
Reglas
Todo lo que la API hace, revisa y rechaza. Código: servicio.js (rutas, numeración, envío), dgi.js (validaciones y JSON), sage.js (base de datos).
1. Acceso
- Toda ruta pide
Authorization: Bearer <token>, menos/y/salud. - El token dice qué empresa es. Tiene 16 caracteres o más y se compara en tiempo constante. Un token que no existe da 401.
- Una empresa solo emite con su clave. Nunca puede emitir con la de otra.
- Las claves de efacturapty y los tokens viven en
empresas.jsondel servidor, fuera de git y con permisos 600.
2. Empresas y ambientes
| Empresa | RUC | Sucursal | Punto |
|---|---|---|---|
| ALQUIMAQ_PANAMA | 155589097-2-2014 DV 17 | 0003 | 001 |
| ALQUIMAQ_CHORRERA | 155589097-2-2014 DV 17 | 0000 | 001 |
| ALQUIMAQ_CORONADO | 155589097-2-2014 DV 17 | 0002 | 001 |
| JDL_RENTALS | 8-975-1141 DV 21 | 0001 | 001 |
| SPEEDCAR | 155650257-2-2017 DV 99 | 0000 | 001 |
- Producción usa la clave de la empresa. Sin ella, la empresa no emite de verdad (503). La clave de producción se pone solo el día del corte de esa empresa.
- Prueba (
"prueba": true) usa la clave de prueba. Esa clave es de otra cuenta (RUC 8-954-1813), no de estas empresas. Todas la comparten, solo para probar. - En prueba la factura sale con la sucursal de la cuenta de prueba (
0000) y punto001, no con la de la empresa. - En prueba el correo del receptor se reemplaza por el correo de prueba. Una factura de prueba nunca le llega al cliente.
- En prueba el total máximo es 5 dólares.
- Sin clave del ambiente pedido, la API responde 503 antes de reservar número.
3. Numeración
- Producción: una serie por empresa y tipo de documento.
- Prueba: una serie por tipo de documento, compartida por todas las empresas. Nunca usa la numeración del sistema (
F-…). - La serie de producción arranca en el «Siguiente» de la empresa. Ejemplo: ALQUIMAQ_PANAMA factura 01 arranca en 1718, nota 06 en 457.
- La serie salta los números ya autorizados por otro sistema: sueltos o rangos.
- La serie nunca retrocede. Dos pedidos a la vez no reciben el mismo número.
- Las series viven en
~/efactura-datos, fuera de la carpeta de la app. Desplegar no las reinicia. - Un borrador trae
numerosolo para reenviar uno rechazado. Sinnumero, recibe el siguiente libre. - Un borrador que no pasa las validaciones da 400 y no gasta número.
GET /v1/siguientedice el número que tocaría, sin reservarlo.
4. Validaciones del borrador
Cualquiera de estas da 400 con la lista en mensajes. Nada se envía al PAC.
- Forma:
receptorobjeto,itemsypagoslistas,fechanúmero,numeroentero mayor que 0 si viene, cantidades, precios y montos numéricos. - Tipo de documento: solo
01,06,04o05. 04y05llevancufeReferenciado.- Receptor con nombre.
- Receptor contribuyente (
01) o gobierno (03): lleva RUC y DV. - Receptor extranjero (
04): lleva pasaporte o identificación. - País en código de 2 letras (PA, US…).
- Correo del receptor, si viene, bien escrito.
- Al menos una línea.
- Cada línea: descripción, de 160 caracteres o menos.
- Cada línea: cantidad mayor que 0.
- Cada línea: precio 0 o mayor.
- Cada línea: sin descuento. Sage no lo acepta: se baja el precio.
- Cada línea: ITBMS solo
00o01. - Los pagos cubren el total.
- En prueba, total de 5 dólares o menos.
5. Cálculo
- Línea: neto = precio × cantidad, redondeado a 2 decimales.
- ITBMS total = 7 % de la suma de las líneas gravadas, redondeado a 2 decimales. Igual que Sage.
- La diferencia de redondeo entre el ITBMS total y la suma por línea va a la última línea gravada.
- Total = neto + ITBMS. Vuelto = pagado − total.
- Los totales siempre los calcula la API.
6. JSON enviado al PAC
- En PascalCase:
DatosGenerales,ListaItems,Totales. - Valores fijos:
TipoEmision "01",NaturalezaOperacion "01",TipoOperacion 1,FormatoGeneracionCafe 1,ManeraEntregaCafe 1,EnvioContenedorReceptor 1,ProcesoGeneracionFe 2,TipoTransaccionVenta 1,TipoSucursal 2,UnidadMedidaCodigoInterno "und",Descuento null. DestinoOperacion: 2 si el receptor es extranjero, si no 1.InformacionEmisorlleva soloCodigoSucursal. El PAC completa RUC, nombre y dirección desde la cuenta de la clave.FechaEmisiones la hora real de Panamá (-05:00).TiempoPago: 1 contado, 2 crédito (todo con forma 01), 3 mixto.- El JSON se convierte a texto una sola vez. Ese texto exacto se envía, se reintenta, se devuelve en
solicitudy se guarda en la base de datos.
7. Envío y respuesta
- Red caída o error 5xx del PAC: hasta 3 intentos con el mismo número y el mismo texto (espera 2 y 4 segundos).
- Si los 3 fallan:
rechazadacon ese número. El sistema lo reenvía con ese número. - Error 4xx del PAC:
rechazadacon los mensajes del PAC. 1002 Documento duplicadoen prueba: salta al siguiente número solo (hasta 9 veces).1002en producción:rechazada. Ese número ya está emitido. Revísalo en la DGI, no reemitas a ciegas.- La respuesta trae
empresa,tipoDocumento,numero,prueba,estado,cufe,protocolo,fechaAutorizacion,qr,mensajesysolicitud. - Cada emisión y anulación queda en
facturas.jsonl.
8. Base de datos para Sage
- Solo se guardan facturas autorizadas en producción. Speechtree lee esta tabla: una fila es una factura real para él. Por eso las pruebas no escriben nada en ella.
- La tabla
facturas_sagese crea sola si no existe. - Una fila por documento: clave única
(empresa, tipo_documento, numero). json_fees el texto exacto enviado al PAC, no uno rehecho.fecha_emisionytotalsalen de ese mismo JSON.- Insert con
ON DUPLICATE KEY UPDATE id = id: guardar dos veces no duplica ni cambia nada. - Nunca UPDATE ni DELETE.
- Si MariaDB falla, la factura sigue autorizada y la fila queda en
pendientes-sage.jsonl. Se reintenta con la siguiente factura y al arrancar. - Credenciales en el
.envdel servidor, fuera de git, permisos 600. - Speechtree entra con su propio usuario: solo
SELECTsobrefacturas_sage, solo desde la IP del servidor de Sage.
Filas de prueba, mientras dura el desarrollo. Para probar la lectura, la tabla tiene 7 filas de SPEEDCAR que no son facturas: numero desde 9000001 y cufe que empieza por PRUEBA- (5 facturas 01, una nota 04 y una 06). El json_fe tiene la forma exacta de uno real. No se registran en Sage de verdad y se borran antes del corte: DELETE FROM facturas_sage WHERE numero > 9000000 AND cufe LIKE 'PRUEBA-%'.
9. Anulación, PDF y RUC
- Anular pide
cufey un motivo de 15 caracteres o más, con la clave del ambiente en que se emitió. - El PDF se pide con la clave del ambiente en que se emitió.
- La consulta de RUC usa la clave de producción si hay; si no, la de prueba.
facturas_sage
La tabla que lee Speechtree.
CREATE TABLE IF NOT EXISTS facturas_sage (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
empresa VARCHAR(30) NOT NULL,
tipo_documento CHAR(2) NOT NULL DEFAULT '01',
numero INT UNSIGNED NOT NULL,
fecha_emision DATETIME NOT NULL,
total DECIMAL(12,2) NOT NULL,
cufe VARCHAR(120) NULL,
json_fe LONGTEXT NOT NULL CHECK (JSON_VALID(json_fe)),
creado_en TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (id),
UNIQUE KEY ux_documento (empresa, tipo_documento, numero),
KEY ix_creado (creado_en)
);