API Documentation - Purchase Order

Environment

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

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

POST Create a Purchase Order

Adds purchase orders from ERP.

Target URL: ${environment}/documents/purchaseorders/

Rate Limits: 5 requests per second per token.

Required Headers

Name	Description
Authorization	Bearer Token for authentication. or Apikey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-Type	Request content type (application/json).

Request Body

{
  "status":"Approved",
  "corporationDivision":126,
  "number":"New",
  "operation":"Import",
  "currency":"BRL",
  "issueDate":"2024-08-16T18:49:41.382Z",
  "paymentTerms":"FREE OF CHARGE",
  "totalValue":462,
  "incoterm":"CIF",
  "transportMode":"Sea",
  "items":[
    {
      "positionErp":10,
      "partNumber":"12121",
      "vendorNumber":"2",
      "description":"APARELHO WIRELESS RECEBEDOR PARA CADEIRAS DE CINEMA COM BOTÃO MODELO MC250 501711, CONEXÃO 5PIN DIN PLUG, OPERA NA FREQUÊNCIA 2.4GHZ, VOLTAGEM DE 29V.",
      "ncm":"43434233",
      "currency":"BRL",
      "quantity":"22",
      "quantityMeasurementUnit":"KG",
      "value":"21.000",
      "weight":"12",
      "weightMeasurementUnit":"KG",
      "shippingDate":"20240816"
    }
  ],
  "thirdParties":[
    {
      "nif":"10001",
      "companyId":1883,
      "role":"importer",
      "name":"teste"
    },
    {
      "nif":"10002",
      "companyId":365484,
      "partnerErpCode":"1239494",
      "role":"exporter",
      "name":"teste2"
    },
    {
      "nif":"10003",
      "companyId":287423,
      "partnerErpCode":"1239495",
      "role":"manufacturer",
      "name":"teste3"
    },
    {
      "nif":"11222333000181",
      "companyId":105,
      "partnerErpCode":"1239496",
      "role":"customsbroker",
      "name":"teste4"
    }
  ]
}

Field Explanation

Field	Mandatory	Type	Description
status	Yes	String(30)	Purchase order status. [Approved, Cancelled, Waiting Approval]
corporationDivision	Yes	Int8	Corporate division ID responsible for the order (e.g. 126).
number	Yes	String(255)	Purchase order number (e.g. 40000100).
operation	No	String	Description of the operation related to the purchase order (e.g. Import).
currency	Yes	String(3)	Currency used in the transaction (e.g. BRL).
issueDate	Yes	Datetime	Issue date and time of the purchase order (e.g. 2024-08-16T18:49:41.382Z).
paymentTerms	No	String	Agreed payment terms (e.g. FREE OF CHARGE).
totalValue	Yes	Numeric	Total value of the purchase order (e.g. 462.00).
incoterm	Yes	String(3)	International commercial terms (e.g. CIF). [EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DPU, DAP, DDP]
transportMode	Yes	String(3)	Mode of transport used for goods delivery (e.g. Sea). [Air, Road, Sea]
items.[n].positionErp	Yes	Int	Item position in the ERP system (e.g. 10).
items.[n].partNumber	Yes	String(255)	Part number of the item (e.g. 12121).
items.[n].vendorNumber	No	String(120)	Supplier ID for the item (e.g. 2).
items.[n].description	Yes	String(200)	Detailed item description (e.g. Wireless receiver for cinema seats, Model MC250).
items.[n].ncm	Yes	String(8)	Fiscal classification of the item according to NCM (e.g. 43434233).
items.[n].currency	Yes	String(3)	Item currency (e.g. BRL).
items.[n].quantity	Yes	Numeric	Quantity of included items in the order (e.g. 22.0).
items.[n].quantityMeasurementUnit	Yes	String(10)	Measurement unit for the quantity (e.g. KG).
items.[n].value	Yes	Numeric	Unit value of the item (e.g. 21.0).
items.[n].weight	Yes	Numeric	Weight of the item (e.g. 12.0).
items.[n].weightMeasurementUnit	Yes	String	Unit of measure for weight (e.g. KG, LB).
items.[n].shippingDate	Yes	Date	Shipping date of the item, format YYYYMMDD (e.g. 20240816).
thirdParties.[n].companyId	No	Int8	ID of the company involved as a third party, registration number in Kestraa (e.g. 1883 for importer).
thirdParties.[n].partnerErpCode	No	String(50)	ID of the partner in the ERP (e.g. 1883 for exporter, customs broker, or manufacturer).
thirdParties.[n].nif	Yes	String(25)	Tax identification number of the company (e.g. 11222333000181).
thirdParties.[n].role	Yes	String(30)	Role played by the company in the transaction (e.g. importer, exporter, manufacturer, customsbroker).
thirdParties.[n].name	Yes	String(120)	Company name for each thirdParties entry (e.g. ABC S.A).

