API de Faturas

Listar faturas

invoices:read

curl -X GET "https://api.comando.one/v1/invoices" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

Criar fatura

Cria uma fatura. Se 'items' for enviado, o valor é calculado a partir deles. O cliente pode ser da empresa **ou compartilhado com ela com a permissão 'Faturar'** (o dono marca em Clientes → Compartilhar; é diferente de 'Faturas', que trata das faturas do dono). A fatura pertence a quem a lança — financeiro, baixa e NFS-e são dessa empresa; só o cadastro do cliente é do dono. Cliente compartilhado sem 'Faturar' devolve 404 — na API e na tela.

invoices:create

curl -X POST "https://api.comando.one/v1/invoices" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"<string (uuid)>","due_date":"<string (date)>"}'

Excluir fatura

Exclusão física da fatura (itens e cobranças vinculadas via cascade). Use cancel para apenas cancelar.

invoices:delete

curl -X DELETE "https://api.comando.one/v1/invoices/{id}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

Obter fatura

invoices:read

curl -X GET "https://api.comando.one/v1/invoices/{id}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

Corrigir fatura

Corrige o cabeçalho de uma fatura já criada. Existe para não ser preciso APAGAR a fatura (e estornar a baixa antes) só para trocar um status. Escopo estreito de propósito: para cancelar use `PATCH /v1/invoices/{id}/cancel` — o cancelamento tem efeitos que uma troca de status não dispara. O vencimento não muda aqui: quem cobra é a parcela (`invoice_charges`), e mexer só no cabeçalho daria a impressão de ter mudado a cobrança sem mudar nada do que é cobrado.

invoices:create

curl -X PATCH "https://api.comando.one/v1/invoices/{id}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

Programar a cobrança automática

Liga ou desliga o envio AUTOMÁTICO da cobrança nas parcelas em aberto da fatura. Sem isso a cobrança nunca sai sozinha: o disparo diário só envia com `auto_send_enabled` ligado na parcela, e a fatura criada por API nasce desligada. `days_before` = quantos dias ANTES do vencimento disparar (0 = no dia). Desligar devolve o canal para `manual`.

invoices:send

curl -X PATCH "https://api.comando.one/v1/invoices/{id}/auto-send" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

Cancelar fatura

invoices:cancel

curl -X PATCH "https://api.comando.one/v1/invoices/{id}/cancel" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

Listar as parcelas da fatura

As PARCELAS (invoice_charges) da fatura, com quanto já foi pago e quanto falta em cada uma. Não confunda com `/v1/charges`, que é a cobrança do GATEWAY (Pix/boleto emitido no banco): a parcela é o que manda no vencimento e no status de pagamento da fatura. Use esta rota para descobrir o `charge_id` antes de dar baixa.

invoices:read

curl -X GET "https://api.comando.one/v1/invoices/{id}/charges" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

Dar baixa em uma parcela

Registra o recebimento de uma parcela: cria o pagamento e o aloca à parcela. A parcela e a fatura passam a `pago` (ou `parcial`) pelo próprio banco. Sem `amount`, quita o saldo restante; sem `payment_date`, usa hoje (America/Sao_Paulo). Se a baixa QUITA a fatura e informa a forma de recebimento, ela é copiada para a Forma de Cobrança da fatura quando esta está vazia (baixa parcial não mexe). Baixa PARCIAL é permitida; acima do saldo, não. Campo de corpo que a rota não conhece devolve 400 em vez de ser ignorado.

invoices:settle

curl -X POST "https://api.comando.one/v1/invoices/{id}/charges/{charge_id}/pay" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

Listar as baixas de uma parcela

Os recebimentos já registrados na parcela. `reconciled: true` avisa que aquele pagamento está conciliado com o extrato — o estorno dele será recusado até a conciliação ser desfeita.

invoices:read

curl -X GET "https://api.comando.one/v1/invoices/{id}/charges/{charge_id}/payments" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

Estornar uma baixa

Desfaz um recebimento registrado na parcela. A parcela e a fatura voltam a `pendente`/`vencido`/`parcial` pelo próprio banco. O pagamento é apagado quando existia só para esta baixa; cobrindo outras faturas, perde apenas esta alocação e tem o valor reduzido. RECUSA (409) se o pagamento estiver conciliado com o extrato ou se a parcela tiver gerado repasse (split) já liberado ou pago — nos dois casos a resposta diz o que desfazer antes.

invoices:settle

curl -X DELETE "https://api.comando.one/v1/invoices/{id}/charges/{charge_id}/payments/{payment_id}" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"

Enviar segunda via da fatura ao cliente

Envia a segunda via por e-mail. Sem 'to', usa o e-mail cadastrado do cliente. Os anexos da fatura vão junto por padrão. Registra a tentativa na fila de e-mails antes de enviar, então um envio que falha deixa rastro.

invoices:send

curl -X POST "https://api.comando.one/v1/invoices/{id}/send" \
  -H "Authorization: Bearer cmd_live_SUA_CHAVE"