Crypware Systems

Nigeria E-Invoicing API Documentation

Introduction

Nigeria's Federal Inland Revenue Service (FIRS) is advancing its tax administration by implementing an electronic invoicing (e-invoicing) system. This initiative aims to enhance tax compliance, increase transparency, and reduce revenue losses, thereby improving the country's tax-to-GDP ratio.

Key Developments in Nigeria's E-Invoicing System:

  • Pilot Phase Initiation: In February 2025, FIRS launched a pilot phase of the e-invoicing system, targeting large taxpayers across various sectors. This phase is designed to gather insights and address potential challenges before a full-scale rollout.

  • Full Implementation Timeline: Based on the outcomes of the pilot, FIRS plans to fully implement the e-invoicing system by July 2025, encompassing Business-to-Business (B2B), Business-to-Consumer (B2C), and Business-to-Government (B2G) transactions.

  • System Features: The e-invoicing platform, known as the Merchant Buyer Solution (MBS), is designed to replace traditional paper-based invoicing with a digital framework that facilitates real-time validation and storage of transactions.

Technical Compliance:

To comply with the new regulations, businesses must use authorized e-invoicing solutions that integrate with the FIRS platform. The system offers two main options:

  1. Direct Issuance: Businesses can generate invoices directly through the FIRS e-invoice portal.
  2. System Integration: Companies can integrate their existing invoicing software with the FIRS e-invoice system via API.

Authentication

All API requests require authentication headers. The following headers must be included in every request:

Base URL

All API endpoints use the following base URL: https://cryptware-einvoicing.flick.network

Required Headers

  • Name
    participant-id
    Type
    string
    Description

    Unique identifier for the registered participant/supplier.

  • Name
    x-api-key
    Type
    string
    Description

    API key for authentication. Contact your administrator to obtain this key.

  • Name
    Content-Type
    Type
    string
    Description

    Set to application/json for POST/PATCH requests.


Common Data Structures

These data structures are reusable components used across various API endpoints. Understanding these structures is essential for proper API integration.

Invoice Document

The main invoice document structure containing all invoice details.

  • Name
    document_identifier
    Type
    string
    Description

    Unique identifier for the invoice document. This is your internal reference number. (Mandatory)

  • Name
    issue_date
    Type
    string (YYYY-MM-DD)
    Description

    Date when the invoice was issued. (Mandatory)

  • Name
    due_date
    Type
    string (YYYY-MM-DD)
    Description

    Payment due date for the invoice. (Optional)

  • Name
    invoice_type_code
    Type
    string
    Description

    Code representing the type of invoice (e.g., "380" for commercial invoice, "384" for corrected invoice). (Mandatory)

  • Name
    document_currency_code
    Type
    string
    Description

    Currency code for the invoice (e.g., "NGN" for Nigerian Naira). (Mandatory)

  • Name
    tax_currency_code
    Type
    string
    Description

    Currency code for tax calculations (e.g., "NGN"). (Mandatory)

  • Name
    payment_status
    Type
    string
    Description

    Current payment status: "PENDING", "PAID", or "REJECTED". Defaults to "PENDING". (Optional)

  • Name
    business_model
    Type
    string
    Description

    Business transaction model: "B2B" (Business-to-Business), "B2C" (Business-to-Consumer), or "B2G" (Business-to-Government). (Optional)


Accounting Customer Party

This structure contains comprehensive information about the customer (buyer) to whom the invoice is being issued. This is a mandatory component of every invoice.

  • Name
    party_name
    Type
    string
    Description

    The legal or registered name of the customer. (Mandatory)

  • Name
    tin
    Type
    string
    Description

    Tax Identification Number (TIN) of the customer. Must be registered with FIRS. (Mandatory)

  • Name
    email
    Type
    string
    Description

    Email address of the customer for invoice delivery and notifications. (Mandatory)

  • Name
    telephone
    Type
    string
    Description

    Phone number of the customer. Must include country code starting with + (e.g., "+234" for Nigeria). (Optional)

  • Name
    business_description
    Type
    string
    Description

    Brief description of the customer's business activity or industry sector. (Optional)

  • Name
    postal_address
    Type
    object
    Description

    Physical address of the customer. (Mandatory)

  • Name
    street_name
    Type
    string
    Description

    Street address including building number and street name.

  • Name
    city_name
    Type
    string
    Description

    City or town name.

  • Name
    postal_zone
    Type
    string
    Description

    Postal code or zip code.

  • Name
    state
    Type
    string
    Description

    State code (e.g., "NG-LA" for Lagos). (Optional)

  • Name
    country
    Type
    string
    Description

    Country code (ISO 3166-1 alpha-2), e.g., "NG" for Nigeria. (Mandatory)


