Cancelar pedido

{
  "reason": "Duplicate charge",
  "vendor_uid": "vendor-uid-abc"
}

{
  "reason": "Solicitação do cliente",
  "cancellation_type": "101",
  "vendor_uid": "vendor-uid-abc"
}

{
  "reason": "Customer cancellation",
  "cancellation_type": "101",
  "payment_method_uid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "vendor_uid": "vendor-uid-abc",
  "store_uid": "store-uid-xyz",
  "media": "WEB",
  "email": "customer@example.com",
  "customer_uid": "customer-uid-123"
}

{
  "data": {
    "uid": "550e8400-e29b-41d4-a716-446655440000",
    "order_code": "ORD-2026-001234",
    "account_uid": "acc-uid-12345",
    "vendor_uid": "vendor-uid-abc",
    "store_uid": "store-uid-xyz",
    "status": "CANCELED",
    "payment_status": "REFUNDED",
    "cancellation_type": "101",
    "order_lines": [],
    "totals": [],
    "payment_methods": [],
    "metadata": {},
    "created_at": "2026-03-30T12:00:00.000Z",
    "updated_at": "2026-03-30T12:05:00.000Z",
    "deleted_at": null
  },
  "status": 200,
  "method": "POST",
  "pathname": "/api/v4/integrations/sales/aggregator/orders/550e8400-e29b-41d4-a716-446655440000/refund",
  "duration": 120,
  "traceId": "abc123",
  "isArray": false
}

{
  "status": 422,
  "errors": {
    "status": "422",
    "code": "invalid_type",
    "title": "Validation error",
    "detail": "reason is required"
  }
}

{
  "status": 404,
  "errors": {
    "status": "404",
    "code": "not_found",
    "title": "Not found",
    "detail": "Order not found"
  }
}

{
  "status": 400,
  "errors": {
    "status": "400",
    "code": "custom",
    "title": "Error",
    "detail": "Payment methods not found"
  },
  "message": "Payment methods not found",
  "code": 0,
  "moreInfo": "https://docs.artisn.io/api/errors"
}

POST

api

integrations

sales

aggregator

orders

{order_uid}

refund

{
  "reason": "Duplicate charge",
  "vendor_uid": "vendor-uid-abc"
}

{
  "reason": "Solicitação do cliente",
  "cancellation_type": "101",
  "vendor_uid": "vendor-uid-abc"
}

{
  "reason": "Customer cancellation",
  "cancellation_type": "101",
  "payment_method_uid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "vendor_uid": "vendor-uid-abc",
  "store_uid": "store-uid-xyz",
  "media": "WEB",
  "email": "customer@example.com",
  "customer_uid": "customer-uid-123"
}

{
  "data": {
    "uid": "550e8400-e29b-41d4-a716-446655440000",
    "order_code": "ORD-2026-001234",
    "account_uid": "acc-uid-12345",
    "vendor_uid": "vendor-uid-abc",
    "store_uid": "store-uid-xyz",
    "status": "CANCELED",
    "payment_status": "REFUNDED",
    "cancellation_type": "101",
    "order_lines": [],
    "totals": [],
    "payment_methods": [],
    "metadata": {},
    "created_at": "2026-03-30T12:00:00.000Z",
    "updated_at": "2026-03-30T12:05:00.000Z",
    "deleted_at": null
  },
  "status": 200,
  "method": "POST",
  "pathname": "/api/v4/integrations/sales/aggregator/orders/550e8400-e29b-41d4-a716-446655440000/refund",
  "duration": 120,
  "traceId": "abc123",
  "isArray": false
}

{
  "status": 422,
  "errors": {
    "status": "422",
    "code": "invalid_type",
    "title": "Validation error",
    "detail": "reason is required"
  }
}

{
  "status": 404,
  "errors": {
    "status": "404",
    "code": "not_found",
    "title": "Not found",
    "detail": "Order not found"
  }
}

{
  "status": 400,
  "errors": {
    "status": "400",
    "code": "custom",
    "title": "Error",
    "detail": "Payment methods not found"
  },
  "message": "Payment methods not found",
  "code": 0,
  "moreInfo": "https://docs.artisn.io/api/errors"
}

