API de Facturación Electrónica

curl -X GET "https://sandbox.vision-total.rogcr.com/api/facturacion/connection" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{
  "success": false,
  "message": "El documento de identificación es inválido para el tipo seleccionado.",
  "code": "BAD_REQUEST"
}

{
  "message": "motivo requerido (3-180 caracteres)"
}

vt_m2m_<prefijo>.<secreto>
#         └─ público ─┘ └─ autoriza ┘

# Ejemplo (el secreto es inventado para la documentación):
vt_m2m_k3P9xQ7mR2tY.Tq8mZ2vL4nB6xD8fH0jK3mP5sR7wY9aC1eG3iK5oQ7uW9yA1bC3e

curl -X GET "https://sandbox.vision-total.rogcr.com/api/m2m/me" \
  -H "Authorization: Bearer vt_m2m_k3P9xQ7mR2tY.Tq8mZ2v…"

{
  "token": {
    "id": "c4e1...",
    "name": "Sync contable",
    "organizationId": "3b91c..."
  },
  "organization": {
    "id": "3b91c...",
    "name": "Comercial del Este",
    "legalName": "Comercial del Este Sociedad Anónima",
    "taxId": "3101234567",
    "taxIdType": "02",
    "currency": "CRC",
    "type": "retail"
  },
  "role": { "id": "c7d2...", "name": "Facturación" }
}

HTTP 403
{
  "message": "Las credenciales de máquina no pueden usar esta operación."
}

curl -X GET "https://sandbox.vision-total.rogcr.com/api/organizations" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "id": "3b91c...",
    "name": "Comercial del Este",
    "legalName": "Comercial del Este Sociedad Anónima",
    "taxId": "3101234567",
    "taxIdType": "02",
    "address": "Avenida Central, 500 metros al sur",
    "country": "Costa Rica",
    "email": "facturacion@miempresa.cr",
    "currency": "CRC",
    "type": "retail",
    "facturacionConfigured": true,
    "hasHaciendaCredentials": true,
    "hasCertificate": true
  }
]

curl -X GET "https://sandbox.vision-total.rogcr.com/api/facturacion/connection" \
  -H "Authorization: Bearer $TOKEN"

{
  "organizationId": "3b91c...",
  "haciendaConfigReady": true,
  "facturacionConfigured": true,
  "credentialsConfigured": true,
  "certificateConfigured": true,
  "environment": "sandbox",
  "clientId": "api-stag",
  "username": "usuario-idp@hacienda.go.cr",
  "certificate": {
    "issuedAt": "2026-01-15T00:00:00.000Z",
    "expiresAt": "2027-01-15T00:00:00.000Z",
    "isActive": true
  }
}

curl -X GET "https://sandbox.vision-total.rogcr.com/api/facturacion/consecutivos" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    { "sucursalCodigo": "001", "terminalCodigo": "00001", "tipoDocumento": "01", "lastNumber": 42, "updatedAt": "2026-10-24T15:02:00.000Z" },
    { "sucursalCodigo": "001", "terminalCodigo": "00001", "tipoDocumento": "04", "lastNumber": 87, "updatedAt": "2026-10-24T15:02:00.000Z" }
  ]
}

curl -X POST "https://sandbox.vision-total.rogcr.com/api/customers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporación Wegner S.A.",
    "governmentId": "3109876543",
    "governmentIdType": "02",
    "email": "facturacion@wegner.cr",
    "phone": "+50627778899",
    "address": "Zona Industrial Heredia, bodega 12",
    "provinceCode": "2",
    "cantonCode": "01",
    "districtCode": "03",
    "economicActivities": ["4610.0", "4711.0", "7020.0"]
  }'

curl -X POST "https://sandbox.vision-total.rogcr.com/api/products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Café molido 250 g",
    "sku": "CAF-250",
    "price": 2850.00,
    "costPrice": 1700.00,
    "stock": 120,
    "productType": "product",
    "cabys": "5897000000000",
    "codigoImpuesto": "01",
    "tarifaIvaCode": "08",
    "codigoMoneda": "CRC"
  }'

{
  "id": "5b70...",
  "name": "Café molido 250 g",
  "cabys": "5897000000000",
  "unitOfMeasureId": "3a7e...",
  "unitOfMeasure": {
    "id": "3a7e...",
    "code": "Unid",
    "name": "Unidad",
    "symbol": "Unid",
    "baseUnitCode": null,
    "conversionFactor": "1.00000000"
  }
}

curl -X POST "https://sandbox.vision-total.rogcr.com/api/suppliers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identificationType": "02",
    "identificationNumber": "3012345678",
    "name": "Distribuidora Nacional S.A.",
    "email": "ventas@distribuidora.cr",
    "isForeign": false,
    "provinceCode": "1",
    "cantonCode": "01",
    "districtCode": "01",
    "streetAddress": "Zona Industrial,-calle 4, nave 22",
    "economicActivities": ["4610.0"]
  }'

curl -X GET "https://sandbox.vision-total.rogcr.com/api/cabys?q=cafe&limit=20" \
  -H "Authorization: Bearer $TOKEN"

{
  "total": 2,
  "items": [
    { "codigo": "5897000000000", "descripcion": "Café molido, sin azúcar" },
    { "codigo": "5897000000001", "descripcion": "Café en grano" }
  ]
}

curl -X POST "https://sandbox.vision-total.rogcr.com/api/hacienda/exoneraciones/lookup" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "autorizacion": "AL-00001234-01" }'

