# Factura electrónica de exportación

<p class="callout info">**Endpoint**  
*POST* /api/2.0/documentos-electronicos/emision/exportacion</p>

Crea y envía a Hacienda una factura electrónica de exportación con la disposición 4.4. Es el comprobante para ventas a receptores en el extranjero, y se distingue de la factura ordinaria en tres puntos: el receptor es opcional y se identifica como extranjero, cada línea de mercancía puede declarar su partida arancelaria, y normalmente se emite en moneda extranjera.

## Autenticación

Todas las peticiones requieren los cuatro encabezados siguientes.

<table id="bkmrk-encabezadodescripci%C3%B3"><thead><tr><th>Encabezado</th><th>Descripción</th></tr></thead><tbody><tr><td>`api-token`</td><td>Token de API de la cuenta.</td></tr><tr><td>`access-token`</td><td>Token de acceso asociado al `api-token`.</td></tr><tr><td>`Content-Type`</td><td>`application/json`</td></tr><tr><td>`Accept`</td><td>`application/json`. **Obligatorio.** Si se omite, una petición no autenticada responde con una redirección al formulario de inicio de sesión en lugar de un error JSON.</td></tr></tbody></table>

La emisión por API requiere un plan con acceso a API activo y documentos disponibles en el ciclo vigente.

## Ejemplo mínimo

```shell
curl --location 'https://app.facturadorvirtual.com/api/2.0/documentos-electronicos/emision/exportacion' \
--header 'api-token: iuJPbVCYQY3AmWuVHMflT9ZySlwzxb9ehviLbHNsz6yQnBm4' \
--header 'access-token: IDq4ME4ZUO9YmQ0fOc43AFp7mMO6talIuIALFaUUcs2H2pwLpYN2' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "actividad": "014002",
    "condicion_venta": "01",
    "moneda": "USD",
    "tipo_cambio": 512.45,
    "medio_pago": {
        "04": {
            "codigo": "04",
            "total": 1000
        }
    },
    "incliuir_receptor": 1,
    "tipo_cedula": "05",
    "cedula": "US-8891234",
    "nombre": "Costa Rica Coffee Imports LLC",
    "correo": "purchasing@crcoffee.example",
    "comentarios": "Exportación de prueba por medio del API",
    "lineas": [
        {
            "codigo": "00001",
            "codigoCabys": "0161010100000",
            "descripcion": "Café oro en sacos de 69 kg",
            "cantidad": "10",
            "unidad": "Kg",
            "partidaArancelaria": "090111000000",
            "descuento": 0,
            "naturalezaDescuento": "",
            "precioUnitario": 100,
            "impuestos": {
                "01": {
                    "tarifa": "01"
                }
            }
        }
    ]
}'
```

## Campos del documento

### Obligatorios

<table id="bkmrk-campotipodescripci%C3%B3n"><thead><tr><th>Campo</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>`actividad`</td><td>string</td><td>Código de la actividad económica del emisor. Debe estar registrada en la cuenta.</td></tr><tr><td>`condicion_venta`</td><td>string</td><td>Código de condición de venta. Ver la tabla más abajo.</td></tr><tr><td>`moneda`</td><td>string</td><td>Código de moneda. En una exportación es habitual `USD` o `EUR`.</td></tr><tr><td>`medio_pago`</td><td>object</td><td>De 1 a 4 medios de pago. Ver la tabla más abajo. Se ignora cuando la condición de venta es a crédito.</td></tr><tr><td>`lineas`</td><td>array</td><td>Al menos una línea de detalle. Ver la sección correspondiente.</td></tr></tbody></table>

### Opcionales

<table id="bkmrk-campotipodescripci%C3%B3n-1"><thead><tr><th>Campo</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>`tipo_cambio`</td><td>number</td><td>Tipo de cambio respecto al colón, mayor que cero. Si se omite se asume `1`; cuando `moneda` es `USD` y no se envía, el sistema aplica automáticamente el tipo de cambio de referencia del día. Para otras monedas debe enviarse explícitamente.</td></tr><tr><td>`sucursal`</td><td>string</td><td>Código de sucursal, por ejemplo `004`. Si se omite, se usa el valor configurado en las preferencias de facturación.</td></tr><tr><td>`punto`</td><td>string</td><td>Punto de emisión, por ejemplo `00001`. Si se omite, se usa el valor configurado en las preferencias de facturación.</td></tr><tr><td>`nombre_comercial`</td><td>string</td><td>Nombre comercial del receptor, entre 3 y 80 caracteres.</td></tr><tr><td>`codigo_actividad_receptor`</td><td>string</td><td>Código de actividad económica del receptor.</td></tr><tr><td>`comentarios`</td><td>string</td><td>Notas del comprobante. Si el texto contiene un patrón `#codigo`, ese valor se registra además como número de orden.</td></tr><tr><td>`orden`</td><td>string u object</td><td>Número de orden asociado. Acepta un string con el código, o un objeto `{"codigo": "...", "estado": "...", "proveedor": "..."}`.</td></tr><tr><td>`devolucion`</td><td>number</td><td>Monto de devolución de IVA, mayor que cero.</td></tr><tr><td>`cargos`</td><td>array</td><td>Otros cargos del comprobante. Ver la sección correspondiente.</td></tr></tbody></table>

