Bloque Docs
  • Español

      • Organizaciones

      Aprende cómo crear y gestionar organizaciones usando el SDK de Bloque.

      Descripción General

      Las organizaciones son la base de la plataforma Bloque. Pueden ser empresas o individuos y contienen toda la información de perfil y cumplimiento normativo necesaria.

      Crear una Organización

      Organización de Negocios

      import { SDK } from '@bloque/sdk';
import type { CreateOrgParams } from '@bloque/sdk/orgs';

const bloque = new SDK({
  origin: 'your-origin',
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_API_KEY!,
  },
  mode: 'production',
});

const params: CreateOrgParams = {
  org_type: 'business',
  profile: {
    legal_name: 'Acme Corporation',
    tax_id: '123456789',
    incorporation_date: '2020-01-01',
    business_type: 'llc',
    incorporation_country_code: 'US',
    incorporation_state: 'CA',
    address_line1: '123 Main St',
    postal_code: '94103',
    city: 'San Francisco',
  },
  metadata: {
    source: 'web_app',
    campaign: 'q1_2024',
  },
};

const organization = await bloque.orgs.create(params);

      Organización Individual

      const params: CreateOrgParams = {
  org_type: 'individual',
  profile: {
    legal_name: 'John Doe',
    tax_id: '123-45-6789',
    incorporation_date: '1990-05-20',
    business_type: 'sole_proprietorship',
    incorporation_country_code: 'US',
    address_line1: '456 Oak Ave',
    postal_code: '10001',
    city: 'New York',
  },
};

const organization = await bloque.orgs.create(params);

      Parámetros

      CreateOrgParams

      CampoTipoRequeridoDescripción
      org_type'business' | 'individual'SíTipo de organización
      profileOrgProfileSíDetalles del perfil de la organización
      metadataRecord<string, unknown>NoMetadatos personalizados

      OrgProfile

      CampoTipoRequeridoDescripción
      legal_namestringSíNombre legal de la organización
      tax_idstringSíNúmero de ID fiscal
      incorporation_datestringSíFecha de incorporación (YYYY-MM-DD)
      business_typestringSíTipo de negocio (ej: 'llc', 'corporation')
      incorporation_country_codestringSíCódigo de país (ISO 3166-1 alpha-2)
      incorporation_statestringNoEstado/provincia
      address_line1stringSíLínea de dirección principal
      address_line2stringNoLínea de dirección secundaria
      postal_codestringSíCódigo postal/ZIP
      citystringSíCiudad
      logo_urlstringNoURL del logo
      placesPlace[]NoUbicaciones adicionales

      Respuesta

      Organization

      interface Organization {
  urn: string;                           // Nombre único de recurso
  org_type: 'business' | 'individual';   // Tipo de organización
  profile: OrgProfile;                   // Perfil de la organización
  metadata?: Record<string, unknown>;    // Metadatos personalizados
  status: OrgStatus;                     // Estado de la organización
}

      Estado de la Organización

      EstadoDescripción
      awaiting_compliance_verificationPendiente de verificación de cumplimiento normativo
      activeLa organización está activa
      suspendedLa organización está suspendida
      closedLa organización está cerrada

      Organizaciones con Múltiples Ubicaciones

      Para organizaciones con múltiples ubicaciones, utiliza el campo places:

      const params: CreateOrgParams = {
  org_type: 'business',
  profile: {
    legal_name: 'Global Tech Inc',
    tax_id: '98-7654321',
    incorporation_date: '2018-03-10',
    business_type: 'corporation',
    incorporation_country_code: 'US',
    incorporation_state: 'DE',
    address_line1: '789 Corporate Blvd',
    postal_code: '19801',
    city: 'Wilmington',
    places: [
      {
        country_code: 'US',
        state: 'CA',
        address_line1: '100 Silicon Valley Dr',
        postal_code: '94025',
        city: 'Menlo Park',
        is_primary: true,
      },
      {
        country_code: 'US',
        state: 'NY',
        address_line1: '250 Broadway',
        postal_code: '10007',
        city: 'New York',
        is_primary: false,
      },
    ],
  },
};

      Metadatos Personalizados

      Agrega campos personalizados para rastrear información adicional:

      const params: CreateOrgParams = {
  org_type: 'business',
  profile: {
    // ... profile fields
  },
  metadata: {
    source: 'api',
    customer_id: 'cust_123',
    plan: 'enterprise',
    referral_code: 'REF2024',
  },
};

      Mejores Prácticas

      1. Valida los Datos: Asegúrate de que todos los campos requeridos estén presentes antes de llamar a la API
      2. Maneja Errores: Siempre usa bloques try-catch
      3. Guarda URNs: Almacena el URN de la organización para operaciones futuras
      4. Usa Metadatos: Rastrea contexto adicional usando metadatos
      5. Prueba en Sandbox: Siempre prueba con mode: 'sandbox' primero

      Próximos Pasos