{
  "success": true,
  "data": {
    "numeroDocumento": "12-34",
    "tipoDocumento": "08",
    "nombreInstitucion": "02",
    "fechaEmision": "2026-01-01",
    "tarifaExonerada": 13,
    "cabys": "5897000000000",
    "poseeCabys": true,
    "institucionNombre": "Ministerio de Hacienda",
    "fechaVencimiento": "2027-12-31"
  }
}

curl -X GET "https://sandbox.vision-total.rogcr.com/api/units-of-measure" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "id": "3a7e...",
    "code": "Unid",
    "name": "Unidad",
    "symbol": "Unid",
    "baseUnitCode": null,
    "conversionFactor": "1.00000000"
  },
  {
    "id": "8d26...",
    "code": "Kg",
    "name": "Kilogramo",
    "symbol": "Kg",
    "baseUnitCode": null,
    "conversionFactor": "1.00000000"
  },
  {
    "id": "c13e...",
    "code": "G",
    "name": "Gramo",
    "symbol": "G",
    "baseUnitCode": "kg",
    "conversionFactor": "0.00100000"
  }
]

curl -X GET "https://sandbox.vision-total.rogcr.com/api/facturacion/taxpayers/3109876543" \
  -H "Authorization: Bearer $TOKEN"

{
  "nombre": "CORPORACIÓN WEGNER S.A.",
  "tipoIdentificacion": "02",
  "regimen": { "codigo": 1, "descripcion": "Régimen general" },
  "situacion": {
    "omiso": "NO",
    "estado": "Inscrito",
    "moroso": "NO",
    "administracionTributaria": "San José"
  },
  "actividades": [
    { "estado": "A", "tipo": "S", "codigo": "4610.0", "descripcion": "Venta al por mayor a cambio de una retribución o por contrato" },
    { "estado": "A", "tipo": "S", "codigo": "4711.0", "descripcion": "Venta al por menor en comercios no especializados" },
    { "estado": "A", "tipo": "S", "codigo": "7020.0", "descripcion": "Actividades de consultoría y administración de empresas" }
  ]
}

HTTP 404
{ "message": "Taxpayer not found" }

// El código de actividad sale del padrón, no de un campo escrito a mano.
const contribuyente = await consultarContribuyente(customer.governmentId)

if (!contribuyente.registrado) {
  // No se puede facturar a este receptor: la factura sería rechazada.
  throw new Error(`El contribuyente ${customer.governmentId} no está en el padrón de Hacienda`)
}

// El nombre que va al XML es el del padrón, no el que escribió el usuario.
const nombreReceptor = contribuyente.contribuyente?.nombre ?? customer.name

// La primera actividad activa sirve como CodigoActividadReceptor.
const actividades = contribuyente.contribuyente?.actividades?.filter((a) => a.estado === "A") ?? []
const actividad = actividades[0]
const actividadEconomicaReceptor = actividad?.codigo   // p. ej. "4610.0"

// El mismo catálogo se guarda en la ficha del cliente: el API exige que
// `actividadEconomicaReceptor` sea uno de los `customer.economicActivities`.
await api(`/customers/${customer.id}`, {
  method: "PUT",
  body: { economicActivities: actividades.map((a) => a.codigo) },
})

curl -X GET "https://sandbox.vision-total.rogcr.com/api/organizations/$ORG_ID/activities" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "organizationId": "3b91c...",
    "codigo": "4711.1",
    "descripcion": "Venta al por menor en supermercados, almacenes y similares",
    "esPrincipal": true,
    "createdAt": "2026-10-01T12:00:00.000Z"
  },
  {
    "organizationId": "3b91c...",
    "codigo": "4711.2",
    "descripcion": "Venta al por menor en minisuper, pulperias y similares",
    "esPrincipal": false,
    "createdAt": "2026-10-01T12:00:00.000Z"
  }
]

// 1 · El padrón: fuente de verdad del CIIU del receptor.
const padron = await consultarContribuyente("3109876543", token)
if (!padron.registrado) throw new Error("El contribuyente no está en el padrón de Hacienda")

const actividades = padron.contribuyente.actividades
  .filter((a) => a.estado === "A")
  .map((a) => a.codigo)          // p. ej. ["4610.0", "4711.0", "7020.0"]

// 2 · La ficha del cliente guarda ese mismo catálogo.
const customer = await api("/customers", {
  method: "POST",
  token,
  body: {
    name: padron.contribuyente.nombre,
    governmentId: "3109876543",
    governmentIdType: "02",
    email: "facturacion@wegner.cr",
    economicActivities: actividades,
  },
})

// 3 · La factura usa uno de los códigos ya registrados.
const invoice = await api("/invoices", {
  method: "POST",
  token,
  body: {
    documentType: "01",
    customerId: customer.id,
    actividadEconomicaReceptor: actividades[0],
    // …
  },
})

curl -X GET "https://sandbox.vision-total.rogcr.com/api/economic-activities" \
  -H "Authorization: Bearer $TOKEN"

[
  { "codigo": "0000.1", "descripcion": "Preoperativa" },
  { "codigo": "0114.0", "descripcion": "Cultivo de caña de azúcar" },
  { "codigo": "4610.0", "descripcion": "Venta al por mayor a cambio de una retribución o por contrato" },
  { "codigo": "4711.1", "descripcion": "Venta al por menor en supermercados, almacenes y similares" },
  { "codigo": "6201.0", "descripcion": "Actividades de programación informática" },
  { "codigo": "9900.0", "descripcion": "Actividades de organizaciones y órganos extraterritoriales" }
]

