{
"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"
}
API
Cancelar pedido
Cancela um pedido de agregador e, quando o processador de pagamento suporta, reembolsa o pagamento.
POST
/
api
/
v4
/
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
Se o webhook do provedor nunca chegar, o documento fica em
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
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_uidajuda 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 retorna400. - 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 emcancelling. 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. |
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_statusdistingue dois desfechos diferentes:REFUNDED(o processador devolveu o dinheiro) eCANCELED(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.