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

# Retrieve Supplier Bill

> Get a single supplier bill, including supplier balance and reciprocal client.

## Overview

Returns one supplier bill by its CzUid. The response includes a
`supplier_balance` block aggregating the supplier's outstanding invoices
across all your work points, plus the next due invoice (if any).

## Default expansions

The detail endpoint expands `supplier`, `expense`, `client`,
`efactura_message`, and `lines` by default. Pass `expand=` (empty) to skip
all expansions, or `expand=supplier,lines` to choose a subset.


## OpenAPI

````yaml GET /supplier-bills/{id}
openapi: 3.1.0
info:
  title: Contazen API
  version: 1.2.0
  description: >
    Build powerful integrations with the Contazen invoicing platform. The
    Contazen API is organized around REST, 

    has predictable resource-oriented URLs, accepts JSON request bodies, returns
    JSON-encoded responses, 

    and uses standard HTTP response codes, authentication, and verbs.


    ## Authentication

    The API uses Bearer token authentication. Include your API key in the
    Authorization header.


    ### Getting your API Key

    1. Log in to your Contazen account

    2. Navigate to Settings > API

    3. Generate or copy your API key (starts with `sk_live_` for production or
    `sk_test_` for testing)


    ### Using the API Key

    Include your API key in the Authorization header:

    ```

    Authorization: Bearer sk_live_YOUR_API_KEY

    ```


    ### Example Request with cURL

    ```bash

    curl --request GET \
      --url https://api.contazen.ro/v1/clients \
      --header 'Authorization: Bearer sk_live_YOUR_API_KEY' \
      --header 'Accept: application/json'
    ```


    ## Rate Limiting

    - 1000 requests per hour per API key

    - 100 create operations per minute per API key


    Rate limit information is included in response headers:

    - `X-RateLimit-Limit`: Maximum requests allowed

    - `X-RateLimit-Remaining`: Requests remaining

    - `X-RateLimit-Reset`: Reset time (Unix timestamp)


    ## Pagination

    All list endpoints return paginated results with the following format:

    ```json

    {
      "success": true,
      "data": {
        "object": "list",
        "data": [...],
        "has_more": true,
        "total": 245,
        "page": 1,
        "per_page": 50,
        "total_pages": 5
      },
      "meta": {
        "version": "v1",
        "request_id": "req_1a2b3c4d",
        "response_time": "23.45ms"
      }
    }

    ```


    ## Multi-Work-Point Access

    API keys belong to a specific work point but can access data from all work
    points

    within the same parent company.


    ## Error Handling

    The API uses conventional HTTP response codes to indicate success or
    failure. 

    In general: 2xx codes indicate success, 4xx codes indicate an error due to
    the 

    information provided, and 5xx codes indicate an error with Contazen's
    servers.


    ## Expanding Nested Objects

    Many endpoints support the `expand` parameter to include related objects in
    the response.

    This follows the Stripe API pattern. For example:

    - `expand[]=lines` - Include invoice line items

    - `expand[]=payments` - Include payment records

    - `expand[]=client` - Include full client object


    ## Localization

    The API supports multiple languages through:

    - `locale` query parameter (en, ro)

    - `Accept-Language` header

    - Default: English
  contact:
    name: Contazen Support
    email: support@contazen.ro
    url: https://contazen.ro
  license:
    name: Proprietary
    url: https://www.contazen.ro/termeni-si-conditii-de-utilizare/
servers:
  - url: https://api.contazen.ro/v1
    description: Production API server
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: API authentication and test endpoints
  - name: Clients
    description: Manage your customers (B2B and B2C)
  - name: Invoices
    description: Create and manage invoices, proformas, and receipts
  - name: Products
    description: Manage your product and service catalog
  - name: Expenses
    description: Track and manage business expenses
  - name: Expense Categories
    description: Organize expenses with categories
  - name: Suppliers
    description: Manage expense suppliers and vendors
  - name: Settings
    description: API settings and configuration
  - name: Payments
    description: Payments received against invoices
  - name: Receipts
    description: Cash receipts (chitanțe) — standalone or paired with an invoice
  - name: Company Lookup
    description: Romanian company lookup (ANAF / VIES)
  - name: Invoice Series
    description: Manage invoice numbering series
  - name: Bank Accounts
    description: Manage IBAN bank accounts
  - name: E-Factura
    description: Romanian e-invoicing status and configuration
  - name: Supplier Bills
    description: Supplier invoices imported from the ANAF SPV inbox
  - name: VAT Rates
    description: Firm-scoped custom VAT rates on top of the Romanian catalog
  - name: Currencies
    description: Currencies enabled for the firm's bill templates
  - name: Languages
    description: Languages enabled for the firm's bill templates
  - name: Conta
    description: |
      Public ANAF data for the firm's CUI: fiscal profile (TVA scope, RTVAI,
      split TVA, status, e-Factura registration, CAEN) and annual balance
      sheets (cifra de afaceri, profit, capitaluri, datorii, salariați).

      Powered by the public ANAF webservices (no OAuth required for these
      endpoints). The data is cached locally and refreshed on demand via
      the `/sync` actions.
