Inicio

Documentación del API de comprobantes electrónicos de Facturador Virtual, versión 4.4 de la disposición del Ministerio de Hacienda de Costa Rica.

Quiénes somos

Facturador Virtual es una plataforma costarricense de facturación electrónica. Genera los comprobantes con la estructura que exige el Ministerio de Hacienda, los firma con el certificado del contribuyente, los envía al servicio de recepción y da seguimiento a su comprobación, sin que quien integra tenga que construir el XML ni resolver la firma digital.

El API expone esas mismas capacidades para que un sistema externo —un punto de venta, un comercio electrónico, un ERP— emita comprobantes de forma programática.

En todo comprobante emitido por la plataforma, el campo ProveedorSistema del XML lleva la cédula jurídica 3-101-660528, que identifica a Facturador Virtual como proveedor del sistema ante Hacienda.

Qué encontrará aquí

Esta documentación cubre la emisión de comprobantes electrónicos por API: cómo autenticarse y cómo construir cada tipo de documento, campo por campo, con sus catálogos, reglas de validación y respuestas de error.

Cada página de documento sigue la misma estructura: endpoint, autenticación, ejemplo mínimo funcional, campos obligatorios, opcionales y condicionales, catálogos aplicables, formato de la respuesta y tabla de errores.

Por dónde empezar

1. Obtenga sus credenciales. Necesita un plan con acceso a API activo y el par de tokens que se genera desde el perfil de la cuenta. Empiece por Credenciales de acceso al API.
2. Verifique que funcionan. En esa misma página hay una llamada de solo lectura que confirma las credenciales sin consumir documentos de su plan.
3. Emita su primer documento. Vaya a Factura electrónica y adapte el ejemplo mínimo. Es el documento más común y el que sirve de referencia para los demás.

Si su caso no es una factura ordinaria, la tabla siguiente le indica qué página leer.

Documentos disponibles

Documento	Cuándo se usa	Método y ruta	Tipo
Factura electrónica	Venta a un receptor identificado.	POST /emision/factura	01
Tiquete electrónico	Venta en la que no se identifica al receptor.	POST /emision/tiquete	04
Nota de crédito	Anular o disminuir el monto de un documento ya emitido.	PUT /emision/nota-credito/{clave}	03
Nota de débito	Incrementar el monto de un documento ya emitido.	PUT /emision/nota-debito/{clave}	02
Factura de exportación	Venta a un receptor en el extranjero.	POST /emision/exportacion	09
Factura de compra	Respaldar una compra a quien no puede emitir comprobante electrónico.	POST /emision/compra	08

Todas las rutas cuelgan de https://app.facturadorvirtual.com/api/2.0/documentos-electronicos.

Convenciones comunes

Estas reglas aplican a todos los documentos, y no se repiten en cada página.

Autenticación

Cuatro encabezados en cada petición: api-token, access-token, Content-Type: application/json y Accept: application/json. El último no es opcional; sin él, una petición no autenticada responde con una redirección al formulario de inicio de sesión en vez de un error JSON.

El código HTTP y el código del cuerpo son cosas distintas

Una emisión procesada devuelve HTTP 200 aunque Hacienda no haya recibido el documento. El campo codigo del cuerpo es el que informa del resultado de la recepción: 200 si fue recibido, 500 si no se pudo entregar. En este segundo caso el comprobante queda registrado y el sistema reintenta el envío automáticamente.

{
  "codigo": 200,
  "contenidoXml": "…",
  "contenidoXmlFirmado": "…",
  "documento": {
    "clave": "50622032000070175094601000001010000000006118491223",
    "consecutivo": "00400001010000000006",
    "recepcion": "recibido",
    "comprobacion": "por_comprobar"
  },
  "errores": []
}

contenidoXml y contenidoXmlFirmado vienen codificados en base64 y corresponden al XML antes y después de la firma.

Recepción y comprobación son dos etapas

Que Hacienda reciba el documento no significa que lo apruebe. La comprobación ocurre después, normalmente en uno o dos minutos, y el estado pasa de por_comprobar a aceptado o rechazado. Una integración correcta no asume que un codigo: 200 equivale a un comprobante aceptado.

Errores

HTTP	Significado
302	Falta el encabezado Accept: application/json.
401	Credenciales inválidas.
403	Credenciales correctas, pero el plan no incluye acceso a API o se agotaron los documentos del ciclo.
422	Algún campo no cumple las reglas de validación. El cuerpo indica cuál.
500	Error no controlado durante el procesamiento.

Catálogos compartidos

Condición de venta, medios de pago, impuestos, códigos de tarifa y unidades de medida son los mismos en todos los documentos. Cada página incluye las tablas que le aplican, de modo que no es necesario saltar entre páginas para construir una petición.

Dos detalles que causan la mayoría de los rechazos: el campo tarifa de un impuesto recibe el código de tarifa y no el porcentaje —"08" significa 13 %—, y el campo unidad de una línea debe ser un código del catálogo de unidades de Hacienda, como Unid o Kg, no un texto libre.

Soporte

Para consultas sobre la integración, escriba a soporte@facturadorvirtual.com. Si su consulta es sobre un comprobante concreto, incluya la clave de 50 dígitos: es el identificador que permite rastrearlo tanto en la plataforma como ante Hacienda.