thirdParties.[n].role	Mandatory
importer	Yes
exporter	Yes
manufacturer	No
customsbroker	No

Response

{
  "corporationDivision": 126,
  "id": 1111111,
  "number": "xpto",
  "issueDate": "2025-05-20T18:49:41.382Z",
  "itemsUrl": "http://kestraadocuments-qa.kestraa.com.br/documents/purchaseorders/1111111",
  "linksUrl": "http://kestraadocuments-qa.kestraa.com.br/documents/purchaseorders/1111111",
  "thirdPartiesUrl": "http://kestraadocuments-qa.kestraa.com.br/documents/purchaseorders/1111111",
  "items": [
    {
      "id": 58630670,
      "quantity": 22,
      "quantityMeasurementUnit": "KG",
      "value": 21.000,
      "ncm": "43434233",
      "weight": 12,
      "weightMeasurementUnit": "KG",
      "partNumber": "12121",
      "currency": "BRL",
      "description": "APARELHO WIRELESS RECEBEDOR PARA CADEIRAS DE CINEMA COM BOTÃO MODELO MC250 501711, CONEXÃO 5PIN DIN PLUG, OPERA NA FREQUÊNCIA 2.4GHZ, VOLTAGEM DE 29V.",
      "positionErp": 10,
      "cancelled": false,
      "vendorNumber": "2",
      "shippingDate": "20240816",
      "update": false,
      "remove": false,
      "create": false,
      "notRemoved": true,
      "rabbitmqEvents": []
    }
  ],
  "status": "Waiting Approval",
  "sequencial": false,
  "transportMode": "Sea",
  "totalValue": 462,
  "currency": "BRL",
  "incoterm": "CIF",
  "paymentTerms": "FREE OF CHARGE",
  "operation": "Import",
  "eventsUrl": "http://kestraadocuments-qa.kestraa.com.br/documents/purchaseorders/1111111/events",
  "rabbitmqEvents": [
    {
      "id": null,
      "producer": "documents",
      "payload": "{\"id\":1111111,\"number\":\"xpto\",\"issueDate\":1747766981382,...}",
      "event_date": "2025-05-20 19:27",
      "user_id": null,
      "corporation_id": 126,
      "routing_key": "documents.purchaseorder",
      "entity_id": 1111111,
      "entity_type": "purchaseorder",
      "entity_version": "1.0",
      "action": "create"
    }
  ]
}

HTTP Status Codes

Code	Description
200	OK
201	Created
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error

GET Get Purchase Order Header

Returns the header data of a Purchase Order, including third parties, terms and status.

Target URL: ${environment}/api/document/purchaseorder/${id}/header

Required Headers

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

Path Parameters

Field	Description
id	ID of the purchase order within the Kestraa platform.

Query Parameters

Field	Mandatory	Type	Description
details	No	Boolean	If true, returns additional header details. Default: false.
userRole	No	String	User role used to resolve role-specific permissions on the response.
priority	No	String	Priority filter applied when resolving the header.

Response

