# Inicio

<p class="callout info">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.</p>

## 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](https://docs.facturadorvirtual.com/books/api-fe-44/page/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](https://docs.facturadorvirtual.com/books/api-fe-44/page/factura-electronica) 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

<table id="bkmrk-documentocu%C3%A1ndo-se-u"><thead><tr><th>Documento</th><th>Cuándo se usa</th><th>Método y ruta</th><th>Tipo</th></tr></thead><tbody><tr><td>[Factura electrónica](https://docs.facturadorvirtual.com/books/api-fe-44/page/factura-electronica)</td><td>Venta a un receptor identificado.</td><td>`POST` `/emision/factura`</td><td>`01`</td></tr><tr><td>[Tiquete electrónico](https://docs.facturadorvirtual.com/books/api-fe-44/page/tiquete-electronico)</td><td>Venta en la que no se identifica al receptor.</td><td>`POST` `/emision/tiquete`</td><td>`04`</td></tr><tr><td>[Nota de crédito](https://docs.facturadorvirtual.com/books/api-fe-44/page/nota-de-credito-electronica)</td><td>Anular o disminuir el monto de un documento ya emitido.</td><td>`PUT` `/emision/nota-credito/{clave}`</td><td>`03`</td></tr><tr><td>[Nota de débito](https://docs.facturadorvirtual.com/books/api-fe-44/page/nota-de-debito-electronica)</td><td>Incrementar el monto de un documento ya emitido.</td><td>`PUT` `/emision/nota-debito/{clave}`</td><td>`02`</td></tr><tr><td>[Factura de exportación](https://docs.facturadorvirtual.com/books/api-fe-44/page/factura-electronica-de-exportacion)</td><td>Venta a un receptor en el extranjero.</td><td>`POST` `/emision/exportacion`</td><td>`09`</td></tr><tr><td>[Factura de compra](https://docs.facturadorvirtual.com/books/api-fe-44/page/factura-electronica-de-compra)</td><td>Respaldar una compra a quien no puede emitir comprobante electrónico.</td><td>`POST` `/emision/compra`</td><td>`08`</td></tr></tbody></table>

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.

```json
{
  "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

<table id="bkmrk-httpsignificado-302f"><thead><tr><th>HTTP</th><th>Significado</th></tr></thead><tbody><tr><td>302</td><td>Falta el encabezado `Accept: application/json`.</td></tr><tr><td>401</td><td>Credenciales inválidas.</td></tr><tr><td>403</td><td>Credenciales correctas, pero el plan no incluye acceso a API o se agotaron los documentos del ciclo.</td></tr><tr><td>422</td><td>Algún campo no cumple las reglas de validación. El cuerpo indica cuál.</td></tr><tr><td>500</td><td>Error no controlado durante el procesamiento.</td></tr></tbody></table>

### 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.

<p class="callout warning">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.</p>

## 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.