Cotizar

Antes de emitir podés preguntar cuánto impuesto lleva una venta. No crea nada, no consume consecutivos y no toca a Hacienda.

curl -X POST https://api.timbre.cr/internal/v1/quotes \
  -H "Authorization: Bearer timbre_sk_…" \
  -H 'Content-Type: application/json' \
  -d '{
    "issuerId": "…",
    "lines": [
      {
        "lineNumber": 1,
        "cabys": "2312000000300",
        "detail": "Harina de arroz, saco de 25 kg",
        "quantity": "2.000",
        "unitOfMeasure": "Unid",
        "unitPrice": "5000.00000"
      }
    ]
  }'

La respuesta trae cada línea calculada y un resumen:

{
  "catalogVersion": "…",
  "lines": [
    {
      "numeroLinea": 1,
      "subTotal": "10000.00000",
      "baseImponible": "10000.00000",
      "impuesto": [
        { "codigo": "01", "codigoTarifaIVA": "08", "monto": "1300.00000" }
      ],
      "impuestoNeto": "1300.00000",
      "montoTotalLinea": "11300.00000"
    }
  ],
  "resumen": {
    "totalMercanciasGravadas": "10000.00000",
    "totalVenta": "10000.00000",
    "totalImpuesto": "1300.00000",
    "totalComprobante": "11300.00000"
  },
  "provenance": [],
  "warnings": []
}

El dinero es texto

"5000.00000", no 5000.00000.

Un número en JSON es un double, y un double no representa exactamente los decimales que la ley te obliga a declarar. La diferencia aparece como un colón de más en un total que Hacienda rechaza. Timbre recibe y devuelve montos como cadenas decimales, siempre.

De dónde sale la tarifa

De la línea vos mandás el código CAByS. La tarifa sale del catálogo, no de vos: no hay campo para declarar cuánto IVA lleva algo.

provenance explica cada decisión —de qué versión del catálogo salió la tarifa, qué regla se aplicó y con cuánta confianza— para que puedas auditar por qué un impuesto quedó como quedó.

Si el comprador está exonerado

Es un dato del documento, no de una línea: mandá exoneration.authorizationNumber con el número que le dio Hacienda al comprador. Timbre lo verifica contra Hacienda una sola vez y lo aplica línea por línea según qué CAByS cubre —una autorización que cubre solo algunas líneas es normal, y esas otras quedan gravadas completas.

Un número que Hacienda no reconoce, vencido, o que no cubre ninguna línea del documento se rechaza en vez de facturarse a precio completo en silencio. Errores tiene el detalle de cada exoneration_*.

Verificar tu propio cálculo

Si ya calculás el total en tu lado y querés que Timbre lo confirme en vez de solo confiar, mandá expectedTotal. Si no coincide con lo que Timbre deriva, la respuesta es expected_total_mismatch en vez de un documento firmado sobre un número que no es el que esperabas.