sinch-fax-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sinch Fax API

Overview

概述

The Sinch Fax API lets you send and receive faxes programmatically. It supports multiple file formats, webhooks for incoming faxes, fax-to-email delivery, and automatic retries. Used for healthcare, legal, financial, and government applications where fax remains a required communication channel.

Auth: HTTP Basic (

keyId:keySecret

) or OAuth2 bearer token. All examples use Basic auth. See sinch-authentication for setup.

Sinch Fax API允许您以编程方式发送和接收传真。它支持多种文件格式、入站传真Webhook、传真转邮件交付以及自动重试功能。适用于医疗、法律、金融和政府类应用场景，这些场景中传真仍是必需的沟通渠道。

认证方式： HTTP Basic（

keyId:keySecret

）或OAuth2承载令牌。所有示例均使用Basic认证。请参阅sinch-authentication进行设置。

Getting Started

快速开始

Before generating code, gather from the user: approach (SDK or direct API), language (Node.js, Python, Java, .NET, curl), and use case (sending, receiving, fax-to-email, or managing services). Do not assume defaults.

When the user chooses SDK, fetch the relevant API reference docs linked in Links for accurate method signatures. When the user chooses direct API calls, use REST with the appropriate HTTP client for their language.

Language	Package	Install
Node.js	`@sinch/sdk-core` (preview — not recommended for production)	`npm install @sinch/sdk-core`
Python	`sinch`	`pip install sinch`
Java	`com.sinch.sdk:sinch-sdk-java`	Maven dependency
.NET	`Sinch`	`dotnet add package Sinch`

在生成代码之前，需向用户确认以下信息：实现方式（SDK或直接调用API）、开发语言（Node.js、Python、Java、.NET、curl）以及使用场景（发送传真、接收传真、传真转邮件或管理服务）。请勿默认任何选项。

当用户选择SDK时，请参考链接中提供的相关API参考文档，以获取准确的方法签名。当用户选择直接调用API时，请使用REST方式，并结合其对应语言的合适HTTP客户端。

语言	包名	安装命令
Node.js	`@sinch/sdk-core` （预览版——不推荐用于生产环境）	`npm install @sinch/sdk-core`
Python	`sinch`	`pip install sinch`
Java	`com.sinch.sdk:sinch-sdk-java`	Maven依赖项
.NET	`Sinch`	`dotnet add package Sinch`

First API Call — Send a Fax

首次API调用——发送传真

curl (replace

{projectId}

with your project ID from the Sinch dashboard):

bash

curl -X POST \
  'https://fax.api.sinch.com/v3/projects/{projectId}/faxes' \
  -H 'Content-Type: application/json' \
  -u YOUR_key_id:YOUR_key_secret \
  -d '{
    "to": "+12025550134",
    "contentUrl": "https://example.com/document.pdf",
    "callbackUrl": "https://yourserver.com/fax-callback"
  }'

Node.js SDK: See Send a Fax with Node.js.

Test number: Send to

+19898989898

to emulate a real fax without charges (always suggest this for integration testing).

curl（将

{projectId}

替换为您在Sinch控制台中的项目ID）：

bash

curl -X POST \
  'https://fax.api.sinch.com/v3/projects/{projectId}/faxes' \
  -H 'Content-Type: application/json' \
  -u YOUR_key_id:YOUR_key_secret \
  -d '{
    "to": "+12025550134",
    "contentUrl": "https://example.com/document.pdf",
    "callbackUrl": "https://yourserver.com/fax-callback"
  }'

Node.js SDK： 请参阅使用Node.js发送传真。

测试号码： 发送至

+19898989898

可模拟真实传真发送且不产生费用（集成测试时建议始终使用该号码）。

Key Concepts

核心概念

Fax Services — Logical containers for fax configuration. Associate numbers, set defaults, and manage routing. Fax Numbers — Phone numbers provisioned for fax. Must be configured in your Sinch dashboard. Faxes — Individual fax transmissions (inbound or outbound). Each has a unique ID, status, and metadata. Fax statuses —

QUEUED

→

IN_PROGRESS

→

COMPLETED

FAILURE

. Error details in

errorType

and

errorMessage