curl -X GET "https://sandbox.vision-total.rogcr.com/api/locations/costa-rica"

{
  "pais": "Costa Rica",
  "provincias": [
    {
      "codigo": "1",
      "nombre": "San José",
      "cantones": [
        {
          "codigo": "01",
          "nombre": "San José",
          "distritos": [
            { "codigo": "01", "nombre": "Carmen" },
            { "codigo": "02", "nombre": "Merced" }
          ]
        },
        {
          "codigo": "02",
          "nombre": "Escazú",
          "distritos": [
            { "codigo": "01", "nombre": "Escazú" },
            { "codigo": "02", "nombre": "San Antonio" }
          ]
        }
      ]
    }
  ]
}

// El catálogo es global y estático: se consulta una vez y se cachea.
const ubicaciones = await fetch(`${BASE}/locations/costa-rica`).then((r) => r.json());

// Índices para resolver en cascada sin recorrer el árbol en cada render.
const porProvincia = new Map(ubicaciones.provincias.map((p) => [p.codigo, p]));
const cantonesDe = (provincia) => porProvincia.get(provincia)?.cantones ?? [];
const distritosDe = (provincia, canton) =>
  cantonesDe(provincia).find((c) => c.codigo === canton)?.distritos ?? [];

// El nombre legible sale del catálogo, no de una copia local.
const nombreUbicacion = (provincia, canton, distrito) => {
  const p = porProvincia.get(provincia);
  const c = p?.cantones.find((x) => x.codigo === canton);
  const d = c?.distritos.find((x) => x.codigo === distrito);
  return [p?.nombre, c?.nombre, d?.nombre].filter(Boolean).join(", ");
};

// Se manda el código tal cual: sin padding en la provincia.
const body = {
  provinceCode: "1",     // San José
  cantonCode: "01",      // San José
  districtCode: "01",    // Carmen
  streetAddress: "Zona Industrial, calle 4, nave 22",
};

curl -X GET "https://sandbox.vision-total.rogcr.com/api/exchange-rates/USD" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": {
    "currency": "USD",
    "rate": 512.35,
    "fetchedAt": "2026-11-05T08:00:00.000Z"
  }
}

curl -X PUT "https://sandbox.vision-total.rogcr.com/api/customers/$CUSTOMER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+50689998877",
    "address": "Zona Industrial Heredia, bodega 12"
  }'

curl -X POST "https://sandbox.vision-total.rogcr.com/api/warehouses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Bodega central", "isDefault": true }'

curl -X POST "https://sandbox.vision-total.rogcr.com/api/products/$PRODUCT_ID/movements" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 24,
    "type": "in",
    "reason": "Recepción de mercadería",
    "warehouseId": "8c31...",
    "referenceId": "rec-2026-0042",
    "uomId": "3a7e..."
  }'

curl -X POST "https://sandbox.vision-total.rogcr.com/api/waste" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "5b70...",
    "warehouseId": "8c31...",
    "quantity": 3,
    "reason": "spoilage",
    "notes": "Lote dañado por humedad"
  }'

curl -X POST "https://sandbox.vision-total.rogcr.com/api/inventory/reconcile" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "productId": "5b70...", "warehouseId": "8c31..." }'

curl -X POST "https://sandbox.vision-total.rogcr.com/api/invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "01",
    "customerId": "9f2c...",
    "terminalId": "7a41...",
    "sucursalCodigo": "001",
    "numeroTerminal": "00001",
    "codigoActividadEmisor": "4711.1",
    "condicionVenta": "01",
    "codigoMoneda": "CRC",
    "tipoCambio": 1,
    "notes": "Venta de mercadería",
    "items": [
      {
        "productId": "5b70...",
        "quantity": 2,
        "price": 2850.00,
        "taxRate": 0.13,
        "tarifaIvaCode": "08",
        "detalle": "Café molido 250 g",
        "unidadMedida": "Unid"
      },
      {
        "productId": null,
        "quantity": 1,
        "price": 5000.00,
        "taxRate": 0.13,
        "tarifaIvaCode": "08",
        "detalle": "Servicio de instalación",
        "unidadMedida": "Unid"
      }
    ]
  }'

{
  "success": true,
  "data": {
    "id": "0e77...",
    "documentType": "01",
    "documentTypeLabel": "Factura Electrónica",
    "status": "draft",
    "customerId": "9f2c...",
    "customerName": "Corporación Wegner S.A.",
    "customer": { "identificationType": "02", "identificationNumber": "3109876543" },
    "organization": {
      "name": "Comercial del Este",
      "legalName": "Comercial del Este Sociedad Anónima",
      "taxId": "3101234567",
      "taxIdType": "02",
      "email": "facturacion@miempresa.cr"
    },
    "terminalId": "7a41...",
    "terminalName": "POS Principal",
    "sucursalCodigo": "001",
    "numeroTerminal": "00001",
    "codigoActividadEmisor": "4711.1",
    "condicionVenta": "01",
    "codigoMoneda": "CRC",
    "tipoCambio": 1,
    "subtotal": 10700,
    "taxTotal": 1391,
    "discountTotal": 0,
    "total": 12091,
    "paidBalance": 0,
    "remainingBalance": 12091,
    "createdByUserId": "8a5f...",
    "createdAt": "2026-10-24T15:10:00.000Z",
    "haciendaStatus": null
  }
}

