Route settlements

Route settlements are an operational grouping of receivables registered by an associate during a workday, identified by a route code. They apply to customers whose operating model includes drivers or distributors who visit clients during a single shift and need to settle what they collected at the end of the day.

When to use this resource

If your customer has no fleet or does not use the route-sheet concept, you can ignore this section. Route settlements apply to models B and C on the associates' side.

Model

{
  "id": 5001,
  "routeCode": "AA-2026-05-15-042",
  "date": "2026-05-15",
  "associateId": 88,
  "receivableAccountIds": [4242, 4243, 4250],
  "summary": {
    "receivablesCount": 12,
    "totalAmount": 425000.00,
    "byReceivableType": [
      { "type": "INVOICE",     "count": 10, "amount": 450000.00 },
      { "type": "RETURN_PRODUCT", "count": 1, "amount": -15000.00 },
      { "type": "RETENTION",   "count": 1, "amount": -10000.00 }
    ]
  },
  "creationDate": "2026-05-15T18:30:00-03:00"
}

Field	Description
routeCode	Route code. Unique per date and customer
date	Date of the route settlement
associateId	Associate who settled
receivableAccountIds	Receivable accounts touched during the shift
summary.receivablesCount	Number of receivables registered during the shift
summary.totalAmount	Net sum (positives add, negatives subtract)
summary.byReceivableType	Breakdown by receivable type

Endpoints

Method	Path	Description
GET	/v1/route-settlements	List with filters
POST	/v1/route-settlements	Create or update a route settlement
GET	/v1/route-settlements/{routeCode}	Detail by code
GET	/v1/route-settlements/{routeCode}/receivables	Receivables for the route settlement
GET	/v1/associates/{id}/route-settlements	Route settlements for an associate

Create or update

POST /v1/route-settlements
Idempotency-Key: erp-route-AA-2026-05-15-042
Content-Type: application/json

{
  "routeCode": "AA-2026-05-15-042",
  "date": "2026-05-15",
  "associateId": 88
}

Field	Type	Required	Description
routeCode	string	Yes	Unique per date and customer
date	YYYY-MM-DD	Yes	Date of the shift
associateId	int64	Yes	Responsible associate

Once created, any receivables that the associate registers during the day with externalRoutingCode = "AA-2026-05-15-042" are automatically grouped under this route settlement.

Validations

Validation	Error
routeCode already exists for a different date	422 route-code-already-used
Disabled associate	422 associate-disabled
Same (routeCode, date) with a different associateId	409 route-code-already-used

Filters

GET /v1/route-settlements

Parameter	Type	Description
associateId	int64	Route settlements for an associate
routeCode	string	Search by code
fromDate, toDate	YYYY-MM-DD	Date range
page, count	int	Pagination

List receivables for a route settlement

GET /v1/route-settlements/AA-2026-05-15-042/receivables

Returns the list of receivables (not settlement items, but the receivables registered during that shift). Each one includes its status, amount, client, etc. This is the main input for the driver's daily reconciliation.