### Campos condicionales

<table id="bkmrk-campose-vuelve-oblig"><thead><tr><th>Campo</th><th>Se vuelve obligatorio cuando…</th><th>Reglas</th></tr></thead><tbody><tr><td>`plazo_credito`</td><td>`condicion_venta` es `02` o `10`</td><td>Entero entre 1 y 99999, expresado en días.</td></tr><tr><td>`condicion_venta_otros`</td><td>`condicion_venta` es `99`</td><td>Texto entre 5 y 100 caracteres.</td></tr><tr><td>`medio_pago.<codigo>.detalle`</td><td>El código del medio de pago es `99`</td><td>Texto entre 3 y 100 caracteres.</td></tr><tr><td>`cedula`, `nombre`, `correo`</td><td>Se envía `incliuir_receptor`</td><td>Ver la sección «Receptor».</td></tr></tbody></table>

## Receptor

En la factura de exportación el receptor es opcional. Para incluirlo se envía el indicador `incliuir_receptor` junto con los datos del cliente:

```json
"incliuir_receptor": 1,
"tipo_cedula": "05",
"cedula": "US-8891234",
"nombre": "Costa Rica Coffee Imports LLC",
"correo": "purchasing@crcoffee.example",
"telefono": "18005550123",
"nombre_comercial": "CR Coffee"
```

<p class="callout warning">El indicador se llama `incliuir_receptor`, con esa grafía exacta. Es el nombre del campo tal como lo espera el sistema en todas sus interfaces; escrito de otra forma, el indicador no se reconoce y los datos del receptor dejan de ser obligatorios.</p>

Al enviar `incliuir_receptor`, los campos `cedula`, `nombre` y `correo` pasan a ser obligatorios. Si se omite el indicador, esos campos siguen aceptándose y se incorporan al comprobante, pero no se exige ninguno; omitiéndolos todos, el documento se emite sin receptor identificado.

<table id="bkmrk-campodescripci%C3%B3n-inc"><thead><tr><th>Campo</th><th>Descripción</th></tr></thead><tbody><tr><td>`incliuir_receptor`</td><td>Indicador de inclusión del receptor. Envíe `1`.</td></tr><tr><td>`tipo_cedula`</td><td>Tipo de identificación. Para un receptor en el extranjero corresponde `05`, extranjero no domiciliado. El valor `99` se acepta y se normaliza a `05`.</td></tr><tr><td>`cedula`</td><td>Identificación del receptor, máximo 20 caracteres. En receptores extranjeros se conserva tal cual, sin eliminar guiones.</td></tr><tr><td>`nombre`</td><td>Nombre del receptor, máximo 80 caracteres.</td></tr><tr><td>`correo`</td><td>Correo electrónico del receptor. Debe ser una dirección válida; a él se envía el comprobante.</td></tr><tr><td>`telefono`</td><td>Teléfono del receptor. Opcional. Se conservan únicamente los dígitos.</td></tr><tr><td>`nombre_comercial`</td><td>Nombre comercial del receptor, entre 3 y 80 caracteres.</td></tr></tbody></table>

## Condición de venta

