Comercios — Documentación Funcional

Documentación generada a partir de Swagger merchants.yaml (versión 1.0.0).

1. Visión General

El servicio de Merchants es responsable de registrar, consultar, actualizar y calificar los establecimientos comerciales que desean aceptar pagos a través de la plataforma Getnet.

En términos de negocio: cuando una persona física (autónomo, profesional liberal), un MEI o una empresa (CNPJ) quiere empezar a recibir pagos con tarjeta, link de pago, POS o e-commerce por Getnet, necesita ser acreditado. Este proceso de acreditación —desde el primer registro hasta la aprobación final— es exactamente lo que gestiona este servicio.

El servicio resuelve los siguientes problemas:

¿Cómo registrar un nuevo cliente de adquirencia? — Ya sea persona física o jurídica, el servicio ofrece un flujo guiado de ingreso de datos, que puede hacerse en una sola etapa o en varias etapas progresivas.
¿Cómo saber si un CPF o CNPJ ya es cliente de Getnet? — Una consulta rápida responde si el documento ya tiene un Establecimiento Comercial (EC) acreditado.
¿Cómo mantener los datos de registro actualizados? — El servicio permite actualizar cualquier información del registro en cualquier momento.
¿Cómo validar si el cliente está apto para operar? — El proceso de calificación (análisis de riesgo y compliance) verifica si el establecimiento puede realmente hacer negocios con Getnet.

2. Contexto y Casos de Uso

Cuándo utilizar este servicio

Utiliza este servicio siempre que necesites:

Iniciar la acreditación de un nuevo establecimiento comercial en Getnet.
Consultar los datos de registro de un establecimiento existente.
Actualizar información de registro (dirección, ingresos, representante legal, etc.).
Verificar previamente si un CPF o CNPJ ya tiene vínculo con Getnet.
Activar el análisis de riesgo y compliance de un establecimiento antes de activarlo.

Escenarios reales de negocio

Escenario 1 — Autónomo queriendo aceptar tarjeta

João es electricista autónomo y quiere un POS de Getnet. El canal recopila su CPF, nombre, fecha de nacimiento, celular, correo electrónico y nombre de la madre. Con estos datos, se crea el registro de João. Luego, se agregan los datos de ingresos, dirección y horario de funcionamiento. Finalmente, se activa la calificación para saber si João puede operar.

Escenario 2 — Empresa iniciando acreditación (PJ)

Una panadería con CNPJ quiere aceptar pagos digitales. El canal informa el CNPJ y los datos del representante legal (CPF, nombre, celular y correo electrónico). La plataforma ya busca automáticamente los datos de la empresa en la Receita Federal (razón social, socios, dirección). El canal complementa con nombre comercial, facturación anual y dirección comercial, y luego activa la calificación.

Escenario 3 — Verificación de duplicidad antes del registro

Antes de iniciar la acreditación, el canal verifica si el CPF o CNPJ ya tiene un EC acreditado en Getnet. Si es así, se evita la duplicidad. Si no, se procede con el registro normalmente.

Escenario 4 — Actualización de datos de registro

Un comercio ya acreditado cambia de dirección. El canal busca los datos actuales del comercio, cambia solo el campo de dirección en la respuesta y reenvía el payload completo para la actualización.

Escenario 5 — Recalificación tras rechazo

Un comercio fue rechazado en la calificación por datos incorrectos. Tras corregir la información mediante actualización, el canal activa nuevamente la calificación para un nuevo análisis.

3. Prerrequisitos

Autenticación

Todos los endpoints de esta API requieren un token de acceso válido. Este token debe obtenerse previamente en el servicio de autenticación de Getnet:

Cómo obtener: POST /token (dominio Authentication)
Cómo usar: enviar en el header HTTP Authorization directamente, sin el prefijo Bearer:

text

Authorization: {access_token}

text

Authorization: {access_token}

El token tiene un período de validez. Renuévalo antes de iniciar nuevas solicitudes cuando sea necesario.

Ambientes disponibles

Ambiente	URL base
Homologación (test)	`https://api-homologacao.getnet.com.br:443/v1`
Producción	`https://api-backoffice.getnet.com.br:443/v1`

Dependencias de otros servicios

Algunos datos requeridos en la jornada de acreditación dependen de consultas a otros dominios de la plataforma. Estas llamadas no son obligatorias, pero se recomiendan fuertemente para evitar errores en la calificación:

Servicio	Cuándo usar
`GET /domains/acquirer-merchant-categories`	Para obtener los códigos de categoría de actividad económica disponibles (PF y PJ). Filtra por `?natural_person` para listar solo las categorías de persona física.
`GET /domains/zipcode/{postal_code}`	Para validar el código postal y obtener automáticamente los datos de dirección (calle, barrio, ciudad, estado). Código postal inválido causa rechazo en la calificación.
`GET /domains/countries`	Para obtener los códigos de país válidos, usados en los campos `nationality` y `country_of_birth`.

Permisos y perfiles

El canal integrado debe estar debidamente habilitado en la plataforma Getnet para operar el dominio de Comercios.
Las credenciales utilizadas para obtener el token deben tener permiso de lectura y escritura sobre los recursos de este dominio.

4. Flujo Principal

La acreditación de un comercio sigue un flujo por etapas, desde la verificación inicial hasta la aprobación final. Los endpoints se relacionan de la siguiente forma:

text

