🗓️ Importante: La información de este artículo aplicará a partir del 10 de marzo.
Cuando creas documentos de ingreso vía API pública, Quipu necesita saber si:
debe asignar la numeración (porque el documento “nace” en Quipu), o
debe registrar un número que ya existe (porque el documento ya estaba emitido fuera).
La API lo decide con una regla muy simple: si envías el número de documento o no.
Cómo decide Quipu el tipo de serie
A) En la API NO informas el número (solo envías la serie)
Quipu asigna numeración correlativa → Documentos nuevos
Necesitas una serie configurada como Para documentos nuevos.
Cuándo usar este caso
Cuando quieres que Quipu sea quien lleve la numeración.
Cuando estás creando facturas “desde cero” desde una integración.
B) En la API SÍ informas el número (envías serie + número)
Quipu registra el número que envías → Documentos existentes
Necesitas una serie configurada como Para documentos existentes.
Cuándo usar este caso
Cuando estás migrando históricos.
Cuando el número ya existe porque el documento fue emitido fuera de Quipu.
Qué tienes que tener preparado (antes de usar API)
En Configuración → Numeración asegúrate de tener:
una serie para el tipo de documento (por ejemplo, Facturas) configurada como Documentos nuevos
y, si vas a registrar históricos, otra serie configurada como Documentos existentes
Recomendación: usa nombres/prefijos distintos para identificarlas fácilmente (por ejemplo, A- para existentes y AQ- para nuevos). No es obligatorio, pero evita errores
Errores típicos y cómo resolverlos
“He enviado una serie, pero Quipu no numera como esperaba”
Revisa qué estás enviando en la API:
Si no envías número, Quipu numera (nuevos).
Si envías número, Quipu registra ese número (existentes).
“Estoy registrando históricos y me lo trata como nuevo”
Suele pasar porque no estás enviando el número.
Solución: envía serie + número y usa una serie de Documentos existentes.
“Estoy creando documentos nuevos y me da conflicto con la serie”
Suele pasar cuando la serie que estás usando está configurada como Documentos existentes.
Solución: en Configuración → Numeración, usa una serie configurada como Documentos nuevos para creación desde API.
Buenas prácticas (cuando usas API para varias cosas)
Si usas API para:
crear facturas desde cero, y
migrar históricos
…lo más limpio es tener dos series separadas:Serie API para Documentos nuevos
Serie API para Documentos existentes
Esto reduce errores y hace que el equipo identifique rápido qué está pasando.