{
  "message": "El producto \"Café molido 250 g\" (SKU CAF-250) no tiene CABYS asignado. Asignalo en Configuración > Productos antes de facturar.",
  "code": "PRODUCT_MISSING_CABYS"
}

curl -X POST "https://sandbox.vision-total.rogcr.com/api/invoices/$INVOICE_ID/payments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payments": [
      { "method": "cash", "amount": 5000, "reference": "Efectivo", "change": 0, "customerAmount": 5000 },
      { "method": "sinpe", "amount": 7091, "reference": "SINPE-884512" }
    ]
  }'

{
  "success": true,
  "data": {
    "payments": [
      {
        "id": "c1a0...",
        "method": "cash",
        "amount": 5000,
        "reference": "Efectivo",
        "change": 0,
        "customerAmount": 5000,
        "receivedAt": "2026-10-24T15:14:00.000Z",
        "haciendaDocumentId": null,
        "haciendaClave": null
      }
    ],
    "payment": { "id": "c1a0...", "method": "cash", "amount": 5000 },
    "invoice": { "id": "0e77...", "status": "paid", "paidBalance": 12091, "remainingBalance": 0 },
    "advanceApplications": []
  }
}

curl -X POST "https://sandbox.vision-total.rogcr.com/api/invoices/$INVOICE_ID/facturar" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "01",
    "customerId": "9f2c...",
    "actividadEconomicaReceptor": "4711.0"
  }'

{
  "success": true,
  "data": {
    "haciendaDocumentId": "d41b...",
    "clave": "50624102600310123456700100001010000000042112345678",
    "jobId": "14"
  }
}

curl -X GET "https://sandbox.vision-total.rogcr.com/api/cabys?q=vehiculo%20electrico&limit=20" \
  -H "Authorization: Bearer $TOKEN"

{
  "total": 2,
  "items": [
    { "codigo": "8711100000000", "descripcion": "Automóviles y camionetas, eléctricos" },
    { "codigo": "8711990000000", "descripcion": "Partes y accesorios de vehículos eléctricos" }
  ]
}

curl -X POST "https://sandbox.vision-total.rogcr.com/api/products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vehículo eléctrico BYD Dolphin 2026",
    "sku": "VEH-0001",
    "price": 18500000,
    "costPrice": 16000000,
    "productType": "product",
    "cabys": "8711100000000",
    "codigoImpuesto": "01",
    "tarifaIvaCode": "08",
    "codigoMoneda": "CRC",
    "unitOfMeasureId": "3a7e..."
  }'

curl -X POST "https://sandbox.vision-total.rogcr.com/api/invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "01",
    "customerId": "9f2c...",
    "sucursalCodigo": "001",
    "numeroTerminal": "00001",
    "codigoActividadEmisor": "4510.0",
    "actividadEconomicaReceptor": "4711.0",
    "condicionVenta": "01",
    "codigoMoneda": "CRC",
    "tipoCambio": 1,
    "notes": "Venta de vehículo eléctrico con exoneración ARESEP",
    "items": [
      {
        "productId": "ID_VEHICULO",
        "quantity": 1,
        "price": 18500000,
        "taxRate": 0.13,
        "tarifaIvaCode": "08",
        "codigoImpuesto": "01",
        "detalle": "Vehículo eléctrico BYD Dolphin 2026",
        "unidadMedida": "Unid",
        "numeroVINoSerie": "JTDDA3T7KA012345",

        "exoTipoDocumento": "03",
        "exoNumeroDocumento": "RES-ARESEP-2026-04512",
        "exoArticulo": 5,
        "exoInciso": 3,
        "exoNombreInstitucion": "12",
        "exoFechaEmision": "2026-03-14",
        "exoTarifaExoneradaOverride": 13,
        "exoMontoExoneradoOverride": 2405000
      },
      {
        "productId": "ID_KIT_CARGA",
        "quantity": 1,
        "price": 450000,
        "taxRate": 0.13,
        "tarifaIvaCode": "08",
        "codigoImpuesto": "01",
        "detalle": "Kit de carga doméstica 7.4 kW",
        "unidadMedida": "Unid"
      },
      {
        "productId": "ID_ACCESORIOS",
        "quantity": 1,
        "price": 85000,
        "taxRate": 0.13,
        "tarifaIvaCode": "08",
        "codigoImpuesto": "01",
        "detalle": "Alfombrillas y kit de seguridad",
        "unidadMedida": "Unid"
      }
    ]
  }'

curl -X POST "https://sandbox.vision-total.rogcr.com/api/invoices/$INVOICE_ID/payments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payments": [
      { "method": "transfer", "amount": 19104550, "reference": "BAC #884512" }
    ]
  }'

<Detalle>
  <CodigoCABYS>8711100000000</CodigoCABYS>
  <Cantidad>1</Cantidad>
  <UnidadMedida>Unid</UnidadMedida>
  <Detalle>Vehículo eléctrico BYD Dolphin 2026</Detalle>
  <NumeroVINoSerie>JTDDA3T7KA012345</NumeroVINoSerie>
  <PrecioUnitario>18500000.00000</PrecioUnitario>
  <MontoTotal>18500000.00000</MontoTotal>
  <SubTotal>18500000.00000</SubTotal>
  <BaseImponible>18500000.00000</BaseImponible>
  <Impuesto>
    <Codigo>01</Codigo>
    <CodigoTarifaIVA>08</CodigoTarifaIVA>
    <Tarifa>13.00000</Tarifa>
    <Monto>2405000.00000</Monto>
    <Exoneracion>
      <TipoDocumento>03</TipoDocumento>
      <NumeroDocumento>RES-ARESEP-2026-04512</NumeroDocumento>
      <Articulo>5</Articulo>
      <Inciso>3</Inciso>
      <NombreInstitucion>12</NombreInstitucion>
      <FechaEmision>2026-03-14T00:00:00</FechaEmision>
      <TarifaExonerada>13.00000</TarifaExonerada>
      <MontoExoneracion>2405000.00000</MontoExoneracion>
    </Exoneracion>
    <ImpuestoNeto>0.00000</ImpuestoNeto>
  </Impuesto>
  <MontoTotalLinea>18500000.00000</MontoTotalLinea>
