@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Billingo API v3
@base https://api.billingo.hu/v3
@version 3.0.7
@auth ApiKey X-API-KEY in header
@endpoints 31
@hint download_for_search
@toc bank-accounts(5), currencies(1), document-blocks(1), documents(12), organization(1), partners(5), products(5), utils(1)

@group bank-accounts
@endpoint GET /bank-accounts
@desc List all bank account
@optional {page: int=1, per_page: int=25}
@returns(200) {data: [map], total: int, per_page: int, current_page: int, last_page: int, prev_page_url: str, next_page_url: str} # Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 422: Validation errors occured., 500: Internal server error.}

@endpoint POST /bank-accounts
@desc Create a bank account
@required {name: str, account_number: str, currency: str(AUD/BGN/BRL/CAD/CHF/CNY/CZK/DKK/EUR/GBP/HKD/HRK/HUF/IDR/ILS/INR/ISK/JPY/KRW/LTL/LVL/MXN/MYR/NOK/NZD/PHP/PLN/RON/RSD/RUB/SEK/SGD/THB/TRY/UAH/USD/ZAR)}
@optional {id: int, account_number_iban: str, swift: str, need_qr: bool=false}
@returns(201) {id: int, name: str, account_number: str, account_number_iban: str, swift: str, currency: str, need_qr: bool} # BankAccount created successfully.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 422: Validation errors occured., 500: Internal server error.}

@endpoint GET /bank-accounts/{id}
@desc Retrieve a bank account
@required {id: int}
@returns(200) {id: int, name: str, account_number: str, account_number_iban: str, swift: str, currency: str, need_qr: bool} # Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint PUT /bank-accounts/{id}
@desc Update a bank account
@required {id: int, name: str, account_number: str, currency: str(AUD/BGN/BRL/CAD/CHF/CNY/CZK/DKK/EUR/GBP/HKD/HRK/HUF/IDR/ILS/INR/ISK/JPY/KRW/LTL/LVL/MXN/MYR/NOK/NZD/PHP/PLN/RON/RSD/RUB/SEK/SGD/THB/TRY/UAH/USD/ZAR)}
@optional {id: int, account_number_iban: str, swift: str, need_qr: bool=false}
@returns(200) {id: int, name: str, account_number: str, account_number_iban: str, swift: str, currency: str, need_qr: bool} # Bank account updated successfully.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint DELETE /bank-accounts/{id}
@desc Delete a bank account
@required {id: int}
@returns(204) Bank account deleted successfully.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 404: Non-existent resource is requested., 500: Internal server error.}

@endgroup

@group currencies
@endpoint GET /currencies
@desc Get currencies exchange rate.
@required {from: str, to: str}
@returns(200) {from_currency: str, to_currency: str, conversation_rate: num(float)} # Currencies exchange rate returned.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 422: Validation errors occured., 500: Internal server error.}

@endgroup

@group document-blocks
@endpoint GET /document-blocks
@desc List all document blocks
@optional {page: int=1, per_page: int=25}
@returns(200) {data: [map], total: int, per_page: int, current_page: int, last_page: int, prev_page_url: str, next_page_url: str} # Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 422: Validation errors occured., 500: Internal server error.}

@endgroup

