Creare factura¶

Descriere - Creare factura¶

Aceasta sectiune este dedicata crearii unei facturi noi
Aceasta operatiune dupa finalizare va returna identificatorul Keez al noii facturi externalId
Nu se poate crea/modifica o factura fara articole, daca nu exista articolul pentru factura, acesta se creaza inaintea facturi: Vezi Creare Articol
Facturile sunt de 2 tipuri:
1. Facturi pentru persoane fizice
2. Facturi pentru persoane juridice
Diferenta dintre facturile PF si PJ o face modul de completare a proprietatii „partner” din modelul de request:
Pentru PJ se va folosi Vezi Model Persoane juridice

Pentru PF se va folosi Vezi Model Persoane fizice

Operatii care se pot realiza dupa ce o factura a fost creata:

Model de utilizare API - Creare factura¶

Asa cum este explicat in zona de Informatii generale utilizare API orice apel catre API se face catre un URL de baza la care apoi se adauga endpoint-ul respectivei operatii

Notă

Verb: POST
Endpoint: /{clientEid}/invoices
Request parameter: {clientEid}
Request body: {data_body}
Returns: externalId
Type of return: String

Atenționare

A se observa parametru {clientEid} si tipul acestuia (path variable)
A se observa parametru {data_body} si tipul acestuia (request body)

Model de request body - Creare factura¶

Request body -ul se creaza in prealabil, inaintea apelului catre API
Acesta va contine informatiile specifice acelei facturi care se vrea a fi creat
Modelul acestui body se regasete in tabelul din Vezi Model Factura
Informatiile obligatorii de completat pentru o factura sunt semnalizate in coloana „Coloana obligatorie” din modelul de mai sus
Formatul de date primit de fiecare parametru in parte este specificat in coloane „Format” din modelul de mai sus

- Model pentru facturi PF:

data_body = {
    "series": "SERIE",
    "documentDate": 20190102,
    "dueDate": 20190102,
    "vatOnCollection": False,
    "currencyCode": "EUR",
    "exchangeRate": 4.82,
    "originalNetAmount": 482,
    "originalNetAmountCurrency": 100,
    "originalVatAmount": 0,
    "originalVatAmountCurrency": 0,
    "netAmount": 482,
    "netAmountCurrency": 100,
    "vatAmount": 0,
    "vatAmountCurrency": 0,
    "grossAmount": 482,
    "grossAmountCurrency": 100,
    "paymentTypeId": 1,
    "partner": {
        "isLegalPerson": False,
        "identificationNumber": "1930912217543",
        "partnerName": "Marian Ion",
        "countryCode": "RO",
        "countryName": "Romania",
        "countyCode": "RO-B",
        "countyName": "Bucuresti",
        "cityName": "Sector 1",
        "addressDetails": "Strada Maria Tanase nr. 1"
    },
    "invoiceDetails": [
        {
            "itemExternalId": "{ID_EXTERN_ARTICOL}",
            "measureUnitId": 1,
            "quantity": 1,
            "unitPrice": 100,
            "originalNetAmount": 482,
            "originalNetAmountCurrency": 100,
            "originalVatAmount": 0,
            "originalVatAmountCurrency": 0,
            "netAmount": 482,
            "netAmountCurrency": 100,
            "vatAmount": 0,
            "vatAmountCurrency": 0,
            "grossAmount": 482,
            "grossAmountCurrency": 100,
        }
    ]
}

- Model pentru facturi PF:

data_body = {
    "series": "SERIE",
    "number": 1,
    "documentDate": 20190102,
    "dueDate": 20190102,
    "vatOnCollection": False,
    "currencyCode": "RON",
    "originalNetAmount": 100,
    "originalNetAmountCurrency": 100,
    "originalVatAmount": 0,
    "originalVatAmountCurrency": 0,
    "netAmount": 100,
    "netAmountCurrency": 100,
    "vatAmount": 0,
    "vatAmountCurrency": 0,
    "grossAmount": 100,
    "grossAmountCurrency": 100,
    "paymentTypeId": 1,
    "partner": {
        "isLegalPerson": true,
        "partnerName": "CENTRUL MEDICAL UNIREA SRL",
        "registrationNumber": "J40/15930/1991",
        "identificationNumber": "5919324",
        "taxAttribute": "RO",
        "countryCode": "RO",
        "countryName": "Romania",
        "countyCode": "RO-B",
        "countyName": "BUCURESTI",
        "cityName": "Sector 1",
        "addressDetails": "PŢA. CHARLES DE GAULLE, NR.15, BL.CLADIREA CHARLES DE GAULLE PLAZA, ET.4 "
    },
    "invoiceDetails": [
        {
            "itemExternalId": "{ID_EXTERN_ARTICOL}",
            "measureUnitId": 1,
            "quantity": 1,
            "unitPrice": 100,
            "originalNetAmount": 100,
            "originalNetAmountCurrency": 100,
            "originalVatAmount": 0,
            "originalVatAmountCurrency": 0,
            "netAmount": 100,
            "netAmountCurrency": 100,
            "vatAmount": 0,
            "vatAmountCurrency": 0,
            "grossAmount": 100,
            "grossAmountCurrency": 120
        }
    ]
}

Notă

Daca exista deja o factura cu o anumita serie, nu mai trebuie completat numarul, acesta se va completa cu urmatorul disponibil Exemplu:

Daca fac prima factura cu seria SRS atunci va trebui sa completez proprietatea „number” cu numarul de inceput al acestei serii (nu trebuie sa fie neparat 1)

Daca exista deja o factura pe seria SRS atunci NU trebuie sa pun proprietatea „number”. Se va completa automat.

Validari - Creare factura¶

La momentul executarii acestul apel se vor verifica/valida urmatoarele:

