bgpwtf/invoice/proto/invoice.proto

syntax = "proto3";
package invoice;
option go_package = "code.hackerspace.pl/hscloud/bgpwtf/invoice/proto";

// GTU codes as defined by JPK_V7. In context of polish VAT/tax law.
//   Original schema: http://crd.gov.pl/wzor/2020/05/08/9393/schemat.xsd
// These are used to tag invoice Items. These then get coalesced when an
// Invoice gets created, and that set of tags (specific now to an invoice)
// is then submitted to accounting.
// Numerical values of each code correspond to its numeric name (which is
// enshrined in the JPK schema).
// For each value, we provide one of more of following comments:
//  - PL: official polish <xsd:documentation> field from schema.
//  - EN: non-legally binding english translation for internal documentation
//        purposes.
//  - COMMENT: extra comments for internal documentation purposes.
enum GTUCode {
    GTU_INVALID = 0;
    // PL: Dostawa napojów alkoholowych - alkoholu etylowego, piwa, wina,
    //     napojów fermentowanych i wyrobów pośrednich, w rozumieniu przepisów
    //     o podatku akcyzowym
    // EN: Supply of alcoholic beverages - ethanol, beer, wine, fermented
    //     beverages and intermediate products, within the meaning of
    //     provisions on excise duty.
    GTU_01 = 1;
    // PL: Dostawa towarów, o których mowa w art. 103 ust. 5aa ustawy
    // EN: Supply of goods referred to in Art. 103 paragraph 5aa of the VAT law
    // COMMENT: liquid fuels.
    GTU_02 = 2;
    // PL: Dostawa oleju opałowego w rozumieniu przepisów o podatku akcyzowym
    //     oraz olejów smarowych, pozostałych olejów o kodach CN od 2710 19 71
    //     do 2710 19 99, z wyłączeniem wyrobów o kodzie CN 2710 19 85 (oleje
    //     białe, parafina ciekła) oraz smarów plastycznych zaliczanych do kodu
    //     CN 2710 19 99, olejów smarowych o kodzie CN 2710 20 90, preparatów
    //     smarowych objętych pozycją CN 3403, z wyłączeniem smarów
    //     plastycznych objętych tą pozycją
    // EN: Supply of fuel oil under the provisions of provisions on excise
    //     duty, and lubricating oils, other oils with CN codes from 2710 19 71
    //     do 2710 19 99, except products with code CN 2710 19 85 (while
    //     mineral oils, liquid paraffin) and high viscosity oils classified
    //     under code CN 2710 19 199, lubricating oils with code CN 2710 20 90,
    //     lubricating products classified under code CN 3403, except high
    //     viscosity lubricants classified under this code.
    GTU_03 = 3;
    // PL: Dostawa wyrobów tytoniowych, suszu tytoniowego, płynu do papierosów
    //     elektronicznych i wyrobów nowatorskich, w rozumieniu przepisów o
    //     podatku akcyzowym
    // EN: Supply of tobacco products, dried tobacco, electronic cigarette
    //     liquids and designer products, within the meaning of provisions on
    //     excise duty.
    GTU_04 = 4;
    // PL: Dostawa odpadów - wyłącznie określonych w poz. 79-91 załącznika nr
    //     15 do ustawy
    // EN: Waste supply - only as defined in annex 15 position 79-91 of the VAT
    //     law.
    // COMMENT: non-WEEE waste, except batteries.
    GTU_05 = 5;
    // PL: Dostawa urządzeń elektronicznych oraz części i materiałów do nich,
    //     wyłącznie określonych w poz. 7-9, 59-63, 65, 66, 69 i 94-96 załącznika
    //     nr 15 do ustawy
    // EN: Supply of electronic devices and components thereof, only as defined
    //     in annex 15, positions 7-9, 59-63, 65, 66, 69 and 94-96 of the VAT
    //     law.
    // COMMENT: print cartridges, ink, plastics, processors, computers, HDDs,
    //          SSDs, mobile phones, video game consoles, photo cameras,
    //          photocopier parts, software bundles on SSDs, video on SSDs.
    // COMMENT: tl;dr computer accessories and stuff, but not CDs/DVDs.
    GTU_06 = 6;
    // PL: Dostawa pojazdów oraz części samochodowych o kodach wyłącznie CN
    //     8701 - 8708 oraz CN 8708 10
    // EN: Supply of vehicles and car parts only with CN codes 8701-8708 and CN
    //     8708 10.
    GTU_07 = 7;
    // PL: Dostawa metali szlachetnych oraz nieszlachetnych - wyłącznie
    //     określonych w poz. 1-3 załącznika nr 12 do ustawy oraz w poz. 12-25,
    //     33-40, 45, 46, 56 i 78 załącznika nr 15 do ustawy
    // EN: Supply of precious and common metals - only as defined in annex 12
    //     positions 1-3 and annex 15 positions 12-25, 33-40, 45, 46, 56, 78 of
    //     the VAT law.
    // COMMENT: metals but also wax/stearine for sculpting, metal waste,
    //          antiques (>100Y) containing metal.
    GTU_08 = 8;
    // PL: Dostawa leków oraz wyrobów medycznych - produktów leczniczych,
    //     środków spożywczych specjalnego przeznaczenia żywieniowego oraz
    //     wyrobów medycznych, objętych obowiązkiem zgłoszenia, o którym mowa w
    //     art. 37av ust. 1 ustawy z dnia 6 września 2001 r. - Prawo
    //     farmaceutyczne (Dz. U. z 2019 r. poz. 499, z późn. zm.)
    // EN: Supply of medicine and medical products - [...]
    GTU_09 = 9;
    // PL: Dostawa budynków, budowli i gruntów
    // EN: Supply of buildings, structures and land.
    GTU_10 = 10;
    // PL: Świadczenie usług w zakresie przenoszenia uprawnień do emisji gazów
    //     cieplarnianych, o których mowa w ustawie z dnia 12 czerwca 2015 r. o
    //     systemie handlu uprawnieniami do emisji gazów cieplarnianych (Dz. U.
    //     z 2018 r. poz. 1201 i 2538 oraz z 2019 r. poz. 730, 1501 i 1532)
    // EN: Supply of services related to transfer of greenhouse gas emission
    //     allowances, as defined in Dz. U. z 2018r. poz. 1201 i 2538 oraz z
    //     2019r.  poz. 730, 1501 i 1532.
    GTU_11 = 11;
    // PL: Świadczenie usług o charakterze niematerialnym - wyłącznie:
    //     doradczych, księgowych, prawnych, zarządczych, szkoleniowych,
    //     marketingowych, firm centralnych (head offices), reklamowych,
    //     badania rynku i opinii publicznej, w zakresie badań naukowych i prac
    //     rozwojowych
    // EN: Supply of non-material services - only: consulting, accounting,
    //     legal, managerial, training, marketing, head offices, advertisement,
    //     market and public opinion study, within academic research and R&D.
    // COMMENT: IT consulting falls under this.
    GTU_12 = 12;
    // PL: Świadczenie usług transportowych i gospodarki magazynowej - Sekcja H
    //      PKWiU 2015 symbol ex 49.4, ex 52.1
    // EN: Supply of transport and logistics services [...].
    GTU_13 = 13;
}