Invoice Line Items

Invoice line items represent individual products or services included in an invoice. Each invoice must contain at least one line item. This array structure allows multiple items to be included in a single invoice.

  • Name
    hsn_code
    Type
    string
    Description

    Harmonized System Nomenclature (HSN) code for product classification. This is a globally standardized system for classifying traded products. (Mandatory)

  • Name
    product_category
    Type
    string
    Description

    Category or classification of the product/service (e.g., "Lubricants", "Food and Beverages", "Electrical energy"). (Mandatory)

  • Name
    item_name
    Type
    string
    Description

    Descriptive name of the product or service. (Mandatory)

  • Name
    sellers_item_identification
    Type
    string
    Description

    Seller's internal SKU or product identification code. (Optional)

  • Name
    invoiced_quantity
    Type
    number
    Description

    Quantity of items being invoiced. (Mandatory)

  • Name
    uom
    Type
    string
    Description

    Unit of measurement (e.g., "ST" for stock, "PC" for pieces, "KG" for kilograms, "LTR" for liters). (Mandatory)

  • Name
    price_amount
    Type
    number
    Description

    Unit price per item before discounts and taxes. (Mandatory)

  • Name
    discount_rate
    Type
    number
    Description

    Discount rate as a percentage (e.g., 10.5 for 10.5% discount). (Optional)

  • Name
    discount_amount
    Type
    number
    Description

    Fixed discount amount in the document currency. (Optional)

  • Name
    fee_rate
    Type
    number
    Description

    Additional fee rate as a percentage. (Optional)

  • Name
    fee_amount
    Type
    number
    Description

    Fixed fee amount in the document currency. (Optional)

  • Name
    line_extension_amount
    Type
    number
    Description

    Total amount for this line item before taxes (calculated as: quantity × price - discount + fee). (Optional - can be auto-calculated)

  • Name
    tax_rate
    Type
    number
    Description

    Applicable tax rate as a percentage (e.g., 7.5 for 7.5% VAT). (Mandatory)

  • Name
    tax_category_id
    Type
    string
    Description

    Tax category identifier (e.g., "ZERO_VAT", "LOCAL_SALES_TAX", "STANDARD_VAT", "EXEMPT_VAT"). Use the /resources/tax-categories endpoint to get valid values. (Mandatory)


Postal Address

Standard address structure used in various API requests.

  • Name
    street_name
    Type
    string
    Description

    Street address including building/house number and street name. (Mandatory)

  • Name
    city_name
    Type
    string
    Description

    City or town name. (Mandatory)

  • Name
    postal_zone
    Type
    string
    Description

    Postal code or zip code. (Mandatory)

  • Name
    state
    Type
    string
    Description

    State or region code (e.g., "NG-LA" for Lagos). (Optional)

  • Name
    country
    Type
    string
    Description

    Country code using ISO 3166-1 alpha-2 format (e.g., "NG" for Nigeria). (Mandatory)


Invoice APIs

GET/invoice/search

Search Invoices

Retrieve a list of invoices based on search criteria. This endpoint allows you to query and filter invoices.

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

Request

GET
/invoice/search
curl --request GET \
  --url {{baseUrl}}/invoice/search \
  --header 'participant-id: 019b4e74-d285-72d6-b23a-005c40328079' \
  --header 'x-api-key: 72aa34346860bfb721f081b8b96cf48adecc0dda00e76f2cb16882b05bbeca7b'

Response

200
Success
{
  "status": "success",
  "data": {
    "invoices": [
      {
        "irn": "TSTCRPT-1554544516-C1B44E6C-20250305",
        "document_identifier": "TSTCRPT-1554544516",
        "issue_date": "2025-03-05",
        "status": "SIGNED",
        "total_amount": 150.00
      }
    ],
    "total": 1
  }
}

GET/invoice/download/{irn}

Download Invoice Details

Download complete invoice details by Invoice Reference Number (IRN). This endpoint returns the full invoice document.

Path Parameters

  • Name
    irn
    Type
    string
    Description

    Invoice Reference Number (e.g., "TSTCRPT-1554544516-C1B44E6C-20250305").

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

Request

GET
/invoice/download/{irn}
curl --request GET \
  --url {{baseUrl}}/invoice/download/TSTCRPT-1554544516-C1B44E6C-20250305 \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}'

Response

