Transactions API Reference

This comprehensive guide covers everything you need to know about using the /api/guardian/v1/transactions/create endpoint to submit VAT transactions to the Guardian system.

Overview

The Guardian Transactions API allows you to submit individual VAT transactions for processing and compliance validation. Each transaction represents a single invoice or business transaction that needs to be reported for VAT purposes.

Endpoint: POST /api/guardian/v1/transactions/

Prerequisites

Before using this endpoint, ensure you have:

1. Authentication Token: A valid Bearer token for API access
2. Entity Jurisdiction ID: Your registered entity jurisdiction UUID
3. Transaction Type ID: The appropriate transaction type for your use case

Request Structure

Headers

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Request Body Schema

{
  "entity_jurisdiction": "string (uuid, required)",
  "invoice_number": "string (required, max 255 characters)",
  "invoice_date": "string (date, required, format: YYYY-MM-DD)",
  "partner_name": "string (required, max 255 characters)",
  "partner_country": "string (required, ISO 3166-1 alpha-2 code)",
  "vat_number": "string (optional, max 255 characters)",
  "net": "string (decimal, required)",
  "vat": "string (decimal, required)",
  "gross": "string (decimal, required)",
  "vat_rate": "string (decimal, required)",
  "vat_rate_type": "string (required)",
  "currency": "string (required, ISO 4217 code)",
  "reporting_period": "string (date, required, format: YYYY-MM-DD)",
  "transaction_type_id": "string (uuid, required)",
  "source": "string (required)"
}

Field Descriptions

Field	Type	Required	Description	Example
entity_jurisdiction	UUID	✅	Your registered entity jurisdiction ID	ej123456-7890-abcd-ef12-34567890abcd
invoice_number	String	✅	Unique invoice reference (max 255 chars)	INV-2025-001
invoice_date	Date	✅	Invoice date in YYYY-MM-DD format	2025-01-15
partner_name	String	✅	Customer or supplier name (max 255 chars)	German Customer GmbH
partner_country	String	✅	ISO 3166-1 alpha-2 country code	DE
vat_number	String	❌	Partner's VAT number (max 255 chars)	DE987654321
net	Decimal	✅	Net amount (excluding VAT)	1000.00
vat	Decimal	✅	VAT amount	190.00
gross	Decimal	✅	Gross amount (including VAT)	1190.00
vat_rate	Decimal	✅	VAT rate percentage	19.00
vat_rate_type	String	✅	Type of VAT rate applied	standard
currency	String	✅	ISO 4217 currency code	EUR
reporting_period	Date	✅	Reporting period start date	2025-01-01
transaction_type_id	UUID	✅	Transaction type identifier	tt123456-7890-abcd-ef12-34567890abcd
source	String	✅	Source system identifier	tax_engine_api

VAT Rate Types

Type	Description	Use Case
standard	Standard VAT rate	Most common transactions
reduced	Reduced VAT rate	Books, food, medical supplies
zero_rated	Zero-rated supplies	Intra-EU supplies, exports
exempt	VAT-exempt supplies	Financial services, insurance

Transaction Types

Common transaction types and their use cases:

Type	ID	Description
B2B Sales	tt-b2b-sales-001	Business-to-business sales within EU
B2C Sales	tt-b2c-sales-001	Business-to-consumer sales within EU
Intra-EU Supplies	tt-intra-eu-001	Zero-rated intra-EU supplies
Import Services	tt-import-services-001	Services imported from outside EU

Note: To get the complete list of available transaction types, use:

curl -X GET https://api.abacus.com/api/guardian/v1/transaction-types/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Requests

1. Standard B2B Transaction (Germany)

curl -X POST https://api.abacus.com/api/guardian/v1/transactions/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_jurisdiction": "ej123456-7890-abcd-ef12-34567890abcd",
    "invoice_number": "INV-2025-001",
    "invoice_date": "2025-01-15",
    "partner_name": "German Customer GmbH",
    "partner_country": "DE",
    "vat_number": "DE987654321",
    "net": "1000.00",
    "vat": "190.00",
    "gross": "1190.00",
    "vat_rate": "19.00",
    "vat_rate_type": "standard",
    "currency": "EUR",
    "reporting_period": "2025-01-01",
    "transaction_type_id": "tt-b2b-sales-001",
    "source": "tax_engine_api"
  }'

2. Intra-EU Supply (Zero-rated)