┌─────────────────────────────────────────────────────────────────────┐
│                    FLUJO DE ACREDITACIÓN                          │
└─────────────────────────────────────────────────────────────────────┘

  ETAPA 0 — Verificación previa (opcional, pero recomendada)
  ─────────────────────────────────────────────────────────
  600;">GET /establishment-contracts-basic/legal-document-number/{cpf_cnpj}/ec-accredited
       │
       ├── accredited: true  ──► Documento ya posee EC. No continuar con el registro.
       │
       └── accredited: false ──► Puede registrar. Seguir a la ETAPA 1.


  ETAPA 1 — Creación del comercio (datos mínimos)
  ──────────────────────────────────────────────
  600;">POST /merchants
       │
       Enviar: CPF/CNPJ + datos personales básicos + opt-ins (LGPD + términos)
       │
       Retorna: merchant_id + sub_status_steps (etapas pendientes)
       │
       └──► Guardar el merchant_id para usar en las etapas siguientes.


  ETAPA 2 — Complemento de datos (cuando sea necesario)
  ────────────────────────────────────────────────────
  600;">GET /merchants/{merchant_id}          <- Obtener estado actual completo
       │
       Cambiar solo los campos necesarios en el payload retornado
       │
  600;">PUT /merchants/{merchant_id}          <- Reenviar payload completo actualizado
       │
       Enviar: ingresos, patrimonio, direcciones, horario de funcionamiento, etc.
       │
       ATENCION: NUNCA enviar payload parcial — el 600;">PUT sustituye todos los datos.


  ETAPA 3 — Calificación (análisis de riesgo y compliance)
  ───────────────────────────────────────────────────────
  600;">POST /merchants/{merchant_id}/qualification
       │
       Retorna 200
       │
       └── Verificar: report.recommended.status


  ETAPA 4 — Resultado de la calificación
  ────────────────────────────────────
       report.recommended.status
       │
       ├── "approved" ──► Comercio aprobado. Continuar con las próximas
       │                   etapas de la acreditación (ofertas, contratos).
       │
       └── "reproved" ──► Comercio rechazado. Consultar motivo en:
                           report.details[*].detail_description

text

┌─────────────────────────────────────────────────────────────────────┐
│                    FLUJO DE ACREDITACIÓN                          │
└─────────────────────────────────────────────────────────────────────┘

  ETAPA 0 — Verificación previa (opcional, pero recomendada)
  ─────────────────────────────────────────────────────────
  600;">GET /establishment-contracts-basic/legal-document-number/{cpf_cnpj}/ec-accredited
       │
       ├── accredited: true  ──► Documento ya posee EC. No continuar con el registro.
       │
       └── accredited: false ──► Puede registrar. Seguir a la ETAPA 1.


  ETAPA 1 — Creación del comercio (datos mínimos)
  ──────────────────────────────────────────────
  600;">POST /merchants
       │
       Enviar: CPF/CNPJ + datos personales básicos + opt-ins (LGPD + términos)
       │
       Retorna: merchant_id + sub_status_steps (etapas pendientes)
       │
       └──► Guardar el merchant_id para usar en las etapas siguientes.


  ETAPA 2 — Complemento de datos (cuando sea necesario)
  ────────────────────────────────────────────────────
  600;">GET /merchants/{merchant_id}          <- Obtener estado actual completo
       │
       Cambiar solo los campos necesarios en el payload retornado
       │
  600;">PUT /merchants/{merchant_id}          <- Reenviar payload completo actualizado
       │
       Enviar: ingresos, patrimonio, direcciones, horario de funcionamiento, etc.
       │
       ATENCION: NUNCA enviar payload parcial — el 600;">PUT sustituye todos los datos.


  ETAPA 3 — Calificación (análisis de riesgo y compliance)
  ───────────────────────────────────────────────────────
  600;">POST /merchants/{merchant_id}/qualification
       │
       Retorna 200
       │
       └── Verificar: report.recommended.status


  ETAPA 4 — Resultado de la calificación
  ────────────────────────────────────
       report.recommended.status
       │
       ├── "approved" ──► Comercio aprobado. Continuar con las próximas
       │                   etapas de la acreditación (ofertas, contratos).
       │
       └── "reproved" ──► Comercio rechazado. Consultar motivo en:
                           report.details[*].detail_description

Descripción de cada endpoint

Método	Endpoint	Qué hace
`GET`	`/establishment-contracts-basic/legal-document-number/{doc}/ec-accredited`	Verifica si el CPF o CNPJ ya posee EC acreditado. Úsalo antes de iniciar un nuevo registro.
`GET`	`/merchants`	Lista comercios por CPF/CNPJ o código EC, con paginación y filtros de status y tipo.
`POST`	`/merchants`	Crea un nuevo comercio. Acepta datos mínimos y permite complementación posterior.
`GET`	`/merchants/{merchant_id}`	Retorna todos los datos de un comercio específico. Obligatorio antes de cualquier actualización.
`PUT`	`/merchants/{merchant_id}`	Actualiza los datos del comercio con sustitución total. Siempre usar la respuesta del GET como base.
`POST`	`/merchants/{merchant_id}/qualification`	Dispara el análisis de riesgo y compliance del comercio.
`GET`	`/merchants/{merchant_id}/qualification`	Consulta el resultado de la última calificación.

Diferencias entre PF y PJ en el flujo

text

PERSONA FÍSICA (PF)                   PERSONA JURÍDICA (PJ)
  ──────────────────                    ────────────────────
  fiscal_type: natural_person           fiscal_type: company

  Datos mínimos en el 600;">POST:            Datos mínimos en el 600;">POST:
  • CPF                                 • CNPJ
  • Nombre completo                     • Teléfono de la empresa
  • Fecha de nacimiento                 • CPF + datos del representante legal
  • Celular + correo electrónico          (nombre, nacimiento, celular, correo)
  • Nombre de la madre
  • Nacionalidad + país de nacimiento
  • Categoría de actividad (MCC)

  Complementar vía 600;">PUT:                 Complementar vía 600;">PUT:
  • Ingreso bruto mensual               • Nombre comercial
  • Patrimonio neto                     • Facturación bruta anual
  • Dirección residencial               • Patrimonio neto de la empresa
  • Dirección comercial                 • Dirección comercial de la empresa
  • Horario de funcionamiento           • Direcciones del representante legal
                                        • Horario de funcionamiento

  Etapas extra de onboarding (PJ):
  • SOCIAL_CONTRACT    — envío del contrato social
  • LETTER_OF_ATTORNEY — envío de poder (cuando aplique)

  Datos completados automáticamente (PJ):
  • Razón social, fecha de fundación, régimen tributario (vía CNPJ/Receita Federal)
  • Cuadro societario completo (shareholders)

text

