发送文件

发送文件进行标准分析

要开始文件分析，请使用 multipart/form-data 格式向 /document 端点发送 POST 请求。

端点：https://api.caas.qitech.app/document_analysis/document

请求格式

请求必须以 multipart/form-data 格式发送，包含数据字段和文件字段。分析所需的必填字段为 id、document_analysis_type、document_bytes。

请求示例：

curl -X POST "https://api.caas.qitech.app/document_analysis/document" \
-H "Authorization: SUA_CHAVE_API" \
-H "Content-Type: multipart/form-data" \
-F "id=solicitacao-abc-12345" \
-F "document_analysis_type=proof_of_address_default" \
-F "document_bytes=@/caminho/para/seu/comprovante.pdf"

发送属性说明

属性	描述
id（必填）	由您提供的请求唯一标识符。此 ID 可在以后用于检索分析结果。
document_analysis_type（必填）	一个字符串，指定要对文档执行的分析类型。支持的类型请参见下表。
document_bytes（必填）	待分析的文档文件。必须作为 multipart 请求体中的文件发送。注意：请勿将此字段作为 base64 编码字符串发送。
async（可选，默认=false）	一个布尔值（true 或 false），定义处理模式。 - false（同步）：API 将尝试处理文档并在同一请求中返回结果。 - true（异步）：API 将确认接收并在后台处理。结果将通过 webhook 发送到预先配置的 URL（更多信息请参见关于 webhooks 的部分）。

注意

async 字段应用于指示异步请求。同步请求应仅用于小型文档和需要立即响应的快速分析。如果分析未在同步请求的时间限制内完成，返回状态为 202 Accepted，并且必须通过下述的 GET 请求获取结果。在这种情况下不会发送 webhook：webhook 仅用于异步分析。

支持的分析类型

document_analysis_type 字段确定将应用于您文档的数据提取模型。以下是目前支持的类型。

分析类型	文档类型	描述
`proof_of_address_default`	居住证明（水电费、燃气费、网络费账单、政府信函、声明）	提取并验证姓名、结构化地址、原始地址、签发日期和文档类型。
`company_statute_default`	公司章程或合同	基本提取和验证：公司数据、股本、登记机构和股东结构。
`company_statute_credit_right_assignment`	公司章程或合同	高级提取，包括验证信贷权转让的签署权限：签署人组、财务限额以及是否需要人工审核。
`power_of_attorney_default`	授权委托书	提取授权人、被授权人、授予的权限、范围、有效期、不可撤销性和公证信息。
`invoice_default`	发票和 DANFEs	提取开票方、承包方、发票类型和税收、编号、日期、项目和金额。
`bankslip_default`	银行付款单	提取受益人、受益人 CNPJ、条形码、金额和到期日。
`ccb_default`	银行信用凭证（CCB）	提取合同编号、发行人数据、担保、融资金额、利率、分期和到期日。
`portability_retention_evidence_analysis`	携号转网保留证据	验证证据：合同编号、发行人证件和电话、携转编号、是否有签名以及是否为有效确认。

展开下方的每个类型，查看分析在 analysis_result 中返回的字段，以及每个字段的类型和含义。嵌套字段以完整路径显示（address.street），列表以 [] 标记。

proof_of_address_default — 在 analysis_result 中返回的字段

字段	类型	说明
`name`	`string`	持有人全名，按文档中提取的内容
`address`	`object`	结构化的居住地址。未找到的信息返回为空字符串
`address.street`	`string`	街道名称
`address.number`	`string`	门牌号
`address.complement`	`string`	补充信息，如公寓、房间或楼层（如有）
`address.neighborhood`	`string`	街区
`address.city`	`string`	城市
`address.state`	`string`	州或联邦区
`address.cep`	`string`	邮政编码（CEP）
`raw_address`	`string`	完整的居住地址，纯文本形式
`issue_date`	`string`	文档签发日期，格式为 YYYY-MM-DD
`document_type`	enum: `utility_bill`, `bank_statement`, `address_declaration`, `rental_agreement`, `government_letter` …	所发送的文档类型（例如 'utility_bill'、'address_declaration'）

company_statute_default — 在 analysis_result 中返回的字段