<table id="bkmrk-c%C3%B3digodescripci%C3%B3n-01"><thead><tr><th>Código</th><th>Descripción</th></tr></thead><tbody><tr><td>`01`</td><td>Contado</td></tr><tr><td>`02`</td><td>Crédito</td></tr><tr><td>`03`</td><td>Consignación</td></tr><tr><td>`04`</td><td>Apartado</td></tr><tr><td>`05`</td><td>Arrendamiento con opción de compra</td></tr><tr><td>`06`</td><td>Arrendamiento en función financiera</td></tr><tr><td>`07`</td><td>Cobro a favor de un tercero</td></tr><tr><td>`08`</td><td>Servicios prestados al Estado</td></tr><tr><td>`09`</td><td>Pago de servicios prestados al Estado</td></tr><tr><td>`10`</td><td>Venta a crédito en IVA hasta 90 días</td></tr><tr><td>`11`</td><td>Pago de venta a crédito en IVA hasta 90 días</td></tr><tr><td>`12`</td><td>Venta de mercancía no nacionalizada</td></tr><tr><td>`13`</td><td>Venta de bienes usados no contribuyente</td></tr><tr><td>`14`</td><td>Arrendamiento operativo</td></tr><tr><td>`15`</td><td>Arrendamiento financiero</td></tr><tr><td>`99`</td><td>Otros. Requiere `condicion_venta_otros`.</td></tr></tbody></table>

<p class="callout warning">Con las condiciones de venta `02`, `08` y `10` el comprobante se emite a crédito y **los medios de pago enviados se descartan**: el XML no incluye el nodo de medio de pago. Aun así el campo `medio_pago` debe venir presente en la petición.</p>

## Medios de pago

`medio_pago` es un objeto con hasta cuatro entradas, donde la clave y el campo `codigo` coinciden. `total` es el monto cubierto por ese medio y debe ser mayor que cero.

```json
"medio_pago": {
    "04": { "codigo": "04", "total": 1000 }
}
```

<table id="bkmrk-c%C3%B3digodescripci%C3%B3n-01-1"><thead><tr><th>Código</th><th>Descripción</th></tr></thead><tbody><tr><td>`01`</td><td>Efectivo</td></tr><tr><td>`02`</td><td>Tarjeta</td></tr><tr><td>`03`</td><td>Cheque</td></tr><tr><td>`04`</td><td>Transferencia o depósito bancario</td></tr><tr><td>`05`</td><td>Recaudado por terceros</td></tr><tr><td>`06`</td><td>SINPE Móvil</td></tr><tr><td>`07`</td><td>Plataforma digital</td></tr><tr><td>`99`</td><td>Otros. Requiere `detalle`.</td></tr></tbody></table>

## Líneas de detalle

### Campos obligatorios de la línea

<table id="bkmrk-campotipodescripci%C3%B3n-2"><thead><tr><th>Campo</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>`codigo`</td><td>string</td><td>Código del producto o servicio, máximo 20 caracteres.</td></tr><tr><td>`descripcion`</td><td>string</td><td>Detalle de la línea, entre 3 y 200 caracteres.</td></tr><tr><td>`cantidad`</td><td>number</td><td>Cantidad, mayor que cero. Se redondea a 3 decimales.</td></tr><tr><td>`unidad`</td><td>string</td><td>Código de unidad de medida del catálogo de Hacienda. Debe coincidir exactamente con un código del catálogo, por ejemplo `Unid`, `Kg`, `L`, `Sp`, `Os`. La categoría del código determina si la línea se registra como mercancía o como servicio.</td></tr><tr><td>`precioUnitario`</td><td>number</td><td>Precio unitario, mayor o igual a cero.</td></tr><tr><td>`descuento`</td><td>number</td><td>Monto del descuento. Envíe `0` si no aplica.</td></tr><tr><td>`naturalezaDescuento`</td><td>string</td><td>Naturaleza del descuento. Envíe cadena vacía si no aplica; si se envía texto, debe tener entre 3 y 80 caracteres.</td></tr></tbody></table>

<p class="callout danger">`codigoCabys` no es rechazado por la validación, pero Hacienda exige el código CABYS en todos los comprobantes. Omitirlo produce un rechazo del lado de Hacienda, no del API.</p>

### Campos opcionales de la línea

