時刻とデータ形式

JSONとテキスト

• リクエストボディとレスポンスボディは、Content-Type: application/jsonのUTF-8のJSONです。ファイルのアップロードにはmultipart/form-dataを使います。
• フィールド名と列挙値はsnake_caseです：next_retry_at、index_failed。
• エラーメッセージとAPIのテキストは英語です。カードのタイトルなど自分で書いたテキストは、書いたとおりの言語でそのまま返されます。

時刻

時刻はすべて、UTCのRFC 3339タイムスタンプです。

{"created_at": "2026-10-24T10:00:00Z"}

• 新しいフィールドは、上の例のようにZを使った短い形式です。
• 以前からあるフィールドの一部は、2026-10-24T10:00:00.123456+00:00の形式で、秒の小数部が最大6桁あります。UTCで同じ時点を表します。どちらの形式も標準のRFC 3339パーサーで解析し、タイムスタンプを文字列として比較しないでください。
• 名前が_atで終わるフィールドはすべてタイムスタンプです。

送信する時刻には、Zまたは+02:00のような数値のタイムゾーンのオフセットを含める必要があります。オフセットのない時刻はあいまいなので、コードvalidation.failedとともに422が返ります。Sursaは受け取った時刻をすべてUTCに変換します。

const since = new Date(Date.now() - 24 * 3600 * 1000).toISOString(); // "2026-10-23T10:00:00.000Z"

クエリ文字列の中では、+は%2Bと書く必要があります。そうしないとスペースとして解釈されます。時刻の値をURLエンコードするか、Zを使ってください。

日付・期間・件数

金額

財務関連のレスポンスの金額は、精度が失われないように、浮動小数点数ではなく"1250.00"のような10進数の文字列です。通貨は別のフィールドで、"EUR"のようなISO 4217のコードです。金額は、使用する言語の10進数型で解析してください。

ID

IDは、オブジェクトによって文字列または整数です。オブジェクトのIDを参照してください。

列挙型

ステータスなど、値の集合が決まっているフィールドは文字列です。レスポンスの列挙型はどれも、後のバージョンで新しい値が加わることがあります。知らない値は「その他」として扱ってください。バージョンと互換性を参照してください。

nullと省略されたフィールド

• nullは「値なし」を意味します。担当者のいないカードは"owner_id": nullです。
• そのオブジェクトやそのリクエストに当てはまらないフィールドは、レスポンスから省略されることがあります。常に含まれるフィールドはAPIリファレンスに記載されています。
• PATCHでは、送信しなかったフィールドは値を保ちます。リファレンスでnullが許可されているフィールドは、nullを送信すると値を消去できます。