Crear Items

Crear Items

Pruebas

Dominio: https://test-api-factura.edw-dev.com

Producción

Dominio: https://api-financiero.e-dinky.com

Este endpoint permite crear nuevos items (bienes y servicios) en el sistema.

Crear Item

Endpoint: POST /api/v1/items/create

Descripción: Crea un nuevo item en el sistema.

Headers Requeridos

Accept: application/json
Content-Type: application/json
Authorization: Bearer {token}

Cuerpo de la Solicitud

Campo	Tipo	Requerido	Descripción
code	string	Sí	Código único del item
description	string	Sí	Descripción del item
rate	number	Sí	Precio unitario del item
unit	string	Sí	Unidad de medida
type	string	No	Tipo de item: PRODUCT o SERVICE (por defecto: PRODUCT)
allow_accounting	integer	No	Permite contabilidad de inventario (0 o 1)
count_available	integer	No	Cantidad disponible en inventario
taxes	array	Sí	Array de impuestos aplicables
taxes[].percentaje	string	Sí	Porcentaje del impuesto
taxes[].code	string	Sí	Código del tipo de impuesto
taxes[].percentaje_code	string	Sí	Código del porcentaje específico

Ejemplos de Solicitud

Item Básico

{
  "code": "PROD-001",
  "description": "Producto de ejemplo",
  "rate": 25.50,
  "unit": "Unidad",
  "type": "PRODUCT",
  "taxes": [
    {
      "percentaje": "15",
      "code": "2",
      "percentaje_code": "4"
    }
  ]
}

Item con Inventario

{
  "code": "PROD-002",
  "description": "Producto con inventario",
  "rate": 45.75,
  "unit": "Unidad",
  "type": "PRODUCT",
  "allow_accounting": 1,
  "count_available": 100,
  "taxes": [
    {
      "percentaje": "15",
      "code": "2",
      "percentaje_code": "4"
    }
  ]
}

Servicio

{
  "code": "SERV-001",
  "description": "Servicio de consultoría",
  "rate": 150.00,
  "unit": "Hora",
  "type": "SERVICE",
  "taxes": [
    {
      "percentaje": "15",
      "code": "2",
      "percentaje_code": "4"
    }
  ]
}

Ejemplos de Implementación

cURL

curl -X POST "https://dev-facturacion.e-dinky.test/api/v1/items/create" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here" \
  -d '{
    "code": "PROD-001",
    "description": "Producto de ejemplo",
    "rate": 25.50,
    "unit": "Unidad",
    "type": "PRODUCT",
    "taxes": [
      {
        "percentaje": "15",
        "code": "2",
        "percentaje_code": "4"
      }
    ]
  }'

Laravel PHP

use Illuminate\Support\Facades\Http;

$itemData = [
    'code' => 'PROD-001',
    'description' => 'Producto de ejemplo',
    'rate' => 25.50,
    'unit' => 'Unidad',
    'type' => 'PRODUCT',
    'taxes' => [
        [
            'percentaje' => '15',
            'code' => '2',
            'percentaje_code' => '4'
        ]
    ]
];

$response = Http::withHeaders([
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
    'Content-Type' => 'application/json'
])->post('https://dev-facturacion.e-dinky.test/api/v1/items/create', $itemData);

$newItem = $response->json();

Node.js

const axios = require('axios');

const createItem = async (token, itemData) => {
  try {
    const response = await axios.post('https://dev-facturacion.e-dinky.test/api/v1/items/create', itemData, {
      headers: {
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    });
    return response.data;
  } catch (error) {
    console.error('Error:', error.response.data);
  }
};

// Uso
const itemData = {
  code: 'PROD-001',
  description: 'Producto de ejemplo',
  rate: 25.50,
  unit: 'Unidad',
  type: 'PRODUCT',
  taxes: [
    {
      percentaje: '15',
      code: '2',
      percentaje_code: '4'
    }
  ]
};

createItem(token, itemData);

Respuesta Exitosa (201 Created)

{
  "message": "Registro creado",
  "status": "CREATED",
  "payload": {
    "code": "PROD-001",
    "description": "Producto de ejemplo",
    "rate": 25.5,
    "unit": "Unidad",
    "type": "PRODUCT",
    "taxes": [
      {
        "type_name": "IVA",
        "name": "15%",
        "percentaje_tax": "15.00",
        "type_tax_code": "2",
        "tax_code": "4"
      }
    ]
  }
}

Respuesta de Error (422 Unprocessable Entity)

{
  "message": "Error de validación",
  "status": "UNPROCESSABLE_ENTITY",
  "errors": {
    "code": [
      "El código ya existe en el sistema"
    ]
  }
}

Códigos de Respuesta

Código	Descripción
201	Item creado exitosamente
400	Error en los datos enviados
401	Token de autorización inválido
422	Error de validación (código duplicado)
500	Error interno del servidor

Validaciones

Campos Obligatorios

• code: Debe ser único en el sistema
• description: No puede estar vacío
• rate: Debe ser un número positivo
• unit: No puede estar vacío
• taxes: Debe contener al menos un impuesto

Reglas de Negocio

• El código del item debe ser único
• Los códigos de impuestos deben existir en el sistema LOVs
• Si type es SERVICE, no se puede establecer allow_accounting = 1
• Si allow_accounting = 1, se puede especificar count_available

Notas Importantes

• Códigos únicos: El campo code debe ser único en todo el sistema
• Tipos de items: PRODUCT para productos físicos, SERVICE para servicios
• Inventario: Solo los productos pueden manejar inventario (allow_accounting = 1)
• Impuestos: Los códigos deben corresponder a valores válidos en el sistema LOVs
• Precios: Se manejan con 2 decimales de precisión
• Unidades: Pueden ser cualquier texto descriptivo (Unidad, Kg, Litro, etc.)

Ejemplos de Uso Común

Producto con Control de Inventario

{
  "code": "LAPTOP-001",
  "description": "Laptop Dell Inspiron 15",
  "rate": 899.99,
  "unit": "Unidad",
  "type": "PRODUCT",
  "allow_accounting": 1,
  "count_available": 50,
  "taxes": [
    {
      "percentaje": "15",
      "code": "2",
      "percentaje_code": "4"
    }
  ]
}

Servicio Profesional

{
  "code": "CONSULT-HR",
  "description": "Consultoría en Recursos Humanos",
  "rate": 75.00,
  "unit": "Hora",
  "type": "SERVICE",
  "taxes": [
    {
      "percentaje": "15",
      "code": "2",
      "percentaje_code": "4"
    }
  ]
}