Registro de Negocios

Descripción general

Crea una nueva cuenta de negocio de forma programática vía la API. Crea una cuenta de negocio, almacena la información del negocio e inicia el proceso de KYB (Know Your Business). Después de un registro exitoso, la cuenta quedará en estado PENDING hasta que se complete la verificación KYB.

Alcances requeridos

Propiedad	Valor
Endpoint	GraphQL API
Autenticación	OAuth Bearer Token
Alcances requeridos	`REGISTER_BUSINESS`

Requisitos previos

Antes de llamar a esta mutación, usa la consulta getBusinessCategories para obtener valores válidos de businessCategoryId y businessSubCategoryId.

Estructura básica de la mutación

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

Parámetros

Parámetro	Tipo	Requerido	Descripción
`businessName`	`String`	Sí	El nombre legal del negocio
`dbaName`	`String`	No	El nombre comercial o “Doing Business As”
`businessStructure`	`BusinessStructure`	Sí	Debe ser uno de: `LLC`, `CORPORATION`, `PARTNERSHIP`, `SOLE_PROPRIETORSHIP`, `COOP`
`businessLegalAddress`	`BusinessLegalAddress`	Sí	El objeto de la dirección legal del negocio (ver abajo)
`stateOfIncorporation`	`String`	Sí	El estado donde se constituyó el negocio
`taxId`	`String`	Sí	Tax ID / Número EIN. Formato: `XX-XXXXXXX` (2 dígitos, guion, 7 dígitos)
`soleProprietorshipDocumentUrl`	`String`	Condicional	Requerido si `businessStructure` es `SOLE_PROPRIETORSHIP`. Primero carga el documento vía el endpoint REST
`businessCategoryId`	`UUID`	Sí	ID de la categoría del negocio (de la consulta getBusinessCategories)
`businessSubCategoryId`	`UUID`	Sí	ID de la subcategoría del negocio (de la consulta getBusinessCategories)
`natureOfBusiness`	`String`	No	Breve descripción de la naturaleza del negocio
`websiteUrl`	`String`	No	URL del sitio web del negocio
`businessAccountUsage`	`[BusinessAccountUsage]`	Condicional	Arreglo de tipos de uso. Requerido si no se proporciona `businessAccountUsageOther`.
`businessAccountUsageOther`	`String`	Condicional	Requerido si `businessAccountUsage` está vacío o no se proporciona.
`owners`	`[BusinessOwner]`	Sí	Lista de dueños del negocio. Se requiere al menos un dueño. El dueño principal debe ser un usuario registrado de Fluz.

Formato de direcciónDa formato a businessLegalAddress y a cada address de propietario usando los campos estructurados a continuación, con una dirección real y entregable y una ciudad / estado / código postal consistentes. La dirección legal del negocio puede ser internacional (nombre del país, ISO 3166; algunos países están restringidos, p. ej., Rusia o Irán). Las direcciones de los dueños deben ser de EE. UU. Una dirección con formato incorrecto o incongruente devuelve BS-0002 (dirección legal del negocio) o BS-0003 (información del dueño). Consulta Requisitos de Formato de Dirección para más detalles.

BusinessLegalAddress

Campo	Tipo	Requerido	Descripción
`streetAddressLine1`	`String`	Sí	Línea 1 de la dirección
`streetAddressLine2`	`String`	No	Línea 2 de la dirección
`city`	`String`	Sí	Ciudad
`state`	`String`	Sí	Estado/provincia
`postalCode`	`String`	Sí	Código postal
`country`	`String`	Sí	Nombre del país (ISO 3166). Algunos países están restringidos para el registro KYB, p. ej., Rusia o Irán

BusinessOwner

Campo	Tipo	Requerido	Descripción
`firstName`	`String`	Sí	Nombre del dueño
`lastName`	`String`	Sí	Apellido del dueño
`emailAddress`	`String`	Sí	Email del dueño. Asegúrate de usar el correo con el que el usuario se registró en la plataforma de Fluz.
`title`	`String`	Sí	Cargo del dueño en la empresa
`ownershipPercentage`	`Int`	Sí	Porcentaje de propiedad (0-100). La propiedad total entre todos los dueños no puede exceder 100
`lastFourSsnDigits`	`String`	Sí	Últimos 4 dígitos del SSN
`dob`	`String`	Sí	Fecha de nacimiento en formato `MM/DD/YYYY` (p. ej., `02/28/1975`)
`phoneNumber`	`String`	Sí	Número de teléfono: mínimo 10 dígitos, solo dígitos
`address`	`OwnerAddress`	Sí	Dirección del dueño (debe ser de EE. UU., ver `OwnerAddress`)

OwnerAddress

