# Ajustar existencias

`POST https://api.fiscalisto.com/v1/stock_adjustments`

Mete o saca existencias de un almacén con su motivo: el inventario inicial, una merma, un robo, un sobrante. Las entradas valen su unit_cost (o el costo promedio), las salidas el costo del emisor (promedio o PEPS). Los productos deben llevar track_stock: true. Se aplica al momento (status applied).

## Parámetros

| Nombre | Dónde | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `Idempotency-Key` | encabezado |  | Opcional (los SDK la mandan solos). Si la respuesta se pierde, repita la solicitud con el mismo valor durante 24 horas: contesta lo mismo, con idempotent-replayed: true, y no lo hace dos veces (ni crea, ni manda correos, ni cobra). |

## Cuerpo

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `issuer` | string |  | El emisor (iss_…). Por omisión, su único emisor. |
| `warehouse` | string |  | El almacén (whs_…). Por omisión, el de la Matriz. |
| `reason` | `shrinkage`, `theft`, `damage`, `expiration`, `internal_use`, `gift`, `initial`, `surplus`, `count`, `other` | sí | Por qué: shrinkage (merma), theft (robo o extravío), damage (daño), expiration (caducidad), internal_use (uso interno), gift (muestra o regalo), initial (inventario inicial), surplus (sobrante), count (conteo físico) u other. |
| `note` | string o null |  | Una nota, para el kárdex. |
| `lines` | arreglo de objeto | sí | Lo que entra o sale de cada producto, hasta 500 líneas. (hasta 500) |
| `lines[].product` | string | sí | El producto (prd_…), con track_stock: true. |
| `lines[].quantity` | number | sí | Cuánto entra (positivo) o sale (negativo), en la unidad del producto. |
| `lines[].unit_cost` | number |  | Lo que costó cada unidad que entra, en pesos sin IVA; sin él, el costo promedio de hoy. (de 0 a ∞) |
| `lines[].lot` | string |  | El lote o número de serie, si el producto los lleva. (hasta 60 caracteres) |
| `lines[].expires_on` | string |  | La caducidad de un lote nuevo (AAAA-MM-DD). |

Ejemplo:

```json
{
  "reason": "initial",
  "note": "Inventario de apertura",
  "lines": [
    {
      "product": "prd_OufpKqnrvx9p2",
      "quantity": 50,
      "unit_cost": 90
    }
  ]
}
```

## Con el SDK de TypeScript

```ts
import { Fiscalisto } from "fiscalisto";

// La llave viene de FISCALISTO_API_KEY.
const fiscalisto = new Fiscalisto();

const stockAdjustment = await fiscalisto.stockAdjustments.create({
  reason: "initial",
  note: "Inventario de apertura",
  lines: [
    {
      product: "prd_OufpKqnrvx9p2",
      quantity: 50,
      unit_cost: 90,
    },
  ],
}, { idempotencyKey: "pedido-A-1042" });
```

## Con el SDK de Python

```python
from fiscalisto import Fiscalisto

# La llave viene de FISCALISTO_API_KEY.
fiscalisto = Fiscalisto()

stock_adjustment = fiscalisto.stock_adjustments.create({
    "reason": "initial",
    "note": "Inventario de apertura",
    "lines": [
        {
            "product": "prd_OufpKqnrvx9p2",
            "quantity": 50,
            "unit_cost": 90,
        },
    ],
}, idempotency_key="pedido-A-1042")
```

## Con el SDK de PHP

```php
<?php

use Fiscalisto\Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
$fiscalisto = new Fiscalisto();

$stockAdjustment = $fiscalisto->stockAdjustments->create([
    'reason' => 'initial',
    'note' => 'Inventario de apertura',
    'lines' => [
        [
            'product' => 'prd_OufpKqnrvx9p2',
            'quantity' => 50,
            'unit_cost' => 90,
        ],
    ],
], ['idempotency_key' => 'pedido-A-1042']);
```

## Con el SDK de .NET

```csharp
using Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var stockAdjustment = await fiscalisto.StockAdjustments.CreateAsync(new CreateStockAdjustmentParams
{
    Reason = "initial",
    Note = "Inventario de apertura",
    Lines = new()
    {
        new()
        {
            Product = "prd_OufpKqnrvx9p2",
            Quantity = 50,
            UnitCost = 90,
        },
    },
}, new RequestOptions { IdempotencyKey = "pedido-A-1042" });
```

