@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Customer Credit API
@base https://apiexamples.vtexcommercestable.com.br
@version 1.0
@auth ApiKey X-VTEX-API-AppKey in header | ApiKey X-VTEX-API-AppToken in header | ApiKey VtexIdclientAutCookie in header
@common_fields {Content-Type: str # Type of the content being sent., Accept: str # HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.}
@endpoints 25
@hint download_for_search
@toc api(25)

@endpoint GET /api/creditcontrol/invoices
@desc Search all invoices
@required {creditAccountId: str # Credit account identification.}
@optional {from: str # Indicates the starting position of the invoice to be searched in the invoice list. For example, the value `1` indicates that the first invoice in the list will be returned., to: str # Indicates the final position of the invoice to be searched in the invoice list. For example, if the value of `from` is equal to `1` and `to` is `300`, information from 300 invoices will be displayed in the response body of the request., createdDateFrom: str # Indicates the initial creation date of invoices that should be searched in the invoice list based on their creation date. The dates should be in ISO8601 format., createdDateTo: str # Indicates the final creation date of invoices that should be searched in the invoice list based on their creation date. The dates should be in ISO8601 format., dueDateFrom: str # Indicates the initial due date of invoices that should be searched in the invoice list based on their creation date. The dates should be in ISO8601 format., dueDateTo: str # Indicates the final due date of invoices that should be searched in the invoice list based on their creation date. The dates should be in ISO8601 format., value: num # Indicates the value of the invoices to be searched for. It must be completed with a decimal value., status: str(Opened/Paid/Cancelled) # Indicates the status of the invoices to be searched for., friendlyId: str # Simplified identification of an invoice. This code is created automatically, always associated with an existing invoice. It consists of an 8-digit random ID (of numbers and letters) and the installment., observation: str # Observation notes about the invoice.}
@returns(200) {data: [map], summary: map{total: num, count: int, totalPaid: num, totalCancelled: num}} # OK

@endpoint GET /api/creditcontrol/accounts/{creditAccountId}/invoices/{invoiceId}
@desc Retrieve invoice by ID
@required {creditAccountId: str # Credit account identification., invoiceId: str # Invoice identification.}
@returns(200) {id: str, friendlyId: str, status: str, value: num, accountId: str, creditValue: num, createdAt: str, updatedAt: str, originalDueDate: str, dueDate: str, installment: num, orderId: str, transactionId: str, numberOfInstallments: num, creditAccountId: str} # OK

@endpoint PUT /api/creditcontrol/accounts/{creditAccountId}/invoices/{invoiceId}
@desc Change invoice
@required {creditAccountId: str # Credit account identification., invoiceId: str # Invoice identification., status: str(Opened/Paid/Cancelled) # Invoice status.}
@optional {friendlyId: str # Simplified identification of an invoice. This code is created automatically, always associated with an existing invoice. It consists of an 8-digit random ID (of numbers and letters) and the installment., observation: str # Observation notes about the invoice., paymentLink: str # Link (URL) created to direct the customer to an invoice payment environment (optional).}
@returns(200) OK. This endpoint does not return any data in the response body.

@endpoint DELETE /api/creditcontrol/accounts/{creditAccountId}/invoices/{invoiceId}
@desc Cancel invoice
@required {creditAccountId: str # Credit account identification., invoiceId: str # Invoice identification.}
@returns(200) OK. This endpoint does not return any data in the response body.

@endpoint GET /api/creditcontrol/accounts/{creditAccountId}/invoices
@desc Retrieve invoices by Customer Credit account ID
@required {creditAccountId: str # Credit account identification.}
@returns(200) {data: [map], summary: map{total: num, count: int, totalPaid: int, totalCancelled: int}} # OK

@endpoint POST /api/creditcontrol/accounts/{creditAccountId}/invoices/{invoiceId}/payments
@desc Mark an invoice as paid
@required {creditAccountId: str # Credit account identification., invoiceId: str # Invoice identification.}
@returns(200) {id: str, friendlyId: str, status: str, value: num, accountId: str, creditValue: num, createdAt: str, updatedAt: str, originalDueDate: str, dueDate: str, installment: num, orderId: str, transactionId: str, numberOfInstallments: num, creditAccountId: str} # OK

@endpoint PUT /api/creditcontrol/accounts/{creditAccountId}/invoices/{invoiceId}/postponement
@desc Postpone an invoice
@required {creditAccountId: str # Credit account identification., invoiceId: str # Invoice identification., dueDays: num # Number of days to postpone the invoice.}
@returns(200) OK. This endpoint does not return any data in the response body.

@endpoint GET /api/creditcontrol/accounts
@desc Search all accounts
@optional {from: str # Indicates the starting position of the credit customer account to be searched in the account list. Example, value `1` indicates that the first account in the list will be returned., to: str # Indicates the final position of the credit customer account to be searched in the account list. Example, if the value of `from` is equal to `1` and `to` is `40`, information from 40 accounts will be displayed in the response body of the request., status: str(Opened/Paid/Cancelled) # Indicates the status of the accounts to be searched for., email: str # Indicates the email registered to the account to be searched.}
@returns(200) {data: [map], summary: map{count: int}} # OK

@endpoint POST /api/creditcontrol/accounts
@desc Open an account
@required {document: str # Account owner document., documentType: str(CPF/CNPJ/Other) # Document type., email: str # Account owner email., creditLimit: str # Maximum credit amount on the account., description: str # This field is deprecated., tolerance: str # Account credit tolerance (in decimals). This value represents the increase in credit on an account. For example, a value of `0.30` indicates that the account owner can use up to 30% above the account's original maximum credit amount.}
@returns(200) {id: str, balance: num, document: str, status: str, documentType: str, creditLimit: num, updatedAt: str, createdAt: str, description: str, availableCredit: num, preAuthorizedCredit: num, email: str, tolerance: num, availableBalance: num} # OK

@endpoint GET /api/creditcontrol/accounts/{creditAccountId}
@desc Retrieve an account by ID
@required {creditAccountId: str # Credit account identification.}
@returns(200) {id: str, balance: num, document: str, status: str, documentType: str, creditLimit: num, updatedAt: str, createdAt: str, description: str, availableCredit: num, preAuthorizedCredit: num, email: str, tolerance: num, availableBalance: num} # OK

@endpoint DELETE /api/creditcontrol/accounts/{creditAccountId}
@desc Close an account
@required {creditAccountId: str # Credit account identification.}
@optional {document: str # Account owner document., documentType: str(CPF/CNPJ/Other) # Document type., email: str # Account owner email.}
@returns(200) {id: str, balance: num, document: str, status: str, documentType: str, creditLimit: num, updatedAt: str, createdAt: str, description: str, availableCredit: num, preAuthorizedCredit: num, email: str, tolerance: num, availableBalance: num} # OK

@endpoint PUT /api/creditcontrol/accounts/{creditAccountId}
@desc Update account information
@required {creditAccountId: str # Credit account identification., email: str # Account owner email., document: str # Account owner document., documentType: str(CPF/CNPJ/Other) # Document type.}
@optional {creditLimit: num # Maximum credit amount on the account., tolerance: num # Account credit tolerance (in decimals). This value represents the increase in credit on an account. For example, a value of `0.30` indicates that the account owner can use up to 30% above the account's original maximum credit amount.}
@returns(200) {id: str, balance: num, document: str, status: str, documentType: str, creditLimit: num, updatedAt: str, createdAt: str, description: str, availableCredit: num, preAuthorizedCredit: num, email: str, tolerance: num, availableBalance: num} # OK

@endpoint GET /api/creditcontrol/accounts/{creditAccountId}/statements
@desc Get account statements
@required {creditAccountId: str # Credit account identification.}
@returns(200) {statements: [map], currentBalance: num, intervalBalance: num, previousBalance: num} # OK

@endpoint PUT /api/creditcontrol/accounts/{creditAccountId}/creditlimit
@desc Change credit limit of an account
@required {creditAccountId: str # Credit account identification., value: num # Credit limit value.}
@returns(200) {id: str, balance: num, status: str, creditLimit: num, updatedAt: str, createdAt: str, description: str, availableCredit: num, preAuthorizedCredit: num, email: str, tolerance: num, availableBalance: num} # OK

@endpoint PUT /api/creditcontrol/accounts/{creditAccountId}/statements/{statementId}
@desc Decrease balance of an account
@required {creditAccountId: str # Credit account identification., statementId: str # Statement identification. This is the same `transactionId` value obtained from the [Account statements](https://developers.vtex.com/docs/api-reference/customer-credit-api#get-/api/creditcontrol/accounts/-creditAccountId-) endpoint response body., value: str # Value to be debited from the account balance.}
@returns(200) {value: str} # OK

@endpoint PUT /api/creditcontrol/accounts/{creditAccountId}/transactions/{transactionId}/settlement
@desc Create or update settlement
@required {creditAccountId: str # Credit account identification., transactionId: str # Pre-authorization identification., value: num # Value to be settled in the invoice.}
@returns(200) {value: num, id: str} # OK

@endpoint POST /api/creditcontrol/accounts/{creditAccountId}/transactions
@desc Create a pre-authorization
@required {creditAccountId: str # Credit account identification., value: num # Pre-Authorization value., settle: bool # Indicates whether pre-authorization should be available to be settled. This means that the `transactionId` created in this request can be used to be associated with an order within a maximum period of 30 days., installments: num # Number of installments.}
@optional {expirationDate: str # Pre-Authorization expiration date. This field should only be sent if the `settle` field is sent as `false`.}
@returns(200) {id: str, value: num, expirationDate: str, installments: num} # OK

@endpoint PUT /api/creditcontrol/accounts/{creditAccountId}/transactions/{transactionId}
@desc Update a pre-authorization
@required {creditAccountId: str # Credit account identification., transactionId: str # Pre-authorization identification., value: num # Pre-Authorization value., settle: bool # Indicates whether pre-authorization should be available to be settled. This means that the `transactionId` can be used to be associated with an order within a maximum period of 30 days., installments: num # Number of installments.}
@returns(200) {id: str, value: num, installments: num} # OK

@endpoint DELETE /api/creditcontrol/accounts/{creditAccountId}/transactions/{transactionId}
@desc Cancel a pre-authorization
@required {creditAccountId: str # Credit account identification., transactionId: str # Pre-authorization identification.}
@returns(200) OK. This endpoint does not return any data in the response body.

@endpoint POST /api/creditcontrol/accounts/{creditAccountId}/holders
@desc Add an account holder
@required {creditAccountId: str # Credit account identification., claims: map{email!: str} # Holder information.}
@returns(200) {level: num, claims: map{email: str}, id: str, createdAt: str} # OK

@endpoint DELETE /api/creditcontrol/accounts/{creditAccountId}/holders/{holderId}
@desc Delete an account holder
@required {creditAccountId: str # Credit account identification., holderId: str # Holder identification.}
@returns(200) {id: str} # OK

@endpoint PUT /api/creditcontrol/accounts/{creditAccountId}/tolerance
@desc Change tolerance of an account
@required {creditAccountId: str # Credit account identification., value: num # This value represents the increase in credit on an account. For example, a value of `0.30` indicates that the account owner can use up to 30% above the account's original maximum credit amount.}
@returns(200) {id: str, balance: num, status: str, creditLimit: num, updatedAt: str, createdAt: str, description: str, availableCredit: num, preAuthorizedCredit: num, email: str, tolerance: num, availableBalance: num} # OK

@endpoint POST /api/creditcontrol/accounts/{creditAccountId}/transactions/{transactionId}/refunds
@desc Partially or totally refund a settlement
@required {creditAccountId: str # Credit account identification., transactionId: str # Pre-authorization identification., value: num # Refund amount. This number must always be less than or equal to the value of the captured transaction.}
@returns(200) {value: num} # OK

@endpoint GET /api/creditcontrol/storeconfig
@desc Retrieve store configuration
@returns(200) {dailyInterestRate: num, invoicePostponementLimit: num, taxRate: num, maxPostponementDays: num, defaultCreditValue: num, postponementEnabled: bool, automaticCheckingAccountCreationEnabled: bool, toleranceEnabled: bool, myCreditsEnabled: bool, maxPreAuthorizationGrowthRate: num, notificationsSettings: map{daysPrior: [map], daysAfter: [map]}} # OK

@endpoint PUT /api/creditcontrol/storeconfig
@desc Create or change store configuration
@required {dailyInterestRate: num # Daily interest rate (percent 0.1 = 10%)., invoicePostponementLimit: num # Maximum number of postponements allowed., taxRate: num # Tax rate value (percent 0.1 = 10%)., maxPostponementDays: num # Maximum number of days of postponement., defaultCreditValue: num # Default credit amount., maxPreAuthorizationGrowthRate: num # Pre-authorization growth rate value (percent 0.1 = 10%)., myCreditsEnabled: bool # Show the [My Credits](https://help.vtex.com/en/tutorial/customer-credit-overview--1uIqTjWxIIIEW0COMg4uE0#my-credits) page on storefront., toleranceEnabled: bool # Allows orders to be placed even if they exceed X % of the account's credit limit., automaticCheckingAccountCreationEnabled: bool # Allows users who have not previously received credit to complete an order., postponementEnabled: bool # Postponement option activated.}
@optional {notificationsSettings: map{daysPrior: [map], daysAfter: [map]} # Notification settings information.}
@returns(200) {dailyInterestRate: num, invoicePostponementLimit: num, taxRate: num, maxPostponementDays: num, defaultCreditValue: num, postponementEnabled: bool, automaticCheckingAccountCreationEnabled: bool, toleranceEnabled: bool, myCreditsEnabled: bool, maxPreAuthorizationGrowthRate: num, notificationsSettings: map{daysPrior: [map], daysAfter: [map]}} # OK

@end