Uwata Developers

Todos os endpoints requerem o scope invoices:read e o cabeçalhoX-Company-Id.

Listar facturas

GET/api/v1/v1/invoicesListar facturas da empresa

Devolve uma lista paginada de facturas da empresa. Podes filtrar por estado, tipo e intervalo de datas.

Query parameters

Nome	Tipo	Obrig.	Descrição
`page`	`number`	não	Número da página (começa em 1).ex: `1`
`pageSize`	`number`	não	Resultados por página (máx. 100).ex: `20`
`status`	`string`	não	Filtrar por estado: DRAFT, ISSUED, PAID, CANCELLED, OVERDUE.
`type`	`string`	não	Filtrar por tipo: FT, FR, FS, NC, ND, PF.
`from`	`string`	não	Data de início (ISO 8601).ex: `2024-01-01`
`to`	`string`	não	Data de fim (ISO 8601).ex: `2024-12-31`

GET /api/v1/v1/invoices

curl "https://api.uwata.app/api/v1/v1/invoices?page=1&pageSize=20" \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Company-Id: SEU_COMPANY_ID"

Resposta

{
  "data": [
    {
      "id": "clx1234abcd",
      "number": "FT 2024/1",
      "type": "FT",
      "status": "ISSUED",
      "totalAmount": 150000,
      "currency": "AOA",
      "issuedAt": "2024-11-01T10:00:00.000Z",
      "dueDate": null,
      "customer": {
        "id": "cly5678efgh",
        "name": "Empresa ABC, Lda.",
        "nif": "5000123456"
      },
      "items": [
        {
          "description": "Consultoria TI",
          "quantity": 1,
          "unitPrice": 150000,
          "total": 150000
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

Detalhes de uma factura

GET/api/v1/v1/invoices/{id}Detalhes de uma factura

Devolve os detalhes completos de uma factura específica, incluindo os itens, cliente e estado de transmissão AGT.

Path parameters

Nome	Tipo	Obrig.	Descrição
`id`	`string`	sim	ID único da factura.ex: `clx1234abcd`

GET /api/v1/v1/invoices/{id}

curl "https://api.uwata.app/api/v1/v1/invoices/clx1234abcd" \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Company-Id: SEU_COMPANY_ID"

Tipos de documento

Valores do campo type

Nome	Tipo	Obrig.	Descrição
`FT`	`type`	não	Factura — documento fiscal principal.
`FR`	`type`	não	Factura-Recibo — factura com recibo de pagamento incluído.
`FS`	`type`	não	Factura Simplificada — para consumidores finais.
`NC`	`type`	não	Nota de Crédito — anulação parcial ou total de uma factura.
`ND`	`type`	não	Nota de Débito — cobrança adicional sobre uma factura.
`PF`	`type`	não	Proforma — orçamento/proposta sem valor fiscal.

Estados da factura

Valores do campo status

Nome	Tipo	Obrig.	Descrição
`DRAFT`	`status`	não	Rascunho — ainda não emitida.
`ISSUED`	`status`	não	Emitida — válida fiscalmente.
`PAID`	`status`	não	Paga — pagamento confirmado.
`CANCELLED`	`status`	não	Anulada — substituída por nota de crédito.
`OVERDUE`	`status`	não	Em atraso — data de vencimento ultrapassada.

Referência — Facturas