@easyflow/javascript-sdk
Version:
Enterprise-grade JavaScript SDK for Easyflow payment processing platform with enhanced credit card validation, comprehensive TypeScript definitions, and Lovable.dev integration support
476 lines (406 loc) • 11 kB
Markdown
# Easyflow SDK - Data Structures Reference
This document provides detailed information about the data structures expected by the Easyflow JavaScript SDK.
## Table of Contents
1. [Customer Data Structure](#customer-data-structure)
2. [Payment Data Structure](#payment-data-structure)
3. [Order Data Structure](#order-data-structure)
4. [Credit Card Data Structure](#credit-card-data-structure)
5. [Address Data Structure](#address-data-structure)
6. [Phone Data Structure](#phone-data-structure)
7. [Document Data Structure](#document-data-structure)
8. [Item Data Structure](#item-data-structure)
9. [Metadata Structure](#metadata-structure)
10. [Error Response Structure](#error-response-structure)
## Customer Data Structure
### Required Fields
```typescript
interface Customer {
name: string // Full name (min: 2, max: 100 characters)
email: string // Valid email address
document: Document // CPF or CNPJ information
}
```
### Optional Fields
```typescript
interface CustomerExtended extends Customer {
phone?: Phone // Phone number information
address?: Address // Billing address
deliveryAddress?: Address // Delivery address (if different from billing)
metadata?: Metadata[] // Additional customer information
}
```
### Example
```javascript
const customer = {
name: 'João Silva Santos',
email: 'joao.silva@exemplo.com',
document: {
type: 'CPF',
number: '12345678901',
},
phone: {
areaCode: '+55',
ddd: '11',
number: '9988776655',
isMobile: true,
},
address: {
zipCode: '01234567',
street: 'Rua das Flores',
complement: 'Apto 101',
neighborhood: 'Centro',
city: 'São Paulo',
state: 'SP',
number: '123',
},
}
```
## Payment Data Structure
### Credit Card Payment
```typescript
interface CreditCardPayment {
method: 'credit-card'
numberInstallments: number // 1-12 installments
valueInCents?: number // Required for charge(), optional for placeOrder()
creditCard: {
cardId?: string // Saved card ID
token?: string // Encrypted card token
last4Numbers?: string // Last 4 digits
holderName?: string // Card holder name
expiresAtMonth?: string // Expiration month (01-12)
expiresAtYear?: string // Expiration year (YYYY)
flag?: string // Card brand (visa, mastercard, etc.)
}
}
```
### PIX Payment
```typescript
interface PixPayment {
method: 'pix'
numberInstallments: number // Always 1 for PIX
valueInCents?: number // Required for charge(), optional for placeOrder()
}
```
### Bank Billet Payment
```typescript
interface BankBilletPayment {
method: 'bank-billet'
numberInstallments: number // Always 1 for bank billet
valueInCents?: number // Required for charge(), optional for placeOrder()
}
```
### Example
```javascript
const payments = [
{
method: 'credit-card',
numberInstallments: 6,
creditCard: {
token: 'transactional-token-123',
cardId: 'saved-card-123',
last4Numbers: '1234',
holderName: 'JOAO SILVA SANTOS',
expiresAtMonth: '12',
expiresAtYear: '2025',
flag: 'visa',
},
},
{
method: 'pix',
numberInstallments: 1,
},
]
```
## Order Data Structure
### Buyer Information
```typescript
interface Buyer {
customerId?: string // Existing customer ID (optional)
name: string // Full name
email: string // Valid email
document: Document // CPF or CNPJ
phone: Phone // Phone number
address: Address // Billing address
}
```
### Complete Order Structure
```typescript
interface OrderData {
buyer: Buyer
payments: Payment[]
offerItems?: OfferItem[] // For placeOrder()
items?: Item[] // For charge()
metadata?: Metadata[]
}
```
### Example
```javascript
const orderData = {
buyer: {
customerId: 'existing-customer-123',
name: 'João Silva Santos',
email: 'joao.silva@exemplo.com',
document: {
type: 'CPF',
number: '12345678901',
},
phone: {
areaCode: '+55',
ddd: '11',
number: '9988776655',
isMobile: true,
},
address: {
zipCode: '01234567',
street: 'Rua das Flores',
complement: 'Apto 101',
neighborhood: 'Centro',
city: 'São Paulo',
state: 'SP',
number: '123',
},
},
payments: [
{
method: 'credit-card',
numberInstallments: 6,
creditCard: {
cardId: 'saved-card-123',
},
},
],
offerItems: [
{
offerItemId: 'offer-item-123',
quantity: 1,
},
],
metadata: [
{
key: 'source',
value: 'website',
},
],
}
```
## Credit Card Data Structure
### For Encryption
```typescript
interface CreditCardData {
cardNumber: string // 13-19 digits
cvv: string // 3-4 digits
month: string // 01-12
year: string // YYYY format
holderName: string // Card holder name
}
```
### Example
```javascript
const creditCardData = {
cardNumber: '4111111111111111',
cvv: '123',
month: '12',
year: '2025',
holderName: 'JOAO SILVA SANTOS',
}
```
## Address Data Structure
```typescript
interface Address {
zipCode: string // Brazilian ZIP code (8 digits)
street: string // Street name
complement?: string // Apartment, building, etc.
neighborhood: string // Neighborhood name
city: string // City name
state: string // State abbreviation (SP, RJ, MG, etc.)
number: string // House/building number
}
```
### Example
```javascript
const address = {
zipCode: '01234567',
street: 'Rua das Flores',
complement: 'Apto 101',
neighborhood: 'Centro',
city: 'São Paulo',
state: 'SP',
number: '123',
}
```
## Phone Data Structure
```typescript
interface Phone {
areaCode: string // Country code (+55 for Brazil)
ddd: string // Area code (11, 21, 31, etc.)
number: string // Phone number (8-9 digits)
isMobile: boolean // Whether it's a mobile number
}
```
### Example
```javascript
const phone = {
areaCode: '+55',
ddd: '11',
number: '9988776655',
isMobile: true,
}
```
## Document Data Structure
```typescript
interface Document {
type: 'CPF' | 'CNPJ' // Document type
number: string // Document number (CPF: 11 digits, CNPJ: 14 digits)
}
```
### Example
```javascript
const cpfDocument = {
type: 'CPF',
number: '12345678901',
}
const cnpjDocument = {
type: 'CNPJ',
number: '12345678000195',
}
```
## Item Data Structure
### For charge() method
```typescript
interface Item {
name: string // Product name
description: string // Product description
quantity: number // Quantity (positive integer)
priceInCents: number // Price in cents (positive integer)
}
```
### Example
```javascript
const items = [
{
name: 'Carregador de Celular',
description: 'Carregador de celular com cabo USB-C',
quantity: 1,
priceInCents: 5000, // R$ 50,00
},
{
name: 'Cabo USB-C',
description: 'Cabo USB-C de alta velocidade',
quantity: 2,
priceInCents: 1500, // R$ 15,00 cada
},
]
```
## Metadata Structure
```typescript
interface Metadata {
key: string // Metadata key
value: string // Metadata value
}
```
### Example
```javascript
const metadata = [
{
key: 'source',
value: 'website',
},
{
key: 'campaign',
value: 'black-friday-2024',
},
{
key: 'user_id',
value: 'user-12345',
},
]
```
## Error Response Structure
### Standard Error Format
```typescript
interface ErrorResponse {
error: {
code: string // Error code
message: string // Human-readable error message
details?: string // Additional error details
field?: string // Field that caused the error
value?: any // Value that caused the error
}
timestamp: string // ISO timestamp
requestId?: string // Unique request identifier
}
```
### Common Error Codes
| Code | Description | HTTP Status |
|--------------------------|--------------------------|-------------|
| `VALIDATION_ERROR` | Data validation failed | 400 |
| `SECURITY_ERROR` | Security violation | 403 |
| `RATE_LIMIT_EXCEEDED` | Too many requests | 429 |
| `NETWORK_ERROR` | Network/API error | 500+ |
| `BUSINESS_ID_INVALID` | Invalid business ID | 400 |
| `OFFER_NOT_FOUND` | Offer not found | 404 |
| `CUSTOMER_NOT_FOUND` | Customer not found | 404 |
| `PAYMENT_METHOD_INVALID` | Invalid payment method | 400 |
| `CREDIT_CARD_INVALID` | Invalid credit card data | 400 |
### Example Error Response
```javascript
{
"error"
:
{
"code"
:
"VALIDATION_ERROR",
"message"
:
"Invalid email format",
"details"
:
"Email must be a valid email address",
"field"
:
"email",
"value"
:
"invalid-email"
}
,
"timestamp"
:
"2024-01-15T10:30:00.000Z",
"requestId"
:
"req-12345-abcde"
}
```
## Validation Rules
### String Lengths
- **Name**: 2-100 characters
- **Email**: 5-254 characters
- **Street**: 5-200 characters
- **City**: 2-100 characters
- **State**: 2 characters (Brazilian states)
- **ZIP Code**: 8 characters (Brazilian format)
### Numeric Ranges
- **Phone DDD**: 11-99 (Brazilian area codes)
- **Phone Number**: 8-9 digits
- **Installments**: 1-12 for credit cards, 1 for PIX/bank billet
- **Price**: Positive integer in cents
- **Quantity**: Positive integer
### Required vs Optional
- **Required for all operations**: name, email, document
- **Required for shipping**: address
- **Required for contact**: phone
- **Required for payments**: payment method and details
- **Optional**: complement, metadata, deliveryAddress
## Best Practices
1. **Always validate data** before sending to the SDK
2. **Use proper error handling** to catch and display validation errors
3. **Sanitize user input** to prevent XSS attacks
4. **Store sensitive data securely** (never log credit card numbers)
5. **Handle rate limiting** gracefully with exponential backoff
6. **Use metadata** to track order sources and campaigns
7. **Implement proper logging** for debugging and monitoring
8. **Test with real data** in development environment
9. **Follow Brazilian data regulations** (LGPD compliance)
10. **Use HTTPS** in production environments