<table id="bkmrk-campotipodescripci%C3%B3n-3"><thead><tr><th>Campo</th><th>Tipo</th><th>Descripción</th></tr></thead><tbody><tr><td>`codigoCabys`</td><td>string</td><td>Código CABYS de 13 dígitos.</td></tr><tr><td>`partidaArancelaria`</td><td>string</td><td>Partida arancelaria de la mercancía. Si se envía, debe tener **exactamente 12 caracteres**. Es el campo propio de la factura de exportación.</td></tr><tr><td>`codigoInternoFV`</td><td>string</td><td>Código del producto en el catálogo de Facturador Virtual.</td></tr><tr><td>`id_producto`</td><td>integer</td><td>Identificador del producto en Facturador Virtual.</td></tr><tr><td>`unidadMedidaComercial`</td><td>string</td><td>Unidad de medida comercial, máximo 20 caracteres.</td></tr><tr><td>`tipoTransaccion`</td><td>string</td><td>Código de tipo de transacción de la versión 4.4.</td></tr><tr><td>`tipoDescuento`</td><td>string</td><td>Código del tipo de descuento, máximo 2 caracteres. Si se omite se asume `08`. Con los códigos `01` y `03` el impuesto de la línea se registra como asumido por el emisor.</td></tr><tr><td>`tipoDescuentoOtro`</td><td>string</td><td>Descripción cuando `tipoDescuento` corresponde a «otros». Entre 5 y 100 caracteres.</td></tr><tr><td>`ivaCobradoFabrica`</td><td>number</td><td>IVA cobrado en fábrica.</td></tr><tr><td>`vinSerie`</td><td>string</td><td>Número VIN o serie, para vehículos.</td></tr><tr><td>`esCabysMedicamento`</td><td>boolean</td><td>Marca la línea como medicamento. Al activarse se toman `registroMedicamento` (máximo 100 caracteres) y `formaFarmaceutica` (3 caracteres).</td></tr><tr><td>`es_combo`</td><td>boolean</td><td>Marca la línea como combo. Los componentes se envían en `componentes`, un arreglo con la misma estructura de una línea de detalle.</td></tr><tr><td>`impuestos`</td><td>object</td><td>Impuestos aplicados a la línea. Ver la siguiente sección.</td></tr></tbody></table>

## Impuestos

`impuestos` es un objeto cuya clave es el código del impuesto. El campo `tarifa` recibe el **código de tarifa**, no el porcentaje: el porcentaje se resuelve a partir de ese código. En una exportación lo habitual es aplicar una tarifa de 0 %.

```json
"impuestos": {
    "01": {
        "tarifa": "01"
    }
}
```

<table id="bkmrk-c%C3%B3digo-de-impuestode"><thead><tr><th>Código de impuesto</th><th>Descripción</th></tr></thead><tbody><tr><td>`01`</td><td>Impuesto al Valor Agregado</td></tr><tr><td>`02`</td><td>Impuesto Selectivo de Consumo</td></tr><tr><td>`03`</td><td>Impuesto Único a los Combustibles</td></tr><tr><td>`04`</td><td>Impuesto específico de Bebidas Alcohólicas</td></tr><tr><td>`05`</td><td>Impuesto Específico sobre las bebidas envasadas sin contenido alcohólico y jabones de tocador</td></tr><tr><td>`06`</td><td>Impuesto a los Productos de Tabaco</td></tr><tr><td>`07`</td><td>IVA (cálculo especial)</td></tr><tr><td>`08`</td><td>IVA Régimen de Bienes Usados (Factor)</td></tr><tr><td>`12`</td><td>Impuesto Específico al Cemento</td></tr><tr><td>`99`</td><td>Otros. Se describe en `descripcionOtro`.</td></tr></tbody></table>

<table id="bkmrk-c%C3%B3digo-de-tarifadesc"><thead><tr><th>Código de tarifa</th><th>Descripción</th><th>Porcentaje aplicado</th></tr></thead><tbody><tr><td>`01`</td><td>Tarifa 0% (Artículo 32, num 1, RLIVA)</td><td>0</td></tr><tr><td>`02`</td><td>Tarifa reducida 1%</td><td>1</td></tr><tr><td>`03`</td><td>Tarifa reducida 2%</td><td>2</td></tr><tr><td>`04`</td><td>Tarifa reducida 4%</td><td>4</td></tr><tr><td>`05`</td><td>Transitorio 0%</td><td>0</td></tr><tr><td>`06`</td><td>Transitorio 4%</td><td>4</td></tr><tr><td>`07`</td><td>Tarifa transitoria 8%</td><td>8</td></tr><tr><td>`08`</td><td>Tarifa general 13%</td><td>13</td></tr><tr><td>`09`</td><td>Tarifa reducida 0.5%</td><td>0.5</td></tr><tr><td>`10`</td><td>Tarifa exenta</td><td>0</td></tr><tr><td>`11`</td><td>Tarifa 0% sin derecho a crédito</td><td>0</td></tr></tbody></table>

Para el impuesto `08` se envía además `factor`. Para los impuestos `03`, `04`, `05` y `06` pueden enviarse los datos específicos `cantidadUnidadMedida`, `porcentaje`, `proporcion`, `volumenUnidadConsumo` e `impuestoUnidad`. La exoneración se declara dentro del impuesto `01` con los campos `exoneracionTipo`, `exoneracionNumero`, `exoneracionInstitucion`, `exoneracionFecha` en formato `dd/mm/aaaa` y `exoneracionTarifa`.

