API de facturación electrónica en Panamá

En Panamá no puedes emitir una factura electrónica válida sin que el SFEP (el sistema de la DGI) la autorice primero. Es un modelo de pre-clearance: tu sistema manda el documento, el gobierno lo valida, y solo entonces existe fiscalmente.

El problema es que la DGI no expone una API pública. Toda la comunicación pasa por intermediarios llamados PACs (Proveedores Autorizados de Comprobantes). Y cada PAC tiene su propia API, su propio formato, su propia documentación.

G-Force Gateway simplifica esto. Es un middleware que recibe JSON, lo convierte a XML firmado y lo enruta al PAC que elijas. Tú nunca tocas XML ni firmas criptográficas. Conteo mantiene la documentación completa de la API en docs.conteo.me.

La cadena completa:

Tu sistema (JSON) → G-Force Gateway → PAC → SFEP (DGI) → autorizacion
                                                                ↓
Tu sistema ← { cufe, nroAuthorizationProtocol, qr } ←─────────┘
                  ↓
Tu sistema → DownloadPDF → G-Force Gateway → CAFE (PDF en Base64)

Autenticación

Cada petición al Gateway lleva tres capas de credenciales. No es complicado, pero sí es distinto a lo que la mayoría de APIs hacen.

Capa 1: JWT en el header. Un token que G-Force te da cuando te registras como plataforma. Va en el header Authorization. Lo guardas como variable de entorno (GFORCE_JWT).

Capa 2: credenciales de plataforma. Identifican tu aplicación ante G-Force. Son tres campos (GF_Company, GF_Token, Enterprise) que van en el body de cada request. Un solo juego para toda tu app, guardados como variables de entorno.

Capa 3: credenciales del PAC. Identifican al contribuyente específico. Son tres campos más (Company, Token, Id_Pac) que también van en el body. Cada negocio que factura tiene las suyas, emitidas por el PAC durante la afiliación.

Así se ve la estructura base de cualquier request:

curl -X POST \
https://gateway-eb-develop.gforceint.com/api/v1/GFGatewayEB/{METODO} \
-H "Authorization: $GFORCE_JWT" \
-H "Content-Type: application/json" \
-d '{
  "GF_Company": "tu_usuario_gforce",
  "GF_Token": "tu_contraseña_gforce",
  "Enterprise": "tu_codigo_empresa",
  "Id_Pac": "EBI",
  "Company": "usuario_contribuyente",
  "Token": "contraseña_contribuyente"
}'

La guía de autenticación tiene los detalles de cada campo y credenciales de desarrollo para pruebas.

Emitir una factura

El endpoint SendDocument es el núcleo de todo. Le pasas los datos del emisor, receptor y los items con sus tasas de ITBMS, y G-Force se encarga de armar el XML, firmarlo con el certificado del contribuyente y enviarlo al PAC.

curl -X POST \
https://gateway-eb-develop.gforceint.com/api/v1/GFGatewayEB/SendDocument \
-H "Authorization: $GFORCE_JWT" \
-H "Content-Type: application/json" \
-d '{
  "GF_Company": "tu_usuario_gforce",
  "GF_Token": "tu_contraseña_gforce",
  "Id_Pac": "EBI",
  "Enterprise": "tu_codigo_empresa",
  "Company": "usuario_pac_contribuyente",
  "Token": "contraseña_pac_contribuyente",
  "identifierControlShipping": "orden-001",
  "environment": "2",
  "document": {
    "codeBranchIssuer": "0000",
    "dataTransaction": {
      "typeEmission": "01",
      "typeDocument": "01",
      "numberDocumentFiscal": "0000000001",
      "pointBillingFiscal": "001",
      "dateBroadcast": "2026-04-13T10:00:00-05:00",
      "natureOperation": "01",
      "typeOperation": "1",
      "destinationOperation": "1",
      "formatCAFE": "3",
      "deliveryCAFE": "3",
      "shippingContainer": "1",
      "processGeneration": "1",
      "typeSale": "1",
      "client": {
        "typeClientEB": "02",
        "typeTaxpayer": "1",
        "numberRUC": "8-730-241",
        "digitCheckRUC": "59",
        "businessName": "Farmacia Central, S.A.",
        "address": "Calle 50, Ciudad de Panama",
        "codeLocation": "1-1-1",
        "province": "Panama",
        "district": "Panama",
        "correction": "San Francisco",
        "country": "PA"
      }
    },
    "listItems": [{
      "description": "Servicio de mantenimiento",
      "code": "SRV-001",
      "amount": "1.00",
      "priceUnit": "150.00",
      "priceUnitDiscount": "0.00",
      "priceItem": "150.00",
      "rateITBMS": "01",
      "valueITBMS": "10.50",
      "totalValue": "160.50",
      "codeGTIN": "0",
      "cantGTINCom": "1.00",
      "codeGTINInv": "0",
      "cantGTINComInv": "1.00"
    }],
    "totalsSubTotals": {
      "totalPriceNet": "150.00",
      "totalITBMS": "10.50",
      "totalISC": "",
      "totalAmountTaxed": "10.50",
      "totalInvoice": "160.50",
      "totalValueReceived": "160.50",
      "timePayment": "1",
      "nroItems": "1",
      "totalAllItems": "160.50",
      "listFormPayment": [{
        "formPaymentInvoice": "02",
        "valueFeePaid": "160.50"
      }]
    }
  }
}'