</Detalle>

{
  "data": {
    "items": [
      {
        "detalle": "Vehículo eléctrico BYD Dolphin 2026",
        "total": 18500000,
        "taxAmount": 0,
        "tarifaIvaCode": "08",
        "codigoCabys": "8711100000000",
        "numeroVINoSerie": "JTDDA3T7KA012345",
        "exoTipoDocumento": "03",
        "exoNumeroDocumento": "RES-ARESEP-2026-04512",
        "exoArticulo": 5,
        "exoInciso": 3,
        "exoNombreInstitucion": "12",
        "exoFechaEmision": "2026-03-14T00:00:00.000Z",
        "exoTarifaExoneradaOverride": 13,
        "exoMontoExoneradoOverride": 2405000
      }
    ],
    "subtotal": 19035000,
    "taxTotal": 69550,
    "total": 19104550
  }
}

curl -X POST "https://sandbox.vision-total.rogcr.com/api/invoices/$INVOICE_ID/nota-credito" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "motivo": "Devolución de 2 unidades de café por producto dañado",
    "codigoReferencia": "01",
    "medioReembolso": "01"
  }'

curl -X POST "https://sandbox.vision-total.rogcr.com/api/invoices/$INVOICE_ID/nota-debito" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "motivo": "Intereses por mora en el pago",
    "codigoReferencia": "10",
    "lineas": [
      {
        "codigoCabys": "5897000000000",
        "detalle": "Interés moratorio 30 días",
        "cantidad": 1,
        "precioUnitario": 1500,
        "tarifaIvaCode": "08"
      }
    ],
    "medioReembolso": "01"
  }'

curl -X POST "https://sandbox.vision-total.rogcr.com/api/invoices/$INVOICE_ID/recibo-pago" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "monto": 5000,
    "motivo": "Abono a cuenta de la factura 001-00000000042",
    "medioPago": "01",
    "medioPagoOtros": null
  }'

curl -X GET "https://sandbox.vision-total.rogcr.com/api/facturacion/documents/$DOCUMENT_ID/children?type=credit" \
  -H "Authorization: Bearer $TOKEN"

curl -X GET "https://sandbox.vision-total.rogcr.com/api/facturacion/documents/$DOCUMENT_ID/status" \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": {
    "documentId": "d41b...",
    "clave": "50624102600310123456700100001010000000042112345678",
    "documentType": "01",
    "estado": "aceptado",
    "detalleMensaje": "El documento fue aceptado por el sistema de facturación electrónica.",
    "mensajeHacienda": "<MensajeHacienda ...>...</MensajeHacienda>",
    "submittedAt": "2026-10-24T15:16:00.000Z",
    "acceptedAt": "2026-10-24T15:16:42.000Z",
    "rejectedAt": null,
    "cached": false
  }
}

{
  "success": true,
  "data": {
    "estado": "accepted",
    "detalleMensaje": "Este comprobante fue recibido en el ambiente de pruebas, por lo cual no tiene validez para fines tributarios.\n\ncodigo, mensaje, fila, columna\n-20, \"\"El nodo denominado 'Número de teléfono receptor' no posee la estructura establecida para el mismo\"\", 0, 0"
  }
}

// Mal: el detalle no está vacío, luego «algo falló».
// const fallida = Boolean(detalleMensaje)

// Bien: el estado es el que decide.
const ESTADOS_FINALES = new Set(["aceptado", "accepted", "rechazado", "rejected", "error"])
const fallida = !ESTADOS_FINALES.has(estado)

// Y las advertencias se pueden mostrar aparte, sin cambiar el veredicto.
const avisos = parseCodigosHacienda(detalleMensaje)   // p. ej. el -20 del teléfono

curl -X GET "https://sandbox.vision-total.rogcr.com/api/facturacion/documents/$DOCUMENT_ID/pdf" \
  -H "Authorization: Bearer $TOKEN" \
  -o comprobante.pdf

curl -X GET "https://sandbox.vision-total.rogcr.com/api/facturacion/documents?page=1&limit=20&estado=accepted" \
  -H "Authorization: Bearer $TOKEN"

curl -X POST "https://sandbox.vision-total.rogcr.com/api/facturacion/documents/$DOCUMENT_ID/email" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "additionalRecipients": ["contabilidad@wegner.cr"] }'

curl -X POST "https://sandbox.vision-total.rogcr.com/api/facturacion/documents/$DOCUMENT_ID/resend" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": {
    "id": "0e77...",
    "status": "invoiced",
    "haciendaStatus": "accepted",
    "haciendaDocuments": [
      {
        "id": "d41b...",
        "documentType": "01",
        "clave": "50630102600310987654300100001010000000138111089578",
        "numeroConsecutivo": "138",
        "estado": "accepted",
        "tenantEnvironment": "sandbox"
      }
    ]
  }
}

