> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uvvipay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar status do onboarding

> Consulta o status do onboarding de subconta iniciado via API. Retorna status, action e can_resubmit.

<Note>
  Consulta o status do onboarding iniciado por
  `POST /v2/submerchants/onboarding/pf` ou
  `POST /v2/submerchants/onboarding/pj`. Use o `registration_id` retornado no
  submit. Exige headers `client-id` + `client-secret`.
</Note>

## Campos da resposta

| Campo             | Tipo               | Descrição                                                 |
| ----------------- | ------------------ | --------------------------------------------------------- |
| `external_id`     | `string` \| `null` | Valor do `x-idempotency-key` enviado no onboarding        |
| `registration_id` | `string` (UUID)    | ID do registro de onboarding                              |
| `status`          | `string`           | `processing`, `approved`, `rejected` ou `action_required` |
| `action`          | `string`           | `none`, `resubmit_documents` ou `contact_support`         |
| `can_resubmit`    | `boolean`          | `true` quando o reenvio de documentos está elegível       |

## Como usar `status`, `action` e `can_resubmit`

| `status`          | `action`             | `can_resubmit` | O que fazer                                                                                |
| ----------------- | -------------------- | -------------- | ------------------------------------------------------------------------------------------ |
| `processing`      | `none`               | `false`        | Aguarde e consulte de novo                                                                 |
| `approved`        | `none`               | `false`        | Onboarding concluído. Liste a subconta pelo documento para obter o `internalId`            |
| `action_required` | `resubmit_documents` | `true`         | Reenvie documentos em `POST /v2/submerchants/onboarding/{registrationId}/resend-documents` |
| `rejected`        | `contact_support`    | `false`        | Não reenvie. Contate o suporte                                                             |

**NOTA:** Use este endpoint para decidir a próxima ação. O `status` da
resposta `202` do submit ou do reenvio não substitui esta consulta.

**NOTA:** Se `can_resubmit` for `false`, o reenvio retorna `409`.


## OpenAPI

````yaml GET /v2/submerchants/onboarding/{registrationId}/status
openapi: 3.0.0
info:
  title: UvviPay Public API
  description: >-
    Endpoints públicos da plataforma UvviPay para integração de subcontas
    (submerchants).
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.uvvipay.com.br
    description: Produção
  - url: https://api-staging.uvvipay.com.br
    description: Staging
security:
  - client-id: []
    client-secret: []
tags: []
paths:
  /v2/submerchants/onboarding/{registrationId}/status:
    get:
      tags:
        - Submerchants
      summary: Consultar status do onboarding (API)
      description: >-
        Consulta o status do onboarding de subconta iniciado via API. Retorna
        status, action e can_resubmit.
      operationId: getApiOnboardingStatus
      parameters:
        - name: client-secret
          in: header
          description: Secret da credencial do merchant
          required: true
          schema:
            type: string
        - name: client-id
          in: header
          description: ID público da credencial do merchant
          required: true
          schema:
            type: string
        - name: registrationId
          in: path
          description: >-
            UUID do registro de onboarding retornado no POST
            /v2/submerchants/onboarding/pf|pj
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Status do onboarding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiOnboardingStatusResponseDto'
        '400':
          description: registrationId inválido
        '401':
          description: Credenciais inválidas ou ausentes
        '403':
          description: Recurso não habilitado para este merchant
        '404':
          description: Onboarding não encontrado para o merchant autenticado
        '429':
          description: Limite de requisições excedido
components:
  schemas:
    ApiOnboardingStatusResponseDto:
      type: object
      properties:
        external_id:
          type: string
          nullable: true
          description: Chave de idempotência enviada no onboarding (x-idempotency-key)
          example: pedido-123
        registration_id:
          type: string
          format: uuid
          description: ID do registro de onboarding
          example: 2f1c8b9a-4d3e-4f6a-9b1c-0a1b2c3d4e5f
        status:
          type: string
          enum:
            - processing
            - approved
            - rejected
            - action_required
          description: Estado do onboarding para o integrador
          example: action_required
        action:
          type: string
          enum:
            - none
            - resubmit_documents
            - contact_support
          description: Próxima ação esperada do integrador
          example: resubmit_documents
        can_resubmit:
          type: boolean
          description: Indica se o POST de reenvio de documentos está elegível
          example: true
      required:
        - external_id
        - registration_id
        - status
        - action
        - can_resubmit
  securitySchemes:
    client-id:
      type: apiKey
      in: header
      name: client-id
    client-secret:
      type: apiKey
      in: header
      name: client-secret

````