{
  "id": 58357788,
  "corporationDivision": 126,
  "incoterm": "CIF",
  "status": "Approved",
  "number": "5500000746",
  "issueDate": "2024-08-16T18:49:41.382Z",
  "deliveryDate": "2024-09-20T00:00:00.000Z",
  "currencyCode": "BRL",
  "acquisitionCountry": "BR",
  "provenanceCountry": "US",
  "originCountry": "US",
  "pickupLocation": "Porto de Santos",
  "deliveryLocation": "São Paulo",
  "orderOrigin": "ERP",
  "loadStatus": "Pending",
  "importer": {
    "id": 1883,
    "company": 1883,
    "name": "100018 - Centro 1",
    "nif": "33567794000129",
    "role": "importer"
  },
  "exporter": {
    "id": 365484,
    "company": 365484,
    "name": "300013 - Demo Exporter",
    "nif": "005262781910",
    "role": "exporter"
  },
  "customBroker": null,
  "manufacturer": null,
  "trading": null,
  "broker": null,
  "companyImporter": 1883,
  "companyExporter": 365484,
  "isSelected": false,
  "totalValue": 462.00,
  "goodsAvailableDate": "2024-08-20",
  "references": [],
  "permission": {
    "canEdit": true,
    "canCancel": false
  },
  "corporation": 126,
  "paymentTerms": "FREE OF CHARGE",
  "transportMode": "Sea",
  "businessplaceCode": "1000",
  "companyCode": "1000",
  "businessPlaceBranch": "01",
  "operation": "Import",
  "accountAndOrder": false,
  "hasNotificationEnabled": false,
  "terms": {},
  "priority": "none"
}

Campos nulos não aparecem na resposta real (@JsonInclude(NON_NULL)) — foram mantidos no exemplo acima apenas para ilustrar os campos possíveis. O campo assignment nunca é retornado por esta rota (filtro interno não é aplicado nesse fluxo).

Response Field Explanation

Field	Type	Description
id	Long	ID interno da Purchase Order.
corporationDivision	Long	ID da divisão/corporação responsável pela PO.
poLinkInvoiceId	Long	ID de vínculo com a Invoice relacionada, quando existente.
poLinkShipmentId	Long	ID de vínculo com o Shipment relacionado, quando existente.
incoterm	String	Termo internacional de comércio (e.g. CIF, FOB).
status	String	Status da Purchase Order (e.g. Approved, Waiting Approval).
number	String	Número da Purchase Order.
issueDate	String (ISO 8601)	Data de emissão da PO.
deliveryDate	String (ISO 8601)	Data de entrega prevista.
currencyCode	String	Código da moeda utilizada (e.g. BRL, USD).
acquisitionCountry	String	País de aquisição.
provenanceCountry	String	País de procedência.
originCountry	String	País de origem.
pickupLocation	String	Local de coleta.
deliveryLocation	String	Local de entrega.
notificationSentAT	Date	Data/hora de envio da última notificação.
orderOrigin	String	Origem do pedido (e.g. ERP).
loadStatus	String	Status do carregamento (load) vinculado à PO.
importer	ThirdPartyDTO	Dados do importador. Ver tabela ThirdPartyDTO abaixo.
exporter	ThirdPartyDTO	Dados do exportador.
customBroker	ThirdPartyDTO	Dados do despachante aduaneiro.
manufacturer	ThirdPartyDTO	Dados do fabricante.
trading	ThirdPartyDTO	Dados da trading.
broker	ThirdPartyDTO	Dados do broker.
companyImporter	Long	ID da empresa importadora.
companyExporter	Long	ID da empresa exportadora.
companyCustomBroker	Long	ID da empresa despachante.
companyManufacturer	Long	ID da empresa fabricante.
isSelected	Boolean	Indica se a PO está selecionada. Default: false.
totalValue	BigDecimal	Valor total da Purchase Order.
goodsAvailableDate	String	Data de disponibilidade das mercadorias.
references	List<ReferenceDTO>	Lista de referências associadas à PO.
assignment	AssignmentDTO	Dados de atribuição/responsável. Nunca retornado nesta rota (sempre null/omitido).
permission	PermissionDTO	Permissões do usuário autenticado sobre a PO.
corporation	long	ID da corporação.
paymentTerms	String	Condições de pagamento.
transportMode	String	Modo de transporte (e.g. Sea, Air, Road).
businessplaceCode	String	Código do local de negócio.
companyCode	String	Código da empresa no ERP.
businessPlaceBranch	String	Filial do local de negócio.
operation	String	Tipo de operação (e.g. Import).
accountAndOrder	Boolean	Indica se a operação é "conta e ordem".
hasNotificationEnabled	Boolean	Indica se as notificações estão habilitadas para a PO.
terms	TermsDTO	Termos adicionais da PO.
priority	String	Nível de prioridade (e.g. none).

ThirdPartyDTO

