Ciclo de una clasificación

Crear una clasificación es asincrónico: POST /classifications responde 202 enseguida y el dictamen llega después. Tu integración consulta el estado hasta que termina.

Estados

`status`	Qué significa	¿Descuenta un crédito?
`in_progress`	Está clasificando. `stage` dice la etapa.	Lo aparta: vuelve si no se resuelve
`pending_data`	El clasificador necesita datos. `questions` trae las preguntas.	No, hasta que se resuelva
`resolved`	Hay dictamen. `candidates` trae las opciones.	Sí, 1 crédito
`failed`	No se pudo completar. `failure_reason` dice por qué.	No
`abandoned`	Esperó respuestas 30 días y nadie respondió.	No

resolved, failed y abandoned son finales. Pueden aparecer estados nuevos en el futuro: tratá cualquier valor desconocido como «todavía no terminó».

Esperar el resultado

Consultá GET /classifications/{id} cada 3 segundos mientras status sea in_progress. Suele tardar alrededor de un minuto.

async function waitForVerdict(id) {
  for (;;) {
    const response = await fetch(`https://api.nomenclator.com.ar/v1/classifications/${id}`, {
      headers: { Authorization: `Bearer ${process.env.NOMENCLATOR_API_KEY}` },
    });
    const classification = await response.json();
    if (classification.status !== "in_progress") return classification;
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

Mientras está en curso, stage va pasando por extraction, retrieval, verdict, validation y sim; después de responder preguntas arranca por answers_intake. Sirve para mostrar el progreso; no hace falta que tu integración dependa del orden.

Cuando pide datos

Con pending_data, la clasificación trae las preguntas:

{
  "status": "pending_data",
  "questions": [
    {
      "id": "q1",
      "text": "¿La bomba es sumergible?",
      "options": ["Sí", "No"]
    }
  ],
  "candidates": [ /* propuesta provisional, si la hay */ ],
  "candidates_are_provisional": true
}

Respondé con POST /classifications/{id}/answers, con un question_id y una answer de hasta 500 caracteres por pregunta. Podés sumar una ficha nueva en file_url. La clasificación vuelve a in_progress y seguís consultando igual que antes.

Responder no suma costo. La clasificación descuenta 1 crédito en total, al resolverse. Al responder se vuelve a apartar ese crédito: sin saldo, la respuesta es 402 y la clasificación sigue esperando.
Hay una sola ronda de preguntas.
Si nadie responde en 30 días, pasa a abandoned sin costo.
Si la clasificación no está esperando respuestas, el pedido devuelve 409 conflict.

Cuando falla

failure_reason puede ser:

Valor	Qué pasó
`no_valid_candidates`	No encontramos un NCM válido para esa descripción. Probá con más detalle o con la ficha.
`unreadable_pdf`	No pudimos procesar el PDF.
`timed_out`	Tardó más de lo esperado y se canceló.
`service_unavailable`	El clasificador no estaba disponible.
`unexpected_format`	El clasificador devolvió una respuesta inesperada.
`persist_failed`	No pudimos guardar el resultado.

Ninguna descuenta créditos. Para reintentar, creá una clasificación nueva con otra Idempotency-Key.

Clasificaciones simultáneas

Tu organización puede tener hasta 10 clasificaciones en curso a la vez con la API. Si pasás ese número, el pedido devuelve 429. Mirá límites.

Empezá acá

Conceptos

Clasificaciones

Referencia arancelaria

Cuenta

Ciclo de una clasificación

Estados

Esperar el resultado

Cuando pide datos

Cuando falla

Clasificaciones simultáneas

​Estados

​Esperar el resultado

​Cuando pide datos

​Cuando falla

​Clasificaciones simultáneas

Estados

Esperar el resultado

Cuando pide datos

Cuando falla

Clasificaciones simultáneas