Invoice API Usage Guide

API Version: v1.0
Microservice: XDPeople.Soba.Invoice.WebAPI

---

Overview

The Invoice API is an XDPeople.Soba microservice responsible for complete lifecycle management of sales documents, including:

• 📝 Quotes
• 📦 Orders
• 📄 Proforma Invoices
• 🧾 Sales Invoices
• 💰 Receipts
• ↩️ Credit Notes

Key Features

• ✅ Document creation, update, and query
• ✅ Advanced filters (status, dates, customer, document type)
• ✅ Result pagination
• ✅ JWT authentication
• ✅ Multi-tenancy support
• ✅ Clean Architecture with CQRS pattern
• ✅ Swagger/OpenAPI documentation

---

Technical Information

Base URL

Environment	Base URL	Documentation
Production	https://api.xdsoba.com/invoice/api/v1	Swagger UI

Note

For local development environments, please refer to the internal configuration documentation.

Technologies Used

• .NET 8.0 - Main framework
• MediatR - CQRS pattern implementation
• Entity Framework Core - Data access ORM
• MySQL - Main database
• FluentValidation - Command validation
• JWT Bearer Authentication - Authentication
• Swagger/OpenAPI - API documentation

Health Checks

GET /health

Checks API status (memory, connectivity, etc.)

---

Authentication

The Invoice API uses JWT (JSON Web Token) for authentication.

Obtain JWT Token

To obtain a JWT token, use the Gateway authentication endpoint:

POST https://api.xdsoba.com/gateway/auth/combined-login
Content-Type: application/json

{
  "tenantKey": "XDPT.30010",
  "tenantPassword": "your-tenant-password",
  "userKey": "user@example.com",
  "userPassword": "your-user-password"
}

Use the Token

Add the token to the Authorization header of all requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Authentication in Swagger UI

1. Access the Swagger UI
2. Click the "Authorize" button (🔒)
3. Enter: Bearer <your-jwt-token>
4. Click "Authorize"
5. Close the modal

---

Available Endpoints

1. Create Document

POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}

Description: Creates a new sales document (invoice, quote, order, etc.)

Response Codes:

• 201 Created - Document created successfully
• 400 Bad Request - Invalid data
• 401 Unauthorized - Not authenticated
• 500 Internal Server Error - Internal error

2. Update Document

PUT /api/v1/invoices/{id}
Content-Type: application/json
Authorization: Bearer {token}

Description: Updates an existing document

Response Codes:

• 200 OK - Document updated successfully
• 400 Bad Request - Invalid data or ID mismatch
• 404 Not Found - Document not found
• 409 Conflict - Concurrency conflict
• 500 Internal Server Error - Internal error

3. Get Document by ID

GET /api/v1/invoices/{id}
Authorization: Bearer {token}

Description: Gets the complete details of a document by its ID

Response Codes:

• 200 OK - Document found
• 404 Not Found - Document not found

4. Get Document by Number

GET /api/v1/invoices/{documentTypeId}/{serieId}/{number}
Authorization: Bearer {token}

Description: Gets a document by its type, series, and number

Parameters:

• documentTypeId (int) - Document type ID
• serieId (int) - Series ID
• number (int) - Document number

Response Codes:

• 200 OK - Document found
• 400 Bad Request - Invalid parameters
• 404 Not Found - Document not found

5. List Documents

GET /api/v1/invoices?pageNumber=1&pageSize=10&status=Open&fromDate=2025-01-01&toDate=2025-12-31
Authorization: Bearer {token}

Description: Lists documents with optional filters and pagination

Query Parameters:

• pageNumber (int, default: 1) - Page number
• pageSize (int, default: 10) - Page size
• status (string, optional) - Filter by status (Open/Closed)
• fromDate (DateTime, optional) - Start creation date (format: YYYY-MM-DD)
• toDate (DateTime, optional) - End creation date (format: YYYY-MM-DD)
• entityKeyId (string, optional) - Filter by customer/supplier
• documentTypeId (int, optional) - Filter by document type
• sortBy (string, optional) - Sort by field (date/number/entity/total)
• sortDescending (bool, default: false) - Descending order

Response Codes:

• 200 OK - Document list returned successfully

---

Main Features

1. Sales Document Management

The Invoice API supports all sales document types:

Document Type	Description	Typical Use	Dedicated Guide
Quote	Quote	Commercial proposals	📝 Quotes Guide
Order	Order	Customer orders	📦 Orders Guide
Proforma Invoice	Proforma Invoice	Advance billing	⚠️ In development
Sales Invoice	Sales Invoice	Definitive billing	🧾 Invoices Guide
Receipt	Receipt	Payment voucher	💰 Receipts Guide
Credit Note	Credit Note	Returns/corrections	↩️ Credit Notes Guide

2. Document Header and Lines

Each document is composed of:

• Header: General information (customer, date, totals, etc.)
• Lines (Bodies): Document items (products, quantities, prices, taxes)

3. Customer/Entity Information

Documents can store complete entity information:

• Name/Description
• Tax ID/VAT
• Address, Postal Code, City, State, Country
• Email, Phone

4. Tax Information

Full support for:

• Taxes (VAT) per line
• Second tax rate
• Tax exemption
• Tax region

5. Commercial Information

• Payment mode
• Due date
• Discounts (line and header)
• Commissions
• Document references

6. Logistics Information

For transport documents:

• Loading/unloading location
• Loading/unloading dates
• Carrier
• Warehouses (origin/destination)

7. Document Status