PERSONA FÍSICA (PF)                   PERSONA JURÍDICA (PJ)
  ──────────────────                    ────────────────────
  fiscal_type: natural_person           fiscal_type: company

  Datos mínimos en el 600;">POST:            Datos mínimos en el 600;">POST:
  • CPF                                 • CNPJ
  • Nombre completo                     • Teléfono de la empresa
  • Fecha de nacimiento                 • CPF + datos del representante legal
  • Celular + correo electrónico          (nombre, nacimiento, celular, correo)
  • Nombre de la madre
  • Nacionalidad + país de nacimiento
  • Categoría de actividad (MCC)

  Complementar vía 600;">PUT:                 Complementar vía 600;">PUT:
  • Ingreso bruto mensual               • Nombre comercial
  • Patrimonio neto                     • Facturación bruta anual
  • Dirección residencial               • Patrimonio neto de la empresa
  • Dirección comercial                 • Dirección comercial de la empresa
  • Horario de funcionamiento           • Direcciones del representante legal
                                        • Horario de funcionamiento

  Etapas extra de onboarding (PJ):
  • SOCIAL_CONTRACT    — envío del contrato social
  • LETTER_OF_ATTORNEY — envío de poder (cuando aplique)

  Datos completados automáticamente (PJ):
  • Razón social, fecha de fundación, régimen tributario (vía CNPJ/Receita Federal)
  • Cuadro societario completo (shareholders)

5. Guía Rápida de Integración

Esta sección presenta el camino más común de uso de la API — el happy path — para acreditar un comercio PF y un comercio PJ de principio a fin.

Happy Path — Persona Física (PF)

text