@group documents
@endpoint GET /documents
@desc List all documents
@optional {page: int=1, per_page: int=25, block_id: int # Filter documents by the identifier of your DocumentBlock., partner_id: int # Filter documents by the identifier of your Partner., payment_method: str # Filter documents by PaymentMethod value., payment_status: str # Filter documents by PaymentStatus value., start_date: str(date) # Filter documents by date., end_date: str(date) # Filter documents by date., start_number: int # Starting number of the document, should not contain year or any other formatting. Required if `start_year` given, end_number: int # Ending number of the document, should not contain year or any other formatting. Required if `end_year` given, start_year: int # Year for `start_number` parameter. Required if `start_number` given., end_year: int # Year for `end_number` parameter. Required if `end_number` given.}
@returns(200) {data: [map], total: int, per_page: int, current_page: int, last_page: int, prev_page_url: str, next_page_url: str} # Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 422: Validation errors occured., 500: Internal server error.}

@endpoint POST /documents
@desc Create a document
@required {partner_id: int, block_id: int, type: str(advance/draft/invoice/proforma), fulfillment_date: str(date), due_date: str(date), payment_method: str(aruhitel/bankcard/barion/barter/cash/cash_on_delivery/coupon/elore_utalas/ep_kartya/kompenzacio/levonas/online_bankcard/payoneer/paypal/paypal_utolag/payu/pick_pack_pont/postai_csekk/postautalvany/skrill/szep_card/transferwise/upwork/utalvany/valto/wire_transfer), language: str(de/en/fr/hr/hu/it/ro/sk), currency: str(AUD/BGN/BRL/CAD/CHF/CNY/CZK/DKK/EUR/GBP/HKD/HRK/HUF/IDR/ILS/INR/ISK/JPY/KRW/LTL/LVL/MXN/MYR/NOK/NZD/PHP/PLN/RON/RSD/RUB/SEK/SGD/THB/TRY/UAH/USD/ZAR)}
@optional {vendor_id: str, bank_account_id: int, conversion_rate: num(float)=1, electronic: bool=false, paid: bool=false, items: [any], comment: str, settings: map{mediated_service: bool, without_financial_fulfillment: bool, online_payment: str, round: str, place_id: int}}
@returns(201) {id: int, invoice_number: str, type: str, cancelled: bool, block_id: int, payment_status: str, payment_method: str, gross_total: num(float), currency: str, conversion_rate: num(float), invoice_date: str(date), fulfillment_date: str(date), due_date: str(date), paid_date: str(date), organization: map{name: str, tax_number: str, bank_account: map{id: int, name: str, account_number: str, account_number_iban: str, swift: str}, address: map{country_code: str, post_code: str, city: str, address: str}, small_taxpayer: bool, ev_number: str, eu_tax_number: str, cash_settled: bool}, partner: any, electronic: bool, comment: str, tags: [str], notification_status: str, language: str, items: [map], summary: map{net_amount: num(float), net_amount_local: num(float), gross_amount_local: num(float), vat_amount: num(float), vat_amount_local: num(float), vat_rate_summary: [map]}, settings: map{mediated_service: bool, without_financial_fulfillment: bool, online_payment: str, round: str, place_id: int}} # Document created successfully.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 422: Validation errors occured., 500: Internal server error.}

@endpoint GET /documents/{id}
@desc Retrieve a document
@required {id: int}
@returns(200) {id: int, invoice_number: str, type: str, cancelled: bool, block_id: int, payment_status: str, payment_method: str, gross_total: num(float), currency: str, conversion_rate: num(float), invoice_date: str(date), fulfillment_date: str(date), due_date: str(date), paid_date: str(date), organization: map{name: str, tax_number: str, bank_account: map{id: int, name: str, account_number: str, account_number_iban: str, swift: str}, address: map{country_code: str, post_code: str, city: str, address: str}, small_taxpayer: bool, ev_number: str, eu_tax_number: str, cash_settled: bool}, partner: any, electronic: bool, comment: str, tags: [str], notification_status: str, language: str, items: [map], summary: map{net_amount: num(float), net_amount_local: num(float), gross_amount_local: num(float), vat_amount: num(float), vat_amount_local: num(float), vat_rate_summary: [map]}, settings: map{mediated_service: bool, without_financial_fulfillment: bool, online_payment: str, round: str, place_id: int}} # Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint POST /documents/{id}/cancel
@desc Cancel a document
@required {id: int}
@returns(200) {id: int, invoice_number: str, type: str, cancelled: bool, block_id: int, payment_status: str, payment_method: str, gross_total: num(float), currency: str, conversion_rate: num(float), invoice_date: str(date), fulfillment_date: str(date), due_date: str(date), paid_date: str(date), organization: map{name: str, tax_number: str, bank_account: map{id: int, name: str, account_number: str, account_number_iban: str, swift: str}, address: map{country_code: str, post_code: str, city: str, address: str}, small_taxpayer: bool, ev_number: str, eu_tax_number: str, cash_settled: bool}, partner: any, electronic: bool, comment: str, tags: [str], notification_status: str, language: str, items: [map], summary: map{net_amount: num(float), net_amount_local: num(float), gross_amount_local: num(float), vat_amount: num(float), vat_amount_local: num(float), vat_rate_summary: [map]}, settings: map{mediated_service: bool, without_financial_fulfillment: bool, online_payment: str, round: str, place_id: int}} # Document cancellation successfully. Cancel document returned.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint POST /documents/{id}/create-from-proforma
@desc Create a document from proforma.
@required {id: int}
@returns(201) {id: int, invoice_number: str, type: str, cancelled: bool, block_id: int, payment_status: str, payment_method: str, gross_total: num(float), currency: str, conversion_rate: num(float), invoice_date: str(date), fulfillment_date: str(date), due_date: str(date), paid_date: str(date), organization: map{name: str, tax_number: str, bank_account: map{id: int, name: str, account_number: str, account_number_iban: str, swift: str}, address: map{country_code: str, post_code: str, city: str, address: str}, small_taxpayer: bool, ev_number: str, eu_tax_number: str, cash_settled: bool}, partner: any, electronic: bool, comment: str, tags: [str], notification_status: str, language: str, items: [map], summary: map{net_amount: num(float), net_amount_local: num(float), gross_amount_local: num(float), vat_amount: num(float), vat_amount_local: num(float), vat_rate_summary: [map]}, settings: map{mediated_service: bool, without_financial_fulfillment: bool, online_payment: str, round: str, place_id: int}} # Document created successfully.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint GET /documents/{id}/download
@desc Download a document in PDF format.
@required {id: int}
@returns(200) Document PDF file.
@returns(202) {message: str} # Document PDF has not generated yet. You should try to download again later.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint GET /documents/{id}/online-szamla
@desc Retrieve a document Online Számla status
@required {id: int}
@returns(200) {transaction_id: str, status: str, messages: [map]} # Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint GET /documents/{id}/payments
@desc Retrieve a payment histroy
@required {id: int}
@returns(200) Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint PUT /documents/{id}/payments
@desc Update payment history
@required {id: int}
@returns(200) Payment history updated successfully.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint DELETE /documents/{id}/payments
@desc Delete all payment history on document
@required {id: int}
@returns(200) Payment history deleted successfully.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 404: Non-existent resource is requested., 500: Internal server error.}