## Con el SDK de Go

```go
package main

import (
	"context"
	"fmt"
	"log"

	fiscalisto "fiscalisto.com/go"
)

func main() {
	// La llave viene de FISCALISTO_API_KEY.
	client, err := fiscalisto.NewClient("")
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()

	stockAdjustment, err := client.StockAdjustments.Create(ctx, &fiscalisto.CreateStockAdjustmentParams{
		Reason: "initial",
		Note:   fiscalisto.String("Inventario de apertura"),
		Lines: []fiscalisto.CreateStockAdjustmentParamsLine{
			{
				Product:  "prd_OufpKqnrvx9p2",
				Quantity: 50,
				UnitCost: fiscalisto.Float64(90),
			},
		},
	}, fiscalisto.WithIdempotencyKey("pedido-A-1042"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(stockAdjustment.ID)
}
```

## Con el SDK de Java

```java
import com.fiscalisto.FiscalistoClient;
import com.fiscalisto.RequestOptions;
import com.fiscalisto.model.CreateStockAdjustmentParams;
import com.fiscalisto.model.CreateStockAdjustmentParamsLine;
import java.util.List;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var stockAdjustment = fiscalisto.stockAdjustments().create(new CreateStockAdjustmentParams()
        .setReason("initial")
        .setNote("Inventario de apertura")
        .setLines(List.of(
                new CreateStockAdjustmentParamsLine()
                        .setProduct("prd_OufpKqnrvx9p2")
                        .setQuantity(50)
                        .setUnitCost(90)
        )), RequestOptions.idempotencyKey("pedido-A-1042"));
System.out.println(stockAdjustment.getId());
```

## Respuesta 201

Correcto.

Un objeto `StockAdjustment`:

| Campo | Tipo | Siempre viene | Descripción |
| --- | --- | --- | --- |
| `id` | string | sí | Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). |
| `livemode` | boolean | sí | true en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT. |
| `object` | `"stock_adjustment"` | sí | Qué tipo de objeto es («invoice», «customer»…). |
| `issuer` | string | sí | El emisor. |
| `warehouse` | string | sí | El almacén (whs_…). |
| `reason` | `shrinkage`, `theft`, `damage`, `expiration`, `internal_use`, `gift`, `initial`, `surplus`, `count`, `other` | sí | El motivo (ver POST /v1/stock_adjustments). |
| `note` | string o null | sí | Su nota, o null. |
| `status` | `applied`, `pending`, `rejected`, `reversed` | sí | applied (ya movió existencias), pending (espera aprobación en la app), rejected o reversed (se deshizo). |
| `value` | number | sí | Lo que vale lo que movió, en pesos sin IVA. |
| `lines` | arreglo de objeto | sí | Lo que entró o salió de cada producto. |
| `lines[].product` | string | sí | Un producto de su catálogo (prd_…): toma su clave, unidad, precio e impuestos. |
| `lines[].quantity` | number | sí | Cantidad (Cantidad). Por omisión 1. |
| `lines[].unit_cost` | number o null | sí | El costo por unidad que se dio al ajuste, en pesos sin IVA, o null (el costo promedio). |
| `lines[].lot` | string o null | sí | Lote del medicamento (LoteMedicamento). |
| `created_at` | string (date-time) o null | sí | Cuándo se hizo. |

```json
{
  "id": "adj_OufpKqnrvx9p1",
  "object": "stock_adjustment",
  "livemode": false,
  "issuer": "iss_OufpKqnrvx9p",
  "warehouse": "whs_OufpKqnrvx9p1",
  "reason": "initial",
  "note": "Inventario de apertura",
  "status": "applied",
  "value": 4500,
  "lines": [
    {
      "product": "prd_OufpKqnrvx9p2",
      "quantity": 50,
      "unit_cost": 90,
      "lot": null
    }
  ],
  "created_at": "2026-10-27T09:30:00-06:00"
}
```

## Errores

Puede responder 400, 401, 403, 404, 429, 500 con el cuerpo de error de siempre; cada código está en https://fiscalisto.com/docs/api/errores.md.