Create an attachment

curl --request POST \
  --url https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "cupom-fiscal-posto.jpg",
  "contentType": "image/jpeg",
  "checksumSha256": "mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=",
  "sizeBytes": 2457600
}
'

import requests

url = "https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments"

payload = {
    "name": "cupom-fiscal-posto.jpg",
    "contentType": "image/jpeg",
    "checksumSha256": "mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=",
    "sizeBytes": 2457600
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'cupom-fiscal-posto.jpg',
    contentType: 'image/jpeg',
    checksumSha256: 'mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=',
    sizeBytes: 2457600
  })
};

fetch('https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'cupom-fiscal-posto.jpg',
    'contentType' => 'image/jpeg',
    'checksumSha256' => 'mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=',
    'sizeBytes' => 2457600
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments"

	payload := strings.NewReader("{\n  \"name\": \"cupom-fiscal-posto.jpg\",\n  \"contentType\": \"image/jpeg\",\n  \"checksumSha256\": \"mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=\",\n  \"sizeBytes\": 2457600\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"cupom-fiscal-posto.jpg\",\n  \"contentType\": \"image/jpeg\",\n  \"checksumSha256\": \"mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=\",\n  \"sizeBytes\": 2457600\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"cupom-fiscal-posto.jpg\",\n  \"contentType\": \"image/jpeg\",\n  \"checksumSha256\": \"mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=\",\n  \"sizeBytes\": 2457600\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60",
  "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
  "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
  "status": "PENDING_UPLOAD",
  "name": "cupom-fiscal-posto.jpg",
  "contentType": "image/jpeg",
  "ai": {
    "status": "PENDING"
  },
  "thumbnail": {
    "status": "PENDING"
  },
  "fiscal": {
    "status": "PENDING"
  },
  "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
  "uploadUrl": "https://files.example.com/3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60.jpg?signature=…",
  "sizeBytes": 2457600,
  "contents": [],
  "createdAt": "2026-10-15T14:31:05.000Z",
  "updatedAt": "2026-10-15T14:31:05.000Z"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "ATTACHMENT_MEMBERSHIP_REQUIRED",
  "origin": "ATTACHMENT",
  "message": "Organization membership required"
}

{
  "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"
    }
  ]
}

POST

realms

{realmId}

organizations

{organizationId}

attachments

Create an attachment

curl --request POST \
  --url https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "cupom-fiscal-posto.jpg",
  "contentType": "image/jpeg",
  "checksumSha256": "mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=",
  "sizeBytes": 2457600
}
'

import requests

url = "https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments"

payload = {
    "name": "cupom-fiscal-posto.jpg",
    "contentType": "image/jpeg",
    "checksumSha256": "mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=",
    "sizeBytes": 2457600
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'cupom-fiscal-posto.jpg',
    contentType: 'image/jpeg',
    checksumSha256: 'mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=',
    sizeBytes: 2457600
  })
};

fetch('https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'cupom-fiscal-posto.jpg',
    'contentType' => 'image/jpeg',
    'checksumSha256' => 'mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=',
    'sizeBytes' => 2457600
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments"

	payload := strings.NewReader("{\n  \"name\": \"cupom-fiscal-posto.jpg\",\n  \"contentType\": \"image/jpeg\",\n  \"checksumSha256\": \"mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=\",\n  \"sizeBytes\": 2457600\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"cupom-fiscal-posto.jpg\",\n  \"contentType\": \"image/jpeg\",\n  \"checksumSha256\": \"mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=\",\n  \"sizeBytes\": 2457600\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.attachment.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/attachments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"cupom-fiscal-posto.jpg\",\n  \"contentType\": \"image/jpeg\",\n  \"checksumSha256\": \"mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs=\",\n  \"sizeBytes\": 2457600\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60",
  "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
  "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
  "status": "PENDING_UPLOAD",
  "name": "cupom-fiscal-posto.jpg",
  "contentType": "image/jpeg",
  "ai": {
    "status": "PENDING"
  },
  "thumbnail": {
    "status": "PENDING"
  },
  "fiscal": {
    "status": "PENDING"
  },
  "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
  "uploadUrl": "https://files.example.com/3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60.jpg?signature=…",
  "sizeBytes": 2457600,
  "contents": [],
  "createdAt": "2026-10-15T14:31:05.000Z",
  "updatedAt": "2026-10-15T14:31:05.000Z"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "ATTACHMENT_MEMBERSHIP_REQUIRED",
  "origin": "ATTACHMENT",
  "message": "Organization membership required"
}

{
  "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"
    }
  ]
}

Uploading a file takes two requests:

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.
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.

Path Parameters

realmId

string<uuid>

required

ID of your realm.

Format: UUID

organizationId

string<uuid>

required

ID of the organization the file belongs to.

Format: UUID

Body

application/json

name

string

required

Name of the file, returned as sent.

Required string length: 1 - 255

Example:

"cupom-fiscal-posto.jpg"

contentType

string

required

Media type of the file. The upload must send exactly this value as its Content-Type header.

Required string length: 1 - 255

Example:

"image/jpeg"

checksumSha256

string

required

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.

Required string length: 44

Pattern: ^[A-Za-z0-9+/]{43}=$

Example:

"mAvD2GDNsz9cDoFtpN+2TKBKtAMo+ZngJoUAsEf7eWs="

sizeBytes

integer

required

Size of the file in bytes, up to 25 MiB (26,214,400 bytes). The upload must be exactly this long.

Required range: 1 <= x <= 26214400

Example:

2457600

Response

Successful response

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.

string<uuid>

required

ID of the new attachment. Store it wherever the file is used.

Example:

"3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e4c60"

realmId

string<uuid>

required

ID of the realm the attachment belongs to.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organizationId

string<uuid>

required

ID of the organization the attachment belongs to.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

status

enum<string>

required

PENDING_UPLOAD until the file is uploaded to uploadUrl.

Available options:

PENDING_UPLOAD,

AVAILABLE,

DELETED

Example:

"PENDING_UPLOAD"

name

string

required

Name of the file, as sent.

Example:

"cupom-fiscal-posto.jpg"

contentType

string

required

Media type of the file, as declared. The upload must send it as Content-Type.

Example:

"image/jpeg"

object

required

The content analysis, which starts once the file is uploaded.

Show child attributes

thumbnail

object

required

The preview image, generated once the file is uploaded.

Show child attributes

fiscal

object

required

The fiscal-data extraction, which starts once the file is uploaded.

Show child attributes

createdBy

string

required

ID of the user (or API client) who created the attachment.

Example:

"e3553bc1-5e20-4e17-b22a-a796fda0aa99"

uploadUrl

string

required

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=…"

sizeBytes

number

Size of the file in bytes, as declared. The upload must be exactly this long.

Example:

2457600

contents

string[]

Facts read from the file — empty until the analysis has run.

Example: []

Example:

[]

createdAt

string<date-time>

When the attachment was created.

Example:

"2026-10-15T14:31:05.000Z"

updatedAt

string<date-time>

When the attachment last changed.

Example:

"2026-10-15T14:31:05.000Z"

Overview

Identity

Banking

Billing

Accounting

Registry

Platform

Notification

Rule Engine

Scheduling

Travel

Vehicles

Attachments

Create an attachment

Path Parameters

Body

Response