@endpoint GET /documents/{id}/public-url
@desc Retrieve a document download public url.
@required {id: int}
@returns(200) {public_url: str} # Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint POST /documents/{id}/send
@desc Send invoice to given email adresses.
@required {id: int}
@optional {emails: [str]}
@returns(200) {emails: [str]} # List of email adresses where the invoice sent.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endgroup

@group organization
@endpoint GET /organization
@desc Retrieve a organization data.
@returns(200) {tax_code: str} # Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 422: Validation errors occured., 500: Internal server error.}

@endgroup

@group partners
@endpoint GET /partners
@desc List all partners
@optional {page: int=1, per_page: int=25}
@returns(200) {data: [any], total: int, per_page: int, current_page: int, last_page: int, prev_page_url: str, next_page_url: str} # Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 422: Validation errors occured., 500: Internal server error.}

@endpoint POST /partners
@desc Create a partner
@required {name: str, address: map{country_code!: str, post_code!: str, city!: str, address!: str}}
@optional {emails: [str], taxcode: str, iban: str, swift: str, account_number: str, phone: str, general_ledger_number: str}
@returns(201) Partner created successfully.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 422: Validation errors occured., 500: Internal server error.}

@endpoint GET /partners/{id}
@desc Retrieve a partner
@required {id: int}
@returns(200) Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint PUT /partners/{id}
@desc Update a partner
@required {id: int, name: str, address: map{country_code!: str, post_code!: str, city!: str, address!: str}}
@optional {emails: [str], taxcode: str, iban: str, swift: str, account_number: str, phone: str, general_ledger_number: str}
@returns(200) Partner updated successfully.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint DELETE /partners/{id}
@desc Delete a partner
@required {id: int}
@returns(204) Partner deleted successfully.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 404: Non-existent resource is requested., 500: Internal server error.}

