Cómo leer las respuestas y los errores¶

La API creció por etapas y no todos los llamados responden con la misma forma. Esta página reúne las formas que existen, qué significa cada código y qué conviene hacer en cada caso, para que tu integración las trate bien desde el primer día.

La regla práctica¶

Mira primero el código HTTP. 200 o 201 es éxito; 4xx es un problema del llamado; 5xx es un problema del servidor.
Después mira el cuerpo, según la familia del llamado (tabla de abajo).
En un éxito, revisa igual los avisos (warning o advertencia): el llamado funcionó, pero hay algo que deberías saber.

Las cuatro formas de respuesta¶

Familia de llamados	Éxito	Error
Documentos: emitir, nota de venta, documentar, anular	`{ "success": true, "message": "...", "data": { ... } }`	`{ "success": false, "message": "...", "errors": ["..."] }`
Reservas de stock	`{ "exito": true, ... }` o la lista pedida	`{ "exito": false, "faltantes": [...] }` o `{ "error": "..." }`
Consultas y mantenedores: productos, clientes, categorías, configuración, informes	El objeto o la lista directamente, sin envoltorio	`{ "error": "...", "detalle": "..." }`
Recepción de mercadería	`{ "exito": true, "mensaje": "..." }` en los llamados clásicos; `{ "success": true, "data": { ... } }` en guardar y confirmar	`{ "exito": false, "mensaje": "..." }` o `{ "error": "..." }`

La referencia muestra la forma exacta de cada llamado.

Documentos¶

{
  "success": true,
  "message": "Venta JSON procesada exitosamente. DTE 33 folio 100",
  "data": { "folio": 100, "token": "a1b2c3d4...", "pdf": "https://...", "warning": "" }
}

{
  "success": false,
  "message": "Sin FOLIOS",
  "errors": ["No hay folios asignados, debe asignar folios a la caja."]
}

message es el título del problema y errors trae el detalle. Muéstrale o registra los dos.

Reservas¶

{ "exito": true, "token": "carro-web-8f3a2b", "expiraEn": "2026-08-10T10:15:00" }

{ "exito": false,
  "faltantes": [ { "codigo": "A001", "solicitado": 2, "disponible": 1, "stockFisico": 3 } ] }

Consultas y mantenedores¶

{ "codigo": 1234, "rut": "76543210", "digito": "K", "razonSocial": "Empresa Cliente SPA" }

{ "error": "Cliente no encontrado" }

Una búsqueda sin resultados no es un error: responde 200 con una lista vacía ([]).

Los avisos: el llamado funcionó, pero...¶

Campo	Dónde aparece	Qué avisa
`data.warning`	Al emitir un documento	Los montos no cuadran; los precios se leyeron en un modo distinto al que usa la empresa; se envió forma de pago en una boleta. El documento sí se emitió.
`data.advertencia`	Al crear una nota de venta con `tokenReserva`	La reserva ya había vencido: el pedido se creó, pero el stock no está garantizado.

Un aviso nunca detiene la operación. Conviene registrarlo siempre y avisar a una persona, porque suele indicar un cálculo o un dato que hay que corregir en tu sistema.

Qué significa cada código¶

Código	Significado	Qué hacer
`200`	Funcionó.	Leer el cuerpo y los avisos.
`201`	Se creó el registro (por ejemplo, un cliente).	El cuerpo trae el registro con su código.
`400`	El llamado tiene un problema: falta un dato, un valor no es válido o una regla del negocio lo impide (sin folios, certificado vencido).	Leer el mensaje y corregir. Repetir el mismo llamado no sirve.
`401`	Faltan las credenciales, están mal escritas o la sesión venció (dura 1 hora).	Renovar la sesión o iniciar sesión de nuevo. Ver Primeros pasos.
`403`	La empresa no tiene habilitado el uso de la API, o su cuenta está suspendida.	Contactar a soporte. El cuerpo trae `Error` y `Mensaje`.
`404`	Lo que se busca no existe: un folio, un cliente, un carro reservado que ya venció.	Según el caso: corregir el dato o volver a crear.
`409`	El llamado es válido, pero choca con el estado actual.	Ver la tabla siguiente.
`500`	Error inesperado del servidor.	Ver "Reintentos". Si se repite, avisar a soporte con el mensaje.

Qué significa un `409` según el llamado¶

Llamado	Significado
`POST /reservas`	No hay stock suficiente. No se reservó nada; `faltantes` dice cuánto queda.
`POST /documento/procesar/json`	Ya hay una emisión en curso con el mismo `TransactionId`. Esperar el resultado.
`POST /documento/notaventa/{folio}/documentar`	El pedido ya fue documentado, está anulado u otra petición lo está documentando.
`POST /documento/notaventa/{folio}/anular`	El pedido ya está anulado o ya fue documentado.
`DELETE /recepciones/{id}`	La recepción ya fue importada a una compra.

Reintentos: cuándo repetir un llamado¶

El riesgo de repetir a ciegas es emitir dos veces. La regla:

Situación	¿Repetir?
`400`, `401`, `403`, `404`	No. Hay que corregir algo primero.
`409`	No repetir igual. Leer qué estado lo impide.
Timeout o `500` en una consulta (`GET`)	Sí, sin riesgo.
Timeout o `500` al reservar	Sí: reenviar el mismo carro con el mismo token reemplaza, no duplica.
Timeout o `500` al emitir un documento	Solo si enviaste `TransactionId`. Con el mismo valor, la API devuelve la respuesta original en vez de emitir otro folio. Sin `TransactionId`, consulta primero si el documento quedó emitido.
Timeout o `500` al documentar una nota de venta	Sí: un pedido no se documenta dos veces. Si el primer intento funcionó, el segundo responde `409`.

TransactionId es un identificador único que genera tu sistema (un UUID) y envías en POST /documento/procesar/json. Es la forma segura de reintentar una emisión; úsalo siempre. La API recuerda cada TransactionId durante 30 minutos, así que el reintento debe hacerse dentro de ese plazo y con el mismo total.

Convenciones de los datos¶

Nombres de campos. Las respuestas usan minúscula inicial (razonSocial, atpPublicable). Al enviar, la API no distingue mayúsculas de minúsculas: RazonSocial y razonSocial son lo mismo.
Fechas. yyyy-MM-dd o yyyy-MM-ddTHH:mm:ss.
Montos. En pesos, sin decimales para los totales de documentos.
RUT. En documentos y clientes va separado: rut sin puntos ni dígito verificador ("76543210") y digito aparte ("K"). Algunos llamados lo piden junto, con guion (76543210-K); la referencia lo indica.
Campos que no envías. Se toman como vacíos o cero. Revisa en cada guía cuáles son obligatorios.

Qué registrar siempre¶

Para que soporte pueda ayudarte rápido, guarda de cada llamado que falle:

la fecha y hora,
la URL y el método (POST /documento/procesar/json),
el código HTTP,
el cuerpo completo de la respuesta,
y, si es una emisión, el TransactionId y el folio.

Con eso, escribe a soporte@opentpv.cl.