Migrate from v1 to v2 Document API version

API Integration
1

Overview

This guide provides a detailed migration path from v1 Create a Document to v2 Create a Document. It highlights key differences and necessary updates to ensure a smooth transition.

Key Changes in V2

1. Serial Number Handling

  • v1:
    • serial_number (string)
  • v2:
    • serial_number_v2 (object)
      • prefix: Prefix for document numbering (e.g., INV-)
      • doc_number: Numeric sequence (e.g., 1)
      • suffix: Optional suffix (e.g., -2024)

Action Required:

  • If you do not send serial_number explicitly, it will be auto-generated.
  • prefix, suffix, and doc_number have been separated in v2.
  • If values are provided, the serial number will be formatted as:
    prefix + doc_number + suffix (e.g., INV-1-2024).
  • Empty strings can be used for prefix and suffix if not needed.
  • If you require a specific prefix but do not want to send doc_number, you can omit doc_number from the payload. A new doc_number will be automatically generated for the given prefix.
  • More details on the schema.

2. Customer to Party Migration

  • v1: customer
  • v2: party

Action Required:

  • The key name has changed from customer to party.
  • The party object must include a party_type (customer or vendor) based on the document type.
  • customer_billing_address and customer_shipping_address are now included in the party object as billing_address and shipping_address.
  • More details on the schema.

3. Address Schema Changes

  • v2 Updates:
    • Added an addr_id key (must be between 0 and 999999).
    • If the provided addr_id already exists, the existing address will be updated; otherwise, a new address will be created.

4. Payments and Bank Details

Updates:

  • Added bank_details inside the payments array, allowing different details for each payment.
  • bank_details provided outside the payments key will be used for displaying details on the PDF.
  • More details on the schema.

5. Items

Updates:

6. Additional Charges & Deductions

Updates:

  • Added support for additional charges and deductions using the charges_and_deductions key (e.g., delivery charges, packing charges, etc.).
  • More details on the schema.

7. Export Fields

Updates:

8. Document Conversion

Updates:

  • Added support for tracking document conversions using the convert key.
  • Example: Track which quotation was converted into a specific invoice.
  • More details on the schema.

9. Document Custom Headers Support

Updates:

Summary of Required Updates

V1 Field Action Required V2 Field
serial_number Use serial_number_v2 serial_number_v2
customer Replace with party party
All address fields Add addr_id key in each address All address fields
items Introduce custom_columns if needed items
Additional charges (N/A) Introduce if applicable charges_and_deductions
Document custom headers (N/A) Introduce if applicable custom_headers
Convert documents (N/A) Introduce if applicable convert