// SP codes as defined by JPK_V7. In context of polish VAT/tax law.
//   Original schema: http://crd.gov.pl/wzor/2020/05/08/9393/schemat.xsd
// These are used to tag invoices, and describe sale procedures regarding this
// invoice.
// Numerical values are arbitrary.
// For each value, we provide one of more of following comments:
//  - PL: official polish <xsd:documentation> field from schema.
//  - EN: non-legally binding english translation for internal documentation
//        purposes.
//  - COMMENT: extra comments for internal documentation purposes.
enum SPCode {
    SP_INVALID = 0;
    // PL: Dostawa w ramach sprzedaży wysyłkowej z terytorium kraju, o której
    //     mowa w art. 23 ustawy
    // EN: Mail Order sales, as per art. 23 of the VAT law.
    SP_SW = 1;
    // PL: Świadczenie usług telekomunikacyjnych, nadawczych i elektronicznych,
    //     o których mowa w art. 28k ustawy
    // EN: Supply of telecommunication, broadcast and electronic services as
    //     per artc. 28k of the VAT law.
    // COMMENT: MOSS EU VAT sales.
    SP_EE = 2;
    // PL: Istniejące powiązania między nabywcą a dokonującym dostawy towarów
    //     lub usługodawcą, o których mowa w art. 32 ust. 2 pkt 1 ustawy
    // EN: Existing connection between the buyer and supplier of goods or
    //     services, as per art. 32, par. 2 point 2 of the VAT law
    SP_TP = 3;
    // PL: Wewnątrzwspólnotowe nabycie towarów dokonane przez drugiego w
    //     kolejności podatnika VAT w ramach transakcji trójstronnej w
    //     procedurze uproszczonej, o której mowa w dziale XII rozdziale 8
    //     ustawy
    // EN: Intra-EU goods supply by the second VAT taxpayer in a tripartite
    //     simplified procedures as defined insection XII chapter 8 of the VAT
    //     law
    SP_TT_WNT = 4;
    // PL: Dostawa towarów poza terytorium kraju dokonana przez drugiego w
    //     kolejności podatnika VAT w ramach transakcji trójstronnej w
    //     procedurze uproszczonej, o której mowa w dziale XII rozdziale 8
    //     ustawy
    // EN: Foreign goods supply by the second VAT taxpayer in a tripartite
    //     simplified procedures as defined insection XII chapter 8 of the VAT
    //     law
    SP_TT_D = 5;
    // PL: Świadczenie usług turystyki opodatkowane na zasadach marży zgodnie z
    //     art. 119 ustawy
    // EN: Supply of tourism services under magin tax as per art. 119 of the
    //     VAT law
    SP_MR_T = 6;
    // PL: Dostawa towarów używanych, dzieł sztuki, przedmiotów
    //     kolekcjonerskich i antyków, opodatkowana na zasadach marży zgodnie z
    //     art. 120 ustawy
    // EN: Supply of used goods, art, collectibles and antiques under margin
    //     tax as per art 120 of the VAT law
    SP_MR_UZ = 7;
    // PL: Wewnątrzwspólnotowa dostawa towarów następująca po imporcie tych
    //     towarów w ramach procedury celnej 42 (import)
    // EN: Intra-EU goods supply after import of these goods as part of the
    //     customs procedure 42 (import)
    SP_I_42 = 8;
    // PL: Wewnątrzwspólnotowa dostawa towarów następująca po imporcie tych
    //     towarów w ramach procedury celnej 63 (import)
    // EN: Intra-EU goods supply after import of these goods as part of the
    //     customs procedure 63 (import)
    SP_I_63 = 9;
    // PL: Transfer bonu jednego przeznaczenia dokonany przez podatnika
    //     działającego we własnym imieniu, opodatkowany zgodnie z art. 8a ust.
    //     1 ustawy
    // EN: Transfer of a single-purpose voucher by a taxpayer acting on their
    //     own behalf, taxed under art. 8a paragraph 1 of the VAT law
    SP_B_SPV = 10;
    // PL: Dostawa towarów oraz świadczenie usług, których dotyczy bon jednego
    //     przeznaczenia na rzecz podatnika, który wyemitował bon zgodnie z
    //     art. 8a ust. 4 ustawy
    // EN: Supply of goods and services affected by single-purpose voucher for
    //     a taxpayer, which emitted that voucher in accordance with art. 8a
    //     paragraph 4 of the VAT law
    SP_B_SPV_DOSTAWA = 11;
    // PL: Świadczenie usług pośrednictwa oraz innych usług dotyczących
    //     transferu bonu różnego przeznaczenia, opodatkowane zgodnie z art. 8b
    //     ust. 2 ustawy
    // EN: Supply of intermediary services and other services relating to the
    //     transfer of multi-purpose vouchers, taxed in accordance with art. 8b
    //     paragraph 2 of the VAT law
    SP_B_MPV_PROWIZJA = 12;
    // PL: Transakcja objęta obowiązkiem stosowania mechanizmu podzielonej
    //     płatności
    // EN: Transaction required to use the VAT split payment mechanism
    SP_MPP = 13;
}