200
Success
{
  "status": "success",
  "data": {
    "irn": "TSTCRPT-1554544516-C1B44E6C-20250305",
    "document_identifier": "TSTCRPT-1554544516",
    "issue_date": "2025-03-05",
    "invoice_type_code": "380",
    "document_currency_code": "NGN",
    "accounting_customer_party": {
      "party_name": "cryptware",
      "tin": "23773131-0001",
      "email": "crypt@g.com"
    },
    "invoice_line": [],
    "pdf_url": "https://example.com/invoice.pdf"
  }
}

GET/invoice/details/{irn}

Get Invoice Details with QR

Retrieve invoice details including QR code information. This endpoint is useful for displaying invoices with embedded QR codes for verification.

Path Parameters

  • Name
    irn
    Type
    string
    Description

    Invoice Reference Number.

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

Request

GET
/invoice/details/{irn}
curl --request GET \
  --url {{baseUrl}}/invoice/details/TSTCRPT-2555574445-C1B44E6C-20250305 \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}'

Response

200
Success
{
  "status": "success",
  "data": {
    "irn": "TSTCRPT-2555574445-C1B44E6C-20250305",
    "qr_code": "iVBORw0KGgoAAAANSUhEUgAA...",
    "qr_code_url": "https://example.com/qr/TSTCRPT-2555574445-C1B44E6C-20250305",
    "invoice_details": {
      "document_identifier": "TSTCRPT-2555574445",
      "issue_date": "2025-03-05",
      "total_amount": 100.50
    }
  }
}

POST/invoice/generate

Generate Invoice

Generate a new e-invoice and submit it to the FIRS platform. This is the primary endpoint for creating invoices.

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

  • Name
    Content-Type
    Type
    string
    Description

    Must be application/json.

Request Body

  • Name
    document_identifier
    Type
    string
    Description

    Unique document reference number or identifier.

  • Name
    issue_date
    Type
    string
    Description

    Date on which the invoice was issued (format: YYYY-MM-DD).

  • Name
    invoice_type_code
    Type
    string
    Description

    Code representing the invoice type (e.g., "380" for commercial invoice, "384" for corrected invoice).

  • Name
    document_currency_code
    Type
    string
    Description

    Currency code for the invoice (e.g., "NGN").

  • Name
    tax_currency_code
    Type
    string
    Description

    Currency code for tax calculations (e.g., "NGN").

  • Name
    payment_status
    Type
    string
    Description

    Payment status (e.g., "PENDING", "PAID", "REJECTED"). Optional, defaults to "PENDING".

  • Name
    accounting_customer_party
    Type
    object
    Description

    Customer/buyer information. See Common Data Structures section.

  • Name
    invoice_line
    Type
    array
    Description

    Array of invoice line items. See Common Data Structures section. At least one item required.

Request

POST
/invoice/generate
curl --request POST \
  --url {{baseUrl}}/invoice/generate \
  --header 'Content-Type: application/json' \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}' \
  --data '{
    "document_identifier": "TSTCRPT-1554544515",
    "issue_date": "2025-03-05",
    "invoice_type_code": "380",
    "document_currency_code": "NGN",
    "tax_currency_code": "NGN",
    "accounting_customer_party": {
      "party_name": "cryptware",
      "email": "crypt@g.com",
      "tin": "23773131-0001",
      "telephone": "+234",
      "business_description": "Lubricants",
      "postal_address": {
        "street_name": "4 POINT ROAD OLUYOLA ESTATE",
        "city_name": "IBADAN",
        "postal_zone": "OLUYOLE",
        "country": "NG"
      }
    },
    "invoice_line": [
      {
        "hsn_code": "2710.19",
        "price_amount": 10,
        "discount_amount": 1,
        "uom": "ST",
        "invoiced_quantity": 2.23,
        "product_category": "Lubricants",
        "tax_rate": 0,
        "tax_category_id": "ZERO_VAT",
        "item_name": "QUARTZ 5000 SL 20W50 205L TOT NG",
        "sellers_item_identification": "209897"
      },
      {
        "hsn_code": "2710.19",
        "price_amount": 10,
        "discount_amount": 2,
        "uom": "ST",
        "invoiced_quantity": 7.25,
        "product_category": "Lubricants",
        "tax_rate": 0,
        "tax_category_id": "ZERO_VAT",
        "item_name": "RUBIA TIR 7400 15W40 205L TOT NG",
        "sellers_item_identification": "189402"
      }
    ]
  }'

Response

