Quickstart

Create your first invoice through the Gesvision API in under 5 minutes.

Prerequisites

• A Gesvision account with API access (request one here)
• A valid JWT token (see Authentication)
• curl, Postman, Insomnia, or any HTTP client

Step 1 — Authenticate

curl -X POST https://app.gesvision.com/Gesvision/rest/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "api_user", "password": "your_password"}'

Save the returned token:

export TOKEN="eyJhbGciOiJIUzI1NiIs..."

Step 2 — Create an invoice

curl -X POST https://app.gesvision.com/Gesvision/rest/api/v1/invoices \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "counterpartyId": 42,
    "companyId": 1,
    "branchId": 1,
    "series": "A",
    "currencyCode": "EUR",
    "vatIndicator": "INCLUDED",
    "issued": false,
    "lines": [
      {
        "productId": 1024,
        "quantity": 2,
        "unitPrice": 49.90,
        "vatTypeId": 1
      }
    ]
  }'

The API returns the created invoice with all server-computed fields:

{
  "id": 5001,
  "version": 0,
  "code": "A-1234",
  "status": "DRAFT",
  "counterpartyId": 42,
  "counterpartyName": "Óptica Central S.L.",
  "grossAmount": 99.80,
  "discountAmount": 0.00,
  "netAmount": 82.48,
  "vatAmount": 17.32,
  "total": 99.80,
  "totalPaid": 0.00,
  "lines": [ ... ],
  "createdAt": "2026-02-24T10:30:00Z"
}

tip

The counterpartyId, companyId, branchId, productId and vatTypeId values must match existing records in your Gesvision instance. Check them in the Gesvision application or via the list endpoints.

Step 3 — Register a payment

curl -X POST https://app.gesvision.com/Gesvision/rest/api/v1/payments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": 5001,
    "amount": 99.80,
    "paymentMethodId": 1
  }'

Step 4 — Verify the invoice

curl https://app.gesvision.com/Gesvision/rest/api/v1/invoices/5001 \
  -H "Authorization: Bearer $TOKEN"

Check that totalPaid now matches total. The invoice is fully paid.

Step 5 — Update the invoice (optional)

To update, send a PUT request with the If-Match header set to the current version number (see Optimistic Locking):

curl -X PUT https://app.gesvision.com/Gesvision/rest/api/v1/invoices/5001 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: 0" \
  -d '{
    "counterpartyId": 42,
    "companyId": 1,
    "branchId": 1,
    "series": "A",
    "externalRef": "PO-2026-789",
    "lines": [
      {
        "productId": 1024,
        "quantity": 3,
        "unitPrice": 49.90,
        "vatTypeId": 1
      }
    ]
  }'

Common integration scenarios

Scenario	Endpoints used
E-commerce sync	Create invoices + payments when orders are placed online
Accounting export	List invoices with modifiedAfter for incremental sync
CRM integration	Update customer data (email, phone, address)
Subscription billing	Create recurring orders with subscription: true
Insurance claims	Create invoices with insurer fields and credit notes for adjustments

Next steps

• Browse the full API v2 Reference (or v1 (legacy))
• Learn about Pagination for listing endpoints
• Understand Error Handling for robust integrations
• Read about Optimistic Locking for safe concurrent updates