Search Invoice by Key

The invoice search by key will return the complete details of a specific invoice, including all invoice items.

Request

ENDPOINT

/wallet/WALLET_KEY/invoice/INVOICE_KEY

METHOD

GET

Path Parameters

Field	Type	Description	Characters
wallet_key	uuidv4	Unique wallet key in UUID v4 format	36
invoice_key	uuidv4	Unique invoice key in UUID v4 format	36

Response

STATUS

200

Response Body: Invoice details

{
  "invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "due_date": "2024-02-15",
  "closing_date": "2024-01-31",
  "invoice_status": "opened",
  "total_amount": 350.00,
  "paid_amount": 0.00,
  "invoice_items": [
    {
      "invoice_item_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "wallet_entry_key": null,
      "payment_instrument_entry_key": "g3ebe8d6-4c8a-1794-22d9-406c0f8g3dbe",
      "installment_number": 1,
      "invoice_description": "Compra no estabelecimento XYZ",
      "amount": 150.00,
      "used_limit": 150.00,
      "paid_amount": 0.00,
      "invoice_item_status": "concluded",
      "invoice_item_due_date": "2024-02-15",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "invoice_item_key": "b2c3d4e5-f6g7-8901-bcde-f23456789012",
      "invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "wallet_entry_key": null,
      "payment_instrument_entry_key": "g3ebe8d6-4c8a-1794-22d9-406c0f8g3dbe",
      "installment_number": 2,
      "invoice_description": "Parcela 2 de 3 - Compra parcelada",
      "amount": 200.00,
      "used_limit": 200.00,
      "invoice_item_status": "concluded",
      "invoice_item_due_date": "2024-02-15",
      "created_at": "2024-01-16T14:45:00Z"
    }
  ],
  "invoice_payments": [
    {
      "invoice_payment_key": "c3d4e5f6-g7h8-9012-cdef-345678901234",
      "total_amount": 350.00,
      "paid_amount": 0.00,
      "invoice_payment_type": "bank_slip",
      "invoice_payment_status": "paid"
    }
  ],
  "invoice_payments_chargebacks": [
    {
      "invoice_item_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "chargeback_paid_amount": 50.00
    }
  ],
  "created_at": "2024-01-15T10:30:00Z"
}

Response Body Params

Field	Type	Description	Characters
invoice_key *	uuidv4	Unique invoice identification key in uuid v4 format	36
due_date *	string	Invoice due date (YYYY-MM-DD format)	10
closing_date *	string	Invoice closing date (YYYY-MM-DD format)	10
invoice_status *	string	Invoice status	Enumerators invoice_status
total_amount *	number	Total invoice amount	-
paid_amount *	number	Paid invoice amount	-
invoice_items *	object array	Invoice items	Object invoice_item
invoice_payments *	object array	Invoice payments	Object invoice_payment
invoice_payments_chargebacks *	object array	Invoice payment chargebacks	Object invoice_payment_chargeback
created_at *	string	Creation date (ISO 8601 UTC format)	-

Object invoice_item

Field	Type	Description	Characters
invoice_item_key *	uuidv4	Unique invoice item identification key in uuid v4 format	36
invoice_key *	uuidv4	Unique invoice identification key in uuid v4 format	36
wallet_entry_key	uuidv4	Unique wallet entry identification key in uuid v4 format	36
payment_instrument_entry_key	uuidv4	Unique payment instrument entry identification key in uuid v4 format	36
installment_number *	integer	Installment number	-
invoice_description *	string	Invoice item description	-
amount *	float	Item amount	-
used_limit *	float	Used limit	-
invoice_item_status *	string	Invoice item status	Enumerators invoice_item_status
invoice_item_due_date *	string	Item due date (YYYY-MM-DD format)	10
created_at *	string	Creation date (ISO 8601 UTC format)	-

Object invoice_payment

Field	Type	Description	Characters
invoice_payment_key *	uuidv4	Unique invoice payment identification key in uuid v4 format	36
total_amount	number	Total payment amount	-
paid_amount	number	Paid payment amount	-
invoice_payment_type *	string	Invoice payment type	Enumerators invoice_payment_type
invoice_payment_status *	string	Invoice payment status	Enumerators invoice_payment_status

Object invoice_payment_chargeback

Field	Type	Description	Characters
invoice_item_key *	uuidv4	Unique identification key of the invoice item related to the chargeback in uuid v4 format	36
chargeback_paid_amount	number	Used chargeback amount	-

Enumerators invoice_status

Enumerator	Description
opened	Open invoice
processing_closing	Processing closure
processing_expiration	Processing expiration
closed	Closed invoice
processing_payment	Awaiting payment
paid	Paid invoice

Note

The processing_payment status is applied only for payroll type wallets in the scenario where the possible payment amount has already been made and there is a remaining amount to be paid with the benefit.

Enumerators invoice_payment_type

Enumerator	Description
bank_slip	Bank slip
payroll_discount	INSS discount

Note

The payroll_discount type exists only for payroll type wallets and represents the amount that will be discounted via benefit.

Enumerators invoice_payment_status

Enumerator	Description
processing_payment	Awaiting payment
paid	Paid

Note

• For payroll_discount type payments: the payment is created at the time of invoice closure with processing_payment status and the discount is requested from INSS. When the discount payment is made, the status changes to paid.
• For bank_slip type payments: the payment is created with processing_payment status when we receive the bank slip payment notice. At the time of bank slip settlement, the status changes to paid. The payment can be created with paid status directly if a payment notice is not received.

Enumerators invoice_item_status

Enumerator	Description
concluded	Concluded item
canceled	Canceled item

Error Response

STATUS

4xx

Response Body: Error

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}

HTTP Code status	QI Code code	Title title	Description (eng) description	Description (pt-br) translation
404	CIN000007	Wallet not Found	Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found	Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado
404	CIN000016	Invoice Not Found	Invoice with key: 8cb70dea-9fb0-4a68-9572-99a72849c8d6 was not found	Fatura com a chave: 8cb70dea-9fb0-4a68-9572-99a72849c8d6 não foi encontrado