• Open: Document in editing
• Closed: Finalized document

8. Inventory Control

• Stock flow (inbound/outbound)
• Stock behavior
• Origin and destination warehouses

---

Data Models

CreateDocumentHeaderCommand

Required Fields:

{
  "serieId": 1,                    // Series ID
  "documentTypeId": 5,              // Document type ID
  "entityKeyId": "CLI001",          // Customer/supplier ID
  "documentBodies": [               // Document lines
    {
      "itemKeyId": "PROD001",       // Product/item ID
      "quantity": 2.0,              // Quantity
      "retailPrice": 50.00,         // Unit price
      "taxId": 1,                   // Tax ID
      "paymentType": 1,             // Payment type
      "stockFlow": 1,               // Stock flow (1=outbound, -1=inbound)
      "stockBehavior": 1,           // Stock behavior
      "secondTaxId": 0              // Second tax rate
    }
  ]
}

Optional Fields:

{
  "entityDescription": "Example Client, Ltd",
  "entityVat": "PT123456789",
  "entityAddress": "123 Example Street",
  "entityPostalCode": "1000-000",
  "entityCity": "Lisbon",
  "entityState": "Lisbon",
  "entityCountry": "Portugal",
  "entityEmail": "client@example.pt",
  "entityPhone": "210000000",
  "obs": "Document observations",
  "docReference": "PO-2025-001",
  "extraDocReference": "EXTRA-REF",
  "dueDate": "2025-12-31",
  "paymentModeId": 1,
  "paymentTypeId": 1,
  "exemptionCode": "M01",
  "exemptionReason": "Exempt under article X",
  "loadPlaceDescription": "Central Warehouse",
  "unloadPlaceDescription": "Customer Store",
  "loadPlaceDate": "2025-11-28T10:00:00",
  "unloadPlaceDate": "2025-11-28T15:00:00",
  "carrierDescription": "XYZ Carrier",
  "taxRegionId": 1,
  "saleZoneAreaObjectId": 1,
  "guid": "550e8400-e29b-41d4-a716-446655440000"
}

UpdateDocumentCommand

{
  "id": 123,                        // Required: Document ID
  "entityDescription": "New Name",  // Optional
  "obs": "New observation",         // Optional
  "docReference": "NEW-REF",        // Optional
  "extraDocReference": "EXTRA",     // Optional
  "dueDate": "2025-12-31",          // Optional
  "paymentModeId": 2,               // Optional
  "close": true,                    // Optional: Close document
  "documentBodies": [...]           // Optional: New lines
}

---

Usage Examples

Example 1: Create a Simple Invoice

POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "entityDescription": "Example Client, Ltd",
  "entityVat": "PT123456789",
  "obs": "Invoice for order PO-2025-001",
  "docReference": "PO-2025-001",
  "dueDate": "2025-12-31",
  "paymentModeId": 1,
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Product 1",
      "quantity": 2.0,
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 1,
      "stockBehavior": 1,
      "secondTaxId": 0
    }
  ]
}

Response (201 Created):

{
  "id": 123,
  "documentNumber": "FT A/001",
  "entityKeyId": "CLI001",
  "entityDescription": "Example Client, Ltd",
  "total": 190.00,
  "totalTaxes": 43.70,
  "status": "Open",
  "creationDate": "2025-11-28T10:30:00",
  "documentBodies": [...]
}

Example 2: Close a Document

PUT /api/v1/invoices/123
Content-Type: application/json
Authorization: Bearer {token}

{
  "id": 123,
  "close": true
}

Example 3: List Open Documents

GET /api/v1/invoices?status=Open&pageNumber=1&pageSize=20
Authorization: Bearer {token}

---

Error Handling

The Invoice API uses standard HTTP status codes and returns structured error responses.

Status Codes

Code	Description	When It Occurs
200 OK	Success	Successful operation
201 Created	Created	Resource created successfully
400 Bad Request	Invalid request	Validation failed, invalid data
401 Unauthorized	Unauthorized	Invalid or missing token
404 Not Found	Not found	Resource doesn't exist
409 Conflict	Conflict	Concurrency conflict
500 Internal Server Error	Internal error	Unexpected error

Error Structure

{
  "message": "Error description",
  "errors": [
    "Error detail 1",
    "Error detail 2"
  ]
}

---

Best Practices

1. Authentication

• ✅ Always include the JWT token in the Authorization header
• ✅ Renew the token before it expires
• ✅ Store the token securely
• ❌ Don't share tokens between users

2. Document Creation

• ✅ Validate all data before sending
• ✅ Provide clear descriptions for items and entities
• ✅ Include document references (PO, purchase order, etc.)
• ✅ Correctly set taxes per line
• ✅ Verify stock flow (inbound/outbound)
• ❌ Don't create duplicate documents

3. Document Updates

• ✅ Always get the latest version before updating
• ✅ Update only necessary fields
• ✅ Close documents only when finalized
• ❌ Don't update closed documents (create a credit note)

4. Document Queries

• ✅ Use pagination for large lists
• ✅ Apply filters to reduce data volume
• ✅ Use caching when appropriate
• ❌ Don't load all documents without filters

---

Next Steps

• 📝 Quotes Guide - Create and manage quotes
• 📦 Orders Guide - Process customer orders
• 🧾 Invoices Guide - Issue sales invoices
• 💰 Receipts Guide - Register payments
• ↩️ Credit Notes Guide - Process returns

---

Last Updated: December 2, 2025
Document Version: 1.0