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

# GRN Creation API

> Create Goods Receipt Notes (GRN) with line items linked to purchase orders

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
Content-Type: application/json
```

## Request

**Content-Type:** `application/json`

### Body Parameters

| Parameter      | Type   | Required | Description                                                        |
| -------------- | ------ | -------- | ------------------------------------------------------------------ |
| `grnNumber`    | string | Yes      | GRN number to assign to the document (minimum 1 character)         |
| `lineItems`    | array  | Yes      | List of line items that make up the GRN (minimum 1 item required)  |
| `poId`         | string | Yes      | Purchase order ID that this GRN is linked to (minimum 1 character) |
| `receivedDate` | string | Yes      | Received date for the GRN in ISO-8601 format (YYYY-MM-DD)          |
| `remark`       | string | No       | Remark for the GRN (minimum 1 character)                           |
| `referenceNo`  | string | No       | Reference number for the GRN (minimum 1 character)                 |
| `description`  | string | No       | Description for the GRN (minimum 1 character)                      |

### Line Items Object

Each item in the `lineItems` array must contain the following fields:

| Parameter    | Type   | Required | Description                                        |
| ------------ | ------ | -------- | -------------------------------------------------- |
| `quantity`   | number | Yes      | Quantity received for the line item                |
| `rate`       | number | Yes      | Unit rate to be applied to the line item           |
| `identifier` | string | Yes      | Description of the line item (minimum 1 character) |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pazy.io/v1.0/procurement/grn \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "grnNumber": "GRN-2024-001",
      "poId": "po_identifier",
      "receivedDate": "2024-02-15",
      "description": "Goods receipt for office supplies",
      "remark": "All items received in good condition",
      "referenceNo": "REF-2024-001",
      "lineItems": [
        {
          "identifier": "SKU-001",
          "quantity": 100,
          "rate": 50.00
        },
        {
          "identifier": "SKU-002",
          "quantity": 50,
          "rate": 75.50
        }
      ]
    }'
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/procurement/grn', {
    method: 'POST',
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      grnNumber: 'GRN-2024-001',
      poId: 'po_identifier',
      receivedDate: '2024-02-15',
      description: 'Goods receipt for office supplies',
      remark: 'All items received in good condition',
      referenceNo: 'REF-2024-001',
      lineItems: [
        {
          identifier: 'SKU-001',
          quantity: 100,
          rate: 50.00
        },
        {
          identifier: 'SKU-002',
          quantity: 50,
          rate: 75.50
        }
      ]
    })
  });

  const result = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  url = "https://api.pazy.io/v1.0/procurement/grn"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  payload = {
      "grnNumber": "GRN-2024-001",
      "poId": "po_identifier",
      "receivedDate": "2024-02-15",
      "description": "Goods receipt for office supplies",
      "remark": "All items received in good condition",
      "referenceNo": "REF-2024-001",
      "lineItems": [
          {
              "identifier": "SKU-001",
              "quantity": 100,
              "rate": 50.00
          },
          {
              "identifier": "SKU-002",
              "quantity": 50,
              "rate": 75.50
          }
      ]
  }

  response = requests.post(url, headers=headers, json=payload)
  result = response.json()
  ```
</CodeGroup>

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field            | Type    | Description                                  |
| ---------------- | ------- | -------------------------------------------- |
| `ok`             | boolean | Indicates whether the request was successful |
| `data`           | object  | Contains the GRN creation response data      |
| `data.id`        | string  | Unique identifier for the GRN                |
| `data.grnNumber` | string  | GRN number assigned to the document          |
| `data.status`    | string  | Current status of the GRN                    |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "grn_identifier",
    "grnNumber": "GRN-2024-001",
    "status": "CREATED"
  }
}
```

## Error Responses

### Missing Required Fields

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "grnNumber is required"
  }
}
```

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "PURCHASE_ORDER_ID_REQUIRED",
    "message": "Purchase order ID required"
  }
}
```

### Invalid Date

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_DATE",
    "message": "Invalid date"
  }
}
```

### Invalid Expected Delivery Date

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_EXPECTED_DELIVERY_DATE",
    "message": "Invalid expected delivery date"
  }
}
```

### Invalid Line Items

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body/lineItems: must NOT have fewer than 1 items"
  }
}
```

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body/lineItems/0/quantity: must be number"
  }
}
```

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body/lineItems/0/identifier: must NOT have fewer than 1 characters"
  }
}
```

### Purchase Order Not Found

**HTTP Status:** `404 Not Found`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "PURCHASE_ORDER_NOT_FOUND",
    "message": "Purchase order not found"
  }
}
```

### GRN Not Found

**HTTP Status:** `404 Not Found`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "GRN_NOT_FOUND",
    "message": "GRN not found"
  }
}
```

### Invalid State

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_STATE",
    "message": "Invalid state"
  }
}
```

### Invalid Matching Type

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_MATCHING_TYPE",
    "message": "Invalid matching type"
  }
}
```

### Invalid Procurement Type

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_PROCUREMENT_TYPE",
    "message": "Invalid procurement type"
  }
}
```

### Invalid Source

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_SOURCE",
    "message": "Invalid source"
  }
}
```

### Invalid Type

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_TYPE",
    "message": "Invalid type"
  }
}
```

### Invalid GSTIN

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_GSTIN",
    "message": "Invalid GSTIN"
  }
}
```

### Invalid Currency

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_CURRENCY",
    "message": "Invalid currency Only INR is supported at the moment"
  }
}
```

### Vendor Not Found

**HTTP Status:** `404 Not Found`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VENDOR_NOT_FOUND",
    "message": "Vendor not found"
  }
}
```

### Authentication Errors

**HTTP Status:** `401 Unauthorized`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}
```

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}
```

### Permission Errors

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}
```

### GRN Creation Errors

**HTTP Status:** `500 Internal Server Error`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "PROCUREMENT_CREATION_FAILED",
    "message": "Error creating procurement"
  }
}
```

### Internal Error

**HTTP Status:** `500 Internal Server Error`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error"
  }
}
```

## Best Practices

### GRN Creation

* Ensure all required fields (`grnNumber`, `lineItems`, `poId`, `receivedDate`) are provided
* Use ISO 8601 date format (YYYY-MM-DD) for the `receivedDate` field
* Provide at least one line item with valid `quantity`, `rate`, and `identifier` values
* The `poId` must reference an existing purchase order in the system
* Use `description` to provide context about the goods received
* Include `remark` for any special notes or conditions about the receipt
* Use `referenceNo` to link the GRN to external reference numbers or documents
* Ensure the received date is not in the future and aligns with the purchase order timeline

### Line Items

* Ensure each line item has a unique `identifier` that matches the purchase order line items
* Use positive numbers for `quantity` and `rate`
* The quantity received should typically match or be less than the quantity ordered in the purchase order
* Verify that line items correspond to the linked purchase order