API de Pendências — Documentação Funcional

Este documento descreve o comportamento funcional da API de Pendências do ponto de vista de um integrador parceiro. Explica o que a API faz, o fluxo de onboarding que suporta, as pendências que um comerciante pode ter e as regras de negócio que governam cada operação.

Visão geral

A API de Pendências permite que parceiros consultem e resolvam as pendências de onboarding de um comerciant Getnet. Uma pendência é um requisito pendente (dados faltantes, um documento ou uma aceitação) que o comerciante deve satisfazer antes que a afiliação possa prosseguir.

Usando esta API, um parceiro pode:

Consultar as pendências abertas de um comerciante e seu status atual.
Enviar ou atualizar dados de registro.
Solicitar e validar códigos de verificação de canal de contato (SMS / email / WhatsApp).
Fazer upload de documentos obrigatórios (como conteúdo Base64).
Aceitar documentos e termos.
Baixar documentos gerados quando disponíveis.

Todas as requisições e respostas usam JSON em snake_case, datas estão em ISO-8601 UTC e o tipo de conteúdo é application/json.

Atores e contexto

Toda operação é executada no contexto de um parceiro agindo em nome de um comerciante.

Campo	Descrição
`partnerId`	Identificador único da aplicação parceira.
`merchantId`	Identificador do comerciante cujo onboarding está sendo gerenciado.

Ambos os identificadores aparecem no caminho de cada endpoint:

text

/api/v1/partner/{partnerId}/merchant/{merchantId}/pendencies

text

/api/v1/partner/{partnerId}/merchant/{merchantId}/pendencies

Um tipo de pessoa é derivado do documento legal do comerciante e retornado como person_type:

natural_person — o documento legal do comerciante é um CPF (pessoa física).
company — o documento legal do comerciante é um CNPJ (pessoa jurídica).

O tipo de pessoa determina quais atributos de registro se aplicam (veja Catálogo de atributos data_grid).

Pendências suportadas

Apenas as pendências abaixo são expostas aos parceiros. Qualquer outra pendência que a plataforma rastreia internamente nunca é retornada.

Pendência	Significado	Resolvida via
`cell_phone_validation`	A propriedade do celular deve ser verificada	solicitação de token + validação
`email_validation`	A propriedade do email deve ser verificada	solicitação de token + validação
`data_grid`	Atributos de registro devem ser fornecidos/atualizados	`PUT /data-grid`
`selfie_upload`	Selfie deve ser enviada	`POST /upload-document`
`identification_document_upload`	Documento de identificação deve ser enviado	`POST /upload-document`
`social_contract_upload`	Contrato social deve ser enviado	`POST /upload-document`
`letter_of_attorney_upload`	Procuração deve ser enviada	`POST /upload-document`
`order_summary`	Resumo do pedido deve ser aceito	`PUT /acceptance-document`
`terms_and_conditions`	Termos e condições devem ser aceitos	`PUT /acceptance-document`
`privacy_policy`	Política de privacidade deve ser aceita	`PUT /acceptance-document`

Um comerciante sem pendências abertas retorna uma lista vazia (pendencies: []).

Quando uma pendência data_grid é retornada, seu campo grid_info lista exatamente quais atributos de registro devem ser enviados.

Fluxo de onboarding ponta a ponta

Um parceiro primeiro consulta as pendências do comerciante e depois resolve cada uma respeitando as regras de ordenação abaixo. Apenas as pendências que estão realmente abertas para esse comerciante precisam ser resolvidas.

text

Query pendencies
      │
      ▼
1. Contact validation (first)
      ├─ Submit email / cell_phone via data_grid   → 600;">PUT  .../data-grid
      │  (the value must exist before a code can be sent to it)
      └─ Request and validate the code             → 600;">POST .../token-request
                                                    → 600;">POST .../token-validation
      │
      ▼
2. Resolve remaining registration data (data_grid) → 600;">PUT  .../data-grid
      │
      ▼
