Ver .md Abrir en ChatGPT Abrir en Claude

💰 Gestión de Monedas

Autenticación Requerida

Incluir en todos los endpoints de esta sección el header: Authorization: Bearer {token}

Permite administrar el catálogo y las tasas de cambio de monedas extranjeras (ej. USD, EUR) respecto a la moneda funcional nacional (COP - Peso Colombiano) para emitir documentos electrónicos multi-moneda.

Parámetro Multi-Tenant: client_uuid

Si operas como Casa de Software, puedes configurar las tasas de cambio de tus empresas cliente agregando ?client_uuid={{client_uuid}}.

GET {{url}}/company/customers
Authorization: Bearer {token}

📋 Catálogo y Monedas de la Empresa

GET /currency/all — Catálogo General de Monedas

GET {{url}}/currency/all
Authorization: Bearer {token}
Content-Type: application/json

Descripción: Obtiene el catálogo completo de monedas soportadas por el sistema.

✅ Respuesta Exitosa (HTTP 200)

{
  "dataRecords": {
    "data": [
      {
        "id": 164,
        "CurrencyISO": "USD",
        "Language": "EN",
        "CurrencyName": "Dólar Estadounidense",
        "Money": "Dólar",
        "Symbol": "$",
        "Format": "en-US",
        "image": "usa.png",
        "active": 1
      },
      {
        "id": 272,
        "CurrencyISO": "COP",
        "Language": "ES",
        "CurrencyName": "Peso Colombiano",
        "Money": "Peso",
        "Symbol": "$",
        "Format": "es-CO",
        "image": "colombia.png",
        "active": 1
      }
    ]
  },
  "success": true
}

GET /currency — Monedas Configuradas en la Empresa

GET {{url}}/currency?client_uuid={{client_uuid}}
Authorization: Bearer {token}
Content-Type: application/json

Descripción: Obtiene, paginada (15 por página), la lista de monedas y tasas de cambio asignadas a la empresa emisora. Cada registro incluye en currency los datos de la moneda del catálogo.

Parámetros:

Nombre	Ubicación	Requerido	Descripción
`uid`	query	No	Filtra por el `id` de una moneda configurada en la empresa.
`page`	query	No	Número de página (default: `1`).
`client_uuid`	query	No	UUID del cliente (Casa de Software).

✅ Respuesta Exitosa (HTTP 200)

{
  "dataRecords": {
    "current_page": 1,
    "data": [
      {
        "id": 7,
        "currency_id": 272,
        "company_id": 1,
        "exchange_rate_value": "0.00",
        "national_currency": 1,
        "plural_name": "PESOS",
        "singular_name": "PESO",
        "denomination": "COP",
        "currency": {
          "id": 272,
          "CurrencyISO": "COP",
          "CurrencyName": "Peso Colombiano",
          "Symbol": "$"
        }
      },
      {
        "id": 8,
        "currency_id": 164,
        "company_id": 1,
        "exchange_rate_value": "4200.50",
        "national_currency": 0,
        "plural_name": "DÓLARES",
        "singular_name": "DÓLAR",
        "denomination": "USD",
        "currency": {
          "id": 164,
          "CurrencyISO": "USD",
          "CurrencyName": "Dólar Estadounidense",
          "Symbol": "$"
        }
      }
    ],
    "per_page": 15,
    "total": 2
  },
  "success": true
}

El objeto currency está recortado: trae los mismos campos que GET /currency/all. El paginador incluye además los campos estándar (from, to, last_page, links, etc.).

⚙️ Configuración de Tasas de Cambio

POST /currency — Agregar Moneda a la Empresa

POST {{url}}/currency?client_uuid={{client_uuid}}
Authorization: Bearer {token}
Content-Type: application/json

Descripción: Registra una nueva divisa con su tasa de cambio para la empresa emisora.

💡 Guía para Desarrolladores — Configuración de Monedas

Los datos de la divisa se serializan en la propiedad records del JSON (Content-Type: application/json).

