# Documentação Open API (Swagger)

Segue abaixo os endpoints no padrão openapi. Pode ser visualizado usando uma IDE de desenvolvimento ou pelo site <https://editor.swagger.io/>

```
openapi: 3.0.3
info:
  title: API de Transactions - Certificados PF | PJ
  description: API para criação e consulta de transactions de certificados digitais (Pessoa Física e Pessoa Jurídica).
  version: 1.0.0

servers:
  - url: https://{host}
    variables:
      host:
        default: api-varbackendhom.soluti.com.br
        description: Host da API

tags:
  - name: Autenticação
  - name: Transactions

paths:

  /oauth/token:
    post:
      tags:
        - Autenticação
      summary: Obter access token OAuth2
      description: Autenticação via client_credentials.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - grant_type
                - client_id
                - client_secret
              properties:
                grant_type:
                  type: string
                  example: client_credentials
                client_id:
                  type: string
                  example: CLIENT_ID
                client_secret:
                  type: string
                  example: CLIENT_SECRET
                scope:
                  type: string
                  example: ""
      responses:
        "200":
          description: Token gerado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  token_type:
                    type: string
                    example: Bearer
                  expires_in:
                    type: integer
                    example: 31536000
                  access_token:
                    type: string
                    example: eyJ0....26Y

  /api/v1/p/transaction:
    post:
      tags:
        - Transactions
      summary: Criar nova transaction (PF ou PJ)
      description: Criar nova transaction (PF ou PJ)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTransactionRequest"
      responses:
        "201":
          description: Transaction criada com sucesso
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateTransactionResponse"
        "422":
          description: Erro de validação
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"

  /api/v1/p/transaction/{uuid}:
    get:
      tags:
        - Transactions
      summary: Consultar transaction por UUID
      security:
        - bearerAuth: []
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: UUID da transaction
      responses:
        "200":
          description: Dados da transaction
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateTransactionResponse"
        "404":
          description: Transaction não encontrada
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"



  /path/webhook-update:
    post:
      tags:
        - Webhook
      summary: Webhook de atualização de status
      description: |
        Este webhook é enviado pelo sistema quando o status da transaction é atualizado (aprovada, emitida, revogada ou cancelada).

        Seu sistema deve disponibilizar um endpoint público para recebimento.

        in-progress: Em andamento, transaction criada e em processo de validação/videconferência.

        approved: Aprovada, certificado pronto para emissão.
        
        issued: Emitida, certificado foi emitido.

        cancelled: Cancelada, solicitação cancelada pelo emissor.

        revoked: Revogada, certificado foi revogado a pedido do cliente ou pelo emissor.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTransactionResponse"
            example:
              transaction_id: "a1230c21-d114-4563c-bd0a-85d2947b43b2"
              status: "approved"
              transaction_link: "https://vlinehom.com.br/1866c559-d0cd-451b-8294-6308bf5a7b8c"
              request_code: "11DE76JL3546O982"
              ar_address: "https://arsolutihom.acsoluti.com.br"
              requires_documentation: false

      responses:
        "200":
          description: Webhook recebido com sucesso.
        "400":
          description: Qualquer código HTTP retornado da classe 400 ou 500 será entendido como erro e uma nova tentantiva será feita em alguns minutos.

components:

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:

    CreateTransactionRequest:
      type: object
      required:
        - negociation_token
        - product_sku
        - registration_authority
        - physical_person
      properties:
        negociation_token:
          type: string
          description: Código da negociação
          example: abc123
        product_sku:
          type: integer
          example: 190
          description: SKU do produto
        registration_authority:
          type: string
          description: Autoridade de registro
          example: arsolutihom
        shouldEmailNotify:
          type: boolean
          example: true
          default: true
          description: Se true, envia uma notificação ao email physical_person.email informando que uma nova transaction foi criada junto com o link para continuar a jornada.
        physical_person:
          $ref: "#/components/schemas/PhysicalPerson"
        legal_person:
          $ref: "#/components/schemas/LegalPerson"

    PhysicalPerson:
      type: object
      required:
        - cpf
        - name
        - birthdate
        - email
        - phone
        - city
      properties:
        cpf:
          type: string
          example: "12345678901"
          description: CPF do titular, apenas números.
        name:
          type: string
          example: José da Silva
          description: Nome completo do titular
        birthdate:
          type: string
          example: 1990-08-10
          description: Data de nascimento do titular
        email:
          type: string
          example: cliente@email.com
          description: Email do titular
        email_cc:
          type: string
          example: copia@email.com
          description: Email auxiliar (usado para notificar sobre vencimento do certificado)
        social_name:
          type: string
          example: Zé
          description: Nome social do titular a qual o mesmo prefere ser chamado. Normalmente usado quando a pessoa em questão não gosta de usar seu primeiro nome.
        phone:
          type: string
          example: "11999999999"
          description: Telefone do titular (DDD + número)
        city:
          type: integer
          example: 3550308
          description: Código IBGE do município do titular (local de residência)

    LegalPerson:
      type: object
      properties:
        name:
          type: string
          example: EMPRESA LTDA
          description: Razão social da empresa
        cnpj:
          type: string
          example: "12345678000199"
          description: CNPJ da empresa, apenas números

    CreateTransactionResponse:
      type: object
      properties:
        transaction_id:
          type: string
          example: 1866c559-d0cd-451b-8294-6308bf5a7b8c
          description: Identificador da transaction (UUID)
        status:
          type: string
          enum:
            - in-progress
            - approved
            - issued
            - cancelled
            - revoked
          example: in-progress
          description: Status da transaction. Sempre inicia com in-progress
        cpf:
          type: string
          example: 12345678901
          description: CPF do titular. Apenas números
        cnpj:
          type: string
          example: 12345678000199
          description: CNPJ da empresa, quando certificado PJ. Apenas números
        transaction_link:
          type: string
          example: https://vlinehom.com.br/1866c559-d0cd-451b-8294-6308bf5a7b8c
          description: Link a ser usado pelo cliente para continuar o processo de validação e emissão do certificado
        requires_documentation:
          type: boolean
          example: true
          description: Retorna se será necessário anexar documentos que comprovem o vinculo do titular com a empresa
        ar_address:
          type: string
          example: https://arsolutihom.acsoluti.com.br
          description: Endereço URL da AR onde a solicitação foi validada e/ou emitida. Disponível apenas após o status approved
        request_code:
          type: string
          example: 11DE5J6U9AS3324
          description: Código da solicitação na AR. Disponível apenas após o status approved

    ValidationError:
      type: object
      properties:
        message:
          type: string
          example: The given data was invalid.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string

    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: 401 Unauthorized
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://manuais.soluti.com.br/documentacao-de-integracao-videoconferencia/referencia-da-api/documentacao-open-api-swagger.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.