const issued = await api(`/invoices/${id}/facturar`, { method: "POST", body: payload })

// El consecutivo no viene en la respuesta de emisión: se lee del detalle.
const detail = await api(`/invoices/${id}`)
const consecutivo = detail.data.haciendaDocuments?.[0]?.numeroConsecutivo

// Clave y consecutivo juntos permiten auditar:
//   clave 506 30 10 26 003109876543 00100001010000000138 1 11089578
//                                        └──── consecutivo 138 ────┘

curl -X POST "https://sandbox.vision-total.rogcr.com/api/purchases/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "files=@/ruta/comprobante.xml" \
  -F 'messageConfig={"tipoMensaje":"1","condicionImpuesto":"01","codigoActividad":"4711.1","clasificacion":"compra"}'

{
  "success": true,
  "data": {
    "exitosos": 1,
    "fallidos": 0,
    "advertencias": [],
    "comprasAfectadas": ["c3f1..."],
    "archivos": [
      {
        "filename": "comprobante.xml",
        "size": 24817,
        "status": "ok",
        "documentType": "01",
        "documentTypeLabel": "01 FE — Factura Electrónica",
        "clave": "50624102600310123456700100001010000000042112345678",
        "detectedNamespaceKey": "FE",
        "purchaseInvoiceId": "c3f1...",
        "purchaseMessageId": "a91c...",
        "s3Key": "compras/c3f1.../comprobante.xml",
        "mensajeReceptor": {
          "purchaseInvoiceId": "c3f1...",
          "status": "ok",
          "clave": "50624102600310123456700100001010000000042112345678",
          "estadoEnvio": "no_enviado"
        }
      }
    ],
    "mensajes": {
      "exitosos": 1,
      "fallidos": 0,
      "omitidos": 0,
      "resultados": [
        {
          "purchaseInvoiceId": "c3f1...",
          "status": "ok",
          "clave": "50624102600310123456700100001010000000042112345678",
          "estadoEnvio": "no_enviado"
        }
      ]
    }
  }
}

{
  "estado": "rechazado",
  "detalleMensaje": "-17, \"Número de cédula física/jurídica/NITE/DIMEX receptor no posee la estructura establecida para el mismo\", 0, 0\n-38, \"El número de identificación del receptor no corresponde a un registro válido, Favor verificar\", 0, 0"
}

// El detalle trae líneas «-17, "mensaje", fila, columna».
const errores = (detalle ?? "")
  .split("\n")
  .map((linea) => linea.match(/^\s*(-\d+),\s*"(.*)",\s*(\d+),\s*(\d+)/))
  .filter(Boolean)
  .map((m) => ({ codigo: m[1], mensaje: m[2], fila: Number(m[3]), columna: Number(m[4]) }))

// -1   → unidad de medida inválida
// -17  → identificación del receptor mal formada
// -38  → identificación del receptor no registrada en Hacienda

// La URL base ya incluye el prefijo /api. No lo duplique en las rutas.
const BASE = process.env.VT_API_BASE ?? "https://sandbox.vision-total.rogcr.com/api";

async function api(path, { method = "GET", body, token } = {}) {
  const headers = { Accept: "application/json" };
  if (token) headers.Authorization = `Bearer ${token}`;
  if (body) headers["Content-Type"] = "application/json";

  const res = await fetch(`${BASE}${path}`, {
    method,
    headers,
    body: body ? JSON.stringify(body) : undefined,
  });

  const text = await res.text();
  const data = text ? JSON.parse(text) : null;

  if (!res.ok) {
    const err = new Error(data?.message ?? `HTTP ${res.status}`);
    err.code = data?.code;
    err.status = res.status;
    throw err;
  }
  return data;
}

// Un 404 en el padrón NO es un fallo del API: es la respuesta que el servicio
// necesita para decidir si el receptor es facturable.
async function consultarContribuyente(identificacion, token) {
  try {
    const contribuyente = await api(`/facturacion/taxpayers/${identificacion}`, { token });
    return { registrado: true, contribuyente };
  } catch (err) {
    if (err.status === 404) return { registrado: false, contribuyente: null };
    throw err;
  }
}

// Los códigos de rechazo de Hacienda vienen en el texto del detalle, no en el
// campo `code` de la respuesta.
function parseCodigosHacienda(detalle) {
  return (detalle ?? "")
    .split("\n")
    .map((linea) => linea.match(/^\s*(-\d+),\s*"(.*)",\s*(\d+),\s*(\d+)/))
    .filter(Boolean)
    .map((m) => ({ codigo: m[1], mensaje: m[2], fila: Number(m[3]), columna: Number(m[4]) }));
}

// 1 · La credencial de máquina ES la sesión. No hay login ni select-organization:
//     el token lo entrega el administrador (Ajustes → Claves API (M2M)) y se
//     envía tal cual en cada llamada.
const token = process.env.VT_TOKEN;

// 2 · Verificar la credencial: organización, rol y nombre de la credencial.
const sesion = await api("/m2m/me", { token });
if (!sesion?.organization?.id) throw new Error("Credencial M2M inválida o sin organización.");
// La organización sale del token: nunca se envía en el cuerpo de la petición.
const organizationId = sesion.organization.id;

// 3 · Estado de la configuración de facturación
const connection = await api("/facturacion/connection", { token });
if (!connection.facturacionConfigured) {
  throw new Error("La organización aún no tiene la facturación electrónica activada.");
}

