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

# Aprovar Reembolso

> Antecipa o reembolso pedido pelo comprador, sem esperar o fim da janela.

#### Escopo

```bash theme={null}
    write orders
```

## O que esta chamada faz

Aprovar **antecipa** um reembolso que já vai acontecer: sem aprovação, ele é efetivado sozinho em
`autoApproveAt`. Use quando não há motivo para esperar, por exemplo quando o comprador confirmou no
atendimento que quer o dinheiro de volta.

A resposta `200` traz o reembolso com `status: "in_settlement"`: o estorno foi enviado à
adquirente e vira `refunded` quando ela confirmar a devolução.

> [!WARNING]
>
> **Só alcança solicitação aberta** (`refund_requested`). Se o comprador desistiu, a venda voltou a
> `paid`, e a chamada responde `409` sem estornar nada.
>
> É a diferença para [Reembolsar Pedido](/api-reference/orders/refund), que estorna na hora
> qualquer pedido pago. Numa automação disparada pelo webhook `refund_requested`, use esta rota:
> aquela estornaria a compra de quem já tinha desistido.

## Repetir é seguro

Se a chamada der timeout, repita. Se a aprovação já tinha passado, a resposta é `200` com o estado
atual, e nada é estornado de novo.

## Erros

| Código | Quando |
| - | - |
| `400` | Conta do produtor bloqueada, ou a adquirente recusou o estorno. Neste caso o reembolso fica `acquirer_error` |
| `404` | Pedido inexistente ou de outra conta |
| `409` | A solicitação não está mais aberta. `status` no corpo diz por quê: `paid` (o comprador desistiu), `in_settlement` ou `refunded` (o prazo venceu e o reembolso saiu sozinho) ou `acquirer_error` |
| outros | Repassados da adquirente quando ela não responde ao estorno. O reembolso fica `acquirer_error` |

```json 409 theme={null}
{
  "detail": "Este reembolso não está aguardando aprovação.",
  "code": "refund_not_pending",
  "status": "paid"
}
```

***

## Exemplo

```python Python theme={null}
import requests

resposta = requests.post(
    "https://api.cakto.com.br/public_api/refunds/5f2a1c3e-8b7d-4e21-9f10-3c6d7a2b9e41/approve/",
    headers={"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsIn..."},
    timeout=30,
)

if resposta.status_code == 409:
    print(f"Não estava mais aberto: {resposta.json()['status']}")
else:
    resposta.raise_for_status()
    print(f"Aprovado: {resposta.json()['status']}")
```

```javascript Node.js theme={null}
const resposta = await fetch(
  "https://api.cakto.com.br/public_api/refunds/5f2a1c3e-8b7d-4e21-9f10-3c6d7a2b9e41/approve/",
  {
    method: "POST",
    headers: { Authorization: "Bearer eyJhbGciOiJIUzI1NiIsIn..." },
  },
);

if (resposta.status === 409) {
  const corpo = await resposta.json();
  console.log(`Não estava mais aberto: ${corpo.status}`);
} else if (!resposta.ok) {
  throw new Error(`Cakto API error ${resposta.status}`);
}
```


## OpenAPI

````yaml POST /public_api/refunds/{id}/approve/
openapi: 3.0.3
info:
  title: Cakto API
  version: 1.0.0
  description: Documentação da API pública do Cakto.
servers:
  - url: https://api.cakto.com.br
    description: Cakto API
