Misoca API v1

Misoca の外部API を定義します。

Service URL (リクエスト先URL)

Representation Formats (表現形式)

Misoca APIはRESTなURLを提供し、HTTPパラメータで引数を渡します。

戻り値は、HTTP STATUS CODE 200 とともに、指定したフォーマットで取得されます。

請求書の構造

invoice 1-1 invoice_body  
  1-n invoice_items 最大40件

基本的なデータ構造は、 請求書(invoice) に対して単一の請求書本文(invoice_body)と複数の請求明細(invoice_item)を持ちます。 invoice_item の最大件数は40件です。

各種APIの詳細

【自己情報取得】

GET /me

自身の情報を返します。

要求する権限

返り値 (成功)

パラメータ 説明
user_id ユーザID。ユーザを一意に識別します。
email ユーザのメールアドレスです。

サンプルレスポンス

{
  "user_id": 110602,
  "email": user@example.com
}

【新規作成】

POST /invoice/

請求書を作成します。

要求する権限

POSTパラメータ

invoice_items は最大で40件までになります。

パラメータ 項目 必須 制限
invoice[invoice_number] 請求番号 - 20文字

請求書に記載される請求番号です。
未記入の場合は自動で番号が付与されます。

パラメータ 項目 必須 制限
invoice[issue_date] 請求日 日付

請求日付です。
YYYY/MM/DD(西暦年/月/日)の形式で記入してください。
例: 2012/05/25

パラメータ 項目 必須 制限
invoice[payment_due_on] お支払い期限 - 日付

支払いの期日です。
YYYY/MM/DD(西暦年/月/日)の形式で記入してください。
例: 2012/06/30

パラメータ 項目 必須 制限
invoice[subject] 件名 - 40文字

請求書に記載される件名です。

パラメータ 項目 必須 制限
invoice[recipient_name] 請求先名称 40文字

請求書に記載される、請求先の名称です。
必ず記入してください。

パラメータ 項目 必須 制限
invoice[recipient_title] 敬称 - 5文字

請求先に付加される敬称です。

パラメータ 項目 必須 制限
invoice[recipient_notes] 担当者 -  

請求先の担当者です。

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][recipient_zip_code] 送付先郵便番号 郵送時必須 8文字

郵送する場合に必要となる送付先郵便番号です。
封筒の宛先欄に印字されます。
000-0000 形式で記入してください。
例: 460-0007

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][recipient_address1] 送付先住所1 郵送時必須 60文字

郵送する場合に必要となる送付先住所です。
封筒の宛先欄に印字されます。

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][recipient_address2] 送付先住所2 - 60文字

郵送する場合に必要となる送付先住所です。
封筒の宛先欄に印字されます。

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][recipient_name1] 送付先名前1 郵送時必須 20文字

郵送する場合に必要となる送付先の名前です。
封筒の宛先欄に印字されます。

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][recipient_name2] 送付先名前2 - 20文字

郵送する場合に必要となる送付先の名前です。
封筒の宛先欄に印字されます。

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][recipient_name3] 送付先名前3 - 20文字

郵送する場合に必要となる送付先の名前です。
封筒の宛先欄に印字されます。

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][recipient_name4] 送付先名前4 - 20文字

郵送する場合に必要となる送付先の名前です。
封筒の宛先欄に印字されます。

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][recipient_title] 送付先敬称 - 5文字

郵送する場合に必要となる送付先の名前です 。
封筒の宛先欄に印字されます。
送付先名前1-4の末尾に付加されます。

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][tax_rate] 消費税率 - 小数

消費税率を整数パーセンテージで設定します。 記入がない場合は、[自社情報]-[消費税設定]に設定された情報が利用されます。

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][tax_option] 消費税設定 - 右記

請求金額の計算を行う際の消費税設定を記入します。
下記の
EXCLUDE」「INCLUDE」「EXEMPT」のいずれかを記入してください。

記入がない場合は、[自社情報]-[消費税設定]に設定された情報が利用されます。

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][sender_zip_code] 送信者郵便番号 郵送時必須 000-0000
パラメータ 項目 必須 制限
invoice[invoice_body_attributes][sender_address1] 送信者住所 郵送時必須 -
invoice[invoice_body_attributes][sender_address2] 送信者住所2   -
invoice[invoice_body_attributes][sender_address3] 送信者住所3   -
パラメータ 項目 必須 制限
invoice[invoice_body_attributes][sender_name1] 送信者名1 郵送時必須 (1)
invoice[invoice_body_attributes][sender_name2] 送信者名2   (1)
invoice[invoice_body_attributes][sender_name3] 送信者名3   (1)

