API de factura electrónica

Un solo servicio para las cinco empresas del servidor. Cada sistema le manda un borrador; la API valida, numera, arma el JSON de la DGI, lo envía a efacturapty y guarda la copia que lee Speechtree para Sage 50.

Base: https://efactura.speedcarservices.com

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.

Arquitectura: sistemas, API, efacturapty, DGI, MariaDB, Speechtree y Sage 50 SISTEMAS DE CADA EMPRESA SPEEDCAR ALQUIMAQ_PANAMA ALQUIMAQ_CHORRERA ALQUIMAQ_CORONADO JDL_RENTALS borrador + token API efactura efactura.speedcarservices.com 1. Identifica la empresa 2. Valida el borrador 3. Reserva el número 4. Arma el JSON de la DGI 5. Envía y reintenta InvoiceRequest CUFE / rechazo efacturapty PAC DGI ~/efactura-datos contadores.json facturas.jsonl pendientes-sage.jsonl solo autorizadas de producción MariaDB facturas_sage solo INSERT SELECT Speechtree Sage 50 Modo prueba: clave de prueba, correo de prueba, máximo 5 dólares. Nunca llega a MariaDB ni a Speechtree.

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.

Flujo de una emisión, de la validación al guardado para Sage Llega el borrador con el token ¿Token válido y clave del ambiente? No: 401 o 503. Sin número. ¿Pasa las validaciones? No: 400 con la lista. Sin número. Reserva el número de la serie Producción: por empresa y tipo, desde «Siguiente», saltando los ya usados. Arma el JSON (un solo texto) Envía a efacturapty Red caída o 5xx: hasta 3 intentos, mismo número, mismo texto. Autorizada Producción: INSERT en facturas_sage Rechazada Vuelve con su número y los mensajes

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.

RutaQué hace
GET /salud{ ok: true }
GET /v1/estadoDatos de la empresa del token: empresa, nombre, ruc, dv, sucursal, punto, produccion, prueba, maximoPrueba.
GET /v1/siguiente?tipo=01&prueba=1El número que tocaría ahora, sin reservarlo.
POST /v1/facturasEmite. Cuerpo { borrador }. 400 con mensajes si falta algo.
POST /v1/facturas/anularCuerpo { cufe, motivo, prueba }. Motivo de 15 caracteres o más.
GET /v1/facturas/pdf?cufe=…&prueba=1El PDF de la factura (CAFE).
GET /v1/ruc/:rucConsulta 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

  1. Toda ruta pide Authorization: Bearer <token>, menos / y /salud.
  2. 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.
  3. Una empresa solo emite con su clave. Nunca puede emitir con la de otra.
  4. Las claves de efacturapty y los tokens viven en empresas.json del servidor, fuera de git y con permisos 600.

2. Empresas y ambientes

EmpresaRUCSucursalPunto
ALQUIMAQ_PANAMA155589097-2-2014 DV 170003001
ALQUIMAQ_CHORRERA155589097-2-2014 DV 170000001
ALQUIMAQ_CORONADO155589097-2-2014 DV 170002001
JDL_RENTALS8-975-1141 DV 210001001
SPEEDCAR155650257-2-2017 DV 990000001
  1. 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.
  2. 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.
  3. En prueba la factura sale con la sucursal de la cuenta de prueba (0000) y punto 001, no con la de la empresa.
  4. En prueba el correo del receptor se reemplaza por el correo de prueba. Una factura de prueba nunca le llega al cliente.
  5. En prueba el total máximo es 5 dólares.
  6. Sin clave del ambiente pedido, la API responde 503 antes de reservar número.