security: []
paths:
  /public_api/refunds/{id}/approve/:
    post:
      tags:
        - refunds
      description: >-
        Aprova uma solicitação de reembolso aberta (`refund_requested`): o
        estorno sai agora, sem esperar `autoApproveAt`. Só alcança solicitação
        aberta, nunca estorna um pedido `paid`. Repetir a chamada é seguro.
      operationId: refunds_approve_create
      parameters:
        - in: path
          name: id
          schema:
            type: string
          description: Id do pedido reembolsado ou com reembolso solicitado.
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
              examples:
                Aprovado:
                  value:
                    id: 5f2a1c3e-8b7d-4e21-9f10-3c6d7a2b9e41
                    refId: Q7W2k9P
                    status: in_settlement
                    amount: '197.00'
                    currency: BRL
                    paymentMethod: pix
                    offerType: main
                    parentOrderId: null
                    reason: Comprei por engano
                    refundedBy: producer
                    paidAt: '2026-09-26T10:14:03.201544-03:00'
                    requestedAt: '2026-09-28T09:41:22.873610-03:00'
                    autoApproveAt: '2026-09-29T09:41:22.873610-03:00'
                    settlementStartedAt: '2026-09-28T11:02:40.118302-03:00'
                    refundedAt: null
                    customer:
                      id: 183921
                      name: Maria Souza
                      email: maria.souza@example.com
                      birthDate: null
                      phone: '11999999999'
                      docType: cpf
                      docNumber: '12345678909'
                    product:
                      id: ff3fdf61-e88f-43b5-982a-32d50f112414
                      short_id: AckhQ75
                      name: Curso de Exemplo
                    offer:
                      id: B8BcHrY
                      name: Oferta principal
          description: >-
            Estorno enviado à adquirente. `status` vem `in_settlement` até ela
            confirmar a devolução, e aí vira `refunded`. Repetir a chamada
            devolve o estado atual, sem estornar de novo.
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                ContaBloqueada:
                  value:
                    detail: Conta do produtor bloqueada.
          description: Corpo da resposta status 400
        '401':
          description: Request não autenticado devido à ausência ou invalidez do token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedError'
              examples:
                Token ausente ou inválido:
                  $ref: '#/components/examples/UnauthenticatedErrorExample'
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                NaoEncontrado:
                  value:
                    detail: Não encontrado.
          description: >-
            Também é a resposta para pedido de outra conta: 403 confirmaria que
            o id existe.
        '409':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  code:
                    type: string
                    enum:
                      - refund_not_pending
                  status:
                    type: string
              examples:
                NaoEstaPendente:
                  value:
                    detail: Este reembolso não está aguardando aprovação.
                    code: refund_not_pending
                    status: paid
          description: >-
            A solicitação não está mais aberta, e `status` diz por quê: `paid`
            (o comprador desistiu), `in_settlement` ou `refunded` (o prazo
            venceu e o reembolso saiu sozinho) ou `acquirer_error` (a adquirente
            recusou o estorno). Nada foi estornado por esta chamada.
      security:
        - OAuth Token: []
