Faturas

REST API — Todos os endpoints requerem autenticação via Bearer token. Inclua Authorization: Bearer {token} em cada requisição. Os tokens são gerenciados em Configurações do GitScrum → API. Base URL: https://services.gitscrum.com — Todos os caminhos de requisição nesta documentação são relativos a esta URL base.

Crie, gerencie e acompanhe faturas em todo o seu ciclo de vida: rascunho, emissão, envio e marcação como paga.

Listar faturas

GET /company-invoices?company_slug={slug}

Retorna todas as faturas do workspace.

Parâmetros de query

Resposta

{
  "data": [
    {
      "uuid": "inv-abc-123",
      "title": "January 2026 Services",
      "status": "sent",
      "client": {
        "uuid": "client-abc-123",
        "name": "Acme Corp"
      },
      "due_date": "2026-02-28",
      "currency": "USD",
      "subtotal": 8500,
      "tax": 0,
      "total": 8500,
      "issued_at": "2026-02-01T10:00:00Z",
      "paid_at": null,
      "created_at": "2026-01-28T09:00:00Z"
    }
  ]
}

Obter fatura

GET /company-invoices/{uuid}?company_slug={slug}

Retorna detalhes completos da fatura incluindo itens de linha.

Parâmetros de caminho

Resposta

{
  "data": {
    "uuid": "inv-abc-123",
    "title": "January 2026 Services",
    "status": "sent",
    "client": {
      "uuid": "client-abc-123",
      "name": "Acme Corp"
    },
    "due_date": "2026-02-28",
    "currency": "USD",
    "subtotal": 8500,
    "tax": 0,
    "total": 8500,
    "items": [
      {
        "description": "Frontend development",
        "quantity": 40,
        "unit_price": 150,
        "total": 6000
      },
      {
        "description": "Code review & QA",
        "quantity": 10,
        "unit_price": 250,
        "total": 2500
      }
    ],
    "issued_at": "2026-02-01T10:00:00Z",
    "paid_at": null,
    "created_at": "2026-01-28T09:00:00Z"
  }
}

Criar fatura

POST /company-invoices

Cria uma nova fatura em status de rascunho.

Corpo da requisição

Cada item no array items:

Exemplo

curl -X POST https://services.gitscrum.com/company-invoices \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "company_slug": "acme",
    "contact_company_uuid": "client-abc-123",
    "title": "February 2026 Services",
    "due_date": "2026-03-31",
    "currency": "USD",
    "items": [
      {
        "description": "Development hours",
        "quantity": 60,
        "unit_price": 150
      }
    ]
  }'

Atualizar fatura

PUT /company-invoices/{uuid}

Atualiza uma fatura existente. Aceita os mesmos campos opcionais de criar mais company_slug.

Parâmetros de caminho

Emitir fatura

POST /company-invoices/{uuid}/issue?company_slug={slug}

Altera o status da fatura de draft para issued.

Parâmetros de caminho

Enviar fatura

POST /company-invoices/{uuid}/send?company_slug={slug}

Envia a fatura ao cliente por email.

Parâmetros de caminho

Marcar como paga

POST /company-invoices/{uuid}/paid?company_slug={slug}

Marca a fatura como paga.

Parâmetros de caminho

Resposta

{
  "data": {
    "uuid": "inv-abc-123",
    "status": "paid",
    "paid_at": "2026-02-07T14:00:00Z"
  }
}

Excluir fatura

DELETE /company-invoices/{uuid}?company_slug={slug}

Exclui permanentemente uma fatura.

Parâmetros de caminho

Estatísticas de faturas

GET /company-invoices/stats?company_slug={slug}

Retorna estatísticas de faturas do workspace.

Resposta

{
  "data": {
    "total": 45,
    "draft": 3,
    "issued": 2,
    "sent": 8,
    "paid": 32,
    "total_value": 185000,
    "paid_value": 142000
  }
}

Adicionar item de linha

POST /company-invoices/{uuid}/item?company_slug={slug}

Adiciona um item de linha a uma fatura.

Parâmetros de caminho

Corpo da requisição

Listar itens de linha

GET /company-invoices/{uuid}/items?company_slug={slug}

Retorna todos os itens de linha de uma fatura.

Parâmetros de caminho

Excluir item de linha

DELETE /company-invoices/{uuid}/item/{id}?company_slug={slug}

Remove um item de linha de uma fatura.

Parâmetros de caminho

Marcar como reembolsada

POST /company-invoices/{uuid}/refunded?company_slug={slug}

Marca a fatura como reembolsada.

Parâmetros de caminho

Ciclo de vida da fatura

draft → issued → sent → paid

1. Criar — fatura começa como draft
2. Emitir — trava a fatura, altera status para issued
3. Enviar — entrega ao cliente, altera status para sent
4. Marcar como paga — registra pagamento, altera status para paid

Referência de campos