// 4 · Catálogo de unidades de medida: la única fuente de verdad del código
//     que se manda en `unidadMedida`. Se consulta una vez y se cachea.
const unidades = await api("/units-of-measure", { token });   // array plano

const porCodigo = new Map(unidades.map((u) => [u.code, u]));

// La línea lleva el `code` que devuelve el catálogo, tal cual.
const unidadDe = (codigo) => porCodigo.get(codigo)?.code ?? porCodigo.get("Unid").code;

// 5 · Verificar el receptor en el padrón de Hacienda ANTES de facturar.
//     Un 404 aquí significa que el comprobante sería rechazado con -38.
const padron = await consultarContribuyente("3109876543", token);
if (!padron.registrado) {
  throw new Error("El contribuyente 3109876543 no está en el padrón de Hacienda.");
}

// El nombre y la actividad económica salen del padrón, no de un campo a mano.
// Los códigos CIIU4 llevan punto ("4610.0"), tal como los devuelve Hacienda.
const nombreReceptor = padron.contribuyente.nombre;
const actividadesReceptor = padron.contribuyente.actividades?.filter((a) => a.estado === "A") ?? [];
const actividadReceptor = actividadesReceptor[0]?.codigo;

// 6 · Cliente. El catálogo de actividades se guarda tal cual: el API exige
//     que `actividadEconomicaReceptor` sea uno de estos códigos.
const customer = await api("/customers", {
  method: "POST",
  token,
  body: {
    name: nombreReceptor,
    governmentId: "3109876543",
    governmentIdType: "02",
    email: "facturacion@wegner.cr",
    economicActivities: actividadesReceptor.map((a) => a.codigo),
  },
});

// 7 · Producto con CABYS (sin CABYS real no hay comprobante válido).
//     La unidad se toma del catálogo: `unitOfMeasureId` es el id de la fila.
const product = await api("/products", {
  method: "POST",
  token,
  body: {
    name: "Café molido 250 g",
    sku: "CAF-250",
    price: 10700,
    costPrice: 6500,
    productType: "product",
    cabys: "5897000000000",
    codigoImpuesto: "01",
    tarifaIvaCode: "08",
    codigoMoneda: "CRC",
    unitOfMeasureId: porCodigo.get("Unid").id,
  },
});

// 8 · Factura en borrador. La unidad sale del catálogo de la API: si se omite,
//     el API escribe «Unid».
const invoice = await api("/invoices", {
  method: "POST",
  token,
  body: {
    documentType: "01",
    customerId: customer.id,
    sucursalCodigo: "001",
    numeroTerminal: "00001",
    condicionVenta: "01",
    actividadEconomicaReceptor: actividadReceptor,
    items: [
      {
        productId: product.id,
        quantity: 1,
        price: 10700,
        taxRate: 0.13,
        tarifaIvaCode: "08",
        detalle: "Café molido 250 g",
        unidadMedida: unidadDe(product.unitOfMeasure?.code),
      },
    ],
  },
});

// 9 · Pago
await api(`/invoices/${invoice.data.id}/payments`, {
  method: "POST",
  token,
  body: { payments: [{ method: "cash", amount: 12091, customerAmount: 12091 }] },
});

// 10 · Emisión
const issued = await api(`/invoices/${invoice.data.id}/facturar`, {
  method: "POST",
  token,
  body: {
    documentType: "01",
    customerId: customer.id,
    actividadEconomicaReceptor: actividadReceptor,
  },
});

// 11 · Sondeo del estado: el veredicto lo da `estado`, nunca el detalle.
const ESTADOS_FINALES = new Set(["aceptado", "accepted", "rechazado", "rejected", "error"]);
let status;
for (let i = 0; i < 20; i++) {
  await new Promise((r) => setTimeout(r, 3000));
  status = await api(`/facturacion/documents/${issued.data.haciendaDocumentId}/status`, { token });
  if (ESTADOS_FINALES.has(status.data.estado)) break;
}

const avisos = parseCodigosHacienda(status.data.detalleMensaje);  // p. ej. el -20 del teléfono
console.log(status.data.estado, issued.data.clave, avisos);

// 12 · El consecutivo no viene en la respuesta de emisión: se lee del detalle.
const detail = await api(`/invoices/${invoice.data.id}`, { token });
const consecutivo = detail.data.haciendaDocuments?.[0]?.numeroConsecutivo;
console.log("Consecutivo", consecutivo);

import os
import re
import time
import requests

# La URL base ya incluye el prefijo /api. No lo duplique en las rutas.
BASE = os.environ.get("VT_API_BASE", "https://sandbox.vision-total.rogcr.com/api")
SESSION = requests.Session()

# Códigos de rechazo de Hacienda: vienen en el texto del detalle, no en `code`.
PATRON_CODIGOS = re.compile(r'^\s*(-\d+),\s*"(.*)",\s*(\d+),\s*(\d+)')

# La unidad de la línea sale del catálogo de la API: es la única fuente de
# verdad. No se escribe el código a mano ni se mantiene una lista local.
ESTADOS_FINALES = {"aceptado", "accepted", "rechazado", "rejected", "error"}


def api(path, method="GET", **kwargs):
    response = SESSION.request(method, f"{BASE}{path}", timeout=30, **kwargs)
    if not response.ok:
        raise RuntimeError(f"{response.status_code} {response.text}")
    return response.json() if response.content else None


