> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fire.rest/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear recepción de mercancía

> Registra una recepción de mercancía de un proveedor. Incrementa los niveles de stock en el almacén de destino.

<ParamField header="x-api-key" type="string" required>
  API key de BOH con scope `inventory:write`.
</ParamField>

<ParamField path="vendorId" type="string" required>UUID del vendor.</ParamField>

<ParamField body="store_id" type="string">UUID del establecimiento de destino. Se requiere `store_id` o `external_store_id`.</ParamField>
<ParamField body="external_store_id" type="string">ID externo del establecimiento.</ParamField>
<ParamField body="supplier_id" type="string">UUID del proveedor. Se requiere `supplier_id` o `external_supplier_id`.</ParamField>
<ParamField body="external_supplier_id" type="string">ID externo del proveedor.</ParamField>
<ParamField body="occurred_at" type="string">Cuándo ocurrió la recepción (ISO 8601). Por defecto: ahora.</ParamField>
<ParamField body="reference" type="string">Número de referencia o albarán.</ParamField>
<ParamField body="notes" type="string">Notas de texto libre.</ParamField>

<ParamField body="lines" type="object[]" required>
  Líneas de artículos recibidos.

  <Expandable title="campos de línea">
    <ParamField body="item_id" type="string">UUID del artículo.</ParamField>
    <ParamField body="external_item_id" type="string">ID externo del artículo.</ParamField>
    <ParamField body="quantity" type="number" required>Cantidad recibida.</ParamField>
    <ParamField body="unit_id" type="string" required>UUID de la unidad.</ParamField>
    <ParamField body="unit_cost" type="number">Costo unitario (para valoración).</ParamField>
    <ParamField body="notes" type="string">Notas de línea.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="external_user_id" type="string" required>Actor que realiza la recepción.</ParamField>
<ParamField body="idempotency_key" type="string">Clave de idempotencia para prevenir duplicados.</ParamField>

<RequestExample>
  ```json theme={null}
  {
    "external_store_id": "tienda-principal",
    "external_supplier_id": "proveedor-fresco",
    "occurred_at": "2026-08-07T09:00:00.000Z",
    "reference": "FAC-2026-001",
    "lines": [
      {
        "external_item_id": "tomate-bola",
        "quantity": 10,
        "unit_id": "unit_kg_01...",
        "unit_cost": 25.00
      }
    ],
    "external_user_id": "almacenista_01"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "gr_01...",
    "status": "COMPLETED",
    "store_id": "str_principal_01...",
    "supplier_id": "sup_01...",
    "occurred_at": "2026-08-07T09:00:00.000Z",
    "reference": "FAC-2026-001",
    "lines": [
      {
        "id": "grl_01...",
        "item_id": "itm_01...",
        "quantity": 10,
        "unit_id": "unit_kg_01...",
        "unit_cost": 25.00
      }
    ]
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "kind": "store_not_found",
      "message": "Store not found"
    }
  }
  ```
</ResponseExample>