Field	Type	Description
id	Long	ID do terceiro (third party) na plataforma Kestraa.
company	Long	ID da empresa vinculada ao terceiro.
name	String	Nome/razão social do terceiro. Resolvido via serviço de catálogo externo.
nif	String	Identificação fiscal do terceiro. Resolvido via serviço de catálogo externo.
role	String	Papel do terceiro na operação (e.g. importer, exporter, manufacturer, customsbroker).
attributes	ThirdPartyAttribute	Atributos adicionais do terceiro (objeto interno da lib kestraa-ddm).

HTTP Status Codes

Code	Description
200	OK
401	Unauthorized
404	Not Found
500	Internal Server Error

PUT Update a Purchase Order

Updates purchase orders from ERP.

Target URL: ${environment}/documents/purchaseorders/${id}

Rate Limits: 5 requests per second per token.

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 purchase order within the Kestraa platform.

Request Body

{
  "status":"Approved",
  "corporationDivision":126,
  "number":"New update",
  "operation":"Import",
  "currency":"BRL",
  "issueDate":"2024-08-16T18:49:41.382Z",
  "paymentTerms":"FREE OF CHARGE",
  "totalValue":462,
  "incoterm":"CIF",
  "transportMode":"Sea",
  "items":[
    {
      "positionErp":10,
      "partNumber":"12121",
      "vendorNumber":"2",
      "description":"APARELHO WIRELESS RECEBEDOR PARA CADEIRAS DE CINEMA COM BOTÃO MODELO MC250 501711, CONEXÃO 5PIN DIN PLUG, OPERA NA FREQUÊNCIA 2.4GHZ, VOLTAGEM DE 29V.",
      "ncm":"43434233",
      "currency":"BRL",
      "quantity":"22",
      "quantityMeasurementUnit":"KG",
      "value":"21.000",
      "weight":"12",
      "weightMeasurementUnit":"KG",
      "shippingDate":"20240816"
    }
  ],
  "thirdParties":[
    {
      "nif":"10001",
      "companyId":1883,
      "role":"importer",
      "name":"teste"
    },
    {
      "nif":"10002",
      "companyId":365484,
      "partnerErpCode":"1239494",
      "role":"exporter",
      "name":"teste2"
    },
    {
      "nif":"10003",
      "companyId":287423,
      "partnerErpCode":"1239495",
      "role":"manufacturer",
      "name":"teste3"
    },
    {
      "nif":"11222333000181",
      "companyId":105,
      "partnerErpCode":"1239497",
      "role":"customsbroker",
      "name":"teste4"
    }
  ]
}

Field structure is identical to the POST request — see Create a Purchase Order above.

Response

{
  "corporationDivision": 126,
  "id": 1111111,
  "number": "xpto",
  "issueDate": "2025-05-20T18:49:41.382Z",
  "thirdParties": [
    {
      "id": 1883,
      "name": "100018 - Centro 1",
      "nif": "33567794000129",
      "role": "importer",
      "importerId": 126
    },
    {
      "id": 365484,
      "name": "300013 - Demo Exporter",
      "nif": "005262781910",
      "role": "exporter",
      "importerId": 126
    }
  ],
  "items": [
    {
      "quantity": 22,
      "quantityMeasurementUnit": "KG",
      "value": 21.000,
      "ncm": "43434233",
      "weight": 12,
      "weightMeasurementUnit": "KG",
      "partNumber": "12121",
      "currency": "BRL",
      "description": "APARELHO WIRELESS RECEBEDOR PARA CADEIRAS DE CINEMA COM BOTÃO MODELO MC250 501711, CONEXÃO 5PIN DIN PLUG, OPERA NA FREQUÊNCIA 2.4GHZ, VOLTAGEM DE 29V.",
      "positionErp": 10,
      "cancelled": false,
      "vendorNumber": "2",
      "shippingDate": "20240816",
      "update": false,
      "remove": false,
      "create": false,
      "notRemoved": true,
      "rabbitmqEvents": []
    }
  ],
  "status": "Waiting Approval",
  "sequencial": false,
  "transportMode": "Sea",
  "totalValue": 0,
  "totalNetWeight": 0.0000,
  "currency": "BRL",
  "incoterm": "CIF",
  "paymentTerms": "FREE OF CHARGE",
  "operation": "Import",
  "priority": "none",
  "hasNotificationEnabled": false,
  "rabbitmqEvents": [
    {
      "id": null,
      "producer": "documents",
      "payload": "{\"id\":1111111,\"number\":\"xpto\",\"issueDate\":1747766981382,...}",
      "event_date": "2025-05-20 19:49",
      "user_id": null,
      "corporation_id": 126,
      "routing_key": "documents.purchaseorder",
      "entity_id": 1111111,
      "entity_type": "purchaseorder",
      "entity_version": "1.0",
      "action": "update"
    }
  ]
}

