EFRIX

Developer Guide

Developer Guide

A step-by-step guide to integrating EFRIX into your application.

1. Create an Account

  1. Visit the EFRIX Developer Portal
  2. Click Get Started and create an account
  3. Verify your email address
  4. Complete your business profile

2. Get Your API Keys

  1. Navigate to Dashboard → Settings → API Keys

  2. You'll see two environments:

    • Sandbox - For testing (no real URA submissions)
    • Production - For live transactions

  3. Click Generate Keys for the environment you need

  4. Copy your credentials:

    • API Key: efrix_test_abc123...
    • API Secret: sk_test_xyz789...

⚠️ Warning: Never expose your API Secret in client-side code. Always make API calls from your server.

3. Make Your First API Call

Test Connection

curl -X GET https://gateway.tarifix.xtellar.app/efrix/v1/sandbox/taxpayer/info \
  -H "X-EFRIX-API-Key: efrix_test_abc123" \
  -H "X-EFRIX-API-Secret: sk_test_xyz789"

Expected Response:

{
  "success": true,
  "data": {
    "tin": "1000000001",
    "business_name": "Your Test Business",
    "status": "ACTIVE"
  }
}

4. Create Your First Invoice

curl -X POST https://gateway.tarifix.xtellar.app/efrix/v1/sandbox/invoices \
  -H "X-EFRIX-API-Key: efrix_test_abc123" \
  -H "X-EFRIX-API-Secret: sk_test_xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer": {
      "tin": "1000000002",
      "legal_name": "Test Customer Ltd"
    },
    "items": [
      {
        "name": "Test Product",
        "quantity": 1,
        "unit_price": 100000,
        "tax_category": "STANDARD"
      }
    ],
    "payment_mode": "CASH"
  }'

Success Response:

{
  "success": true,
  "data": {
    "id": "inv_test123",
    "fiscal_document_number": "TEST-FIS-001",
    "ura_verification_code": "TESTCODE123",
    "qr_code_url": "https://api.tarifix.xtellar.app/efrix/qr/inv_test123.png",
    "status": "SUBMITTED",
    "totals": {
      "subtotal": 100000,
      "tax_amount": 18000,
      "total": 118000
    }
  }
}

5. Integration Code Examples

JavaScript/Node.js

const axios = require('axios');

const efrix = axios.create({
  baseURL: 'https://api.tarifix.xtellar.app/efrix/v1',
  headers: {
    'X-EFRIX-API-Key': process.env.EFRIX_API_KEY,
    'X-EFRIX-API-Secret': process.env.EFRIX_API_SECRET,
    'Content-Type': 'application/json'
  }
});

// Create an invoice
async function createInvoice(invoiceData) {
  try {
    const response = await efrix.post('/invoices', invoiceData);
    return response.data;
  } catch (error) {
    console.error('EFRIX Error:', error.response?.data);
    throw error;
  }
}

// Usage
const invoice = await createInvoice({
  buyer: { tin: '1000000002', legal_name: 'Customer Ltd' },
  items: [{ name: 'Product', quantity: 1, unit_price: 50000, tax_category: 'STANDARD' }],
  payment_mode: 'CASH'
});

console.log('Fiscal Number:', invoice.data.fiscal_document_number);

Python

import requests
import os

class EfrixClient:
    def __init__(self):
        self.base_url = 'https://api.tarifix.xtellar.app/efrix/v1'
        self.headers = {
            'X-EFRIX-API-Key': os.environ['EFRIX_API_KEY'],
            'X-EFRIX-API-Secret': os.environ['EFRIX_API_SECRET'],
            'Content-Type': 'application/json'
        }
    
    def create_invoice(self, data):
        response = requests.post(
            f'{self.base_url}/invoices',
            json=data,
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

# Usage
client = EfrixClient()
invoice = client.create_invoice({
    'buyer': {'tin': '1000000002', 'legal_name': 'Customer Ltd'},
    'items': [{'name': 'Product', 'quantity': 1, 'unit_price': 50000, 'tax_category': 'STANDARD'}],
    'payment_mode': 'CASH'
})
print(f"Fiscal Number: {invoice['data']['fiscal_document_number']}")

6. Set Up Webhooks

Receive real-time notifications when invoice statuses change.

  1. Go to Dashboard → Settings → Webhooks
  2. Click Add Endpoint
  3. Enter your URL: https://your-app.com/webhooks/efrix
  4. Select events to receive:
    • invoice.created
    • invoice.submitted
    • invoice.failed
  5. Copy the Webhook Secret for verification

Verifying Webhooks

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express.js handler
app.post('/webhooks/efrix', (req, res) => {
  const signature = req.headers['x-efrix-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  const { event, data } = req.body;
  console.log(`Received ${event}:`, data);
  
  res.status(200).send('OK');
});

7. Go to Production Checklist

Before switching to production:

  • All test invoices processed successfully in sandbox
  • Error handling implemented for all API calls
  • Webhook endpoints tested and verified
  • API keys stored securely (environment variables)
  • Rate limiting handling in place
  • Logging implemented for debugging

Switch to Production:

  1. Go to Dashboard → Settings → API Keys
  2. Generate Production keys
  3. Update your environment variables
  4. Remove /sandbox from API URL

Common Issues

Invalid TIN Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid TIN format",
    "details": { "field": "buyer.tin" }
  }
}

Solution: TIN must be exactly 10 digits.

Rate Limit Exceeded

{
  "error": {
    "code": "RATE_LIMIT_ERROR",
    "message": "Too many requests"
  }
}

Solution: Implement exponential backoff and check X-RateLimit-* headers.

Need Help?

Previous
Architecture
Next
SDK Documentation