201
Success
{
  "status": "success",
  "message": "Invoice generated successfully",
  "data": {
    "irn": "TSTCRPT-1554544515-C1B44E6C-20250305",
    "status": "SIGNED",
    "qr_code": "XtIv69xI4CDxAqrvPL+8c/JhHmwWxfOqo+IyTwHBZCf...",
    "firs_response": {
      "code": 201,
      "message": "Invoice accepted"
    },
    "steps_completed": [
      "irn_validation",
      "invoice_validation",
      "invoice_signing",
      "database_storage"
    ]
  }
}

Error Response

400
Bad Request
{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "document_identifier",
      "message": "Document identifier is required"
    }
  ]
}

PATCH/invoice/{irn}

Update Invoice Payment Status

Update the payment status of an existing invoice. This endpoint allows you to mark invoices as paid, rejected, or update payment references.

Path Parameters

  • Name
    irn
    Type
    string
    Description

    Invoice Reference Number.

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

  • Name
    Content-Type
    Type
    string
    Description

    Must be application/json.

Request Body

  • Name
    payment_status
    Type
    string
    Description

    New payment status. Accepted values: "PAID", "PENDING", "REJECTED".

  • Name
    reference
    Type
    string
    Description

    Payment reference or transaction ID (optional).

Request

PATCH
/invoice/{irn}
curl --request PATCH \
  --url {{baseUrl}}/invoice/TSTCRPT-2555574445-C1B44E6C-20250305 \
  --header 'Content-Type: application/json' \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}' \
  --data '{
    "payment_status": "REJECTED",
    "reference": "ref-125669"
  }'

Response

200
Success
{
  "status": "success",
  "message": "Invoice payment status updated successfully",
  "data": {
    "irn": "TSTCRPT-2555574445-C1B44E6C-20250305",
    "payment_status": "REJECTED",
    "reference": "ref-125669",
    "updated_at": "2025-03-05T14:30:00Z"
  }
}

Resource APIs

Resource APIs provide access to reference data and master data required for invoice generation, such as tax categories, HSN codes, currencies, and more.

GET/resources/all

Get All Resources

Retrieve all available resource types in a single request. This is a convenient endpoint to fetch all master data at once.

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

Request

GET
/resources/all
curl --request GET \
  --url {{baseUrl}}/resources/all \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}'

Response

200
Success
{
  "status": "success",
  "data": {
    "hs_codes": [],
    "service_codes": [],
    "currencies": [],
    "countries": [],
    "invoice_types": [],
    "payment_means": [],
    "tax_categories": [],
    "vat_exemptions": []
  }
}

GET/resources/hs-codes

Get HSN Codes

Retrieve the list of Harmonized System Nomenclature (HSN) codes. These codes classify products for tax purposes.

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

Request

GET
/resources/hs-codes
curl --request GET \
  --url {{baseUrl}}/resources/hs-codes \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}'

Response

200
Success
{
  "status": "success",
  "data": [
    {
      "code": "2710.19",
      "description": "Petroleum oils and oils obtained from bituminous minerals"
    },
    {
      "code": "271600",
      "description": "Electrical energy"
    }
  ]
}

GET/resources/services-codes

Get Service Codes

Retrieve the list of service classification codes for service-based invoices.

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

Request

GET
/resources/services-codes
curl --request GET \
  --url {{baseUrl}}/resources/services-codes \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}'

Response

200
Success
{
  "status": "success",
  "data": [
    {
      "code": "SRV001",
      "description": "Consulting Services"
    },
    {
      "code": "SRV002",
      "description": "IT Services"
    }
  ]
}

GET/resources/currencies

Get Currencies

Retrieve the list of supported currency codes for invoicing.

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

Request

GET
/resources/currencies
curl --request GET \
  --url {{baseUrl}}/resources/currencies \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}'

Response

200
Success
{
  "status": "success",
  "data": [
    {
      "code": "NGN",
      "name": "Nigerian Naira",
      "symbol": "₦"
    },
    {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$"
    }
  ]
}

GET/resources/countries

Get Countries

Retrieve the list of country codes (ISO 3166-1 alpha-2) supported by the system.

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

Request

GET
/resources/countries
curl --request GET \
  --url {{baseUrl}}/resources/countries \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}'

Response

200
Success
{
  "status": "success",
  "data": [
    {
      "code": "NG",
      "name": "Nigeria"
    },
    {
      "code": "US",
      "name": "United States"
    }
  ]
}

GET/resources/invoice-types

Get Invoice Types

Retrieve the list of invoice type codes and their descriptions. These codes define the nature of the invoice (e.g., commercial invoice, credit note).

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

Request

GET
/resources/invoice-types
curl --request GET \
  --url {{baseUrl}}/resources/invoice-types \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}'

Response