components:
  schemas:
    Refund:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: >-
            Id do pedido. É também o id do reembolso: é por ele que se consulta
            e aprova.
        refId:
          type: string
          readOnly: true
          description: Id curto do pedido, o mesmo que aparece no painel.
        status:
          allOf:
            - $ref: '#/components/schemas/RefundStatusEnum'
          readOnly: true
          description: >-
            `refund_requested`: o comprador pediu e a janela está aberta; se
            ninguém agir, o reembolso é efetivado em `autoApproveAt`.
            `in_settlement`: aprovado, aguardando a adquirente confirmar a
            devolução. `acquirer_error`: a adquirente recusou o estorno.
            `refunded`: devolvido.


            * `refund_requested` - refund_requested

            * `in_settlement` - in_settlement

            * `acquirer_error` - acquirer_error

            * `refunded` - refunded
        amount:
          type: string
          format: decimal
          example: '2.49'
          readOnly: true
          description: Valor deste pedido, como string decimal.
        currency:
          type: string
          readOnly: true
          description: Moeda do pedido.
        paymentMethod:
          type: string
          readOnly: true
          description: Método de pagamento do pedido.
        offerType:
          type: string
          readOnly: true
          description: '`main`, `orderbump`, `upsell` ou `downsell`.'
        parentOrderId:
          type: string
          readOnly: true
          nullable: true
          description: >-
            Id do pedido principal da mesma compra, quando este é order bump ou
            upsell.
        reason:
          type: string
          readOnly: true
          nullable: true
          description: Motivo informado pelo comprador ao pedir o reembolso.
        refundedBy:
          type: string
          readOnly: true
          nullable: true
          description: >-
            Quem acionou o reembolso: `customer` (pedido pelo comprador),
            `producer` (aprovado ou feito pelo produtor) ou `admin` (suporte da
            Cakto).
        paidAt:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: Quando o pedido foi pago.
        requestedAt:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: >-
            Quando o comprador pediu o reembolso. `null` em reembolso feito sem
            solicitação.
        autoApproveAt:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: >-
            Fim da janela da solicitação: se o comprador não cancelar e ninguém
            aprovar antes, o reembolso é efetivado automaticamente neste
            instante. `null` fora da janela.
        settlementStartedAt:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: Quando o estorno foi enviado à adquirente.
        refundedAt:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: >-
            Quando a adquirente confirmou a devolução. `null` enquanto não
            confirmou.
        customer:
          allOf:
            - $ref: '#/components/schemas/CustomerOrder'
          readOnly: true
          description: 'Comprador: nome e contato para falar com ele dentro da janela.'
        product:
          allOf:
            - $ref: '#/components/schemas/RefundProduct'
          readOnly: true
        offer:
          allOf:
            - $ref: '#/components/schemas/RefundOffer'
          readOnly: true
          nullable: true
      required:
        - amount
        - autoApproveAt
        - currency
        - customer
        - id
        - offer
        - offerType
        - paidAt
        - parentOrderId
        - paymentMethod
        - product
        - reason
        - refId
        - refundedAt
        - refundedBy
        - requestedAt
        - settlementStartedAt
        - status
    UnauthenticatedError:
      type: object
      properties:
        detail:
          type: string
    RefundStatusEnum:
      enum:
        - refund_requested
        - in_settlement
        - acquirer_error
        - refunded
      type: string
      description: |-
        * `refund_requested` - refund_requested
        * `in_settlement` - in_settlement
        * `acquirer_error` - acquirer_error
        * `refunded` - refunded
    CustomerOrder:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          title: Nome
          description: Nome completo do cliente
          maxLength: 255
        email:
          type: string
          format: email
          description: Endereço de email do cliente
          maxLength: 254
        birthDate:
          type: string
          format: date
          nullable: true
          title: Nascimento
          description: Data de nascimento do cliente
        phone:
          type: string
          title: Telefone
          description: Número de telefone do cliente
          maxLength: 255
        docType:
          nullable: true
          title: Tipo de Documento
          description: |-
            Tipo do documento (ex: cpf, cnpj)

            * `cpf` - CPF
            * `cnpj` - CNPJ
            * `dni` - DNI
            * `cuit` - CUIT
          oneOf:
            - $ref: '#/components/schemas/DocTypeEnum'
            - $ref: '#/components/schemas/BlankEnum'
            - $ref: '#/components/schemas/NullEnum'
        docNumber:
          type: string
          nullable: true
          title: Documento
          description: Número do documento do cliente
          maxLength: 255
      required:
        - email
        - id
        - name
        - phone
    RefundProduct:
      type: object
      properties:
        id:
          type: string
          description: Identificador único do produto
          maxLength: 255
        short_id:
          type: string
          title: ID Curto
          description: Identificador curto do produto
          maxLength: 40
        name:
          type: string
          title: Nome
          description: Nome do produto
          maxLength: 255
      required:
        - name
    RefundOffer:
      type: object
      properties:
        id:
          type: string
          title: Identificador
          description: Identificador único da oferta
          maxLength: 40
        name:
          type: string
          title: Nome
          description: Nome da oferta, exibido no checkout e em outros locais
          maxLength: 255
      required:
        - name
    DocTypeEnum:
      enum:
        - cpf
        - cnpj
        - dni
        - cuit
      type: string
      description: |-
        * `cpf` - CPF
        * `cnpj` - CNPJ
        * `dni` - DNI
        * `cuit` - CUIT
    BlankEnum:
      enum:
        - ''
    NullEnum:
      enum:
        - null
  examples:
    UnauthenticatedErrorExample:
      summary: Token ausente ou inválido
      description: Token ausente ou inválido
      value:
        detail: As credenciais de autenticação não foram fornecidas.
  securitySchemes:
    OAuth Token:
      type: http
      scheme: bearer
      in: header
      name: Authorization
      description: >-
        Token de autenticação do tipo `Bearer {access_token}`, onde
        `{access_token}` é o token obtido no fluxo de
        [autenticação](/authentication).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.