字段	类型	说明
`company_name_official`	`string`	公司完整法定名称
`company_name_trade`	`string`	商号名称
`cnpj`	`string`	CNPJ，格式为 XX.XXX.XXX/XXXX-XX
`nire`	`string`	NIRE —— 企业登记识别号
`headquarters_address_full`	`string`	总部完整地址
`incorporation_date`	`string`	公司成立日期
`last_consolidated_amendment_date`	`string`	最近一次合并修订的日期
`corporate_purpose_summary`	`string`	主要经营范围
`share_capital_value`	`number`	股本总额
`share_capital_currency`	`string`	股本币种（例如 'BRL'）
`registration_office_name`	`string`	登记机构名称（例如 JUCESP）
`registration_office_number`	`string`	在主管机构的登记号
`registration_office_date`	`string`	在主管机构登记或备案的日期
`requires_power_of_attorney_check`	`boolean`	当签署权限不明确或提及授权委托书时为真，表示需要核查另一份文档
`partners_data[]`	`object`	从公司章程中提取的单个股东数据
`partners_data[].name`	`string`	股东全名
`partners_data[].cpf`	`string`	股东 CPF，格式为 XXX.XXX.XXX-XX
`partners_data[].is_administrator`	`boolean`	当股东被明确任命为管理人时为真
`partners_data[].role_powers`	`string`	职位或权限，仅当股东为管理人时填写
`partners_data[].share_quantity`	`integer`	股东持有的股份或股权数量
`partners_data[].share_value`	`number`	股份或股权的总价值（BRL）
`partners_data[].participation_percentage`	`number`	股东在公司中的持股比例
`clauses_of_interest`	`object`	从文档中提取的相关条款
`clauses_of_interest.administration_clause_summary`	`string`	定义谁代表并代公司签署的条款摘要

company_statute_credit_right_assignment — 在 analysis_result 中返回的字段

字段	类型	说明
`requires_review`	`boolean`	表示文档是否复杂、是否包含大量关于管理的条款或子条款，或是否需要其他文档配合（如股东会或选举会议记录）。
`company_data`	`object`	被分析实体的完整登记与股权数据。
`company_data.company_name_official`	`string`	公司完整法定名称
`company_data.company_name_trade`	`string`	商号名称
`company_data.cnpj`	`string`	CNPJ（CNPJ/MF），格式为 XX.XXX.XXX/XXXX-XX
`company_data.nire`	`string`	企业登记识别号（NIRE）
`company_data.headquarters_address_full`	`string`	总部完整地址
`company_data.incorporation_date`	`string`	公司成立日期
`company_data.last_consolidated_amendment_date`	`string`	本公司章程或修订的日期
`company_data.corporate_purpose_summary`	`string`	主要经营范围
`company_data.share_capital_value`	`number`	股本总额
`company_data.share_capital_currency`	`string`	股本币种（例如 'BRL'）
`company_data.registration_office_name`	`string`	登记机构名称（例如 JUCESP）
`company_data.partners_data[]`	`object`	从公司章程中提取的单个股东数据。
`company_data.partners_data[].name`	`string`	股东全名
`company_data.partners_data[].cpf`	`string`	股东 CPF，格式为 XXX.XXX.XXX-XX
`company_data.partners_data[].cnpj`	`string`	股东公司的 CNPJ（当股东为法人时），格式为 XX.XXX.XXX/XXXX-XX
`company_data.partners_data[].is_representative`	`boolean`	当股东可以代表公司时为真。
`company_data.partners_data[].role_powers`	enum: `president`, `partner`, `administrator`, `director`, `manager` …	职位或权限。若指公司、组织或类似主体，请使用 'other'。
`company_data.partners_data[].share_quantity`	`integer`	股东持有的股份或股权数量
`company_data.partners_data[].share_value`	`number`	股份或股权的总价值
`company_data.partners_data[].participation_percentage`	`number`	股东在公司中的持股比例
`analyzed_operation`	`string`	所分析代表权对应的具体法律行为或交易。
`source_documents[]`	`string`	作为分析依据的公司文档清单（例如“公司章程”、“选举会议记录”）。
`allows_proxies`	`boolean`	表示该实体的章程是否允许通过受托人代表。
`signer_groups[]`	`object`	该实体有效的各签署组及签署规则。
`signer_groups[].group_id`	`integer`	签署组的唯一数字标识符。
`signer_groups[].description`	`string`	该组所代表业务规则的清晰摘要。
`signer_groups[].source_clause`	`string`	确立该规则的条款或条文的完整文本。
`signer_groups[].representation_type`	enum: `Conjunta`, `Individual`, `Conforme Mandato`	说明代表方式为共同还是单独。若两者均允许，请使用单独。
`signer_groups[].minimum_signers`	`integer`	该组必须签署的最少成员数。若为共同签署，该值必须大于 1
`signer_groups[].limitations`	`object`	适用于该签署规则的条件与限制。
`signer_groups[].limitations.financial_limit`	`object`	以结构化形式表示该规则的财务权限额度。
`signer_groups[].limitations.financial_limit.operator`	enum: `MENOR_IGUAL`, `MAIOR_QUE`, `MAIOR`, `MENOR`, `IGUAL` …	财务限额的比较运算符。
`signer_groups[].limitations.financial_limit.value`	`number`	权限额度的金额。
`signer_groups[].limitations.financial_limit.currency`	`string`	金额的币种代码（例如 BRL、USD）。
`signer_groups[].limitations.observations`	`string`	关于该规则解释或适用的补充说明。
`signer_groups[].members[]`	`object`	可组成签署组的职位。
`signer_groups[].members[].position`	enum: `president`, `partner`, `administrator`, `director`, `manager` …	职位或权限。若指公司、组织或类似主体，请使用 'other'。
`signer_groups[].members[].full_name`	`string`	担任该职位者的全名（若已识别）。
`signer_groups[].members[].cpf`	`string`	该个人的 CPF（若可获得）。
`signer_groups[].members[].mandate_end_date`	`string`	任期到期日（例如 'YYYY-MM-DD'）。
`signer_groups[].members[].is_qualified`	`boolean`	表示担任该职位者是否已在文档中识别。
`signer_groups[].members[].is_required`	`boolean`	表示该成员是否为必需。

