Fetch invoice by processor ID

GET

invoices

by-processor-id

{processorId}

curl --request GET \
  --url https://api.useaira.com/v1/invoices/by-processor-id/{processorId} \
  --header 'X-API-KEY: <api-key>'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "displayId": "<string>",
  "customer": {
    "id": "<string>",
    "externalId": "705faf65-9c8b-4053-8c0b-2021281ce83f",
    "name": "Acme Inc.",
    "customFields": {
      "customField1": "value1",
      "customField2": [
        "value2",
        "value3"
      ]
    }
  },
  "paymentAccount": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "businessName": "<string>",
    "taxId": "<string>",
    "taxIdType": "cnpj",
    "tradeName": "<string>",
    "email": "[email protected]",
    "address": {
      "zipCode": "<string>",
      "number": "<string>",
      "street": "<string>",
      "neighborhood": "<string>",
      "city": "<string>",
      "state": "AC",
      "country": "Brasil",
      "complement": "<string>"
    }
  },
  "contract": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "startDate": "2023-12-25",
    "endDate": "2023-12-25",
    "billingEndDay": 16,
    "status": "active",
    "paymentSettings": {
      "scheduledPaymentDay": 16,
      "dueOffsetDays": 6
    },
    "billingSettings": {
      "billingCycleMinimumAmount": 1
    },
    "sendNotifications": true,
    "rateAdjustmentIndex": "none",
    "customFields": {
      "customField1": "value1",
      "customField2": [
        "value2",
        "value3"
      ]
    }
  },
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "totalAmount": 1,
  "closedReason": "end_of_cycle",
  "payments": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "amount": 123,
      "dueDate": "2023-12-25",
      "createdAt": "2023-11-07T05:31:56Z",
      "processedAt": "2023-11-07T05:31:56Z",
      "paymentMethod": "bolepix",
      "status": "created",
      "pixLink": "<string>",
      "bankSlipLink": "<string>"
    }
  ],
  "status": "open",
  "processorId": "<string>",
  "plans": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "description": "<string>",
      "planSettings": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "fixedAmount": 1,
        "minimumAmount": 1
      },
      "totalAmount": 1,
      "product": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "customFields": {
          "customField1": "value1",
          "customField2": [
            "value2",
            "value3"
          ]
        }
      },
      "metrics": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "resourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "currencyUnitId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "billingModel": "in_full",
          "priceTierDivision": "unique_tier",
          "fixedAmount": 1,
          "minimumAmount": 1,
          "resourceName": "<string>",
          "resourceType": "unit",
          "priceTiers": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "billingType": "unit",
              "from": 2,
              "to": 2,
              "packageSize": 2,
              "price": "<string>",
              "fixedPrice": "<string>",
              "basisPoints": 1,
              "totalAmount": 1,
              "usage": 1
            }
          ],
          "totalAmount": 1,
          "resourceCustomFields": {},
          "currencyUnit": {
            "id": "<string>",
            "name": "<string>",
            "code": "<string>"
          }
        }
      ]
    }
  ],
  "additionalItems": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "description": "<string>",
      "amount": 2,
      "type": "discount"
    }
  ]
}

Authorizations

X-API-KEY

string

header

required

API Key Authentication.

Path Parameters

processorId

string

required

Response

Default Response

string<uuid>

required

The unique identifier of the invoice.

displayId

string

required

The human-readable identifier of the invoice.

customer

object

required

The customer associated with this invoice.

Show child attributes

customer.id

string

required

The unique identifier of the customer in our system.

customer.externalId

string

required

An optional external identifier of the customer from the external system, used throughout the system to identify the customer. This field can not be updated.

Example:

"705faf65-9c8b-4053-8c0b-2021281ce83f"

customer.name

string

required

The name of the customer.

Example:

"Acme Inc."

customer.customFields

object

required

Custom fields that can be associated with the entity. The fields must be previously created in the system before they can be used.

Show child attributes

customer.customFields.{key}

Example:

{
  "customField1": "value1",
  "customField2": ["value2", "value3"]
}

paymentAccount

object

required

The payment account used for this invoice.

Show child attributes

paymentAccount.id

string<uuid>

required