HTTP Status Codes

Code	Description
200	OK
201	Created
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error

PUT Update Purchase Order Items

Updates purchase order items from the ERP.

Target URL: ${environment}/documents/purchaseorders/${id}/items/${id}

Rate Limits: 5 requests per second per token.

Required Headers

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

Request Body

{
  "positionErp":10,
  "partNumber":"12121",
  "vendorNumber":"2",
  "description":"APARELHO WIRELESS RECEBEDOR PARA CADEIRAS DE CINEMA COM BOTÃO MODELO MC250 501711, CONEXÃO 5PIN DIN PLUG, OPERA NA FREQUÊNCIA 2.4GHZ, VOLTAGEM DE 29V.",
  "ncm":"43434233",
  "currency":"BRL",
  "quantity":"22",
  "quantityMeasurementUnit":"KG",
  "value":"21.000",
  "weight":"12",
  "weightMeasurementUnit":"KG",
  "shippingDate":"20240816",
  "cancelled": false
}

Field Explanation

Field	Mandatory	Type	Description
positionErp	Yes	Int	Item position in the ERP system (e.g. 10).
partNumber	Yes	String(255)	Part number of the item (e.g. 12121).
vendorNumber	No	String(120)	Supplier ID for the item (e.g. 2).
description	Yes	String(200)	Detailed item description (e.g. Wireless receiver for cinema seats, Model MC250).
ncm	Yes	String(8)	Fiscal classification of the item according to NCM (e.g. 43434233).
currency	Yes	String(3)	Item currency (e.g. BRL).
quantity	Yes	Numeric	Quantity of included items in the order (e.g. 22.0).
quantityMeasurementUnit	Yes	String(10)	Measurement unit for the quantity (e.g. KG).
value	Yes	Numeric	Unit value of the item (e.g. 21.0).
weight	Yes	Numeric	Weight of the item (e.g. 12.0).
weightMeasurementUnit	Yes	String	Unit of measure for weight (e.g. KG, LB).
shippingDate	Yes	Date	Shipping date of the item, format YYYYMMDD (e.g. 20240816).
cancelled	Yes	Boolean	If true, the item is cancelled; if false, the item is active.

Response

{
  "id": 58688029,
  "quantity": 22,
  "quantityMeasurementUnit": "KG",
  "value": 21.000,
  "ncm": "43434233",
  "weight": 12,
  "weightMeasurementUnit": "KG",
  "partNumber": "12121",
  "currency": "BRL",
  "description": "APARELHO WIRELESS RECEBEDOR PARA CADEIRAS DE CINEMA COM BOTÃO MODELO MC250 501711, CONEXÃO 5PIN DIN PLUG, OPERA NA FREQUÊNCIA 2.4GHZ, VOLTAGEM DE 29V.",
  "positionErp": 10,
  "cancelled": true,
  "vendorNumber": "2",
  "shippingDate": "20240816",
  "update": false,
  "remove": false,
  "create": false,
  "notRemoved": true,
  "rabbitmqEvents": []
}

DELETE Delete a Purchase Order

Deletes purchase orders from ERP.

Target URL: ${environment}/documents/purchaseorders/${id}

Rate Limits: 5 requests per second per token.

Required Headers

Name	Description
Authorization	Bearer Token for authentication. or Apikey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-Type	Request content type (application/json).

Request

curl --location --request DELETE '${environment}/documents/purchaseorders/${id}' \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json'
    or
    --header 'Authorization: Apikey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
    --header 'Content-Type: application/json'

Path Parameters

Field	Description
environment	Base URL for the target environment.
id	ID of the purchase order within the Kestraa platform.

HTTP Status Codes

Code	Description
200	OK
201	Created
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error