Faturas (Invoices)

Endpoints de /api2/invoice para listar, consultar, criar (faturamento total ou parcial) e reenviar o e-mail das invoices vinculadas aos pedidos. Suporta captura online, offline ou no_capture e identificação por order_id ou order_increment_id.

REST JSON Bearer Token Novo em 2026

Visão geral

O recurso de invoices documenta o lado financeiro do pedido: faturamento, captura no gateway e comunicação por e-mail. Para detalhes das regras gerais (paginação, datas, status HTTP, tratamento de items), consulte a página principal de Pedidos.

Modos de capturaonline, offline e no_capture.

Identificadoresorder_id ou order_increment_id.

opt

Itens parciaisorder_item_id ou sku + qty.

Aliases/api2/invoice e /api2/invoices.

GET/api2/invoice

Listar invoices.

ListagemFiltros

page, limit, include_pagination Opcional

Paginação padrão.

order_id Opcional

ID interno do pedido.

order_increment_id Opcional

Número incremental do pedido.

increment_id Opcional

Número incremental da invoice. Valor único retorna a invoice detalhada; lista por vírgula ou array funciona como filtro.

state Opcional

Estado da invoice. Valores comuns: 1 aberta, 2 paga, 3 cancelada.

created_from, created_to Opcional

Intervalo de criação.

sort, direction Opcional

Campos aceitos: entity_id, created_at, updated_at, increment_id, grand_total.

Exemplos

GET /api2/invoice?page=1&limit=50&include_pagination=1
Authorization: Bearer {{token}}

GET /api2/invoice?order_increment_id=100000123
Authorization: Bearer {{token}}

{
  "page": 1,
  "limit": 50,
  "include_pagination": 1,
  "order_increment_id": "100000123",
  "created_from": "2026-01-01",
  "created_to": "2026-12-31"
}

Resposta de listagem usa a chave invoices. Busca por ID ou increment_id único usa a chave invoice. Existe alias plural /api2/invoices.

GET/api2/invoice

Obter invoice individual.

GET /api2/invoice?id=456
Authorization: Bearer {{token}}

GET /api2/invoice?increment_id=100000045
Authorization: Bearer {{token}}

POST/api2/invoice/create

Faturar pedido total ou parcialmente.

FaturamentoCaptura

order_id / order_increment_id

Identificação do pedido. Use exatamente um dos dois.

items Opcional

Lista de itens a faturar. Cada entrada usa order_item_id ou sku + qty. Se omitido, fatura todas as quantidades disponíveis.

capture Opcional

Aceita online, offline ou no_capture. Padrão offline.

send_email Opcional

Quando true, envia o e-mail da invoice após salvar.

comment Opcional

Comentário registrado na invoice.

is_customer_notified, is_visible_on_front Opcional

Flags do comentário, não disparam e-mail por si só.

Faturamento total

POST /api2/invoice/create
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_increment_id": "100000123",
  "capture": "offline",
  "send_email": true,
  "comment": "Invoice criada pela integração."
}

Faturamento parcial

POST /api2/invoice/create
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_id": 123,
  "items": [
    {"order_item_id": 10, "qty": 1},
    {"sku": "PRODUTO-001", "qty": 2}
  ],
  "capture": "no_capture"
}

POST/api2/invoice/email

Reenviar o e-mail da invoice. Identifique a invoice com invoice_id, id ou increment_id.

POST /api2/invoice/email
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "invoice_id": 456,
  "comment": "Reenvio solicitado pela integração."
}

Formas de uso suportadas

Combinações testadas e homologadas para o recurso Invoices.

Listar invoices abertasGET /api2/invoice?state=1&include_pagination=1

Invoices de um pedidoGET /api2/invoice?order_increment_id=100000123

Invoice por númeroGET /api2/invoice?increment_id=100000045

Faturamento total offlinePOST /api2/invoice/create + capture=offline

Faturamento parcial sem capturaPOST /api2/invoice/create + items[] + capture=no_capture

Reenviar e-mailPOST /api2/invoice/email

Recomendações para integração

Evitar

Confiar que send_email=true sozinho substitua o reenvio explícito via /api2/invoice/email em casos de falha de SMTP.
Misturar order_id e order_increment_id no mesmo payload.
Usar capture=online sem confirmar suporte do gateway — o erro virá da própria integração de pagamento.

Auditoria financeira

Para reconciliação contábil, prefira capture=offline + comment identificando o sistema de origem (ex.: "Faturado via ERP-XYZ"). Isso facilita a rastreabilidade no histórico do pedido sem acionar o gateway.

Erros comuns

Status	Exemplo de body	Quando ocorre
`400`	`{"error": "Invalid item"}`	Item de `items` sem `order_item_id`/`sku` ou com `qty` não positivo.
`400`	`{"error": "Cannot create invoice"}`	O pedido não admite mais faturamento (ex.: já totalmente faturado ou cancelado).
`401`	`{"error": "Unauthorized"}`	`Authorization` ausente ou token expirado.
`404`	`{"error": "Order not found"}`	`order_id` ou `order_increment_id` inexistente.
`404`	`{"error": "Invoice not found"}`	`invoice_id` ou `increment_id` inexistente.
`409`	`{"error": "Conflict on save"}`	Duplicidade ou deadlock em gravação concorrente.
`500`	`{"error": "Payment gateway error"}`	Falha repassada pelo método de pagamento quando `capture=online`.

Faturas (Invoices)

Visão geral

Exemplos

Faturamento total

Faturamento parcial

Formas de uso suportadas

Recomendações para integração

Recomendado

Evitar

Auditoria financeira

Erros comuns