// VAT invoice item (ie. entry).
message Item {
    string title = 1;
    uint64 count = 2;
    uint64 unit_price = 3;
    // in thousands of percent points
    // (ie 23% == 23000)
    uint64 vat = 4;
    // GTU codes for this item.
    repeated GTUCode gtu_code = 7;

    // Denormalized fields follow. These are only present in Invoice, not
    // InvoiceData.
    uint64 total_net = 5;
    uint64 total = 6;
    // Next tag: 8
}

// Point of contact for an invoice.
message ContactPoint {
    string medium = 1;
    string contact = 2;
}

// Invoice 'intent' - ie. data given by an Invoice creator. These never change
// after creation.
message InvoiceData {
    repeated Item item = 1;
    repeated string invoicer_billing = 2;
    repeated ContactPoint invoicer_contact = 3;
    repeated string customer_billing = 4;
    string invoicer_vat_id = 5;
    string invoicer_company_number = 12;
    string customer_vat_id = 6;
    bool reverse_vat = 7;
    bool us_customer = 11;
    // Optional, if not given the proforma will be created with the current time.
    int64 date = 14;
    int64 days_due = 8;
    string iban = 9;
    string swift = 10;
    string unit = 13;
    repeated SPCode sp_code = 15;
    // Next tag: 16
}