curl -X POST https://api.abacus.com/api/guardian/v1/transactions/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_jurisdiction": "ej123456-7890-abcd-ef12-34567890abcd",
    "invoice_number": "INTRA-EU-001",
    "invoice_date": "2025-01-20",
    "partner_name": "Amsterdam B.V.",
    "partner_country": "NL",
    "vat_number": "NL123456789B01",
    "net": "2000.00",
    "vat": "0.00",
    "gross": "2000.00",
    "vat_rate": "0.00",
    "vat_rate_type": "zero_rated",
    "currency": "EUR",
    "reporting_period": "2025-01-01",
    "transaction_type_id": "tt-intra-eu-001",
    "source": "tax_engine_api"
  }'

3. French B2C Transaction

curl -X POST https://api.abacus.com/api/guardian/v1/transactions/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_jurisdiction": "ej-fr-001-uuid",
    "invoice_number": "FR-INV-2025-001",
    "invoice_date": "2025-01-16",
    "partner_name": "Paris Consumer",
    "partner_country": "FR",
    "net": "500.00",
    "vat": "100.00",
    "gross": "600.00",
    "vat_rate": "20.00",
    "vat_rate_type": "standard",
    "currency": "EUR",
    "reporting_period": "2025-01-01",
    "transaction_type_id": "tt-b2c-sales-001",
    "source": "tax_engine_api"
  }'

Response Format

Successful Response (201 Created)

{
  "id": "t1r2a3n4-s5a6-7890-ctio-n1234567890",
  "entity_jurisdiction": "ej123456-7890-abcd-ef12-34567890abcd",
  "invoice_number": "INV-2025-001",
  "partner_name": "German Customer GmbH",
  "net": "1000.00",
  "vat": "190.00",
  "gross": "1190.00",
  "validity_status": "valid",
  "compliance_status": "valid",
  "committed": true,
  "created_at": "2025-07-02T10:25:00Z"
}

Response Fields

Field	Type	Description
id	UUID	Unique transaction identifier
entity_jurisdiction	UUID	Entity jurisdiction ID
invoice_number	String	Invoice reference number
partner_name	String	Partner name
net	Decimal	Net amount
vat	Decimal	VAT amount
gross	Decimal	Gross amount
validity_status	String	Data validation status (valid, warning, error)
compliance_status	String	Compliance validation status (valid, warning, error)
committed	Boolean	Whether transaction is committed to reporting
created_at	DateTime	Transaction creation timestamp

Status Codes and Error Handling

Success Codes

• 201 Created: Transaction successfully created
• 200 OK: Transaction processed with warnings

Error Codes

• 400 Bad Request: Invalid request data
• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: Insufficient permissions
• 422 Unprocessable Entity: Validation errors
• 500 Internal Server Error: Server error

Common Error Response

{
  "error": "Validation failed",
  "details": {
    "vat_number": ["Invalid VAT number format for country DE"],
    "net": ["Net amount must be positive"],
    "invoice_date": ["Invoice date cannot be in the future"]
  }
}

Validation Rules

Business Logic Validation

1. Amount Consistency: net + vat = gross
2. VAT Calculation: net × (vat_rate / 100) = vat (with tolerance for rounding)
3. Date Validation: Invoice date cannot be in the future
4. VAT Number: Must match the format for the specified country
5. Currency: Must be valid ISO 4217 code
6. Country: Must be valid ISO 3166-1 alpha-2 code

Field Constraints

• Invoice Number: Must be unique per entity jurisdiction
• Decimal Fields: Maximum 2 decimal places
• String Fields: UTF-8 encoding, trimmed whitespace
• Dates: ISO 8601 format (YYYY-MM-DD)

Best Practices

1. Data Quality

• Always validate amounts before submission
• Use consistent decimal precision (2 decimal places)
• Ensure invoice numbers are unique within your system
• Validate VAT numbers using official formats

2. Testing

• Use the sandbox environment for testing
• Test with various transaction types and scenarios
• Validate edge cases (zero-rated, exempt transactions)

Troubleshooting

Common Issues

1. Authentication Errors
   • Verify your API token is valid and not expired
   • Ensure the token has the correct permissions
2. Validation Errors
   • Check that all required fields are provided
   • Verify amount calculations (net + vat = gross)
   • Ensure date formats are correct (YYYY-MM-DD)
3. VAT Number Validation
   • Use the correct format for each country
   • Some countries require specific prefixes
   • VAT numbers are optional but recommended for B2B transactions
4. Transaction Type Issues
   • Ensure you're using a valid transaction type ID
   • Different transaction types have different validation rules
   • Use the transaction types endpoint to get valid options

Getting Help

• Check the API Reference for detailed field specifications
• Review Core Workflows for common patterns
• See Examples for specific use cases
• Contact support for complex integration questions

---