Daca exista factura
Toate proprietatiile obligatorii trebuie sa fie completate
Seria facturii nu permite spatii
Se verifica daca pentru seria facturii create exista deja un numar generat
Data scadenta nu poate sa fie mai mica decat data facturii
Daca discount-ul este global atunci toate valorile de discount de pe articol trebuie sa fie egale cu cele de pe factura
Daca discount-ul este procentual atunci procentul de discount trebuie completat
Daca discount-ul este valoric atunci procentul de discount nu trebuie sa fie completat
Valoarea discount-ului pentru articol nu poate sa fie mai mare decat valoarea neta a articolului
Procentul de discount pentru articol nu poate sa fie mai mare de 100%
Daca factura are articole care contin accize atunci factura si articolul trebuie sa contina acest calcul
Este obligatorie pentru persoanele fizice completarea adresei sau a CNP-ului

Verificarile si validarile vor arunca (throw) mesaje de eroare sub forma de exceptie (Vezi Model Exceptie) atasate de un cod HTTP error 500. Vezi Coduri eroare posibile

Mod de folosire - Wrapper - Creare factura¶

Daca se foloseste wrapper -ul scris in Python se utilizeaza astfel:

Se preia token-ul pe baza parametrilor specifici
Se apeleaza metoda specifica acestui request POST

token_url = 'https://staging.keez.ro/idp/connect/token'
api_url = f'https://{ENVIRONMENT}.keez.ro/api/v1.0/public-api'

client_eid = '{RECEIVED_CLIENT_EID}'
application_id = '{RECEIVED_APPLICATION_ID}'
secret = '{RECEIVED_SECRET}'

api = KeezPublicApi(app=application, secret=secret, token_url=token_url, api_url=api_url)

data_body = {
    "series": "SERIE",
    "documentDate": 20190102,
    "dueDate": 20190102,
    "vatOnCollection": False,
    "currencyCode": "EUR",
    "exchangeRate": 4.82,
    "originalNetAmount": 482,
    "originalNetAmountCurrency": 100,
    "originalVatAmount": 0,
    "originalVatAmountCurrency": 0,
    "netAmount": 482,
    "netAmountCurrency": 100,
    "vatAmount": 0,
    "vatAmountCurrency": 0,
    "grossAmount": 482,
    "grossAmountCurrency": 100,
    "paymentTypeId": 1,
    "partner": {
        "isLegalPerson": False,
        "identificationNumber": "1930912217543",
        "partnerName": "Marian Ion",
        "countryCode": "RO",
        "countryName": "Romania",
        "countyCode": "RO-B",
        "countyName": "Bucuresti",,
        "cityName": "Sector 1",
        "addressDetails": "Strada Maria Tanase nr. 1"
    },
    "invoiceDetails": [
        {
            "itemExternalId": "{ID_EXTERN_ARTICOL}",
            "measureUnitId": 1,
            "quantity": 1,
            "unitPrice": 100,
            "originalNetAmount": 482,
            "originalNetAmountCurrency": 100,
            "originalVatAmount": 0,
            "originalVatAmountCurrency": 0,
            "netAmount": 482,
            "netAmountCurrency": 100,
            "vatAmount": 0,
            "vatAmountCurrency": 0,
            "grossAmount": 482,
            "grossAmountCurrency": 100,
        }
    ]
}

result = api.create_invoice(client_eid, data_body)

Mod de folosire - Fara Wrapper - Creare factura¶

class InvoiceService:
    def __init__(self):
        token = TokenService()
        self.auth_token = token.generate_token()
        self.token = f'{self.auth_token.get("token_type")} {self.auth_token.get("access_token")}'

        self.client_eid = token.client_eid
        self.api_endpoint = token.api_endpoint

    def createInvoice(self):
        invoice_url = f'{self.api_endpoint}/{self.client_eid}/invoices'

        data_body = {
            "series": "SERIE",
            "documentDate": 20190102,
            "dueDate": 20190102,
            "vatOnCollection": False,
            "currencyCode": "EUR",
            "exchangeRate": 4.82,
            "originalNetAmount": 482,
            "originalNetAmountCurrency": 100,
            "originalVatAmount": 0,
            "originalVatAmountCurrency": 0,
            "netAmount": 482,
            "netAmountCurrency": 100,
            "vatAmount": 0,
            "vatAmountCurrency": 0,
            "grossAmount": 482,
            "grossAmountCurrency": 100,
            "paymentTypeId": 1,
            "partner": {
                "isLegalPerson": False,
                "identificationNumber": "1930912217543",
                "partnerName": "Marian Ion",
                "countryCode": "RO",
                "countryName": "Romania",
                "countyCode": "RO-B",
                "countyName": "Bucuresti",,
                "cityName": "Sector 1",
                "addressDetails": "Strada Maria Tanase nr. 1"
            },
            "invoiceDetails": [
                {
                    "itemExternalId": "{ID_EXTERN_ARTICOL}",
                    "measureUnitId": 1,
                    "quantity": 1,
                    "unitPrice": 100,
                    "originalNetAmount": 482,
                    "originalNetAmountCurrency": 100,
                    "originalVatAmount": 0,
                    "originalVatAmountCurrency": 0,
                    "netAmount": 482,
                    "netAmountCurrency": 100,
                    "vatAmount": 0,
                    "vatAmountCurrency": 0,
                    "grossAmount": 482,
                    "grossAmountCurrency": 100,
                }
            ]
        }

        _req = requests.post(url=invoice_url, headers={'Content-Type': 'application/json', 'Authorization': self.token}, json=data_body)
        return _req.json()


if __name__ == '__main__':
    service = InvoiceService()
    invoice = service.createInvoice()
    print(invoice)

Notă

Clasa TokenService() se gaseste la sectiunea Autorizarea: Vezi Autorizarea