The unique identifier of the payment account.

paymentAccount.businessName

string

required

The legal business name of the payment account holder.

Minimum string length: 1

paymentAccount.taxId

string

required

The tax identification number (CNPJ or CPF) of the payment account holder.

paymentAccount.taxIdType

enum<string>

default:cnpj

required

The type of tax identification number (CNPJ or CPF) of the payment account holder.

Available options:

cnpj,

cpf

paymentAccount.tradeName

string | null

The trade or "doing business as" name of the payment account holder.

Minimum string length: 1

paymentAccount.email

string<email> | null

The contact email address for the payment account.

paymentAccount.address

object

The physical address associated with the payment account.

Show child attributes

paymentAccount.address.zipCode

string

required

The postal code (CEP) of the address.

Required string length: 8

paymentAccount.address.number

string

required

The street number of the address.

Minimum string length: 1

paymentAccount.address.street

string

required

The street name of the address.

Minimum string length: 1

paymentAccount.address.neighborhood

string

required

The neighborhood or district of the address.

Minimum string length: 1

paymentAccount.address.city

string

required

The city name of the address.

Minimum string length: 1

paymentAccount.address.state

enum<string>

required

The state abbreviation of the address.

Available options:

AC,

AL,

AP,

AM,

BA,

CE,

DF,

ES,

GO,

MA,

MT,

MS,

MG,

PA,

PB,

PR,

PE,

PI,

RJ,

RN,

RS,

RO,

RR,

SC,

SP,

SE,

TO

paymentAccount.address.country

enum<string>

required

The country code of the address.

Available options:

Brasil

paymentAccount.address.complement

string | null

required

Additional address information like apartment number, floor, etc.

contract

object

required

The contract associated with this invoice.

Show child attributes

contract.id

string<uuid>

required

Unique identifier for the contract.

contract.startDate

string<date>

required

Date when the contract becomes active.

contract.endDate

string<date> | null

required

Optional date when the contract expires. If null, the contract has no end date.

contract.billingEndDay

number

required

Day of the month when the billing cycle ends (1-31).

Required range: 1 <= x <= 31

contract.status

enum<string>

required

Current status of the contract.

Available options:

active,

canceled,

completed,

draft

contract.paymentSettings

object

required

Schema defining payment gateway settings for a contract. Required if payment gateway is enabled.

Show child attributes

contract.paymentSettings.scheduledPaymentDay

number

required

The specific day of the month when the payment will be scheduled. For example, a value of 1 means the payment will be scheduled on the 1st day of the month. A value of 31 represents the last day of the month, regardless of whether the month has 28, 30, or 31 days.

Required range: 1 <= x <= 31

contract.paymentSettings.dueOffsetDays

number

required

Number of days after the payment start date until payment is due (minimum of 5 days).

Required range: x >= 5

contract.billingSettings

object

required

Contract billing settings.

Show child attributes

contract.billingSettings.billingCycleMinimumAmount

number

required

Minimum amount to be charged in a billing cycle.

Required range: x >= 0

contract.sendNotifications

boolean

Indicates whether notifications should be sent for this contract.

contract.rateAdjustmentIndex

enum<string> | null

Reference index (e.g. IPCA) used to filter contracts when applying a mass adjustment on contracts.

Available options:

none,

igpm,

ipca,

other

contract.customFields

object

Custom fields that can be associated with the entity. The fields must be previously created in the system before they can be used.

Show child attributes

contract.customFields.{key}

Example:

{
  "customField1": "value1",
  "customField2": ["value2", "value3"]
}

startDate

string<date>

required

The start date of the billing period.

endDate

string<date>

required

The end date of the billing period.

totalAmount

number

required

The total amount to be paid for this invoice.

Required range: x >= 0

closedReason

enum<string> | null

required

The reason why the billing cycle was closed.

Available options:

end_of_cycle,

billing_end_day_updated

payments

object[] | null

required

List of payments associated with this invoice.

Show child attributes

payments.id

string<uuid>

required

payments.amount

number

required

payments.dueDate

string<date>

required

payments.createdAt

string<date-time>

required

payments.processedAt

string<date-time> | null

required

payments.paymentMethod

enum<string> | null

required

