薪资单识别

薪资单分类与字段抽取接口说明。通用鉴权与返回约定见「快速开始」；本产品业务接口使用请求头 X-API-Key。

目录

• 1. POST /v1/classify
• 2. POST /v1/extract
• 3. GET /health
• Glossary

1. POST /v1/classify

判断图片是否为薪资单，并返回文档类型及子类型。适用于服务端 B2B 调用（图片 Base64 编码传输）。

Code Sample:

curl -X POST \
  -H "X-API-Key: {Your API Key}" \
  -H "Content-Type: application/json" \
  -d '{"image_base64": "{Base64 encoded image}", "file_type": "JPEG"}' \
  "https://verifai.mocasa.com/payslipscan/v1/classify"

Request URL

https://verifai.mocasa.com/payslipscan/v1/classify POST (application/json)

Request Header Parameters

Request Parameters

Note:

• Image size must not exceed 5 MB
• Supported formats: JPEG, PNG

Example of Success Response — document is a payslip:

{
    "request_id": "a3f8c2e1-7b4d-4e9a-b5c6-1234567890ab",
    "status": "success",
    "result": {
        "document_type": "PAYSLIP",
        "payslip_subtype": "NORMAL_PAYSLIP",
        "detected_document_type": null
    },
    "error_message": null,
    "pricing_strategy": "PAY"
}

Example of Success Response — document is a BIR tax certificate:

{
    "request_id": "b4e9d3f2-8c5e-4f0b-a6d7-2345678901bc",
    "status": "success",
    "result": {
        "document_type": "PAYSLIP",
        "payslip_subtype": "TAX_CERTIFICATE",
        "detected_document_type": null
    },
    "error_message": null,
    "pricing_strategy": "PAY"
}

Example of Success Response — document is NOT a payslip:

{
    "request_id": "c5f0e4g3-9d6f-5g1c-b7e8-3456789012cd",
    "status": "success",
    "result": {
        "document_type": "NOT_PAYSLIP",
        "payslip_subtype": null,
        "detected_document_type": "EMPLOYMENT_CERTIFICATE"
    },
    "error_message": null,
    "pricing_strategy": "PAY"
}

Example of INVALID_INPUT Response:

{
    "request_id": "c2d4e6f8-1a3b-5c7d-9e0f-abcdef012345",
    "status": "error",
    "result": null,
    "error_message": "Image exceeds 5MB limit.",
    "pricing_strategy": "FREE"
}

Example of SERVICE_UNAVAILABLE Response:

{
    "request_id": "d6g1f5h4-0e7g-6h2d-c8f9-4567890123de",
    "status": "error",
    "result": null,
    "error_message": "Service temporarily unavailable. Please retry later.",
    "pricing_strategy": "FREE"
}

Example of PROCESSING_FAILED Response:

{
    "request_id": "e8h3i9l2-5j1k-2m7n-g3o4-9012345678ij",
    "status": "error",
    "result": null,
    "error_message": "Classification result could not be parsed. Please retry or use a clearer image.",
    "pricing_strategy": "PAY"
}

Response Description

Result Detail of result:

Response Code {#response-code-classify}

Note: Please also refer to Common Status Codes in the Glossary.

2. POST /v1/extract

从薪资单图片中提取结构化字段（姓名、雇主、薪资周期、薪资金额）。适用于服务端 B2B 调用（图片 Base64 编码传输）。

Recommended: Call /v1/classify first to confirm document_type is PAYSLIP before calling this endpoint.

Code Sample:

curl -X POST \
  -H "X-API-Key: {Your API Key}" \
  -H "Content-Type: application/json" \
  -d '{"image_base64": "{Base64 encoded image}", "file_type": "JPEG"}' \
  "https://verifai.mocasa.com/payslipscan/v1/extract"

Code Sample (generate payload from local file):

python3 -c "
import base64, json
with open('/path/to/payslip.jpg', 'rb') as f:
    b64 = base64.b64encode(f.read()).decode()
print(json.dumps({'image_base64': b64, 'file_type': 'JPEG'}))
" > payload.json

curl -X POST \
  -H "X-API-Key: {Your API Key}" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  "https://verifai.mocasa.com/payslipscan/v1/extract"

Request URL

https://verifai.mocasa.com/payslipscan/v1/extract POST (application/json)

Request Header Parameters

Request Parameters

Example of Success Response — all fields extracted:

{
    "request_id": "e7h2g6i5-1f8h-7i3e-d9g0-5678901234ef",
    "status": "success",
    "result": {
        "employee_name": "Maria Santos",
        "employer_name": "XYZ Manufacturing Inc.",
        "pay_period": "2024-03-01 to 2024-03-15",
        "gross_pay": 18500.00,
        "net_pay": 15320.75
    },
    "error_message": null,
    "pricing_strategy": "PAY"
}

Example of Success Response — some fields not found (partial null):

{
    "request_id": "f8i3h7j6-2g9i-8j4f-e0h1-6789012345fg",
    "status": "success",
    "result": {
        "employee_name": "Pedro Reyes",
        "employer_name": null,
        "pay_period": null,
        "gross_pay": 12000.00,
        "net_pay": 10500.00
    },
    "error_message": null,
    "pricing_strategy": "PAY"
}

Example of INVALID_INPUT Response:

{
    "request_id": "h0k5j9l8-4i1k-0l6h-g2j3-8901234567hi",
    "status": "error",
    "result": null,
    "error_message": "Image exceeds 5MB limit.",
    "pricing_strategy": "FREE"
}

Example of SERVICE_UNAVAILABLE Response:

{
    "request_id": "g9j4i8k7-3h0j-9k5g-f1i2-7890123456gh",
    "status": "error",
    "result": null,
    "error_message": "Service temporarily unavailable. Please retry later.",
    "pricing_strategy": "FREE"
}

Example of PROCESSING_FAILED Response:

{
    "request_id": "k1m6n0p9-7l3m-1o8p-i5q6-0123456789kl",
    "status": "error",
    "result": null,
    "error_message": "Extraction result could not be parsed. Please retry or use a clearer image.",
    "pricing_strategy": "PAY"
}

Response Description

Result Detail of result:

Note:

• All fields are read from printed values only. No calculation or inference is performed.
• gross_pay and net_pay must come from the same pay period.
• For multi-period payslips: aggregate totals are preferred; otherwise the most recent sub-period is used.

Response Code {#response-code-extract}

Note: Please also refer to Common Status Codes in the Glossary.

3. GET /health

服务健康检查，无需鉴权。

Code Sample:

curl "https://verifai.mocasa.com/payslipscan/health"

Request URL

https://verifai.mocasa.com/payslipscan/health GET

Example of Success Response:

{
    "status": "ok"
}

HTTP status code 200 indicates the service is running normally.

Glossary

Authentication

All business endpoints (/v1/*) require the X-API-Key request header for authentication.

Notes:

• When neither SERVICE_API_KEY nor SERVICE_API_KEYS is configured on the server, authentication is automatically disabled (development/test mode). All requests are accepted without a key.
• /health endpoint does not require authentication.

Common Status Codes {#common-status-codes}

The following HTTP status codes may be returned for authentication failures. These are distinct from the business-layer error_message field in the response body.

Note: Business-layer errors (INVALID_INPUT, SERVICE_UNAVAILABLE, PROCESSING_FAILED) always return HTTP 200. Use the status field in the response body to determine success or failure.

Pricing Strategy

Each response includes a pricing_strategy field indicating whether the request incurs a charge:

Request URL & Parameters

• Request URL can be found at each API section along with the request method (POST or GET) and Content-Type
• Parameters marked optional are not mandatory; omitting them uses the documented default value
• Parameters without optional are mandatory; omitting them may return INVALID_INPUT

Image Quality Requirements

The service extracts information from uploaded images. Please ensure images satisfy the following:

• Format: PNG / JPG / JPEG
• File size: below 5 MB
• Content: the payslip should be clearly readable; heavily blurred or low-resolution images will return NOT_PAYSLIP / OTHER_DOCUMENT from /v1/classify
• Orientation: upright or landscape; avoid heavy tilting
• Visibility: no obstructions covering text (glare, shadow, dirt, ink marks)