> ## 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.

# Invoice Creation API

> Create invoices by uploading invoice files (PDF or images) for processing

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
```

## Request

**Content-Type:** `multipart/form-data`

### Body Parameters

| Parameter | Type             | Required | Description                                                                                                                                               |
| --------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file`    | File             | Yes      | The invoice file to upload. Supported formats: PDF, JPEG, JPG, PNG                                                                                        |
| `remarks` | String or Object | No       | Optional remarks/notes for the invoice. Can be provided as a string value directly, or as an object with a `value` property containing the remarks string |

### File Requirements

* Maximum file size: 50 MB
* Supported formats: PDF (application/pdf), JPEG (image/jpeg), JPG (image/jpg), PNG (image/png)
* The file should contain a readable invoice document

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pazy.io/v1.0/invoice \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -F "file=@/path/to/invoice.pdf" \
    -F "remarks=Payment due in 30 days"
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const formData = new FormData();
  formData.append('file', fileInput.files[0]);
  formData.append('remarks', 'Payment due in 30 days'); // Optional

  const response = await fetch('https://api.pazy.io/v1.0/invoice', {
    method: 'POST',
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY'
    },
    body: formData
  });

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

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

  url = "https://api.pazy.io/v1.0/invoice"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY"
  }

  files = {
      'file': ('invoice.pdf', open('/path/to/invoice.pdf', 'rb'), 'application/pdf')
  }

  data = {
      'remarks': 'Payment due in 30 days'  # Optional
  }

  response = requests.post(url, headers=headers, files=files, data=data)
  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 invoice creation response data                                                         |
| `data.id`           | string  | Unique identifier for the invoice. Use this ID to retrieve invoice details later                    |
| `data.status`       | string  | Current processing status. Possible values: `PROCESSING`, `QUEUED`                                  |
| `data.processingId` | string  | Identifier for the processing job. Used for tracking invoice processing status                      |
| `data.isReady`      | boolean | Indicates whether the invoice is ready for use. Initially `false` as the invoice is being processed |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "id": "invoice_identifier",
    "status": "PROCESSING",
    "processingId": "job_123456",
    "isReady": false
  }
}
```

### Status Values

* **PROCESSING**: The invoice is currently being processed and parsed
* **QUEUED**: The invoice has been queued for processing

<Info>
  After successful upload, the invoice will be processed asynchronously. Use the returned `id` to check the invoice status and retrieve details once processing is complete.
</Info>

## Error Responses

### Missing File

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

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

### Invalid File Type

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_FILE_TYPE",
    "message": "Invalid file type. Only PDF, JPEG, JPG, and PNG files are allowed"
  }
}
```

### File Too Large

**HTTP Status:** `413 Payload Too Large` (or `400 Bad Request`)

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: fileSize: File size exceeds maximum allowed size"
  }
}
```

### 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"
  }
}
```

### Processing Errors

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVOICE_CREATION_FAILED",
    "message": "Failed to create invoice"
  }
}
```

## Best Practices

### File Uploads

* Verify file size before upload (max 50 MB)
* Ensure file format is supported (PDF, JPEG, JPG, PNG)
* Use appropriate MIME types when setting Content-Type headers
* Handle upload errors gracefully with retry logic

### Invoice Processing

* Store the returned `id` for future reference
* Poll the invoice status using the invoice detail endpoint
* Wait for `isReady` to become `true` before using the invoice data
* The `status` field will indicate if the invoice is still being processed