API Documentation

Environment

Production: https://api.kestraa.com.br

QA: https://api-qa.kestraa.com.br

PUT Edit Exchange

Updates an existing Exchange (foreign exchange payment) record.

Target URL: ${environment}/v1/finance/exchanges/${id}

Required Headers

Name	Description
Authorization	Bearer Token for authentication. or Apikey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-Type	Request content type (application/json).
ID	ID of the Exchange within the Kestraa platform.

Request Body

{
  "bank": "",
  "comments": "",
  "contract": "teste_vitor",
  "currencyRate": "2.2",
  "paidDate": "2025-06-01T00:00:00",
  "dueDate": "2025-04-14T00:00:00",
  "type": "PREPAYMENT",
  "value": 200000,
  "erpCode": ""
}

Field Explanation

Field	Mandatory	Type	Description
bank	No	varchar(100)	Nome e código do banco (campo atualizável). Exemplo: 002 - Banco Shanghai.
comments	No	varchar(250)	Comentário sobre o pagamento (Exchange) (campo atualizável).
contract	No	varchar(25)	Número do contrato relacionado (campo atualizável). Exemplo: XPTO01.
currencyRate	No	numeric(8,4)	Taxa de conversão da moeda (campo atualizável). Exemplo: 2.2000.
paidDate	No	Date/Time	Data de pagamento (campo atualizável). Exemplo: 2025-04-14T00:00:00.
dueDate	Yes	Date/Time	Data de vencimento do pagamento (não pode ser atualizado após a criação).
type	Yes	varchar(25)	Tipo de pagamento (não pode ser atualizado após a criação).
value	Yes	numeric(10,4)	Valor total do pagamento (não pode ser atualizado após a criação). Exemplo: 1500.0000.
erpCode	No	varchar(12)	Id gerado pelo ERP (campo atualizável). Exemplo: 152365845.

Response

{
    "id": "471ff387-34de-466f-895e-0c413ca97810",
    "invoiceId": 58357789,
    "purchaseOrderId": 58357788,
    "referenceNumber": "xpto1",
    "order": "01",
    "type": "PrePayment",
    "value": 10000.00,
    "dueDate": "2024-07-29T12:00:00",
    "paidDate": "2024-07-29T12:00:00",
    "paymentTerms": "0001-pagamento imediato 4",
    "contract": "xpto1",
    "currencyRate": 2.2,
    "comments": "xpto1",
    "createdAt": "2024-07-29T10:01:03",
    "updatedAt": "2024-07-29T10:01:03",
    "totalValueInvoice": 1000.00,
    "purchaseOrderNumber": "xpto01",
    "erpCode": "Error",
    "bank": "01 - Santander",
    "canIntegrate": true,
    "invoice": "xpto01",
    "balance": 20.20,
    "allocated": null,
    "letterOfCredit": null
}

Response Field Explanation

Field	Description
id	Identificador único do pagamento.
invoiceId	Sem vínculo com fatura no momento.
purchaseOrderId	ID interno da Purchase Order associada.
referenceNumber	Número de referência não informado.
order	Código do pedido.
type	Tipo de pagamento.
value	Valor do pagamento.
dueDate	Data de vencimento.
paidDate	Pagamento ainda não realizado.
paymentTerms	Condição de pagamento.
contract	Número de contrato não informado.
currencyRate	Taxa de conversão da moeda não informada.
comments	Comentários adicionais ausentes.
createdAt	Data de criação do registro.
updatedAt	Última atualização do registro.
totalValueInvoice	Valor total da fatura ainda não registrado.
erpCode	Código de retorno do ERP.
bank	Nome/código do banco não informado.
canIntegrate	Flag indicando que o item pode ser integrado.
invoice	Objeto de fatura não vinculado.
balance	Saldo ainda não informado.
allocated	Valor alocado não informado.
letterOfCredit	Carta de crédito não vinculada.

HTTP Status Codes

Code	Description
200	OK
400	Bad Request
401	Unauthorized
500	Server Error

GET Query Exchange

Lists Exchange (foreign exchange payment) records, optionally filtered by reference number.

Target URL: ${environment}/v1/finance/exchanges?filter=${referenceNumber}

