{ "openapi": "3.1.0", "info": { "title": "ContaFlow API", "version": "1.0.0", "description": "API public pentru integrări (marketplace-uri, magazine online, alte soft-uri). Autentificare cu chei API per firmă. Datele sunt izolate pe firma cheii." }, "servers": [ { "url": "/api/v1", "description": "Suprafața publică v1" } ], "security": [ { "cheieApi": [] } ], "tags": [ { "name": "Parteneri", "description": "Clienți și furnizori" }, { "name": "Facturi", "description": "Facturi emise/primite, postare, e-Factura XML" }, { "name": "Trezorerie", "description": "Încasări și plăți" }, { "name": "Note", "description": "Note contabile" }, { "name": "Rapoarte", "description": "Balanță, situații, registre, TVA (citire)" }, { "name": "Integrări", "description": "Conectori (eMAG etc.)" } ], "components": { "securitySchemes": { "cheieApi": { "type": "http", "scheme": "bearer", "description": "Cheie API per firmă: `Authorization: Bearer cf_live__`. Se generează din Setări firmă → Chei API (nivel citire sau citire+scriere)." } }, "parameters": { "Idempotency": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Pe scrieri: reluarea aceleiași chei întoarce răspunsul original, fără re-execuție." } }, "schemas": { "Eroare": { "type": "object", "properties": { "eroare": { "type": "object", "properties": { "cod": { "type": "string" }, "mesaj": { "type": "string" } } } } }, "LinieFactura": { "type": "object", "required": [ "descriere", "cantitate", "pretUnitar", "cotaTVA" ], "properties": { "descriere": { "type": "string" }, "cantitate": { "type": "number" }, "pretUnitar": { "type": "number", "description": "Preț unitar net (lei)" }, "cotaTVA": { "type": "integer", "description": "ex: 19, 9, 5, 0" } } }, "PartenerInput": { "type": "object", "required": [ "denumire" ], "properties": { "denumire": { "type": "string" }, "tip": { "type": "string", "enum": [ "CLIENT", "FURNIZOR", "AMBELE" ], "default": "AMBELE" }, "cui": { "type": "string" }, "adresa": { "type": "string" }, "referintaExterna": { "type": "string", "description": "ID extern (ex: ID client din alt sistem)" } } }, "FacturaInput": { "type": "object", "required": [ "partenerId", "data", "linii" ], "properties": { "partenerId": { "type": "string" }, "data": { "type": "string", "format": "date", "example": "2026-02-05" }, "tip": { "type": "string", "enum": [ "EMISA", "PRIMITA" ], "default": "EMISA" }, "serie": { "type": "string" }, "referintaExterna": { "type": "string" }, "linii": { "type": "array", "items": { "$ref": "#/components/schemas/LinieFactura" }, "minItems": 1 } } }, "OperatiuneInput": { "type": "object", "required": [ "tip", "modalitate", "partenerId", "data", "suma" ], "properties": { "tip": { "type": "string", "enum": [ "INCASARE", "PLATA" ] }, "modalitate": { "type": "string", "enum": [ "BANCA", "CASA" ] }, "partenerId": { "type": "string" }, "data": { "type": "string", "format": "date" }, "suma": { "type": "number" }, "facturaId": { "type": "string" }, "referintaExterna": { "type": "string" } } }, "LinieNota": { "type": "object", "required": [ "contContabilId" ], "properties": { "contContabilId": { "type": "string" }, "debit": { "type": "number", "default": 0 }, "credit": { "type": "number", "default": 0 }, "partenerId": { "type": "string" } } }, "NotaInput": { "type": "object", "required": [ "perioadaId", "dataInregistrare", "explicatie", "linii" ], "properties": { "perioadaId": { "type": "string" }, "dataInregistrare": { "type": "string", "format": "date" }, "explicatie": { "type": "string" }, "referintaExterna": { "type": "string" }, "linii": { "type": "array", "items": { "$ref": "#/components/schemas/LinieNota" }, "minItems": 2 } } }, "ComandaEmag": { "type": "object", "required": [ "id", "data", "cumparator", "produse" ], "properties": { "id": { "type": "string", "description": "ID comandă eMAG → referintaExterna" }, "data": { "type": "string", "format": "date" }, "cumparator": { "type": "object", "required": [ "nume" ], "properties": { "nume": { "type": "string" }, "cui": { "type": "string" }, "adresa": { "type": "string" } } }, "produse": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "nume", "cantitate", "pretUnitar", "cotaTVA" ], "properties": { "nume": { "type": "string" }, "cantitate": { "type": "number" }, "pretUnitar": { "type": "number" }, "cotaTVA": { "type": "integer" }, "pretCuTVA": { "type": "boolean", "description": "true ⇒ pretUnitar include TVA (se convertește la net)" } } } } } } } }, "paths": { "/parteneri": { "get": { "tags": [ "Parteneri" ], "summary": "Listează partenerii", "parameters": [ { "name": "referintaExterna", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Listă parteneri" } } }, "post": { "tags": [ "Parteneri" ], "summary": "Creează un partener", "parameters": [ { "$ref": "#/components/parameters/Idempotency" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartenerInput" } } } }, "responses": { "201": { "description": "Partener creat" }, "403": { "description": "Cheie fără drept de scriere" } } } }, "/parteneri/{id}": { "get": { "tags": [ "Parteneri" ], "summary": "Detalii partener", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Partener" }, "404": { "description": "Inexistent" } } } }, "/facturi": { "get": { "tags": [ "Facturi" ], "summary": "Listează facturile", "parameters": [ { "name": "tip", "in": "query", "schema": { "type": "string", "enum": [ "EMISA", "PRIMITA" ] } }, { "name": "referintaExterna", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Listă facturi" } } }, "post": { "tags": [ "Facturi" ], "summary": "Creează o factură", "parameters": [ { "$ref": "#/components/parameters/Idempotency" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacturaInput" } } } }, "responses": { "201": { "description": "Factură creată" } } } }, "/facturi/{id}": { "get": { "tags": [ "Facturi" ], "summary": "Detalii factură", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Factură" }, "404": { "description": "Inexistentă" } } } }, "/facturi/{id}/postare": { "post": { "tags": [ "Facturi" ], "summary": "Postează factura în contabilitate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Postată" }, "422": { "description": "Regulă de business (ex: perioadă indisponibilă)" } } } }, "/facturi/{id}/xml": { "get": { "tags": [ "Facturi" ], "summary": "XML e-Factura (UBL, doar facturi emise)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "XML UBL", "content": { "application/xml": {} } }, "404": { "description": "Inexistentă" }, "422": { "description": "Nu e factură emisă" } } } }, "/trezorerie": { "get": { "tags": [ "Trezorerie" ], "summary": "Listează operațiunile", "parameters": [ { "name": "referintaExterna", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Listă operațiuni" } } }, "post": { "tags": [ "Trezorerie" ], "summary": "Înregistrează o încasare/plată", "parameters": [ { "$ref": "#/components/parameters/Idempotency" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatiuneInput" } } } }, "responses": { "201": { "description": "Operațiune înregistrată" } } } }, "/note": { "get": { "tags": [ "Note" ], "summary": "Listează notele", "parameters": [ { "name": "referintaExterna", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Listă note" } } }, "post": { "tags": [ "Note" ], "summary": "Creează o ciornă de notă", "parameters": [ { "$ref": "#/components/parameters/Idempotency" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotaInput" } } } }, "responses": { "201": { "description": "Notă creată (ciornă)" } } } }, "/note/{id}": { "get": { "tags": [ "Note" ], "summary": "Detalii notă", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Notă" }, "404": { "description": "Inexistentă" } } } }, "/note/{id}/postare": { "post": { "tags": [ "Note" ], "summary": "Postează nota", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Postată" }, "422": { "description": "Regulă de business (ex: notă neechilibrată)" } } } }, "/balanta": { "get": { "tags": [ "Rapoarte" ], "summary": "Balanța de verificare", "parameters": [ { "name": "exercitiuId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "luna", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Balanță" } } } }, "/situatii": { "get": { "tags": [ "Rapoarte" ], "summary": "Situații financiare (bilanț + CPP + F40)", "parameters": [ { "name": "exercitiuId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "nrSalariati", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Situații" } } } }, "/registre/jurnal": { "get": { "tags": [ "Rapoarte" ], "summary": "Registrul Jurnal", "parameters": [ { "name": "exercitiuId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Jurnal" } } } }, "/registre/cartea-mare": { "get": { "tags": [ "Rapoarte" ], "summary": "Cartea Mare (fișa unui cont)", "parameters": [ { "name": "exercitiuId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "contId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fișa contului" } } } }, "/registre/inventar": { "get": { "tags": [ "Rapoarte" ], "summary": "Registrul Inventar", "parameters": [ { "name": "exercitiuId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inventar" } } } }, "/tva/decont": { "get": { "tags": [ "Rapoarte" ], "summary": "Decont TVA (sumar)", "parameters": [ { "name": "an", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "luna", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Decont" } } } }, "/tva/d300": { "get": { "tags": [ "Rapoarte" ], "summary": "Decont D300 (defalcat pe cote)", "parameters": [ { "name": "an", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "luna", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "D300" } } } }, "/tva/d394": { "get": { "tags": [ "Rapoarte" ], "summary": "Declarație D394 (pe partener)", "parameters": [ { "name": "an", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "luna", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "D394" } } } }, "/integrari/emag": { "post": { "tags": [ "Integrări" ], "summary": "Importă comenzi eMAG ca facturi", "description": "Mapează comenzi normalizate → facturi (partener hibrid, dedup pe ID comandă, postare best-effort). Idempotent la re-import.", "parameters": [ { "$ref": "#/components/parameters/Idempotency" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "comenzi" ], "properties": { "comenzi": { "type": "array", "items": { "$ref": "#/components/schemas/ComandaEmag" }, "minItems": 1 } } } } } }, "responses": { "200": { "description": "Rezultate per comandă (importata/postata/duplicat/eroare)" } } } } } }