JavaScript / Node.js
PHP (cURL)
Python
C# / .NET
Postman

import axios from 'axios';

const records = {
  currency_id: 164,           // ID del catálogo (GET /currency/all)
  exchange_rate_value: 4200.50,// Tasa de cambio respecto al COP
  national_currency: 0,        // 1: Moneda funcional local, 0: Moneda extranjera
  plural_name: "DÓLARES",
  singular_name: "DÓLAR",
  denomination: "USD"
};

const response = await axios.post(`${url}/currency`, {
  records: JSON.stringify(records)
}, {
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  }
});

<?php
$records = [
    'currency_id'         => 164,
    'exchange_rate_value' => 4200.50,
    'national_currency'   => 0,
    'plural_name'         => 'DÓLARES',
    'singular_name'       => 'DÓLAR',
    'denomination'        => 'USD',
];

$payload = json_encode(['records' => json_encode($records)]);

$ch = curl_init("{$url}/currency");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

import json
import requests

records = {
    "currency_id": 164,
    "exchange_rate_value": 4200.50,
    "national_currency": 0,
    "plural_name": "DÓLARES",
    "singular_name": "DÓLAR",
    "denomination": "USD"
}

response = requests.post(
    f"{url}/currency",
    json={"records": json.dumps(records)},
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }
)

using System.Text.Json;
using System.Net.Http.Headers;

var records = new {
    currency_id = 164,
    exchange_rate_value = 4200.50,
    national_currency = 0,
    plural_name = "DÓLARES",
    singular_name = "DÓLAR",
    denomination = "USD"
};

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
var response = await client.PostAsJsonAsync($"{url}/currency", new {
    records = JsonSerializer.Serialize(records)
});

const records = {
    currency_id: 164,
    exchange_rate_value: 4200.50,
    national_currency: 0,
    plural_name: "DÓLARES",
    singular_name: "DÓLAR",
    denomination: "USD"
};

const payload = { records: JSON.stringify(records) };
pm.request.body.mode = 'raw';
pm.request.body.raw = JSON.stringify(payload);
pm.request.headers.add({key: 'Content-Type', value: 'application/json'});

Propiedades de records:

Campo	Tipo	Requerido	Descripción
`currency_id`	integer	✅ Sí	ID de la moneda del catálogo (`GET /currency/all`).
`exchange_rate_value`	number	No	Tasa de cambio respecto al peso colombiano (default: `0`).
`national_currency`	integer	No	`1` si es la moneda funcional local, `0` si es extranjera (default: `0`).
`plural_name`	string	No	Nombre en plural (ej. `DÓLARES`).
`singular_name`	string	No	Nombre en singular (ej. `DÓLAR`).
`denomination`	string	No	Código ISO de la moneda (ej. `USD`, `EUR`).

El body debe incluir records como string JSON. Esto aplica a POST, PUT y DELETE de /currency.

✅ Respuesta Exitosa (HTTP 200)

{
  "message": "Registro creado correctamente.",
  "record": {
    "id": 8,
    "currency_id": 164,
    "company_id": 1,
    "exchange_rate_value": "4200.50",
    "national_currency": 0,
    "plural_name": "DÓLARES",
    "singular_name": "DÓLAR",
    "denomination": "USD"
  },
  "success": true
}

❌ Moneda duplicada (HTTP 400)

La moneda ya está configurada para la empresa:

{
  "success": false,
  "message": "La moneda ya existe para la empresa"
}

❌ Sin records o JSON inválido (HTTP 422)

{
  "message": "El campo records es requerido",
  "errors": {
    "records": ["El campo records es requerido"]
  }
}

Si records no es un JSON válido, el mensaje es El campo records debe ser un JSON válido.

PUT /currency/{id} — Actualizar Tasa de Moneda

PUT {{url}}/currency/{id}?client_uuid={{client_uuid}}
Authorization: Bearer {token}
Content-Type: application/json

Parámetros:

