> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Create an attachment > Registers a file and returns the URL to upload its bytes to. Uploading a file takes two requests: 1. Call this endpoint with the file's `name`, `contentType`, `sizeBytes` and `checksumSha256` — the SHA-256 digest of the file's bytes, base64-encoded (44 characters). It answers `201` with the new attachment, in `PENDING_UPLOAD`, and an `uploadUrl`. 2. Send the file's bytes to `uploadUrl` with a `PUT`, within 25 minutes. Send exactly the `Content-Type` you declared and an `x-amz-checksum-sha256` header holding the `checksumSha256` you declared, with a body of exactly `sizeBytes` bytes and no `Authorization` header. An upload whose type, size or content differs is rejected. Once the upload lands, the attachment becomes `AVAILABLE`, usually within seconds — read it again to know when; until then a download answers `409 ATTACHMENT_NOT_AVAILABLE`. The summary, the preview image and the fiscal data are then filled in on their own: follow `ai.status`, `thumbnail.status` and `fiscal.status`. Files can be up to 25 MiB of any type. The automatic analysis covers PDFs, JPEG and PNG images and XML documents, up to 3.7 MB for an image and 4 MB for a PDF or XML; the preview covers JPEG, PNG, GIF, BMP and TIFF images and the first page of a PDF. An uploaded file can't be replaced — create a new attachment for a new version. ## OpenAPI ````yaml /api-reference/attachment.openapi.json post /realms/{realmId}/organizations/{organizationId}/attachments openapi: 3.0.3 info: title: Attachment version: 1.0.0 description: >- Portão 3 attachment API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Shared file store: upload a file once, keep its ID, and read back its preview, an automatic summary and, for a nota fiscal or invoice, its fiscal data. Confidence tiers: generated:typed=9 copied:manual=0 unknown=0. servers: - url: https://api.attachment.v2.portao3.com.br/ description: production - url: https://api.attachment.dev.3pers.com.br/ description: development security: [] tags: - name: Attachments paths: /realms/{realmId}/organizations/{organizationId}/attachments: post: tags: - Attachments summary: Create an attachment description: Registers a file and returns the URL to upload its bytes to. operationId: postRealmsByRealmIdOrganizationsByOrganizationIdAttachments parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of the organization the file belongs to. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Name of the file, returned as sent. example: cupom-fiscal-posto.jpg contentType: type: string minLength: 1 maxLength: 255 description: >- Media type of the file. The upload must send exactly this value as its `Content-Type` header. example: image/jpeg checksumSha256: type: string minLength: 44 maxLength: 44 pattern: ^[A-Za-z0-9+/]{43}=$ description: >- SHA-256 digest of the file's bytes, base64-encoded (44 characters). The upload must send exactly this value as its `x-amz-checksum-sha256` header. example: mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs= sizeBytes: type: integer minimum: 1 maximum: 26214400 description: >- Size of the file in bytes, up to 25 MiB (26,214,400 bytes). The upload must be exactly this long. example: 2457600 required: - name - contentType - checksumSha256 - sizeBytes responses: '201': description: Successful response content: application/json: schema: type: object properties: id: type: string description: >- ID of the new attachment. Store it wherever the file is used. example: 3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60 format: uuid realmId: type: string description: ID of the realm the attachment belongs to. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organizationId: type: string description: ID of the organization the attachment belongs to. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid status: type: string enum: - PENDING_UPLOAD - AVAILABLE - DELETED description: >- `PENDING_UPLOAD` until the file is uploaded to `uploadUrl`. example: PENDING_UPLOAD name: type: string description: Name of the file, as sent. example: cupom-fiscal-posto.jpg contentType: type: string description: >- Media type of the file, as declared. The upload must send it as `Content-Type`. example: image/jpeg sizeBytes: type: number description: >- Size of the file in bytes, as declared. The upload must be exactly this long. example: 2457600 ai: type: object properties: status: type: string enum: - PENDING - PROCESSING - DONE - FAILED - SKIPPED description: >- Progress of the automatic content analysis (a short summary plus extracted facts, in pt-BR). `PENDING` and `PROCESSING` are transient — analysis runs asynchronously after upload — settling on `DONE`, `SKIPPED` (the file type is not analysable) or `FAILED`. example: PENDING required: - status description: >- The content analysis, which starts once the file is uploaded. thumbnail: type: object properties: status: type: string enum: - PENDING - PROCESSING - DONE - FAILED - SKIPPED description: >- Progress of the attachment's preview image. `PENDING` and `PROCESSING` are transient — a preview is generated asynchronously shortly after upload, so a freshly created attachment reports one of them until it settles on `DONE`, `SKIPPED` (the file is not an image we can render) or `FAILED`. example: PENDING required: - status description: The preview image, generated once the file is uploaded. fiscal: type: object properties: status: type: string enum: - PENDING - PROCESSING - DONE - FAILED - SKIPPED description: >- Progress of the attachment's fiscal-data extraction. `PENDING` and `PROCESSING` are transient — a fiscal document's structured data is read asynchronously shortly after upload, so a freshly created attachment reports one of them until it settles on `DONE` (`extractedReceipt` is populated), `SKIPPED` (the file is not a fiscal document, or nothing could be read from it) or `FAILED`. example: PENDING required: - status description: >- The fiscal-data extraction, which starts once the file is uploaded. contents: type: array items: type: string description: >- Facts read from the file — empty until the analysis has run. --- Example: `[]` example: [] createdBy: type: string description: ID of the user (or API client) who created the attachment. example: e3553bc1-5e20-4e17-b22a-a796fda0aa99 createdAt: type: string description: When the attachment was created. example: '2026-10-15T14:31:05.000Z' format: date-time updatedAt: type: string description: When the attachment last changed. example: '2026-10-15T14:31:05.000Z' format: date-time uploadUrl: type: string description: >- Pre-signed URL to `PUT` the file's bytes to, valid for 25 minutes. Send exactly the declared `Content-Type`, an `x-amz-checksum-sha256` header with the declared `checksumSha256`, and a body of exactly `sizeBytes` bytes — and no `Authorization` header. (The example is shortened.) example: >- https://files.example.com/3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60.jpg?signature=… required: - id - realmId - organizationId - status - name - contentType - ai - thumbnail - fiscal - createdBy - uploadUrl description: >- A just-created attachment, waiting for its file. It carries only what exists at creation time: no analysis has run yet, so `summary`, `image` and `extractedReceipt` are absent and each status block is `PENDING`. '403': description: >- `ATTACHMENT_MEMBERSHIP_REQUIRED` — You are not a member of the organization. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - ATTACHMENT_MEMBERSHIP_REQUIRED description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - ATTACHMENT description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: ATTACHMENT_MEMBERSHIP_REQUIRED origin: ATTACHMENT message: Organization membership required '422': description: >- `BAD_REQUEST` — A path parameter is not a valid ID or the body failed validation; `fields` lists each offending field. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BAD_REQUEST description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - ATTACHMENT description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BAD_REQUEST origin: ATTACHMENT message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: name message: 'Invalid input: expected string, received undefined' code: NAME_REQUIRED ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.