> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cucu.bo/llms.txt
> Use this file to discover all available pages before exploring further.

# Moneda Extranjera

> Factura de compra y venta de moneda extranjera. Sector 9.

Para casas de cambio y cualquier operación de compra o venta de divisas. Se emite por
`POST /api/v1/invoices` con `documentSectorType: 9`.

<Info>
  Los bancos, cooperativas y demás entidades financieras facturan sus servicios por
  [Entidades Financieras](/api/sectors/financial) (sector `15`), que según Impuestos **no incluye a las
  casas de cambio**. Si una entidad financiera además compra y vende divisas, esas operaciones van por este sector.
</Info>

<Note>
  **Disponible en sandbox** (`sandbox.cucu.bo`). Llega a producción con la próxima versión de la API;
  hasta entonces, `api.cucu.bo` responde `422 SECTOR_NOT_SUPPORTED` para el sector `9`.
</Note>

## Datos del sector

| Campo | Valor |
| - | - |
| `documentSectorType` | `9` |
| Servicio SIAT | Facturación Electrónica / Computarizada (genérico por modalidad) |
| Tipo de documento | `2` — sin derecho a crédito fiscal. **Lo fija el sector**: no hace falta mandar `invoiceType` y, si se manda, se ignora |
| `codigoCliente` | Lo que mandes en `clientCode` (el código de cliente de tu sistema); si no lo mandas, el `clientDocumentNumber` del cliente |
| Gift card | No aplica: el documento del SIN no tiene `montoGiftCard` |
| Notas de crédito-débito | **No admite** (ver la sección *Notas de crédito-débito* más abajo) |

## Campos específicos