@endgroup

@group products
@endpoint GET /products
@desc List all product
@optional {page: int=1, per_page: int=25}
@returns(200) {data: [map], total: int, per_page: int, current_page: int, last_page: int, prev_page_url: str, next_page_url: str} # Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 422: Validation errors occured., 500: Internal server error.}

@endpoint POST /products
@desc Create a product
@required {name: str, currency: str(AUD/BGN/BRL/CAD/CHF/CNY/CZK/DKK/EUR/GBP/HKD/HRK/HUF/IDR/ILS/INR/ISK/JPY/KRW/LTL/LVL/MXN/MYR/NOK/NZD/PHP/PLN/RON/RSD/RUB/SEK/SGD/THB/TRY/UAH/USD/ZAR), vat: str(0%/1%/10%/11%/12%/13%/14%/15%/16%/17%/18%/19%/2%/20%/21%/22%/23%/24%/25%/26%/27%/3%/4%/5%/6%/7%/8%/9%/AAM/AM/EU/EUK/F.AFA/FAD/K.AFA/MAA/TAM/ÁKK/ÁTHK), unit: str}
@optional {id: int, comment: str, net_unit_price: num(float), general_ledger_number: str, general_ledger_taxcode: str}
@returns(201) {id: int, name: str, comment: str, currency: str, vat: str, net_unit_price: num(float), unit: str, general_ledger_number: str, general_ledger_taxcode: str} # Product created successfully.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 422: Validation errors occured., 500: Internal server error.}

@endpoint GET /products/{id}
@desc Retrieve a product
@required {id: int}
@returns(200) {id: int, name: str, comment: str, currency: str, vat: str, net_unit_price: num(float), unit: str, general_ledger_number: str, general_ledger_taxcode: str} # Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint PUT /products/{id}
@desc Update a product
@required {id: int, name: str, currency: str(AUD/BGN/BRL/CAD/CHF/CNY/CZK/DKK/EUR/GBP/HKD/HRK/HUF/IDR/ILS/INR/ISK/JPY/KRW/LTL/LVL/MXN/MYR/NOK/NZD/PHP/PLN/RON/RSD/RUB/SEK/SGD/THB/TRY/UAH/USD/ZAR), vat: str(0%/1%/10%/11%/12%/13%/14%/15%/16%/17%/18%/19%/2%/20%/21%/22%/23%/24%/25%/26%/27%/3%/4%/5%/6%/7%/8%/9%/AAM/AM/EU/EUK/F.AFA/FAD/K.AFA/MAA/TAM/ÁKK/ÁTHK), unit: str}
@optional {id: int, comment: str, net_unit_price: num(float), general_ledger_number: str, general_ledger_taxcode: str}
@returns(200) {id: int, name: str, comment: str, currency: str, vat: str, net_unit_price: num(float), unit: str, general_ledger_number: str, general_ledger_taxcode: str} # Product updated successfully.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endpoint DELETE /products/{id}
@desc Delete a product
@required {id: int}
@returns(204) Product deleted successfully.
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 403: Authenticated user doesn't have access to the resource., 404: Non-existent resource is requested., 500: Internal server error.}

@endgroup

@group utils
@endpoint GET /utils/convert-legacy-id/{id}
@desc Convert legacy ID to v3 ID.
@required {id: int}
@returns(200) {id: int, legacy_id: int} # Success response
@errors {400: The request is malformed., 401: Authorization information is missing or invalid., 404: Non-existent resource is requested., 422: Validation errors occured., 500: Internal server error.}

@endgroup

@end