Preguntas frecuentes
Me da PRODUCT_NOT_FOUND y el producto sí existe en Contadito
Existe en el catálogo, pero tu externalProductId no está mapeado a él. Son
dos cosas distintas: el mapeo lo carga el personal de Contadito. Mándale la
lista de tus SKUs.
Me da 403 INTEGRATION_NOT_ENABLED y mi key es correcta
Correcto: la key es válida, pero tu empresa no tiene la integración habilitada —o le falta configuración—. No es algo que puedas resolver desde tu código. Ver Primeros pasos.
Perdí mi API key
No se puede recuperar: solo guardamos un hash. Emite una nueva desde la app y revoca la anterior.
¿Puedo tener más de una key activa?
Hasta dos. Es lo justo para rotar sin cortar el servicio. Una tercera activa nunca es un estado legítimo de rotación.
Se me cayó la conexión al crear una factura. ¿Reintento?
Sí, con la misma Idempotency-Key y el mismo body. Si la factura ya se
había emitido, te la devolvemos con replayed: true y no se crea una segunda.
Ver Idempotencia.
replayed: true, ¿es un error?
No. Es lo contrario: confirma que tu reintento no duplicó nada. Trátalo como éxito.
¿Puedo mandar mi propio precio?
Sí, por línea, con
items[].price. Si lo
omites se usa el precio de la lista configurada para tu empresa. El precio que
mandas vale solo para esa factura: no cambia el catálogo.
¿Y el impuesto?
Ese no. La tasa de ISV y la condición de exento salen siempre del producto en el catálogo, mandes o no un precio. Si están mal, se corrigen ahí.
Mandé un price y el total no bajó lo que esperaba
Revisa si el producto es parcialmente gravado: el monto exento por unidad viene del catálogo y no se reescala con tu precio, así que la porción gravada absorbe toda la diferencia. Ver Conceptos de facturación.
¿Cómo consulto una factura si solo tengo el número de factura?
No se puede: GET /v1/invoices/{id} usa el id interno, no el
invoiceNumber. Guarda el id al emitir.
¿Cómo busco un cliente que ya registré?
Con GET /v1/clients, que devuelve todos tus
clientes ordenados por nombre y con paginación opcional. No filtra por RTN
ni por nombre: el filtrado lo haces tú.
Por eso sigue valiendo el consejo: guarda el id de Contadito junto a tu propio
id de cliente cuando lo creas, y usa el listado para la carga inicial o para
reconciliar. Si intentas recrear un cliente que ya existe, obtendrás un 409.
count no coincide con la cantidad de clientes que recibí
Es correcto: count es el total de clientes de tu empresa, no el tamaño de
la página. Con ?page=1&limit=50 sobre 380 clientes, clients trae 50 y
count trae 380. ÚSalo para calcular las páginas: Math.ceil(count / limit).
Mandé page y me devolvió todos los clientes
La paginación es todo o nada: se aplica solo si mandas page y limit
juntos. Con uno solo se ignora y recibes la lista completa.
Mandé un campo extra en el body y me rechazó
Es a propósito: los campos desconocidos no se ignoran, se rechazan con
400 VALIDATION_FAILED. Un campo mal escrito que se ignora en silencio es peor
que un error.
taxBreakdown me trae dos entradas, ¿está mal?
No. Honduras tiene más de una tasa de ISV y una factura con productos de tasas distintas trae una entrada por tasa. Tu comprobante debe desglosarlas.
¿Cuál es la diferencia entre exento y exonerado?
Exento depende del producto; exonerado depende del cliente y requiere su RTN. Ver Conceptos de facturación.
¿Hay ambiente de pruebas?
Para probar tu integración usa
POST /v1/invoices/preview: calcula los
totales y renderiza el PDF con tu propia configuración, sin consumir CAI, sin
avanzar el correlativo y sin escribir nada. No necesita Idempotency-Key.
Si además necesitas emitir facturas de prueba de verdad, pídele a tu contacto en Contadito una empresa de prueba con su propia key y su propio rango. No emitas pruebas contra tu empresa de producción: cada factura consume un correlativo real.
¿Cómo obtengo el PDF de una factura?
POST /v1/invoices te lo devuelve en pdfBase64. Para reimprimirlo después,
GET /v1/invoices/{id}/pdf lo genera al momento.
En GET /v1/invoices/{id}, pdfBase64 siempre viene null.
¿Puedo entregarle a un cliente el PDF de una previsualización?
No. Sale marcado SIN VALIDEZ FISCAL y con el CAI enmascarado: no es un comprobante y no sustituye una factura.
¿Hay webhooks?
No en v1. La comunicación es solo solicitud/respuesta.
¿A quién le escribo cuando algo falla?
A tu contacto en Contadito, con: el code, la hora aproximada (con zona
horaria), el Idempotency-Key si fue una creación de factura, y el id de la
factura si ya existía. Nunca incluyas tu API key en el mensaje; si la
mandaste por error, revócala.