Además de los [campos estándar](/api/create-invoice#request-body):

### Cabecera

| Campo | Tipo | Req | Descripción |
| - | - | - | - |
| `documentSectorType` | integer | Sí | `9` |
| `clientDocumentType` | integer | Sí | `1`–`5` (`codigoTipoDocumentoIdentidad`) |
| `currencyOperationType` | integer | **Sí** | `1` = venta de divisa al cliente, `2` = compra de divisa al cliente (`codigoTipoOperacion`) |
| `currencyCode` | integer | **Sí** | Divisa operada, código de la paramétrica de monedas del SIAT (`codigoMoneda`). P. ej. `2` = dólar |
| `exchangeRate` | number | **Sí** | Tipo de cambio pactado con el cliente, hasta 5 decimales (`tipoCambio`) |
| `officialExchangeRate` | number | **Sí** | Tipo de cambio oficial de esa divisa, hasta 5 decimales (`tipoCambioOficial`) |
| `descuentoAdicional` | number | No | Descuento sobre el total, en bolivianos (`descuentoAdicional`) |

Con `currencyCode: 1` (bolivianos), `exchangeRate` y `officialExchangeRate` deben ser `1`, como pide Impuestos.

Si falta un campo obligatorio, la emisión responde `400` antes de llegar al SIAT, con el campo en el mensaje
(p. ej. `officialExchangeRate (tipoCambioOficial) es obligatorio y mayor a 0 para moneda extranjera (sector 9)`).

### Detalle

| Campo | Tipo | Req | Descripción |
| - | - | - | - |
| `quantity` | number | Sí | Cantidad de divisa operada, hasta 5 decimales (p. ej. `120` dólares) |
| `priceUnit` | number | Sí | Precio en bolivianos de cada unidad de divisa: el tipo de cambio pactado, hasta 5 decimales |
| `amountDiscount` | number | No | Descuento por línea |

<Info>
  **Cómo se arma el total.** Los montos van en **bolivianos**, igual que en el ejemplo oficial de Impuestos
  (120 USD × 6.98 = 837.60 Bs). La API calcula el resto con las operaciones que publica Impuestos;
  **no se aceptan en el request**:

  ```
  subTotal                = cantidad × precioUnitario − montoDescuento
  montoTotal              = Σ subTotal − descuentoAdicional
  montoTotalMoneda        = montoTotal / tipoCambio
  ingresoDiferenciaCambio = tipoCambio − tipoCambioOficial      (venta, currencyOperationType 1)
                          = tipoCambioOficial − tipoCambio      (compra, currencyOperationType 2)
  montoTotalSujetoIva     = 0
  ```

  `ingresoDiferenciaCambio` viaja en valor absoluto, como pide Impuestos. La operación **no da crédito
  fiscal**: `montoTotalSujetoIva` siempre viaja en `0`.
</Info>

## Ejemplo

Venta de 120 USD a 6.98 con oficial 6.96 → `montoTotal` 837.60 Bs, `montoTotalMoneda` 120.00,
`ingresoDiferenciaCambio` 0.02.

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://sandbox.cucu.bo/api/v1/invoices \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "pointOfSaleId": "660e8400-e29b-41d4-a716-446655440004",
      "documentSectorType": 9,
      "clientDocumentType": 1,
      "clientDocumentNumber": "5115889",
      "clientBusinessName": "JUAN PEREZ",
      "currencyOperationType": 1,
      "currencyCode": 2,
      "exchangeRate": 6.98,
      "officialExchangeRate": 6.96,
      "paymentMethodCode": 1,
      "details": [
        {
          "activityEconomic": "661910",
          "codeProductSin": "71590",
          "description": "Venta de dolares americanos (USD)",
          "quantity": 120,
          "unitMeasure": 58,
          "priceUnit": 6.98
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch('https://sandbox.cucu.bo/api/v1/invoices', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      pointOfSaleId: '660e8400-e29b-41d4-a716-446655440004',
      documentSectorType: 9,
      clientDocumentType: 1,
      clientDocumentNumber: '5115889',
      clientBusinessName: 'JUAN PEREZ',
      currencyOperationType: 1,
      currencyCode: 2,
      exchangeRate: 6.98,
      officialExchangeRate: 6.96,
      paymentMethodCode: 1,
      details: [{
        activityEconomic: '661910',
        codeProductSin: '71590',
        description: 'Venta de dolares americanos (USD)',
        quantity: 120,
        unitMeasure: 58,
        priceUnit: 6.98
      }]
    })
  });
  ```

  ```python Python theme={"system"}
  import requests

  response = requests.post(
      'https://sandbox.cucu.bo/api/v1/invoices',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': 'YOUR_API_KEY'
      },
      json={
          'pointOfSaleId': '660e8400-e29b-41d4-a716-446655440004',
          'documentSectorType': 9,
          'clientDocumentType': 1,
          'clientDocumentNumber': '5115889',
          'clientBusinessName': 'JUAN PEREZ',
          'currencyOperationType': 1,
          'currencyCode': 2,
          'exchangeRate': 6.98,
          'officialExchangeRate': 6.96,
          'paymentMethodCode': 1,
          'details': [{
              'activityEconomic': '661910',
              'codeProductSin': '71590',
              'description': 'Venta de dolares americanos (USD)',
              'quantity': 120,
              'unitMeasure': 58,
              'priceUnit': 6.98
          }]
      }
  )
  ```
</CodeGroup>

<Note>
  `activityEconomic`, `codeProductSin` y `unitMeasure` son los que Impuestos te habilitó: tomalos de los
  [catálogos](/api/catalogs) de tu empresa. Los del ejemplo son ilustrativos.
</Note>

## Notas de crédito-débito

Las facturas del sector `9` **no admiten** notas de crédito-débito. La nota es un ajuste de IVA
(Art. 36, RND 102100000011) y la compra-venta de divisas no lo genera: no hay nada que ajustar.
`POST /api/v1/invoices/{id}/credit-note` sobre una factura de este sector responde `422`:

```json theme={"system"}
{
  "success": false,
  "message": null,
  "data": null,
  "error": {
    "code": "CREDIT_DEBIT_NOTE_NOT_ALLOWED",
    "details": "Las facturas del documento sector 9 no admiten notas de crédito-débito: la nota ajusta IVA (Art. 36 RND 102100000011) y este sector no lo genera."
  }
}
```

Para corregir una factura de este sector, se [anula](/api/cancel-invoice) y se emite una nueva.

<Info>
  Ver [Crear Factura](/api/create-invoice) para la referencia completa de campos estándar, response y códigos de error.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.