fields. Supported formats — PDF (most reliable), DOC, DOCX, TIF/TIFF, JPG, PNG, TXT, HTML. Webhooks/Callbacks — HTTP POST notifications for fax events. Default content type is

multipart/form-data

(fax content as attachment). Set

callbackUrlContentType: "application/json"

for JSON callbacks. Cover Pages — Customizable cover pages per service. Attach via

coverPageId

and

coverPageData

on send. Fax-to-Email — Incoming faxes auto-forwarded to email addresses. Retries — Auto-retry on failure. Default set per fax service; maximum: 5. Retention — Fax logs and media retained for 13 months. Use

DELETE /faxes/{id}/file

to remove earlier.

传真服务 —— 用于配置传真的逻辑容器。可关联号码、设置默认值并管理路由。 传真号码 —— 为传真功能配置的电话号码。必须在Sinch控制台中完成配置。 传真任务 —— 单个的传真传输任务（入站或出站）。每个任务都有唯一ID、状态和元数据。 传真状态 ——

QUEUED

（排队中）→

IN_PROGRESS

（处理中）→

COMPLETED

（已完成）或

FAILURE

（失败）。错误详情包含在

errorType

和

errorMessage

字段中。 支持的文件格式 —— PDF（最可靠）、DOC、DOCX、TIF/TIFF、JPG、PNG、TXT、HTML。 Webhook/回调 —— 针对传真事件的HTTP POST通知。默认内容类型为

multipart/form-data

（传真内容作为附件）。可设置

callbackUrlContentType: "application/json"

以接收JSON格式的回调。 封面页 —— 可针对每个服务自定义封面页。发送时通过

coverPageId

和

coverPageData

进行关联。 传真转邮件 —— 收到的传真会自动转发至指定邮箱地址。 自动重试 —— 发送失败时自动重试。默认次数由传真服务设置，最大为5次。 数据保留 —— 传真日志和媒体文件保留13个月。可使用

DELETE /faxes/{id}/file

提前删除。

Common Patterns

常见使用模式

Three ways to deliver content:

contentUrl

for URLs (recommended — supports basic auth),

multipart/form-data

for local files, or

contentBase64

for in-memory bytes.

contentUrl

can be a single URL or an array of URLs to compose multi-document faxes.

For HTTPS URLs, ensure your SSL certificate (including intermediate certs) is valid and up-to-date. You can optionally specify

from

to set the sender number.

Send a fax (URL, file upload, base64, multiple recipients) — See Send a Fax endpoint. Use
```
multipart/form-data
```
for local files, JSON with
```
contentUrl
```
for URLs.
Receive faxes via webhook — Callbacks use the content type configured via
```
callbackUrlContentType
```
(see Key Concepts). Check
```
direction === 'INBOUND'
```
on the fax object. See Receive a Fax with Node.js.
Fax-to-email — Configure via API or dashboard. Incoming faxes auto-forward to the configured email. See Fax-to-Email Reference.
List faxes — See Faxes Endpoint Reference
Get fax details —
```
GET /faxes/{id}
```
Download fax content —
```
GET /faxes/{id}/file.pdf
```
(
```
.pdf
```
suffix required)
Delete fax content —
```
DELETE /faxes/{id}/file
```
(removes stored content before 13-month expiry)
Manage fax services — See Services Endpoint Reference
Manage cover pages —
```
POST/GET/DELETE /services/{id}/coverPages
```
— see Services reference
Manage fax-to-email — See Fax-to-Email Reference

交付内容的三种方式：使用

contentUrl

指定URL（推荐——支持Basic认证）、使用

multipart/form-data

上传本地文件，或是使用

contentBase64

传递内存中的字节数据。

contentUrl

可以是单个URL，也可以是URL数组以组合多文档传真。

对于HTTPS URL，请确保您的SSL证书（包括中间证书）有效且为最新版本。您可选择性指定

from

字段设置发送方号码。