(1)255文字まで。但し、請求書を郵送するには20文字までとしてください。

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][sender_tel] 送信者電話番号 - -
パラメータ 項目 必須 制限
invoice[invoice_body_attributes][sender_fax] 送信者FAX番号 - -
パラメータ 項目 必須 制限
invoice[invoice_body_attributes][sender_email] 送信者メールアドレス - -
パラメータ 項目 必須 制限
invoice[invoice_body_attributes][notes] 備考 - -
パラメータ 項目 必須 制限
invoice[invoice_body_attributes][withholding_tax_type] 源泉徴収税設定 - 下記

源泉徴収税設定です。下記のいずれかを記入してください。

記入がない場合は、[自社情報]-[課税設定]に設定された情報が利用されます。

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][tax_rounding_policy] 消費税端数処理 - 下記

消費税端数処理です。下記のいずれかを記入してください。

記入がない場合は、[自社情報]-[課税設定]に設定された情報が利用されます。

パラメータ 項目 必須 制限
invoice[invoice_body_attributes][bank_accounts_attributes][0][detail] 振込口座名1 - -
invoice[invoice_body_attributes][bank_accounts_attributes][1][detail] 振込口座名2 - -
invoice[invoice_body_attributes][bank_accounts_attributes][2][detail] 振込口座名3 - -

振込先の口座名です(最大3行まで)。 記入がない場合は、[自社情報]-[お振込先]に設定された情報が利用されます。

パラメータ 項目 必須 制限
invoice[invoice_items_attributes][0][name] 品目1 - 255文字

請求書に記載される項目の品目名です。

パラメータ 項目 必須 制限
invoice[invoice_items_attributes][0][quantity] 数量1 - 数値

請求書に記載される項目の数量です。

パラメータ 項目 必須 制限
invoice[invoice_items_attributes][0][unit_price] 単価1 - 数値

請求書に記載される項目の単価です。
¥などの通貨記号は記入しないでください。

パラメータ 項目 必須 制限
invoice[invoice_items_attributes][0][unit_name] 単位1 - -

請求書に記載される項目の単位です。

パラメータ 項目 必須 制限
invoice[invoice_items_attributes][0][tax_exempted] 消費税対象外フラグ1 - 真偽値

請求書に記載される項目の消費税対象外フラグです。

パラメータ 項目 必須 制限
invoice[invoice_items_attributes][0][excluding_withholding_tax] 源泉徴収税対象外フラグ1 - 真偽値

請求書に記載される項目の源泉徴収税対象外フラグです。

パラメータ 項目 必須 制限
invoice[recipient_code] 取引先管理コード - -

関連付けたい取引先の管理コードを指定してください

※ 下記項目は取引先の値が請求書に設定されます。

※ 下記項目は、パラメータ・取引先・自社情報の順の優先度で、値が請求書に設定されます。(例:パラメータに記入がなく、取引先に記入があれば、取引先の値)

返り値(成功)

パラメータ 説明
id 請求書ID

【請求ステータスの更新】

PUT /invoice/:id/submitted

指定された請求書を請求済にします。

PUT /invoice/:id/unsubmitted

指定された請求書を未請求にします。

要求する権限

URLパラメータ

パラメータ 説明
:id 請求書IDを示します

返り値(成功)

パラメータ 説明
id 請求書ID

【入金ステータスの更新】

PUT /invoice/:id/paid

指定された請求書を入金済みにします。

PUT /invoice/:id/unpaid

指定された請求書を未入金にします。

要求する権限

URLパラメータ

パラメータ 説明
:id 請求書IDを示します

返り値(成功)

パラメータ 説明
id 請求書ID

【取得】

GET /invoice/:id

指定された請求書を取得します。

要求する権限

URLパラメータ

パラメータ 説明
:id 請求書IDを示します

返り値(成功)

