Support documents

Support documents are the files that back a pre-appointment's charges — the same evidence a payer will later require to honour the billing (medical orders, TISS guides, ID documents, and so on). Collecting them before care is the whole point of pre-attendance.

Placeholders and completion

When required supports are configured for a charge's provider_product_code, the pre-appointment is seeded with PENDING document placeholders — one per required support_file_code. A placeholder is a "slot" that says "this charge still needs this document".

Uploading a file completes the matching placeholder(s):

POST /v1/checkin/appointments/{id}/documents
Content-Type: multipart/form-data

The request has two parts:

Part	Content-Type	What
file	binary (PDF, JPEG or PNG)	The document itself. Max 25 MB.
request_data	application/json	The metadata: support_file_code and provider_product_codes.

// request_data part — application/json
{
  "support_file_code": "CPF",
  "provider_product_codes": ["PROC001", "PROC002"]
}

How provider_product_codes selects which placeholders get completed:

• Empty or absent → completes the PENDING placeholders of all charges of the pre-appointment for that support_file_code (case-insensitive).
• Non-empty → restricts completion to the matching charges. Codes with no corresponding charge are silently ignored.

The file is uploaded to storage once and shared across every placeholder it completes — one upload can satisfy the same required document across several charges. The response is a 201 with one array element per completed document.

MIME type is enforced by content, not extension

The whitelist (application/pdf, image/jpeg, image/png) is checked by inspecting the file's magic bytes, not by trusting the filename. A .pdf that isn't really a PDF is rejected with 422.

Source: MANUAL vs HIS_INBOUND

Every document has a source, and it determines what you can do with it:

Source	Origin	Deletable?	Clearable?
MANUAL	Uploaded through the documents endpoint	✅ Yes	✅ Yes
HIS_INBOUND	Arrived with the appointment from the HIS	❌ No (403)	❌ No (403)

Documents that came from the HIS are treated as already received and are immutable here — the HIS is their system of record. Only manually uploaded documents can be deleted (soft-delete) or cleared back to PENDING.

• Delete (DELETE .../documents/{documentId}) marks the record disabled. The file is not removed from storage (it may be shared with other placeholders completed by the same upload).
• Clear (POST .../documents/{documentId}/clear) reverts a MANUAL document to PENDING, wiping the file fields (name, extension, path, size, MIME, AI-validation) while keeping support_file_code, required, the charge link, and source = MANUAL. Also does not touch storage.

AI / DVS validation

Uploaded documents are validated by AI/DVS using the same rules as the RCM account-assembly flow. Each document carries an AI validation status:

ai_validation_status	Meaning
PENDING	Not yet validated.
APPROVED	Passed the applicable rules.
REJECTED	Failed one or more rules.
NOT_APPLICABLE	No validation rules apply to this document.
ERROR	The validation itself failed to run (not a verdict on the document). Retry the upload or contact support.

The no-hard-block rule

This is the rule that shapes the whole flow:

Missing or rejected documents never block check-in

A missing mandatory document or an AI-REJECTED one produces a warning and a recorded pendencia — never a block. The reception user can always confirm the pre-appointment and let the patient through, with no justification or approval. Pendencias are visible downstream to the billing team (faturamento), who resolve them as part of the normal billing cycle.

The API's job is to surface what's missing so the user can act on it while the patient is present — not to gate care.

Listing

GET /v1/checkin/appointments/{id}/documents returns all enabled documents (including PENDING placeholders without a file), each with a presigned download URL (null for empty placeholders) and the associated charge info. Documents that share a stored file share one presigned URL.

Endpoints

Operation	Endpoint
Upload	POST /v1/checkin/appointments/{id}/documents
List	GET /v1/checkin/appointments/{id}/documents
Delete (soft)	DELETE /v1/checkin/appointments/{id}/documents/{documentId}
Clear to PENDING	POST /v1/checkin/appointments/{id}/documents/{documentId}/clear

Common pitfalls

• Uploading a file larger than 25 MB → 413 Payload Too Large.
• A support_file_code / provider_product_codes combination that matches no PENDING placeholder → 422. Check the configured supports for the charge.
• Trying to delete or clear a HIS document → 403. Only MANUAL documents are mutable.
• Assuming the download URL is permanent — presigned URLs expire. Re-list to get a fresh one.