发送传真（URL、文件上传、Base64、多收件人） —— 请参阅发送传真端点。本地文件使用
```
multipart/form-data
```
，URL使用JSON格式的
```
contentUrl
```
。
通过Webhook接收传真 —— 回调的内容类型由
```
callbackUrlContentType
```
配置（请参阅核心概念部分）。在传真对象中检查
```
direction === 'INBOUND'
```
来判断是否为入站传真。请参阅使用Node.js接收传真。
传真转邮件 —— 可通过API或控制台进行配置。收到的传真会自动转发至配置的邮箱。请参阅传真转邮件参考文档。
列出传真任务 —— 请参阅传真端点参考文档
获取传真详情 ——
```
GET /faxes/{id}
```
下载传真内容 ——
```
GET /faxes/{id}/file.pdf
```
（必须包含
```
.pdf
```
后缀）
删除传真内容 ——
```
DELETE /faxes/{id}/file
```
（在13个月保留期前删除存储的内容）
管理传真服务 —— 请参阅服务端点参考文档
管理封面页 ——
```
POST/GET/DELETE /services/{id}/coverPages
```
—— 请参阅服务参考文档
管理传真转邮件 —— 请参阅传真转邮件参考文档

Troubleshooting

故障排查

Fax not delivered

传真未交付

Check fax status via

GET /faxes/{id}

— look at

status

errorType

(

DOCUMENT_CONVERSION_ERROR

CALL_ERROR

FAX_ERROR

FATAL_ERROR

GENERAL_ERROR

), and

errorMessage

If
```
contentUrl
```
was used with HTTPS, verify the SSL certificate (including intermediate certs) is valid
Fax delivery depends on the receiving machine answering — retries are automatic (max 5, default set per service)

通过

GET /faxes/{id}

查询传真状态——查看

status

、

errorType

（

DOCUMENT_CONVERSION_ERROR

、

CALL_ERROR

、

FAX_ERROR

、

FATAL_ERROR

、

GENERAL_ERROR

）和

errorMessage

字段

如果使用了
```
contentUrl
```
且为HTTPS地址，请验证SSL证书（包括中间证书）是否有效
传真交付依赖接收方设备应答——系统会自动重试（最多5次，默认次数由服务设置）

Fax content renders incorrectly

传真内容显示异常

Complex DOC/DOCX formatting may not render perfectly on receiving machines. Recommend PDF instead.

复杂的DOC/DOCX格式在接收设备上可能无法完美渲染。建议使用PDF格式。

Cannot send or receive faxes

无法发送或接收传真

Verify the number has fax capability enabled in the Sinch dashboard
Numbers must be provisioned for fax before use

请在Sinch控制台中验证号码是否已启用传真功能
号码必须先完成传真功能的配置才能使用

Gotchas and Best Practices

注意事项与最佳实践

Use
```
callbackUrl
```
for status tracking — fax delivery is async. Prefer callbacks over polling.
PDF is the safest format for reliable rendering on receiving machines.
Fax logs and media are retained for 13 months. Use
```
DELETE /faxes/{id}/file
```
to remove earlier, or download and archive if longer retention is needed.
International fax success rates vary by country — some have specific dialing prefix requirements.
Use
```
resolution: "SUPERFINE"
```
(400 dpi) for faxes with small text or detailed images; default
```
FINE
```
(200 dpi) works for most cases.

使用
```
callbackUrl
```
跟踪状态——传真交付是异步的。优先使用回调而非轮询。
为确保在接收设备上可靠渲染，PDF是最安全的文件格式。
传真日志和媒体文件保留13个月。如需提前删除，可使用
```
DELETE /faxes/{id}/file
```
；如需更长时间保留，请下载并归档。
国际传真的成功率因国家而异——部分国家有特定的拨号前缀要求。
对于包含小字体或细节丰富的图像的传真，使用
```
resolution: "SUPERFINE"
```
（400 dpi）；默认的
```
FINE
```
（200 dpi）适用于大多数场景。

sinch-fax-api

Original

Translation

Sinch Fax API

Sinch Fax API

Overview

概述

Getting Started

快速开始

First API Call — Send a Fax

首次API调用——发送传真

Key Concepts

核心概念

Common Patterns

常见使用模式

Troubleshooting

故障排查

Fax not delivered

传真未交付

Fax content renders incorrectly

传真内容显示异常

Cannot send or receive faxes

无法发送或接收传真

Gotchas and Best Practices

注意事项与最佳实践

Links

相关链接