3. Documents                                       → 600;">POST .../upload-document
      ├─ Selfie, then identification document (only after the selfie, when required)
      └─ Social contract or power of attorney (per the merchant&#039;s case)
      │
      ▼
4. Accept documents and terms                      → 600;">PUT  .../acceptance-document
      │
      ▼
Onboarding completed

text

Query pendencies
      │
      ▼
1. Contact validation (first)
      ├─ Submit email / cell_phone via data_grid   → 600;">PUT  .../data-grid
      │  (the value must exist before a code can be sent to it)
      └─ Request and validate the code             → 600;">POST .../token-request
                                                    → 600;">POST .../token-validation
      │
      ▼
2. Resolve remaining registration data (data_grid) → 600;">PUT  .../data-grid
      │
      ▼
3. Documents                                       → 600;">POST .../upload-document
      ├─ Selfie, then identification document (only after the selfie, when required)
      └─ Social contract or power of attorney (per the merchant&#039;s case)
      │
      ▼
4. Accept documents and terms                      → 600;">PUT  .../acceptance-document
      │
      ▼
Onboarding completed

Regras de ordenação:

Validação de contato vem primeiro. Um código de verificação só pode ser solicitado após o valor correspondente de email / cell_phone já existir no registro. Envie esses atributos data_grid antes de solicitar/validar um token para esse canal.
Documento de identificação após a selfie, quando a selfie é obrigatória.
Contrato social antes de procuração. O comerciante fornece o contrato social ou a procuração dependendo de sua situação.

Operações

Caminho base: /api/v1/partner/{partnerId}/merchant/{merchantId}/pendencies

Documentação interativa está disponível em /swagger-ui.html; a especificação OpenAPI em /api-docs.

1. Consultar pendências

GET (caminho base)

Retorna as pendências do comerciante com seu status atual e timestamp da última atualização, além do person_type do comerciante e situações gerais. Quando uma pendência é do tipo data_grid, grid_info informa ao parceiro quais atributos devem ser resolvidos.

Comerciante não encontrado / não acessível → 404.
Sem pendências aplicáveis → 200 com uma lista vazia.

Sucesso: 200

2. Solicitar código de validação

POST /token-request

Solicita um código de verificação único a ser enviado ao comerciante através de um canal de contato.

Campo	Obrigatório	Descrição
`type`	sim	Canal de contato: `cell_phone`, `email` (WhatsApp também é suportado como canal).
`value`	sim	O valor do canal (ex: `email@email.com` ou um número de telefone).

O código é despachado de forma assíncrona para o comerciante.

Sucesso: 202 (aceito / despachado)

3. Validar código

POST /token-validation

Envia o código que o comerciante recebeu para confirmar a propriedade do canal de contato.

Campo	Obrigatório	Descrição
`token`	sim	O código único recebido pelo comerciante.
`type`	não	Canal de contato para o qual o código foi enviado.
`value`	não	O valor do canal.
`device_fingerprint`	não	Impressão digital do dispositivo para prevenção de fraude.

Sucesso: 200 (propriedade do canal confirmada)

4. Resolver data_grid

PUT /data-grid

Envia atributos de registro para resolver a pendência data_grid. O corpo carrega um envelope de pendências; apenas data_grid é aceito, e cada item grid_info é discriminado por seu attribute:

json

{
  "pendencies": [
    {
      "name": "data_grid",
      "grid_info": [
        { "attribute": "email", "email": "teste@email.com" },
        { "attribute": "cell_phone", "cell_phone": "51992547923" }
      ]
    }
  ]
}

json

{
  "pendencies": [
    {
      "name": "data_grid",
      "grid_info": [
        { "attribute": "email", "email": "teste@email.com" },
        { "attribute": "cell_phone", "cell_phone": "51992547923" }
      ]
    }
  ]
}

O comerciante deve ter uma pendência data_grid ativa (status pendente); caso contrário, a requisição é rejeitada com 422.
Apenas atributos no catálogo de atributos são aceitos; qualquer outro atributo, um campo desconhecido, um corpo vazio ou um valor malformado → 400.

Sucesso: 204 (sem conteúdo)

5. Fazer upload de documento

POST /upload-document

Faz upload de um documento obrigatório como conteúdo Base64. Retorna a situação atual (status e data da última atualização) do documento enviado.

Campo	Obrigatório	Descrição
`document_type`	sim	Ex: `social_contract`, `identification_document`, `selfie`.
`side`	sim	Lado da imagem, ex: `front`, `back`.
`file_type`	sim	Formato do arquivo, ex: `pdf`, `jpg`, `png`.
`file_base64`	sim	Conteúdo do arquivo codificado em Base64 (deve ser Base64 válido).
`device_fingerprint`	não	Impressão digital do dispositivo.

Campos desconhecidos são rejeitados com 400.

Sucesso: 200

6. Aceitar documento

PUT /acceptance-document

Aceita um documento ou termos. O corpo carrega um envelope de pendências; a resposta retorna o nome e a situação atual da pendência aceita.

json

{
  "pendencies": [
    {
      "name": "privacy_policy",
      "device_fingerprint": "abc123",
      "situation": { "status": "..." }
    }
  ]
}

json

{
  "pendencies": [
    {
      "name": "privacy_policy",
      "device_fingerprint": "abc123",
      "situation": { "status": "..." }
    }
  ]
}

Sucesso: 200

7. Baixar documento

GET /download-document/{documentType}

Baixa um documento gerado como uma string Base64. documentType deve ser um de terms_and_conditions ou order_summary; qualquer outro valor → 400.

Sucesso: 200 (retorna o document_type e seu conteúdo Base64)

Catálogo de atributos data_grid

Quando uma pendência data_grid é retornada, grid_info lista os atributos que devem ser enviados. O conjunto aplicável depende do tipo de pessoa do comerciante.

Pessoa Física (PF)

country_of_birth, cell_phone, email, gross_monthly_income, net_worth, residential_address, merchant_category_code, commercial_address, business_address

Pessoa Jurídica (PJ)

Atributos de nível de empresa merchant_category_code e business_address, mais os dados do representante legal:

legal_representative.email, legal_representative.cell_phone, legal_representative.country_of_birth, legal_representative.residential_address, legal_representative.gross_monthly_income, legal_representative.net_worth

Regras de valor por atributo

Atributo	Formato do valor	Regra
`email` / `legal_representative.email`	`email`	Endereço de email válido, não em branco.
`cell_phone` / `legal_representative.cell_phone`	`cell_phone`	10 a 13 dígitos.
`country_of_birth` / `legal_representative.country_of_birth`	`country`	ISO 3166-1 alpha-2 (ex: `BR`).
`residential_address`, `business_address`, `commercial_address` (e `legal_representative.residential_address`)	`address`	Veja campos de endereço abaixo.
`merchant_category_code`	`merchant_category_code` + `economic_activity_classification_code`, ou `acquirer_merchant_category_code`	Forneça o par MCC (MCC = 4 dígitos, CNAE = 1–7 dígitos) ou o MCC do adquirente.
`gross_monthly_income` / `legal_representative.gross_monthly_income`	`gross_monthly_income`	Valor inteiro em BRL (reais, não centavos).
`net_worth` / `legal_representative.net_worth`	`net_worth`	Valor inteiro em BRL (reais, não centavos).

Campos de endereço: street (obrigatório), number (em branco é tratado como "0"), district (obrigatório), city, state, postal_code (obrigatório, apenas dígitos), country (obrigatório, ISO alpha-2).

Regras de negócio e restrições

Apenas pendências abertas podem ser resolvidas. Resolver data_grid requer uma pendência data_grid ativa (pendente); caso contrário 422.
Exposição seletiva. Apenas as pendências suportadas são retornadas; tipos de pendência internos nunca são expostos.
Entrada rigorosa. Corpos de requisição de parceiros rejeitam campos desconhecidos (400), e corpos vazios ({} / []) são rejeitados.
Documentos devem conter conteúdo Base64 válido.
Ordenação de validação de contato. Um código de verificação só pode ser enviado para um valor de email / cell_phone que já existe no registro.
Tipo de pessoa é derivado do documento legal do comerciante: CPF → natural_person, CNPJ → company.
Sem pendências abertas retorna uma lista vazia.
Dados sensíveis devem ser transmitidos via HTTPS, e todas as requisições requerem autenticação.

Significados de erros

HTTP	Significado
`200`	Sucesso
`202`	Aceito (código de validação despachado)
`204`	Sucesso, sem conteúdo retornado
`400`	Requisição inválida (corpo malformado, campo desconhecido, valor inválido, canal/tipo de documento não suportado)
`401`	Autenticação ausente ou inválida
`403`	Chamador autenticado não tem permissão para acessar o recurso
`404`	Comerciante não encontrado ou não acessível pelo parceiro
`422`	Violação de regra de negócio (ex: sem pendência `data_grid` ativa para resolver)
`500`	Erro inesperado
`504`	Requisição expirou

Respostas de erro compartilham uma forma comum:

json

{ "status_code": 422, "message": "No active data_grid pendency to resolve for this merchant.", "details": [] }

json

{ "status_code": 422, "message": "No active data_grid pendency to resolve for this merchant.", "details": [] }

Nesta página

API de Pendências — Documentação Funcional