## Otros cargos

```json
"cargos": [
    {
        "tipo": "04",
        "detalle": "Flete internacional",
        "monto": 150,
        "tipoIdentidadTercero": "01",
        "numeroIdentidadTercero": "701750946",
        "nombreTercero": "Naviera S.A.",
        "porcentajeTercero": 10
    }
]
```

Los campos `tipo`, `detalle` y `monto` aplican a todos los cargos. Los cuatro campos de tercero solo se envían cuando `tipo` es `04`.

## Respuesta

Una emisión procesada devuelve **HTTP 200**. El campo `codigo` del cuerpo indica el resultado de la recepción en Hacienda y es independiente del código HTTP.

```json
{
  "codigo": 200,
  "contenidoXml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iV…",
  "contenidoXmlFirmado": "Nfdsfffadeec2lvbj0iMS4wIiBlbmNvZGluZz0iV…",
  "documento": {
    "clave": "50622032000070175094600400001090000000008118491223",
    "consecutivo": "00400001090000000008",
    "recepcion": "recibido",
    "comprobacion": "por_comprobar"
  },
  "errores": []
}
```

El tipo de documento `09` dentro del consecutivo identifica la factura de exportación.

<table id="bkmrk-campodescripci%C3%B3n-cod"><thead><tr><th>Campo</th><th>Descripción</th></tr></thead><tbody><tr><td>`codigo`</td><td>Resultado de la recepción en Hacienda. `200` si el documento fue recibido; `500` si no se pudo entregar.</td></tr><tr><td>`contenidoXml`</td><td>XML generado, codificado en `base64`.</td></tr><tr><td>`contenidoXmlFirmado`</td><td>XML firmado, codificado en `base64`. Es `null` cuando la firma o el envío no se completaron.</td></tr><tr><td>`documento.clave`</td><td>Clave numérica de 50 dígitos del comprobante.</td></tr><tr><td>`documento.consecutivo`</td><td>Consecutivo de 20 dígitos del comprobante.</td></tr><tr><td>`documento.recepcion`</td><td>Estado de la recepción: `recibido` o `por_enviar`.</td></tr><tr><td>`documento.comprobacion`</td><td>Estado de la comprobación: `por_comprobar`, `aceptado` o `rechazado`.</td></tr><tr><td>`errores`</td><td>Arreglo de objetos `{"tipo": "...", "mensaje": "..."}` devueltos por Hacienda.</td></tr></tbody></table>

## Errores

<table id="bkmrk-httpcuerpocausa-302r"><thead><tr><th>HTTP</th><th>Cuerpo</th><th>Causa</th></tr></thead><tbody><tr><td>302</td><td>Redirección al inicio de sesión</td><td>Falta el encabezado `Accept: application/json` en una petición no autenticada.</td></tr><tr><td>401</td><td>`{"message": "Unauthenticated."}`</td><td>`api-token` o `access-token` inválidos o ausentes.</td></tr><tr><td>403</td><td>`{"error": "No posee un Plan Api activo"}`</td><td>El plan de la cuenta no incluye acceso a API.</td></tr><tr><td>403</td><td>`{"error": "Ha llegado al límite de facturas del Plan Api contratado"}`</td><td>Se agotaron los documentos del ciclo vigente.</td></tr><tr><td>422</td><td>`{"errors": {"campo": ["mensaje"]}}`</td><td>Uno o más campos no cumplen las reglas de validación. Una causa frecuente es una `partidaArancelaria` que no tiene exactamente 12 caracteres.</td></tr><tr><td>500</td><td>`{"0": "Ha ocurrido un error", "error": "...", "stack": [...]}`</td><td>Error no controlado durante el procesamiento.</td></tr></tbody></table>

<p class="callout warning">Existe además un caso en el que la respuesta es **HTTP 200** con `"codigo": 500`, `"documento": null` y `"errores": []`. Ocurre cuando el comprobante no llegó a construirse; la causa más frecuente es un código de `unidad` que no existe en el catálogo de unidades de medida. Verifique ese campo antes de reintentar.</p>

## Comprobación

La recepción es el primer paso: significa que Hacienda recibió el documento, no que lo aprobó. La comprobación se realiza automáticamente, por lo general en uno o dos minutos, y el estado pasa de `por_comprobar` a `aceptado` o `rechazado`.