Solicitud de Categorización de Documento con IA

Este endpoint inicia una tarea asíncrona que utiliza Inteligencia Artificial (IA) para categorizar un documento electrónico (como una factura) basándose en su clave de acceso (identifier) y el contribuyente asociado. La categorización final será notificada por Webhook.

Detalles Técnicos

Endpoint y Método

• Método: POST
• Endpoint: /tasks - Como todas las tareas de fondo, se usa para crearlas

Headers Requeridos

• Content-Type: application/json - Para indicar que enviamos un JSON
• x-api-key: [Tu Clave] - Tu credencial de autenticación

Estructura del Body/Payload

El cuerpo JSON define la tarea de categorización:

• type (string, requerido): El tipo de tarea de categorización. Valor: "CATEGORY.INVOICE"
• taxpayerId (string, requerido): El RUC o ID del contribuyente asociado al documento
• identifier (string, requerido): La clave de acceso del documento electrónico a categorizar (ej. factura)

Código de Ejemplo

const axios = require('axios');
let data = JSON.stringify({
  "type": "CATEGORY.INVOICE",
  "taxpayerId": "1726051285001",
  "identifier": "2404202407176001321000120590020011861860000000012"
});

let config = {
  method: 'post',
  url: 'https://staging-api.taxo.ws/tasks',
  headers: { 
    'x-api-key': 'tu_api_key',
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Respuesta de la solicitud

La respuesta es una simple confirmación de que la tarea de IA ha sido aceptada y encolada:

{
  "status": "success",
  "data": {
    "id": "a6451273-eaca-4e50-bfa8-fe22f45097d5",
    "createdAt": "2025-11-13T16:34:02.000Z",
    "status": "INITIALIZED"
  }
}

Campos de la Respuesta

• status (string): "success"
• data.id (string): El identificador único de la tarea de categorización
• data.createdAt (string): Marca de tiempo de la solicitud
• data.status (string): El estado inicial, "INITIALIZED"

Código de Respuesta HTTP

201 Created: La solicitud para la categorización por IA fue recibida y se ha creado una nueva tarea pendiente de ejecución.

Por defecto todas las tareas de categorización empiezan en el estado INITIALIZED que nos indica que la tarea ha sido iniciada y podemos hacer su seguimiento en el webhook.