PASO 1        PASO 2              PASO 3           PASO 4
  Verificar →   Crear comercio   →  Completar datos → Calificar
  duplicidad    (600;">POST /merchants)    (600;">PUT)            (600;">POST /qualification)

text

PASO 1        PASO 2              PASO 3           PASO 4
  Verificar →   Crear comercio   →  Completar datos → Calificar
  duplicidad    (600;">POST /merchants)    (600;">PUT)            (600;">POST /qualification)

Paso 1 — Verificar si el CPF ya es cliente

Antes de registrar, consulta si el CPF ya tiene un EC acreditado:

text

GET /establishment-contracts-basic/legal-document-number/24751750011/ec-accredited

text

GET /establishment-contracts-basic/legal-document-number/24751750011/ec-accredited

Respuesta esperada (puede continuar):

json

{
  "accredited": false
}

json

{
  "accredited": false
}

Si accredited: true, el CPF ya tiene vínculo. No crees un nuevo registro.

Paso 2 — Crear el comercio PF (datos mínimos)

Envía los datos esenciales para crear el registro. Los datos complementarios se enviarán en el siguiente paso.

Solicitud:

text

600;">POST /merchants

text

600;">POST /merchants

json

{
  "acquirer_code": "getnet",
  "merchant_legal_data": {
    "country": "BR",
    "person": {
      "fiscal_type": "natural_person",
      "legal_document_number": "24751750011",
      "name": "JOÃO DA SILVA SANTOS",
      "birth_date": "1985-03-22",
      "cell_phone": "11987654321",
      "email": "joao.santos@email.com",
      "nationality": "BR",
      "phone": null,
      "economic_activity_profile": {
        "acquirer_merchant_category_code": "2119"
      },
      "mothers_name": "MARIA DA SILVA",
      "country_of_birth": "BR"
    }
  },
  "additional_information": {
    "shared_data": {
      "opt_ins": [
        { "opt_in_type": "lgpd", "accept": true },
        { "opt_in_type": "terms_and_conditions", "accept": true }
      ]
    }
  }
}

json

{
  "acquirer_code": "getnet",
  "merchant_legal_data": {
    "country": "BR",
    "person": {
      "fiscal_type": "natural_person",
      "legal_document_number": "24751750011",
      "name": "JOÃO DA SILVA SANTOS",
      "birth_date": "1985-03-22",
      "cell_phone": "11987654321",
      "email": "joao.santos@email.com",
      "nationality": "BR",
      "phone": null,
      "economic_activity_profile": {
        "acquirer_merchant_category_code": "2119"
      },
      "mothers_name": "MARIA DA SILVA",
      "country_of_birth": "BR"
    }
  },
  "additional_information": {
    "shared_data": {
      "opt_ins": [
        { "opt_in_type": "lgpd", "accept": true },
        { "opt_in_type": "terms_and_conditions", "accept": true }
      ]
    }
  }
}

Qué enviar:

fiscal_type: siempre "natural_person" para PF.

acquirer_merchant_category_code: usa "2119" (Profesional Autónomo) cuando no sepas la categoría específica.

opt_ins: obligatorio con lgpd y terms_and_conditions, ambos con accept: true.

Respuesta esperada (HTTP 200):

json

{
  "situation": {
    "status": "accepted",
    "sub_status_steps": [
      { "name": "DATA_GRID", "situation": { "status": "pending" } },
      { "name": "TERMS_AND_CONDITIONS", "situation": { "status": "finished" } },
      { "name": "PRIVACY_POLICY", "situation": { "status": "finished" } },
      { "name": "CELL_PHONE", "situation": { "status": "pending" } },
      { "name": "EMAIL", "situation": { "status": "pending" } }
    ]
  },
  "merchant": {
    "merchant_id": "6a0f23739a4f90ca92a85686",
    "acquirer_merchant_code": "55317249",
    "situation": { "status": "accepted" }
  },
  "reports": null
}

json

{
  "situation": {
    "status": "accepted",
    "sub_status_steps": [
      { "name": "DATA_GRID", "situation": { "status": "pending" } },
      { "name": "TERMS_AND_CONDITIONS", "situation": { "status": "finished" } },
      { "name": "PRIVACY_POLICY", "situation": { "status": "finished" } },
      { "name": "CELL_PHONE", "situation": { "status": "pending" } },
      { "name": "EMAIL", "situation": { "status": "pending" } }
    ]
  },
  "merchant": {
    "merchant_id": "6a0f23739a4f90ca92a85686",
    "acquirer_merchant_code": "55317249",
    "situation": { "status": "accepted" }
  },
  "reports": null
}

Qué observar en la respuesta:

Guarda el merchant_id — será necesario en todos los pasos siguientes.

El campo sub_status_steps lista las etapas aún pendientes. DATA_GRID con status: pending indica que aún faltan datos complementarios.

TERMS_AND_CONDITIONS y PRIVACY_POLICY ya aparecen como finished porque los opt-ins fueron enviados en el POST.

Paso 3 — Completar los datos (PUT)

Antes de cualquier actualización, consulta el estado actual del comercio:

text

GET /merchants/6a0f23739a4f90ca92a85686

text

GET /merchants/6a0f23739a4f90ca92a85686

Sobre la respuesta obtenida, agrega/modifica los campos complementarios y reenvía el payload completo:

text

PUT /merchants/6a0f23739a4f90ca92a85686

text

PUT /merchants/6a0f23739a4f90ca92a85686

json

{
  "acquirer_code": "getnet",
  "merchant_id": "6a0f23739a4f90ca92a85686",
  "merchant_legal_data": {
    "country": "BR",
    "person": {
      "fiscal_type": "natural_person",
      "legal_document_number": "24751750011",
      "name": "JOÃO DA SILVA SANTOS",
      "birth_date": "1985-03-22",
      "cell_phone": "11987654321",
      "email": "joao.santos@email.com",
      "nationality": "BR",
      "country_of_birth": "BR",
      "mothers_name": "MARIA DA SILVA",
      "economic_activity_profile": {
        "acquirer_merchant_category_code": "2119"
      },
      "gross_monthly_income": 500000,
      "net_worth": 2000000,
      "residential_address": {
        "postal_code": "01321001",
        "street": "RUA MARTINIANO DE CARVALHO",
        "number": "611",
        "suite": "AP 64",
        "district": "BELA VISTA",
        "city": "SAO PAULO",
        "state": "SP",
        "country": "BR"
      },
      "commercial_address": {
        "postal_code": "01321001",
        "street": "RUA MARTINIANO DE CARVALHO",
        "number": "611",
        "suite": "AP 64",
        "district": "BELA VISTA",
        "city": "SAO PAULO",
        "state": "SP",
        "country": "BR"
      },
      "working_hours": [
        {
          "start_day": "mon",
          "end_day": "fri",
          "start_time": "08:00:00",
          "end_time": "18:00:00"
        }
      ]
    }
  }
}

json

{
  "acquirer_code": "getnet",
  "merchant_id": "6a0f23739a4f90ca92a85686",
  "merchant_legal_data": {
    "country": "BR",
    "person": {
      "fiscal_type": "natural_person",
      "legal_document_number": "24751750011",
      "name": "JOÃO DA SILVA SANTOS",
      "birth_date": "1985-03-22",
      "cell_phone": "11987654321",
      "email": "joao.santos@email.com",
      "nationality": "BR",
      "country_of_birth": "BR",
      "mothers_name": "MARIA DA SILVA",
      "economic_activity_profile": {
        "acquirer_merchant_category_code": "2119"
      },
      "gross_monthly_income": 500000,
      "net_worth": 2000000,
      "residential_address": {
        "postal_code": "01321001",
        "street": "RUA MARTINIANO DE CARVALHO",
        "number": "611",
        "suite": "AP 64",
        "district": "BELA VISTA",
        "city": "SAO PAULO",
        "state": "SP",
        "country": "BR"
      },
      "commercial_address": {
        "postal_code": "01321001",
        "street": "RUA MARTINIANO DE CARVALHO",
        "number": "611",
        "suite": "AP 64",
        "district": "BELA VISTA",
        "city": "SAO PAULO",
        "state": "SP",
        "country": "BR"
      },
      "working_hours": [
        {
          "start_day": "mon",
          "end_day": "fri",
          "start_time": "08:00:00",
          "end_time": "18:00:00"
        }
      ]
    }
  }
}

Atención:

El PUT es un reemplazo total. Siempre parte de la respuesta del GET y cambia solo lo necesario.

Valores monetarios en centavos: 500000 = R$ 5.000,00.

El código postal informado debe existir en la base de Getnet. Valida con GET /domains/zipcode/{postal_code} antes de enviar.

commercial_address y residential_address pueden ser iguales (común para autónomos).

Paso 4 — Calificar el comercio PF

Con los datos completos, activa el análisis de riesgo:

text

POST /merchants/6a0f23739a4f90ca92a85686/qualification

text

POST /merchants/6a0f23739a4f90ca92a85686/qualification

El cuerpo de la solicitud puede omitirse para la calificación estándar.

Respuesta — Comercio aprobado (HTTP 200):

json

{
  "report": {
    "recommended": {
      "status": "approved"
    },
    "details": []
  }
}

json

{
  "report": {
    "recommended": {
      "status": "approved"
    },
    "details": []
  }
}

Respuesta — Comercio rechazado (HTTP 200):

json

{
  "report": {
    "recommended": {
      "status": "reproved"
    },
    "details": [
      {
        "detail_type": "blacklist",
        "detail_attribute": "merchant.merchant_legal_data.person.legal_document_number",
        "detail_description": "Estimado Cliente, agradecemos su contacto pero en este momento nuestros servicios no están disponibles para su negocio.",
        "detail_code": "QR-8003"
      }
    ]
  }
}

json

{
  "report": {
    "recommended": {
      "status": "reproved"
    },
    "details": [
      {
        "detail_type": "blacklist",
        "detail_attribute": "merchant.merchant_legal_data.person.legal_document_number",
        "detail_description": "Estimado Cliente, agradecemos su contacto pero en este momento nuestros servicios no están disponibles para su negocio.",
        "detail_code": "QR-8003"
      }
    ]
  }
}

approved: comercio habilitado. Continúa con los siguientes pasos (ofertas, contratos).

reproved: lee detail_description en cada ítem de details para entender el motivo. Cuando el motivo no pueda ser divulgado, el mensaje será genérico (como en el ejemplo).

Happy Path — Persona Jurídica (PJ)

text

PASO 1        PASO 2              PASO 3           PASO 4
  Verificar →   Crear comercio   →  Completar datos → Calificar
  duplicidad    (600;">POST /merchants)    (600;">PUT)            (600;">POST /qualification)

text

PASO 1        PASO 2              PASO 3           PASO 4
  Verificar →   Crear comercio   →  Completar datos → Calificar
  duplicidad    (600;">POST /merchants)    (600;">PUT)            (600;">POST /qualification)

Paso 1 — Verificar si el CNPJ ya es cliente

text

GET /establishment-contracts-basic/legal-document-number/07221119000163/ec-accredited

text

GET /establishment-contracts-basic/legal-document-number/07221119000163/ec-accredited

Respuesta esperada (puede continuar):

json

{
  "accredited": false
}

json

{
  "accredited": false
}

Paso 2 — Crear el comercio PJ (datos mínimos)

text

600;">POST /merchants

text

600;">POST /merchants

json

{
  "acquirer_code": "getnet",
  "additional_information": {
    "shared_data": {
      "opt_ins": [
        { "opt_in_type": "lgpd", "accept": true },
        { "opt_in_type": "terms_and_conditions", "accept": true }
      ]
    }
  },
  "merchant_legal_data": {
    "country": "BR",
    "person": {
      "fiscal_type": "company",
      "legal_document_number": "07221119000163",
      "phone": "51999999999",
      "annual_gross_income": null,
      "net_worth": null,
      "monthly_card_income": null,
      "legal_representative": {
        "fiscal_type": "natural_person",
        "legal_document_number": "24751750011",
        "name": "JOÃO DA SILVA SANTOS",
        "birth_date": "1985-03-22",
        "cell_phone": "51999999999",
        "email": "joao.santos@empresa.com.br",
        "gross_monthly_income": null,
        "mothers_name": null,
        "nationality": null,
        "net_worth": null
      }
    }
  }
}

json

{
  "acquirer_code": "getnet",
  "additional_information": {
    "shared_data": {
      "opt_ins": [
        { "opt_in_type": "lgpd", "accept": true },
        { "opt_in_type": "terms_and_conditions", "accept": true }
      ]
    }
  },
  "merchant_legal_data": {
    "country": "BR",
    "person": {
      "fiscal_type": "company",
      "legal_document_number": "07221119000163",
      "phone": "51999999999",
      "annual_gross_income": null,
      "net_worth": null,
      "monthly_card_income": null,
      "legal_representative": {
        "fiscal_type": "natural_person",
        "legal_document_number": "24751750011",
        "name": "JOÃO DA SILVA SANTOS",
        "birth_date": "1985-03-22",
        "cell_phone": "51999999999",
        "email": "joao.santos@empresa.com.br",
        "gross_monthly_income": null,
        "mothers_name": null,
        "nationality": null,
        "net_worth": null
      }
    }
  }
}

Qué enviar:

fiscal_type de la empresa: siempre "company".

fiscal_type del representante legal: siempre "natural_person".

Los datos de la empresa (razón social, dirección, socios) se buscan automáticamente vía CNPJ en la Receita Federal — no es necesario informarlos.

opt_ins es obligatorio ya en el POST.

Respuesta esperada (HTTP 200) — destacados:

json

{
  "situation": {
    "status": "accepted",
    "sub_status_steps": [
      { "name": "DATA_GRID", "situation": { "status": "pending" } },
      { "name": "SOCIAL_CONTRACT", "situation": { "status": "pending" } },
      { "name": "LETTER_OF_ATTORNEY", "situation": { "status": "pending" } },
      { "name": "TERMS_AND_CONDITIONS", "situation": { "status": "finished" } },
      { "name": "PRIVACY_POLICY", "situation": { "status": "finished" } }
    ]
  },
  "merchant": {
    "merchant_id": "6a0f43fd9a4f90ca92a8596d",
    "acquirer_merchant_code": "55317268",
    "merchant_legal_data": {
      "person": {
        "fiscal_type": "company",
        "legal_name": "NOMBRE COMERCIAL DE LA EMPRESA",
        "founding_date": "2014-04-30",
        "tax_regime": "EIRELI",
        "federal_registration_status": "active"
      }
    }
  }
}

json

{
  "situation": {
    "status": "accepted",
    "sub_status_steps": [
      { "name": "DATA_GRID", "situation": { "status": "pending" } },
      { "name": "SOCIAL_CONTRACT", "situation": { "status": "pending" } },
      { "name": "LETTER_OF_ATTORNEY", "situation": { "status": "pending" } },
      { "name": "TERMS_AND_CONDITIONS", "situation": { "status": "finished" } },
      { "name": "PRIVACY_POLICY", "situation": { "status": "finished" } }
    ]
  },
  "merchant": {
    "merchant_id": "6a0f43fd9a4f90ca92a8596d",
    "acquirer_merchant_code": "55317268",
    "merchant_legal_data": {
      "person": {
        "fiscal_type": "company",
        "legal_name": "NOMBRE COMERCIAL DE LA EMPRESA",
        "founding_date": "2014-04-30",
        "tax_regime": "EIRELI",
        "federal_registration_status": "active"
      }
    }
  }
}

Qué observar:

El merchant_id retornado debe guardarse para los próximos pasos.

La plataforma ya completó automáticamente: legal_name, founding_date, tax_regime, federal_registration_status y la lista de socios (shareholders).

SOCIAL_CONTRACT y LETTER_OF_ATTORNEY son etapas exclusivas de PJ.

Paso 3 — Completar los datos PJ (PUT)

Consulta el estado actual:

text

GET /merchants/6a0f43fd9a4f90ca92a8596d

text

GET /merchants/6a0f43fd9a4f90ca92a8596d

Sobre la respuesta del GET, agrega los datos complementarios y reenvía:

text

PUT /merchants/6a0f43fd9a4f90ca92a8596d

text

PUT /merchants/6a0f43fd9a4f90ca92a8596d

Principales campos a complementar para PJ:

Campo	Ejemplo
`trade_name`	`"PADARIA BOA HORA"`
`annual_gross_income`	`25000000` (= R$ 250.000,00)
`net_worth`	`5000000` (= R$ 50.000,00)
`business_address`	Dirección comercial de la empresa (código postal válido)
`working_hours`	Horario de funcionamiento
`legal_representative.country_of_birth`	`"BR"`
`legal_representative.nationality`	`"BR"`
`legal_representative.gross_monthly_income`	`1500000` (= R$ 15.000,00)
`legal_representative.net_worth`	`3000000` (= R$ 30.000,00)
`legal_representative.residential_address`	Dirección residencial del representante
`legal_representative.commercial_address`	Dirección comercial del representante

Atención con la lista de socios (shareholders): El array shareholders se completa automáticamente por la plataforma. Reenvíalo exactamente como retornado por el GET — no omitas, cambies ni reordenes los socios.

Paso 4 — Calificar el comercio PJ

text

POST /merchants/6a0f43fd9a4f90ca92a8596d/qualification

text

POST /merchants/6a0f43fd9a4f90ca92a8596d/qualification

La respuesta y la interpretación son las mismas que para PF:

report.recommended.status: "approved" → comercio habilitado.
report.recommended.status: "reproved" → consulta report.details[*].detail_description.

6. Reglas de Negocio

Reglas generales

Parámetro obligatorio en el listado

Al consultar la lista de comercios (GET /merchants), es obligatorio informar al menos uno de los parámetros abajo. La ausencia de ambos retorna error 400:

legal_document_number — CPF (11 dígitos) o CNPJ (14 dígitos), solo dígitos.
acquirer_merchant_code — Código EC en Getnet.

Paginación del listado

Parámetro	Predeterminado	Mínimo	Máximo
`page`	`1`	`1`	—
`limit`	`25`	`1`	`200`

Reglas de creación — POST /merchants

Opt-ins obligatorios

El campo additional_information.shared_data.opt_ins es obligatorio en POST /merchants y debe contener los dos tipos abajo, ambos con accept: true:

`opt_in_type`	Descripción
`lgpd`	Consentimiento para el tratamiento de datos personales conforme a la LGPD.
`terms_and_conditions`	Aceptación de los términos y condiciones de uso de la plataforma.

Campos obligatorios en el POST — Persona Física (PF)

Campo	Formato / Restricción
`acquirer_code`	Fijo: `"getnet"`
`fiscal_type`	Fijo: `"natural_person"`
`legal_document_number`	CPF — exactamente 11 dígitos numéricos, sin máscara
`name`	Nombre completo
`birth_date`	Formato `YYYY-MM-DD`
`cell_phone`	10 a 11 dígitos (DDD + número), solo dígitos
`email`	Formato de correo electrónico válido
`nationality`	Código ISO 3166-1 alpha-2 (ej.: `"BR"`). Debe existir en `GET /domains/countries`
`country_of_birth`	Código ISO 3166-1 alpha-2 (ej.: `"BR"`). Debe existir en `GET /domains/countries`
`mothers_name`	Nombre completo de la madre
`acquirer_merchant_category_code`	Código válido obtenido vía `GET /domains/acquirer-merchant-categories`. Usar `"2119"` como predeterminado para PF

Campos obligatorios en el POST — Persona Jurídica (PJ)

Campo	Formato / Restricción
`acquirer_code`	Fijo: `"getnet"`
`fiscal_type`	Fijo: `"company"`
`legal_document_number`	CNPJ — exactamente 14 dígitos numéricos, sin máscara
`phone`	10 a 11 dígitos (DDD + número), solo dígitos
`legal_representative.fiscal_type`	Fijo: `"natural_person"`
`legal_representative.legal_document_number`	CPF — exactamente 11 dígitos numéricos
`legal_representative.name`	Nombre completo del representante legal
`legal_representative.birth_date`	Formato `YYYY-MM-DD`
`legal_representative.cell_phone`	10 a 11 dígitos, solo dígitos
`legal_representative.email`	Formato de correo electrónico válido

Reglas de actualización — PUT /merchants/{merchant_id}

Sustitución total (full replace)

El PUT /merchants/{merchant_id} sustituye todos los datos del comercio. Los campos omitidos serán eliminados del registro. El flujo obligatorio es:

text

600;">GET  /merchants/{merchant_id}   →  Obtener estado actual completo
Modificar solo el(los) campo(s) deseado(s) en la respuesta obtenida
600;">PUT  /merchants/{merchant_id}   →  Reenviar el payload completo

text

600;">GET  /merchants/{merchant_id}   →  Obtener estado actual completo
Modificar solo el(los) campo(s) deseado(s) en la respuesta obtenida
600;">PUT  /merchants/{merchant_id}   →  Reenviar el payload completo

Nunca envíes un payload parcial en el PUT.

Cuadro societario (PJ)

El array shareholders se completa automáticamente por la plataforma vía Receita Federal. Al hacer el PUT, reenvíalo exactamente como retornado por el GET — sin omitir, cambiar ni reordenar socios.

Reglas de dirección

Se aplican a todos los campos de dirección: commercial_address, residential_address (PF) y business_address (PJ), incluyendo las direcciones del representante legal.

Regla	Detalle
Código postal obligatorio	El campo `postal_code` es obligatorio. Formato: 8 dígitos numéricos, sin guion (ej.: `"01321001"`).
El código postal debe existir en la base de Getnet	Un código postal inexistente causa rechazo del comercio en la calificación. Valida previamente con `GET /domains/zipcode/{postal_code}` (recomendado).
`number` o `suite`	`number` es obligatorio cuando el inmueble posee número. Cuando no hay número, el campo `suite` (complemento) se vuelve obligatorio.
Código postal de alcance municipal	Cuando `GET /domains/zipcode/{postal_code}` no retorne `street` y `district`, esos datos deben recopilarse del comercio e informarse manualmente.
Direcciones iguales permitidas	`commercial_address` y `residential_address` pueden contener los mismos datos (común para autónomos).

Reglas de valores monetarios

Todos los campos de valor monetario se expresan en centavos (enteros):

Campo	Ejemplo	Equivalente
`gross_monthly_income`	`1500000`	R$ 15.000,00
`net_worth`	`5000000`	R$ 50.000,00
`annual_gross_income`	`25000000`	R$ 250.000,00
`monthly_card_income`	`3000000`	R$ 30.000,00

Reglas de calificación

Regla	Detalle
Campo principal del resultado	Siempre verifica `report.recommended.status`. Los valores posibles son `"approved"` (apto) y `"reproved"` (rechazado).
Rechazo con motivo genérico	Cuando el motivo del rechazo no pueda ser divulgado por políticas internas de Getnet, `detail_description` retornará un mensaje genérico. Esto es esperado y no indica falla en la integración.
Modo simulación	Es posible ejecutar la calificación en modo de simulación enviando `{ "validation": true }` en el body. El estado del comercio no se altera en este modo.

Status del ciclo de vida del comercio

Status	Significado
`accepted`	Registro recibido. Comercio creado, pero los datos complementarios pueden estar pendientes.
`pending_qualification`	Esperando la activación de la calificación (KYC).
`under_analysis`	En análisis por el equipo de riesgo y compliance de Getnet.
`approved`	Aprobado y listo para recibir ofertas y contratos.
`active`	Activo y transaccionando.
`rejected`	Rechazado en la calificación. No podrá operar.
`blocked`	Bloqueado temporalmente.
`cancelled`	Cancelado o descredenciado.

Etapas del onboarding (sub_status_steps)

Etapa	Quién tiene	Descripción
`DATA_GRID`	PF y PJ	Datos complementarios aún pendientes de completar (ingresos, dirección, horario, etc.).
`SELFIE`	PF y PJ	Envío de selfie para validación biométrica.
`IDENTIFICATION_DOCUMENT`	PF y PJ	Envío de documento de identidad.
`TERMS_AND_CONDITIONS`	PF y PJ	Aceptación de los términos de uso (completado automáticamente cuando el opt-in es enviado en el POST).
`PRIVACY_POLICY`	PF y PJ	Aceptación de la política de privacidad (completado automáticamente).
`ORDER_SUMMARY`	PF y PJ	Confirmación del resumen del pedido.
`CELL_PHONE`	PF y PJ	Validación del número de celular por código OTP.
`EMAIL`	PF y PJ	Validación del correo electrónico por código OTP.
`SOCIAL_CONTRACT`	Solo PJ	Envío del contrato social de la empresa.
`LETTER_OF_ATTORNEY`	Solo PJ	Envío de poder cuando el representante legal no es socio.

7. Tratamiento de Errores

Estructura estándar de error

Todos los errores siguen la estructura abajo:

json

{
  "status_code": 400,
  "message": "Solicitud inválida.",
  "error_code": "MERCHANT_DOCUMENT_INVALID",
  "details": [
    {
      "item": "legal_document_number",
      "description": "Documento inválido."
    }
  ]
}

json

{
  "status_code": 400,
  "message": "Solicitud inválida.",
  "error_code": "MERCHANT_DOCUMENT_INVALID",
  "details": [
    {
      "item": "legal_document_number",
      "description": "Documento inválido."
    }
  ]
}

Campo	Descripción
`status_code`	Código HTTP del error.
`message`	Mensaje general que describe el problema.
`error_code`	Código interno de negocio (cuando esté disponible). Útil para tratamiento programático.
`details`	Lista de errores campo a campo (presente en errores `400` y `422`).

Códigos de error por endpoint

Código HTTP	Nombre	Endpoints donde ocurre	Qué significa	Qué hacer
`400`	Bad Request	Todos	La solicitud está malformada o faltan parámetros obligatorios. Verifica el array `details` para identificar campo a campo el problema.	Corrige los campos indicados en `details` y reenvía la solicitud. En el `GET /merchants`, asegúrate de informar `legal_document_number` o `acquirer_merchant_code`.
`401`	Unauthorized	Todos	El token de acceso está ausente, inválido o expirado.	Obtén un nuevo token vía `POST /token` y reenvía la solicitud con el header `Authorization` correcto (sin prefijo `Bearer`).
`403`	Forbidden	Todos	El token es válido, pero el canal no tiene permiso para acceder al recurso solicitado.	Verifica si las credenciales utilizadas poseen permiso para el dominio Merchants. Contacta al soporte si es necesario.
`404`	Not Found	`GET /merchants/{merchant_id}`, `PUT /merchants/{merchant_id}`, `GET /qualification`, `GET /ec-accredited`	El recurso solicitado no fue encontrado. El `merchant_id` puede estar incorrecto o el comercio puede no existir en el ambiente consultado.	Verifica si el `merchant_id` fue obtenido de la respuesta del `POST /merchants` y si estás consultando el ambiente correcto (homologación vs. producción).
`409`	Conflict	`POST /merchants`	Ya existe un comercio registrado con el documento (CPF o CNPJ) informado.	Utiliza `GET /merchants?legal_document_number={doc}` para localizar el registro existente, o verifica previamente con `GET /ec-accredited` antes de crear.
`422`	Unprocessable Entity	`POST /merchants`, `PUT /merchants/{merchant_id}`, `GET /ec-accredited`, `POST /qualification`	La solicitud es sintácticamente válida, pero viola reglas de negocio. Ejemplos: código postal inválido, código de categoría inexistente, CPF/CNPJ con formato incorrecto.	Verifica el array `details` para identificar qué campo generó la violación. Corrige el valor y reenvía.
`500`	Internal Server Error	Todos	Error interno inesperado en la plataforma. No relacionado con el payload enviado.	Espera unos instantes e intenta nuevamente. Si el error persiste, abre un ticket en el soporte Getnet informando el `request_id` de la solicitud.

Escenarios de error más comunes

Creación con documento ya existente (409)

json

{
  "status_code": 409,
  "message": "Merchant ya existente para el documento informado.",
  "error_code": "MERCHANT_ALREADY_EXISTS"
}

json

{
  "status_code": 409,
  "message": "Merchant ya existente para el documento informado.",
  "error_code": "MERCHANT_ALREADY_EXISTS"
}

Qué hacer: consulta el merchant existente con GET /merchants?legal_document_number={doc} para obtener el merchant_id y continuar la jornada a partir del registro ya creado.

Campo obligatorio ausente (400)

json

{
  "status_code": 400,
  "message": "Solicitud inválida.",
  "details": [
    {
      "item": "legal_document_number",
      "description": "Documento inválido."
    }
  ]
}

json

{
  "status_code": 400,
  "message": "Solicitud inválida.",
  "details": [
    {
      "item": "legal_document_number",
      "description": "Documento inválido."
    }
  ]
}

Qué hacer: corrige el campo indicado en details.item y reenvía. Verifica el formato (dígitos, tamaño) y si el valor está en el patrón esperado.

Merchant rechazado en la calificación (200 con status reproved)

json

{
  "report": {
    "recommended": { "status": "reproved" },
    "details": [
      {
        "detail_type": "blacklist",
        "detail_code": "QR-8003",
        "detail_description": "Estimado Cliente, agradecemos su contacto pero en este momento nuestros servicios no están disponibles para su negocio."
      }
    ]
  }
}

json

{
  "report": {
    "recommended": { "status": "reproved" },
    "details": [
      {
        "detail_type": "blacklist",
        "detail_code": "QR-8003",
        "detail_description": "Estimado Cliente, agradecemos su contacto pero en este momento nuestros servicios no están disponibles para su negocio."
      }
    ]
  }
}

Qué hacer: el rechazo retorna siempre HTTP 200 — no es un error de integración. Verifica detail_description para entender el motivo. Cuando el mensaje sea genérico (como en el ejemplo), el motivo no puede ser divulgado por políticas internas de Getnet. El merchant no podrá operar.

Token expirado (401)

json

{
  "status_code": 401,
  "message": "Token de acceso ausente, inválido o expirado."
}

json

{
  "status_code": 401,
  "message": "Token de acceso ausente, inválido o expirado."
}

Qué hacer: obtén un nuevo token vía POST /token (dominio Authentication) y reenvía la solicitud con el nuevo valor en el header Authorization.

8. Glosario

Término	Definición
Merchant	Establecimiento comercial acreditado — cliente de adquirencia de Getnet. Puede ser Persona Física (PF), MEI o Persona Jurídica (PJ).
EC (Establecimiento Comercial)	Código único atribuido por el adquirente (Getnet) al merchant acreditado. También llamado `acquirer_merchant_code`.
Acreditación	Proceso por el cual un cliente (PF o PJ) es registrado y habilitado para aceptar pagos a través de Getnet.
Onboarding	Jornada completa de entrada del merchant en la plataforma, desde el primer registro hasta la aprobación final.
Calificación (KYC)	Proceso de análisis de riesgo y compliance que verifica si el merchant está apto para hacer negocios con Getnet. KYC = Know Your Customer (Conoce a tu Cliente).
Persona Física (PF)	Merchant registrado con CPF. Incluye autónomos, profesionales liberales y personas físicas en general.
Persona Jurídica (PJ)	Merchant registrado con CNPJ. Incluye empresas de cualquier tamaño y régimen tributario.
MEI	Microemprendedor Individual — categoría especial de PJ con CNPJ y características propias de acreditación.
Representante Legal	Persona física (CPF) autorizada a actuar en nombre de la empresa (PJ) ante Getnet. Puede ser socio, director o apoderado.
Beneficiario Final	Persona física que, en última instancia, controla o se beneficia de la empresa. Identificado automáticamente a partir del cuadro societario consultado en la Receita Federal.
Cuadro Societario (Shareholders)	Lista de socios y beneficiarios finales de una empresa PJ, completada automáticamente por la plataforma vía consulta a la Receita Federal.
MCC (Merchant Category Code)	Código de 4 dígitos que clasifica el ramo de actividad del merchant, conforme al estándar de las marcas (Visa, Mastercard, etc.).
Acquirer Merchant Category Code	Código de subramo de Getnet, más granular que el MCC. Define con más precisión la actividad económica del merchant.
CNAE	Clasificación Nacional de Actividades Económicas — código que identifica la actividad económica de una empresa ante la Receita Federal.
PEP (Persona Expuesta Políticamente)	Persona que ejerce o ejerció un cargo público relevante. La identificación de PEPs es exigida por regulación del Banco Central.
Domicilio Bancario	Cuenta bancaria a la cual se liquidan (transfieren) los valores recibidos por el merchant.
Centralizadora	Merchant o grupo que recibe la liquidación de pagos en nombre de otros establecimientos subordinados.
Sub-status Steps	Etapas granulares del proceso de onboarding (ej.: ingreso de datos, validación de celular, envío de documentos), cada una con su propio estado (`pending`, `finished`).
`merchant_id`	Identificador único del merchant generado por la plataforma en el momento de la creación. Necesario para todas las operaciones posteriores.
`acquirer_code`	Identificador del adquirente. Actualmente siempre `getnet`.
`fiscal_type`	Define si el merchant es Persona Física (`natural_person`) o Persona Jurídica (`company`).
Opt-in	Consentimiento explícito del merchant para el tratamiento de datos (LGPD) y la aceptación de los términos de uso. Obligatorio en la creación del registro.
Código postal de alcance municipal	Código postal que cubre un municipio entero, sin discriminar calle o barrio. En estos casos, los campos `street` y `district` deben informarse manualmente.
DATA_GRID	Etapa del onboarding que agrupa los datos complementarios aún pendientes de completar (ingresos, dirección, horario de funcionamiento, etc.).
LETTER_OF_ATTORNEY	Etapa del onboarding exclusiva para PJ, referente al envío del poder cuando el representante legal no es socio de la empresa.
SOCIAL_CONTRACT	Etapa del onboarding exclusiva para PJ, referente al envío del contrato social de la empresa.
Valores en centavos	Todos los campos monetarios de la API (ingresos, patrimonio, facturación) se expresan en centavos. Ejemplo: R$ 15.000,00 = `1500000`.
`approved` / `reproved`	Resultado de la calificación. `approved` indica que el merchant está apto para operar. `reproved` indica rechazo — el merchant no podrá hacer negocios con Getnet.
`accepted`	Status del merchant justo después de la creación, indicando que el registro fue recibido y está esperando complemento de datos o calificación.
ISO 3166-1 alpha-2	Estándar internacional de códigos de país con 2 letras (ej.: `BR` para Brasil). Usado en los campos `country`, `nationality` y `country_of_birth`.

En esta página

Comercios — Documentación Funcional