power_of_attorney_default — 在 analysis_result 中返回的字段

字段	类型	说明
`grantors[]`	`object`	授权人清单 —— 至少需要一位
`grantors[].name`	`string`	授权人全名
`grantors[].cpf`	`string`	授权人 CPF，格式为 XXX.XXX.XXX-XX（自然人）
`grantors[].cnpj`	`string`	授权人 CNPJ，格式为 XX.XXX.XXX/XXXX-XX（法人）
`grantees[]`	`object`	被授权人清单 —— 至少需要一位
`grantees[].name`	`string`	被授权人全名
`grantees[].cpf`	`string`	被授权人 CPF，格式为 XXX.XXX.XXX-XX（自然人）
`grantees[].cnpj`	`string`	被授权人 CNPJ，格式为 XX.XXX.XXX/XXXX-XX（法人）
`powers_granted`	`string`	授权委托书所授予权限的说明
`power_scope`	`string`	所授予权限的范围或限制（若有说明）
`expiration_date`	`string`	权限到期日；为 null 表示无限期有效
`is_irrevocable`	`boolean`	当授权委托书被明确声明为不可撤销时为真
`revocation_clause`	`string`	撤销条款的文本（若存在）
`notary_name`	`string`	文档登记所在公证处的名称
`notary_registration_number`	`string`	公证处的登记号或簿册号
`notary_date`	`string`	公证认证日期
`document_date`	`string`	授权委托书的签署日期
`purpose`	`string`	授权委托书声明的用途（例如出庭代理、操作银行账户）

invoice_default — 在 analysis_result 中返回的字段

字段	类型	说明
`company_name`	`string`	公司法定名称
`cnpj`	`string`	公司 CNPJ
`invoice_type`	enum: `Documento fiscal eletrônico de serviços`, `Documento fiscal eletrônico de produto`	发票类型 —— 商品或服务
`taxation_type`	`string`	税收类型
`invoice_issue_date`	`string`	发票开具日期
`invoice_number`	`string`	发票编号
`contracting_company`	`string`	承包方公司
`invoice_description`	`string`	发票说明
`invoice_value`	`number`	发票金额
`items[]`	`object`	发票项目清单
`items[].code`	`string`	项目代码（NCM/SH）
`items[].description`	`string`	项目说明
`items[].quantity`	`integer`	项目数量
`items[].value`	`number`	项目金额
`rps_code`	`string`	RPS 代码 —— 服务临时收据
`access_key`	`string`	访问密钥，用于商品发票

