API de facturación electrónica de Costa Rica

La parte difícil de la facturación electrónica en Costa Rica no es la venta: es el XML v4.4, la firma digital, los consecutivos, el envío a Hacienda y el manejo de rechazos. La API se ocupa de todo eso para que tu ERP, POS o e-commerce solo tenga que declarar qué se vendió.

• Endpoints para los 6 tipos de comprobante electrónico
• Generación del XML v4.4 con todos los campos que exige Hacienda
• Firma XAdES con tu certificado .p12 (nosotros la aplicamos)
• Envío a Hacienda y consulta automática del estado (aceptado/rechazado)
• Correo al receptor con el PDF y los XML, como exige la normativa
• Búsqueda de códigos CABYS y gestión de emisores, sucursales y cajas

Un POST a /api/procesar con el tipo_documento y los datos de la venta. La respuesta es HTTP 202: recibís la clave numérica de 50 dígitos y el consecutivo al instante, mientras la firma y el envío a Hacienda ocurren en background. El resultado final (aceptado/rechazado) se consulta después.

const res = await fetch('https://api.plaxp.com/api/procesar', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.PLAXP_API_KEY,
  },
  body: JSON.stringify({
    tipo_documento: '01',          // 01=FE · 04=Tiquete · 03=NC · 02=ND
    codigo_sucursal: '001',
    codigo_caja: '001',
    consecutivo: 1,
    condicion_venta: '01',         // 01 = contado
    medios_pago: [{ tipo: '01', monto: 56500 }],
    receptor: {
      tipo_identificacion: '01',   // 01 = cédula física
      identificacion: '123456789',
      nombre: 'Juan Pérez',
      correo: '[email protected]',
    },
    lineas: [{
      codigo_cabys: '8399000000000',
      detalle: 'Servicio profesional',
      cantidad: 1,
      precio_unitario: 50000,
      codigo_tarifa: '08',         // 08 = IVA 13%
      tarifa: 13,
    }],
  }),
});

const doc = await res.json();
// 202 → { success, mensaje, data: { clave, consecutivo } }
// La firma y el envío a Hacienda ocurren en background.

Los seis comprobantes electrónicos de la versión 4.4. Cambiás el campo tipo_documento:

Dos opciones. La más simple: tu API Key en el header X-API-Key (cada emisor tiene la suya; nunca la expongas en el frontend).

X-API-Key: sk_live_tu_clave_secreta

Para integraciones de producción recomendamos OAuth (JWT): pedís un token con tu client_id y client_secret y lo mandás como Bearer. El token dura 15 minutos y se renueva con un refresh_token (7 días).

curl -X POST 'https://api.plaxp.com/auth/token' \
  -H 'Content-Type: application/json' \
  -d '{ "client_id": "tu_client_id", "client_secret": "tu_secret" }'
# → { access_token, refresh_token, token_type: "Bearer", expires_in: 900 }

# luego, en cada emisión:
#   Authorization: Bearer <access_token>

Hacienda no responde aceptado al instante: valida de forma asíncrona. Al emitir recibís la clave. Del lado de Plaxp nosotros consultamos a Hacienda por vos (con reintentos y backoff) hasta que responde; vos solo leés el estado final por la clave — sin implementar polling contra Hacienda:

curl 'https://api.plaxp.com/api/consultar/<clave-de-50-digitos>' \
  -H "X-API-Key: $PLAXP_API_KEY"
# → { estado_hacienda: "aceptado" | "rechazado" | "procesando",
#     mensaje_hacienda, respuesta_xml_hacienda }

También hay una consulta pública por clave, sin autenticación, con los datos reducidos del comprobante.

Hacienda tiene un ambiente de pruebas (staging). Te damos credenciales de sandbox para que integres y valides el flujo completo sin generar comprobantes reales. La guía paso a paso está acá: credenciales de prueba de Hacienda (TRIBU-CR). Y si querés entender la firma: firma XAdES-EPES y certificado .p12.