Si la DGI autoriza el documento, la respuesta viene con el cufe (identificador único de la factura), el qr (URL de verificación) y el nroAuthorizationProtocol:

{
  "code": "200",
  "result": "procesado",
  "message": "El documento se envio correctamente.",
  "cufe": "FE0120000249610000000001...",
  "qr": "https://dgi-fep.mef.gob.pa/Consultas/FacturasPorQR?chFE=...",
  "receptionDateDGI": "2026-04-13T10:00:06-05:00",
  "nroAuthorizationProtocol": "1234567890123"
}

Guarda cufe y nroAuthorizationProtocol en tu base de datos. Los vas a necesitar para descargar el CAFE, emitir notas de crédito y consultar el estado del documento.

El campo identifierControlShipping funciona como ID de idempotencia. Si mandas el mismo request con el mismo ID (por ejemplo después de un timeout), G-Force no duplica el documento. Usa el ID de tu orden interna.

La referencia completa de SendDocument con todos los campos está en docs.conteo.me.

Descargar el CAFE

El CAFE (Comprobante Auxiliar de Factura Electrónica) es el PDF oficial que le entregas a tu cliente. No lo generas tú, lo genera el PAC después de que la DGI autoriza la factura. Lo descargas con DownloadPDF usando los identificadores del documento.

curl -X POST \
https://gateway-eb-develop.gforceint.com/api/v1/GFGatewayEB/DownloadPDF \
-H "Authorization: $GFORCE_JWT" \
-H "Content-Type: application/json" \
-d '{
  "GF_Company": "tu_usuario_gforce",
  "GF_Token": "tu_contraseña_gforce",
  "Id_Pac": "EBI",
  "Enterprise": "tu_codigo_empresa",
  "Company": "usuario_pac_contribuyente",
  "Token": "contraseña_pac_contribuyente",
  "Branch": "",
  "invoiceId": "",
  "documentData": {
    "codeBranchIssuing": "0000",
    "numberDocumentFiscal": "0000000001",
    "pointBillingFiscal": "001",
    "serialDevice": "",
    "typeDocument": "01",
    "typeEmission": "01"
  }
}'

La respuesta trae el PDF en Base64 dentro del campo document. Decodifícalo, guárdalo y sírvelo a tu cliente. Este PDF incluye el QR verificable, los datos fiscales y el número de autorización. Es el único comprobante legalmente válido.

Referencia completa: DownloadPDF.

Qué más puedes hacer

Además de emitir y descargar, la API tiene endpoints para cubrir todo el ciclo de vida de una factura:

Consultar estado con StatusDocument. Si un request falla por timeout y no sabes si la factura se emitió o no, consúltalo. Pasas los mismos documentData que usaste para emitir y te devuelve el estado actual (Autorizada, Rechazada, etc.).

Anular una factura con CancellationDocument. En Panamá no puedes editar una factura ya emitida. Si hay un error, la anulas y emites una nueva. La anulación pasa por el PAC y queda registrada en el SFEP.

Validar un RUC con ConsultRucDV. Antes de emitir una factura, puedes verificar si el RUC del receptor existe en la DGI y obtener su dígito verificador. Útil para validar en tiempo real cuando el usuario introduce el RUC en tu formulario.

Listar facturas con ListInvoices y ver el detalle de una específica con GetDetailInvoice. Filtras por fecha, RUC, número de documento o CUFE.

Enviar el CAFE por correo con SendMail. El Gateway envía el PDF directamente al correo del cliente. Puedes rastrear si lo abrió con MailTracking.

Consultar folios disponibles con RemainingPages. Cada PAC tiene un sistema de folios. Si se te acaban, las facturas dejan de emitirse.

Entornos

Hay dos URLs base. El campo environment en el body del request también tiene que coincidir.

ITBMS y códigos de referencia

El SFEP valida las tasas de impuesto y los códigos de documento. Si mandas un código incorrecto, la factura se rechaza. Los que más vas a usar:

Tipos de documento, métodos de pago, tipos de cliente y todos los demás códigos están en la referencia Panamá.

Manejo de errores

Cuando algo falla, la respuesta trae un code distinto de "200" y un message legible. Los errores más comunes:

La guía de errores lista todos los códigos con las acciones recomendadas.

Preguntas frecuentes