200
Success
{
  "status": "success",
  "data": [
    {
      "code": "380",
      "description": "Commercial Invoice"
    },
    {
      "code": "384",
      "description": "Corrected Invoice"
    },
    {
      "code": "396",
      "description": "Credit Note"
    }
  ]
}

GET/resources/payment-means

Get Payment Means

Retrieve the list of payment method codes (e.g., bank transfer, cash, card).

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

Request

GET
/resources/payment-means
curl --request GET \
  --url {{baseUrl}}/resources/payment-means \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}'

Response

200
Success
{
  "status": "success",
  "data": [
    {
      "code": "10",
      "description": "Cash"
    },
    {
      "code": "30",
      "description": "Credit Transfer"
    },
    {
      "code": "48",
      "description": "Bank Card"
    }
  ]
}

GET/resources/tax-categories

Get Tax Categories

Retrieve the list of tax category codes used for invoice line items.

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

Request

GET
/resources/tax-categories
curl --request GET \
  --url {{baseUrl}}/resources/tax-categories \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}'

Response

200
Success
{
  "status": "success",
  "data": [
    {
      "id": "ZERO_VAT",
      "description": "Zero-rated VAT",
      "rate": 0.0
    },
    {
      "id": "LOCAL_SALES_TAX",
      "description": "Local Sales Tax",
      "rate": 7.5
    },
    {
      "id": "STANDARD_VAT",
      "description": "Standard VAT",
      "rate": 7.5
    }
  ]
}

GET/resources/vat-exemptions

Get VAT Exemptions

Retrieve the list of VAT exemption reasons and codes.

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

Request

GET
/resources/vat-exemptions
curl --request GET \
  --url {{baseUrl}}/resources/vat-exemptions \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}'

Response

200
Success
{
  "status": "success",
  "data": [
    {
      "code": "VATEX-NG-001",
      "description": "Export of goods outside Nigeria"
    },
    {
      "code": "VATEX-NG-002",
      "description": "Goods and services to diplomats"
    }
  ]
}

Transmitting APIs

GET/transmitting/lookup/{id}

Transmit Lookup

Look up the transmission status of an invoice by its identifier. This endpoint helps track whether an invoice has been successfully transmitted to FIRS.

Path Parameters

  • Name
    id
    Type
    string
    Description

    Invoice identifier or document reference number (e.g., "5524270296-A2EC78CC-20251203").

Headers

  • Name
    participant-id
    Type
    string
    Description

    Your registered participant ID.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication.

Request

GET
/transmitting/lookup/{id}
curl --request GET \
  --url {{baseUrl}}/transmitting/lookup/5524270296-A2EC78CC-20251203 \
  --header 'participant-id: {{participant-id}}' \
  --header 'x-api-key: {{x-api-key}}'

Response

200
Success
{
  "status": "success",
  "data": {
    "id": "5524270296-A2EC78CC-20251203",
    "transmission_status": "TRANSMITTED",
    "transmitted_at": "2025-12-03T10:30:00Z",
    "firs_acknowledgment": {
      "status": "ACCEPTED",
      "timestamp": "2025-12-03T10:30:05Z"
    }
  }
}

Error Response

404
Not Found
{
  "status": "error",
  "message": "Invoice not found",
  "error_code": "INVOICE_NOT_FOUND"
}

Error Codes

Common error codes you may encounter when using the API:

  • Name
    INVALID_PARTICIPANT_ID
    Type
    401
    Description

    The participant-id provided is invalid or not registered.

  • Name
    INVALID_API_KEY
    Type
    401
    Description

    The x-api-key provided is invalid or expired.

  • Name
    VALIDATION_ERROR
    Type
    400
    Description

    Request validation failed. Check the error details for specific field errors.

  • Name
    INVOICE_NOT_FOUND
    Type
    404
    Description

    The requested invoice could not be found.

  • Name
    DUPLICATE_INVOICE
    Type
    409
    Description

    An invoice with the same document_identifier already exists.

  • Name
    FIRS_CONNECTION_ERROR
    Type
    502
    Description

    Unable to connect to FIRS platform. Please try again later.

  • Name
    RATE_LIMIT_EXCEEDED
    Type
    429
    Description

    Too many requests. Please slow down and try again.


Rate Limiting

The API implements rate limiting to ensure fair usage and system stability:

  • Standard Tier: 100 requests per minute per participant
  • Premium Tier: 500 requests per minute per participant

When rate limits are exceeded, you'll receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry.


Changelog

Version 1.0.0 (July 2025)

  • Initial release
  • Invoice generation and management endpoints
  • Resource data endpoints
  • Transmission lookup functionality