bankslip_default — 在 analysis_result 中返回的字段

字段	类型	说明
`beneficiary_cnpj`	`string`	受益人 CNPJ
`beneficiary_company_name`	`string`	受益人法定名称
`boleto_barcode`	`string`	付款单条形码
`due_date`	`string`	到期日
`value`	`number`	付款单金额

ccb_default — 在 analysis_result 中返回的字段

字段	类型	说明
`contract_number`	`string`	CCB 编号
`issuer_document`	`string`	出票人的 CPF 或 CNPJ
`issuer_cep`	`string`	出票人邮政编码（CEP）
`guarantee_chassis`	`string`	作为担保的车辆车架号（如适用）
`invoice_total_value`	`number`	发票总金额（如适用）
`annual_interest_rate`	`number`	固定年利率，以百分比表示
`financed_amount`	`number`	CCB 融资总金额
`total_installments`	`integer`	分期总期数
`first_due_date`	`string`	首期到期日
`last_due_date`	`string`	末期到期日（参见付款计划）
`has_signature`	`boolean`	表示文档是否具有有效签名（实体或电子）
`is_valid_contract`	`boolean`	表示所发送的文档是否确为银行信用凭证（CCB）

portability_retention_evidence_analysis — 在 analysis_result 中返回的字段

字段	类型	说明
`contract_number`	`string`	合同编号
`issuer_document_number`	`string`	借款人 CPF
`issuer_phone_number`	`string`	借款人电话号码
`portability_number`	`number`	携转编号
`has_signature`	`boolean`	表示文档（尤其是 CCB）是否包含电子签名要素，如哈希值、验证码、二维码或认证页。
`is_valid_evidence`	`boolean`	表示该文档是否属于可接受的证据类型，如文字对话或银行信用凭证（CCB）。
`is_confirmation`	`boolean`	表示该证据是否确认携转被取消。当客户明确声明取消或不承认携转请求，或证据为已签名的 CCB（has_signature: true）时应为 TRUE。当其不是对话，或对话未表明取消或不承认时应为 FALSE。该值始终为 TRUE 或 FALSE。

对于此处未列出的分析类型，请通过 suporte.caas@qitech.com.br 联系我们的支持团队，咨询自定义实现。

文件格式与限制

document_bytes 字段接受以下格式。文件的真实类型根据内容验证，而非扩展名或声明的 Content-Type —— 将 .jpg 标记为 application/pdf 发送会导致 DOC00202。

格式	最大大小	说明
PDF	30 MB	最多 350 页（`DOC00203`）。受密码保护的 PDF 会被拒绝（`DOC00305`）。
JPEG	30 MB
PNG	10 MB

响应

成功响应（`200 OK`）

同步分析成功完成时，API 返回 HTTP 200 OK 及以下响应体。信封字段始终相同；随 document_analysis_type 变化的是 analysis_result 的内容。

{
  "id": "request-abc-12345",
  "document_analysis_type": "proof_of_address_default",
  "validation_status": "valid",
  "file_metadata": { "file_type": "pdf" },
  "analysis_result": { "...": "提取的字段，随分析类型而变化" },
  "feedback_data": null
}

字段	说明
`id`	您在请求中发送的相同标识符。
`document_analysis_type`	应用的分析类型。
`validation_status`	验证结果。请参见下方的可能取值。
`file_metadata`	收到文件的元数据，例如检测到的类型。
`analysis_result`	提取的数据。分析未完成时为空（`{}`）。
`feedback_data`	您为该文档登记的反馈（如有）。

`validation_status` 取值

取值	含义
`valid`	分析成功完成。
`pending`	仍在处理中。
`missing_information`	文档缺少必需信息。
`bad_quality`	文档质量不足以进行分析。
`invalid_data`	文档包含无效或不一致的数据。
`incorrect_document_type`	内容与请求的分析类型不匹配。
`parsing_error`	分析结果无法解析。
`analysis_failed`	模型无法完成分析。

接受响应（`202 OK`）

