Contactos y Cuentas Bancarias

{
  "firstName": "Juan",                       // Nombre
  "countrySymbol": "CO",                     // Código de país
  "businessType": "PERSON",                  // PERSON, COMPANY, etc.
  "type": "PERSON"                           // PERSON, BUSINESS, GOVERNMENT, NGO, FOREIGN
}

{
  "lastName": "Pérez",                       // Apellido
  "email": "cliente@ejemplo.com",            // Correo electrónico
  "phone": "+573001234567",                  // Número de teléfono
  "documentType": "CC",                      // Tipo de documento de ID
  "documentNumber": "1234567890",            // Número de documento de ID (requerido si se provee documentType)
  "taxIdType": "NIT",                        // Tipo de ID fiscal (deprecado, usar documentType)
  "taxIdNumber": "900123456",                // Número de ID fiscal (deprecado, usar documentNumber)
  "address": {
    "street": "Calle 123",
    "city": "Bogotá",
    "state": "Cundinamarca",
    "zipCode": "110111",
    "country": "CO"
  }
}

async function createContact(token, orgId, merchantId, contactData) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts`,
    {
      firstName: contactData.firstName,
      lastName: contactData.lastName,               // Opcional
      email: contactData.email,                     // Opcional
      phone: contactData.phone,                     // Opcional
      countrySymbol: contactData.countrySymbol,
      documentType: contactData.documentType,       // Opcional
      documentNumber: contactData.documentNumber,   // Opcional (requerido si se provee documentType)
      businessType: 'PERSON',                       // o 'COMPANY'
      type: 'PERSON'                                // PERSON, BUSINESS, GOVERNMENT, NGO, FOREIGN
    },
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Uso - Crear contacto de cliente
const customer = await createContact(token, orgId, merchantId, {
  firstName: 'Juan',
  lastName: 'Pérez',
  countrySymbol: 'CO',
  email: 'cliente@ejemplo.com',
  phone: '+573001234567',
  documentType: 'CC',
  documentNumber: '1234567890'
});
 
console.log('Contacto creado:', customer.id);

def create_contact(token, org_id, merchant_id, contact_data):
    response = requests.post(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/contacts',
        json={
            'firstName': contact_data['first_name'],
            'lastName': contact_data.get('last_name'),        # Opcional
            'email': contact_data.get('email'),               # Opcional
            'phone': contact_data.get('phone'),               # Opcional
            'countrySymbol': contact_data['country'],
            'documentType': contact_data.get('document_type'),    # Opcional
            'documentNumber': contact_data.get('document_number'),# Opcional (requerido si se provee documentType)
            'businessType': 'PERSON',
            'type': 'PERSON'
        },
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    )
    
    return response.json()
 
# Uso
customer = create_contact(token, org_id, merchant_id, {
    'first_name': 'Juan',
    'last_name': 'Pérez',
    'email': 'cliente@ejemplo.com',
    'phone': '+573001234567',
    'country': 'CO',
    'document_type': 'CC',
    'document_number': '1234567890'
})

curl -X POST 'https://api-sandbox.koywe.com/api/v1/organizations/TU_ORG_ID/merchants/TU_MERCHANT_ID/contacts' \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "Juan",
    "lastName": "Pérez",
    "email": "cliente@ejemplo.com",
    "phone": "+573001234567",
    "countrySymbol": "CO",
    "documentType": "CC",
    "documentNumber": "1234567890",
    "businessType": "PERSON",
    "type": "PERSON"
  }'

{
  "id": "cnt_abc123",
  "firstName": "Juan",
  "lastName": "Pérez",
  "email": "cliente@ejemplo.com",
  "phone": "+573001234567",
  "countrySymbol": "CO",
  "documentType": "CC",
  "documentNumber": "1234567890",
  "businessType": "PERSON",
  "createdAt": "2025-11-13T10:00:00Z",
  "merchantId": "mrc_xyz789"
}

async function addBankAccountToContact(token, orgId, merchantId, contactId, bankData) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts/${contactId}/accounts`,
    {
      name: bankData.name,
      kind: 'BANK',
      isDefault: bankData.isDefault,
      countrySymbol: bankData.country,
      currencySymbol: bankData.currency,
      entity: bankData.entity,           // Requerido para CO, CL. Opcional para otros (auto-deducido)
      accountNumber: bankData.accountNumber,
      type: bankData.type                // Requerido para Colombia: 'SAVINGS' o 'CHECKING'
    },
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Uso - Colombia (entity requerido)
const bankAccountCO = await addBankAccountToContact(token, orgId, merchantId, 'cnt_abc123', {
  name: 'Bancolombia COP',
  isDefault: true,
  country: 'CO',
  currency: 'COP',
  entity: 'BANCOLOMBIA',     // Requerido para Colombia y Chile
  accountNumber: '1234567890',
  type: 'SAVINGS'            // Requerido para Colombia
});
 
// Uso - Perú (entity auto-deducido del CCI)
const bankAccountPE = await addBankAccountToContact(token, orgId, merchantId, 'cnt_def456', {
  name: 'Peru PEN',
  isDefault: false,
  country: 'PE',
  currency: 'PEN',
  accountNumber: '00219100012345678901'  // CCI de 20 dígitos - código banco auto-deducido
});
 
console.log('Cuenta bancaria agregada:', bankAccountCO.id);

def add_bank_account_to_contact(token, org_id, merchant_id, contact_id, bank_data):
    payload = {
        'name': bank_data['name'],
        'kind': 'BANK',
        'isDefault': bank_data['is_default'],
        'countrySymbol': bank_data['country'],
        'currencySymbol': bank_data['currency'],
        'accountNumber': bank_data['account_number']
    }
 
    # entity requerido para CO, CL; opcional para otros
    if bank_data.get('entity'):
        payload['entity'] = bank_data['entity']
 
    # type requerido para Colombia; opcional para otros países (por defecto VIRTUAL)
    if bank_data.get('type'):
        payload['type'] = bank_data['type']
    
    response = requests.post(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/contacts/{contact_id}/accounts',
        json=payload,
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    )
    
    return response.json()
 
# Uso - Colombia (entity requerido)
bank_account_co = add_bank_account_to_contact(token, org_id, merchant_id, 'cnt_abc123', {
    'country': 'CO',
    'currency': 'COP',
    'entity': 'BANCOLOMBIA',      # Requerido para Colombia
    'account_number': '1234567890',
    'type': 'SAVINGS'                # Requerido para Colombia
})
 
# Uso - Chile (entity requerido)
bank_account_cl = add_bank_account_to_contact(token, org_id, merchant_id, 'cnt_ghi789', {
    'country': 'CL',
    'currency': 'CLP',
    'entity': 'BANCO_ESTADO',     # Requerido para Chile
    'account_number': '12345678901'
})

# Colombia - entity (código banco) requerido
curl -X POST 'https://api-sandbox.koywe.com/api/v1/organizations/TU_ORG_ID/merchants/TU_MERCHANT_ID/contacts/cnt_abc123/accounts' \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Bancolombia COP",
    "kind": "BANK",
    "isDefault": true,
    "countrySymbol": "CO",
    "currencySymbol": "COP",
    "entity": "BANCOLOMBIA",
    "accountNumber": "1234567890",
    "type": "SAVINGS"
  }'

async function listContacts(token, orgId, merchantId, options = {}) {
  const response = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts`,
    {
      params: {
        search: options.search,        // Opcional: buscar por nombre o email
        limit: options.limit || 50,
        page: options.page || 1
      },
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return response.data;
}
 
// Uso
const contacts = await listContacts(token, orgId, merchantId, {
  search: 'juan',
  limit: 20
});
 
console.log(`Se encontraron ${contacts.length} contactos`);

async function getContact(token, orgId, merchantId, contactId) {
  const response = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts/${contactId}`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return response.data;
}
 
// Uso
const contact = await getContact(token, orgId, merchantId, 'cnt_abc123');
console.log('Contacto:', contact);

async function getContactBankAccounts(token, orgId, merchantId, contactId) {
  const response = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts/${contactId}/accounts`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return response.data;
}
 
// Uso
const bankAccounts = await getContactBankAccounts(token, orgId, merchantId, 'cnt_abc123');
console.log('Cuentas bancarias:', bankAccounts);

async function updateContact(token, orgId, merchantId, contactId, updates) {
  const response = await axios.put(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts/${contactId}`,
    updates,
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Uso - Actualizar teléfono o dirección
const updated = await updateContact(token, orgId, merchantId, 'cnt_abc123', {
  phone: '+573009876543',
  address: {
    street: 'Calle 456',
    city: 'Medellín'
  }
});

// Verificar si el contacto existe antes de crear
async function getOrCreateContact(token, orgId, merchantId, email) {
  // Intentar encontrar existente
  const contacts = await listContacts(token, orgId, merchantId, { search: email });
  
  if (contacts.length > 0) {
    return contacts[0];  // Devolver existente
  }
  
  // Crear nuevo si no se encuentra
  return await createContact(token, orgId, merchantId, {
    email: email,
    // ... otros campos
  });
}

// 1. Crear contacto de cliente
const customer = await createContact(token, orgId, merchantId, {
  firstName: 'María',
  lastName: 'García',
  countrySymbol: 'CO',
  businessType: 'PERSON',
  type: 'PERSON',
  email: 'cliente@ejemplo.com',
  documentType: 'CC',
  documentNumber: '1234567890',
  phone: '+573001234567'
});
 
// 2. Crear orden PAYIN vinculada al contacto
const order = await createPayinOrder(token, orgId, merchantId, {
  contactId: customer.id,
  amount: 50000,
  currency: 'COP',
  // ... otros campos
});

// 1. Crear contacto de proveedor
const provider = await createContact(token, orgId, merchantId, {
  firstName: 'Servicios ABC SAS',
  countrySymbol: 'CO',
  businessType: 'COMPANY',
  type: 'BUSINESS',
  email: 'proveedor@ejemplo.com',
  documentType: 'NIT',
  documentNumber: '900123456-1'
});
 
// 2. Agregar cuenta bancaria del proveedor
const bankAccount = await addBankAccountToContact(token, orgId, merchantId, provider.id, {
  name: 'Bancolombia COP',
  kind: 'BANK',
  isDefault: true,
  countrySymbol: 'CO',
  currencySymbol: 'COP',
  entity: 'BANCOLOMBIA',
  accountNumber: '1234567890',
  type: 'CHECKING'
});
 
// 3. Crear orden PAYOUT
const payout = await createPayoutOrder(token, orgId, merchantId, {
  contactId: provider.id,
  destinationAccountId: bankAccount.id,  // Vincular a cuenta bancaria
  amount: 500000,
  currency: 'COP'
});