パラメータ 説明
archived_at 処理日時
delivery_status 郵送状況(発送完了:1 未完了:0)
delivery_status_result 郵送結果
id 請求書ID
invoice_number 請求番号
invoice_status ステータス(請求済み:1 未請求:0)
issue_date 発行日時
payment_due_on お支払期限
payment_status 支払状況
recipient_name 請求先名
recipient_title 敬称
trashed_at 削除日時
final_total_price 合計金額
withholding_tax_type 源泉徴収税種別
amount_of_withholding_tax 源泉徴収税
percentage_of_tax_rate 消費税率(パーセント表示)(例: 8%)
tax_rate 消費税率(例: 0.08)
amount_of_tax 消費税額
user_id ユーザのID
invoice_body 請求書の内容
invoice_items 請求商品
パラメータ 説明
notes 備考
recipient_address1 送付先住所1
recipient_address2 送付先住所2
recipient_name1 送付先氏名1
recipient_name2 送付先氏名2
recipient_name3 送付先氏名3
recipient_name4 送付先氏名4
recipient_title 敬称
recipient_zip_code 請求先郵便番号
sender_address1 請求元住所1
sender_address2 請求元住所2
sender_address3 請求元住所3
sender_email 請求元メールアドレス
sender_fax 請求元FAX番号
sender_name1 請求元名1
sender_name2 請求元名2
sender_name3 請求元名3
sender_tel 請求元電話番号
sender_zip_code 請求元郵便番号
tax_option 消費税設定(税別:EXCLUDE 税込:INCLUDE 免税:EXEMPT)
tax_rate 消費税率
bank_accounts 口座情報
パラメータ 説明
detail 口座情報
display_order 表示順
パラメータ 説明
name 名前
quantity
tax_exempted 消費税フラグ
unit_price 単価
price 小計

サンプルレスポンス

{
  "archived_at": null,
  "delivery_status": 0,
  "delivery_status_result": null,
  "id": 91,
  "invoice_number": "20140327-001",
  "invoice_status": 0,
  "issue_date": "2014-03-27",
  "payment_due_on": null,
  "payment_status": 0,
  "recipient_name": "Standfirm",
  "recipient_title": "様",
  "trashed_at": null,
  "final_total_price": 6000,
  "withholding_tax_type": "JapaneseStandardWithReconstructionTax" ,
  "amount_of_withholding_tax" 600, //要計算
  "tax_rate": 8 ,
  "amount_of_tax": 480,   //要計算
  "user_id": 110602,
  "invoice_body": {
    "notes": "振り込み手数料は\r\nご負担\r\nお願いいたします。",
    "recipient_address1": "愛知県名古屋市浪速区",
    "recipient_address2": "1-43-5",
    "recipient_name1": "ミソカ",
    "recipient_name2": "太郎",
    "recipient_name3": "",
    "recipient_name4": "",
    "recipient_title": "様",
    "recipient_zip_code": "4620803",
    "sender_address1": "東京都",
    "sender_address2": "渋谷区大須",
    "sender_address3": "1-3",
    "sender_email": "office@example.com",
    "sender_fax": "03-0000-0002",
    "sender_name1": "ミソカインボイス株式会社",
    "sender_name2": "開発部",
    "sender_name3": "請求書サービス課",
    "sender_tel": "03-0000-0001",
    "sender_zip_code": "151-0064",
    "tax_option": "EXEMPT",
    "tax_rate": 5,
    "bank_accounts": [
      {
        "detail": "日本ジャパン銀行 丸の内支店 普通口座 0123456 ミソカインボイス(カ 1",
        "display_order": 0
      },
      {
        "detail": "日本ジャパン銀行 丸の内支店 普通口座 0123456 ミソカインボイス(カ 2",
        "display_order": 1
      },
      {
        "detail": "日本ジャパン銀行 丸の内支店 普通口座 0123456 ミソカインボイス(カ 3",
        "display_order": 2
      }
    ]
  },
  "invoice_items": [
    {
      "name": "item",
      "quantity": "3.0",
      "tax_exempted": false,
      "unit_price": "500.0",
      "price": 1500
    },
    {
      "name": "item2",
      "quantity": "5.0",
      "tax_exempted": false,
      "unit_price": "900.0",
      "price": 4500
    },
    {
      "name": "",
      "quantity": null,
      "tax_exempted": false,
      "unit_price": null,
      "price": 0
    },
    ...
  ]
}

【一覧取得】

GET /invoices/

要求する権限

GETパラメータ