如果文档以异步方式处理，API 将返回 HTTP 202 Accepted 状态，请求将异步处理。稍后可以使用 GET 请求检索文档分析，如下所述。

错误响应（`4xx`）

如果请求或文档存在问题，API 将返回 4xx 状态码和描述错误的 JSON 正文。

错误代码参考

以下表格列出了 API 返回的所有可能的错误代码。您可以使用这些代码在应用程序中实现健壮的错误处理。

类别 1：请求错误（DOC001xx）

代码	标题	描述
`DOC00100`	Missing required field	请求在 `multipart/form-data` 正文中不包含必填字段。
`DOC00101`	Invalid field length	`form-data` 字段中某个值的长度无效。
`DOC00102`	Invalid content type at request	请求的 `Content-Type` 头不是 `multipart/form-data`。
`DOC00103`	Invalid field at request	请求在 `form-data` 正文中包含意外或无效字段。

类别 2：文件处理错误（DOC002xx）

当发送的文件本身存在阻止处理的问题时，会发生这些错误。

代码	标题	描述
`DOC00200`	Invalid Document Analysis Type	`document_analysis_type` 对发送的文档无效。（例如：对水电费账单使用 `company_statute_default` 分析。）
`DOC00201`	Invalid File Size	发送的文档大小超过允许的最大限制。
`DOC00202`	Invalid File Type	由于类型或格式不一致，文件无法处理（例如：发送了一个 `.jpg` 文件，但类型为 `application/pdf`）。
`DOC00203`	PDF exceeds page limit	提供的 PDF 文件包含的页数超过了处理允许的最大限制（当前限制为 350 页）。

类别 3：文档分析错误（DOC003xx）

这些错误发生在数据提取和分析阶段，即文件成功打开之后。

代码	标题	描述
`DOC00300`	Missing Information	文档不包含完成分析所需的基本信息。
`DOC00301`	Bad Quality	文档质量（例如：分辨率、可读性、清晰度）太低，无法准确分析。
`DOC00302`	Invalid Data	文档包含不一致或无效的数据（例如：校验和不正确、字段相互矛盾）。
`DOC00303`	Incorrect Document Type	文档内容与所选 `document_analysis_type` 的预期文档类型不符。
`DOC00304`	Invalid PDF File	提供的文件不是有效或格式良好的 PDF，无法打开。
`DOC00305`	Password Protected PDF	发送的 PDF 已用密码加密，无法处理。
`DOC00306`	Parsing Error	无法处理文档分析。

类别 4：服务故障（DOC005xx）

这些错误表示问题出在我们这一侧，而非您的文档或请求。它们以 HTTP 5xx 状态返回，建议的操作是重试请求。

代码	标题	HTTP 状态	说明
`DOC00500`	Analysis Failed	`503`	无法完成分析。请重试；如果问题持续存在，请联系支持团队。

检索文档分析

您可以随时使用其唯一的 id 检索之前提交的文档分析结果。

https://api.caas.qitech.app/document_analysis/document/{document_id}

将 document_id 替换为您发送 POST 请求时使用的相同值。

登记分析反馈

您可以登记关于分析质量的反馈，这有助于我们改进模型。使用原始请求中相同的 id 向以下端点发送 POST 请求。

POST https://api.caas.qitech.app/document_analysis/document/{document_id}/feedback

curl -X POST "https://api.caas.qitech.app/document_analysis/document/request-abc-12345/feedback" \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "event_date": "2026-09-02T14:30:00",
  "feedback_data": { "incorrect_field": "issue_date", "correct_value": "2026-07-20" }
}'

属性	说明
`event_date`（必填）	反馈的日期和时间。
`feedback_data`（必填）	包含反馈内容的自由格式对象。

登记的反馈随后会在获取分析结果时通过 feedback_data 字段返回。也可以对同一端点发送 GET 请求来读取。

发送文件进行标准分析​

发送属性说明​

支持的分析类型​

文件格式与限制​

响应​

成功响应（200 OK）​

validation_status 取值​

接受响应（202 OK）​

错误响应（4xx）​

错误代码参考​

类别 1：请求错误（DOC001xx）​

类别 2：文件处理错误（DOC002xx）​

类别 3：文档分析错误（DOC003xx）​

类别 4：服务故障（DOC005xx）​