Campo	Tipo	Requerido	Descripción
`streetAddressLine1`	`String`	Sí	Línea 1 de la dirección
`streetAddressLine2`	`String`	No	Línea 2 de la dirección
`city`	`String`	Sí	Ciudad
`state`	`String`	Sí	Debe ser un estado válido de EE. UU. (p. ej., `California`, `New York`, `Texas`)
`postalCode`	`String`	Sí	Debe tener 5 dígitos según el formato de ZIP de EE. UU.

BusinessStructure (enum)

LLC
CORPORATION
PARTNERSHIP
SOLE_PROPRIETORSHIP
COOP

BusinessAccountUsage (enum)

CORPORATE_GIFTING
CORPORATE_SPENDING_ADMIN
REWARDS_MAXIMIZER
GIFT_CARD_RESELLING
PURCHASE_GOODS_FOR_BUSINESS_USE
ONLINE_SELLER_RETAIL_PURCHASING

Detalles de la respuesta

Campo	Tipo	Descripción
`accountId`	`UUID`	El ID de la cuenta del negocio recién creado
`kybStatus`	`String`	El estado KYB del negocio (inicialmente `PENDING`)
`success`	`Boolean`	Indica si el registro fue exitoso (en caso de error)
`error`	`RegisterBusinessError`	Información del error si el registro falló (en caso de error)

RegisterBusinessError

Campo	Tipo	Descripción
`message`	`String`	Mensaje informativo breve del error
`code`	`String`	Código predefinido listado en la tabla de abajo

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"],
        "owners": [
          {
            "firstName": "John",
            "lastName": "Doe",
            "emailAddress": "john@example.com",
            "title": "CEO",
            "ownershipPercentage": 60,
            "lastFourSsnDigits": "1234",
            "dob": "02/28/1975",
            "phoneNumber": "4155551234",
            "address": {
              "streetAddressLine1": "456 Oak Avenue",
              "city": "San Francisco",
              "state": "California",
              "postalCode": "94103"
            }
          },
          {
            "firstName": "Jane",
            "lastName": "Smith",
            "emailAddress": "jane@example.com",
            "title": "CFO",
            "ownershipPercentage": 40,
            "lastFourSsnDigits": "5678",
            "dob": "07/15/1980",
            "phoneNumber": "4155555678",
            "address": {
              "streetAddressLine1": "789 Pine Street",
              "city": "San Francisco",
              "state": "California",
              "postalCode": "94104"
            }
          }
        ]
      }
    }
  }'

Ejemplo de respuesta

Éxito

{
  "data": {
    "registerBusiness": {
      "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "kybStatus": "PENDING"
    }
  }
}

Error

{
  "data": {
    "registerBusiness": {
      "success": false,
      "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

Código	Nombre	Descripción
`BS-0001`	InvalidTaxId	El Tax ID debe tener el formato `XX-XXXXXXX` (2 dígitos, guion, 7 dígitos)
`BS-0002`	InvalidBusinessLegalAddress	La dirección legal del negocio es incorrecta
`BS-0003`	InvalidOwnerInformation	Una o más informaciones del dueño son incorrectas
`BS-0004`	InvalidBusinessAccountUsage	El uso de la cuenta de negocio seleccionado no está permitido
`BS-0005`	InvalidBusinessStructure	La estructura del negocio seleccionada no está permitida
`BS-0006`	InvalidBusinessCategory	Asegúrate de que la categoría del negocio y la subcategoría del negocio sean válidas y estén correctamente relacionadas (no se pueden combinar subcategorías de diferentes categorías; por ejemplo, Arte no puede seleccionarse con la subcategoría Farmacia)
`BS-0007`	RegistrationNotAllowed	Espera a que el último negocio termine el registro antes de iniciar uno nuevo
`AR-0001`	MissingArguments	Falta un argumento requerido (consulta el mensaje de error para más detalles)
`AR-0002`	InvalidArguments	Se proporcionó un argumento inválido (consulta el mensaje de error para más detalles)
`AU-0001`	UnsuccessfulRegistration	Falla general de registro

Notas

Si businessStructure es SOLE_PROPRIETORSHIP, carga el documento mediante el endpoint REST POST https://transactional-graph.staging.fluzapp.com/api/v1/file-upload/sole-proprietorship-document (usando el tipo de contenido form-data). Luego, proporciona la URL generada en soleProprietorshipDocumentUrl
Al especificar el uso de la cuenta, se debe proporcionar businessAccountUsage o businessAccountUsageOther.
Los usuarios no pueden registrar un nuevo negocio si ya tienen una solicitud en curso. Deben esperar a que la solicitud actual sea aprobada o rechazada antes de enviar otra.

​Descripción general

​Alcances requeridos

​Requisitos previos

​Estructura básica de la mutación

​Parámetros

​BusinessLegalAddress

​BusinessOwner

​OwnerAddress

​BusinessStructure (enum)

​BusinessAccountUsage (enum)

​Detalles de la respuesta

​RegisterBusinessError

​Ejemplo cURL

​Ejemplo de respuesta

​Éxito

​Error

​Códigos de error

​Notas