パラメータ 項目 必須 デフォルト 制限 説明
offset 開始 x 0   負数の場合は0。総件数を超える場合は空集合が返されます。
limit 取得件数 x     指定のない場合は 、20件
order ソート種別 x created_at 単数 ソートの基準とする要素。created_at / issue_date / invoice_number / recipient_name
ascending 昇順/降順 x 1   1なら昇順、0なら降順

サンプルレスポンス

[
  {
    "user_id": 110602,
    "archived_at": null,
    "delivery_status": 0,
    "delivery_status_result": null,
    "id": 91,
    "invoice_number": "20140327-001",
    "invoice_status": 0,
    "issue_date": "2014-03-27",
    "payment_due_on": null,
    "payment_status": 0,
    "recipient_name": "Standfirm",
    "recipient_title": "様",
    "trashed_at": null
  },
  {
    "user_id": 110602,
    "archived_at": null,
    "delivery_status": 0,
    "delivery_status_result": null,
    "id": 92,
    "invoice_number": "20140327-002",
    "invoice_status": 0,
    "issue_date": "2014-03-27",
    "payment_due_on": null,
    "payment_status": 0,
    "recipient_name": "ミソカインボイス",
    "recipient_title": "様",
    "trashed_at": null
  },
  ...
]

【郵送指示】

PUT /invoice/:id/send_by_postal_mail

要求する権限

URLパラメータ

パラメータ 説明
:id 請求書IDを示します

返り値(成功)

パラメータ 説明
id 請求書ID
delivery_status_result 発送状況

【郵送ステータス取得】

GET /invoice/:id/delivery_status_result

要求する権限

URLパラメータ

パラメータ 説明
:id 請求書IDを示します

返り値(成功)

パラメータ 説明
id 請求書ID
delivery_status_result 発送状況

配送状況は、郵送が指示されていない場合は、空文字("")になり、郵送指示がされると未処理受付済配達依頼配達中の順に遷移します。

サンプルレスポンス

{
  "id": 12345,
  "delivery_status_result": "受付済"
}

【PDF取得】

GET /invoice/:id/pdf

要求する権限

URLパラメータ

パラメータ 説明
:id 請求書IDを示します

返り値(成功)

パラメータ 説明
id 請求書ID
pdf Base64形式で符号化されたPDF形式の文書

サンプルレスポンス

{
	"id": 23456,
	"pdf": "JVBERi0xLjQ="
}

エラー発生時

APIを処理できない場合は、次のようなエラーレスポンスが返されます。

返り値(失敗)

HTTPステータスコード 意味 説明
422 Unprocessable Entity 処理できないエンティティ。
パラメータ名 説明
code エラーコード
reason エラー事由

エラーコード一覧

エラーコードは32ビット符号なし整数値で表されます。 10進表記の各桁ごとに次の意味を持ちます。

3桁 2桁 6桁
422固定 エラー分類コード 個別コード
内容 説明
422固定 エラーコードであることを示します
エラー分類コード エラーの分類を示すコードです
個別コード エラーの原因を示すコードです
エラーコード PrettyPrint 分類 定義 説明
4220100100 422-01-00100 payment not_registered 郵送料金の支払い方法が登録されていないため、郵送できません
4220200100 422-02-00100 user no_ticket 郵送チケットが不足しているため、郵送することができません
4220300000 422-03-00000 document not_enough_information 文書(請求書)に必須事項が不足しており、作成することができません
4220300100 422-03-00100 document not_postable 文書(請求書)に必須事項が不足しており、郵送することができません
4220300200 422-03-00200 document already_submitted 当該文書(請求書)はすでに郵送済みであり、郵送することができません
4220300300 422-03-00300 document not_exist 当該請求書は存在しません
4220300400 422-03-00400 document too_many_items 当該請求書の項目が多すぎで、作成することができません
4220300500 422-03-00500 document document_not_postable_due_to_sender_name 請求者名が20文字を超えており、郵送することができません
4220400100 422-04-00100 contact not_found 入力された取引先管理コードに関連付く取引先が存在しません
4220400200 422-04-00200 contact duplicate 入力された取引先管理コードに関連付く取引先が複数存在しています
4220000000 422-00-00000 unknown - 何らかの事由でエラーが発生しました

アップデート・更新履歴

2016年11月29日

2016年11月22日

2016年8月30日

2016年8月15日

2016年4月28日

2016年1月19日