Momentan, serviciul TVA API este in mentenanta.

Documentatie Tehnica Verificare TVA API

Ultima actualizare: 27 Aprilie 2018

Descarca documentatia API

1. Cum functioneaza?

API Verificare TVA furnizeaza din sursele oficiale informatii despre firmele din Romania care aplica TVA, TVA la incasare si Split TVA (plata defalcata TVA). Acesta face interogari punctuale la sursele de informatii oficiale sau de pe serverele VerificareTVA.ro atunci cand sursele oficiale sunt indisponibile si returneaza informatii intr-o forma standardizata. Accesul la API se face pe baza de abonament. Sunt necesare un nume de utilizator si o parola pentru initierea unei interogari. API-ul poate fi integrat si accesat in aplicatii proprii prin adaugarea unui cod in interiorul codului sursa.

2.Fluxul de date

Initial se face o interogare de tip HTTP GET la serverul VerificareTVA.ro impreuna cu key-ul asociat abonamentului, CUI-ul firmei si data tranzactiei (a facturii) pana la care se doresc a fi actualizate datele (aceasta data specifica practic cat de noi sa fie informatiile din adresa si data la care se vor afla informatiile legate de TVA). Daca serverul VerificareTVA.ro detine informatii mai noi decat data specificata in interogarea initiala, atunci informatiile sunt livrate din Cache-ul VerificareTVA.ro. Daca informatiile din Cache-ul VerificareTVA.ro sunt mai vechi decat data specificata sau sunt indisponibile, atunci se vor livra informatii direct de la MFinante.ro. Ulterior, se updateaza si Cache-ul VerificareTVA.ro cu noile informatii. In final, API-ul livreaza informatiile in format JSON.

3. Metoda de acces

Se transmite o interogare de tip HTTP GET la adresa web:

https://www.verificaretva.ro/api/apiv4.aspx

Parametrii pentru metoda GET sunt:

Parametru Tip de data Observatii Descriere
key String [max 255 caractere] Optional Key-ul asociat contului de acces la TVA API (vezi interfata online)
cui String [max 10 caractere] Obligatoriu Codul fiscal al firmei la care se solicita informatiile
data Data [AAAA-LLZZ] Obligatoriu Se specifica data facturii pentru care se doresc informatiile despre starea platitorului de TVA.
bilant String [max 1 caracter] – 0/1 Optional Se specifica daca se doresc a fi incluse in raspuns si date din bilant (1 da, 0 nu)

4. Abonamentul de acces

API-ul poate fi accesat cu un cont de utilizator caruia ii poate fi asociat un abonament platit sau gratuit (pana la 250 interogari / 14 zile / cont). in functie de abonamentul ales, API-ul poate fi accesat pana la o limita maxima de interogari pe luna. Crearea unui cont de utilizator se poate face din pagina:

https://www.verificaretva.ro/inregistrare

5. Tratarea exceptiilor

Urmatoarele erori pot aparea in cazul in care sursele de informatii au fost schimbate, versiunea API-ului este expirata sau abonamentul de acces a expirat sau si-a atins limita maxima lunara

ERROR 001 INVALID RESPONSE Eroare interna
ERROR 002 INVALID CUI CUI-ul transmis nu este valid conform algoritmului de validare
ERROR 003 AUTHENTICATION FAILED Datele de autentificare sunt gresite.
ERROR 004 LIMIT EXCEEDED Abonamentul a expirat sau trebuie upgradat pentru a permite un numar mai mare de interogari. Va rugam sa contactati echipa de suport tehnic.
ERROR 006 INCORRECT DATE Data Tranzactiei este incorecta.
ERROR 007 NON-EXISTENT CUI CUI-ul nu exista
ERROR 008 SOURCES UNAVAILABLE Sursele oficiale de date nu sunt disponibile

6. Interpretarea raspunsului

Daca toti parametrii sunt corecti si nu a intervenit nicio eroare in timpul requestului, API-ul ar trebui sa returneze un raspuns similar cu:

{“Raspuns”:”valid”,”Nume”:”BORG DESIGN SRL”,"CUI”:14837428,”NrInmatr”:”J40/8118/2002”,”Judet”:”BUCURESTI”,”Localitate”:”BUCURESTI”,
”Tip”:”STR.”,”Adresa”:”DEMOCRATIEI”,”Nr”:”Nr.4”,”Actualizat”:”2018-01-14”,”TVA”:true,”TVA_data”:”2002-08-26”, "TVAincasare":false,
”TVAincasare_data”:null,”TVAsplit”:true,”TVAsplit_data”:”2017-10-02”}

Acest raspuns este in format jSON si poate fi citit, de exemplu in .NET, cu JavaScriptSerializer() din Namespace-ul System.Web.Script.Serialization. Informatiile returnate pot fi urmatoarele:

INFORMAtIE TIP DATa EXEMPLU
Raspuns String (6) valid
Nume String (255) BORG DESIGN SRL
CUI Numeric 14837428
NrInmatr String (15) J40/8118/2002
Judet String (75) BUCURESTI
Localitate String (75) BUCURESTI
Tip String (50) Str.
Adresa String (255) Democratiei
Nr String (50) 4
Actualizat Data Data actualizarii informatiilor legate de adresa (cele de mai sus)
TVA Bit true (platitor de TVA) / false (neplatitor de TVA)
TVA_data Data Data devenire platitor de TVA / null
TVAincasare Bit true (platitor de TVA la incasare) / false (neplatitor de TVA la incasare)
TVAincasare_data Data Data devenire platitor de TVA la incasare / null
TVAsplit Bit true (platitor de TVA defalcata) / false (neplatitor de TVA defalcata)
TVAsplit_data Data Data devenire platitor de TVA defalcata / null
Bilant String (max) Date din bilant

ATENTIE:
- cele trei informatii: platitor de TVA, platitor de TVA la incasare si platitor de TVA defalcata sunt returnate in functie de data specificata in request (nu sunt returnate starile din momentul requestului, ci starile pe care le avea firma la data specificata);
- cand se specifica parametrul bilant = 1, se consuma cu o interogare in plus.

7. Alte informatii utile

Istoricul interogarilor poate fi consultat in sectiunea:

https://www.verificaretva.ro/contulmeu/istoric-verificari

Datele furnizate de API pot fi consultate si online prin verificarea punctuala (cautarea de pe site) sau prin verificarea de liste.

8. Istoric versiuni

Nou in versiunea 4:

- Adaugarea starii de SplitTVA (Registru Plati Defalcate TVA)

- Adaugarea datelor de inceput ale starilor de TVA, TVA la incasare si TVA Split

- Modificarea tipului de data de la TVA si TVA la incasare din 0 / 1 in true / false