paths:
  /supplier-bills/{id}:
    get:
      tags:
        - Supplier Bills
      summary: Get supplier bill
      operationId: getSupplierBill
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Supplier bill CzUid.
        - name: expand
          in: query
          schema:
            type: string
          description: Defaults to `supplier,expense,client,efactura_message,lines`.
      responses:
        '200':
          description: Supplier bill detail (with `supplier_balance` block)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      supplier_bill:
                        allOf:
                          - $ref: '#/components/schemas/SupplierBill'
                          - type: object
                            properties:
                              supplier_balance:
                                $ref: '#/components/schemas/SupplierBillBalance'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: Bill not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SupplierBill:
      type: object
      properties:
        id:
          type: string
          description: Supplier bill CzUid
        object:
          type: string
          example: supplier_bill
        invoice_number:
          type: string
        invoice_type_code:
          type: string
          enum:
            - '380'
            - '381'
        invoice_type:
          type: string
          enum:
            - invoice
            - credit_note
        issue_date:
          type: string
          format: date
        due_date:
          type: string
          format: date
          nullable: true
        currency:
          type: string
          example: RON
        amounts:
          $ref: '#/components/schemas/SupplierBillAmounts'
        status:
          type: string
          enum:
            - unpaid
            - paid
            - partial
        payment_date:
          type: string
          format: date
          nullable: true
        payment_amount:
          type: number
          format: float
          nullable: true
        supplier:
          $ref: '#/components/schemas/SupplierBillSupplierSummary'
        supplier_id:
          type: string
          nullable: true
          description: CzUid of the linked FirmSupplier (if any)
        expense_id:
          type: string
          nullable: true
          description: CzUid of the linked FirmExpense (if any)
        client_id:
          type: string
          nullable: true
          description: >-
            CzUid of the reciprocal FirmClient — populated when this firm has a
            client with the same CIF as the supplier
        efactura_message_id:
          type: integer
          nullable: true
          description: >-
            Local id of the FirmEfacturaMessage row (the SPV message that
            produced this bill)
        efactura_pdf_url:
          type: string
          nullable: true
          description: >-
            Direct URL to the PDF stream endpoint (null when there is no SPV
            XML)
        order_reference:
          type: string
          nullable: true
        note:
          type: string
          nullable: true
        created_at:
          type: integer
          description: Unix timestamp
        updated_at:
          type: integer
          nullable: true
          description: Unix timestamp
        expense:
          type: object
          nullable: true
          description: Present when expand contains `expense`.
        client:
          type: object
          nullable: true
          description: >-
            Present when expand contains `client` and a reciprocal client
            exists.
        efactura_message:
          type: object
          nullable: true
          description: Present when expand contains `efactura_message`.
          properties:
            id:
              type: integer
            message_id:
              type: string
            cif:
              type: string
              nullable: true
            type:
              type: string
              nullable: true
            creation_date:
              type: string
              format: date-time
              nullable: true
            environment:
              type: string
              enum:
                - test
                - live
              nullable: true
        lines:
          type: array
          description: Present when expand contains `lines`.
          items:
            type: object
    SupplierBillBalance:
      type: object
      description: Aggregate over the same supplier (matched by id, vat_id, or name).
      properties:
        unpaid_total:
          type: number
          format: float
        unpaid_count:
          type: integer
        currency:
          type: string
        next_due:
          type: object
          nullable: true
          properties:
            id:
              type: string
            invoice_number:
              type: string
            due_date:
              type: string
              format: date
              nullable: true
            tax_inclusive:
              type: number
              format: float
    ResponseMeta:
      type: object
      properties:
        version:
          type: string
          default: v1
        request_id:
          type: string
          format: uuid
          description: Unique request identifier for debugging
        response_time:
          type: string
          example: 23.45ms
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          default: false
        error:
          type: object
          required:
            - message
            - type
            - code
          properties:
            message:
              type: string
              description: Human-readable error message
            type:
              type: string
              enum:
                - api_error
                - authentication_error
                - invalid_request_error
                - rate_limit_error
                - permission_error
                - validation_error
            code:
              type: string
              description: Machine-readable error code
            param:
              type: string
              description: The parameter that caused the error
            doc_url:
              type: string
              format: uri
              description: URL to relevant documentation
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    SupplierBillAmounts:
      type: object
      properties:
        tax_exclusive:
          type: number
          format: float
          description: Subtotal without VAT
        tax:
          type: number
          format: float
          description: Total VAT amount
        tax_inclusive:
          type: number
          format: float
          description: Grand total
        paid:
          type: number
          format: float
          description: Amount already paid
        unpaid:
          type: number
          format: float
          description: tax_inclusive minus paid (can be negative for credit notes)
    SupplierBillSupplierSummary:
      type: object
      properties:
        id:
          type: string
          nullable: true
          description: Supplier CzUid (null when no FirmSupplier row exists)
        name:
          type: string
          nullable: true
        vat_id:
          type: string
          nullable: true
        reg_com:
          type: string
          nullable: true
        address:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
  responses:
    UnauthorizedError:
      description: API key is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Use your API key (sk_live_xxx or sk_test_xxx)

````