> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Record an externally-observed fact about an assignment set > Records a fact the operator confirms and moves the set accordingly. offer_sent confirms the authorized offer file was delivered to the fund's administrator, and requires an authorized file to exist. paid, transferred and accepted are per-receivable and follow one another in that order over a set whose endorsement term is already signed; each names where it came from, and each applies either to named receivables or to the whole surviving composition. accepted is the flip: the contract leaves this portfolio and its write-off is enqueued in the SAME transaction, or neither happens. A repeated confirmation is inert and reported as replayed rather than recording a second send or a second write-off. Re-stating paid is also the way to re-issue a title transfer the registradora refused: the fact writes nothing the second time, while the registry command is reached again through its own deterministic reference. Only a transferred fact whose provenance is registry_provider settles that command — the acceptance's proof of a moved title is the registradora's own statement and nobody else's. ## OpenAPI ````yaml /pt/openapi/v3-current/lender.yaml post /api/v1/assignment/sets/{setId}/facts openapi: 3.1.0 info: contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio description: >- Code-first OpenAPI 3.1 surface for the Lender service. Routes that move money are at-most-once per X-Idempotency: when one answers 5xx, the X-Idempotency-Fenced response header says whether that key is now refusing resends (true) or free to retry (false or absent). See docs/contracts/money-route-idempotency.md. license: name: Lerian Studio General License title: Lender API version: 1.0.0 servers: - url: https://lender.sandbox.lerian.net security: - BearerAuth: [] tags: - description: >- Caller session projection: validated subject and effective permissions for the presented token. name: Session - description: >- Ledger accounting operations: journal entries and accrual postings for loan accounts. name: Accounting - description: >- Loan application intake and lifecycle: submission, decisioning, and status. name: LoanApplications - description: >- Loan product catalog: definition, versioning, and activation of lending products. name: LoanProducts - description: >- Loan account servicing operations: balances, schedules, and account-level actions. name: Loan Accounts - description: >- Portfolio dashboard read operations: aggregated portfolio and performance views. name: Dashboard - description: >- Jurisdiction registry: supported jurisdiction profiles and their capabilities. name: Jurisdictions - description: >- Jurisdiction-specific loan application operations (Brazil origination surface). name: Loan Applications - description: >- Tax computation operations for jurisdiction-specific lending (e.g. Brazil IOF). name: Tax - description: >- Brazil consignado privado operations: contract lifecycle, exclusion repair, and compensating adjustments. name: Consignado - description: >- Credit-instrument document template registry: versioned drafting and publication of CCB clausulado. name: DocumentTemplates paths: /api/v1/assignment/sets/{setId}/facts: post: tags: - AssignmentSets summary: Record an externally-observed fact about an assignment set description: >- Records a fact the operator confirms and moves the set accordingly. offer_sent confirms the authorized offer file was delivered to the fund's administrator, and requires an authorized file to exist. paid, transferred and accepted are per-receivable and follow one another in that order over a set whose endorsement term is already signed; each names where it came from, and each applies either to named receivables or to the whole surviving composition. accepted is the flip: the contract leaves this portfolio and its write-off is enqueued in the SAME transaction, or neither happens. A repeated confirmation is inert and reported as replayed rather than recording a second send or a second write-off. Re-stating paid is also the way to re-issue a title transfer the registradora refused: the fact writes nothing the second time, while the registry command is reached again through its own deterministic reference. Only a transferred fact whose provenance is registry_provider settles that command — the acceptance's proof of a moved title is the registradora's own statement and nobody else's. operationId: recordAssignmentSetFact parameters: - description: Assignment set identifier. in: path name: setId required: true schema: description: Assignment set identifier. format: uuid type: string - description: >- Canonical idempotency request ID. Required: this request moves money, and without a key a retry cannot be told apart from a second instruction. in: header name: X-Idempotency required: true schema: description: >- Canonical idempotency request ID. Required: this request moves money, and without a key a retry cannot be told apart from a second instruction. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RecordAssignmentSetFactHumaInputBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AssignmentSetFactHumaBody' description: OK '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unauthorized '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Forbidden '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Service Unavailable default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: RecordAssignmentSetFactHumaInputBody: additionalProperties: false properties: acceptance: $ref: '#/components/schemas/AssignmentAcceptanceHumaBody' description: >- The administrator's acceptance document, in the pinned shape. Required when factType is accepted and provenance is administrator_file. factType: description: >- The externally-observed fact being confirmed. offer_sent is the operator confirming the authorized offer file was delivered to the fund's administrator, and requires an authorized file to exist. paid, transferred and accepted are per-receivable progress facts and follow one another in that order; accepted is the administrator accepting the title transfer, which takes the receivable out of this portfolio and writes it off. term_signed is NOT here: it is derived from the signed endorsement instrument itself. enum: - offer_sent - paid - transferred - accepted type: string provenance: description: >- Where the fact came from. REQUIRED for paid, transferred and accepted; ignored for offer_sent, which is by construction an operator's own confirmation about a file we generated. On a transferred fact it also decides whether the registradora's title-transfer command is settled: only registry_provider does that, because the acceptance guard treats a settled command as proof the title moved, and a desk's or an administrator's own statement is not the registradora's acatamento. Where the fund reaches no registradora the guard does not apply at all. enum: - administrator_file - registry_provider - operator type: string receivableRefs: description: >- Narrows a per-receivable fact to exactly these receivables. Omit it to mean the WHOLE surviving composition — the honest reading of an administrator stating that a portfolio was paid. A reference the set does not carry, or carries as cut or removed, is refused. It must be EMPTY when an acceptance document is present: the document already names what was accepted, and two lists are two answers. items: type: string maxItems: 5000 type: - array - 'null' required: - factType type: object AssignmentSetFactHumaBody: additionalProperties: false properties: assignmentSetId: description: The set the fact was recorded against. type: string derecognizedRefs: description: >- The receivables this call wrote off the balance sheet: contracts that left this portfolio with their write-off enqueued in the same transaction. items: type: string type: - array - 'null' factType: description: The fact that was confirmed. type: string fromState: description: The lifecycle state the set was in. type: string provenance: description: Where the fact came from, echoed back for the audit trail. type: string recordedBy: description: Validated actor identity that confirmed the fact. type: string recordedRefs: description: >- The receivables this call actually recorded the fact for, excluding the ones that already carried it. items: type: string type: - array - 'null' replayed: description: >- True when nothing was written: the set was already in the resulting state, or every receivable named already carried the fact. A repeated confirmation never records a second send and never enqueues a second write-off. type: boolean toState: description: >- The lifecycle state the fact moved it to. It advances only once EVERY surviving receivable carries the fact. type: string required: - assignmentSetId - factType - fromState - toState - recordedBy - replayed type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object AssignmentAcceptanceHumaBody: additionalProperties: false properties: acceptedAt: description: >- When the administrator says the acceptance happened (RFC3339). It is EVIDENCE, not the lifecycle clock: the fact's own instant stays the moment the confirmation reached us, so nothing a counterparty sends can backdate a write-off. format: date-time type: string acceptedBy: description: >- The ADMINISTRATOR's own identity for whoever accepted. It never substitutes for our validated actor, which is recorded beside it. maxLength: 256 type: string assignmentSetId: description: The set the administrator accepted. Must match the set on the route. format: uuid type: string receivableRefs: description: >- The receivables the administrator accepted. An acatamento always names them: 'the whole set' is a convenience our own operators may use, never a claim inferred on an administrator's behalf. items: type: string maxItems: 5000 minItems: 1 type: - array - 'null' transferReference: description: >- The ADMINISTRATOR's own reference for this acatamento — its batch protocol, its file id, whatever it can be quoted back by. One reference for the whole document under both regimes: an administrator does not move titles at a registradora and has no per-title protocol to give. Where a registradora governs, each receivable's fact row also carries OUR confirmed per-title protocol beside this one. maxLength: 256 type: string required: - assignmentSetId - receivableRefs - acceptedBy - acceptedAt - transferReference type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ````