Registrar una empresa

​

Descripción general

1. Crea una cuenta comercial vinculada al solicitante — el usuario de Fluz cuyo token envías,
2. Almacena el registro de la entidad legal — razón social, estructura, tax ID, estado de constitución, domicilio legal, categoría y uso previsto de la cuenta,
3. Almacena la información de beneficiarios finales para cada propietario que proporciones,
4. Abre un caso de KYB para revisión de cumplimiento, y
5. Vincula la nueva cuenta comercial a la concesión OAuth de tu aplicación.

​

Alcances requeridos

​

Estructura básica de la mutación

mutation RegisterBusiness($input: RegisterBusinessInput!) {
  registerBusiness(input: $input) {
    accountId
    kybStatus
    success
    error {
      message
      code
    }
  }
}

​

Parámetros

​

BusinessLegalAddress

​

RegisterBusinessConfirm

​

BusinessOwner

​

OwnerAddress

​

BusinessStructure (enum)

​

BusinessAccountUsage (enum)

​

Requisitos de beneficiarios finales

• Cada persona que posea 25% o más de la entidad, directa o indirectamente.
• Una persona de control — una persona con responsabilidad significativa en la administración de la entidad (CEO, CFO, socio administrador, socio general o similar) — incluso si no tiene participación. Envíala con isControlPerson: true. Exactamente un propietario debe llevar esa marca.
• El solicitante — el usuario al que pertenece tu Bearer token — coincidiendo por emailAddress o phoneNumber. Exactamente un propietario debe coincidir, y ese propietario no puede tener isInvited: true.

• El total de ownershipPercentage en el arreglo no debe exceder 100, pero no necesita sumar 100. Si un negocio es 40/35/25 entre tres personas más un CEO sin participación, envía los cuatro con porcentajes de 40, 35, 25 y 0.
• Donde una entidad (en lugar de una persona) tenga participación, mira a través hasta las personas detrás de ella y envía a esas personas.
• Los correos electrónicos y teléfonos de propietarios deben ser únicos en la lista.
• title es un campo de texto libre, pero será leído por un revisor humano. Usa cargos reconocibles (“Chief Executive Officer”, “Managing Member”) en lugar de siglas internas.

​

Quién necesita datos de identidad completos

​

Referencia rápida de validación

​

Documentos

​

Detalles de la respuesta

​

RegisterBusinessError

​

Ejemplo cURL

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "query": "mutation RegisterBusiness($input: RegisterBusinessInput!) { registerBusiness(input: $input) { accountId kybStatus success error { message code } } }",
    "variables": {
      "input": {
        "businessName": "Acme Corporation",
        "dbaName": "Acme Co",
        "businessStructure": "LLC",
        "businessLegalAddress": {
          "streetAddressLine1": "123 Main Street",
          "streetAddressLine2": "Suite 100",
          "city": "San Francisco",
          "state": "California",
          "postalCode": "94102",
          "country": "United States"
        },
        "stateOfIncorporation": "California",
        "taxId": "12-3456789",
        "businessCategoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "businessSubCategoryId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "natureOfBusiness": "E-commerce retail",
        "websiteUrl": "https://acme.example.com",
        "businessAccountUsage": ["CORPORATE_SPENDING_ADMIN", "PURCHASE_GOODS_FOR_BUSINESS_USE"],
        "externalReferenceId": "your-partner-user-id-123",
        "confirm": {
          "allOwnersWith25PercentageOwnershipListed": true,
          "noOwnersMoreThan25Percentage": false
        },
        "owners": [
          {
            "firstName": "John",
            "lastName": "Doe",
            "emailAddress": "john@example.com",
            "phoneNumber": "+14155551234",
            "title": "Chief Executive Officer",
            "ownershipPercentage": 60,
            "isControlPerson": true,
            "isInvited": false,
            "isUsPerson": true
          },
          {
            "firstName": "Jane",
            "lastName": "Smith",
            "emailAddress": "jane@example.com",
            "phoneNumber": "+14155555678",
            "title": "Chief Financial Officer",
            "ownershipPercentage": 40,
            "isControlPerson": false,
            "isInvited": false,
            "isUsPerson": true,
            "lastFourSsnDigits": "5678",
            "dob": "1980-07-15",
            "address": {
              "streetAddressLine1": "789 Pine Street",
              "city": "San Francisco",
              "state": "California",
              "postalCode": "94104",
              "country": "United States"
            }
          }
        ]
      }
    }
  }'

​

Respuesta de ejemplo

​

Éxito

{
  "data": {
    "registerBusiness": {
      "success": true,
      "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "kybStatus": "SUBMITTED",
      "error": null
    }
  }
}

​

Error

{
  "data": {
    "registerBusiness": {
      "success": false,
      "accountId": null,
      "kybStatus": null,
      "error": {
        "message": "The entered tax id taxId must be in format XX-XXXXXXX (2 digits, hyphen, 7 digits)",
        "code": "BS-0001"
      }
    }
  }
}

​

Códigos de error

​

Pruebas en staging

• Regístrate contra el endpoint GraphQL de staging mostrado en los ejemplos arriba. Ver Entorno de Staging vs. Producción.
• Usa Direcciones de prueba para direcciones que pasen la validación de forma determinista — la dirección legal pasa por un proveedor real de validación de direcciones, así que calles inventadas fallarán.
• Los EINs en staging aún deben cumplir el formato XX-XXXXXXX, pero no necesitan corresponder a una entidad real.
• Los números de teléfono de propietarios deben ser números posibles para su país. +15551234567 falla porque 555 no es un código de área asignado en EE. UU.; usa un código de área real con un intercambio 555, p. ej., +14155551234.
• Debido a que un usuario no puede tener dos solicitudes abiertas (BS-0007), prueba rutas de registro repetidas con usuarios de prueba distintos.

​

Mejores prácticas

• Valida primero del lado del cliente. Casi todos los códigos de error son problemas de formato o selección que puedes detectar antes de la llamada de red. Hacerlo mejora materialmente las tasas de finalización de onboarding.
• Espera un error a la vez. La validación se detiene en el primer problema que encuentra y la dirección legal se verifica temprano, así que un envío rechazado puede tener más de un error.
• Obtén categorías en tiempo de ejecución. Nunca codifiques en duro los UUIDs de categorías.
• Envía isUsPerson en cada propietario. Es la causa más común de rechazo de listas.
• No vuelvas a intentar automáticamente un KYB rechazado. Reenviar no cambiará el resultado y crea casos duplicados.
• Almacena el accountId de inmediato. Es tu único identificador de la solicitud y la referencia que soporte te pedirá.
• Comunica honestamente el estado pendiente. Indícale al usuario que su empresa está en revisión y cuánto tiempo tarda aproximadamente, en lugar de llevarlo a un panel que aún no puede transaccionar.
• Recopila la propiedad completa desde la primera vez. Omitir beneficiarios finales es la causa más común de que una revisión se estanque por documentación adicional.

​

Notas

• Debe proporcionarse businessAccountUsage o businessAccountUsageOther.
• Los usuarios no pueden registrar una nueva empresa mientras ya tengan una solicitud en curso.
• No hay clave de idempotencia. Los envíos duplicados se bloquean mediante la verificación de solicitud abierta.
• La validación se ejecuta antes de escribir algo, y los registros de entidad, solicitud, estatutos y dirección se crean en una sola transacción — un envío rechazado no deja nada atrás.
• El taxId que envías se tokeniza antes de almacenarse y nunca se devuelve por ninguna operación de lectura.

​

Páginas relacionadas