Nombre	Ubicación	Requerido	Descripción
`id`	path	✅ Sí	ID de la moneda configurada en la empresa.
`client_uuid`	query	No	UUID del cliente (Casa de Software).

Body (JSON): records como string JSON, con las mismas propiedades que en POST. currency_id es obligatorio; exchange_rate_value y national_currency toman 0 si los omites, y los nombres quedan vacíos. Envía siempre la configuración completa de la moneda.

{
  "records": "{\"currency_id\":164,\"exchange_rate_value\":4350.25,\"national_currency\":0,\"plural_name\":\"DÓLARES\",\"singular_name\":\"DÓLAR\",\"denomination\":\"USD\"}"
}

✅ Respuesta Exitosa (HTTP 200)

{
  "success": true
}

DELETE /currency/{id} — Eliminar Moneda

DELETE {{url}}/currency/{id}?client_uuid={{client_uuid}}
Authorization: Bearer {token}
Content-Type: application/json

Parámetros:

Nombre	Ubicación	Requerido	Descripción
`id`	path	✅ Sí	ID de la moneda configurada a eliminar.
`client_uuid`	query	No	UUID del cliente (Casa de Software).

Body (JSON): records es obligatorio también en el borrado. Cada campo que envíes dentro de records se añade como condición: solo se elimina la fila que coincida con el id y con esos valores. Para borrar solo por id, envía un objeto vacío.

{
  "records": "{}"
}

✅ Respuesta Exitosa (HTTP 200)

Devuelve las filas eliminadas (un arreglo vacío si ninguna coincidió):

{
  "records": [
    {
      "id": 8,
      "currency_id": 164,
      "company_id": 1,
      "exchange_rate_value": "4200.50",
      "national_currency": 0,
      "plural_name": "DÓLARES",
      "singular_name": "DÓLAR",
      "denomination": "USD"
    }
  ],
  "success": true
}

💱 Tasa de Cambio

GET /currency/change — Cotizar entre dos Monedas

GET {{url}}/currency/change?source=USD&target=COP&quantity=100
Authorization: Bearer {token}

Descripción: Consulta la cotización entre dos monedas con un proveedor externo de tasas de cambio.

Parámetros:

Nombre	Ubicación	Requerido	Descripción
`source`	query	✅ Sí	Código ISO de la moneda de origen (ej. `USD`).
`target`	query	✅ Sí	Código ISO de la moneda de destino (ej. `COP`).
`quantity`	query	✅ Sí	Cantidad a convertir.

✅ Respuesta Exitosa (HTTP 200)

{
  "value": 4200.5,
  "amount": 420050,
  "success": true
}

GET /currency/change/local — Convertir a la Moneda Nacional

GET {{url}}/currency/change/local?source=USD&quantity=100
Authorization: Bearer {token}

Descripción: Convierte una cantidad desde la moneda source hacia la moneda marcada como nacional (national_currency: 1). Requiere tener configurada la moneda nacional.

Parámetros:

Nombre	Ubicación	Requerido	Descripción
`source`	query	✅ Sí	Código ISO de la moneda de origen (ej. `USD`).
`quantity`	query	No	Cantidad a convertir (default: `1`).

✅ Respuesta Exitosa (HTTP 200)

{
  "records": [
    { "value": 4200.5, "amount": 420050 }
  ],
  "success": true
}

❌ Moneda nacional no configurada (HTTP 404)

{
  "success": false,
  "message": "Debe crear la moneda nacional."
}

Si la moneda nacional configurada no existe en el catálogo, el mensaje es No existe la moneda.

Sandbox

En sandbox, ambos endpoints de tasa de cambio devuelven un factor fijo de 1.0: value y amount valen 1.0 × quantity.

📋 Catálogo y Monedas de la Empresa​

⚙️ Configuración de Tasas de Cambio​

💱 Tasa de Cambio​

📋 Catálogo y Monedas de la Empresa

⚙️ Configuración de Tasas de Cambio

💱 Tasa de Cambio