3. Numeración

  1. Producción: una serie por empresa y tipo de documento.
  2. Prueba: una serie por tipo de documento, compartida por todas las empresas. Nunca usa la numeración del sistema (F-…).
  3. La serie de producción arranca en el «Siguiente» de la empresa. Ejemplo: ALQUIMAQ_PANAMA factura 01 arranca en 1718, nota 06 en 457.
  4. La serie salta los números ya autorizados por otro sistema: sueltos o rangos.
  5. La serie nunca retrocede. Dos pedidos a la vez no reciben el mismo número.
  6. Las series viven en ~/efactura-datos, fuera de la carpeta de la app. Desplegar no las reinicia.
  7. Un borrador trae numero solo para reenviar uno rechazado. Sin numero, recibe el siguiente libre.
  8. Un borrador que no pasa las validaciones da 400 y no gasta número.
  9. GET /v1/siguiente dice 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.

  1. Forma: receptor objeto, items y pagos listas, fecha número, numero entero mayor que 0 si viene, cantidades, precios y montos numéricos.
  2. Tipo de documento: solo 01, 06, 04 o 05.
  3. 04 y 05 llevan cufeReferenciado.
  4. Receptor con nombre.
  5. Receptor contribuyente (01) o gobierno (03): lleva RUC y DV.
  6. Receptor extranjero (04): lleva pasaporte o identificación.
  7. País en código de 2 letras (PA, US…).
  8. Correo del receptor, si viene, bien escrito.
  9. Al menos una línea.
  10. Cada línea: descripción, de 160 caracteres o menos.
  11. Cada línea: cantidad mayor que 0.
  12. Cada línea: precio 0 o mayor.
  13. Cada línea: sin descuento. Sage no lo acepta: se baja el precio.
  14. Cada línea: ITBMS solo 00 o 01.
  15. Los pagos cubren el total.
  16. En prueba, total de 5 dólares o menos.

5. Cálculo

  1. Línea: neto = precio × cantidad, redondeado a 2 decimales.
  2. ITBMS total = 7 % de la suma de las líneas gravadas, redondeado a 2 decimales. Igual que Sage.
  3. La diferencia de redondeo entre el ITBMS total y la suma por línea va a la última línea gravada.
  4. Total = neto + ITBMS. Vuelto = pagado − total.
  5. Los totales siempre los calcula la API.

6. JSON enviado al PAC

  1. En PascalCase: DatosGenerales, ListaItems, Totales.
  2. Valores fijos: TipoEmision "01", NaturalezaOperacion "01", TipoOperacion 1, FormatoGeneracionCafe 1, ManeraEntregaCafe 1, EnvioContenedorReceptor 1, ProcesoGeneracionFe 2, TipoTransaccionVenta 1, TipoSucursal 2, UnidadMedidaCodigoInterno "und", Descuento null.
  3. DestinoOperacion: 2 si el receptor es extranjero, si no 1.
  4. InformacionEmisor lleva solo CodigoSucursal. El PAC completa RUC, nombre y dirección desde la cuenta de la clave.
  5. FechaEmision es la hora real de Panamá (-05:00).
  6. TiempoPago: 1 contado, 2 crédito (todo con forma 01), 3 mixto.
  7. El JSON se convierte a texto una sola vez. Ese texto exacto se envía, se reintenta, se devuelve en solicitud y se guarda en la base de datos.

7. Envío y respuesta

  1. 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).
  2. Si los 3 fallan: rechazada con ese número. El sistema lo reenvía con ese número.
  3. Error 4xx del PAC: rechazada con los mensajes del PAC.
  4. 1002 Documento duplicado en prueba: salta al siguiente número solo (hasta 9 veces).
  5. 1002 en producción: rechazada. Ese número ya está emitido. Revísalo en la DGI, no reemitas a ciegas.
  6. La respuesta trae empresa, tipoDocumento, numero, prueba, estado, cufe, protocolo, fechaAutorizacion, qr, mensajes y solicitud.
  7. Cada emisión y anulación queda en facturas.jsonl.

8. Base de datos para Sage

  1. 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.
  2. La tabla facturas_sage se crea sola si no existe.
  3. Una fila por documento: clave única (empresa, tipo_documento, numero).
  4. json_fe es el texto exacto enviado al PAC, no uno rehecho.
  5. fecha_emision y total salen de ese mismo JSON.
  6. Insert con ON DUPLICATE KEY UPDATE id = id: guardar dos veces no duplica ni cambia nada.
  7. Nunca UPDATE ni DELETE.
  8. Si MariaDB falla, la factura sigue autorizada y la fila queda en pendientes-sage.jsonl. Se reintenta con la siguiente factura y al arrancar.
  9. Credenciales en el .env del servidor, fuera de git, permisos 600.
  10. Speechtree entra con su propio usuario: solo SELECT sobre facturas_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

  1. Anular pide cufe y un motivo de 15 caracteres o más, con la clave del ambiente en que se emitió.
  2. El PDF se pide con la clave del ambiente en que se emitió.
  3. 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)
);