Cancela um pedido criado anteriormente com Injetar pedido. O Fire busca o pedido por account e order_uid, atualiza o pedido para CANCELED e devolve o pedido atualizado no envelope padrão da API. Se o processador de pagamento salvo suporta reembolsos (por exemplo, Deuna), o Fire tenta o reembolso e define payment_status como REFUNDED em caso de sucesso. Para outros processadores, o Fire cancela o estado de pagamento e define payment_status como CANCELED.

string

obrigatório

Token Bearer obtido em POST /login. Formato: Bearer <accessToken>.

string

obrigatório

Sua API key do Fire.

string

obrigatório

Deve ser integration. Identifica a requisição como vinda de uma integração externa.

string

obrigatório

Identificador da conta usado para encontrar o pedido.

string

padrão:"application/json"

Use application/json para o corpo da requisição.

string

obrigatório

UID do pedido que será cancelado.

string

obrigatório

Motivo do cancelamento ou solicitação de reembolso.

string

Opcional. UID do método de pagamento usado para resolver credenciais de reembolso quando você precisa direcionar um método específico.

string

obrigatório

UID do vendor usado para resolver credenciais de pagamento.

string

Email do cliente enviado ao processador de pagamento quando aplicável.

string

UID do cliente registrado. Quando presente, o Fire trata o payload de reembolso como autenticado.

string

UID do cliente anônimo. Usado como identificador de usuário do pagamento quando customer_uid não está presente.

string

UID da loja usado para resolver credenciais de pagamento específicas da loja.

string

Meio de venda usado para resolver credenciais. Valores suportados: APP, WEB.

string

Opcional. ID do motivo de cancelamento ou código do catálogo. Quando enviado, é persistido no pedido e reportado ao gateway de pagamento.

{
  "reason": "Duplicate charge",
  "vendor_uid": "vendor-uid-abc"
}

{
  "reason": "Solicitação do cliente",
  "cancellation_type": "101",
  "vendor_uid": "vendor-uid-abc"
}

{
  "reason": "Customer cancellation",
  "cancellation_type": "101",
  "payment_method_uid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "vendor_uid": "vendor-uid-abc",
  "store_uid": "store-uid-xyz",
  "media": "WEB",
  "email": "customer@example.com",
  "customer_uid": "customer-uid-123"
}

object

Pedido atualizado. Os preços em order_lines, totals e payment_methods são devolvidos como valores externos sem escala.

Mostrar data

string

UID do pedido.

string | null

Código legível do pedido.

string

Identificador da conta.

string | null

UID do vendor.

string | null

UID da loja.

string

Status final do pedido. Cancelamentos bem-sucedidos retornam CANCELED.

string

Status final do pagamento: REFUNDED ou CANCELED.

string | null

ID ou código do tipo de cancelamento enviado no request, persistido no pedido. null se não foi fornecido.

array | null

Linhas do pedido com preços sem escala.

array | null

Totais com preços sem escala.

array | null

Métodos de pagamento com valores sem escala.

object | null

Metadados do pedido.

number

Código HTTP no envelope da API.

string

Identificador de trace para suporte e diagnóstico.

{
  "data": {
    "uid": "550e8400-e29b-41d4-a716-446655440000",
    "order_code": "ORD-2026-001234",
    "account_uid": "acc-uid-12345",
    "vendor_uid": "vendor-uid-abc",
    "store_uid": "store-uid-xyz",
    "status": "CANCELED",
    "payment_status": "REFUNDED",
    "cancellation_type": "101",
    "order_lines": [],
    "totals": [],
    "payment_methods": [],
    "metadata": {},
    "created_at": "2026-03-30T12:00:00.000Z",
    "updated_at": "2026-03-30T12:05:00.000Z",
    "deleted_at": null
  },
  "status": 200,
  "method": "POST",
  "pathname": "/api/v4/integrations/sales/aggregator/orders/550e8400-e29b-41d4-a716-446655440000/refund",
  "duration": 120,
  "traceId": "abc123",
  "isArray": false
}