Required Headers

Name	Description
Authorization	Bearer Token for authentication. or Apikey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Query Parameters

Field	Description
filter	Reference number used to filter the Exchange list (e.g. 5500000746-1).

Response

{
    "content": [
        {
            "id": "471ff387-34de-466f-895e-0c413ca97810",
            "type": "PREPAYMENT",
            "dueDate": "2024-07-29T00:00:00",
            "contract": "teste_vitor_v1",
            "paidDate": null,
            "value": 10000.00,
            "currencyRate": 2.2000,
            "comments": "",
            "currency": "USD",
            "remainingValue": 20000.00,
            "invoice": {
                "id": null,
                "number": null
            },
            "purchaseOrder": {
                "id": "58357788",
                "number": "5500000746"
            },
            "shipment": {
                "id": null,
                "number": null
            },
            "erpCode": "Error",
            "bank": "",
            "canIntegrate": false,
            "balance": 10000.00,
            "currencyId": 213,
            "currencyName": "US Dollar",
            "exporterId": 287921,
            "exporterName": "300011 - Fornecedor US Trade",
            "referenceNumber": "5500000746-1",
            "shippingNumber": null,
            "letterOfCredit": null,
            "issuingBank": null
        }
    ],
    "numberOfElements": 1,
    "size": 20,
    "totalPages": 1,
    "cockpit": {
        "dueExchanges": 0,
        "overdue": 144,
        "paid": 301
    },
    "totalNumberOfExchanges": 445,
    "totalValueByCurrency": [
        {
            "currency": "BRL",
            "totalValue": 97000.00
        },
        {
            "currency": "EUR",
            "totalValue": 787063.91
        },
        {
            "currency": "JPY",
            "totalValue": 2552953.93
        },
        {
            "currency": "USD",
            "totalValue": 43788878.94
        }
    ]
}

Response Field Explanation

Field	Description
id	Identificador único do pagamento.
type	Tipo do pagamento.
dueDate	Data de vencimento do pagamento.
contract	Número ou identificador do contrato associado ao pagamento.
paidDate	Data em que o pagamento foi realizado.
value	Valor total do pagamento.
currencyRate	Taxa de conversão da moeda utilizada.
comments	Comentários ou observações sobre o pagamento.
currency	Código da moeda utilizada no pagamento.
remainingValue	Valor restante a ser quitado do pagamento.
invoice	Objeto contendo dados da fatura associada ao pagamento.
purchaseOrder	Objeto contendo dados da ordem de compra relacionada.
shipment	Objeto contendo dados do embarque vinculado ao pagamento.
erpCode	Código de status ou retorno do sistema ERP.
bank	Nome e/ou código do banco vinculado ao pagamento.
canIntegrate	Indica se o pagamento pode ser integrado com outros sistemas.
balance	Saldo atual disponível relacionado ao pagamento.
currencyId	Identificador interno da moeda utilizada.
currencyName	Nome da moeda utilizada.
exporterId	Identificador interno do exportador.
exporterName	Nome ou razão social do exportador.
referenceNumber	Número de referência único do pagamento.
shippingNumber	Número de referência relacionado ao embarque (caso exista).
letterOfCredit	Informações sobre carta de crédito, se houver.
issuingBank	Banco emissor da carta de crédito.
content	Lista com os dados detalhados de pagamentos.
numberOfElements	Quantidade de registros retornados na lista atual.
size	Quantidade máxima de registros por página.
totalPages	Número total de páginas com base na quantidade de registros.
cockpit	Objeto contendo resumo dos pagamentos (vencidos, pagos, etc.).
cockpit.dueExchanges	Quantidade de pagamentos a vencer.
cockpit.overdue	Quantidade de pagamentos vencidos.
cockpit.paid	Quantidade de pagamentos já quitados.
totalNumberOfExchanges	Número total de registros de pagamento encontrados.
totalValueByCurrency	Lista de valores totais agrupados por moeda.
totalValueByCurrency.[n].currency	Código da moeda.
totalValueByCurrency.[n].totalValue	Valor total da moeda agrupada.

HTTP Status Codes

Code	Description
200	OK
400	Bad Request
401	Unauthorized
500	Server Error