Límites de la v1
Esta página existe para que diseñes tu integración con la información completa, no para que la descubras en producción.
Lo que la v1 no hace
| No puedes | Alternativa hoy |
|---|---|
| Facturar al crédito | Solo contado. isCredit: true da 422. |
| Anular una factura | Desde la app de Contadito. Puedes leer isAnnulled. |
| Consultar o crear productos | El mapeo de externalProductId lo carga el personal de Contadito. |
| Buscar un cliente por RTN o nombre | GET /v1/clients lista todos (paginado, ordenado por nombre). Filtra de tu lado. |
| Listar o buscar facturas | Guarda el id que te devuelve POST /v1/invoices. |
| Emitir facturas de prueba | Prueba con POST /v1/invoices/preview, que no consume CAI. Cada POST /v1/invoices sí emite una factura legal. |
| Actualizar o borrar un cliente | Desde la app de Contadito. |
| Facturar con fecha retroactiva | invoiceDate en el pasado está fuera de alcance. |
| Notas de crédito o débito | Desde la app de Contadito. |
| Webhooks | No hay. La comunicación es solo solicitud/respuesta. |
| Enviar impuestos propios | La tasa de ISV y el exento salen del producto en el catálogo. El precio sí puedes mandarlo con items[].price. |
| Emitir para varias empresas con una key | Una key = una empresa. |
Decisiones que te conviene tomar desde el día uno
Guarda los ids. Es la más importante. Un id de factura que no
persistas es un dato perdido: no hay listado de facturas. Los de cliente sí se
pueden recuperar con GET /v1/clients, pero bajando la lista entera y
filtrando tú. Guárdalos en la misma transacción en la que registras la venta.
Persiste el Idempotency-Key antes de llamar. Ver
Idempotencia. Es lo que separa "reintentar es seguro" de
"acabo de emitir una factura legal duplicada".
Programa contra code. Nunca contra message, nunca contra el texto de un
error.
Encola cuando el error sea de configuración. Los INTEGRATION_* no se
arreglan reintentando. Deja la venta en estado "pendiente de facturar" y alerta
a un humano, en vez de perderla.
Prueba con la previsualización.
POST /v1/invoices/preview usa el mismo
motor y la misma plantilla que la emisión real, sin efectos. Es donde deberías
probar tu integración antes de emitir.
No pongas la key en el cliente. Llama a la API desde tu backend.
Compatibilidad
La v1 puede agregar campos a las respuestas sin previo aviso. Tu parser debe ignorar campos que no conoce.
Lo que no cambiará sin una versión nueva:
- La forma de los errores:
{ code, message }. - El significado de los
codeexistentes. - El significado de los campos existentes.
isCredit ya está en el contrato justamente para que agregar facturas de
crédito en v2 no sea un cambio incompatible.
OpenAPI
La especificación se genera desde el código, así que nunca queda desfasada:
- Swagger UI en vivo:
https://integration.contadito.com/v1/docs - YAML:
https://integration.contadito.com/v1/docs-yaml - Copia estática de esta documentación: openapi.yaml
Úsala para generar clientes automáticamente si tu lenguaje lo permite.
¿Necesitas algo de esta lista?
Escríbele a tu contacto en Contadito diciendo qué caso de negocio te bloquea, no solo qué endpoint quieres. La v2 se prioriza con eso.