message Invoice {
    // Original invoice parameters/data.
    InvoiceData data = 1;
    enum State {
        STATE_INVALID = 0;
        STATE_PROFORMA = 1;
        STATE_SEALED = 2;
    };
    State state = 2;
    string uid = 9;
    // If sealed, otherwise 'proforma'.
    string final_uid = 3;
    int64 date = 4;
    // Denormalized fields follow.
    int64 due_date = 5;
    uint64 total_net = 6;
    uint64 total = 7;
    string unit = 8;
    repeated GTUCode gtu_code = 10;
    // Next tag: 11;
}

message CreateInvoiceRequest {
    InvoiceData invoice_data = 1;
}

message CreateInvoiceResponse {
    // Unique invoice ID
    string uid = 1;
}

message GetInvoiceRequest {
    string uid = 1;
}

message GetInvoiceResponse {
    Invoice invoice = 1;
}

message RenderInvoiceRequest {
    string uid = 1;
    string language = 2;
}

message RenderInvoiceResponse {
    bytes data = 1;
}

message SealInvoiceRequest {
    string uid = 1;
    enum DateSource {
        DATE_SOURCE_NOW = 0;
        DATE_SOURCE_PROFORMA = 1;
    }
    DateSource date_source = 2;
    string language = 3;
}

message SealInvoiceResponse {
}

message GetInvoicesRequest {
    // Return all invoices issued in a given year.
    message ForYear {
        int32 year = 1;
    }
    // Return all invoices issued in a given month of a year.
    message ForMonth {
        int32 year = 1;
        int32 month = 2;
    }

    oneof range {
        ForYear for_year = 1;
        ForMonth for_month = 2;
    }
}

message GetInvoicesResponse {
    // Each chunk may contain an arbitrary amount of invoices, and each
    // GetInvoices request may return an arbitrary amount of
    // GetInvoicesResponses in a stream.
    repeated Invoice invoice = 1;
}

service Invoicer {
    // Create an invoice with given data, returning UID. The newly created
    // invoice is created as a proforma invoice and not yet sealed, ie. not
    // given a unique, sequential ID.
    rpc CreateInvoice(CreateInvoiceRequest) returns (CreateInvoiceResponse);

    // Get invoice details for a given UID.
    rpc GetInvoice(GetInvoiceRequest) returns (GetInvoiceResponse);

    // Return chunks of a rendered PDF for a given UID. If the invoice is
    // sealed, the stored PDF will be returned, otherwise a PDF will be
    // rendered on the fly.
    rpc RenderInvoice(RenderInvoiceRequest) returns (stream RenderInvoiceResponse);

    // Seal invoice, ie. assign it a sequential ID and render it to an
    // immutable PDF for audit purposes.
    rpc SealInvoice(SealInvoiceRequest) returns (SealInvoiceResponse);

    // Return a summarized detail of invoice data for a given filter.
    rpc GetInvoices(GetInvoicesRequest) returns (stream GetInvoicesResponse);
}