def consultar_contribuyente(identificacion):
    """Un 404 significa «no registrado en el padrón», no un fallo del API."""
    response = SESSION.get(f"{BASE}/facturacion/taxpayers/{identificacion}", timeout=30)
    if response.status_code == 404:
        return None
    if not response.ok:
        raise RuntimeError(f"{response.status_code} {response.text}")
    return response.json()


def codigos_hacienda(detalle):
    errores = []
    for linea in (detalle or "").split("\n"):
        m = PATRON_CODIGOS.match(linea)
        if m:
            errores.append({"codigo": m.group(1), "mensaje": m.group(2),
                            "fila": int(m.group(3)), "columna": int(m.group(4))})
    return errores


def unidad_de(codigo):
    """El `code` del catálogo, sin transformaciones. Si no hay unidad, «Unid»."""
    return POR_CODIGO.get(codigo, POR_CODIGO["Unid"])["code"]


# La credencial de máquina ES la sesión: no hay login ni select-organization.
# El token lo entrega el administrador (Ajustes → Claves API (M2M)) y se envía
# tal cual en cada llamada.
TOKEN = os.environ.get("VT_TOKEN")
if not TOKEN:
    raise RuntimeError("Falta VT_TOKEN: la credencial de máquina (M2M)")

SESSION.headers.update({"Authorization": f"Bearer {TOKEN}"})

# Verificar la credencial: organización, rol y nombre de la credencial.
sesion = api("/m2m/me")
# La organización sale del token: nunca se envía en el cuerpo de la petición.
organization_id = sesion["organization"]["id"]

# Catálogo de unidades de medida: la única fuente de verdad del código que se
# manda en `unidadMedida`. Se consulta una vez y se cachea.
UNIDADES = api("/units-of-measure")

POR_CODIGO = {u["code"]: u for u in UNIDADES}

connection = api("/facturacion/connection")
if not connection["facturacionConfigured"]:
    raise RuntimeError("Facturación electrónica no activada")

# Verificar el receptor en el padrón ANTES de facturar: si no existe,
# Hacienda rechazará el comprobante con -38.
contribuyente = consultar_contribuyente("3109876543")
if contribuyente is None:
    raise RuntimeError("El contribuyente 3109876543 no está en el padrón de Hacienda")

nombre_receptor = contribuyente["nombre"]
actividades = [a for a in contribuyente.get("actividades", []) if a.get("estado") == "A"]
actividad_receptor = actividades[0]["codigo"] if actividades else None

# El catálogo de actividades se guarda tal cual (los CIIU4 llevan punto:
# "4610.0"): el API exige que `actividadEconomicaReceptor` sea uno de ellos.
customer = api("/customers", method="POST", json={
    "name": nombre_receptor,
    "governmentId": "3109876543",
    "governmentIdType": "02",
    "email": "facturacion@wegner.cr",
    "economicActivities": [a["codigo"] for a in actividades],
})

# Producto con CABYS real: sin él no hay comprobante válido en producción.
# La unidad sale del catálogo: `unitOfMeasureId` es el id de la fila.
product = api("/products", method="POST", json={
    "name": "Café molido 250 g",
    "sku": "CAF-250",
    "price": 10700,
    "costPrice": 6500,
    "productType": "product",
    "cabys": "5897000000000",
    "codigoImpuesto": "01",
    "tarifaIvaCode": "08",
    "codigoMoneda": "CRC",
    "unitOfMeasureId": POR_CODIGO["Unid"]["id"],
})

invoice = api("/invoices", method="POST", json={
    "documentType": "01",
    "customerId": customer["id"],
    "sucursalCodigo": "001",
    "numeroTerminal": "00001",
    "condicionVenta": "01",
    "actividadEconomicaReceptor": actividad_receptor,
    "items": [{
        "productId": product["id"],
        "quantity": 1,
        "price": 10700,
        "taxRate": 0.13,
        "tarifaIvaCode": "08",
        "detalle": "Café molido 250 g",
        "unidadMedida": unidad_de((product.get("unitOfMeasure") or {}).get("code")),
    }],
})

api(f"/invoices/{invoice['data']['id']}/payments", method="POST", json={
    "payments": [{"method": "card", "amount": 12091, "customerAmount": 12091}],
})

issued = api(f"/invoices/{invoice['data']['id']}/facturar", method="POST",
             json={"documentType": "01", "customerId": customer["id"],
                   "actividadEconomicaReceptor": actividad_receptor})

# Sondear hasta el final: el veredicto lo da `estado`, nunca el detalle.
for _ in range(20):
    time.sleep(3)
    status = api(f"/facturacion/documents/{issued['data']['haciendaDocumentId']}/status")
    if status["data"]["estado"] in ESTADOS_FINALES:
        break

print(status["data"]["estado"], issued["data"]["clave"])
print("Avisos:", codigos_hacienda(status["data"].get("detalleMensaje")))

# El consecutivo no viene en la respuesta de emisión: se lee del detalle.
detail = api(f"/invoices/{invoice['data']['id']}")
documentos = detail["data"].get("haciendaDocuments") or []
print("Consecutivo:", documentos[0]["numeroConsecutivo"] if documentos else None)

DOC_ID="d41b..."
TOKEN="..."

for kind in pdf xml mensaje-xml; do
  curl -sS -f "https://sandbox.vision-total.rogcr.com/api/facturacion/documents/$DOC_ID/$kind" \
    -H "Authorization: Bearer $TOKEN" \
    -o "comprobante.$kind" \
    || echo "El artefacto $kind todavía no está disponible"
done

ls -lh comprobante.*