Available options:

bolepix,

bank_slip,

pix

payments.status

enum<string>

required

Available options:

created,

pending,

paid,

failed,

canceled,

expired

payments.pixLink

string | null

required

payments.bankSlipLink

string | null

required

status

enum<string>

required

The current status of the invoice.

Available options:

open,

closed,

canceled

processorId

string | null

required

The identifier of the external processor used for this invoice.

plans

object[]

required

List of plans associated with this invoice.

Minimum array length: 1

Show child attributes

plans.id

string<uuid>

required

The unique identifier for this plan.

plans.name

string

required

The name of the plan.

Minimum string length: 1

plans.description

string | null

required

Optional description of the plan.

plans.planSettings

object

required

Settings configuration for this plan.

Show child attributes

plans.planSettings.id

string<uuid>

required

The plan settings id.

plans.planSettings.fixedAmount

number

required

The fixed cost amount for this plan.

Required range: x >= 0

plans.planSettings.minimumAmount

number

required

The minimum cost amount for this plan.

Required range: x >= 0

plans.totalAmount

number

required

The total amount for this plan.

Required range: x >= 0

plans.product

object

The product associated with this plan.

Show child attributes

plans.product.id

string<uuid>

required

The unique identifier for this product.

plans.product.name

string

required

The name of the product.

Minimum string length: 1

plans.product.customFields

object

Custom fields that can be associated with the entity. The fields must be previously created in the system before they can be used.

Show child attributes

plans.product.customFields.{key}

Example:

{
  "customField1": "value1",
  "customField2": ["value2", "value3"]
}

plans.metrics

object[]

List of metrics associated with this plan.

Minimum array length: 1

Invoice in full metric schema.

Option 1
Option 2

Show child attributes

plans.metrics.id

string<uuid>

required

The unique identifier for this metric.

plans.metrics.resourceId

string<uuid>

required

The ID of the resource this metric is associated with.

plans.metrics.currencyUnitId

string<uuid>

required

The ID of the currency unit this metric is associated with.

plans.metrics.name

string

required

The name of the metric.

Minimum string length: 1

plans.metrics.billingModel

enum<string>

required

The billing model type, set to InFull.

Available options:

in_full

plans.metrics.priceTierDivision

enum<string>

required

The price tier division method for this metric.

Available options:

unique_tier,

progressive

plans.metrics.fixedAmount

number

required

The fixed cost amount for this metric.

Required range: x >= 0

plans.metrics.minimumAmount

number

required

The minimum cost amount for this metric.

Required range: x >= 0

plans.metrics.resourceName

string

required

The name of the resource.

Minimum string length: 1

plans.metrics.resourceType

enum<string>

required

The resource type.

Available options:

unit,

currency

plans.metrics.priceTiers

object[]

required

List of price tiers for this metric.

Show child attributes

plans.metrics.priceTiers.id

string<uuid>

required

The unique identifier for this price tier.

plans.metrics.priceTiers.billingType

enum<string>

required

The billing type for this price tier.

Available options:

unit,

package,

flat,

basis_points

plans.metrics.priceTiers.from

number

required

The starting value for this price tier.

Required range: x >= 1

plans.metrics.priceTiers.to

number | null

required

The ending value for this price tier. Null indicates no upper bound.

Required range: x >= 1

plans.metrics.priceTiers.packageSize

number | null

required

The package size for package-based billing. Null if not package-based.

Required range: x >= 1

plans.metrics.priceTiers.price

string | null

required

The price for this tier in decimal format.

plans.metrics.priceTiers.fixedPrice

string | null

required

The fixed price for this tier in decimal format.

plans.metrics.priceTiers.basisPoints

number | null

required

The basis points associated with this price tier in decimal format

Required range: x >= 0

plans.metrics.priceTiers.totalAmount

number

required

The total amount for this price tier.

Required range: x >= 0

plans.metrics.priceTiers.usage

number

required

The usage amount for this price tier.

Required range: x >= 0

plans.metrics.totalAmount

number

required

The total amount for this metric.

Required range: x >= 0

plans.metrics.resourceCustomFields

object

Custom fields that can be associated with the entity. The fields must be previously created in the system before they can be used.

