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

# Consultar status de requisição

> Consulta o status e os detalhes de uma requisição assíncrona.



## OpenAPI

````yaml openapi.yaml GET /v1/request/{request-id}
openapi: 3.1.0
info:
  title: Pipo Public API
  version: 0.2.0
  description: >
    API pública da Pipo Saúde para integração de movimentações de benefícios

    (inclusões, exclusões e consultas) por parceiros e sistemas de folha de
    pagamento.
  contact:
    name: Pipo Engineering
    email: felipe.rodopoulos@piposaude.com.br
servers:
  - url: https://api.pipo.health
    description: Homologação (staging)
  - url: https://api.piposaude.com.br
    description: Produção
security:
  - bearerAuth: []
tags:
  - name: Autenticação
    description: Obtenção do token de acesso.
  - name: Empresas
    description: Consulta de empresas e seus produtos.
  - name: Benefícios
    description: Consulta de produtos/benefícios disponíveis.
  - name: Movimentações
    description: Inclusões, exclusões e histórico de movimentações.
  - name: Membros
    description: Consulta de membros e seus benefícios.
  - name: Solicitações
    description: Consulta do status de requisições assíncronas.
  - name: Health Check
    description: Verificação de disponibilidade.
paths:
  /v1/request/{request-id}:
    get:
      tags:
        - Solicitações
      summary: Consultar status de requisição
      description: Consulta o status e os detalhes de uma requisição assíncrona.
      parameters:
        - name: request-id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID da requisição.
      responses:
        '200':
          description: Status da requisição (objeto no topo, sem envelope `result`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrollmentRequest'
              example:
                request-id: aaa11111-e89b-12d3-a456-426614174006
                request-type: inclusion
                company-tax-id: '12345678000190'
                status: completed
                created-at: '2024-01-15T10:30:00Z'
                status-by-tax-id:
                  '12345678900':
                    Plano Saúde Premium:
                      status: enrollment-created
                      enrollment-id: 789e0123-e89b-12d3-a456-426614174002
        '403':
          description: Sem permissão.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Not entitled to access this request
components:
  schemas:
    EnrollmentRequest:
      type: object
      required:
        - request-id
        - request-type
        - company-tax-id
        - status
        - created-at
      properties:
        request-id:
          type: string
          format: uuid
        request-type:
          $ref: '#/components/schemas/RequestType'
        company-tax-id:
          $ref: '#/components/schemas/Cnpj'
        status:
          $ref: '#/components/schemas/RequestStatus'
        created-at:
          type: string
          format: date-time
        status-by-tax-id:
          type: object
          description: Mapa de CPF → produto → status da parte da requisição.
          additionalProperties:
            type: object
            additionalProperties:
              type: object
              properties:
                status:
                  $ref: '#/components/schemas/RequestItemStatus'
                enrollment-id:
                  type: string
                  format: uuid
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Mensagem descritiva do erro.
    RequestType:
      type: string
      description: Tipo da requisição.
      enum:
        - inclusion
        - exclusion
        - alteration
    Cnpj:
      type: string
      description: >-
        CNPJ (Cadastro Nacional da Pessoa Jurídica). Aceita apenas dígitos ou
        formatado.
      examples:
        - '12345678000190'
        - 12.345.678/0001-90
    RequestStatus:
      type: string
      description: Status da requisição.
      enum:
        - processing
        - completed
        - partial-failure
        - failed
    RequestItemStatus:
      type: string
      description: >-
        Status de cada parte da requisição (por CPF e produto) em
        `status-by-tax-id`.
      enum:
        - enrollment-created
        - enrollment-creation-failed
        - pending
      example: enrollment-created
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token Bearer obtido em `POST /v1/authenticate`.

````