{
  "status": 422,
  "errors": {
    "status": "422",
    "code": "invalid_type",
    "title": "Validation error",
    "detail": "reason is required"
  }
}

{
  "status": 404,
  "errors": {
    "status": "404",
    "code": "not_found",
    "title": "Not found",
    "detail": "Order not found"
  }
}

{
  "status": 400,
  "errors": {
    "status": "400",
    "code": "custom",
    "title": "Error",
    "detail": "Payment methods not found"
  },
  "message": "Payment methods not found",
  "code": 0,
  "moreInfo": "https://docs.artisn.io/api/errors"
}

Regras de processamento

Quando enviado, payment_method_uid ajuda a resolver credenciais, mas o Fire avalia os métodos de pagamento salvos no pedido.
Para reembolsos com Deuna, o pedido deve incluir metadata.order_token; se não existir, o Fire retorna 400.
Depois de salvar o pedido atualizado, o Fire devolve preços transformados para consumo externo.
O Fire notifica o cancelamento downstream depois de salvar o pedido.

Comportamento após o cancelamento

Um 200 significa que o pedido foi cancelado. Não significa que o documento fiscal já está cancelado: essa parte é assíncrona e pode continuar em andamento — ou falhar — depois da nossa resposta.

O cancelamento fiscal é assíncrono

Quando o pedido tinha um documento fiscal emitido, o Fire solicita o cancelamento ao provedor e deixa o documento em cancelling. O estado final chega por webhook do provedor, não na resposta deste endpoint.

Status do documento	O que significa
`cancelling`	Cancelamento solicitado, aguardando confirmação do provedor. Estado transitório.
`cancelled`	Cancelado e confirmado. Circuito completo.
`rejected`	O fisco recusou o cancelamento. O documento continua válido.

Se o webhook do provedor nunca chegar, o documento fica em cancelling indefinidamente — não há retentativa automática que o destrave. Se você precisa de certeza fiscal, esperar o 200 deste endpoint não basta: consulte o status do documento depois.

Os valores não são zerados

Um pedido cancelado mantém seus totais e seus métodos de pagamento com os valores originais. order_lines, totals e payment_methods voltam com os mesmos valores de antes do cancelamento; o que muda é status e payment_status. Isso é proposital: o pedido registra o que aconteceu, não o que continua válido. Se você concilia valores contra pedidos cancelados, vai encontrar que batem perfeitamente — porque foi cobrado exatamente o que foi vendido, antes do cancelamento. A conciliação correta para um pedido cancelado não é “os valores batem?” e sim “cada elo foi revertido?”.

O cancelamento é total, nunca parcial

Não existe cancelamento por linha nem por valor: cancela-se o pedido inteiro ou nada. Por isso o request não leva valores nem lista de itens. Para reverter só uma parte, cancele e injete um novo pedido.

O que verificar do lado do cliente

Não presuma que o documento fiscal foi cancelado por ter recebido 200. Consulte o status se precisar de certeza.
payment_status distingue dois desfechos diferentes: REFUNDED (o processador devolveu o dinheiro) e CANCELED (a cobrança foi cancelada sem devolução). Não são equivalentes para conciliação.
O evento downstream é emitido depois de salvar o pedido, não depois de confirmar o cancelamento fiscal. Ele chega antes de o circuito estar fechado.

API

APIs de parceiro

PayBridge

Regras de processamento

Comportamento após o cancelamento

O cancelamento fiscal é assíncrono

Os valores não são zerados

O cancelamento é total, nunca parcial

O que verificar do lado do cliente

​Regras de processamento

​Comportamento após o cancelamento

​O cancelamento fiscal é assíncrono

​Os valores não são zerados

​O cancelamento é total, nunca parcial

​O que verificar do lado do cliente

Regras de processamento

Comportamento após o cancelamento

O cancelamento fiscal é assíncrono

Os valores não são zerados

O cancelamento é total, nunca parcial

O que verificar do lado do cliente