Show child attributes

plans.metrics.resourceCustomFields.{key}

plans.metrics.currencyUnit

object

Show child attributes

plans.metrics.currencyUnit.id

string

required

plans.metrics.currencyUnit.name

string

required

plans.metrics.currencyUnit.code

string

required

additionalItems

object[]

required

List of additional items charged in this invoice.

Show child attributes

additionalItems.id

string<uuid>

required

The additional item id.

additionalItems.name

string

required

Name of the additional item.

Minimum string length: 1

additionalItems.description

string | null

required

Optional description of the additional item.

Minimum string length: 1

additionalItems.amount

number

required

Cost amount of the additional item.

Required range: x >= 1

additionalItems.type

enum<string>

required

Type of the additional billing item.

Available options:

discount,

additional_charge

Fetch invoice PDFThis endpoint allows fetching an invoice PDF.

⌘I

Fetch invoice by processor ID

curl --request GET \
  --url https://api.useaira.com/v1/invoices/by-processor-id/{processorId} \
  --header 'X-API-KEY: <api-key>'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "displayId": "<string>",
  "customer": {
    "id": "<string>",
    "externalId": "705faf65-9c8b-4053-8c0b-2021281ce83f",
    "name": "Acme Inc.",
    "customFields": {
      "customField1": "value1",
      "customField2": [
        "value2",
        "value3"
      ]
    }
  },
  "paymentAccount": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "businessName": "<string>",
    "taxId": "<string>",
    "taxIdType": "cnpj",
    "tradeName": "<string>",
    "email": "[email protected]",
    "address": {
      "zipCode": "<string>",
      "number": "<string>",
      "street": "<string>",
      "neighborhood": "<string>",
      "city": "<string>",
      "state": "AC",
      "country": "Brasil",
      "complement": "<string>"
    }
  },
  "contract": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "startDate": "2023-12-25",
    "endDate": "2023-12-25",
    "billingEndDay": 16,
    "status": "active",
    "paymentSettings": {
      "scheduledPaymentDay": 16,
      "dueOffsetDays": 6
    },
    "billingSettings": {
      "billingCycleMinimumAmount": 1
    },
    "sendNotifications": true,
    "rateAdjustmentIndex": "none",
    "customFields": {
      "customField1": "value1",
      "customField2": [
        "value2",
        "value3"
      ]
    }
  },
  "startDate": "2023-12-25",
  "endDate": "2023-12-25",
  "totalAmount": 1,
  "closedReason": "end_of_cycle",
  "payments": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "amount": 123,
      "dueDate": "2023-12-25",
      "createdAt": "2023-11-07T05:31:56Z",
      "processedAt": "2023-11-07T05:31:56Z",
      "paymentMethod": "bolepix",
      "status": "created",
      "pixLink": "<string>",
      "bankSlipLink": "<string>"
    }
  ],
  "status": "open",
  "processorId": "<string>",
  "plans": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "description": "<string>",
      "planSettings": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "fixedAmount": 1,
        "minimumAmount": 1
      },
      "totalAmount": 1,
      "product": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "customFields": {
          "customField1": "value1",
          "customField2": [
            "value2",
            "value3"
          ]
        }
      },
      "metrics": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "resourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "currencyUnitId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "billingModel": "in_full",
          "priceTierDivision": "unique_tier",
          "fixedAmount": 1,
          "minimumAmount": 1,
          "resourceName": "<string>",
          "resourceType": "unit",
          "priceTiers": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "billingType": "unit",
              "from": 2,
              "to": 2,
              "packageSize": 2,
              "price": "<string>",
              "fixedPrice": "<string>",
              "basisPoints": 1,
              "totalAmount": 1,
              "usage": 1
            }
          ],
          "totalAmount": 1,
          "resourceCustomFields": {},
          "currencyUnit": {
            "id": "<string>",
            "name": "<string>",
            "code": "<string>"
          }
        }
      ]
    }
  ],
  "additionalItems": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "description": "<string>",
      "amount": 2,
      "type": "discount"
    }
  ]
}

Conheça a Aira

Conceitos Essenciais

Referência da API

Fetch invoice by processor ID

Authorizations

Path Parameters

Response